server

type Option func(*Options)

type Options struct {
	Logger     *slog.Logger
	Middleware []func(http.Handler) http.Handler
	Metrics    obsx.MetricsProvider
	Telemetry  *obsx.TelemetryProvider

	// Impl is the business-logic implementation of the generated HTTP
	// ServerInterface. Embed apic.UnimplementedServer and override only
	// the methods you need. Nil uses apic.UnimplementedServer{}.
	Impl apic.ServerInterface
	// WSImpl is the business-logic implementation of the generated
	// WebSocket interface. Nil uses genws.UnimplementedWSServer{}.
	WSImpl genws.WSServerInterface
	// MCPImpl is the business-logic implementation of the generated MCP
	// tool interface. Embed genmcp.UnimplementedMCPServer and override only
	// the tools you implement. Nil uses genmcp.UnimplementedMCPServer{}.
	// Register is called unconditionally on startup so SetToolBuckets and
	// SetToolRoles (per-tool rate limits and RBAC) are always installed.
	MCPImpl genmcp.MCPServerInterface

	// AuthAPIKey / AuthJWT override the default credential verifiers. Use
	// AuthJWT to swap the built-in HS256 gate for RS256/ES256/JWKS or an
	// OIDC introspection call (e.g. an HSM-signed RS256 token verified
	// against the signer's public key). Nil keeps the built-in gate.
	AuthAPIKey func(*http.Request) error
	AuthJWT    func(*http.Request) error
	// AuthMTLS enforces deployment-specific mTLS issuer-label policy
	// (PIV/CAC/custom) AFTER securex.VerifyMTLS accepts the request. When
	// the spec declares any mtls route with supported_issuers, Serve
	// refuses to start unless this is wired; IssuerCNVerifier is a ready
	// default the thin entrypoint installs.
	AuthMTLS func(*http.Request, securex.MTLSPolicy) error

	// GetCertificate, when set, supplies the TLS server certificate at
	// handshake time instead of loading a PEM keypair from disk. Wire it
	// to signerx.GetCertificateForServer so the private key lives in an
	// HSM/KMS and never enters the process as raw bytes (NIST SC-12).
	GetCertificate func(*tls.ClientHelloInfo) (*tls.Certificate, error)

	// ExtraRoutes registers application-specific HTTP routes on the SAME mux
	// as the generated API, after the generated routes are registered. Use it
	// for bespoke endpoints that are not part of the apic spec — webhooks
	// with signature auth, reverse proxies, or a hand-wired sub-API — so a
	// service can adopt server.Serve without forking it. These routes share
	// the generated httpx pipeline (body limits, security headers, CORS,
	// per-IP rate limit) but are NOT covered by the generated per-route auth:
	// each handler MUST enforce its own authentication. Patterns must not
	// collide with a generated route (http.ServeMux panics on duplicates).
	ExtraRoutes func(mux *http.ServeMux)

	// InsecureHTTP opts the listener OUT of TLS and serves plain HTTP. It
	// exists for deployments that terminate TLS upstream (ingress/mesh) and
	// hand the process plaintext on a trusted network hop. This is the
	// code-level equivalent of the config opt-in server.tls.mode:"off";
	// either one enables it. It is OFF by default and must be set
	// explicitly — with neither opt-in set, Serve still refuses to boot
	// without a TLS cert, so plaintext is never served by accident. When
	// enabled, Serve logs a one-time warning; terminate TLS upstream.
	InsecureHTTP bool
}