net

type AddressValue struct {
	// Network is the socket family: tcp, tcp4, tcp6, udp, udp4, udp6, unix,
	// unixgram or unixpacket.
	Network string `json:"network"`
	// Addr is the bind target: "host:port" for the IP families, a filesystem
	// path for the unix families.
	Addr string `json:"addr"`
}

type CallHook func(call CallValue)

type CallValue struct {
	// Method is the uppercase HTTP method.
	Method string
	// Host is the authority the call was sent to.
	Host string
	// Path is the request path.
	Path string
	// Status is the HTTP status code, or zero when the call produced no response.
	Status int
	// Bytes is the number of response body bytes read.
	Bytes int64
	// Duration is the wall-clock time from request start to response headers.
	// It deliberately excludes the body: the record is emitted once the body is
	// done with, but this field measures the upstream's time to first answer,
	// which is the one a slow upstream and a large payload do not share.
	Duration time.Duration
	// Err is what ended the call: a policy refusal, a transport failure, the
	// response ceiling, or a failed close. Nil when the body was read in full.
	Err error
}

type Capability string

type CapabilityValue struct {
	// Name is the capability.
	Name Capability `json:"name"`
	// Class is "a-kernel", "a-code" or "b".
	Class string `json:"class"`
	// Status is "on" (probed and in use), "available" (probed, not asked for),
	// "absent" (probed, the kernel lacks it), "missing" (a class A-code
	// capability the code opted into and the kernel lacks: a fault),
	// "disabled" (switched off by KITSUNIUM_NET_DISABLE or an unknown token,
	// never probed) or "unprobed" (the backend the group runs on has no use for
	// it).
	Status string `json:"status"`
	// Reason names the probe stage and the kernel's answer, or the switch.
	Reason string `json:"reason,omitempty"`
}

type ClientConfig struct {
	// BaseURL is the origin every relative path resolves against.
	BaseURL string `json:"base_url"`
	// DialTimeout bounds establishing the TCP connection.
	DialTimeout DurationValue `json:"dial_timeout"`
	// HandshakeTimeout bounds the TLS handshake.
	HandshakeTimeout DurationValue `json:"handshake_timeout"`
	// ResponseTimeout bounds the wait for response headers after the request
	// has been written. It is separate from TotalTimeout so a slow upstream is
	// distinguishable from a large body.
	ResponseTimeout DurationValue `json:"response_timeout"`
	// TotalTimeout bounds the whole call, body included.
	TotalTimeout DurationValue `json:"total_timeout"`
	// MaxResponseSize caps the response body in bytes. A body of exactly this
	// size is admitted; only one past it fails the call, and the body is never
	// truncated.
	MaxResponseSize int64 `json:"max_response_size"`
	// MaxRedirects caps the redirect chain. Every hop is re-authorised by the
	// policy, and a hop to another origin is refused unless RedirectOrigins
	// names it, so a redirect cannot walk out of the allowed surface.
	MaxRedirects int `json:"max_redirects"`
	// RedirectOrigins names the origins, each written scheme://host[:port], a
	// redirect may lead to besides the origin of the request that started the
	// chain. Empty — the default — refuses with RequestDenied every redirect
	// that changes the scheme, the host or the port, https to http included:
	// the built-in policies judge the method and the path, so a hop that keeps
	// the path and swaps the origin would otherwise pass them. A listed origin
	// is followed, and receives none of the DefaultHeaders. An entry that is
	// not a bare http or https origin fails New with InvalidAddress.
	RedirectOrigins []string `json:"redirect_origins"`
	// DefaultHeaders are added to every request that does not already set them
	// and is sent to the origin of BaseURL — or, with no BaseURL, to whatever
	// origin the request names. They are never sent to another origin: a
	// request built for one does not receive them, and a redirect that leaves
	// the origin of the request that started the chain is sent without them.
	DefaultHeaders map[string]string `json:"default_headers"`
}

type Conn interface {
	stdnet.Conn
	// ID returns the monotonic identifier assigned at accept time, for
	// correlating log lines belonging to one connection.
	ID() uint64
	// Group returns the name of the listener group that accepted this
	// connection, so one handler serving several groups can tell them apart.
	Group() string
	// Buffer returns a connection-scoped scratch buffer sized by the group's
	// read-buffer limit. It is recycled with the connection, which is what lets
	// a handler read without allocating per connection.
	Buffer() []byte
}

type ConnHandler interface {
	ServeConn(ctx context.Context, c Conn) error
}

type ConnHandlerFunc func(ctx context.Context, c Conn) error

type DatagramStateValue struct {
	// TruncatedPackets is the number of messages dropped because the kernel cut
	// them: a coalesced message past its buffer (MSG_TRUNC under UDP GRO), or a
	// message whose control data did not fit (MSG_CTRUNC). Neither can be split
	// into whole datagrams, so none of what survives is delivered.
	TruncatedPackets uint64 `json:"truncated_packets"`
	// GSOOversized is the number of GSO sends the kernel refused with EMSGSIZE:
	// a sizing bug, counted, which leaves GSO on.
	GSOOversized uint64 `json:"gso_oversized"`
	// ReplyFailures is the number of replies a BatchReplies group queued during
	// a batch that did not leave: Reply had already reported them sent.
	ReplyFailures uint64 `json:"reply_failures"`
}

