Struct App 

pub struct App { /* private fields */ }

The application builder. Generated app/src/main.rs is exactly this: provide app-level deps, mount modules, serve.

Implementations

impl App

pub fn new() -> Self

pub fn extend<E: Extension>(self, extension: E) -> App

Attach an extension: App::new().extend(Db::from_env().await?).

pub fn security_headers(self, on: bool) -> Self

Secure-by-default headers on every response (spec §4.4). Opting out must be explicit — that is the contract.

pub fn cors(self, config: CorsConfig) -> Self

Install a CORS policy (spec §v2.2). Preflight OPTIONS is answered before routing; actual cross-origin responses (including 404/405) are decorated with the CORS headers. allow_credentials(true) with CorsOrigins::any() is a build error.

pub fn handler_timeout(self, budget: Duration) -> Self

Per-request handler time budget (default 30s — spec §4.4). Exceeding it returns 503 JC0503 without killing the connection or the server.

pub fn body_read_timeout(self, budget: Duration) -> Self

Time budget for reading a request body (default 30s — spec §4.4).

pub fn write_stall_timeout(self, budget: Duration) -> Self

Maximum time a connection’s socket write may stall (client not reading) before the connection is dropped. Protects streaming downloads — and all responses — from slow-reader clients. Default 30s.

pub fn route(self, path: &str, methods: MethodRouter) -> Self

App-level route (prefer modules; this exists for tiny services and tests).

pub fn mount(self, prefix: &str, module: Module) -> Self

Mount a module at a prefix (spec §4.2).

pub fn provide<T: Send + Sync + 'static>(self, value: T) -> Self

App-level singleton value dependency.

pub fn provide_dep<F, Args, T>(self, factory: F) -> Self

where F: DepFactory<Args, T>, T: Send + Sync + 'static,

App-level async factory dependency (request scope).

pub fn middleware<M: Middleware>(self, mw: M) -> Self

App-level middleware — outermost ring of every route’s chain.

pub fn on_serve<F, Fut>(self, name: &'static str, f: F) -> App

where F: FnOnce(TaskContext, Receiver<bool>) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send + 'static,

Register a background task that runs for the lifetime of serve.

The task is launched once when serving starts, receives a TaskContext (resolving app-level deps registered via provide/provide_dep) and a watch::Receiver<bool> that flips to true when shutdown begins. It runs under the same drain governance as connections: shutdown gives it the 10s drain cap to finish before the server aborts remaining work.

Background tasks run ONLY under serve — into_test ignores them, so drive the task’s logic directly in tests rather than relying on it firing. The name is retained for future observability.

pub fn build(self) -> Result<BuiltApp>

Flatten modules, validate the route table, freeze the dispatch trie. All conflicts surface HERE — before serving (spec §4.1 “fail loud”).

pub async fn serve(self) -> Result<()>

Bind from config and serve until Ctrl-C, then drain gracefully. Address: JERRYCAN_ADDR env var, default 127.0.0.1:8000. (Full layered config lands in Phase 1; the env-var layer is the contract that already works.)

pub async fn serve_with(self, listener: TcpListener) -> Result<()>

Serve on an existing listener forever (tests, port 0, socket activation).

pub async fn serve_with_shutdown( self, listener: TcpListener, shutdown: impl Future<Output = ()> + Send, ) -> Result<()>

The serve engine: accept until shutdown resolves, then stop accepting, drain in-flight connections (10s cap), and return.

impl App

pub fn into_test(self) -> TestApp

Build for testing. Panics on build errors — a test should fail loudly.

Swaps the default real Clock for a controllable Clock::test via the override seam (overrides outrank the app’s Clock::system singleton) and keeps a handle on the same clock — TestApp::clock returns it, so advance/set move the very clock handlers resolve.

Trait Implementations

impl Default for App

fn default() -> Self

Returns the “default value” for a type.