Struct App 

pub struct App { /* private fields */ }

The application builder.

App collects application state, routers, and optional OpenAPI configuration, then either finalizes into an AppInner via App::build or starts serving via App::serve.

App is deliberately not generic over its state type: state is stored in a type-erased StateMap, which is what lets router modules be defined without any knowledge of the concrete state type.

Implementations

impl App

pub fn new() -> Self

Creates an empty application.

pub fn state<S: Send + Sync + 'static>(self, state: S) -> Self

Registers an application state value, retrievable via the State extractor.

pub fn logger(self, config: LoggerConfig) -> Self

Configures logging. Without this, logging is on by default with sensible settings (a developer console on a terminal, JSON otherwise; level from RUST_LOG or info).

pub fn cache(self, cache: Cache) -> Self

Enables caching, making the Cache injectable into handlers and services.

Pass a configured cache, for example Cache::in_memory() for the default in-memory store. Without this call, injecting a Cache fails.

pub fn throttle(self, throttle: Throttle) -> Self

Enables rate limiting, defining the policies routes can apply with the throttle attribute and (optionally) a global default.

App::new().throttle(
    Throttle::new()
        .policy("default", 100, 60)
        .policy("strict", 5, 60)
        .default("default"),
);

pub fn include_router(self, router: Router) -> Self

Mounts a router’s routes on the application.

pub fn include(self, route: impl FnOnce() -> Route) -> Self

Mounts a single route, given the route factory generated for a handler.

A #[get] / #[post] / #[sse] / #[websocket] handler named handler generates a handler() route factory, so App::new().include(handler) registers it directly without building a Router.

pub fn openapi<P: OpenApiProvider>(self, provider: P) -> Self

Configures OpenAPI document generation and the documentation UI.

pub fn asyncapi<P: AsyncApiProvider>(self, provider: P) -> Self

Configures AsyncAPI document generation for the SSE/WebSocket channels.

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

Registers a middleware layer.

Layers run in registration order, outermost first. Some middlewares may only be registered once; see DuplicatePolicy.

pub fn lifespan<L: Lifespan>(self) -> Self

Registers a lifespan: a resource container with typed startup/shutdown.

Lifespans start in registration order and stop in reverse order. Their resources are registered for injection. Using a lifespan together with on_startup or on_shutdown is a configuration error.

pub fn on_startup<F, Fut>(self, hook: F) -> Self

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<()>> + Send + 'static,

Registers a startup hook (for apps that do not use a lifespan).

pub fn on_shutdown<F, Fut>(self, hook: F) -> Self

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<()>> + Send + 'static,

Registers a shutdown hook (for apps that do not use a lifespan).

pub fn on_ready<F, Fut>(self, hook: F) -> Self

