proxy

type BindRetryConfig struct {
	// Interval is the minimum time to wait after the latest failure.  It must
	// not be negative if Enabled is true.
	Interval time.Duration

	// Count is the maximum number of retries after the first attempt.
	Count uint

	// Enabled indicates whether the binding should be retried.
	Enabled bool
}

type Config struct {
	// Logger is used as the base logger for the proxy service.  If nil,
	// [slog.Default] with [LogPrefix] is used.
	Logger *slog.Logger

	// TrustedProxies is the trusted list of CIDR networks to detect proxy
	// servers addresses from where the DoH requests should be handled.  The
	// value of nil makes Proxy not trust any address.
	TrustedProxies netutil.SubnetSet

	// PrivateSubnets is the set of private networks.  Client having an address
	// within this set is able to resolve PTR requests for addresses within this
	// set.
	PrivateSubnets netutil.SubnetSet

	// MessageConstructor used to build DNS messages.  If nil, the default
	// constructor will be used.
	MessageConstructor MessageConstructor

	// PendingRequests is used to mitigate the cache poisoning attacks by
	// tracking identical requests and returning the same response for them,
	// performing a single lookup.  If nil, it will be enabled by default.
	PendingRequests *PendingRequestsConfig

	// RequestContext is a context constructor that returns contexts for
	// requests.  If not set, the proxy uses [contextutil.EmptyConstructor].
	RequestContext contextutil.Constructor

	// RequestHandler is an optional custom handler for DNS requests.  It's used
	// instead of DefaultHandler if set.  In case of [ErrDrop] error returned
	// from this handler, the proxy will not send any response to the client.
	RequestHandler Handler

	// UpstreamConfig is a general set of DNS servers to forward requests to.
	UpstreamConfig *UpstreamConfig

	// PrivateRDNSUpstreamConfig is the set of upstream DNS servers for
	// resolving private IP addresses.  All the requests considered private will
	// be resolved via these upstream servers.  Such queries will finish with
	// [upstream.ErrNoUpstream] if it's empty.
	PrivateRDNSUpstreamConfig *UpstreamConfig

	// Fallbacks is a list of fallback resolvers.  Those will be used if the
	// general set fails responding.  It isn't allowed to be empty, but can be
	// nil, which means not to use fallbacks.
	//
	// TODO(e.burkov):  Add explicit boolean for disabling fallbacks.
	Fallbacks *UpstreamConfig

	// TLSConfig is the TLS configuration.  Required for DNS-over-TLS,
	// DNS-over-HTTP, and DNS-over-QUIC servers.
	TLSConfig *tls.Config

	// DNSCryptResolverCert is the DNSCrypt resolver certificate.  Required for
	// DNSCrypt server.
	DNSCryptResolverCert *dnscrypt.Cert

	// BindRetryConfig configures the listeners binding retrying.  If nil,
	// retries are disabled.
	BindRetryConfig *BindRetryConfig

	// HTTPConfig is the configuration for HTTP requests proxying.  Required for
	// DoH server.  If nil, the DoH server is disabled.
	HTTPConfig *HTTPConfig

	// DNSCryptProviderName is the DNSCrypt provider name.  Required for
	// DNSCrypt server.
	DNSCryptProviderName string

	// UpstreamMode determines the logic through which upstreams will be used.
	// If not specified the [proxy.UpstreamModeLoadBalance] is used.
	UpstreamMode UpstreamMode

	// UDPListenAddr is the set of UDP addresses to listen for plain
	// DNS-over-UDP requests.
	UDPListenAddr []*net.UDPAddr

	// TCPListenAddr is the set of TCP addresses to listen for plain
	// DNS-over-TCP requests.
	TCPListenAddr []*net.TCPAddr

	// TLSListenAddr is the set of TCP addresses to listen for DNS-over-TLS
	// requests.
	TLSListenAddr []*net.TCPAddr

	// QUICListenAddr is the set of UDP addresses to listen for DNS-over-QUIC
	// requests.
	QUICListenAddr []*net.UDPAddr

	// DNSCryptUDPListenAddr is the set of UDP addresses to listen for DNSCrypt
	// requests.
	DNSCryptUDPListenAddr []*net.UDPAddr

	// DNSCryptTCPListenAddr is the set of TCP addresses to listen for DNSCrypt
	// requests.
	DNSCryptTCPListenAddr []*net.TCPAddr

	// BogusNXDomain is the set of networks used to transform responses into
	// NXDOMAIN ones if they contain at least a single IP address within these
	// networks.  It's similar to dnsmasq's "bogus-nxdomain".
	BogusNXDomain []netip.Prefix

	// DNS64Prefs is the set of NAT64 prefixes used for DNS64 handling.  nil
	// value disables the feature.  An empty value will be interpreted as the
	// default Well-Known Prefix.
	DNS64Prefs []netip.Prefix

	// EDNSAddr is the ECS IP used in request.
	EDNSAddr net.IP

	// CacheSizeBytes is the maximum cache size in bytes.
	CacheSizeBytes int

	// CacheMinTTL is the minimum TTL for cached DNS responses in seconds.
	CacheMinTTL uint32

	// CacheMaxTTL is the maximum TTL for cached DNS responses in seconds.
	CacheMaxTTL uint32

	// CacheOptimisticAnswerTTL is the default TTL for expired cached responses.
	// Default value is [DefaultOptimisticAnswerTTL].
	CacheOptimisticAnswerTTL time.Duration

	// CacheOptimisticMaxAge is the maximum time entries remain in the cache
	// when cache is optimistic.  Default value is [DefaultOptimisticMaxAge].
	CacheOptimisticMaxAge time.Duration

	// MaxGoroutines is the maximum number of goroutines processing DNS
	// requests.  Important for mobile users.
	//
	// TODO(a.garipov): Rename this to something like “MaxDNSRequestGoroutines”
	// in a later major version, as it doesn't actually limit all goroutines.
	MaxGoroutines uint

	// The size of the read buffer on the underlying socket.  Larger read
	// buffers can handle larger bursts of requests before packets get dropped.
	UDPBufferSize int

	// FastestPingTimeout is the timeout for waiting the first successful
	// dialing when the UpstreamMode is set to [UpstreamModeFastestAddr].
	// Non-positive value will be replaced with the default one.
	FastestPingTimeout time.Duration

	// RefuseAny makes proxy refuse the requests of type ANY.
	RefuseAny bool

	// TCPProxyProtocolV2Enabled defines whether plain DNS-over-TCP listeners
	// require Proxy Protocol v2 headers.
	TCPProxyProtocolV2Enabled bool

	// TLSProxyProtocolV2Enabled defines whether DNS-over-TLS listeners require
	// Proxy Protocol v2 headers before TLS handshake.
	TLSProxyProtocolV2Enabled bool

	// ProxyProtocolV2ReadTimeout bounds the pre-DNS stage when waiting for the
	// PPv2 signature and payload from a newly accepted connection.
	//
	// Zero value means using a built-in default.
	ProxyProtocolV2ReadTimeout time.Duration

	// DNSSECEnabled specifies if the proxy should set the DO bits in the
	// upstream requests.
	DNSSECEnabled bool

	// Enable EDNS Client Subnet option DNS requests to the upstream server will
	// contain an OPT record with Client Subnet option.  If the original request
	// already has this option set, we pass it through as is.  Otherwise, we set
	// it ourselves using the client IP with subnet /24 (for IPv4) and /56 (for
	// IPv6).
	//
	// If the upstream server supports ECS, it sets subnet number in the
	// response.  This subnet number along with the client IP and other data is
	// used as a cache key.  Next time, if a client from the same subnet
	// requests this host name, we get the response from cache.  If another
	// client from a different subnet requests this host name, we pass his
	// request to the upstream server.
	//
	// If the upstream server doesn't support ECS (there's no subnet number in
	// response), this response will be cached for all clients.
	//
	// If client IP is private (i.e. not public), we don't add EDNS record into
	// a request.  And so there will be no EDNS record in response either.  We
	// store these responses in general cache (without subnet) so they will
	// never be used for clients with public IP addresses.
	EnableEDNSClientSubnet bool

	// CacheEnabled defines if the response cache should be used.
	CacheEnabled bool

	// CacheOptimistic defines if the optimistic cache mechanism should be used.
	CacheOptimistic bool

	// UseDNS64 enables DNS64 handling.  If true, proxy will translate IPv4
	// answers into IPv6 answers using first of DNS64Prefs.  Note also that PTR
	// requests for addresses within the specified networks are considered
	// private and will be forwarded as PrivateRDNSUpstreamConfig specifies.
	// Those will be responded with NXDOMAIN if UsePrivateRDNS is false.
	UseDNS64 bool

	// UsePrivateRDNS defines if the PTR requests for private IP addresses
	// should be resolved via PrivateRDNSUpstreamConfig.  Note that it requires
	// a valid PrivateRDNSUpstreamConfig with at least a single general upstream
	// server.
	UsePrivateRDNS bool

	// PreferIPv6 tells the proxy to prefer IPv6 addresses when bootstrapping
	// upstreams that use hostnames.
	PreferIPv6 bool
}

