upstream

Documentation

Index

• type Event
• type EventObserver
• type Opt
• type Upstream
  • func NewUpstream(addr string, opt Opt) (Upstream, error)

Types

type Event

type Event int

const (
	EventConnOpen Event = iota
	EventConnClose
)

type EventObserver

type EventObserver interface {
	OnEvent(typ Event)
}

type Opt

type Opt struct {
	// DialAddr specifies the address the upstream will
	// actually dial to in the network layer by overwriting
	// the address inferred from upstream url.
	// It won't affect high level layers. (e.g. SNI, HTTP HOST header won't be changed).
	// Can be an IP or a domain. Port is optional.
	// Tips: If the upstream url host is a domain, specific an IP address
	// here can skip resolving ip of this domain.
	DialAddr string

	// Socks5 specifies the socks5 proxy server that the upstream
	// will connect though.
	// Not implemented for udp based protocols (aka. dns over udp, http3, quic).
	Socks5 string

	// SoMark sets the socket SO_MARK option in unix system.
	SoMark int

	// BindToDevice sets the socket SO_BINDTODEVICE option in unix system.
	BindToDevice string

	// IdleTimeout specifies the idle timeout for long-connections.
	// Available for TCP, DoT, DoH.
	// Default: TCP, DoT: 10s , DoH, DoQ: 30s.
	IdleTimeout time.Duration

	// EnablePipeline enables query pipelining support as RFC 7766 6.2.1.1 suggested.
	// Available for TCP, DoT upstream with IdleTimeout >= 0.
	// Note: There is no fallback.
	EnablePipeline bool

	// EnableHTTP3 enables HTTP/3 protocol for DoH upstream.
	// Note: There is no fallback.
	EnableHTTP3 bool

	// MaxConns limits the total number of connections, including connections
	// in the dialing states.
	// Implemented for TCP/DoT pipeline enabled upstream and DoH upstream.
	// Default is 2.
	MaxConns int

	// Bootstrap specifies a plain dns server to solve the
	// upstream server domain address.
	// It must be an IP address. Port is optional.
	Bootstrap string

	// Bootstrap version. One of 0 (default equals 4), 4, 6.
	// TODO: Support dual-stack.
	BootstrapVer int

	// TLSConfig specifies the tls.Config that the TLS client will use.
	// Available for DoT, DoH upstream.
	TLSConfig *tls.Config

	// Logger specifies the logger that the upstream will use.
	Logger *zap.Logger

	// EventObserver can observe connection events.
	// Not implemented for udp based protocols (dns over udp, http3, quic).
	EventObserver EventObserver
}

type Upstream

type Upstream interface {
	// ExchangeContext exchanges query message m to the upstream, and returns
	// response. It MUST NOT keep or modify m.
	ExchangeContext(ctx context.Context, m *dns.Msg) (*dns.Msg, error)

	io.Closer
}

Upstream represents a DNS upstream.

func NewUpstream

func NewUpstream(addr string, opt Opt) (Upstream, error)