engine

type AcceptController interface {
	// PauseAccept stops accepting new connections. Existing connections continue.
	PauseAccept() error
	// ResumeAccept resumes accepting new connections after a pause.
	ResumeAccept() error
}

type CPUMonitor interface {
	Sample() (CPUSample, error)
}

type CPUSample struct {
	Utilization float64
	Timestamp   time.Time
}

type CapabilityProfile struct {
	// OS is the operating system name (e.g. "linux").
	OS string
	// KernelVersion is the full kernel version string (e.g. "5.15.0-91-generic").
	KernelVersion string
	// KernelMajor is the major kernel version number.
	KernelMajor int
	// KernelMinor is the minor kernel version number.
	KernelMinor int
	// IOUringTier is the detected io_uring capability tier (None through Optional).
	IOUringTier Tier
	// EpollAvailable is true if epoll is supported on this system.
	EpollAvailable bool
	// MultishotAccept is true if io_uring multishot accept is available (kernel 5.19+).
	MultishotAccept bool
	// MultishotRecv is true if io_uring multishot recv is available (kernel 5.19+).
	MultishotRecv bool
	// ProvidedBuffers is true if io_uring provided buffer rings are available (kernel 5.19+).
	ProvidedBuffers bool
	// SQPoll is true if io_uring SQ polling mode is available (kernel 6.0+).
	SQPoll bool
	// CoopTaskrun is true if IORING_SETUP_COOP_TASKRUN is available (kernel 5.19+).
	CoopTaskrun bool
	// SingleIssuer is true if IORING_SETUP_SINGLE_ISSUER is available (kernel 6.0+).
	SingleIssuer bool
	// LinkedSQEs is true if io_uring linked SQE chains are supported.
	LinkedSQEs bool
	// DeferTaskrun is true if IORING_SETUP_DEFER_TASKRUN is available (kernel 6.1+).
	DeferTaskrun bool
	// FixedFiles is true if io_uring fixed file descriptors are available.
	FixedFiles bool
	// SendZC is true if io_uring zero-copy send is available.
	SendZC bool
	// Sendfile is true if sendfile(2) is available for zero-copy file
	// responses. True on Linux (kernel 2.6.33+, which every supported
	// distro is well past); false on non-Linux platforms. The epoll
	// engine implements engine.SendfileCapable and the H1 static-file
	// response path uses it (Context.File, middleware/static); engines
	// without SendfileCapable (iouring, std) fall back to read+write.
	Sendfile bool
	// Zerocopy is true if a MSG_ZEROCOPY userspace-buffer send path is
	// available. Currently always false: the engine does not ship a
	// MSG_ZEROCOPY send path (a correct one needs SO_ZEROCOPY +
	// sendmsg(MSG_ZEROCOPY) + errqueue completion draining + buffer
	// pinning). sendfile(2) covers the zero-copy file-serving workload
	// via the Sendfile flag above; iouring has IORING_OP_SEND_ZC (kernel
	// 6.0+) which is a separate flag (SendZC above). TCP MSG_ZEROCOPY
	// landed in Linux 4.14, UDP in 5.0 — flip this on (gated at 4.14)
	// only when the send path is actually implemented.
	Zerocopy bool
	// NumCPU is the number of logical CPUs.
	NumCPU int
	// NUMANodes is the number of NUMA nodes detected.
	NUMANodes int
}

type Carryover struct {
	// RemoteAddr is the peer address string captured by the source engine, so
	// the destination need not re-Getpeername the fd.
	RemoteAddr string

	// Buffered holds bytes the source engine had already read off the socket but
	// not yet processed — buffered pipelined NEXT-request bytes that sat in the
	// HTTP/1 parser at a clean request boundary (#383). The destination replays
	// them through its parser before arming its first read. Empty in the common
	// case (the socket was fully drained at the boundary). Only ever carries
	// next-request bytes — the source guarantees no in-progress request remains
	// (AtRequestBoundary), so a fresh parser can consume them correctly.
	Buffered []byte
}

type Engine interface {
	// Listen starts the engine and blocks until ctx is canceled or a fatal
	// error occurs. The engine begins accepting connections on the configured address.
	Listen(ctx context.Context) error
	// Shutdown gracefully drains in-flight connections. The provided context
	// controls the deadline; if it expires, remaining connections are closed.
	Shutdown(ctx context.Context) error
	// Metrics returns a point-in-time snapshot of engine performance counters.
	Metrics() EngineMetrics
	// Type returns the engine type identifier (IOUring, Epoll, Adaptive, or Std).
	Type() EngineType
	// Addr returns the bound listener address, or nil if not yet listening.
	Addr() net.Addr
}

