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 CORSAnswerValue struct {
	// Lines are the field lines, each "Name: value\r\n", for the http1 codec.
	Lines []byte
	// Fields are the fields by name, for net/http's Header.
	Fields []CORSFieldValue
}

type CORSFieldValue struct {
	// Name is the field name.
	Name string
	// Value is the field value.
	Value string
}

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

type CORSValue struct {
	// Origins are the exact origins allowed, as a browser serializes them:
	// scheme://host[:port], in lower case, with no path. "*" allows any origin,
	// alone in the list and without Credentials. "null" is refused: it is what a
	// sandboxed page and a local file both send.
	Origins []string
	// Methods are the methods a preflight may ask for; empty selects the
	// CORS-safelisted GET, HEAD and POST, never every method.
	Methods []string
	// Headers are the request fields a preflight may ask for; empty allows only
	// the CORS-safelisted fields.
	Headers []string
	// ExposeHeaders are the response fields a page may read.
	ExposeHeaders []string
	// Credentials lets a page send cookies and read the answer. It is refused
	// with "*": that combination publishes every user's answers to every site.
	Credentials bool
	// MaxAge is how long a browser may keep a preflight's answer, clamped to 24
	// hours; zero writes no Access-Control-Max-Age, negative is refused.
	MaxAge DurationValue
}

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 CompressValue struct {
	// Types lists the Content-Types, without parameters, that may be compressed.
	// Empty selects text/plain, text/css, text/javascript, text/csv, text/xml,
	// application/json, application/javascript, application/xml, image/svg+xml
	// and application/wasm. text/html is not among them: a page that reflects a
	// request's input beside a secret is what BREACH reads, and a caller who
	// compresses HTML names it here, knowing it does not do that.
	Types []string `json:"types"`
	// Level is gzip's level, 1 to 9 or -1 for its default; zero selects -1.
	Level int `json:"level"`
	// MinBytes is the smallest body compressed: a smaller one is sent as it is,
	// as its gzip container would cost more than it saves. Zero selects 1024; a
	// negative value is refused.
	MinBytes int `json:"min_bytes"`
}

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 ConnUnwrapper interface {
	// Unwrap returns the socket beneath the connection.
	Unwrap() stdnet.Conn
}

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"`
	// KernelDrops is the number of datagrams the kernel dropped before a read
	// could see them, for want of room in a socket's receive buffer: the last
	// SO_RXQ_OVFL count of each batched UDP socket, summed (#973). A gauge of the
	// kernel's own counter, read from the messages that arrive, so a drop after
	// the last message is seen with the next one. The kernel counts what it
	// refused to queue, so under UDP GRO a coalesced message of N datagrams is
	// one drop: the count then stands below the datagrams lost. Zero where the
	// socket is not batched, and under KITSUNIUM_NET_DISABLE=udp-rxq-ovfl.
	KernelDrops uint64 `json:"kernel_drops"`
	// Capabilities reports the optional kernel capabilities of the datagram
	// sockets — udp-rxq-ovfl and udp-pktinfo, and uring-multishot-recvmsg for the
	// groups PacketGroup.HandleLoop serves — as a loop group's do: on, absent, disabled by the
	// operator, or unprobed while no batched socket exists.
	Capabilities []CapabilityValue `json:"capabilities,omitempty"`
}

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 HTTP1AccessStage uint8

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
	// TraceID is the trace the request joined, read from its traceparent by a
	// Trace link in the same chain; the zero value without one.
	TraceID trace.TraceID
	// Stage says what the record is: an answer written, one deferred or pending
	// and so with no status yet, or a deferred answer's completion.
	Stage HTTP1AccessStage
	// ID is the request's number (HTTP1RequestValue.ID): what a sampling decision
	// or a slow-request record is keyed on, the same on both records of a deferred
	// answer.
	ID uint64
	// Elapsed is the time from the batch's start to this record, the wait behind
	// the batch's earlier requests included; on a deferred answer's second record
	// the time since it was deferred.
	Elapsed DurationValue
	// RequestID is the request's correlation identifier, the one its answer
	// carries in X-Request-Id; empty without a RequestID link in the chain.
	RequestID HTTP1RequestIDValue
	// Proto is the request's HTTP major version, 1 or 2.
	Proto uint8
	// Stream is the HTTP/2 stream the request arrived on, zero on HTTP/1.1.
	Stream uint32
	// 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 HTTP1BodyAborter interface {
	// AbortBody tells the handler a request's body will not arrive whole.
	AbortBody(req *HTTP1RequestValue)
}