type DurationValue time.Duration

type EngineValue uint8

type FallbacksValue struct {
	// Count is the number of fallbacks since the server was built.
	Count uint64 `json:"count"`
	// LastGroup names the group of the last fallback.
	LastGroup string `json:"last_group,omitempty"`
	// LastReason is the last fallback's reason.
	LastReason string `json:"last_reason,omitempty"`
	// LastAt is when the last fallback happened; zero when none did.
	LastAt time.Time `json:"last_at"`
}

type FaultValue struct {
	// Source says what reported it: "listener", "loop", "ring", "stall",
	// "capability", "gso" or "environment".
	Source string `json:"source"`
	// Group names the group concerned; empty for the environment.
	Group string `json:"group,omitempty"`
	// Reason names the fault and, where one exists, the runbook's switch.
	Reason string `json:"reason"`
}

type HTTP1AccessLogger interface {
	// LogHTTP1 receives one request's record.
	LogHTTP1(rec HTTP1AccessValue)
}

type HTTP1AccessValue struct {
	// Lane is the request's lane.
	Lane int
	// Route is the route a router link matched, zero for none.
	Route int
	// Method is the request method.
	Method []byte
	// Path is the request's canonical path, without its query.
	Path []byte
	// Status is the answer's status code, 200 when the handler left it zero;
	// zero for an answer still deferred.
	Status int
	// BodyLen is the length of the answer's body.
	BodyLen int
	// Authenticated reports whether an authenticating link verified the request.
	Authenticated bool
	// Deferred reports whether the answer was deferred to the batch's end.
	Deferred bool
	// NFields is how many entries of Fields the record filled.
	NFields int
	// Fields holds the allowed request fields the request carried, in the order
	// the link was given their names.
	Fields [HTTP1MaxAccessFields]HTTP1FieldValue
}

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

type HTTP1Batcher interface {
	// EndBatch ends the batch of the lane whose index is lane: the Lane every
	// request of the batch carried.
	EndBatch(lane int)
}

type HTTP1BearerVerifier interface {
	// VerifyBearer reports whether token, the credentials after "Bearer ", is
	// valid, and fills auth when it is.
	VerifyBearer(token []byte, auth *HTTP1AuthValue) bool
}

type HTTP1FieldValue struct {
	// Name is the field name, validated as an RFC 9110 token.
	Name []byte
	// Value is the field value, without its leading and trailing spaces and
	// tabs; it holds no NUL, CR, LF or other control byte but the tab.
	Value []byte
}

type HTTP1Handler interface {
	ServeHTTP1(req *HTTP1RequestValue, res *HTTP1ResponseValue)
}

type HTTP1HandlerFunc func(req *HTTP1RequestValue, res *HTTP1ResponseValue)

type HTTP1LimitsValue struct {
	// Head bounds the request line, the field lines and the blank line that
	// ends them, in bytes: zero selects HTTP1DefaultHead, at most HTTP1MaxHead.
	Head int `json:"head"`
	// Target bounds the request-target, in bytes: zero selects
	// HTTP1DefaultTarget, and it may not exceed Head.
	Target int `json:"target"`
	// Body bounds the Content-Length a request may declare: zero selects
	// HTTP1DefaultBody, at most HTTP1MaxBody.
	Body int64 `json:"body"`
}

type HTTP1RequestValue struct {
	// Method is the request method, a token.
	Method []byte
	// Target is the request-target exactly as sent, still percent-encoded.
	Target []byte
	// Host is the Host field's value; HasHost says whether it was present.
	Host []byte
	// Authorization is the Authorization field's value; HasAuthorization says
	// whether it was present.
	Authorization []byte
	// Body is the request content, Content-Length bytes after the head. It is
	// empty until the whole body has arrived.
	Body []byte
	// ContentLength is the declared body length, zero when the field is absent.
	ContentLength int64
	// HeadLen is the length of the head: the request line, the field lines and
	// the blank line. It is zero until the head is complete.
	HeadLen int
	// Consumed is HeadLen plus ContentLength: the bytes this request takes from
	// the stream, whatever its method or route. The next pipelined request
	// starts there. It is set as soon as the head is complete, before the body
	// arrives, so an early answer knows how much it has to drain.
	Consumed int
	// NFields is how many entries of Fields the request filled.
	NFields int
	// Fields holds the request's field lines in the order they arrived,
	// Host, Authorization and Content-Length included.
	Fields [HTTP1MaxFields]HTTP1FieldValue
	// HasHost reports whether the request carried a Host field.
	HasHost bool
	// HasAuthorization reports whether the request carried an Authorization
	// field.
	HasAuthorization bool
	// Close reports whether the client asked to close the connection after
	// this request: a Connection field holding the close token.
	Close bool
	// Lane is the index of the lane that framed the request, from 0 to the
	// group's lane count less one — its LoopIO.Loop — set by the loop adapter
	// before the handler runs. One lane is one thread or one goroutine, so a
	// handler finds its per-lane state in a slice sized at LoopStarter.OnStart,
	// with no lock. Parse leaves it as it is; outside the loop adapter it is
	// what the caller set.
	Lane int
	// Path is the request's canonical path, the one target every link of a
	// chain routes and judges on, computed once by the codec: the target's
	// path up to its query, an absolute-form target reduced to its path once
	// its authority matched Host. It is still percent-encoded, and holds no
	// dot-segment, no empty segment, no backslash and no encoded slash, dot,
	// backslash or NUL: the codec refuses a target that would (400). An
	// asterisk-form target, OPTIONS only, is "*".
	Path []byte
	// Query is the target's query, after its "?" and without it; empty when
	// the target has none.
	Query []byte
	// Route is the identifier of the route a router link matched, zero for
	// none. Parse resets it to zero; only a link sets it.
	Route int
	// Auth is what an authenticating link established: the subject and the
	// claims, copied by value into the request, so nothing of them aliases
	// bytes the connection reuses. Parse resets it; Authenticated says
	// whether a link set it.
	Auth HTTP1AuthValue
	// Authenticated reports whether an authenticating link verified the
	// request's credentials and filled Auth. Parse resets it to false.
	Authenticated bool
}

