Crate chio_http_serve 

Graceful shutdown, connection drain, and server hygiene for Chio HTTP services.

Every Chio process that binds an axum::serve listener shares the same three obligations when the platform stops it (SIGTERM on a deploy, scale event, or node rotation):

1. Notice the stop signal instead of dying on the runtime default action.
2. Stop accepting, let in-flight requests finish, then exit, all inside a bounded window so a stuck request cannot hold the process open forever.
3. Refuse abusive load (oversized bodies, slow requests, connection floods) with an explicit denial rather than unbounded resource growth.

This crate centralizes those obligations so the serve sites converge on one implementation instead of drifting apart:

• ShutdownController installs a single signal handler and fans the result out over a tokio::sync::watch channel that the serve loop and every cooperating background task observe.
• apply_server_hygiene wraps a Router with a request timeout, a global concurrency limit fronted by load shedding, and an optional body-size cap.
• MaxConnListener caps the number of simultaneously accepted connections with back-pressure at the accept loop.
• run_until_drained runs the serve future, bounds only the post-signal drain (never the healthy uptime), and then runs a flush hook so a store with a queued write is either made durable or surfaced as a loud error.

The posture is fail-closed throughout. A signal handler that cannot be installed logs and degrades to the platform default rather than crash-looping at startup, and each hygiene limit denies (413 / 408 / 503) rather than accepting work it cannot bound.

Structs

CappedPeerAddr

Peer socket address for a connection accepted through a MaxConnListener over a TcpListener.

MaxConnListener

Wrap any axum::serve::Listener with a hard cap on concurrent connections.

PermittedIo

Connection IO that carries the connection-cap permit alongside it, so the permit is released exactly when the connection is dropped. The read and write halves forward to the wrapped IO unchanged.

ServeHygieneConfig

Bounds and hygiene knobs for one serve site. The Default is a conservative, fail-closed posture: a request that exceeds a bound is denied, never queued.

ShutdownController

Owns the shutdown watch channel that fans one stop signal out to the serve loop and every cooperating background task. The receivers it hands out are cheap to clone.

Enums

DrainOutcome

How a bounded drain finished.

ServeError

Terminal error from a bounded serve. Either variant is a non-zero process exit; neither is ever swallowed.

Constants

DEFAULT_DRAIN_TIMEOUT

Wall-clock ceiling on the drain: how long to wait for in-flight requests to finish after the listener stops accepting. Operators must size the unit TimeoutStopSec at least this high plus a flush margin.

DEFAULT_MAX_CONCURRENT_REQUESTS

Maximum concurrent in-flight requests before surplus load sheds with 503.

DEFAULT_MAX_CONNECTIONS

Maximum simultaneously accepted TCP connections.

DEFAULT_REQUEST_TIMEOUT

Per-request processing ceiling before the request is denied with 408.

Functions

apply_server_hygiene

Wrap router with the configured request timeout, concurrency limit fronted by load shedding, and optional body-size cap.

run_until_drained

Run a graceful serve future to completion, bounding only the post-signal drain, then run a flush hook.

shutdown_signal

Resolve on the first SIGTERM (unix) or Ctrl-C / SIGINT (all platforms).