resolver

type Client struct {
	// Addr is the client's address and port, as the server observed it. It is
	// the one piece of identity that cannot be forged by the query itself.
	//
	// It is [netip.AddrPort] rather than a string because everything that reads
	// it compares or classifies an address — is this client on the local link,
	// which device is at this address, is this a source that may ask us at all
	// — and every one of those from a "192.168.4.20:53214" string means parsing
	// it again on a path that runs tens of thousands of times a second, with a
	// parse failure nobody has a sensible answer for.
	Addr netip.AddrPort
	// ID is a stable identifier for the device, assigned by whatever above us
	// knows about devices. Empty when nothing does.
	ID string
	// Transport names how the query reached us: "udp", "tcp", "tls", "https".
	Transport string
}

type Handler interface {
	Resolve(ctx context.Context, q *dnsmsg.Message, c Client) (*dnsmsg.Message, Result, error)
}

type HandlerFunc func(ctx context.Context, q *dnsmsg.Message, c Client) (*dnsmsg.Message, Result, error)

type Middleware func(Handler) Handler

type Options struct {
	// Upstream is where queries go on a cache miss. Required.
	//
	// It is a [transport.Exchanger] rather than a provider group so that a
	// caller may supply either, or something of its own: the resolver's needs
	// end at "send this and give me the reply".
	Upstream transport.Exchanger `json:"-"`

	// Cache holds answers. Nil disables caching entirely, which is a supported
	// configuration for a resolver sitting in front of another one.
	Cache *cache.Cache `json:"-"`

	// Middleware wraps resolution, outermost first.
	Middleware []Middleware `json:"-"`

	// Identify assigns a device identity to a client, before the middleware
	// chain and before anything is recorded. Nil leaves [Client.ID] as the
	// server set it, which is empty.
	//
	// It is a hook rather than a middleware because the chain takes Client by
	// value: a middleware that set an ID would inform every handler downstream
	// of it and nothing upstream, including the metrics and the query log —
	// so a device table wired in as middleware would filter correctly and
	// report every query as coming from nobody.
	//
	// It runs once per query on the query path, so it must be fast and must not
	// block. A panic in it is contained: an unknown device is a far smaller
	// loss than no DNS.
	Identify func(Client) Client `json:"-"`

	// Timeout bounds one resolution when the caller's context has no earlier
	// deadline. Zero selects [DefaultTimeout].
	Timeout time.Duration `json:"timeout"`

	// StripECS removes any EDNS Client Subnet option from an outbound query.
	//
	// It defaults to ON, and that is a privacy decision taken deliberately:
	// forwarding ECS discloses the client's network to every upstream on every
	// query, which is precisely the disclosure a private resolver exists to
	// prevent. An operator who wants the geo-accuracy it buys can turn it off.
	StripECS *bool `json:"strip_ecs,omitempty"`

	Clock   clock.Clock      `json:"-"`
	Metrics metrics.Recorder `json:"-"`
	Events  *events.Bus      `json:"-"`
	Logger  *slog.Logger     `json:"-"`
}

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

type Result struct {
	Source Source
	// Shared reports that this answer came from an upstream query another
	// caller had already started. It is what makes deduplication visible in a
	// log rather than only in an upstream's bandwidth bill.
	Shared bool
	// Upstream names the provider that answered, empty when nothing was asked.
	Upstream string
	// Blocked reports that a middleware answered from policy rather than from
	// DNS data, and Rule names the rule that matched. They travel here rather
	// than being inferred from Source, because SourceLocal covers every
	// locally synthesised answer — a local zone and a block look identical
	// from outside, and a query log that guessed would mislabel both.
	Blocked bool
	Rule    string
	// Duration is the whole resolution, including any wait for a shared query.
	Duration time.Duration
}

type Source uint8