dns

type Allow struct {
	Prefixes []netip.Prefix
	Keys     []zone.Name
}

type Answer struct {
	// Rcode is the response code, numbered as the wire library numbers it.
	Rcode int

	// Authoritative is the AA bit. It says this server is an authority for the
	// name in the question (RFC 1035 §4.1.1): for that name, not for wherever
	// a CNAME chain happened to end.
	Authoritative bool

	// The three sections of a response. Their records belong to the snapshot
	// and are shared with every other query reading it: a caller may reorder or
	// drop them, and may never write to one.
	Answer     []wire.RR
	Authority  []wire.RR
	Additional []wire.RR

	// Extended explains a response that an RCODE alone would not (RFC 8914).
	Extended ExtendedError
}

type Config struct {
	// Addr is the address to listen on, as host:port. Empty means [defaultAddr].
	Addr string

	// Limits bound the messages the server sends. See [Limits].
	Limits Limits

	// UDPSockets is how many datagram sockets to open on Addr, each with a
	// reader of its own. Zero means one per available processor.
	UDPSockets int

	// TCPIdleTimeout is how long a connection may sit without a query before it
	// is closed. Zero means [defaultTCPIdle].
	TCPIdleTimeout time.Duration

	// MaxTCPClients is how many connections may be open at once. A connection
	// arriving when they all are is closed straight away rather than queued,
	// so that the accept loop never stalls behind a client that has stopped
	// talking. Zero means [defaultTCPClients]; a negative value means no bound
	// at all, which is a decision an operator makes on purpose.
	MaxTCPClients int

	// MaxTransfers is how many zone transfers may run at once, out of the
	// connections MaxTCPClients allows. A transfer arriving when they are all
	// in use is answered SERVFAIL and told to come back, rather than queued
	// behind one that may take minutes. Zero means [defaultTransfers]; a
	// negative value means no bound, which is a decision an operator makes on
	// purpose.
	MaxTransfers int

	// OnError is called for faults the server cannot act on itself: a socket
	// that fails to read, a connection that fails to write, a response that
	// fails to pack. Never for a merely malformed query, which is ordinary
	// traffic that an attacker could otherwise use to generate work.
	//
	// A hook rather than a logger: how the process logs is the wiring's
	// decision, not this package's. May be nil.
	OnError func(error)

	// Transfers decides who may pull a whole zone off this server. Nil allows
	// nobody, which is what an unconfigured server does.
	Transfers Transfers

	// Keys are the TSIG keys this server verifies and signs with. Empty holds
	// none, and then a signed request is refused with BADKEY.
	Keys Keyring

	// Cookies are the secrets Server Cookies are computed under. Zero means
	// none have been minted yet, and until one is published the server answers
	// a query carrying a cookie without one of its own.
	Cookies CookieSecrets

	// History supplies the record changes between two serials, which is the one
	// thing an incremental transfer needs and no snapshot holds. Nil answers
	// every incremental request with a whole zone, which RFC 1995 §2 allows.
	History History

	// Observe is called once per query, after the response has been written.
	// Both the metrics and the live query stream are fed from it; composing
	// them is the wiring's job.
	//
	// It runs on the goroutine that read the query and must not block: an
	// observer that waits stops a reader. Nil means nothing is watching, and
	// then not even the clock is read.
	Observe func(Event)
}

type CookieSecret [16]byte

type CookieSecrets struct {
	// Current is what a cookie handed out now is computed under.
	Current CookieSecret
	// Previous is the secret before it, or zero on a server that has never
	// rotated.
	Previous CookieSecret
}

type Event struct {
	// At is when the query was read, and Latency how long the exchange took
	// from that moment until the response had been written.
	At      time.Time
	Latency time.Duration

	// Client is where the query came from, and Transport how it arrived.
	Client    netip.AddrPort
	Transport Transport

	// Name, Type and Class are the question, as far as it could be read. Name
	// is empty when the message carried none; it is the name the client sent,
	// in the casing it sent, because that is what somebody watching the stream
	// is looking for.
	Name  string
	Type  zone.RRType
	Class zone.Class

	// Rcode is the response code sent, and Size the response in octets.
	Rcode int
	Size  int

	// Truncated is whether the response was cut to fit the transport and the
	// TC bit set (RFC 1035 §4.1.1).
	Truncated bool

	// Refused says the query was turned away for want of a cookie while the
	// server was under load (D35), and what the client had brought with it.
	// [NotRefused] on every other exchange, which is nearly all of them.
	Refused Refusal

	// Dropped is whether nothing was sent at all. Two messages have no safe
	// reply (architecture §2.2) and a response that cannot be packed
	// is a fault; either way the client waits for something that is not
	// coming, which is exactly what an operator is trying to find. Rcode and
	// Size mean nothing when it is set.
	Dropped bool
}

type ExtendedError struct {
	// Present tells an unset error apart from one carrying code 0, which
	// RFC 8914 §4.1 gives the meaning "Other" rather than "none".
	Present bool
	// Code is the INFO-CODE of RFC 8914 §2.
	Code uint16
	// Text is the EXTRA-TEXT: one operator-facing sentence, never a
	// machine-readable payload.
	Text string
}

