dns

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

	// 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)

	// 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 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

	// 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 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 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 Responder struct {
	// contains filtered or unexported fields
}

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

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

type Source interface {
	RecordSource

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

type Transport uint8