Struct AppWithState 

pub struct AppWithState<S> { /* private fields */ }

An Application that combines user-defined state-aware routes with the built-in App controller chain as a fallback.

Routes are matched in registration order. The first match wins; unmatched requests are forwarded to App (static files, health probes, etc.).

Implementations

impl<S: Send + Sync + 'static> AppWithState<S>

pub fn new(state: S) -> Self

Create a new AppWithState wrapping state.

state is stored behind an Arc so it can be shared across threads without cloning. Register routes with the builder methods.

pub fn with_config(self, config: ServerConfig) -> Self

Pin the fallback App (used for any request this app’s own routes don’t match) to an explicit ServerConfig, instead of reading RWS_CONFIG_* environment variables per request.

Mirrors App::with_config — same rationale: safe for parallel tests (no test_env::lock() needed) and lets multiple differently-configured instances coexist in one process.

pub fn state(&self) -> &S

Return a reference to the shared state.

pub fn get<F>(self, pattern: &str, handler: F) -> Self

where F: Fn(&Request, &PathParams, &ConnectionInfo, &S) -> Response + Send + Sync + 'static,

Register a GET handler for pattern.

pub fn post<F>(self, pattern: &str, handler: F) -> Self

where F: Fn(&Request, &PathParams, &ConnectionInfo, &S) -> Response + Send + Sync + 'static,

Register a POST handler for pattern.

pub fn put<F>(self, pattern: &str, handler: F) -> Self

where F: Fn(&Request, &PathParams, &ConnectionInfo, &S) -> Response + Send + Sync + 'static,

Register a PUT handler for pattern.

pub fn patch<F>(self, pattern: &str, handler: F) -> Self

where F: Fn(&Request, &PathParams, &ConnectionInfo, &S) -> Response + Send + Sync + 'static,

Register a PATCH handler for pattern.

pub fn delete<F>(self, pattern: &str, handler: F) -> Self

where F: Fn(&Request, &PathParams, &ConnectionInfo, &S) -> Response + Send + Sync + 'static,

Register a DELETE handler for pattern.

pub fn websocket<F>(self, pattern: &str, handler: F) -> Self

where F: Fn(WebSocketConnection, PathParams, Arc<S>) + Send + Sync + 'static,

Available on non-WebAssembly only.

Serve WebSocket connections at pattern: an upgrade request’s connection goes to handler with the route’s parameters and the state, anything else gets 426 Upgrade Required. The handler runs on a thread of its own for the connection’s life.

use std::sync::Mutex;
use rust_web_server::app::App;
use rust_web_server::websocket::Message;

let app = App::with_state(Mutex::new(0u64)).websocket("/count", |mut ws, _params, state| {
    while let Ok(Some(Message::Text(_))) = ws.recv() {
        let n = { let mut n = state.lock().unwrap(); *n += 1; *n };
        let _ = ws.send_text(&n.to_string());
    }
});

pub fn stream_body(self, method: &str, pattern: &str) -> Self

