upstream

Documentation

Index

• type Event
• type EventObserver
• type Opt
• type Upstream
  • func NewUpstream(addr string, opt Opt) (_ Upstream, err 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.
	// Default: TCP, DoT: 10s , DoH, DoH3, Quic: 30s.
	IdleTimeout time.Duration

	// EnablePipeline enables query pipelining support as RFC 7766 6.2.1.1 suggested.
	// Available for TCP, DoT upstream.
	// Note: There is no fallback. Make sure the server supports it.
	EnablePipeline bool

	// EnableHTTP3 will use HTTP/3 protocol to connect a DoH upstream. (aka DoH3).
	// Note: There is no fallback. Make sure the server supports it.
	EnableHTTP3 bool

	// 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, DoQ upstream.
	TLSConfig *tls.Config

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

	// EventObserver can observe connection events.
	// Not implemented for quic based protocol (DoH3, DoQ).
	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.
	// m MUST be a valid dns msg frame. It MUST be at least 12 bytes
	// (contain a valid dns header).
	ExchangeContext(ctx context.Context, m []byte) (*[]byte, error)

	io.Closer
}

Upstream represents a DNS upstream.

func NewUpstream

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

NewUpstream creates a upstream. addr has the format of: [protocol://]host[:port][/path]. Supported protocol: udp/tcp/tls/https/quic. Default protocol is udp.

Helper protocol:

• tcp+pipeline/tls+pipeline: Automatically set opt.EnablePipeline to true.
• h3: Automatically set opt.EnableHTTP3 to true.