type HTTP1ResponseValue struct {
	// Status is the status code, 200 to 999; zero means 200. The profile
	// sends no interim response.
	Status int
	// Header holds the response's extra field lines, each written as
	// "Name: value\r\n" by the codec's writer. It never holds Content-Length or
	// Connection, which the codec writes.
	Header []byte
	// Body is the response content.
	Body []byte
	// Close asks the codec to close the connection after this response.
	Close bool
	// Defer, set by the handler, holds the answer back until the end of the
	// loop's batch, for work it batches — one database transaction for every
	// request of the batch, say. The response value then stays valid, at the
	// same address, until HTTP1Batcher.EndBatch returns, and the handler
	// completes it there: it fills it and clears Defer. An answer still
	// deferred when EndBatch returns is answered 500 and its connection
	// closed. Only the loop adapter reads it; AppendResponse does not.
	Defer bool
	// Pending, set by the handler, hands the answer to the lane's worker
	// (HTTP1Worker, R3): the loop adapter sends Job to it and writes the
	// answer the worker fills, from the loop's thread, once it comes back.
	// Answers after it on the same connection wait for it, in order. A queue
	// to the worker that is full answers 503 with Retry-After at once, the
	// connection kept; a connection that closes first drops the answer. Pending
	// with Defer, or with no worker, is answered 500 and the connection closed.
	// Only the loop adapter reads it.
	Pending bool
	// Job is the integer a pending answer's worker is given: the handler's own
	// index of what the work needs, which it copied out of the request, since
	// the request's bytes do not outlive the batch.
	Job uint64
}

type HTTP1Worker interface {
	// WorkHTTP1 fills res, the answer to the pending request of lane whose Job
	// was job.
	WorkHTTP1(lane int, job uint64, res *HTTP1ResponseValue)
}

type IdentityFileParams struct {
	// CertFile is the PEM leaf certificate followed by any intermediates.
	// Supplying it without KeyFile is always a configuration slip, never an
	// intention, and is refused: an mTLS client that silently degrades to plain
	// TLS is a security hole that reports nothing.
	CertFile string `json:"cert_file"`
	// KeyFile is the PEM private key matching CertFile.
	KeyFile string `json:"key_file"`
	// RootsFile is the PEM CA bundle used to verify the peer. Leaving it empty
	// selects the platform trust store, which is right for a public endpoint and
	// wrong for a private PKI.
	RootsFile string `json:"roots_file"`
	// ClientCAFile is the PEM CA bundle a server accepts client certificates
	// from. Required whenever RequireClientCert is set.
	ClientCAFile string `json:"client_ca_file"`
	// ServerName overrides the name verified against the peer certificate.
	//
	// This is far more often required than its "optional" typing suggests. Any
	// deployment reached through a port forward or a tunnel connects to
	// 127.0.0.1 while the peer certificate names the real service, and the
	// handshake then fails every single time until ServerName is set. Treat it
	// as mandatory whenever the dial address is not the certificate's name.
	ServerName string `json:"server_name"`
	// MinVersion is the lowest accepted TLS version. Zero selects TLS 1.3;
	// anything below TLS 1.2 is refused.
	MinVersion uint16 `json:"min_version"`
	// NextProtos is the ALPN protocol list, e.g. {"h2", "http/1.1"}.
	NextProtos []string `json:"next_protos"`
	// RequireClientCert turns a server identity into mutual TLS.
	RequireClientCert bool `json:"require_client_cert"`
}

