resource

type Config struct {
	// Protocol is the HTTP protocol version (HTTP1, H2C, or Auto).
	Protocol engine.Protocol
	// Engine is the I/O engine type (IOUring, Epoll, Adaptive, or Std).
	Engine engine.EngineType
	// Addr is the TCP address to listen on (e.g. ":8080").
	Addr string
	// Resources holds worker, buffer, and connection limit overrides.
	Resources Resources
	// MaxHeaderBytes is the max header block size in bytes (min 4096 if set).
	MaxHeaderBytes int
	// MaxConcurrentStreams limits simultaneous H2 streams per connection.
	MaxConcurrentStreams uint32
	// MaxFrameSize is the max H2 frame payload size (range 16384-16777215).
	MaxFrameSize uint32
	// InitialWindowSize is the H2 initial stream flow-control window size.
	InitialWindowSize uint32
	// ReadTimeout is the max duration for reading the entire request.
	ReadTimeout time.Duration
	// WriteTimeout is the max duration for writing the response.
	WriteTimeout time.Duration
	// IdleTimeout is the max duration a keep-alive connection may be idle.
	IdleTimeout time.Duration
	// DisableKeepAlive disables HTTP keep-alive.
	DisableKeepAlive bool
	// Listener is an optional pre-existing listener for socket inheritance.
	Listener net.Listener
	// MaxRequestBodySize is the maximum allowed request body size in bytes.
	// 0 uses the default (100 MB). -1 disables the limit (unlimited).
	MaxRequestBodySize int64
	// AsyncHandlers dispatches HTTP handlers to spawned goroutines instead
	// of inline execution on LockOSThread'd workers. See celeris.Config.
	AsyncHandlers bool
	// OnExpectContinue is called when an H1 request contains "Expect: 100-continue".
	// If the callback returns false, the server responds with 417 Expectation Failed
	// and skips reading the request body. If nil, the server always sends 100 Continue.
	OnExpectContinue func(method, path string, headers [][2]string) bool
	// OnConnect is called when a new connection is accepted.
	OnConnect func(addr string)
	// OnDisconnect is called when a connection is closed.
	OnDisconnect func(addr string)
	// Logger is the structured logger for engine diagnostics (default slog.Default()).
	Logger *slog.Logger
	// EnableH2Upgrade enables RFC 7540 §3.2 HTTP/1.1→H2C upgrades. Resolved
	// from celeris.Config.EnableH2Upgrade (pointer, may be nil) and Protocol.
	// Always a concrete value after WithDefaults.
	EnableH2Upgrade bool
	// SkipBuiltinScaler suppresses the per-engine dynamic worker scaler
	// loop. Set by the adaptive engine when it constructs its sub-engines —
	// adaptive runs ONE higher-level scaler that delegates to the active
	// sub-engine, so the iouring + epoll built-in scalers must stay quiet
	// to avoid two scalers fighting over the same worker pool.
	SkipBuiltinScaler bool
	// WorkerScaling configures the dynamic worker scaler. Nil disables the
	// scaler (default — workers stays at Resources.Workers and never adapts).
	// When set, the scaler activates and deactivates workers based on
	// observed load to keep CQE/event batching density in the sweet spot.
	// See WorkerScalingConfig for tuning details.
	WorkerScaling *WorkerScalingConfig
}

type ResolvedResources struct {
	// Workers is the resolved number of I/O worker goroutines.
	Workers int
	// SQERingSize is the io_uring submission queue size (power of 2).
	SQERingSize int
	// BufferPool is the number of pre-allocated I/O buffers.
	BufferPool int
	// BufferSize is the resolved per-connection I/O buffer size in bytes.
	BufferSize int
	// MaxEvents is the max events returned per epoll_wait call.
	MaxEvents int
	// MaxConns is the resolved max connections per worker.
	MaxConns int
	// SocketRecv is the resolved SO_RCVBUF size.
	SocketRecv int
	// SocketSend is the resolved SO_SNDBUF size.
	SocketSend int
}

type Resources struct {
	// Workers is the number of I/O worker goroutines (0 = GOMAXPROCS).
	Workers int
	// BufferSize is the per-connection I/O buffer size in bytes (0 = engine default).
	BufferSize int
	// SocketRecv is the SO_RCVBUF size for accepted connections (0 = OS default).
	SocketRecv int
	// SocketSend is the SO_SNDBUF size for accepted connections (0 = OS default).
	SocketSend int
	// MaxConns is the max simultaneous connections per worker (0 = unlimited).
	MaxConns int
}

type WorkerScalingConfig struct {
	// Strategy picks the seed-state strategy. Zero value is
	// ScalingStrategyStartHigh, which is the data-validated default for
	// most production workloads. See WorkerScalingStrategy for tuning.
	Strategy WorkerScalingStrategy
	// MinActive is the floor on the active worker count. The scaler will
	// never reduce active workers below this. Defaults to max(2, NumCPU/2).
	// Set to NumCPU to force the scaler to always run at full capacity
	// (effectively a static-w=NumCPU configuration).
	MinActive int
	// TargetConnsPerWorker is the active-worker scaling target. The scaler
	// computes desired = ceil(activeConns / TargetConnsPerWorker), clamps
	// to [MinActive, NumWorkers], and steers active toward that. Default 20.
	// Higher values keep more conns per worker (better batching, less
	// parallelism). Lower values prefer parallelism over batching.
	TargetConnsPerWorker int
	// Interval controls how often the scaler reevaluates active count.
	// Default 250ms. Lower values respond to load changes faster but burn
	// more CPU on the controller goroutine.
	Interval time.Duration
	// ScaleUpStep is the maximum number of workers the scaler will
	// resume per tick. Default 2 — wider bursts disrupt SO_REUSEPORT
	// load balancing more than they help. Bigger values are tempting on
	// SPIKE workloads but produce worse throughput per the v1.4.1
	// SPIKE-test sweep (upStep=4 and upStep=8 both lost to upStep=2).
	ScaleUpStep int
	// ScaleDownStep is the maximum number of workers the scaler will
	// pause per tick when load drops. Default 1 — scale-down too quickly
	// and you can't recover throughput when load comes back.
	ScaleDownStep int
	// ScaleDownHysteresis adds a buffer between desired and active
	// before scale-down fires: scale-down only if desired ≤ active -
	// ScaleDownHysteresis - 1. Default 1 (so a desired-of-N triggers
	// scale-down only when active is N+2 or higher).
	ScaleDownHysteresis int
	// ScaleDownIdleTicks is how many consecutive sub-threshold ticks
	// must pass before a single scale-down step fires. Default 4
	// (= 1 second at the default 250ms interval). Tunes how patient
	// the scaler is about temporary lulls: a request-rate dip of one
	// tick will not trigger scale-down.
	ScaleDownIdleTicks int
	// Trace logs every scaler decision (active, desired, idle_ticks).
	// Default false. Use when diagnosing scaling behaviour.
	Trace bool
}

type WorkerScalingStrategy int