type History interface {
	// Since returns the commits that took the zone from one serial to another,
	// oldest first, with the first starting at from and the last ending at to.
	//
	// The upper serial is the one the snapshot holds, not the newest the
	// journal has. The two differ for as long as a write takes to publish, and
	// a transfer that announced the newer one would have a secondary serve a
	// state this server does not.
	//
	// A range the history does not cover is false rather than an error: a full
	// transfer answers an incremental request correctly (RFC 1995 §2), so not
	// having the difference is a fallback, not a fault.
	Since(
		ctx context.Context, apex zone.Name, from, to zone.Serial,
	) ([]*journal.Commit, bool, error)
}

type Keyring map[zone.Name]TSIGKey

type Limits struct {
	// MaxUDPResponse caps a UDP response however large a buffer the requestor
	// advertises. A requestor may claim to accept 4096 octets; whether the path
	// between us carries them is not something it can know.
	MaxUDPResponse uint16
}

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

type NotifyConfig struct {
	// Targets are the secondaries told when a zone changes. Empty tells
	// nobody, which is where a server starts (docs/decisions/d27-notify.md).
	Targets []NotifyTarget

	// Keys are the TSIG keys a target may name. One it does not hold sends the
	// notification unsigned and reports it: a secondary insisting on TSIG then
	// ignores the news rather than acting on something forgeable.
	Keys Keyring

	// OnError is called for a notification that could not be sent or that was
	// never answered. Never for a write: a notification that does not arrive
	// leaves the secondary on its refresh timer, which is where it was before
	// any of this existed. May be nil.
	OnError func(error)

	// Observe is called for each step of telling one secondary. It is what
	// feeds the metrics, composed by the wiring the way the query path's is.
	// May be nil, and then nothing is counted.
	Observe func(NotifyEvent)

	// Interval and Attempts override RFC 1996's recommendation. Zero takes it.
	// Tests set them; an operator has no reason to.
	Interval time.Duration
	Attempts int
}

type NotifyEvent struct {
	Zone    zone.Name
	Target  netip.AddrPort
	Outcome NotifyOutcome
}

type NotifyOutcome string

type NotifyTarget struct {
	Addr netip.AddrPort
	// Key is the TSIG key the notification is signed with, and is the zero
	// name for one that goes out unsigned (docs/decisions/d28-tsig.md).
	Key zone.Name
}

type ProbeConfig struct {
	// Targets are the secondaries asked. It is the notify list (D27): a
	// secondary worth telling is the one worth asking, and there is no second
	// list to keep in step with the first.
	Targets []NotifyTarget

	// Snapshots reports what this server publishes, which is what "in step"
	// is measured against. A probe compares the secondary with what is being
	// answered now, not with what it was told at the time.
	Snapshots Snapshots

	// OnError is called for a query that could not be sent or built. Never for
	// a secondary that is behind: that is what the probe is for, and it
	// travels as an event rather than as a fault.
	OnError func(error)

	// Observe is called for each answered question, and is what feeds the
	// metrics. May be nil, and then nothing is counted.
	Observe func(ProbeEvent)

	// Forget is called for a pair that has stopped existing, because a target
	// left the notify list or a zone was deleted. A gauge outlives what it
	// describes unless somebody says so. May be nil.
	Forget func(zone.Name, netip.AddrPort)

	// Wait and Floor override the constants above. Tests set them; an operator
	// has no reason to.
	Wait  time.Duration
	Floor time.Duration
}

type ProbeEvent struct {
	Zone    zone.Name
	Target  netip.AddrPort
	Outcome ProbeOutcome

	// Lag is how far behind the secondary is, and is meaningful only for
	// [ProbeBehind]. D2 steps a serial once per commit, so it counts the
	// commits the secondary has yet to see rather than an opaque distance.
	Lag uint32
}

type ProbeOutcome string

type ProbeStanding struct {
	Zone   zone.Name
	Target netip.AddrPort

	// Outcome is what the last finished question found, or the empty string
	// where the pair has not been asked yet.
	Outcome ProbeOutcome

	// Serial is what the secondary last said it holds, and Known whether it
	// ever said. A secondary that has gone quiet keeps the last serial it gave
	// while its outcome says the reading is old.
	Serial zone.Serial
	Known  bool

	// Lag is how many commits behind that serial is, where the last question
	// found the secondary behind.
	Lag uint32

	// At is when the last question finished.
	At time.Time
}

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

type Question struct {
	Name  zone.Name
	Class zone.Class
	Type  zone.RRType
}

type RecordSource interface {
	IterZoneRecords(ctx context.Context, id zone.ZoneID) iter.Seq2[*zone.Record, error]
}

type Refusal uint8

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

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

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

type Snapshots interface {
	Snapshot() *Snapshot
}

type Source interface {
	RecordSource

	// IterZones streams every zone, in any order.
	IterZones(ctx context.Context) iter.Seq2[*zone.Zone, error]
}

type TSIGKey struct {
	Name      zone.Name
	Algorithm zone.TSIGAlgorithm
	Secret    []byte
}

type Transfers interface {
	// MayTransfer decides one request. key is the name the request signed with
	// and verified against, or the zero name when it carried no signature.
	MayTransfer(client netip.Addr, key, apex zone.Name) bool
}

type Transport uint8