Struct App 

pub struct App<S = ()> { /* private fields */ }

A Kerniq application: routes, state, middleware, configuration and lifecycle in one builder.

use kerniq_server::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    App::new()
        .get("/", || async { "Hello from Kerniq" })
        .run("127.0.0.1:3000")
        .await
}

State

App<S> is parameterized by its state type. App::new creates an App<()>; App::state switches to App<T>, after which handlers can extract State<T>. Routes registered before state (which cannot use State<T>) are kept.

Finalization

Nothing is assembled until the app is run or converted with App::into_axum_router. At that point:

1. routes are combined into a single axum::Router (no runtime nesting),
2. the JSON 404/405 fallbacks are installed,
3. the state is provided,
4. middleware is applied in declaration order (first = outermost), followed by the middleware implied by ServerConfig (request_timeout → max_concurrent_requests → max_body_size, outermost to innermost).

Implementations

impl App<()>

pub fn new() -> Self

Creates an application with no routes, no state and default configuration.

pub fn state<T>(self, state: T) -> App<T>

where T: Clone + Send + Sync + 'static,

Sets the application state, available to handlers via State<T>.

The state is cloned for each request that extracts it, so it should be cheap to clone: wrap expensive resources in Arc (connection pools usually already are). Sub-states can be extracted with Axum’s FromRef.

use std::sync::Arc;
use kerniq_server::prelude::*;

#[derive(Clone)]
struct AppState {
    service_name: Arc<str>,
}

async fn name(State(state): State<AppState>) -> String {
    state.service_name.to_string()
}

let app = App::new()
    .state(AppState { service_name: "customer-api".into() })
    .get("/name", name);

impl<S> App<S>

where S: Clone + Send + Sync + 'static,

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

where H: Handler<T, S>, T: 'static,

Registers a GET handler (also answers HEAD).

Paths use {name} captures; :name is accepted and converted.

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

where H: Handler<T, S>, T: 'static,

Registers a POST handler.

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

where H: Handler<T, S>, T: 'static,

Registers a PUT handler.

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

where H: Handler<T, S>, T: 'static,

Registers a PATCH handler.

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

where H: Handler<T, S>, T: 'static,

Registers a DELETE handler.

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

where H: Handler<T, S>, T: 'static,

Registers an OPTIONS handler.

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

where H: Handler<T, S>, T: 'static,

Registers a HEAD handler.

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

where H: Handler<T, S>, T: 'static,

Registers a TRACE handler.

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

where H: Handler<T, S>, T: 'static,

Registers a handler for every method.

pub fn on<H, T>(self, method: Method, path: &str, handler: H) -> Self

where H: Handler<T, S>, T: 'static,

Registers a handler for an arbitrary standard method. See Router::on.

pub fn route(self, path: &str, method_router: MethodRouter<S>) -> Self

Registers an Axum MethodRouter (advanced use: per-route layers, several methods at once). See Router::route.

