serverkit

type Authenticator interface {
	connect.Interceptor
	// Audience names the trust domain this authenticator admits: AudienceUser
	// ("user"), or a name the project chooses ("daemon", "operator").
	Audience() string
	// Caller reads, from a request context, the caller this authenticator
	// admitted, as forge claims. nil means it does not say — its auth keeps
	// the caller somewhere forge cannot read — and NewChain then refuses to
	// default Audit or Activity, because both would record every call as
	// anonymous.
	Caller() CallerLookup
}

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

type CallerLookup = func(ctx context.Context) (*authn.Claims, bool)

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

type ChainDeps struct {
	// Auth authenticates every request and names the audience the chain
	// admits. Required: a nil Auth is a NewChain error, so a server with no
	// authenticator fails at boot instead of serving.
	Auth Authenticator

	// Logger feeds recovery, logging and the default audit interceptor. nil
	// is slog.Default().
	Logger *slog.Logger

	// Trace opens the server span; it runs OUTERMOST, so a request auth
	// rejects still has a span and every log line carries its trace_id. nil
	// is otelconnect with WithTrustRemote — an inbound traceparent (the
	// browser's) becomes the span's parent. A chain facing callers that
	// must not choose its trace ids passes observe.TrustRemoteBy, which
	// adopts as much of each caller's context as it authenticates to.
	// NoTrace drops it.
	Trace connect.Interceptor

	// Deadline bounds every RPC's time and reports one still running past
	// its watchdog threshold. It runs after observability, so a
	// DeadlineExceeded is logged and counted with its full duration, and
	// BEFORE Auth, so authenticating — a token store query, an
	// introspection call — runs inside the RPC's budget. nil is
	// serverkit.Deadline{}: unary RPCs bounded by DefaultUnaryDeadline,
	// streams unbounded, a unary RPC still running after DefaultSlowAfter
	// logged at WARN through Logger. Configure it in place
	// (serverkit.Deadline{Procedures: middleware.ProcedureDeadlines}); any
	// other interceptor here replaces it and runs in the same position.
	// NoDeadline drops it.
	Deadline connect.Interceptor

	// Audit records who called what, after Auth. nil is
	// middleware.AuditInterceptor over Auth's Caller — and a NewChain error
	// when Auth's Caller is nil, since it would audit every call as
	// anonymous. NoAudit drops it.
	Audit connect.Interceptor

	// RateLimit runs after Audit. It has no default — a rate limit is a
	// budget only configuration can name — so nil is none.
	// middleware.RateLimitInterceptor returns nil for a zero rate, so its
	// result can be passed through unconditionally.
	RateLimit connect.Interceptor

	// LogOptions tune how the logging interceptor records successful RPCs
	// (observe.WithSuccessSampling). nil logs every one.
	LogOptions []observe.LogOption

	// Extras are the project's own interceptors, run after RateLimit and
	// before Activity, the stream drain and protovalidate.
	Extras []connect.Interceptor

	// Activity writes the typed activity event each rpc declares in
	// `(forge.v1.method).activity` (forge/pkg/activity), after the handler
	// succeeds. It runs after Auth, so it knows the caller, and next to the
	// handler, so it judges the handler's own outcome. nil is
	// activity.Interceptor with no store, its Principal read from Auth's
	// Caller (activity.ClaimsPrincipal): declared events are logged, not
	// persisted. nil is a NewChain error when Auth's Caller is nil, since
	// every event would name an anonymous actor; pass
	// activity.Interceptor(activity.Deps{Principal: …}) with the project's
	// own Principal then. Pass activity.Deps{Writer: activity.NewStore(db)}
	// to keep events. NoActivity drops it.
	Activity connect.Interceptor

	// StreamDrain binds every server-streaming and bidi RPC to the drain of
	// the listener serving it, so a rollout ends it with a status its client
	// reconnects on (stream_drain.go). nil is StreamDrainInterceptor().
	// NoStreamDrain drops it.
	StreamDrain connect.Interceptor

	// Validate rejects a request whose buf.validate rules fail, with
	// InvalidArgument, right before the handler: it is the innermost layer.
	// nil is protovalidate (pkg/validate). NoValidate drops it.
	Validate connect.Interceptor

	// ReadMaxBytes and SendMaxBytes cap one request's and one response's
	// payload. connect-go reads and decodes a whole body before any
	// interceptor runs, so an uncapped handler turns one anonymous request
	// into an OOMKill. Zero is DefaultMaxBytes (4 MiB); negative is no cap.
	ReadMaxBytes int
	SendMaxBytes int
}