where F: Fn(ReadyContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<()>> + Send + 'static,

Registers a hook that runs once the listener has bound.

Allowed in both lifespan and event-hook modes.

pub fn on_request<F, Fut>(self, hook: F) -> Self

where F: Fn(RequestEvent) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers an observe-only hook that runs when a request arrives.

Hooks run in registration order, before the middleware chain, and cannot alter the response. Use them for logging, metrics, or tracing.

pub fn on_response<F, Fut>(self, hook: F) -> Self

where F: Fn(ResponseEvent) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers an observe-only hook that runs once a response is ready.

Hooks run in registration order, after the middleware chain, and observe the final status and elapsed time.

pub fn on_error<F, Fut>(self, hook: F) -> Self

where F: Fn(ErrorEvent) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers an observe-only hook that runs for a non-validation error.

Validation failures (422) go to on_validation_error instead; every other error fires this hook.

pub fn on_validation_error<F, Fut>(self, hook: F) -> Self

where F: Fn(ValidationErrorEvent) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers an observe-only hook that runs for a request-body validation failure (422).

pub fn on_panic<F, Fut>(self, hook: F) -> Self

where F: Fn(PanicEvent) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers an observe-only hook that runs when a handler panic is caught.

Has no effect unless the panic boundary is enabled with catch_panics.

pub fn websocket_config(self, config: WebSocketConfig) -> Self

Sets default WebSocket limits and timeouts for every #[websocket] route.

A route’s own #[websocket(...)] limits override these defaults.

pub fn max_sse_connections(self, limit: usize) -> Self

Caps the number of concurrent Server-Sent Events streams the app will serve.

Each SSE connection holds a pinned stream and timers for its whole lifetime (often hours), so an unbounded count can exhaust memory. Once the cap is reached, further #[sse] requests are rejected with 503 Service Unavailable until a stream ends. With no cap set, SSE streams are unbounded.

pub fn idle_timeout(self, timeout: Duration) -> Self

Closes a connection after this long with no read or write activity.

Bounds slow or abandoned connections (and zombie keep-alive sockets). It is off by default, because a legitimately idle long-lived connection — an open WebSocket or a quiet Server-Sent Events stream — is normal; enable it only when your routes do not rely on long-lived idle connections, or set it comfortably above your SSE heartbeat interval.

pub fn reuse_port(self, enabled: bool) -> Self

Binds the listening socket with SO_REUSEPORT (Unix), so several processes or instances can listen on the same address and the kernel load-balances new connections across them.

Has no effect on non-Unix platforms. Off by default.

pub fn max_request_body_size(self, bytes: usize) -> Self

Sets the maximum size, in bytes, of a buffered request body.

Applies to the JSON, Valid<T>, and urlencoded Form<T> body extractors, which enforce the cap incrementally as the body arrives (an oversized body is rejected with 400 before it is fully buffered). Multipart uploads have their own UploadConfig limits. Defaults to MAX_BODY_BYTES (2 MiB).

pub fn header_read_timeout(self, timeout: Duration) -> Self

Sets how long a client may take to send the complete request head (request line + headers) after its connection is accepted.

This bounds slowloris-style attacks where a client opens a connection and dribbles header bytes to tie up a worker. Defaults to DEFAULT_HEADER_READ_TIMEOUT (30s); pass a longer duration to relax it. Applies to HTTP/1 connections.

pub fn without_header_read_timeout(self) -> Self

Removes the request-head read deadline, letting a client take unlimited time to send its headers. Only do this behind a trusted proxy that already bounds slow clients.

pub fn http1(self, config: Http1Config) -> Self

Tunes HTTP/1 behavior (keep-alive, header count) for every connection.

pub fn http2(self, config: Http2Config) -> Self

Tunes HTTP/2 behavior (stream limits, keep-alive, flow control) for every connection. HTTP/2 is served automatically over a plaintext upgrade or over TLS via ALPN.

pub fn on_ws_connect<F, Fut>(self, hook: F) -> Self

where F: Fn(WsConnectInfo) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers an observe-only hook that runs when a WebSocket opens.

pub fn on_ws_disconnect<F, Fut>(self, hook: F) -> Self

where F: Fn(WsDisconnectInfo) -> Fut + Send + Sync + 'static, Fut: Future<Output = ()> + Send + 'static,

Registers an observe-only hook that runs when a WebSocket closes.

The event carries how long the connection was open and the close code.

pub fn upload_config(self, config: UploadConfig) -> Self

Sets default multipart upload limits for every form/file route.

A route’s own #[post("/p", upload(...))] limits override these defaults.

pub fn catch_panics(self) -> Self

Enables the panic boundary: a panic in a handler is caught and turned into a 500 response instead of dropping the connection.

Enabled by default. A caught panic fires the on_panic hooks. The boundary has no effect when the process is built with panic = "abort".

pub fn propagate_panics(self) -> Self

Disables the panic boundary: handler panics propagate and tear down the request task instead of becoming a 500 response.

pub fn exception_handler<E, F, Fut>(self, handler: F) -> Self

where E: Error + Send + Sync + 'static, F: Fn(E, ErrorContext) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Registers a handler that maps a typed error E into a response.

When an error carries a source of type E (for example one produced by a #[derive(AppError)] type via ?), the registered handler receives the recovered value and produces the response. Registering a handler for a type again replaces the previous one.

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

Finalizes the application into its request-handling core.

Routers are flattened into a single route table, OpenAPI documentation routes (if configured) are appended, and a Matcher is compiled.

Errors

Returns an error if the route table contains an invalid or duplicate path.

pub async fn serve(self, addr: impl AsRef<str>) -> Result<()>

Runs the application lifecycle and serves on addr until a shutdown signal.

Listens for SIGINT (Ctrl-C) and, on Unix, SIGTERM. The lifecycle runs in order: startup (lifespans or on_startup hooks), bind, on_ready hooks, the accept loop, drain, then shutdown (lifespans in reverse, or on_shutdown hooks).

Errors

Returns an error for a lifecycle misconfiguration, a failed startup, or a bind failure.

pub async fn serve_with_shutdown<S>( self, addr: impl AsRef<str>, shutdown: S, ) -> Result<()>

where S: Future<Output = ()>,

Runs the lifecycle, stopping the accept loop when shutdown resolves.

Like serve but driven by a caller-supplied future instead of SIGINT/SIGTERM, for custom graceful shutdown (and for tests).

pub async fn serve_unix(self, path: impl AsRef<Path>) -> Result<()>

Serves over a Unix-domain socket at path, until a SIGINT/SIGTERM.

Useful behind a reverse proxy on the same host. A stale socket file at path is removed before binding. Unix only.

pub async fn serve_unix_with_shutdown<S>( self, path: impl AsRef<Path>, shutdown: S, ) -> Result<()>

where S: Future<Output = ()>,

Serves over a Unix-domain socket at path, stopping when shutdown resolves. Unix only.

pub async fn build_test(self) -> Result<TestApp>

Builds the application for in-process testing.

Runs the startup phase (lifespans or on_startup hooks) and finalizes the app without binding a socket, returning a TestApp that the TestClient drives. The on_ready hooks are not run, since there is no bound address.

Trait Implementations

impl Default for App

fn default() -> Self

Returns the “default value” for a type.