Return a snapshot of all registered routes as (method, pattern) pairs. Hand requests to method pattern (same pattern syntax as the route) their body as a stream instead of reading it into memory first (#31): the handler reads request.body with std::io::Read while the upload is still arriving.

use std::io::Read;
use rust_web_server::app::App;
use rust_web_server::response::{Response, STATUS_CODE_REASON_PHRASE};

let app = App::with_state(())
    .put("/upload/:name", |request, params, _conn, _state| {
        let mut file = std::fs::File::create(format!("/tmp/{}", params.get("name").unwrap())).unwrap();
        let copied = std::io::copy(&mut &request.body, &mut file);
        Response::text(STATUS_CODE_REASON_PHRASE.n200_ok, &format!("{copied:?}"))
    })
    .stream_body("PUT", "/upload/:name");

pub fn route_entries(&self) -> Vec<RouteInfo>

The registered routes as (method, pattern), in registration order.

pub fn route<H: Handler<S>>(self, handler: H) -> Self

Register a typed handler (18.28.0): a function with extractor arguments annotated #[get("/path")] & co. The method and pattern come from the attribute, which checked the pattern’s parameters against the function’s Path argument at compile time.

use rust_web_server::handler::{Json, Path, State};

#[get("/posts/{id}")]
fn show_post(Path(id): Path<u64>, State(db): State<Db>) -> Result<Json<Post>, AppError> {
    db.find(id).map(Json).ok_or_else(|| AppError::NotFound(format!("post {id}")))
}

let app = App::with_state(db).route(show_post);

pub fn route_conflicts(&self) -> Vec<RouteConflict>

Routes that never run because an earlier one with the same method matches every path they do (18.28.0). See Router::route_conflicts; each is also printed once to stderr when it’s registered.

pub fn mcp( self, name: impl Into<String>, version: impl Into<String>, ) -> McpServer

Attach an MCP server to this application. Requests that do not match the MCP endpoint (POST /mcp) are forwarded to self, so all previously registered routes remain active.

use rust_web_server::app::App;
use rust_web_server::mcp::{McpContent, extract_arg};
use rust_web_server::response::{Response, STATUS_CODE_REASON_PHRASE};
use rust_web_server::core::New;

struct Db { url: String }

let app = App::with_state(Db { url: "postgres://localhost/mydb".to_string() })
    .get("/api/users", |_req, _params, _conn, _db| {
        let mut r = Response::new();
        r.status_code = *STATUS_CODE_REASON_PHRASE.n200_ok.status_code;
        r.reason_phrase = STATUS_CODE_REASON_PHRASE.n200_ok.reason_phrase.to_string();
        r
    })
    .mcp("my-server", "1.0")
    .tool("list_users", "List all users", "{}", |_| {
        Ok(McpContent::json(r#"[{"id":1,"name":"Alice"}]"#))
    });

pub fn wrap<M: Middleware + 'static>( self, layer: M, ) -> WithMiddleware<AppWithState<S>>

Wrap this application in a middleware layer.

Enables fluent composition:

use rust_web_server::app::App;
use rust_web_server::core::New;
use rust_web_server::middleware::RateLimitLayer;
use rust_web_server::response::Response;

let app = App::with_state(())
    .get("/ping", |_, _, _, _| Response::new())
    .wrap(RateLimitLayer);

pub fn openapi_spec(&self, config: &OpenApiConfig) -> String

Available on crate feature openapi only.

Add GET /openapi.json (a generated OpenAPI 3.1 document covering every route registered so far) and GET /docs (Swagger UI, loaded from a CDN, pointed at /openapi.json).

Call this after registering your routes — routes added afterward still work but won’t appear in the generated spec, since it’s built once at this call rather than read dynamically per request.

Requires the openapi feature.

use rust_web_server::app::App;
use rust_web_server::openapi::OpenApiConfig;
use rust_web_server::response::Response;
use rust_web_server::core::New;

let app = App::with_state(())
    .get("/users", |_req, _params, _conn, _state| Response::new())
    .get("/users/:id", |_req, _params, _conn, _state| Response::new())
    .openapi(OpenApiConfig::new("My API", "1.0.0"));

This app’s OpenAPI document as JSON (what openapi serves), e.g. for McpServer::openapi_tools.

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

Available on crate feature openapi only.

Trait Implementations

impl<S: Send + Sync + 'static> Application for AppWithState<S>

fn runs_inline(&self, request: &Request, connection: &ConnectionInfo) -> bool

Route handlers are user code and may block: only requests no route matches, falling through to the built-in App, run inline.

fn execute( &self, request: &Request, connection: &ConnectionInfo, ) -> Result<Response, String>

Receives a parsed request and returns a fully-built response. Walk your controller list with is_matching / process and return the first match.

fn streams_body(&self, request: &Request, connection: &ConnectionInfo) -> bool

true to receive this request’s body as a stream (Body::Stream) instead of read into memory first: execute then runs while the body is still arriving, on a blocking-pool thread, and reads it with std::io::Read — a multi-gigabyte upload in a few chunks of memory. Asked after the head is read, so request.body is empty here; decide from the method, path and headers.

fn registered_routes(&self) -> Vec<RouteInfo>

The routes this application registers, as (method, pattern) — what AppWithState::route_entries returns; wrappers (WithMiddleware, McpServer) report the routes of the application inside. For tools that describe an app (the dev MCP server’s routes tool), not for dispatch. Default: none. Since 18.28.0.

fn execute_async<'a>( &'a self, _request: &'a Request, _connection: &'a ConnectionInfo, ) -> Option<AsyncResponse<'a>>

Available on crate feature http2 only.

An asynchronous version of execute for this request, when the application has one: the async servers await it on the connection’s task instead of tying up a blocking-pool thread while it waits (the config-driven proxy uses this to wait for a backend without holding a thread). None (the default) means “use execute”. Wrappers return Some only when they add no synchronous work of their own.

fn middleware_names(&self) -> Vec<&'static str>

The names of the middleware layers around this application’s routes, in the order a request passes them (Middleware::layer_name). Default: none; WithMiddleware lists its layers, then the inner application’s. Since 18.28.0.

impl<S: Clone> Clone for AppWithState<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.