pub fn group(self, f: impl FnOnce(&mut Group<'_, S>)) -> Self

Registers several routes in a block. See Router::group.

pub fn mount(self, path: &str, router: Router<S>) -> Self

Mounts a Kerniq Router under path (combined with the router’s own prefix).

use kerniq_server::prelude::*;

let users = Router::new().get("/", list).post("/", create);
let app = App::new()
    .mount("/users", users)
    .mount("/accounts", Router::new().get("/", accounts));

pub fn merge(self, router: Router<S>) -> Self

Merges a Kerniq Router at its own prefix.

use kerniq_server::prelude::*;

let api = Router::new()
    .prefix("/api/v1")
    .group(|r| { r.get("/users", users); });
let app = App::new().merge(api);

pub fn mount_axum(self, path: &str, router: Router<S>) -> Self

Mounts an existing axum::Router under path ("/" merges it at the root). Its routes, layers and handlers are used as-is.

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

Adds application-wide middleware. The first middleware added is the outermost. Applies to every route and to the 404 fallback, regardless of whether routes are registered before or after this call.

pub fn layer<L>(self, layer: L) -> Self

where TowerLayer<L>: Middleware,

Adds an application-wide Tower layer. Shares the ordered stack with middleware.

pub fn fallback<H, T>(self, handler: H) -> Self

where H: Handler<T, S>, T: 'static,

Replaces the default JSON 404 NOT_FOUND fallback.

pub fn observability(self, observability: Observability) -> Self

Available on crate feature observability only.

Enables observability (feature observability).

use kerniq_server::prelude::*;
use kerniq_server::observability::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let observability = Observability::builder()
        .service_name("payment-api")
        .metrics(MetricsConfig::new())
        .build()
        .await?;

    App::new()
        .observability(observability)
        .get("/health", || async { "OK" })
        .run("0.0.0.0:3000")
        .await
}

At finalization:

• HTTP instrumentation (metrics, a span per request, W3C context extraction) becomes the outermost middleware, so it measures everything inside it, including timeouts, rate limiting and the 404 fallback;
• a Prometheus endpoint configured on the application listener is added outside all middleware, so scrapes are never instrumented, rate-limited or timed out; one configured with its own listener is served by a background task bound when the app starts.

Under run/serve, telemetry is flushed and shut down after connections and background tasks have drained, bounded by the observability shutdown timeout. With into_axum_router the application owns the handle and calls shutdown itself.

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

Sets the server configuration.

pub fn server_config(&self) -> &ServerConfig

The current server configuration.

pub fn background_task<F, Fut>(self, name: &'static str, task: F) -> Self

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

Registers a background task started when the server starts. It receives a Shutdown handle and should return promptly once it triggers; the server waits up to shutdown_timeout for it.

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

let app = App::new().background_task("heartbeat", |shutdown: Shutdown| async move {
    let mut tick = tokio::time::interval(Duration::from_secs(30));
    loop {
        tokio::select! {
            _ = tick.tick() => tracing::info!("still alive"),
            () = shutdown.wait() => break,
        }
    }
});

pub fn shutdown_signal<F>(self, signal: F) -> Self

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

Replaces the default shutdown trigger (Ctrl+C / SIGTERM) with signal. Shutdown can also be triggered at any time through shutdown_handle.

pub fn shutdown_handle(&self) -> Shutdown

A handle that triggers or observes this app’s shutdown. Store it in state so long-lived handlers (WebSockets, streams) can finish when the server stops.

pub fn routes(&self) -> &[RouteInfo]

The registered routes (for diagnostics; mounted Axum routers appear as a single opaque entry).

pub fn into_axum_router(self) -> Router

Finalizes the application into a plain axum::Router, with fallbacks, state and all middleware applied.

Use this to run Kerniq under axum::serve, embed it into a larger Axum application, or test it with tower::ServiceExt::oneshot. Lifecycle features (background tasks, shutdown signal, connection limits) belong to App::run and are not part of the router.

pub async fn run(self, address: impl AsRef<str>) -> Result<()>

Binds address and serves until shutdown. Requires a Tokio runtime (for example #[tokio::main]).

address is anything tokio::net::TcpListener::bind accepts as a string: "127.0.0.1:3000", "0.0.0.0:8080", "localhost:3000", "[::1]:3000". To use the configured address, pass config.address().

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

Serves on an already-bound listener (useful for tests with port 0, socket activation, or binding before dropping privileges).

pub fn run_blocking(self, address: impl AsRef<str>) -> Result<()>

Like run, but creates and owns a multi-threaded Tokio runtime (with workers threads, if configured).

use kerniq_server::prelude::*;

fn main() -> Result<()> {
    App::new()
        .get("/", || async { "OK" })
        .run_blocking("0.0.0.0:3000")
}

Errors

Returns an error (and does not start) if called from inside a Tokio runtime: nested runtimes are not allowed. Use .run(addr).await there.

Trait Implementations

impl<S> Debug for App<S>

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

Formats the value using the given formatter.

impl Default for App<()>

fn default() -> Self

Returns the “default value” for a type.

impl<S> From<App<S>> for Router

where S: Clone + Send + Sync + 'static,

fn from(app: App<S>) -> Self

Converts to this type from the input type.