The server's own settings -- the values the Application and runServer need that the composition-root Env does not carry: the listen port and the served mount bindings. Backend selection is a composition-root concern; this is the minimal shape the web layer needs to route. The request-body cap is not here: it is a route concern, enforced by the only body-consuming route (publish) against its own pubMaxRequestBytes.

Build a ServerConfig over the given mount bindings, taking the default listen port (defaultPort).

The composition root supplies the bindings -- each a mount's complete ecosystem wiring -- and overrides the port by record update where a deployment needs to. There is no built-in mount: an ecosystem is served only once its binding is passed here, so the web layer carries no ecosystem of its own.

The conventional npm proxy listen port (4873), the mkServerConfig default.

Build the proxy's WAI Application over a ServerConfig and the composition-root Env, with the middleware stack composed around it.

The bare app dispatches a request: a control-plane health probe (/livez / /readyz) is answered at the top level; otherwise the leading path segment is matched to a mount, the prefix stripped, and the remainder classified and rendered. The returned Application has the middleware applied (body cap, client-IP recovery, timeout).

Build the proxy Application with the OpenTelemetry server-span middleware wrapped outermost around application, so one server span covers the whole request (the other middlewares included). When telemetry is disabled the wrapper is id, so this is exactly application -- additive and inert off (see Ecluse.Runtime.Telemetry.Tracing). runServer serves through this; a caller embedding the proxy that wants the request trace builds its application here rather than through the bare application.

Serve the proxy's HTTP front door: allocate the launch's live DrainSignal, build the Application by handing the supplied builder a ServerConfig whose scDrain is that signal, and start warp on the config's port with it. The ServerConfig -- in particular its mount bindings (scMounts), each a mount's complete ecosystem wiring -- is supplied by the composition root, which is where the served ecosystems are mounted (see Ecluse).

Graceful shutdown. The fresh live DrainSignal allocated per launch is wired into both the request path and the warp shutdown handler: the Application builder is invoked with a ServerConfig carrying that signal, so the readiness probe and the going-away middleware read the very drain the handler raises. On SIGTERM or SIGINT the handler raises the drain -- so the readiness probe begins failing and responses gain Connection: close -- then closes the listen socket, which puts warp into graceful-shutdown mode: it stops accepting new connections and waits for in-flight requests and in-progress artifact streams to finish before the process exits, bounded by scDrainTimeout. The handler is a CatchOnce, so a second signal during the drain hard-stops the server rather than being swallowed.

Local-dev quit key. The whole run is wrapped in withInteractiveHalt, which -- only when attached to an interactive terminal -- arms a watcher that forces an immediate halt on Ctrl-D (end of standard input), bypassing the drain like a second Ctrl-C. Outside a TTY (production) no watcher is installed and this changes nothing.

Race a server arm (the first argument) against a never-returning background loop (the second): the shutdown shape the single-process composition roots share -- the proxy racing its HTTP server against the mirror worker, and the pilot racing its probe server against the OSV export loop.

Choosing race_ over concurrently_ is the shutdown invariant. The background loop never returns, so a concurrently_ would keep waiting on it after the server has gracefully drained and returned, leaving the surrounding telemetry and resource brackets un-unwound: no exporter flush, the process hanging until a second signal or the orchestrator's kill. race_ lets the server's graceful return cancel the loop and unwind those brackets (flush and exit cleanly), while a fault thrown by either arm still propagates (race_ re-raises it) so a genuine failure fails the process up rather than being swallowed.

The control-plane health probes, answered above any mount: /livez from the injected liveness check (the worker-heartbeat arm folded in by the caller), /readyz from the drain signal ANDed with the composition root's startup gate, and any other unmounted path as the neutral 404.

The typed request perimeter over one effectful route: run the handler with a commit-tracking respond, catching only synchronous escapes (asynchronous cancellation is not caught and tears the request down like any thread). The handlers report every routine failure as a value, so what arrives here is an escape from some dependency's typed contract.

Pre-commit, the escape is classified (classifyEscape), handed to the injected observation channel (the composition wires the bounded ecluse.serve.perimeter.faults metric and the audit log line), and answered with the route's declared neutral 500 -- no fault detail ever reaches the client. Post-commit -- the wrapped respond has already begun the response -- there is no second response to give: the escape rethrows, warp tears the connection down, and the scOnException hook logs it. Exported for its spec; serve wires it per request.