type Config struct {
	// Addr is the public listener address (e.g. ":8080"). Required.
	Addr string

	// PprofAddr is the side-listener for net/http/pprof, and forge's
	// scaffold sets it ON by default (127.0.0.1:6060) rather than leaving
	// it empty. Never mount pprof on the public Addr — its endpoints can
	// leak memory and stall the process — which is why this is a separate
	// address rather than a path on the main mux.
	//
	// The default is LOOPBACK, and that is what makes always-on defensible:
	// the listener exists in every environment and is routable from none of
	// them (the scaffolded manifests give it no Service, route, or published
	// port). Reach it with:
	//
	//	go tool pprof http://localhost:6060/debug/pprof/heap
	//	kubectl port-forward <pod> 6060:6060   # then the line above
	//
	// Set a wildcard address (0.0.0.0:6060) where a profile genuinely has to
	// cross a container boundary. Empty disables the pprof server entirely.
	//
	// A failed bind is NEVER fatal: Run logs it and serves on without pprof,
	// regardless of FailurePolicy. A debug surface that can kill the process
	// is worse than no debug surface.
	PprofAddr string

	// TLSCertPath and TLSKeyPath enable TLS when both are non-empty.
	// Validation of "both or neither" must happen in the project's
	// config layer before Run is called.
	TLSCertPath string
	TLSKeyPath  string

	// LogLevel is the slog level applied to the root logger. Zero
	// value is slog.LevelInfo.
	LogLevel slog.Level

	// LogFormat selects the slog handler. "text" emits text;
	// anything else (including "" and "json") emits JSON.
	LogFormat string

	// Environment is the deployment environment string. When equal to
	// EnvDevelopment Run emits a loud warning about permissive defaults,
	// suppresses HSTS, and enforces CORS even with an empty CORSOrigins
	// (see CORSEnabled). Every other value — including "" — is treated as
	// a deployed environment: closed by default.
	Environment string

	// OTLPEndpoint is the base OTLP collector endpoint (e.g.
	// "http://localhost:4318"); the wire protocol (http/protobuf by default,
	// grpc) and headers come from OTEL_EXPORTER_OTLP_PROTOCOL / _HEADERS.
	// Empty defers to OTEL_EXPORTER_OTLP_ENDPOINT read by the SDK. serverkit OWNS OpenTelemetry setup: Run
	// calls observe.Setup internally with this endpoint, installs the
	// global trace/metric providers, mounts the Prometheus /metrics handler
	// on its own edge, and flushes the providers during graceful shutdown.
	// Empty means no OTLP exporter is wired — the always-on Prometheus
	// /metrics path still works. The caller no longer builds a cmd/otel.go
	// shim; it projects this (and ServiceName) from its typed config.
	OTLPEndpoint string

	// ServiceName is the logical service name reported on OTel traces and
	// metrics (semconv service.name). It is APP IDENTITY (the project name),
	// not a per-env knob — the caller passes a generated constant. Empty
	// falls back to observe.Setup's "unknown".
	ServiceName string

	// ServiceVersion is reported as semconv service.version (the binary's
	// build version). The "dev" sentinel / empty are treated as "no
	// version" by observe.Setup.
	ServiceVersion string

	// AutoMigrate signals the caller-owned migration step should run.
	// serverkit no longer runs migration itself — the cmd layer reads
	// this flag (plus DatabaseURL/DBDriver/DBPoolTuning below) and runs
	// the migration before calling Run. The fields remain on Config so
	// the projection from the project's typed config stays in one place.
	AutoMigrate bool

	// DatabaseURL is the DSN the caller passes to sql.Open for its
	// migration connection. Required (caller-side) when AutoMigrate is
	// true.
	DatabaseURL string

	// DBDriver is the sql.Open driver name (e.g. "pgx"). Empty
	// defaults to "pgx".
	DBDriver string

	// DBPoolTuning is applied (via ApplyDBPoolTuning) by the caller to
	// its migration connection before the migration runs.
	DBPoolTuning DBPoolTuning

	// DBConnectTimeout is the TOTAL budget for connecting to the database at
	// startup (AutoMigrate and OpenDB). The connect retries with capped
	// exponential backoff and jitter inside it, the process stays up and
	// reports not-ready meanwhile, and only a database still unreachable at
	// the deadline fails the process. Zero falls back to
	// DefaultDBConnectTimeout (5m). The rendered startup probe window must
	// cover it — see v1alpha1.StartupWindowSeconds.
	DBConnectTimeout time.Duration

	// CORSOrigins is the allow-list handed to the CORSMiddleware factory.
	// Each entry must be a full origin (scheme + host + optional port).
	//
	// It does NOT decide whether CORS runs — CORSEnabled does. In
	// development the factory is invoked with an empty list (the project's
	// factory then selects its origin-reflecting dev policy, which ignores
	// the list); in a deployed environment an empty list means no CORS
	// layer at all.
	CORSOrigins []string

	// CORSAllowCredentials toggles Access-Control-Allow-Credentials.
	// The wildcard-origin + credentials combination must be rejected
	// by the project's config validation before Run is called.
	CORSAllowCredentials bool

	// SecurityHeaders enables the OWASP security-header middleware.
	// HSTS is only emitted when Environment != "development".
	SecurityHeaders bool

	// PreStopDelay is the readiness-flip drain pause. Zero falls back
	// to 5s; negative is no pause. Operators tune this to match their
	// load-balancer probe interval — too short causes brief 502s on
	// rollout.
	//
	// PreStopDelay and ShutdownTimeout follow the rule every Config
	// duration does — zero is the default, negative is none — and "none"
	// for both is a phase that takes no time: no pause, and a shutdown
	// window that is over as it opens (in-flight requests and streams are
	// cut, teardown runs on an expired context). It is never "unbounded":
	// forge derives the pod's grace period from the two, and the kubelet
	// would end an unbounded shutdown at it anyway.
	PreStopDelay time.Duration

	// ShutdownTimeout bounds the post-readiness-flip shutdown window
	// (worker Stop, Server.OnShutdown, http.Server.Shutdown all
	// share this budget). Zero falls back to 30s; negative is no window
	// (see PreStopDelay).
	ShutdownTimeout time.Duration

	// DrainReserve is the part of ShutdownTimeout kept back after the
	// long-lived streams are ended (Streams.DrainReserve): a stream that
	// claimed the soft phase (serverkit.Draining) may run until the deadline
	// minus this, and the rest of the teardown — workers, OnShutdown, the
	// telemetry flush — runs in what remains. Zero falls back to
	// DefaultDrainReserve (5s); never more than half the budget.
	DrainReserve time.Duration

	// RedialOnDrain names the Connect procedures ("/pkg.v1.Svc/Method", the
	// generated <Svc><Method>Procedure constant) or whole services
	// ("pkg.v1.Svc", the generated <Svc>Name constant) whose streams the
	// drain ends with Unavailable instead of OK — for a peer that redials on
	// Unavailable, such as a daemon holding a bidi stream. Empty: every
	// drained stream ends OK, with the x-forge-drained trailer. See
	// StreamDrainInterceptor.
	RedialOnDrain []string

	// ReadMaxBytes caps the size of a single Connect request payload.
	// Zero falls back to 4 MiB — but ONLY after Normalize has run. A
	// zero reaching connect.WithReadMaxBytes means UNLIMITED, so any
	// caller that reads this field before Run must Normalize first.
	ReadMaxBytes int

	// SendMaxBytes caps the size of a single Connect response payload.
	// Zero falls back to 4 MiB after Normalize. See ReadMaxBytes for
	// why an un-normalized read is dangerous.
	SendMaxBytes int

	// ReadinessTimeout bounds ALL of a /readyz request's dependency
	// checks together (not each one), so the endpoint's worst case stays
	// inside a kubelet probe's timeoutSeconds no matter how many checks
	// are registered. Zero falls back to 2s.
	ReadinessTimeout time.Duration

	// Probes are the paths the process answers its liveness and readiness
	// probes on — the boot probes, serverkit.Run's listener and a Probes
	// surface alike. Empty is DefaultLivenessPath / DefaultReadinessPath.
	// The scaffold projects them from the liveness_paths / readiness_paths
	// config fields, which the KCL lowering reads too, so the probe a pod
	// is given is the one its process serves.
	Probes ProbePaths

	// ReadHeaderTimeout bounds reading a request's headers (slowloris).
	// Zero falls back to 10s; negative disables it.
	ReadHeaderTimeout time.Duration

	// ReadTimeout bounds reading a whole request, body included — over
	// HTTP/2 it is a deadline on each stream's request body. So it caps how
	// long a client-streaming or bidirectional Connect/gRPC call may keep
	// sending: a server with long-lived client streams sets it negative.
	// Zero falls back to 30s; negative disables it.
	ReadTimeout time.Duration

	// IdleTimeout is how long a keep-alive connection may sit idle (HTTP/1.1
	// and HTTP/2). Zero falls back to 120s; negative disables it, which
	// leaves idle connections open until the client closes them.
	IdleTimeout time.Duration

	// HTTP2MaxConcurrentStreams caps the concurrent streams one HTTP/2
	// connection (TLS or h2c) may open. A client multiplexing many
	// long-lived streams over one connection needs it raised. Zero leaves
	// net/http's default (250 at the time of writing).
	HTTP2MaxConcurrentStreams int

	// WriteStallTimeout bounds how long ONE write to a response may stay
	// blocked on a client that is not reading, after which the response is
	// abandoned (see WriteStallGuard). It is not a cap on how long a response
	// may take: a stream that keeps moving bytes runs as long as it likes.
	// Zero falls back to DefaultWriteStallTimeout; negative disables the
	// guard. A handler that wants a whole-response cap sets one itself with
	// http.NewResponseController(w).SetWriteDeadline — it composes with this.
	WriteStallTimeout time.Duration

	// OperatorHealthProbeAddr is forwarded to Server.RunOperators
	// for projects (like cp-forge) that bind a /healthz + /readyz
	// listener inside the controller manager. Empty string leaves the
	// project's RunOperators to fall back to its own default.
	OperatorHealthProbeAddr string

	// FailurePolicy governs worker Start/RunContext errors and
	// RunOperators errors. Zero value is FailProcess (a component
	// failure terminates the process loudly); set Ignore to restore
	// log-and-continue. See the FailurePolicy doc.
	FailurePolicy FailurePolicy
}

