Struct AppBuilder 

pub struct AppBuilder { /* private fields */ }

Builder for constructing an App.

Use this to configure routes, middleware, and shared state before building the final application.

Example

let app = App::builder()
    .config(AppConfig::new().name("My API"))
    .state(DatabasePool::new())
    .middleware(LoggingMiddleware::new())
    .on_startup(|| {
        println!("Server starting...");
        Ok(())
    })
    .on_shutdown(|| {
        println!("Server stopping...");
    })
    .route("/", Method::Get, index_handler)
    .route("/items", Method::Get, list_items)
    .route("/items", Method::Post, create_item)
    .route("/items/{id}", Method::Get, get_item)
    .build();

Implementations

impl AppBuilder

pub fn new() -> Self

Creates a new application builder.

pub fn config(self, config: AppConfig) -> Self

Sets the application configuration.

pub fn openapi(self, config: OpenApiConfig) -> Self

Enables and configures OpenAPI documentation.

When enabled, the application will automatically generate an OpenAPI 3.1 specification and serve it at the configured endpoint.

Example

let app = App::builder()
    .openapi(OpenApiConfig::new()
        .title("My API")
        .version("1.0.0")
        .description("A sample API"))
    .build();

pub fn enable_docs(self, config: DocsConfig) -> Self

Enables and configures interactive API documentation endpoints.

This wires crate::docs::DocsConfig into the application build and ensures an OpenAPI JSON endpoint is served at config.openapi_path unless overridden later.

Notes:

• Docs endpoints are appended during build() so they don’t appear in the OpenAPI spec.
• If OpenAPI is already configured, its openapi_path is updated to match DocsConfig.

pub fn route<H, Fut>( self, path: impl Into<String>, method: Method, handler: H, ) -> Self

where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a route to the application.

Routes are matched in the order they are added.

pub fn route_entry(self, entry: RouteEntry) -> Self

Adds a pre-built RouteEntry to the application.

This is primarily used by proc-macro generated route builders that already know the method/path and can build an extraction wrapper.

pub fn websocket<H, Fut>(self, path: impl Into<String>, handler: H) -> Self

where H: Fn(&RequestContext, &mut Request, WebSocket) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<(), WebSocketError>> + Send + 'static,

Adds a websocket route to the application.

WebSocket routes are matched only when the server receives a valid websocket upgrade request. They do not appear in OpenAPI output.

pub fn get<H, Fut>(self, path: impl Into<String>, handler: H) -> Self

where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a GET route.

pub fn post<H, Fut>(self, path: impl Into<String>, handler: H) -> Self

where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a POST route.

pub fn put<H, Fut>(self, path: impl Into<String>, handler: H) -> Self

where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a PUT route.

pub fn delete<H, Fut>(self, path: impl Into<String>, handler: H) -> Self

where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a DELETE route.

pub fn patch<H, Fut>(self, path: impl Into<String>, handler: H) -> Self

where H: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Adds a PATCH route.

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

Adds middleware to the application.

Middleware is executed in the order it is added:

• before hooks run first-to-last
• after hooks run last-to-first

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

Adds shared state to the application.

State can be accessed by handlers through the State<T> extractor.

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

where E: Error + Send + Sync + 'static, H: Fn(&RequestContext, E) -> Response + Send + Sync + 'static,

Registers a custom exception handler for a specific error type.

When an error of type E occurs during request handling, the registered handler will be called to convert it into a response.

Example

#[derive(Debug)]
struct AuthError(String);

impl std::fmt::Display for AuthError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Auth error: {}", self.0)
    }
}

impl std::error::Error for AuthError {}

let app = App::builder()
    .exception_handler(|_ctx, err: AuthError| {
        Response::with_status(StatusCode::UNAUTHORIZED)
            .header("www-authenticate", b"Bearer".to_vec())
            .body_json(&json!({"error": err.0}))
    })
    .build();

pub fn exception_handlers(self, handlers: ExceptionHandlers) -> Self

Sets the exception handlers registry.

This replaces any previously registered handlers.

pub fn with_default_exception_handlers(self) -> Self

Uses default exception handlers for common error types.

This registers handlers for:

• HttpError → JSON response with status/detail
• ValidationErrors → 422 with error list

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

where F: FnOnce() -> Result<(), StartupHookError> + Send + 'static,

Registers a synchronous startup hook.

Startup hooks run before the server starts accepting connections, in the order they are registered (FIFO).

Example

let app = App::builder()
    .on_startup(|| {
        println!("Connecting to database...");
        Ok(())
    })
    .on_startup(|| {
        println!("Loading configuration...");
        Ok(())
    })
    .build();

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

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

Registers an async startup hook.

Async startup hooks are awaited in registration order.

Example

let app = App::builder()
    .on_startup_async(|| async {
        let pool = connect_to_database().await?;
        Ok(())
    })
    .build();

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

where F: FnOnce() + Send + 'static,

Registers a synchronous shutdown hook.

Shutdown hooks run after the server stops accepting connections and all in-flight requests complete (or are cancelled).

Shutdown hooks run in reverse registration order (LIFO), matching typical resource cleanup patterns (last acquired, first released).

Example

let app = App::builder()
    .on_shutdown(|| {
        println!("Closing database connections...");
    })
    .build();

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

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

Registers an async shutdown hook.

Async shutdown hooks are awaited in reverse registration order (LIFO).

Example

let app = App::builder()
    .on_shutdown_async(|| async {
        flush_metrics().await;
    })
    .build();

pub fn startup_hook_count(&self) -> usize

Returns the number of registered startup hooks.

pub fn shutdown_hook_count(&self) -> usize

Returns the number of registered shutdown hooks.

pub fn build(self) -> App

Builds the application.

This consumes the builder and returns the configured App.

Panics

Panics if any routes conflict (same method + structurally identical path pattern).

Trait Implementations

impl Debug for AppBuilder

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

Formats the value using the given formatter.

impl Default for AppBuilder

fn default() -> Self

Returns the “default value” for a type.