Struct App 

pub struct App { /* private fields */ }

Thin wrapper over Router plus server settings and lifecycle hooks.

Implementations

impl App

pub fn bind(self, target: impl Into<Bind>) -> BoundApp

Choose a bind target; call .serve() (optionally after .shutdown(...)).

pub async fn listen(self, port: u16) -> Result<()>

Bind 0.0.0.0:port, run CLI if present, otherwise serve.

Prefer this for the common case; use Self::bind for custom addresses. When a plugin attached TLS via [Self::use_tls] (e.g. Acme), this serves HTTPS.

impl App

pub fn build(&self) -> Result<Server>

Compile routes once into a Server. Prefer this over repeated App::handle.

impl App

pub fn new() -> Self

pub fn register_cli<F, Fut>(&mut self, name: &'static str, f: F) -> &mut Self

where F: Fn(Arc<StateMap>, Vec<String>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<()>> + Send + 'static,

Register a plugin CLI command handled by Self::run (e.g. "migrate").

pub fn register_check<F, Fut>(&mut self, name: &'static str, f: F) -> &mut Self

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

Register a readiness check (CheckKind::Ready) for GET /ready and CLI check.

pub fn register_audit<F, Fut>(&mut self, name: &'static str, f: F) -> &mut Self

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

Register a deploy-time audit (CheckKind::Audit) — CLI check only, not /ready.

pub async fn run_checks( &self, state: Arc<StateMap>, kinds: &[CheckKind], ) -> Vec<CheckResult>

Run registered checks filtered by CheckKind.

pub fn with_probes(&mut self) -> &mut Self

Install k8s-style probes: GET /healthz (liveness) and GET /ready (Ready checks).

Idempotent. Presets (App::web / App::api) call this automatically.

pub fn max_body_size(&mut self, bytes: usize) -> &mut Self

pub fn max_connections(&mut self, n: usize) -> &mut Self

Cap concurrent TCP/UDS connections (default 1024).

pub fn max_upgraded_connections(&mut self, n: usize) -> &mut Self

Cap concurrent HTTP upgrades (WebSocket, …). Excess → 503 + Retry-After.

pub fn max_concurrent_streams(&mut self, n: usize) -> &mut Self

Cap concurrent HTTP/2 streams per connection (default 200). Excess streams → GOAWAY/stream-level rejection handled by hyper.

pub fn max_headers(&mut self, n: usize) -> &mut Self

Max HTTP/1 header count (default 100). Excess → 431 from hyper.

pub fn max_buf_size(&mut self, bytes: usize) -> &mut Self

Cap hyper’s connection buffer (headers + body framing). Minimum 8192. Default ~400 KiB. Use this to bound oversized header blocks.

pub fn request_timeout(&mut self, timeout: Option<Duration>) -> &mut Self

Per-request timeout around the handler (default 30s). None disables.

Measured: timeout ends when the handler returns a Response. Streaming response bodies (SSE) continue afterward and are not cut by this timer. Idle between stream chunks is governed by TCP/keep-alive, not this setting.

pub fn header_read_timeout(&mut self, timeout: Duration) -> &mut Self

Timeout for reading request headers (Slowloris). Also applied while waiting for the next keep-alive request (see Self::idle_timeout). Default 10s.

pub fn idle_timeout(&mut self, timeout: Duration) -> &mut Self

Keep-alive idle: how long a quiet connection may wait for the next request. Hyper uses one timer for header reads; the effective wait is min(header_read_timeout, idle_timeout). Default 60s.

pub fn drain_timeout(&mut self, timeout: Duration) -> &mut Self

How long to wait for in-flight connections after accept stops (default 20s).

pub fn keep_alive(&mut self, enabled: bool) -> &mut Self

HTTP/1 keep-alive (default true).

pub fn trust_proxy(&mut self, trust: bool) -> &mut Self

When true, ClientAddr may use X-Forwarded-For / Forwarded (only behind a trusted proxy).

pub fn cli_mode(&mut self, enabled: bool) -> &mut Self

Mark this app as running under the CLI helper (skips BackgroundServices by default).

pub fn service_in_cli(&mut self, enabled: bool) -> &mut Self

Start BackgroundServices even when Self::cli_mode is set (default false).

pub fn install<P: Plugin>(&mut self, plugin: P) -> &mut Self

pub fn has_plugin(&self, id: &str) -> bool

Whether a plugin with this Plugin::id was already installed.

pub fn installed_plugin_meta(&self) -> &[InstalledPlugin]

Metadata for every plugin passed to Self::install (order preserved).

pub async fn run(self) -> Result<()>

Primary app entrypoint: run as a server process.

CLI mode:

• check
• routes
• plugins
• openapi --out <path>
• tasks
• i18n missing

Non-CLI mode binds via Bind::Env (HOST/PORT, default port 3000). Prefer App::bind + BoundApp::run when the address is fixed in code.

pub fn service<S: BackgroundService + 'static>( &mut self, service: S, ) -> &mut Self

Register a process-local BackgroundService.

Lifecycle: compile → on_startup → services → accept; stop: stop accept → drain → stop services → on_shutdown.

pub fn on_startup<F, Fut>(&mut self, f: F) -> &mut Self

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

Run before accepting connections. Err prevents the server from starting.

pub fn on_shutdown<F, Fut>(&mut self, f: F) -> &mut Self

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

Run after the accept loop stops, connections drain, and services stop.

pub fn events(&mut self) -> EventBus

Shared EventBus — inserts a default bus into app state on first use.

pub fn explain(&self) -> String

Route map for debugging / startup banner.

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

Handle one request (compiles the router each call). Prefer Self::build.

pub async fn handle_request( &self, method: Method, path: &str, body: &str, ) -> Response

Sugar over Request::builder + Self::handle (no custom headers). For headers use Request::builder().header(...).build() + Self::handle. Prefer Server::handle_request after Self::build.

impl App

pub fn configure(&mut self) -> Result<&mut Self>

Load sova.toml or Sova.toml from the current directory, then env overrides.

Missing file is not an error — only SOVA_* env overrides apply.

pub fn configure_from_path( &mut self, path: impl AsRef<Path>, ) -> Result<&mut Self>

Load settings from a toml file (app-level only), then SOVA_* env overrides.

pub fn configure_from_str(&mut self, text: &str) -> Result<&mut Self>

Parse toml and apply [server] (+ legacy) for the active profile, then env overrides.

pub fn from_toml(path: impl AsRef<Path>) -> Result<Self>

App::new() + Self::configure_from_path.

pub fn config_doc(&self) -> Option<Arc<ConfigDoc>>

Shared ConfigDoc from the last successful Self::configure_from_str, if any.

Methods from Deref<Target = Router>

pub fn use_middleware<M>(&mut self, mw: M) -> &mut Self

where M: IntoMwEntry,

pub fn with<T: RouteValue>(&mut self, value: T) -> &mut Self

Attach a RouteValue to the last HTTP route, or to router defaults.

After get/post/…, writes to that route. Otherwise writes to router/app defaults (inherited by routes: route > router > app).

pub fn with_update<T, F>(&mut self, f: F) -> &mut Self

where T: RouteValue + Clone + Default, F: FnOnce(&mut T),

Update a RouteValue on the last route (insert T::default() if missing).

pub fn route_middleware<M>(&mut self, mw: M) -> &mut Self

where M: IntoMwEntry,

Push middleware onto the last registered HTTP route only.

pub fn route_meta<T: RouteValue>(&mut self, value: T) -> &mut Self

Alias for Self::with (writes to the last route when present).

pub fn state<T>(&mut self, value: T) -> &mut Self

where T: Send + Sync + 'static,

pub fn try_state<T>(&self) -> Option<Arc<T>>

where T: Send + Sync + 'static,

Shared app state inserted via Self::state, if present.

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

where H: IntoHandler<T>,

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

where H: IntoHandler<T>,

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

where H: IntoHandler<T>,

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

where H: IntoHandler<T>,

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

where H: IntoHandler<T>,

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

where H: IntoHandler<T>,

Explicit HEAD handler (takes precedence over GET→strip-body).

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

where H: IntoHandler<T>,

Explicit OPTIONS handler (takes precedence over auto 204 + Allow).

pub fn redirect( &mut self, from: &str, to: impl Into<String>, status: u16, ) -> &mut Self

GET from → redirect to to with the given HTTP status (e.g. 302, 301, 303).

app.redirect("/health", "/healthz", 302);
app.redirect("/old", "/new", 301);

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

where H: IntoRawHandler,

Escape hatch: handle a path with a raw Hyper request/response (no Sova middleware).

pub fn mount(&mut self, prefix: &str, other: Router) -> &mut Self

Mount a child router under prefix.

Bakes the child’s middleware stack into its routes. Does not prepend this router’s middleware — the eventual root stack is applied once in compile_router as an outer wrap (so App-level middleware is not doubled).

pub fn group<F>(&mut self, prefix: &str, f: F) -> &mut Self

where F: FnOnce(&mut Router),

Sugar over Self::mount: build a child router in a closure.

pub fn catch<H, T>(&mut self, status: u16, handler: H) -> &mut Self

where H: IntoHandler<T>,

Register a catcher for HTTP status in this router’s mount scope.

At dispatch, the catcher with the longest matching prefix wins. not_found is sugar for catch(404, …).

pub fn not_found<H, T>(&mut self, handler: H) -> &mut Self

where H: IntoHandler<T>,

Sugar for Self::catch(404, handler).

pub fn error_handler<F, Fut>(&mut self, f: F) -> &mut Self

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

Called when a leaf handler returns Err. Request is already consumed.

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

Full introspection: HTTP routes and raw paths.

pub fn explain(&self) -> String

Human-readable route map (method, path, middleware names).

Trait Implementations

impl Default for App

fn default() -> Self

Returns the “default value” for a type.

impl Deref for App

type Target = Router

The resulting type after dereferencing.

fn deref(&self) -> &Router

Dereferences the value.

impl DerefMut for App

fn deref_mut(&mut self) -> &mut Router

Mutably dereferences the value.