type IdentityParams struct {
	// CertPEM is the PEM-encoded leaf certificate followed by any intermediates.
	// Paired with KeyPEM; supplying one without the other is an error.
	CertPEM []byte
	// KeyPEM is the PEM-encoded private key matching CertPEM.
	KeyPEM []byte
	// RootsPEM is the PEM-encoded CA bundle used to verify the peer. When empty
	// the platform trust store is used, which is the right default for a public
	// endpoint and the wrong one for a private PKI.
	RootsPEM []byte
	// ClientCAPEM is the PEM-encoded CA bundle a server accepts client
	// certificates from. It is meaningless on a client identity.
	ClientCAPEM []byte
	// ServerName overrides the name verified against the peer certificate. It is
	// required when connecting to a host by IP whose certificate names a DNS name.
	ServerName string
	// MinVersion is the lowest accepted TLS version. Zero selects TLS 1.3;
	// anything below TLS 1.2 is refused outright.
	MinVersion uint16
	// NextProtos is the ALPN protocol list, e.g. {"h2", "http/1.1"}.
	NextProtos []string
	// RequireClientCert turns a server identity into mutual TLS: the peer must
	// present a certificate that chains to ClientCAPEM.
	RequireClientCert bool
}

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

type LimitsValue struct {
	// MaxConns caps concurrent connections in the group. Beyond it, a new
	// connection is accepted and immediately closed with ConnLimitReached, which
	// is kinder than letting the accept queue silently overflow.
	MaxConns int `json:"max_conns"`
	// ReadBufferSize sizes the per-connection scratch buffer returned by
	// Conn.Buffer.
	ReadBufferSize int `json:"read_buffer_size"`
	// MaxPacketSize is the largest datagram accepted. A larger one is DROPPED
	// and counted in StateValue.OversizedPackets, never delivered truncated:
	// the kernel discards the tail, so the prefix that survives reads exactly
	// like a complete message and the handler cannot tell the difference.
	MaxPacketSize int `json:"max_packet_size"`
	// Backlog is the listen backlog depth where the platform honours it.
	Backlog int `json:"backlog"`
	// Shards is the number of independent listeners to open on one address with
	// SO_REUSEPORT, each with its own accept loop, to remove accept contention.
	// Zero selects the platform default.
	Shards int `json:"shards"`
	// BatchSize is how many datagrams to read per syscall. Zero selects the
	// default; one disables batching.
	BatchSize int `json:"batch_size"`
}

type ListenerStateValue struct {
	// Group is the listener group's name.
	Group string `json:"group"`
	// Address is the address actually bound, which for a port of zero is the
	// one the kernel chose rather than the one requested.
	Address string `json:"address"`
	// Network is the socket family.
	Network string `json:"network"`
	// Shards is how many listeners were actually opened on this address.
	Shards int `json:"shards"`
	// Degraded reports that a requested optimisation was unavailable and the
	// server fell back. It is surfaced rather than logged once at startup,
	// because a silent fallback is indistinguishable from a working one and
	// nobody re-reads yesterday's logs to find out.
	Degraded bool `json:"degraded"`
	// DegradedReason names the fallback in plain words when Degraded is set.
	DegradedReason string `json:"degraded_reason,omitempty"`
	// Adopted reports a listener inherited from a supervisor rather than bound
	// by this process.
	Adopted bool `json:"adopted"`
	// Exclusive reports that no other socket can bind the listener's address
	// while it lives: SO_EXCLUSIVEADDRUSE on Windows, set on a unicast TCP or
	// UDP socket this process binds and read back, never set, on an adopted
	// one. It is false on every other platform, which has no such option.
	Exclusive bool `json:"exclusive"`
	// BindWait is how long the bind waited for its address to come free: on
	// Windows, a restarted server's address stays taken until the previous
	// process's connections end, and the bind is retried, bounded. Zero when
	// the first attempt bound.
	BindWait DurationValue `json:"bind_wait"`
}

type LoopBackend uint8

type LoopConnRef struct {
	// Ring is the ring, inside its loop, that holds the connection.
	Ring uint32
	// Slot is the connection's index in the ring's table.
	Slot uint32
	// Gen is the slot's generation. It is never zero for a live connection, so
	// the zero LoopConnRef is stale on every loop.
	Gen uint32
}

type LoopHandler interface {
	// OnOpen is called once per accepted connection, before any OnData for it.
	// Pressure(ref) already answers for this connection.
	OnOpen(io LoopIO, ref LoopConnRef)
	// OnData hands the handler the bytes received on ref and returns how many of
	// them it consumed, from 0 to len(buf). buf stays valid until the next
	// OnBatchEnd returns, never later, and the handler must not write to it.
	// The unconsumed tail is kept in the connection's spill and handed back
	// first, followed by the next bytes, on the next OnData; a tail past the
	// spill ceiling closes the connection with LoopSpillFull. A value outside
	// 0 to len(buf) is treated as len(buf).
	OnData(io LoopIO, ref LoopConnRef, buf []byte) int
	// OnTimeout is called when the deadline set by SetDeadline on ref expires.
	// The connection stays open: closing it is the handler's choice.
	OnTimeout(io LoopIO, ref LoopConnRef)
	// OnWritable is called when ref's pending output falls below the loop's
	// low-water mark after a Write was refused with LoopOutputFull or left output
	// pending past the mark, so a producer that paused can resume.
	OnWritable(io LoopIO, ref LoopConnRef)
	// OnBatchEnd is called once per loop iteration, after the OnData calls of
	// every ring of the loop, and before any buffer handed to them returns to the
	// kernel. It is where a handler flushes work it batched — one database
	// commit for every request of the batch, say — before writing the answers.
	OnBatchEnd(io LoopIO)
	// OnClose is called once per connection, last. err is nil when the peer
	// closed cleanly or the handler called Close, and otherwise names why the
	// loop closed it — LoopSpillFull, an idle timeout, the drain, a socket
	// error. ref is stale once OnClose returns.
	OnClose(io LoopIO, ref LoopConnRef, err error)
}