type CustomUpstreamConfig struct {
	// contains filtered or unexported fields
}

type DNSContext struct {
	// Conn is the underlying client connection.  It is nil if Proto is
	// ProtoDNSCrypt, ProtoHTTPS, or ProtoQUIC.
	Conn net.Conn

	// QUICConnection is the QUIC session from which we got the query.  For
	// ProtoQUIC only.
	QUICConnection *quic.Conn

	// QUICStream is the QUIC stream from which we got the query.  For
	// [ProtoQUIC] only.
	QUICStream *quic.Stream

	// Upstream is the upstream that resolved the request.  In case of cached
	// response it's nil.
	Upstream upstream.Upstream

	// DNSCryptResponseWriter - necessary to respond to a DNSCrypt query
	DNSCryptResponseWriter dnscrypt.ResponseWriter

	// HTTPResponseWriter - HTTP response writer (for DoH only)
	HTTPResponseWriter http.ResponseWriter

	// HTTPRequest - HTTP request (for DoH only)
	HTTPRequest *http.Request

	// ReqECS is the EDNS Client Subnet used in the request.
	ReqECS *net.IPNet

	// CustomUpstreamConfig is the upstreams configuration used only for current
	// request.  The Resolve method of Proxy uses it instead of the default
	// servers if it's not nil.
	CustomUpstreamConfig *CustomUpstreamConfig

	// Req is the request message.
	Req *dns.Msg

	// Res is the response message.
	Res *dns.Msg

	// Proto is the DNS protocol of the query.
	Proto Proto

	// RequestedPrivateRDNS is the subnet extracted from the ARPA domain of
	// request's question if it's a PTR, SOA, or NS query for a private IP
	// address.  It can be a single-address subnet as well as a zero-length one.
	RequestedPrivateRDNS netip.Prefix

	// Addr is the address of the client.
	Addr netip.AddrPort

	// DoQVersion is the DoQ protocol version. It can (and should) be read from
	// ALPN, but in the current version we also use the way DNS messages are
	// encoded as a signal.
	DoQVersion DoQVersion

	// RequestID is an opaque numerical identifier of this request that is
	// guaranteed to be unique across requests processed by a single Proxy
	// instance.
	RequestID uint64

	// IsPrivateClient is true if the client's address is considered private
	// according to the configured private subnet set.
	IsPrivateClient bool
	// contains filtered or unexported fields
}

