Struct App 

pub struct App { /* private fields */ }

An HTTP application: routes, state, middleware, lifespan and metadata.

Implementations

impl App

pub fn new() -> Self

Create an empty application.

pub fn title(self, title: impl Into<String>) -> Self

Set the API title.

pub fn version(self, version: impl Into<String>) -> Self

Set the API version.

pub fn description(self, description: impl Into<String>) -> Self

Set the API description.

pub fn docs(self, docs: DocsConfig) -> Self

Configure documentation endpoints.

pub fn meta(&self) -> &AppMeta

The application metadata.

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

Register methods at path (use {param} for path parameters).

pub fn routes(self, routes: impl IntoIterator<Item = Route>) -> Self

Register routes produced by route macros (see routes![]).

pub fn mount(self, prefix: &str, app: App) -> Self

Mount app under prefix (e.g. /api/v1); / merges its routes into this app. See the module docs.

pub fn nest(self, prefix: &str, app: App) -> Self

Alias of App::mount.

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

Make state available to handlers through State<T>.

Applies to every route of this app regardless of call order.

pub fn database(self, alias: impl Into<String>, db: Db) -> Self

Register db under alias ("default", "replica", …).

Every registered database is available to handlers as State<Databases>; a router set with App::databases is kept.

pub fn databases(self, databases: Databases) -> Self

Replace the whole database registry (aliases and router).

pub fn database_registry(&self) -> Option<&Databases>

The registered databases, if any.

pub fn openapi(&self) -> Result<OpenApi, OpenApiError>

Generate the OpenAPI 3.1 document for this app and its mounts.

Errors

Returns OpenApiError on duplicate operations/ids or schema name conflicts.

pub fn into_router_service(self) -> Result<RouterService, ServerError>

Convert into an in-process tower::Service (used by the testkit). Lifespan hooks are not run.

Errors

Returns ServerError::Configuration if the app is misconfigured.

pub fn into_service_with_lifespan( self, ) -> Result<(RouterService, Lifespan), ServerError>

Like App::into_router_service, but also returns the Lifespan so the caller can run startup and shutdown hooks around the service without binding a socket (used by the testkit).

Errors

Returns ServerError::Configuration if the app is misconfigured.

pub async fn run(self, addr: &str) -> Result<(), ServerError>

Serve until Ctrl-C or Unix SIGTERM, then drain and clean up resources.

Args: addr: Address to bind.

Returns: Success after shutdown and resource cleanup.

Errors

Configuration, startup, bind, serving or shutdown errors.

pub async fn run_until<F>( self, addr: &str, shutdown: F, ) -> Result<(), ServerError>

where F: Future<Output = ()> + Send + 'static,

Serve until a caller-supplied shutdown future completes.

Startup cancellation and bind failure clean initialized resources. HTTP draining and teardown share one deadline. Connection, stream and WebSocket workers are cancelled before resource teardown.

Args: addr: Address to bind. shutdown: Future requesting graceful termination.

Returns: Success after serving and cleanup finish.

Errors

Configuration/startup/I/O errors or exceeded shutdown deadline.

impl App

pub fn background_tasks(self, limits: BackgroundTaskLimits) -> Self

Configure admission and execution limits for this app’s task queue.

Args: limits: Positive limits within Tokio semaphore capacity.

Returns: Configured app; invalid limits become a configuration error.

impl App

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

Share value with every request of this app (and its mounts). See the module docs.

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

Like App::provide for a value that is already shared, so the caller can keep a handle to it.

pub fn override_dependency<T, F, Fut>(self, f: F) -> Self

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

Replace T::resolve with f (also for nested resolution). f gets an owned RequestHead because a borrowed request cannot cross the returned future.

pub fn override_value<T: Dependency + Clone>(self, value: T) -> Self

Replace T::resolve with a clone of value.

pub fn dependency<T: Dependency>(self) -> Self

Resolve T before every routed request; its error short-circuits. The value stays cached, so handlers asking for Depends<T> reuse it.

impl App

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

Set the total graceful-shutdown budget, including resource teardown.

Args: budget: Positive, representable duration (default: 30 seconds).

Returns: The configured application; invalid budgets fail validation.

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

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

Run hook at startup (before the socket is bound).

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

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

Run hook at shutdown (hooks run in reverse registration order).

pub fn lifespan_resource<T, F, Fut, C>(self, init: F) -> Self

where T: Send + Sync + 'static, F: FnOnce() -> Fut + Send + 'static, Fut: Future<Output = Result<(T, C), ApiError>> + Send + 'static, C: Future<Output = Result<(), ApiError>> + Send + 'static,

Create a resource at startup and tear it down at shutdown.

init returns the value and a teardown future (which may capture clones of whatever it needs to close). Handlers receive the value via Resource<T>. Resources are torn down in reverse registration order.

impl App

pub fn layer<L>(self, layer: L) -> Self

where L: Layer<BoxService> + Clone + Send + Sync + 'static, L::Service: Service<Request, Response = Response, Error = Infallible> + Clone + Send + Sync + 'static, <L::Service as Service<Request>>::Future: Send + 'static,

Wrap the application in layer. See the module docs for the ordering rules.

pub fn cors(self, cors: Cors) -> Self

Add Cors middleware.

pub fn compression(self, compression: Compression) -> Self

Add Compression middleware.

pub fn csrf_origin(self, csrf: CsrfOrigin) -> Self

Add CsrfOrigin middleware.

pub fn trusted_hosts(self, hosts: TrustedHosts) -> Self

Add TrustedHosts middleware.

pub fn https_redirect(self, redirect: HttpsRedirect) -> Self

Add HttpsRedirect middleware.

pub fn request_id(self) -> Self

Add request-id middleware with default settings.

pub fn request_logging(self) -> Self

Add RequestLogging middleware.

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

Add a Timeout (504 by default).

pub fn concurrency_limit(self, max: usize) -> Self

Add a ConcurrencyLimit.

pub fn body_limit(self, max_bytes: usize) -> Self

Add a BodyLimit of max_bytes.

pub fn rate_limit(self, limit: RateLimit) -> Self

Add a RateLimit.

impl App

pub fn server_limits(self, limits: ServerLimits) -> Self

Configure bounded transport admission before binding the server.

Args: limits: Accepted socket and per-connection HTTP/2 limits.

Returns: This application; invalid bounds become configuration errors.

impl App

pub fn static_files(self, prefix: &str, dir: impl Into<PathBuf>) -> Self

Serve files from dir under URL prefix (for example /assets).

The mount is not documented in OpenAPI. Path traversal (.. segments) is rejected by tower-http’s ServeDir. A root prefix (/ or empty) serves dir as the fallback for every path no route matches.

pub fn spa(self, prefix: &str, dir: impl Into<PathBuf>) -> Self

Serve a single-page application from dir under prefix (/ for the whole site): files as they are, and dir/index.html for browser navigations to any other path below prefix, so client side routes (/app/settings) load the app.

Explicit routes still win. The fallback applies only to GET and HEAD requests accepting text/html whose last path segment has no extension; a missing asset, an API-style request or a missing index.html answer with the 404 problem document, and other methods with 405. Paths are resolved inside the canonical dir (no .., encoded or not, and no symbolic link leading out). The mount is not documented in OpenAPI.

Trait Implementations

impl Debug for App

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for App

fn default() -> Self

Returns the “default value” for a type.