Struct App 

pub struct App { /* private fields */ }

A configured web application.

The App holds all routes, middleware, state, and lifecycle hooks, and provides methods to handle incoming requests.

Implementations

impl App

pub fn builder() -> AppBuilder<()>

Creates a new application builder.

pub fn config(&self) -> &AppConfig

Returns the application configuration.

pub fn route_count(&self) -> usize

Returns the number of registered routes.

pub fn state(&self) -> &Arc<RwLock<StateContainer>>

Returns the shared state container (protected by RwLock for lifespan mutation).

pub fn get_state<T: Send + Sync + 'static>(&self) -> Option<Arc<T>>

Gets a reference to shared state of type T.

pub fn dependency_overrides(&self) -> &Arc<DependencyOverrides>

Returns the dependency overrides registry.

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

where T: FromDependency, F: Fn(&RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<T, T::Error>> + Send + 'static,

Registers a dependency override for this application (useful in tests).

pub fn override_dependency_value<T>(&self, value: T)

where T: FromDependency,

Registers a fixed dependency override value.

pub fn clear_dependency_overrides(&self)

Clears all registered dependency overrides.

pub fn exception_handlers(&self) -> &Arc<ExceptionHandlers>

Returns the exception handlers registry.

pub fn handle_error<E>(&self, ctx: &RequestContext, err: E) -> Option<Response>

where E: Error + Send + Sync + 'static,

Handles an error using registered exception handlers.

If a handler is registered for the error type, it will be invoked. Otherwise, returns None.

pub fn handle_error_or_default<E>( &self, ctx: &RequestContext, err: E, ) -> Response

where E: Error + Send + Sync + 'static,

Handles an error, returning a 500 response if no handler is registered.

pub fn mounted_apps(&self) -> &[MountedApp]

Returns the mounted sub-applications.

pub async fn handle(&self, ctx: &RequestContext, req: &mut Request) -> Response

Handles an incoming request.

This first checks mounted sub-applications (in registration order), then matches against registered routes, runs middleware, and returns the response. Path parameters are extracted and stored in request extensions for use by the Path extractor.

Mounted App Handling

When a request path matches a mounted app’s prefix, the request is forwarded to that app with the prefix stripped from the path. The mounted app’s middleware runs instead of the parent’s middleware.

Special Parameter Injection

• ResponseMutations: Headers and cookies set by handlers are automatically applied to the final response.
• BackgroundTasks: Tasks are stored in request extensions via BackgroundTasksInner. The HTTP server should retrieve and execute these after sending the response using take_background_tasks().

pub fn take_background_tasks(req: &mut Request) -> Option<BackgroundTasks>

Take background tasks from a request after handling.

This should be called by the HTTP server after handle() returns and the response has been sent to the client. The returned tasks should be executed asynchronously.

Example

let response = app.handle(&ctx, &mut request).await;
// Send response to client...
if let Some(tasks) = App::take_background_tasks(&mut request) {
    tasks.execute_all().await;
}

pub async fn run_startup_hooks(&self) -> StartupOutcome

Runs all startup hooks.

Hooks run in registration order (FIFO). If a hook returns an error with abort: true, execution stops and returns StartupOutcome::Aborted.

This consumes the startup hooks - they can only be run once.

Returns

• StartupOutcome::Success if all hooks succeeded
• StartupOutcome::PartialSuccess if some hooks had non-fatal errors
• StartupOutcome::Aborted if a fatal hook error occurred

pub async fn run_shutdown_hooks(&self)

Runs all shutdown hooks.

Hooks run in reverse registration order (LIFO). Errors are logged but do not stop other hooks from running.

This consumes the shutdown hooks - they can only be run once.

pub fn transfer_shutdown_hooks(&self, controller: &ShutdownController)

Transfers shutdown hooks to a ShutdownController.

This moves all registered shutdown hooks to the controller, which will run them during the appropriate shutdown phase.

Call this when integrating with the server’s shutdown mechanism.

pub fn pending_startup_hooks(&self) -> usize

Returns the number of pending startup hooks.

pub fn pending_shutdown_hooks(&self) -> usize

Returns the number of pending shutdown hooks.

pub fn test_client(self: Arc<Self>) -> TestClient<Arc<App>>

Creates a crate::TestClient for this application.

The test client provides in-process testing without network overhead, simulating HTTP requests against the full application stack including middleware, routing, and handlers.

Example

use fastapi_core::{App, Request, Response, RequestContext, Method};

async fn hello(ctx: &RequestContext, req: &mut Request) -> Response {
    Response::ok().body_text("Hello!")
}

let app = App::builder()
    .route("/hello", Method::Get, hello)
    .build();

// Create test client from app
let client = app.test_client();

// Make requests
let response = client.get("/hello").send();
assert_eq!(response.status().as_u16(), 200);
assert_eq!(response.text(), "Hello!");

pub fn test_client_with_seed(self: Arc<Self>, seed: u64) -> TestClient<Arc<App>>

Creates a crate::TestClient with a specific seed for deterministic testing.

Using the same seed produces reproducible behavior for tests involving concurrent operations or random elements.

Example

let app = Arc::new(App::builder().build());
let client = app.test_client_with_seed(42);
// Tests will be deterministic with this seed

Trait Implementations

impl Debug for App

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

Formats the value using the given formatter.

impl Handler for App

fn call<'a>( &'a self, ctx: &'a RequestContext, req: &'a mut Request, ) -> BoxFuture<'a, Response>

Process a request and return a response.

fn dependency_overrides(&self) -> Option<Arc<DependencyOverrides>>

Optional dependency overrides to apply when building request contexts.