server

type Option func(*Options)

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

	// HealthChecks are the external dependency checks registered against the
	// control-plane health subsystem (/livez, /readyz, /startupz). Each
	// declared health.checks[] entry in the config expects a matching
	// registration here by name. Wire via WithHealthCheck / WithHealthChecker.
	HealthChecks []healthx.Registration

	// OTEL, when non-nil, overrides the env-derived OTLP bootstrap config
	// field-by-field (code wins over OTEL_* env vars, which win over the
	// observability.otel config block). Set via WithOTEL.
	OTEL *otelx.Config
	// LogFile, when non-nil, enables rotating on-disk log delivery
	// (lumberjack), overriding the APIC_LOG_FILE env var and the
	// observability.logs.file config block. Set via WithLogFile.
	LogFile *obsx.LogFileConfig
	// Prometheus, when non-nil, forces the authenticated /metrics
	// endpoint on with this provider config, overriding
	// observability.metrics.enabled. Set via WithPrometheus.
	Prometheus *promx.Config

	// Tracing, when non-nil, overrides observability.tracing.enabled: it
	// turns W3C trace-context propagation (traceparent/tracestate) on or off
	// regardless of the config block. Set via WithTracing.
	Tracing *bool
	// CorrelationHeader, when non-nil, overrides the correlation-ID header
	// name (both the inbound/outbound header and the log token), taking
	// priority over the APIC_CORRELATION_HEADER env var and the
	// observability.tracing.correlation_header config. An empty string means
	// the default (X-Correlation-ID). Set via WithCorrelation.
	CorrelationHeader *string

	// 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
}