providers

type Allower interface {
	// Allow reports whether a query may be sent, claiming a probe if the
	// provider is half-open. It is called once per attempt, immediately before
	// the attempt.
	Allow() bool
}

type BuildOptions struct {
	// Prefer lists schemes in descending preference, as in
	// {SchemeTLS, SchemeHTTPS}. Empty takes the preset's own first endpoint.
	//
	// If none of the listed schemes is published, [Build] fails with
	// [ErrNoEndpoint] rather than falling back to one that was not asked for.
	// An operator who wrote tls and was quietly given cleartext udp has lost
	// the only thing they were configuring, and no log line would say so.
	Prefer []string `json:"prefer"`

	// Name overrides the provider name. Empty uses the preset's name. It is
	// here for the deployment running the same upstream twice with different
	// settings, which would otherwise produce two identically named providers
	// and one uninterpretable metric.
	Name string `json:"name"`

	// Dialer opens connections. Nil selects a [net.Dialer].
	//
	// Setting it is how an embedder routes DNS through a VPN interface, a proxy
	// or a bootstrap resolver — which the tls:// and https:// endpoints need,
	// since their addresses are host names that themselves have to be resolved.
	Dialer transport.Dialer `json:"-"`

	// Timeout bounds one exchange. Zero selects [transport.DefaultTimeout], and
	// it never overrules an earlier deadline on the caller's context.
	Timeout time.Duration `json:"timeout"`

	// IdleTimeout is how long an unused stream connection is held. Zero selects
	// [transport.DefaultIdleTimeout]. Ignored by the datagram leg, which holds
	// nothing.
	IdleTimeout time.Duration `json:"idle_timeout"`

	// MaxConns bounds concurrent connections to the upstream. Zero selects
	// [transport.DefaultMaxConns].
	MaxConns int `json:"max_conns"`

	// Randomize enables DNS-0x20 case randomisation. Worth having on the
	// cleartext schemes, where a forged reply is a real threat, and close to
	// pointless on tls and https, where TLS has already authenticated the peer.
	Randomize bool `json:"randomize"`

	// UDPSize is the EDNS payload size advertised on udp:// endpoints. Zero
	// selects [transport.DefaultUDPSize].
	UDPSize uint16 `json:"udp_size"`

	// TLS configures tls:// and https:// endpoints. Nil takes the platform
	// roots with a TLS 1.2 floor, which is what a public resolver expects.
	TLS *tls.Config `json:"-"`

	// PinnedSPKI overrides [Preset.PinnedSPKI]. It applies to tls:// endpoints
	// only, and is silently unused on the others, because a preset that pins
	// its DoT endpoint is still allowed to publish a udp:// one.
	PinnedSPKI []string `json:"pinned_spki,omitempty"`

	// Health configures the circuit breaker on the resulting provider. The zero
	// value selects the documented defaults; set its Clock in tests.
	Health HealthOptions `json:"health"`
}

type Concurrent interface {
	Strategy

	// Concurrency reports how many of the selected providers to query at once.
	// One means sequential failover, which is what a strategy that does not
	// implement this interface is assumed to want.
	Concurrency() int
}

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

type GroupOptions struct {
	// Name identifies the group in metrics, logs and in any group that contains
	// it. Required, for the same reason a provider's name is.
	Name string `json:"name"`

	// Providers are the upstreams, in preference order. At least one is
	// required. The group does not copy the providers themselves — they are
	// live objects with health records that outlive any one query — but it does
	// copy the slice, so the caller may reuse it.
	Providers []Provider `json:"-"`

	// Strategy chooses between them. Nil selects [Sequential], which reads the
	// list as what it looks like: a preference order.
	Strategy Strategy `json:"-"`

	// Clock is the time source used to measure attempts. Nil selects
	// [clock.System].
	Clock clock.Clock `json:"-"`

	// Metrics records per-attempt upstream timings. Nil selects [metrics.Nop].
	Metrics metrics.Recorder `json:"-"`

	// Events publishes upstream failures and recoveries. Nil publishes nothing,
	// and so does a bus with no subscriber: the group asks before it builds an
	// event, because converting one to an interface allocates whether or not
	// anybody is listening.
	Events *events.Bus `json:"-"`

	// Logger receives failover decisions at debug level and total failures at
	// warn. Nil selects [logging.Discard].
	Logger *slog.Logger `json:"-"`

	// MaxAttempts bounds how many upstreams one query may be sent to. Zero
	// means the number of providers, which is the natural reading of "try them
	// all".
	//
	// It exists because failover multiplies latency as well as reliability: a
	// group of six providers with a two-second timeout each can spend twelve
	// seconds on a query whose client gave up after five. Setting this to two
	// says that if the first two upstreams cannot answer, the sixth almost
	// certainly cannot either, and the client would rather have SERVFAIL now.
	MaxAttempts int `json:"max_attempts"`
}

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