type ConnectPolicy struct {
	// Name identifies the dependency in logs and in the boot /readyz body.
	// Default "database".
	Name string
	// Timeout is the TOTAL budget across all attempts. Default
	// DefaultDBConnectTimeout.
	Timeout time.Duration
	// AttemptTimeout bounds ONE attempt, so a blackholed host (a dropped
	// SYN never errors) costs one attempt's budget rather than the whole
	// total. Default 5s.
	AttemptTimeout time.Duration
	// InitialBackoff is the delay after the first failure; it doubles up to
	// MaxBackoff, with jitter. Defaults 500ms / 10s.
	InitialBackoff time.Duration
	MaxBackoff     time.Duration
	// LogEvery is the width of a log bucket: one WARN per bucket (the first
	// failure always logs), summarising the attempts inside it. Default 15s.
	LogEvery time.Duration
	// Logger receives the WARN/INFO lines. Nil uses slog.Default().
	Logger *slog.Logger
}

type ConnectTimeoutError struct {
	Name     string
	Elapsed  time.Duration
	Attempts int
	Class    string
	Last     error
}

type ContextWorker interface {
	Worker

	// RunContext runs the worker's main loop and returns when ctx is
	// done. See the interface doc for the full shutdown contract.
	RunContext(ctx context.Context) error
}