type HTTP1BodyReader interface {
	// OnBody receives the body's next bytes, chunk valid for this call only.
	// last is true exactly once, on the bytes that complete the Content-Length.
	OnBody(req *HTTP1RequestValue, chunk []byte, last 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 HTTP1FileValue struct {
	// R reads the file: *os.File where a descriptor is to be sent, or any other
	// io.ReaderAt (an embed.FS file) through the copy path. Nil means no file.
	R io.ReaderAt
	// Off is the offset of the first byte to send.
	Off int64
	// Len is how many bytes to send; what Content-Length says.
	Len int64
}

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

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

type HTTP1Limiter interface {
	// Allow reports whether one more request under key may be served, and when
	// it may not, after how many seconds a client should try again. now is a
	// monotonic count of nanoseconds: an instant that moves backwards refills
	// nothing. key is valid for this call only.
	Allow(key []byte, now int64) (ok bool, retryAfter int)
}

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

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
	// Trace is the request's W3C trace context, as the http1 chain's Trace link
	// read it from the traceparent field: invalid (IsValid false) when no such
	// link ran, when the field is absent, or when it is malformed, a request
	// being served either way (§4.3). tracestate is not read: a request carries
	// the 25 bytes of the context and no list. Parse resets it.
	Trace trace.SpanContextValue
	// Scheme is the :scheme pseudo-field of an HTTP/2 request, empty on HTTP/1.1.
	// An HTTP/2 codec maps a request before Canonical (ADR 0221): Method from
	//:method; Target from :path, origin-form or "*" (an absolute-form :path is
	// RefusalTargetForm); Host from :authority, else the Host field, both present
	// and different RefusalTargetHost, HasHost set; Fields the regular fields in
	// arrival order with HPACK's lowercase names; Authorization, ContentLength and
	// Body as on HTTP/1.1; Close, HeadLen and Consumed zero.
	Scheme []byte
	// Proto is the request's HTTP major version, 1 or 2.
	Proto uint8
	// Stream is the HTTP/2 stream the request arrived on, zero on HTTP/1.1.
	Stream uint32
	// ID identifies the request on its lane — the lane in the top 16 bits, a
	// counter from 1 in the rest — set by the loop adapter before the handler
	// runs, so two lanes never hold the same one. It is a number the client
	// never sees, what a sampling decision or a slow-request record is keyed on.
	// Parse leaves it as it is; outside the loop adapter it is what the caller
	// set.
	ID uint64
	// Conn names the connection the request arrived on, set by the loop adapter
	// before the handler runs: what a handler keeps to find, at
	// HTTP1Streamer.OnStreamOpen, the stream this request opened. Parse leaves it
	// as it is.
	Conn LoopConnRef
	// RoutePrefix is how many leading bytes of Path the Prefix route a router link
	// matched covers, zero for an exact route or none: what a file tree strips to
	// find the name under its route. Parse resets it; only a link sets it.
	RoutePrefix int
	// RequestID is the request's correlation identifier, as the http1 chain's
	// RequestID link accepted it from X-Request-Id or minted it: copied by
	// value, so a handler that needs it past the batch copies this value into
	// its own job table. Parse resets it; it is empty when no such link ran.
	RequestID HTTP1RequestIDValue
}

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
	// TraceLine holds the traceparent field line the http1 chain's Trace link
	// writes on this answer, Header pointing at it; a value, so a deferred
	// answer keeps it past the request. Only the link sets it.
	TraceLine [HTTP1TraceLineLen]byte
	// RequestID is the identifier the codec writes as an X-Request-Id field after
	// Header, when set: a value, so a deferred or a pending answer keeps it past
	// the request, and a field written per request needs no slice to outlive the
	// batch. The chain's RequestID link sets it.
	RequestID HTTP1RequestIDValue
	// Stream answers with a response delimited by the connection's close (RFC 9112
	// §6.3 item 8): the codec writes the status line and the fields with
	// Connection: close and no Content-Length, refusing HEAD, 204 and 304 with
	// HTTP1ResponseInvalid, and the handler keeps writing the body through
	// HTTP1Streamer. Requests pipelined behind it are dropped with the connection.
	// A Stream with Defer or Pending, behind a held answer, or with no
	// HTTP1Streamer in the handler is answered 500 and the connection closed. It
	// does not make a chunked answer: ADR 0186 §D6 still refuses every coding.
	Stream bool
	// Upgrade answers 101 Switching Protocols: the codec writes the status line,
	// Connection: Upgrade and Header — which holds the protocol's own fields —
	// and no length, then every later byte of the connection goes to
	// HTTP1Upgrader. It carries no body; with one, or with no HTTP1Upgrader in the
	// handler, the answer is 500 and the connection closed.
	Upgrade bool
	// RetryAfter, when above zero, is written by the codec as a Retry-After field
	// in seconds after Header: a value, so a refusal needs no slice of its own.
	// The chain's RateLimit link sets it.
	RetryAfter int
	// CORS holds the field lines the chain's CORS link gives this answer, written
	// by the codec after Header: its own slot, so the link costs nothing beside a
	// Headers link, and its bytes are the policy's, shared and read only.
	CORS []byte
	// File, set by a pending answer's worker, makes the answer's body a file: the
	// codec writes the head with Content-Length File.Len and no body bytes, and
	// sends the file behind it. A HEAD answer closes File.R unsent. With Body, on a
	// 204 or a 304, or outside a worker's answer it is answered 500 and the
	// connection closed.
	File HTTP1FileValue
}

