serverkit

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

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. Operators tune this to match their load-balancer probe
	// interval — too short causes brief 502s on rollout.
	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.
	ShutdownTimeout time.Duration

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

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

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

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 Operator interface {
	Name() string
}

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

	// 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 runs during graceful shutdown after workers stop and
	// before the http.Server shuts down — the old Application.Shutdown
	// plus (folded in by the caller) the OTel 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 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
}