type DBPoolTuning struct {
	// MaxOpenConns caps total open connections. 0 = unlimited.
	MaxOpenConns int

	// MaxIdleConns caps idle connections. 0 = default (2).
	MaxIdleConns int

	// ConnMaxIdleTime is how long an idle connection survives before
	// being closed. Zero disables the limit.
	ConnMaxIdleTime time.Duration

	// ConnMaxLifetime is the absolute lifetime of any connection.
	// Zero disables the limit.
	ConnMaxLifetime time.Duration

	// SpareConns keeps this many connections dialled ahead of need, so
	// when the pool needs a new connection it takes a spare instead of
	// making the request wait for a dial (see spare_conns.go). Capped at
	// MaxOpenConns, and while that is set, spares are dialled only into the
	// room the pool's open connections leave under it. 0 = off,
	// database/sql's own behavior: dial on demand.
	SpareConns int
}

type Deadline = observe.Deadline

type DescriptorSource interface {
	RangeFiles(func(protoreflect.FileDescriptor) bool)
}

type DrainReport struct {
	// Ended counts the streams the soft phase ended at once: every stream
	// that had not claimed it, and every stream that arrived after the drain
	// began.
	Ended int
	// Claimed counts the streams the soft phase left running because they
	// asked to say goodbye (Draining, OnDrain).
	Claimed int
	// HardEnded counts the claimed streams still running at the deadline
	// minus DrainReserve, and so ended by the drain.
	HardEnded int
	// ConnsClosed counts the hijacked connections the drain closed for
	// handlers that ignored their ended context.
	ConnsClosed int
	// StillRunning counts the streams whose handlers had not returned when
	// the report was taken; after Drain, the ones the budget ran out on.
	StillRunning int
}