type HTTP1StreamValue struct {
	// IO is the loop the connection lives on.
	IO LoopIO
	// Ref is the connection.
	Ref LoopConnRef
}

type HTTP1Streamer interface {
	// OnStreamOpen is called once the stream's head has been queued, from the
	// batch's end: s is valid for as long as the connection lives.
	OnStreamOpen(s HTTP1StreamValue)
	// OnStreamTimeout is called when the deadline s.Deadline armed expires.
	OnStreamTimeout(s HTTP1StreamValue)
	// OnStreamDrain is called once when the group starts draining: the last call
	// before the drain closes the connection, so a handler says goodbye and ends
	// the stream itself.
	OnStreamDrain(s HTTP1StreamValue)
	// OnStreamClose is called once the connection has closed; err says why, nil for an End or a clean close.
	OnStreamClose(s HTTP1StreamValue, err error)
}

type HTTP1Upgrader interface {
	// OnUpgradedData is handed bytes after the head of an upgraded connection and
	// returns how many it took: the rest waits in the spill for its next bytes,
	// and buf is valid for this call only.
	OnUpgradedData(s HTTP1StreamValue, buf []byte) int
}

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 HTTPCountsValue struct {
	// HTTP1Requests counts the HTTP/1.1 requests served.
	HTTP1Requests uint64
	// HTTP2Requests counts the HTTP/2 requests served.
	HTTP2Requests uint64
	// HTTP2Errors counts the HTTP/2 errors by type, a row for each counted.
	HTTP2Errors []corehttp2.ErrorCountValue
}

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 depth the kernel queues established connections at, before the
	// accept loop takes them (#978). Zero keeps the standard library's, the host's
	// somaxconn; the kernel clamps a larger value to it, and State says so. A
	// stream group sets it with the Backlog option, on both engines; Windows
	// keeps the platform's own.
	Backlog int `json:"backlog"`
	// ReceiveBuffer is the receive buffer, in bytes, the kernel is asked for on
	// the group's sockets, before bind (SO_RCVBUF): a datagram group's, a stream
	// group's listeners and so the sockets they accept (#973). Zero keeps the
	// kernel's default. The kernel doubles the value and clamps it to rmem_max;
	// State reports what it holds, in ListenerStateValue.ReceiveBuffer, and a
	// clamp is no fault.
	ReceiveBuffer int `json:"receive_buffer"`
	// SendBuffer is the send buffer, in bytes, asked as ReceiveBuffer is
	// (SO_SNDBUF, clamped to wmem_max).
	SendBuffer int `json:"send_buffer"`
	// 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"`
	// Shared reports a listener its group bound with ShareAddress: SO_REUSEPORT
	// set on every socket of the address and no probe made, so another process
	// that shares too may bind the same address and take part of its
	// connections (#1330). It is false on a listener bound without the option,
	// whose sharded sockets were opened only once a plain bind found the
	// address free, and on an adopted one.
	Shared bool `json:"shared,omitempty"`
	// 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"`
	// H2C reports an HTTP group serving HTTP/2 in cleartext, by prior knowledge alone.
	H2C bool `json:"h2c,omitempty"`
	// HTTP2 is the HTTP/2 bounds the group serves with, resolved: a group given
	// none reads ADR 0195's numbers. Nil for a listener that serves no HTTP.
	HTTP2 *corehttp2.LimitsValue `json:"http2,omitempty"`
	// MaxBodyBytes is the request-body bound an HTTP group served by net/http
	// holds on this listener: the default's 1 MiB, the option's value, or -1
	// for none. Zero on every other listener, which has no such bound.
	MaxBodyBytes int64 `json:"max_body_bytes"`
	// Backlog is the depth of the listener's accept queue as applied: the
	// Backlog option's value, or the host's somaxconn for the default, and the
	// clamp when the host's somaxconn is below what was asked (Degraded, with
	// its reason). Zero for an adopted socket, whose queue the supervisor sized,
	// and for a datagram socket.
	Backlog int `json:"backlog"`
	// ReceiveBuffer is the socket's receive buffer as the kernel holds it,
	// read back after bind, or after the group's size was applied to an
	// adopted socket (SO_RCVBUF): on Linux twice what was asked, clamped to
	// rmem_max, the kernel's default when nothing was asked. Zero where the
	// platform cannot say. A clamp is reported here and is no fault.
	ReceiveBuffer int `json:"receive_buffer"`
	// SendBuffer is the socket's send buffer as the kernel holds it, read back
	// as ReceiveBuffer is (SO_SNDBUF, wmem_max).
	SendBuffer int `json:"send_buffer"`
	// MultipathTCP reports a stream listener whose socket is Multipath TCP,
	// read back from the socket (SO_PROTOCOL is IPPROTO_MPTCP) after bind or
	// adoption: on Linux, what Go's net.Listen opens by default since Go 1.24
	// where the kernel has MPTCP (net.mptcp.enabled), unless GODEBUG's
	// multipathtcp says otherwise. A loop group that opts into uring-send-zc
	// on io_uring binds plain TCP instead, and its rows read false, because a
	// socket accepted from an MPTCP listener refuses IORING_OP_SEND_ZC; the
	// operator switching uring-send-zc off, or capping the group at epoll or
	// the portable backend, gives it Go's default back (#969, ADR 0189).
	// False on every other platform, for a Unix socket and for a datagram one.
	MultipathTCP bool `json:"multipath_tcp"`
	// ProxyRefused counts the connections a ProxyProtocol group refused — peers
	// outside Trusted, and headers malformed or not finished within Timeout. It
	// is the group's count, on each of its listeners' rows.
	ProxyRefused uint64 `json:"proxy_refused,omitempty"`
	// HTTP1Requests counts the HTTP/1.1 requests the group served since Start
	// (#966): one count per request on net/http's engine, one per batch on the
	// loop engine, whose adapter counts them. It is the group's count, on each
	// of its listeners' rows; zero on a group that serves no HTTP.
	HTTP1Requests uint64 `json:"http1_requests,omitempty"`
	// HTTP2Requests counts the HTTP/2 requests the group served, as HTTP1Requests does.
	HTTP2Requests uint64 `json:"http2_requests,omitempty"`
	// HTTP2Errors counts the group's HTTP/2 protocol errors by type, a row for
	// each type counted at least once, in the vocabulary's order: on net/http's
	// engine what its CountError reports, an unanswered PING included; on the
	// loop engine each RST_STREAM and GOAWAY its codec answers with an error
	// and each header list past its bound. net/http counts neither a header
	// list past MaxHeaderBytes, which it answers 431 itself, nor a frame past
	// its frame bound.
	HTTP2Errors []corehttp2.ErrorCountValue `json:"http2_errors,omitempty"`
	// ALPN is the protocol list a TLS HTTP group's listeners offer, in the
	// order offered (#964): the group's versions intersected with its
	// identity's NextProtos, on net/http's engine and on a TLS loop codec
	// group alike. Nil for a group that negotiates nothing.
	ALPN []string `json:"alpn,omitempty"`
}

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 LoopDrainer interface {
	// OnDrain is called once for ref, when the drain reached a connection it may
	// close: a place to say goodbye — an SSE retry field, a WebSocket 1001 — and
	// to close it.
	OnDrain(io LoopIO, ref LoopConnRef)
}