type LoopIO interface {
	// Write copies p into ref's output and returns. Writes on one reference leave
	// in the order they were made, and p may be reused once Write returns. It is
	// refused with LoopOutputFull, copying nothing, when p would pass the
	// connection's output ceiling or the loop's global output budget, and with
	// LoopStaleRef when ref's connection has closed.
	Write(ref LoopConnRef, p []byte) error
	// Close closes ref's connection once the output already written has left,
	// and calls OnClose. A second Close, or a Close on a stale reference, returns
	// LoopStaleRef and does nothing.
	Close(ref LoopConnRef) error
	// SetDeadline arms ref's timer to fire OnTimeout after d, on the loop's
	// coarse timer wheel: it fires no earlier than d and at most one wheel tick
	// late. A d of zero or less disarms it. Arming again replaces the previous
	// deadline.
	SetDeadline(ref LoopConnRef, d time.Duration) error
	// Pressure reports whether ref's connection was accepted, or has since come,
	// under the loop's soft pressure: the group serves more connections than its
	// soft bound. It is a primitive; what a protocol makes of it — HTTP/1.1
	// answers Connection: close — is the protocol adapter's. A stale reference
	// reports false.
	Pressure(ref LoopConnRef) bool
	// Post queues op to run once on the loop's thread with arg, and wakes the
	// loop. It is the one operation any goroutine may call. The queue is
	// preallocated and holds no closure: op is a plain function and arg an
	// integer the caller gives meaning to. Each posted operation runs exactly
	// once, in the order posted; a full queue refuses with LoopPostQueueFull, and
	// a loop that has stopped with ServerClosed.
	Post(op PostFunc, arg uintptr) error
	// Loop returns the index of the loop this LoopIO belongs to, from 0 to the
	// group's lane count less one, fixed for the loop's life: its lane. A
	// handler keeps its per-lane state — a scratch, a batch, a buffer — in a
	// slice indexed by it and sized at LoopStarter.OnStart, so a callback finds
	// its own with no lock and no map. The portable backend runs LoopValue.Loops
	// lanes too, one handler goroutine each. Any goroutine may call it.
	Loop() int
}

type LoopJobValue struct {
	// Ref is the connection the job answers.
	Ref LoopConnRef
	// Slot is the sender's index of the job's state.
	Slot uint32
	// Gen is the generation of that slot when the job was sent.
	Gen uint32
	// Arg is the sender's own argument.
	Arg uint64
}

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

type LoopLayered interface {
	// Next returns the handler the layer wraps.
	Next() LoopHandler
}

type LoopOffloader interface {
	// Worker returns the worker the group's lanes offload to; nil offloads
	// nothing.
	Worker() LoopWorker
	// OnOutbound gives the offloader its lanes' outbounds, once.
	OnOutbound(v LoopOutboundValue)
	// OnDone is called on the lane's thread with each job its worker ran.
	OnDone(io LoopIO, job LoopJobValue)
	// Pending reports, on the lane's thread, whether ref, a connection of lane,
	// waits for an answer its worker has not given back: a draining loop keeps
	// it open until it has, and eviction passes it by.
	Pending(lane int, ref LoopConnRef) bool
}

type LoopOptionHonourer interface {
	// Honours reports whether the handler applies the option of kind k itself.
	Honours(k OptionKind) bool
}

type LoopOutbound interface {
	// Send queues job for the lane's worker, or refuses with LoopOutboundFull.
	Send(io LoopIO, job LoopJobValue) error
}

type LoopOutboundValue struct {
	// Lanes are the lanes' outbounds, by lane.
	Lanes []LoopOutbound
	// OutputCap is LoopValue.OutputCap, its default applied.
	OutputCap int
}

type LoopRingStateValue struct {
	// Loop is the loop's index in its group.
	Loop int `json:"loop"`
	// Ring is the ring's index in its loop.
	Ring int `json:"ring"`
	// Conns is the number of connections the ring holds now.
	Conns int64 `json:"conns"`
	// Accepted is the number of connections the ring accepted.
	Accepted uint64 `json:"accepted"`
	// Closed is the number of connections the ring closed.
	Closed uint64 `json:"closed"`
	// Batches is the number of loop iterations that reaped this ring.
	Batches uint64 `json:"batches"`
	// Completions is the number of completions or events the ring reaped.
	Completions uint64 `json:"completions"`
	// BufferStarved is the number of receives that found no provided buffer
	// (ENOBUFS) and waited for one to come back.
	BufferStarved uint64 `json:"buffer_starved"`
	// EnterRetries is the number of times submitting to the kernel was retried
	// after it was busy — the completion queue full, typically.
	EnterRetries uint64 `json:"enter_retries"`
	// AcceptPauses is the number of times the ring stopped accepting: the
	// descriptor reserve reached, or the process out of descriptors.
	AcceptPauses uint64 `json:"accept_pauses"`
	// Evicted is the number of idle connections closed to admit others.
	Evicted uint64 `json:"evicted"`
	// WatchdogFires is the number of times the liveness watchdog saw a stall it
	// could observe and acted on it.
	WatchdogFires uint64 `json:"watchdog_fires"`
	// Draining reports a ring the watchdog judged sick: it accepts nothing new
	// and closes its connections as they fall idle.
	Draining bool `json:"draining"`
}