type Drainer struct {
	// PreStopDelay is how long the process keeps serving after readiness
	// flips. See Config.PreStopDelay.
	PreStopDelay time.Duration
	// ShutdownTimeout bounds every teardown step after the pre-stop pause.
	// See Config.ShutdownTimeout.
	ShutdownTimeout time.Duration
	// Logger receives the phase lines; nil is slog.Default().
	Logger *slog.Logger
	// Meter records the phases in forge.server.drain.duration; nil is the
	// global OpenTelemetry meter.
	Meter metric.Meter
	// contains filtered or unexported fields
}

type Edge struct {
	CORS            func(origins []string, allowCredentials bool) func(http.Handler) http.Handler
	SecurityHeaders func(production bool) func(http.Handler) http.Handler
	RequestID       func() func(http.Handler) http.Handler
	Outer           func(http.Handler) http.Handler
}

type FailurePolicy int

type FlowCheck struct {
	// Name labels the check in the /flow-health JSON (e.g. "daemon-flow").
	Name string
	// Check runs the assertion. It must NOT include per-entity / per-user
	// detail in the returned Summary — that's the public-status contract.
	Check func(ctx context.Context) FlowResult
}

type FlowResult struct {
	OK      bool
	Summary string
}

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

type ListenerConfig struct {
	// Addr is the address to bind (":8080", "127.0.0.1:0"). Required.
	Addr string

	// TLSCertPath and TLSKeyPath serve TLS when both are set. The pair is
	// loaded by Listen, before the address is bound: a missing or invalid
	// certificate fails boot, never a listener that already reported Ready.
	TLSCertPath string
	TLSKeyPath  string

	// ReadHeaderTimeout bounds reading a request's headers. Zero is 10s.
	ReadHeaderTimeout time.Duration
	// ReadTimeout bounds reading a whole request, body included — over
	// HTTP/2 each stream's request body, so a listener whose clients hold
	// long client or bidi streams sets it negative. Zero is 30s.
	ReadTimeout time.Duration
	// IdleTimeout is how long a keep-alive connection may sit idle. Zero is
	// 120s.
	IdleTimeout time.Duration
	// HTTP2MaxConcurrentStreams caps the streams one HTTP/2 connection may
	// open. Zero is net/http's default.
	HTTP2MaxConcurrentStreams int
	// WriteStallTimeout bounds one write blocked on a client that is not
	// reading (WriteStallGuard). Zero is DefaultWriteStallTimeout.
	WriteStallTimeout time.Duration

	// DrainReserve is the part of the drain budget kept back after the
	// long-lived streams are ended (Streams.DrainReserve). Zero is
	// DefaultDrainReserve.
	DrainReserve time.Duration
	// RedialOnDrain names the procedures or services whose drained streams
	// end Unavailable instead of OK (Streams.RedialOnDrain).
	RedialOnDrain []string
}