type LoopFileSpanValue struct {
	// FD is the open descriptor, read and never closed by the engine.
	FD int
	// Off is the offset of the first byte to send.
	Off int64
	// Len is how many bytes to send.
	Len int64
}

type LoopFileWriter interface {
	// WriteFile queues head, then the file's Len bytes from Off, behind the
	// connection's pending output: head may be empty, and is counted against the
	// output ceiling as Write's bytes are. The descriptor is duplicated before
	// WriteFile returns, so the caller may close its own at once. No byte of the
	// file is ever read by the process.
	//
	// OnWritable fires when the file's last byte has left. While a file is in
	// flight the connection's Write and WriteFile are refused with LoopOutputFull,
	// and a close asked waits for the file. It returns LoopFileRefused when the
	// backend cannot take this file (nothing was queued), LoopOutputFull when head
	// would pass the output ceiling, LoopStaleRef when the connection closed.
	WriteFile(ref LoopConnRef, head []byte, file LoopFileSpanValue) error
}

type LoopHTTPCodec interface {
	// SetHTTP is called once, before any other callback, with the group's HTTP settings.
	SetHTTP(v LoopHTTPValue)
	// Draining announces the group's drain. It is called once, from any
	// goroutine, before the engine starts closing connections for the drain.
	Draining()
	// InFlight reports whether ref's connection, of lane, holds requests the
	// drain must leave open: true keeps it past the drain's first sweep, and
	// eviction passes it by.
	InFlight(lane int, ref LoopConnRef) bool
}