type LoopStarter interface {
	// OnStart is called once, before any other callback, with the number of
	// lanes: every LoopIO.Loop the group's callbacks see is from 0 to lanes
	// less one.
	OnStart(lanes int)
}

type LoopStateValue struct {
	// Group is the loop group's name.
	Group string `json:"group"`
	// Backend is the backend in use.
	Backend LoopBackend `json:"backend"`
	// ProbeStage names the last stage of the kernel probe the backend passed,
	// or the stage that failed when the group fell back.
	ProbeStage string `json:"probe_stage"`
	// Degraded reports that the group runs on a backend other than the best one
	// it asked for: auto fell back from io_uring, say.
	Degraded bool `json:"degraded"`
	// DegradedReason names the fallback and its cause when Degraded is set.
	DegradedReason string `json:"degraded_reason,omitempty"`
	// Loops is the number of loops running.
	Loops int `json:"loops"`
	// LoopsSource says where Loops came from: "explicit", "auto" — LoopsAuto,
	// GOMAXPROCS read at Start — or "single" when Loops was zero.
	LoopsSource string `json:"loops_source"`
	// Rings is the number of rings per loop.
	Rings int `json:"rings"`
	// RingsSource says where Rings came from: "explicit", "derived" from the
	// connection bounds and the descriptor limit, or "single" when no bound was
	// set or the backend runs one ring.
	RingsSource string `json:"rings_source"`
	// RLimitNoFile is the effective RLIMIT_NOFILE soft limit read at Start. The
	// SDK never raises it; the Go runtime already lifts the soft limit to the
	// hard one.
	RLimitNoFile uint64 `json:"rlimit_nofile"`
	// GOMAXPROCS is runtime.GOMAXPROCS(0) read at Start. The SDK never sets it.
	GOMAXPROCS int `json:"gomaxprocs"`
	// BatchP99 is the 99th percentile of one loop iteration's duration, over the
	// loops' recent batches.
	BatchP99 DurationValue `json:"batch_p99"`
	// OutboundRefused counts the jobs a full queue to a worker refused
	// (LoopOutboundFull), every lane's: for the http1 adapter, the 503s it
	// answered for them. Zero when the group offloads nothing.
	OutboundRefused uint64 `json:"outbound_refused"`
	// RingStates reports every ring of every loop, loop by loop.
	RingStates []LoopRingStateValue `json:"ring_states"`
	// Capabilities reports every optional kernel capability the group's backend
	// probed or was told not to, the server's socket probes merged in
	// (ADR 0189).
	Capabilities []CapabilityValue `json:"capabilities,omitempty"`
}