type HealthOptions struct {
	// FailureThreshold is the number of CONSECUTIVE failures that trip the
	// breaker. Consecutive rather than a rate: a provider answering four
	// queries in five is degraded but useful, and taking it out of service
	// would move that load onto its neighbours.
	FailureThreshold int `json:"failure_threshold"`

	// Cooldown is the first interval a tripped provider is passed over for.
	Cooldown time.Duration `json:"cooldown"`

	// MaxCooldown caps the exponential growth of Cooldown across repeated
	// failed probes.
	MaxCooldown time.Duration `json:"max_cooldown"`

	// Clock is the time source. Nil selects [clock.System].
	Clock clock.Clock `json:"-"`
}

type HealthState struct {
	State State `json:"state"`
	// ConsecutiveFailures is the current run of failures; it resets on any
	// success.
	ConsecutiveFailures int `json:"consecutive_failures"`
	// Successes and Failures are lifetime totals, for metrics.
	Successes uint64 `json:"successes"`
	Failures  uint64 `json:"failures"`
	// OpenedAt is when the breaker last tripped, zero if it never has.
	OpenedAt time.Time `json:"opened_at,omitzero"`
	// RetryAt is when the next probe becomes permitted, meaningful only while
	// the state is open.
	RetryAt time.Time `json:"retry_at,omitzero"`
	// Cooldown is the interval currently in force, which grows with repeated
	// failed probes.
	Cooldown time.Duration `json:"cooldown"`
}

type Options struct {
	// Name identifies the provider. Required: an unnamed upstream cannot be
	// reported on, and a group of them cannot be debugged.
	Name string `json:"name"`

	// Exchanger carries the queries. Required.
	Exchanger transport.Exchanger `json:"-"`

	// Health configures the circuit breaker. The zero value selects the
	// documented defaults.
	Health HealthOptions `json:"health"`
}

type Outcome uint8

type Preset struct {
	// Name is how an operator refers to this upstream in configuration, and
	// becomes the [Provider] name in metrics and logs. It is matched
	// case-insensitively; write it lower case.
	Name string `json:"name"`

	// Description is one line an operator sees in a list of choices.
	Description string `json:"description"`

	// Endpoints are the operator's published addresses in the preset author's
	// preference order, each prefixed with the scheme that selects a transport:
	// udp://, tcp://, tls:// or https://. See [ParseEndpoint].
	//
	// Several addresses of the same scheme are the redundancy the operator
	// publishes — usually a primary, a secondary and their IPv6 equivalents.
	// [Build] uses one of them; building a [Provider] per address and grouping
	// them is what uses them all, and is the caller's decision because it
	// doubles the query volume seen by that one operator.
	Endpoints []string `json:"endpoints"`

	// PinnedSPKI are base64 SHA-256 SPKI digests for the tls:// endpoints,
	// carried through to [transport.StreamOptions.PinnedSPKI].
	//
	// It is empty for every preset shipped here, and that is a deliberate
	// finding rather than an oversight: none of these operators publishes a
	// long-lived pin, and a pin baked into a released library outlives the
	// certificate it was taken from. When it expires, every query to that
	// upstream fails at the handshake — a total outage caused by the library
	// rather than by the operator. Pin an upstream you control, from a value
	// you can update as fast as it rotates.
	PinnedSPKI []string `json:"pinned_spki,omitempty"`

	// Notes are what an operator should read before choosing this upstream:
	// filtering behaviour, stated logging policy, jurisdiction. Factual, and
	// not a recommendation — see the type documentation.
	Notes string `json:"notes"`
}

type Provider interface {
	transport.Exchanger

	// Name identifies the provider in metrics, logs and configuration. It is
	// stable for the life of the provider and is what an operator sees.
	Name() string

	// Health reports the provider's current standing. The result is a snapshot;
	// reading it does not block a query in flight.
	Health() HealthState
}

type ProviderError struct {
	// Provider is the name of the upstream that failed.
	Provider string
	// Err is what went wrong, unwrappable so that errors.Is on a transport
	// sentinel still works through the join.
	Err error
}

type RCodeError struct {
	// Provider names the upstream that returned the code.
	Provider string
	// RCode is the response code received.
	RCode dnsmsg.RCode
}

type RandSource interface {
	// IntN returns a uniformly distributed value in [0,n) and panics for n
	// less than one, matching [math/rand/v2.IntN].
	IntN(n int) int
}

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

type SelectAppender interface {
	Strategy

	// SelectAppend appends the selected providers to dst and returns the
	// result. dst may be nil.
	SelectAppend(dst []Provider, ps []Provider) []Provider
}

type State uint8

type Strategy interface {
	// Select returns the providers to try, in order. It must not block and
	// must not mutate the input slice.
	//
	// The result is filtered to providers that are currently worth asking,
	// judged by [HealthState.Available]. It may legitimately be empty — every
	// upstream tripped is a state a group must handle, and a strategy that
	// invented a provider to avoid returning nothing would be hiding the
	// outage from the one component able to make a judgement about it.
	Select(ps []Provider) []Provider

	// Name identifies the policy in logs, metrics and configuration. It is
	// what an operator reads when asking why a particular upstream was chosen.
	Name() string
}

type StrategyValidator interface {
	Strategy

	// Validate reports every problem with using this strategy over ps.
	Validate(ps []Provider) error
}