type ListenerDeps struct {
	// Config is the listener's own block: address, TLS, timeouts, drain.
	Config ListenerConfig
	// Chain is the interceptor chain every Connect route is built with, and
	// the audience every mounted service must declare. Required.
	Chain *Chain
	// Routes are what the listener serves. Required.
	Routes Routes
	// Logger receives the listener's lines and its drain phase; nil is
	// slog.Default().
	Logger *slog.Logger
	// Edge wraps the routes' handler — CORS, security headers, a request id.
	// The Front routes bypass it. nil is no edge.
	Edge func(http.Handler) http.Handler
	// Front are routes served IN FRONT of Edge and of the chain, by exact
	// pattern: probes and /metrics, which a kubelet or a scraper reaches
	// without CORS or credentials. "/" is not allowed: it is the routes'.
	Front map[string]http.Handler
	// REST serves a vanguard REST transcoder over the mounted services
	// (forge.yaml api.rest) in place of the bare Connect mux.
	REST bool
}

type Omit string

type Operator interface {
	Name() string
}

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

type ProbeListenerDeps struct {
	// Config is the listener's address, TLS and timeouts — the process's
	// server address (Config.Listener()), where a kubelet probes it.
	Config ListenerConfig
	// Probes is the surface it serves. Required.
	Probes *Probes
	// Logger is the listener's logger; nil is slog.Default().
	Logger *slog.Logger
}

type ProbePaths struct {
	// Live answers liveness: 200 "ok" while the process runs, booting
	// included. Empty is [DefaultLivenessPath].
	Live []string
	// Ready answers readiness: the boot probes' 503 until the server is
	// composed, then /readyz's drain gate and dependency checks. Empty is
	// [DefaultReadinessPath].
	Ready []string
}

type Probes struct {
	// Drainer is the readiness gate and the stop budget: readiness answers
	// 503 before Drainer.MarkReady and once its drain has begun. Required.
	Drainer *Drainer
	// Metrics is the /metrics handler (observe.Setup's); nil serves none.
	Metrics http.Handler
	// Timeout bounds all of one readiness request's checks together; zero
	// is the serverkit default.
	Timeout time.Duration
	// Logger receives check transitions; nil is slog.Default().
	Logger *slog.Logger
	// Paths are the liveness and readiness paths: the process's
	// Config.Probes, so the boot probes and the probe surface answer on the
	// same ones. Empty is /healthz and /readyz.
	Paths ProbePaths
	// contains filtered or unexported fields
}

type ReadyCheck struct {
	// Name identifies the dependency in the /readyz JSON ("database",
	// "cache", "queue"). It is the only per-check detail that goes out.
	Name string
	// Check probes the dependency. It receives a context already bounded
	// by Config.ReadinessTimeout and must respect it.
	Check func(ctx context.Context) error
}