type LoopHTTPCounter interface {
	// HTTPCounts returns the adapter's counts, read from any goroutine.
	HTTPCounts() HTTPCountsValue
}

type LoopHTTPValue struct {
	// Protocols is the group's Protocols list, nil when the group gave none.
	Protocols []string
	// HTTP2Off is set when KITSUNIUM_NET_DISABLE switched http2-loop off.
	HTTP2Off bool
	// HTTP2 is the HTTP2 option's bounds, the zero value when the group gave none.
	HTTP2 corehttp2.LimitsValue
}

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 LoopPeer interface {
	// Peer returns the credentials the kernel recorded for ref's peer when the
	// connection was made (SO_PEERCRED), with Verified set, and true; false for a
	// connection that is not a Unix one, for a stale ref and for one whose
	// descriptor the backend cannot ask.
	Peer(ref LoopConnRef) (LoopPeerValue, bool)
}

type LoopPeerValue struct {
	// UID is the peer's user id.
	UID uint32
	// GID is the peer's group id.
	GID uint32
	// PID is the peer's process id.
	PID uint32
	// Verified is true when the kernel named the peer.
	Verified bool
}

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"`
	// BatchesCut is the number of batches BatchBudget stopped while this ring
	// still had completions to reap (ADR 0206).
	BatchesCut uint64 `json:"batches_cut"`
	// BytesIn is the number of bytes the ring received and delivered to the handler.
	BytesIn uint64 `json:"bytes_in"`
	// BytesOut is the number of bytes the ring sent: the answers the kernel took, a short
	// send counted as it left.
	BytesOut uint64 `json:"bytes_out"`
	// OutputRefused is the number of Writes the ring refused with LoopOutputFull: the
	// connection's output ceiling, or the slab's budget, reached.
	OutputRefused uint64 `json:"output_refused"`
	// SpillClosed is the number of connections the ring closed with LoopSpillFull:
	// unconsumed input past SpillCap, or the slab's budget spent.
	SpillClosed uint64 `json:"spill_closed"`
	// Timeouts is the number of deadlines of SetDeadline that fired (OnTimeout calls).
	Timeouts uint64 `json:"timeouts"`
	// IdleClosed is the number of connections the ring closed for IdleTimeout.
	IdleClosed uint64 `json:"idle_closed"`
	// PendingOutput is the bytes written and not yet sent, a gauge: what the ring's
	// connections still owe their peers at the last batch's end.
	PendingOutput int64 `json:"pending_output"`
	// 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 LoopSpillChecker interface {
	// CheckSpill is called once, before any other callback, with the most
	// unconsumed input a connection may hold: a returned error fails Start.
	CheckSpill(spillCap int) error
}

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"`
	// SlabInUse is the bytes of the spill and output chunks every loop's slab holds at
	// the last batches' end, chunk sizes counted, a gauge.
	SlabInUse int64 `json:"slab_in_use"`
	// SlabMapped is the bytes every loop's slab has mapped outside the Go heap. A size
	// class keeps one wholly free arena and unmaps the others on the loop's tick
	// (#809), so it falls back after a burst.
	SlabMapped int64 `json:"slab_mapped"`
	// SlabBudget is the ceiling of SlabInUse, every loop's summed: past it a Write is
	// refused and a spill closes its connection, by name, never by the kernel's OOM
	// killer.
	SlabBudget int64 `json:"slab_budget"`
	// SlabBudgetSource says where each loop's slab budget came from (#809):
	// "explicit" for LoopValue.SlabBudget, "derived" from the cgroup allowance
	// memlimit read, "default" for 128 MiB a loop; empty on the portable
	// backend, which has no slab.
	SlabBudgetSource string `json:"slab_budget_source"`
	// 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. It is the ceiling on a
	// request's head and body together for an http1 handler that takes the
	// body whole (a LoopSpillChecker adapts to it at Start); an
	// HTTP1BodyReader's spill holds only the head.
	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"`
	// BatchBudget bounds how long an io_uring loop reaps completions in one
	// batch: past it, a ring stops reaping, and a ring after it reaps at most one
	// more lot of 16 before it stops too — a bounded overrun, not a hard stop.
	// What is left waits for the next batch, which starts at the ring it stopped
	// at and does not wait. A
	// request is answered once its batch ends, after OnBatchEnd, so a batch of
	// thousands of requests holds every answer for its whole length (ADR 0206).
	// A batch that ran past half of it hands its answers to the kernel at once
	// instead of at the next wait. Zero, or a negative value, bounds nothing:
	// the batch reaps up to four CQBatch a ring, as before. epoll and the
	// portable backend ignore it.
	BatchBudget DurationValue `json:"batch_budget"`
	// SendZCMin is the smallest flight an io_uring loop sends zero-copy, in
	// bytes, once the group opted into uring-send-zc (#969): a flight of at least
	// that many bytes leaves by IORING_OP_SEND_ZC and its slab chunk stays the
	// kernel's until the notification says the pages are free, a shorter one by
	// IORING_OP_SEND as before. Zero selects 16 KiB; a negative value is refused
	// with LoopValueInvalid. epoll and the portable backend ignore it, and so
	// does a group that did not opt in.
	SendZCMin int `json:"send_zc_min,omitempty"`
	// Affinity pins each loop's thread to one CPU, Affinity[i] for loop i, with
	// sched_setaffinity once the thread is locked (loop-affinity, class A-code,
	// #857). Nil pins nothing; otherwise it names one CPU per loop, from 0 to
	// 8191, or Start refuses it with LoopValueInvalid. A CPU the kernel refuses —
	// offline, outside the process's set, or a seccomp filter — leaves that loop
	// unpinned, serving, and the row missing, a fault. With Shards(0) and
	// so-incoming-cpu opted into, each loop's listener asks the kernel for the
	// connections its CPU received. The portable backend ignores it.
	Affinity []int `json:"affinity,omitempty"`
	// NotsentLowat is TCP_NOTSENT_LOWAT, in bytes, on the group's TCP listeners,
	// inherited by each accepted socket (tcp-notsent-lowat, class A-code, Linux
	// 3.12, #857): the kernel takes at most that many unsent bytes, so a write
	// is short and OnWritable fires once the peer drained, not once megabytes
	// of socket buffer emptied. Zero sets nothing unless Capabilities opts into
	// tcp-notsent-lowat, which selects 128 KiB; a positive value opts in;
	// negative is refused with LoopValueInvalid. The portable backend ignores it.
	NotsentLowat int `json:"notsent_lowat"`
	// SlabBudget is the most payload memory, in bytes, one loop maps outside the
	// Go heap for its connections' spill and output together (#809): past it a
	// Write is refused with LoopOutputFull and a spill closes its connection
	// with LoopSpillFull. Zero derives it from the cgroup allowance the server
	// reads with memlimit, a quarter of the allowance shared by the loops and
	// at most 128 MiB, and is 128 MiB where no allowance is found; negative is
	// refused with LoopValueInvalid. A size class's wholly free arenas past the
	// first are unmapped on the loop's tick. The portable backend ignores it.
	SlabBudget int `json:"slab_budget"`
	// BusyPoll is busy-poll's window (class A-code, #979): how long a loop's wait
	// polls the device queues of its sockets before it sleeps, io_uring's
	// busy_poll_to and epoll's busy_poll_usecs, rounded up to whole
	// microseconds. Zero selects 50 µs once Capabilities opts into busy-poll; it
	// opts nothing in by itself. Negative, or past one second, is refused with
	// LoopValueInvalid. The portable backend ignores it.
	BusyPoll DurationValue `json:"busy_poll"`
	// BusyPollBudget is how many packets one poll of busy-poll may take, epoll's
	// busy_poll_budget: zero is the kernel's, and past 64 the kernel asks for
	// CAP_NET_ADMIN, its refusal reading the row missing. Negative, or past
	// 65535, is refused with LoopValueInvalid. io_uring always takes the
	// kernel's; the portable backend ignores it.
	BusyPollBudget int `json:"busy_poll_budget"`
	// ZCRX names the NIC receive queue uring-zcrx would serve (class B, #980). A
	// zero Interface keeps the row off. While the row is class B a named queue
	// is only probed — registered on a throwaway ring that is closed at once,
	// the kernel's answer in the row's reason — and no byte is received through
	// it.
	ZCRX ZCRXValue `json:"zcrx"`
}

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: on a UDP socket
	// bound to a wildcard address the address the sender used, read from the
	// datagram (IP_PKTINFO, IPV6_RECVPKTINFO; Linux), with the socket's port;
	// otherwise the socket's bound address.
	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. On a socket bound to a
	// wildcard address it leaves from the address To reports, so a multi-homed
	// host answers from the address the client used.
	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 PacketLoopHandler interface {
	// OnPacket hands the handler one datagram: buf is its payload and from its
	// sender. A coalesced message (UDP GRO) is one call a datagram, in order; a
	// message the kernel cut, or a datagram past the group's MaxPacketSize, is
	// counted in State and never handed on. buf stays valid until the lane's next
	// OnBatchEnd returns, never later, and the handler must not write to it.
	OnPacket(io PacketLoopIO, from netip.AddrPort, buf []byte)
	// OnBatchEnd is called once a batch, after its OnPacket calls and before any
	// buffer handed to them goes back to the kernel; the batch's replies leave
	// after it returns.
	OnBatchEnd(io PacketLoopIO)
}