type LoopValue struct {
	// Backend is the mechanic to run on. LoopBackendAuto takes the best one the
	// platform's probe reaches and reports any fallback in State; an explicit
	// backend the platform cannot run is refused at Start.
	Backend LoopBackend `json:"backend"`
	// Loops is the number of loops, each one goroutine locked to its OS thread
	// on a native backend. Zero selects one; LoopsAuto selects GOMAXPROCS less
	// one, at least one, read once at Start. The SDK never sets GOMAXPROCS:
	// sizing the process against its loops is the consumer's policy, and State
	// reports both. A native loop yields to the Go scheduler every 5 ms of
	// serving while GOMAXPROCS exceeds the group's loops (ADR 0199).
	Loops int `json:"loops"`
	// Rings is the number of descriptor shards inside one loop, each with its
	// own table of at most min(RLIMIT_NOFILE, IORING_MAX_FIXED_FILES) entries:
	// what lets io_uring serve more connections than RLIMIT_NOFILE. Zero
	// derives it, ⌈max(MaxConns, SoftConns) / min(RLIMIT_NOFILE,
	// IORING_MAX_FIXED_FILES)⌉, and one when both are zero; that is the only
	// formula, and State says where the value came from. epoll and the portable
	// backend run one ring whatever it says.
	Rings int `json:"rings"`
	// CQBatch bounds the completions or events one loop iteration reaps before
	// it calls OnBatchEnd. Zero selects the domain default.
	CQBatch int `json:"cq_batch"`
	// SpillCap is the most unconsumed input, in bytes, one connection may hold
	// between OnData calls. Past it the connection is closed with
	// LoopSpillFull. Zero selects the domain default.
	SpillCap int `json:"spill_cap"`
	// OutputCap is the most written and unsent output, in bytes, one
	// connection may hold. A Write past it is refused with LoopOutputFull. Zero
	// selects the domain default.
	OutputCap int `json:"output_cap"`
	// SoftConns is the soft connection bound: a connection accepted while the
	// group serves more is flagged under pressure (LoopIO.Pressure), so a
	// protocol can ask its peer to leave. It refuses nothing; MaxConns does.
	// Zero sets no soft bound.
	SoftConns int `json:"soft_conns"`
	// EvictIdle is how long a connection must have been idle before the loop
	// may close it to admit another under hard pressure — the process out of
	// descriptors, or MaxConns reached. A connection with unread bytes is
	// never evicted. Zero evicts nothing.
	EvictIdle DurationValue `json:"evict_idle"`
	// Capabilities opts the group into kernel capabilities of class A-code
	// (ADR 0189). Each is probed and used where the kernel has it, reported
	// "missing" and as a fault where it does not, and never used once
	// KITSUNIUM_NET_DISABLE names it. An engine, a class B capability or an
	// unknown token is refused at Start with LoopCapabilityRefused. Nil asks
	// for none; the class A-kernel capabilities need no opt-in.
	Capabilities []Capability `json:"capabilities,omitempty"`
	// Outbound is how many jobs one lane's queue to its worker holds (R3),
	// when the group's handler offloads (LoopOffloader). A Send past it is
	// refused with LoopOutboundFull and counted in LoopStateValue. Zero
	// selects 256.
	Outbound int `json:"outbound"`
	// BatchWait bounds how long an io_uring loop holds its wait for
	// BatchWaitMin completions while it is loaded: its previous batch reaped
	// at least four, or two receives carrying bytes at least come within the
	// bound at the rate they arrive. A loaded loop so serves larger batches for fewer
	// wakeups (ADR 0199, ADR 0202). It
	// bounds each grouped wait, not a request's latency: a request read over
	// several batches may meet one at each. Zero selects 250 µs,
	// a negative value turns the grouped wait off, and anything past the 10 ms
	// tick is the tick. epoll and the portable backend ignore it.
	BatchWait DurationValue `json:"batch_wait"`
	// BatchWaitMin is how many completions the grouped wait waits for before
	// BatchWait runs out. Zero selects 32; past CQBatch it is CQBatch.
	BatchWaitMin int `json:"batch_wait_min"`
}

type LoopWorker interface {
	// Work runs job, sent by the lane whose index is lane.
	Work(lane int, job LoopJobValue)
}

type Middleware[H any] func(next H) H

type OptionKind uint8

type OverrideValue struct {
	// Source is "environment" when KITSUNIUM_NET_ENGINE or KITSUNIUM_NET_DISABLE
	// is set to a non-empty value, and empty otherwise.
	Source string `json:"source,omitempty"`
	// Raw is what was read, each variable set as NAME=value, separated by a
	// space, in the order EnvEngine, EnvDisable.
	Raw string `json:"raw,omitempty"`
	// Applied is the highest engine the environment lets a group run on, after
	// both variables; empty when nothing is set. A group runs on
	// min(its code's choice, Applied), skipping what Disabled names.
	Applied Capability `json:"applied,omitempty"`
	// Disabled lists the engines KITSUNIUM_NET_DISABLE switched off.
	Disabled []Capability `json:"disabled,omitempty"`
}

type Packet interface {
	// Data returns the datagram payload.
	Data() []byte
	// From returns the sender's address.
	From() stdnet.Addr
	// To returns the local address the datagram arrived on.
	To() stdnet.Addr
	// ID returns the monotonic identifier assigned at read time.
	ID() uint64
	// Group returns the name of the listener group that received it.
	Group() string
	// Reply writes a datagram back to the sender. It exists so the common case
	// needs no reference to the underlying connection.
	Reply(b []byte) (n int, err error)
}

type PacketHandler interface {
	ServePacket(ctx context.Context, p Packet) error
}

type PacketHandlerFunc func(ctx context.Context, p Packet) error

type Phase uint8

type PlatformValue struct {
	// GOOS is runtime.GOOS.
	GOOS string `json:"goos"`
	// GOARCH is runtime.GOARCH.
	GOARCH string `json:"goarch"`
	// Kernel is the operating system's release as the platform reports it: the
	// uname release on Linux, kern.osrelease on darwin and the BSDs,
	// major.minor.build as GetVersion reports it on Windows; empty when it cannot
	// be read, and on illumos and Solaris, where the standard library reads none.
	Kernel string `json:"kernel,omitempty"`
	// Go is runtime.Version(), the toolchain the binary was built with.
	Go string `json:"go"`
}

type Policy interface {
	Allow(req RequestValue) error
}

type PolicyFunc func(req RequestValue) error

type PostFunc func(io LoopIO, arg uintptr)

type RequestValue struct {
	// Method is the uppercase HTTP method, e.g. "GET".
	Method string
	// Scheme is the URL scheme, e.g. "https".
	Scheme string
	// Host is the authority, host[:port]. It is carried because a policy that
	// sees only the path cannot defend against a redirect that keeps the path
	// and swaps the origin.
	Host string
	// EscapedPath is the percent-encoded path exactly as it will be sent. It is
	// never the decoded form — see the type comment.
	EscapedPath string
	// RawQuery is the encoded query string, without the leading "?".
	RawQuery string
}