type DefaultHandler struct{}

type DoQVersion int

type HTTPConfig struct {
	// Userinfo is the sole permitted userinfo for the DoH basic authentication.
	// If Userinfo is set, all DoH queries are required to have this basic
	// authentication information.
	Userinfo *url.Userinfo

	// ServerHeader sets the Server header of the HTTPS server responses, if not
	// empty.
	ServerHeader string

	// ListenAddresses is the set of addresses to listen for DNS-over-HTTPS
	// requests.  If it is empty the proxy doesn't start the HTTPS server, but
	// still can be used as an http.Handler with [Proxy.ServeHTTP].
	ListenAddresses []netip.AddrPort

	// Routes is the set of routes to handle.  It must be a slice of valid route
	// patterns, if it is empty, the default routes are registered.  It is
	// ignored if ListenAddresses is empty.
	Routes []string

	// ReadTimeout is the maximum duration before timing out reads of the
	// request.  A zero or negative value means there will be no timeout.  It is
	// ignored if ListenAddresses is empty.
	ReadTimeout time.Duration

	// WriteTimeout is the maximum duration before timing out writes of the
	// response.  A zero or negative value means there will be no timeout.  It
	// is ignored if ListenAddresses is empty.
	WriteTimeout time.Duration

	// HTTP3Enabled specifies if HTTP/3 support for HTTPS server.  It is ignored
	// if ListenAddresses is empty.
	HTTP3Enabled bool

	// InsecureEnabled specifies if unencrypted DoH requests are allowed.
	InsecureEnabled bool
}

type Handler interface {
	// ServeDNS resolves the DNS request within *DNSContext.
	ServeDNS(ctx context.Context, p *Proxy, dctx *DNSContext) (err error)
}

type HandlerFunc func(ctx context.Context, p *Proxy, dctx *DNSContext) (err error)

type MessageConstructor = dnsmsg.MessageConstructor

type Middleware interface {
	// Wrap returns a new handler that wraps the specified handler.
	Wrap(handler Handler) (wrapped Handler)
}

type MiddlewareFunc func(h Handler) (wrapped Handler)

type ParseError struct {

	// Idx is an index of the lines.  See [ParseUpstreamsConfig].
	Idx int
	// contains filtered or unexported fields
}

type PendingRequestsConfig struct {
	// Enabled defines if the duplicate requests should be tracked.
	Enabled bool
}

type Proto string

type Proxy struct {

	// Config is the proxy configuration.
	//
	// TODO(a.garipov): Remove this embed and create a proper initializer.
	Config

	// RWMutex protects the whole proxy.
	//
	// TODO(e.burkov):  Find out what exactly it protects and name it properly.
	// Also make it a pointer.
	sync.RWMutex
	// contains filtered or unexported fields
}

type QueryStatistics struct {
	// contains filtered or unexported fields
}

type UpstreamConfig struct {
	// DomainReservedUpstreams maps the domains to the upstreams.
	DomainReservedUpstreams map[string][]upstream.Upstream

	// SpecifiedDomainUpstreams maps the specific domain names to the upstreams.
	SpecifiedDomainUpstreams map[string][]upstream.Upstream

	// SubdomainExclusions is set of domains with subdomains exclusions.
	SubdomainExclusions *container.MapSet[string]

	// Upstreams is a list of default upstreams.
	Upstreams []upstream.Upstream
}

type UpstreamMode string

type UpstreamStatistics struct {
	// Error is the DNS lookup error, if any.
	Error error

	// Address is the address of the upstream DNS resolver.
	//
	// TODO(s.chzhen):  Use [upstream.Upstream] when [cacheItem] starts to
	// contain one.
	Address string

	// QueryDuration is the duration of the successful DNS lookup.
	QueryDuration time.Duration

	// IsCached indicates whether the response was served from a cache.
	IsCached bool
}