The shared shutdown-drain flag the front door observes during a graceful rollover, as a small handle (a reader plus a one-way raise) rather than a bare TVar -- so the same field can hold either a live, flip-once signal (newDrainSignal) or the inert neverDraining constant the socket-free tests assemble against, and nothing downstream can lower it back. It is raised once, on a shutdown signal, and read on every request by the readiness probe and the going-away middleware.

Allocate a live, lowered shutdown-drain signal backed by a TVar. runWarp allocates one per launch, hands it to the application builder through the ServerConfig it passes, and flips it from the signal handler, so the readiness probe and the going-away middleware read the very same signal the instant the handler raises it.

The inert drain signal: permanently lowered, raising it is a no-op. The mkServerConfig default, so an application assembled for a socket-free test (and one driven without ever entering shutdown) reports ready and adds no going-away header. A real launch overrides it with newDrainSignal in runWarp.

Raise a drain signal -- the one-way transition into draining. Idempotent.

Read whether a drain signal is raised.

The bound on the graceful drain: how many seconds the server waits for in-flight requests and in-progress artifact streams to finish after it stops accepting new connections, before the process exits regardless. A newtype so a raw seconds count is not mistaken for some other Int, and so a non-positive value cannot be passed where a positive timeout is meant (see runWarp).

The default graceful-drain bound: 30 seconds. Long enough for an in-flight metadata fetch or a moderate artifact stream to complete during a rolling deploy, short enough that a stuck request cannot pin the old instance indefinitely.

The local-development immediate-halt wiring, as three injection points so its logic is exercised without a real terminal. It exists only to give an interactive session a "quit now" key: when the server is attached to a TTY, closing standard input (Ctrl-D) forces an immediate process exit, aborting any in-progress drain -- the same hard-stop a second Ctrl-C gives, but on the dev's deliberate signal.

It is inert outside an interactive terminal: in production standard input is a non-TTY or closed, haltOnInteractive returns False, and no watcher is installed, so the signal-driven graceful lifecycle is completely untouched. The TTY guard is what enforces that zero-production-impact contract (see withInteractiveHalt).

The real local-dev halt: armed only when standard input is a terminal (hIsTerminalDevice), fired by end-of-input on standard input (Ctrl-D), and halting via exitImmediately -- an immediate _exit that bypasses the graceful drain, mirroring a second Ctrl-C. The exit status (130) is the conventional "terminated from the terminal" code.

Run an action with the local-dev immediate-halt watcher armed __only when interactive__. If haltOnInteractive is True, a watcher runs alongside the action for exactly its lifetime (withAsync, so it is torn down when the action returns or is cancelled -- it never lingers); the watcher blocks on awaitHaltSignal and, when that returns, runs halt. If False -- the production case -- the action runs alone, with no watcher and no extra thread, so nothing about the graceful lifecycle changes.

The cross-cutting middleware stack composed around the proxy Application: correct client-IP recovery behind a load balancer (X-Forwarded-For / X-Real-IP), and a per-request timeout. The pieces live in Ecluse.Runtime.Server.Middleware; this composes them over the ServerConfig.

The request-body cap is not a middleware. Only one route (publish) consumes a request body, and it bounds it at the source as a value: a declared Content-Length over the cap fails closed before a byte is read, and a chunked body is bounded by a counted read (boundedRead), each answered as the route's own 413. A body-cap middleware would instead have to wrap the reader and throw across the request perimeter (untracked control flow), so the bound lives at the read site (Publish) rather than here.

A third middleware, the going-away header, is active only during a graceful drain: while the ServerConfig's DrainSignal is raised it stamps Connection: close on every response so an HTTP/1.1 keep-alive pool (a client's, or a service mesh's connection pool) does not reuse a socket on an instance that is shutting down -- the cause of the 503-on-rollover this guards against (see docs/architecture/web-layer.md → "Graceful shutdown").

Two wai-extra middlewares are deliberately not used. Autohead answers a HEAD by running the GET handler and discarding the body, which on a tarball route would open the upstream and stream a whole artifact to nowhere; instead a HEAD on the tarball or packument route is handled explicitly (in serve), gating exactly as the GET path does but suppressing the body -- the tarball probing the upstream as a HEAD so a bodiless HEAD can never trigger a full-artifact upstream fetch, the packument emitting the same status and headers as the GET with the locally-built body withheld. Gzip would re-compress already compressed artifacts and fight the streaming backpressure the serve path relies on.