type ResponseValue struct {
	// Status is the HTTP status code. It is set even when the call also returns
	// an error, so a caller can tolerate a specific status deliberately.
	Status int
	// Header is the response header set.
	Header http.Header
	// Body is the fully-read response body, already bounded by the client's
	// size cap. It is nil for a status that carries no body, such as 204.
	Body []byte
}

type SSEEventValue struct {
	// ID is the frame's "id" field. A client stores the last non-empty id it
	// saw and sends it back as Last-Event-ID when it reconnects, so this is the
	// resume token — and it is the CALLER's to mint, because only the caller
	// knows what it means. Empty emits no id field, which leaves the client's
	// stored id untouched; that is the format's own behaviour, not an omission.
	// An id carrying U+0000 is refused with SSEFieldInvalid, as one carrying a
	// line terminator is: a client ignores such an id field (WHATWG HTML,
	// "process the field"), so its stored resume token would silently stay the
	// previous one.
	ID string `json:"id"`
	// Name is the frame's "event" field — the event type the client dispatches
	// under. Empty means the default type, "message".
	Name string `json:"event"`
	// Data is the payload. Every line terminator it carries (LF, CR or CRLF)
	// becomes a separate "data:" line, which the client rejoins with "\n". A
	// payload that mixed terminators therefore arrives normalised to LF: the
	// value is preserved, its byte spelling is not.
	Data string `json:"data"`
	// Retry is the reconnection delay hint, emitted as an integer millisecond
	// count. Zero emits no retry field.
	Retry DurationValue `json:"retry"`
}

type StateValue struct {
	// Phase is where the server sits in its lifecycle.
	Phase Phase `json:"phase"`
	// Listeners describes every bound listener, including any degradation.
	Listeners []ListenerStateValue `json:"listeners"`
	// ActiveConns is the number of connections currently being served.
	ActiveConns int64 `json:"active_conns"`
	// TotalConns is the number accepted since the server started.
	TotalConns uint64 `json:"total_conns"`
	// RejectedConns is the number turned away by the connection ceiling.
	RejectedConns uint64 `json:"rejected_conns"`
	// OversizedPackets is the number of datagrams dropped for passing their
	// group's MaxPacketSize. They are counted rather than delivered because the
	// kernel has already discarded the tail, and the prefix that survives is
	// indistinguishable from a complete message to the handler receiving it. A
	// read loop has nobody to return an error to, so this counter is the report.
	OversizedPackets uint64 `json:"oversized_packets"`
	// AcceptBackoffs is the number of times an accept loop waited after Accept
	// failed with anything but its listener closing — the process out of file
	// descriptors, typically, with connections still queued. Retrying at once
	// would spin a core per listener while the condition lasts; each wait is
	// 5 ms, doubling to 1 s, and the next accepted connection starts the curve
	// over. A count that keeps rising is a server that cannot accept.
	AcceptBackoffs uint64 `json:"accept_backoffs"`
	// Datagrams counts what the batched datagram paths drop (ADR 0192).
	Datagrams DatagramStateValue `json:"datagrams"`
	// Loops reports every loop group (ADR 0186 §D8). It is empty while the
	// server serves none.
	Loops []LoopStateValue `json:"loops,omitempty"`
	// Override reports what KITSUNIUM_NET_ENGINE and KITSUNIUM_NET_DISABLE did
	// (ADR 0188).
	Override OverrideValue `json:"override"`
	// Faults lists everything the server runs without now, the degradations of
	// Listeners and Loops included; Degraded is true when it is not empty.
	Faults []FaultValue `json:"faults,omitempty"`
	// Fallbacks counts the engine fallbacks and keeps the last one.
	Fallbacks FallbacksValue `json:"fallbacks"`
	// Platform names the operating system, its release and the toolchain.
	Platform PlatformValue `json:"platform"`
}

type TimeoutsValue struct {
	// Read bounds one read from the peer.
	Read DurationValue `json:"read"`
	// Write bounds one write to the peer.
	Write DurationValue `json:"write"`
	// Idle bounds how long a connection may sit with no traffic at all.
	Idle DurationValue `json:"idle"`
	// Handshake bounds the TLS handshake, which is the phase a hostile peer can
	// most cheaply stall. Unlike the others, zero here does NOT mean unbounded:
	// the negotiation happens before any handler exists to notice it, so it
	// falls back to the domain's default instead.
	Handshake DurationValue `json:"handshake"`
}

type WSCloseCode uint16

type WSMessageValue struct {
	// Binary reports whether the payload is opaque bytes (opcode 0x2) rather
	// than UTF-8 text (opcode 0x1). The zero value is text, which is the
	// opcode a zero-valued frame would carry anyway.
	Binary bool `json:"binary"`
	// Data is the reassembled payload. For a text message it is valid UTF-8,
	// which the engine verifies on both the receiving and the sending side.
	Data []byte `json:"data"`
}

type WSOpCode byte