type Routes interface {
	// Register mounts every route on mux, building each Connect handler with
	// opts — the listener's chain — and returns the fully qualified proto
	// service names it mounted ("acme.billing.v1.BillingService"), which the
	// listener checks against its chain's audience. Plain HTTP routes (a
	// websocket, a login callback) are mounted too and named nowhere.
	Register(mux *http.ServeMux, opts ...connect.HandlerOption) []string
}

type RoutesFunc func(mux *http.ServeMux, opts ...connect.HandlerOption) []string

type Server struct {
	// Handler is the fully-composed HTTP handler: the mux with all
	// services already mounted (their Connect interceptors already
	// applied via connect.HandlerOption at mount time), plus any
	// REST-transcoder swap already resolved by the caller, plus any
	// /metrics handle the caller mounted. serverkit wraps it with its
	// OWN edge (CORS/security/request-id from Config + the factory
	// fields below) and routes /healthz + /readyz to its own probes
	// IN FRONT of that edge, but never re-mounts services. Required.
	//
	// A composition root that uses the Mux ergonomics below need not set
	// Handler explicitly: when Handler is nil at Run time and Mux is
	// non-nil, Run uses Mux as the handler. Setting Handler is still the
	// way to install a REST-transcoder swap or any wrapper around the raw
	// mux — set Handler to the wrapped value after mounting.
	Handler http.Handler

	// Mux is the composition root's service mux — the *http.ServeMux that
	// mountkit.RegisterService (or this Server's Mount* helpers) mount
	// onto. It is OPTIONAL ergonomics: a composition root can `srv.Mux =
	// http.NewServeMux()`, mount services through Server.Mount (which both
	// registers on Mux AND records the proto service name for the
	// completeness check), and leave Handler nil — Run falls back to Mux.
	// When the caller needs to wrap the mux (REST swap, an outer handler)
	// it builds Mux, mounts, then sets Handler to the wrapped value; Mux
	// stays the mount target and the recorded-names set is unaffected.
	Mux *http.ServeMux

	// HandlerOpts is the shared []connect.HandlerOption (the interceptor
	// chain from observe.Chain wrapped via connect.WithInterceptors, plus
	// the ReadMaxBytes/SendMaxBytes payload limits) that every service's
	// Register call receives. Carried on the Server so the Mount helpers
	// can thread it through without the caller repeating it per service.
	// Callers that mount via mountkit.RegisterService directly pass it
	// themselves and may leave this nil.
	HandlerOpts []connect.HandlerOption

	// Chain is the interceptor chain the services were mounted with
	// (NewChain). Set, it does two things: the Mount helpers build each
	// service with its HandlerOptions when HandlerOpts is nil, and Run's
	// Listener checks every recorded service's declared
	// `(forge.v1.service).audience` against the chain's Authenticator and
	// refuses to serve a mismatch. nil — a Server mounted with hand-built
	// HandlerOpts — skips the audience check.
	Chain *Chain

	// Logger is the root logger the caller already built (the same one
	// it passed into bootstrap so mount-time logs and run-time logs
	// agree). When nil, serverkit builds one from Config (newLogger) and
	// SetDefaults it. Optional.
	Logger *slog.Logger

	// Workers / Operators are the already-constructed, already-selected
	// supervised components. Selection (the old names filter) happened
	// ABOVE serverkit: the caller passes exactly the workers/operators
	// this process should run. serverkit no longer filters by name.
	Workers   []Worker
	Operators []Operator

	// OnShutdown is the caller's teardown (closing the serving DB pool,
	// flushing app-owned buffers). Run calls it after in-flight HTTP has
	// drained and workers and operators have stopped, so nothing it closes
	// is still in use, and before the telemetry flush. Optional; nil is a
	// no-op.
	OnShutdown func(context.Context) error

	// RunOperators starts the controller-runtime manager and blocks
	// until ctx is done. serverkit calls it in a goroutine when
	// len(Operators) > 0, and on no other condition: the caller already
	// decided whether this process runs a manager by deciding whether to
	// populate Operators, and serverkit does not second-guess that from
	// the environment. Nil + non-empty Operators is a config error.
	// Optional when Operators is empty.
	RunOperators func(ctx context.Context, logger *slog.Logger, healthProbeAddr string) error

	// Edge factories: kept as fields (not pure Config) because the
	// concrete middleware still lives in the project's generated
	// pkg/middleware tree and serverkit must not import the project.
	// serverkit owns the GATING (driven by Config: CORSOrigins,
	// SecurityHeaders, Environment); these only supply the wrapper. All
	// optional — nil skips that edge layer.
	CORSMiddleware            func(origins []string, allowCredentials bool) func(http.Handler) http.Handler
	SecurityHeadersMiddleware func(production bool) func(http.Handler) http.Handler
	RequestIDMiddleware       func() func(http.Handler) http.Handler
	HTTPMiddleware            func(http.Handler) http.Handler

	// FlowChecks are the APP-FLOW health assertions this service exposes at
	// GET /flow-health. They are the readiness/liveness analogue for an
	// END-TO-END invariant only this service can assert (it holds the state
	// internally), e.g. "every Ready managed daemon is attached to the
	// gateway". serverkit runs every check on each /flow-health request and
	// returns 200 when ALL pass, 503 when ANY fails, plus a STATUS-ONLY JSON
	// aggregate (per-check name + ok + a terse count summary). It deliberately
	// exposes NO per-entity detail anonymously, so the endpoint is safe to
	// probe from `forge env smoke` (which just curls it) without leaking anything
	// sensitive — gate per-entity detail behind your own auth'd endpoint.
	//
	// Empty (the default) means no /flow-health is mounted, so existing
	// services are unaffected. See FlowCheck + AddFlowCheck.
	FlowChecks []FlowCheck

	// ReadyChecks are the DEPENDENCY probes GET /readyz runs on every
	// request — "can this replica serve right now", as opposed to
	// FlowChecks' "is my end-to-end invariant holding". Leaving this empty
	// makes /readyz report readiness purely on the listener being bound,
	// which is what let a replica with an unreachable database advertise
	// itself as Ready through an entire rollout. Register the pool with
	// AddReadyCheck(DBReadyCheck("database", db)). See readiness.go.
	ReadyChecks []ReadyCheck
	// contains filtered or unexported fields
}

