Struct App 

pub struct App { /* private fields */ }

Main application struct

Implementations

impl App

pub fn new() -> Self

pub fn max_body_size(self, size: Option<usize>) -> Self

Set maximum request body size in bytes (None = unlimited)

pub fn body_limit(self, prefix: &str, limit: Option<usize>) -> Self

Different request body limit for everything under prefix

None removes the limit. The longest matching prefix wins over the default from App::max_body_size, e.g. a small default with a large limit for an upload route: App::new().max_body_size(Some(64 * 1024)).body_limit("/api/files", Some(25 << 20)).

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

Register shared application state, readable in handlers and middleware with Request::state

One value per type; registering the same type again replaces it. Use interior mutability (Mutex, RwLock, atomics) for mutable state: the value is shared by all requests and is not cloned.

use ullun::prelude::*;
use std::sync::atomic::{AtomicU64, Ordering};

#[derive(Default)]
struct Hits(AtomicU64);

async fn count(req: Request) -> Result<Response> {
    let hits = req.state::<Hits>()?.0.fetch_add(1, Ordering::Relaxed) + 1;
    Ok(Response::text(hits.to_string()))
}

let app = App::new().state(Hits::default()).get("/", count);

pub fn background<F, Fut>(self, task: F) -> Self

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

Run task alongside the server, started when it starts serving

The task gets a Context with the shared state and the shutdown signal; it should return when ctx.sleep(..) reports false or ctx.shutdown().wait() completes. Finished tasks are awaited during shutdown, for at most App::shutdown_grace.

use std::time::Duration;
use ullun::prelude::*;

struct Jobs;

let app = App::new().state(Jobs).background(|ctx: Context| async move {
    while ctx.sleep(Duration::from_secs(60)).await {
        let _jobs = ctx.state::<Jobs>().unwrap();
        // purge expired sessions, refresh caches, ...
    }
});

pub fn shutdown_grace(self, grace: Duration) -> Self

How long shutdown waits for in-flight requests and background tasks (default 10 seconds)

pub fn group( self, prefix: &str, configure: impl FnOnce(RouteGroup) -> RouteGroup, ) -> Self

Create a route group with a common prefix

pub fn doc(self, method: &str, path: &str, operation: Operation) -> Self

Describe a registered route for the OpenAPI document

path is the path exactly as registered, e.g. /users/{id}.

pub fn openapi(self, info: OpenApiInfo) -> Self

Publish an OpenAPI 3.1 document of all routes (and optionally Swagger UI)

See the openapi module.

pub fn get<H>(self, path: &str, handler: H) -> Self

where H: Handler,

Add GET route

pub fn get_with_params<F, Fut>(self, path: &str, handler: F) -> Self

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

Add GET route with path params extractor

pub fn post<H>(self, path: &str, handler: H) -> Self

where H: Handler,

Add POST route

pub fn put<H>(self, path: &str, handler: H) -> Self

where H: Handler,

Add PUT route

pub fn delete<H>(self, path: &str, handler: H) -> Self

where H: Handler,

Add DELETE route

pub fn patch<H>(self, path: &str, handler: H) -> Self

where H: Handler,

Add PATCH route

pub fn ws<F, Fut>(self, path: &str, handler: F) -> Self

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

Accept WebSocket connections on path (feature websocket)

The handler receives the original request (path params, query, headers, extensions set by middleware) and the upgraded socket, and runs on its own task until it returns.

pub fn ws_with<F, Fut>(self, path: &str, options: WsOptions, handler: F) -> Self

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

Like App::ws with explicit size limit and allowed origins

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

where M: Middleware,

Add middleware

pub fn serve_static(self, route_prefix: &str, dir_path: &str) -> Self

Serve static files from a directory

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

Run the server until CTRL+C or SIGTERM, then shut down gracefully

Stops accepting connections, lets in-flight requests finish and waits for background tasks, each for at most App::shutdown_grace.

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

Serve on an already bound listener until the future is dropped.

Useful for tests, benchmarks and embedding: bind to port 0, read the assigned port from listener.local_addr(), then call serve. Unlike App::run, this does not install signal handlers; use App::serve_with_shutdown for a graceful stop.

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

Serve until signal completes, then shut down gracefully

New connections are refused, idle keep-alive connections are closed, running requests finish, the shutdown signal reaches Request::shutdown_signal and background tasks, and the call returns once everything has stopped or App::shutdown_grace has passed.

Trait Implementations

impl Default for App

fn default() -> Self

Returns the “default value” for a type.