type PacketLoopIO interface {
	// Reply queues p for to, from the lane's socket, and returns: the batch's
	// replies leave together once OnBatchEnd returns — on io_uring as SENDMSG,
	// a run to one peer of one size as one UDP_SEGMENT send (ADR 0192) — and p
	// may be reused once Reply returns. It is refused with LoopOutputFull,
	// copying nothing, when the lane's reply queue has no room; a queued reply
	// the kernel refuses is counted in Datagrams.ReplyFailures. On a socket bound
	// to a wildcard address that reads each datagram's destination (udp-pktinfo),
	// a reply to a peer that sent a datagram in the batch being handed on leaves
	// from the address that datagram reached, the newest one's, as Packet.Reply
	// does (#972); a source the kernel refuses is sent from its own choice, and a
	// reply to a peer that sent nothing in the batch leaves from the kernel's
	// choice.
	Reply(to netip.AddrPort, p []byte) error
	// Loop returns the lane's index, from 0 to the group's lane count less one,
	// fixed for the lane's life.
	Loop() int
}

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 ProxyProtocolValue struct {
	// Trusted lists the CIDRs of the balancers. Empty, or a range that does not
	// parse, fails Start with OptionValueInvalid.
	Trusted []string `json:"trusted"`
	// Timeout bounds the header's arrival, on the server's clock. Zero selects
	// 3 s; a negative value fails Start with OptionValueInvalid.
	Timeout DurationValue `json:"timeout"`
}

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"`
	// SuppressedLogs counts the lines of net/http's own log, and the failed TLS
	// handshakes, the server did not write: over the cap of ten records a second,
	// or with no logger to write them to (WithLogger). A count that rises is a
	// port being probed, or a handler that panics.
	SuppressedLogs uint64 `json:"suppressed_logs"`
	// 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 SteerValue uint8

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"`
	// KeepAlive is the idle time before the first keepalive probe of an accepted
	// socket, and the interval between probes: zero is 15 s, the standard
	// library's, and negative sets none.
	KeepAlive DurationValue `json:"keep_alive"`
	// UserTimeout is TCP_USER_TIMEOUT, the time sent output may stay
	// unacknowledged before the kernel closes the connection: zero is Write's
	// bound when one is set, otherwise none.
	UserTimeout DurationValue `json:"user_timeout"`
}

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

type ZCRXValue struct {
	// Interface is the network interface's name; empty names none.
	Interface string `json:"interface"`
	// Queue is the index of the interface's receive queue; negative is refused
	// with LoopValueInvalid.
	Queue int `json:"queue"`
	// AreaBytes is the size of the area the kernel lands payloads in, rounded up
	// to whole pages: zero selects 4 MiB, negative is refused with
	// LoopValueInvalid.
	AreaBytes int `json:"area_bytes"`
}