type SlowCall = observe.SlowCall

type Streams struct {
	// DrainReserve is how much of the shutdown budget Drain keeps back after
	// it ends the streams that are still open: streams that claimed the soft
	// phase run until the deadline minus this. Zero means
	// DefaultDrainReserve; it is never more than half the budget left when
	// Drain starts, so a soft phase always exists.
	DrainReserve time.Duration

	// RedialOnDrain names the Connect procedures ("/pkg.v1.Svc/Method") or
	// whole services ("pkg.v1.Svc") whose streams the drain ends with
	// Unavailable instead of OK — for peers that redial on Unavailable. See
	// StreamDrainInterceptor for the client contract.
	RedialOnDrain []string

	// Logger receives the "drain: listener drained" line DrainHTTP writes
	// for this listener; nil is slog.Default().
	Logger *slog.Logger
	// Meter records that phase (listener) in forge.server.drain.duration;
	// nil is the global OpenTelemetry meter.
	Meter metric.Meter
	// contains filtered or unexported fields
}

type Worker interface {
	// Name is the worker's stable identifier — used in log lines and
	// the Server.Workers iteration order.
	Name() string

	// Start runs the worker's main loop. It must return when ctx is
	// done. serverkit calls Start once per worker in its own goroutine
	// and never restarts.
	Start(ctx context.Context) error

	// Stop performs graceful shutdown bounded by the supplied ctx
	// (typically Config.ShutdownTimeout). serverkit calls Stop after
	// the worker's Start ctx has been cancelled and the supervisor
	// WaitGroup has drained.
	Stop(ctx context.Context) error
}