type EngineMetrics struct {
	// RequestCount is the cumulative number of requests handled by this engine.
	RequestCount uint64
	// ActiveConnections is the current number of open connections.
	ActiveConnections int64
	// ErrorCount is the cumulative number of connection-level or protocol errors.
	ErrorCount uint64
	// Throughput is the recent requests-per-second rate.
	Throughput float64
	// AsyncRoutes is the count of routes registered with .Async(true) on
	// this engine's handler. Static after Listen — derived from the
	// router's per-route async flags and exposed for diagnostics so
	// operators can see how many handlers run on the per-conn dispatch
	// goroutine vs inline on the worker. Zero on engines whose handler
	// does not implement [github.com/goceleris/celeris/protocol/h2/stream.AsyncRouteResolver].
	AsyncRoutes int
	// AsyncPromotedConns is the cumulative number of connections that
	// have been promoted from inline-on-worker to the per-conn dispatch
	// goroutine via per-handler async (celeris #300). Counts promotions,
	// not currently-promoted conns — every fresh async-mode connection
	// that hits an async route increments this once. Useful to observe
	// how often the inline → goroutine handoff fires vs the pure-sync
	// inline fast path.
	AsyncPromotedConns uint64
	// Workers is the number of I/O workers (io_uring) or event loops
	// (epoll) the engine is running. Static after Listen. The adaptive
	// controller divides ActiveConnections by it to derive the
	// conns-per-worker load signal that drives engine selection.
	Workers int
	// AcceptCount is the cumulative number of connections accepted by this
	// engine since start. Together with elapsed time it yields the accept
	// rate (new-connection arrival rate) used as a secondary load signal.
	AcceptCount uint64
	// CloseCount is the cumulative number of connections closed by this
	// engine since start. AcceptCount - CloseCount tracks the live count;
	// a high close rate relative to accepts indicates short-lived
	// churn-style connections.
	CloseCount uint64
	// BytesRead is the cumulative number of payload bytes received from
	// the network across all connections. Used with BytesWritten and
	// RequestCount to derive the average bytes-per-request signal that
	// suppresses io_uring selection for link-bound (large-payload)
	// workloads where the engines tie.
	BytesRead uint64
	// BytesWritten is the cumulative number of payload bytes sent to the
	// network across all connections. See BytesRead.
	BytesWritten uint64
	// AdaptiveSwitches is the cumulative count of completed epoll⇄io_uring
	// switches performed by the adaptive engine. Zero for non-adaptive
	// engines, which never switch. Live switching is the adaptive engine's
	// most complex path; surfacing the count lets ops and benchmarks
	// correlate a throughput or tail-latency anomaly with switching activity
	// (a rare switch transient can skew a single benchmark pass).
	AdaptiveSwitches uint64
}

type EngineType uint8 //nolint:revive // user-approved name

type EventLoopProvider interface {
	// NumWorkers returns the number of worker event loops available for
	// driver FD registration. This is typically equal to the engine's
	// configured worker count (one per CPU core).
	NumWorkers() int
	// WorkerLoop returns the WorkerLoop for worker n, where 0 <= n < NumWorkers().
	// Calling WorkerLoop with an out-of-range index panics.
	WorkerLoop(n int) WorkerLoop
}

type Protocol uint8

type SendfileCapable interface {
	Sendfile(fdOut int, file *os.File, offset, length int64, headers []byte) (int64, error)
}

type SwitchFreezer interface {
	// FreezeSwitching prevents the adaptive engine from switching.
	FreezeSwitching()
	// UnfreezeSwitching allows engine switching to resume.
	UnfreezeSwitching()
}

type Tier uint8

type TransplantTarget interface {
	// AdoptConn takes ownership of fd — a connected, non-blocking real socket
	// sitting at an HTTP/1 request boundary — and begins serving it. The caller
	// must have already removed fd from its own engine. On a returned error the
	// caller still owns fd and is responsible for closing it.
	AdoptConn(fd int, carry Carryover) error
}

type WorkerLoop interface {
	// RegisterConn adds fd to the worker's interest set and installs the
	// data and close callbacks. The fd is expected to be already connected
	// and in non-blocking mode. Returns an error if fd is already registered
	// on this or another worker.
	RegisterConn(fd int, onRecv func([]byte), onClose func(error)) error
	// UnregisterConn removes fd from the worker's interest set and triggers
	// the onClose callback (with a nil error) after any in-flight operations
	// complete. The caller is responsible for closing the fd itself.
	UnregisterConn(fd int) error
	// Write enqueues data for transmission on fd. The call does not block on
	// the kernel send buffer: data is buffered and flushed asynchronously by
	// the worker. Returns [ErrQueueFull] if the worker's outbound queue is
	// saturated. The data slice may be retained by the worker until the
	// write completes; callers must not modify it after calling Write.
	Write(fd int, data []byte) error
	// CPUID returns the CPU this worker is pinned to, or -1 if the worker is
	// not pinned. Drivers may use this to co-locate allocations (e.g.,
	// NUMA-aware buffers) with the worker.
	CPUID() int
}