Churust 🌀

Churro + Rust — a backend web framework inspired by Ktor. Simple, secure, robust, and easy to learn.

Churust gives you Ktor’s developer experience in Rust: an application engine, a routing DSL, an install(plugin) system, and a phased interceptor pipeline — built on a battle-tested async stack (tokio + hyper + rustls). Churust owns the ergonomic layer; it does not reinvent HTTP parsing or TLS.

Coming from Kotlin/Ktor? See From Ktor to Churust for side-by-side examples (routes, install, JSON, auth, config, tests).

use churust::prelude::*;

#[churust::main]
async fn main() -> std::io::Result<()> {
    Churust::server()
        .port(8080)
        .routing(|r| {
            r.get("/", |_call: Call| async { "Hello from Churust 🌀" });
            r.get("/users/{id}", |Path(id): Path<u64>| async move {
                format!("user #{id}")
            });
        })
        .start()
        .await
}

What you get

How this site is organized

Docs map

Status

Published on crates.io. Pre-1.0: the API is settling rather than settled — expect breaking changes in minor releases until 1.0. Current series documented here: 0.3.

MSRV: Rust 1.96+.

Next step

→ Quick start

Quick start

Get a Churust server running in a few minutes.

Prerequisites

• Rust 1.96+ (rustc --version)
• A terminal and cargo

1. Create a project

cargo new hello-churust
cd hello-churust

2. Add Churust

cargo add churust@0.3

Or in Cargo.toml:

[dependencies]
churust = "0.3"

That is the whole dependency list for a minimal server. Churust re-exports the runtime it is built on as churust::tokio, and #[churust::main] uses that re-export — no separate tokio entry is required.

3. Write the server

Replace src/main.rs with:

use churust::prelude::*;

#[churust::main]
async fn main() -> std::io::Result<()> {
    Churust::server()
        .host("127.0.0.1")
        .port(8080)
        .routing(|r| {
            r.get("/", |_call: Call| async { "Hello from Churust 🌀" });
            r.get("/users/{id}", |Path(id): Path<u64>| async move {
                format!("user #{id}")
            });
        })
        .start()
        .await
}

4. Run it

cargo run

In another terminal:

curl localhost:8080/
# Hello from Churust 🌀

curl localhost:8080/users/7
# user #7

What just happened?

1. #[churust::main] — builds a multi-threaded tokio runtime and runs your async main (the Churust equivalent of #[tokio::main]).
2. Churust::server() — starts the builder for an HTTP application.
3. .routing(|r| { ... }) — registers routes; path segments in {braces} become extractors.
4. .start().await — binds and serves until the process exits.

Try the official example

From a clone of the framework:

git clone https://github.com/davthecoder/Churust.git
cd Churust
cargo run -p hello

That example also shows query parameters and typed app state. See examples/hello.

Next steps

• Know Ktor already? → From Ktor to Churust
• Enable plugins and transports → Installation & features
• Learn extractors in depth → Handlers & extractors
• Build a JSON API → JSON API recipe

From Ktor to Churust

Churust deliberately reuses Ktor’s mental model so you can keep the same shape of application while writing Rust on tokio + hyper + rustls.

The syntax is Rust. The structure of a service — build, install, route, start — should already be familiar.

1. A minimal route

Ktor (Kotlin)

fun Application.module() {
    routing {
        get("/") {
            call.respondText("Hello from Ktor")
        }
    }
}

Churust (Rust)

use churust::prelude::*;

#[churust::main]
async fn main() -> std::io::Result<()> {
    Churust::server()
        .routing(|r| {
            r.get("/", |_call: Call| async { "Hello from Churust 🌀" });
        })
        .start()
        .await
}

Same idea: declare routes inside a routing block.
Rust difference: an explicit async main, and #[churust::main] (like #[tokio::main]) bootstraps the runtime Churust re-exports.

2. Path parameters

Ktor

routing {
    get("/users/{id}") {
        val id = call.parameters["id"]?.toLongOrNull()
            ?: return@get call.respond(HttpStatusCode.BadRequest)

        call.respondText("user #$id")
    }
}

Churust

#![allow(unused)]
fn main() {
r.get("/users/{id}", |Path(id): Path<u64>| async move {
    format!("user #{id}")
});
}

You still can take Call and dig into parts yourself; extractors are the short path for the common case.

3. Install plugins

Ktor

fun Application.module() {
    install(CallLogging)
    install(ContentNegotiation) {
        json()
    }
    install(CORS) {
        allowHost("app.example.com", schemes = listOf("https"))
    }

    routing {
        // …
    }
}

Churust

#![allow(unused)]
fn main() {
Churust::server()
    .install(CallLogging::new())
    .install(ContentNegotiation::new())
    .install(Cors::new().allow_origin("https://app.example.com"))
    .install(Compression::new())
    .install(RateLimit::per_minute(120))
    .routing(|r| {
        // …
    })
}

Enable features in Cargo.toml the same way you would add dependencies in Gradle — then install only what you compiled in:

churust = { version = "0.3", features = ["full"] }

See Installation & features and Pipeline & plugins.

4. JSON body + response

Ktor

@Serializable
data class NewNote(val text: String)

@Serializable
data class Note(val id: Long, val text: String)

routing {
    post("/notes") {
        val input = call.receive<NewNote>()
        call.respond(Note(id = 1, text = input.text))
    }
}

Churust

#![allow(unused)]
fn main() {
#[derive(Deserialize)]
struct NewNote { text: String }

#[derive(Serialize)]
struct Note { id: u64, text: String }

r.post("/notes", |Json(input): Json<NewNote>| async move {
    Json(Note { id: 1, text: input.text })
});
}

5. Authentication / principal

Ktor (sketch)

install(Authentication) {
    bearer("auth") {
        authenticate { credential ->
            if (credential.token == expected) UserIdPrincipal("admin") else null
        }
    }
}

routing {
    authenticate("auth") {
        get("/me") {
            val principal = call.principal<UserIdPrincipal>()!!
            call.respondText(principal.name)
        }
    }
}

Churust

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct Admin { name: String }

Churust::server()
    .install(Auth::bearer(|token: String| async move {
        (token == expected).then(|| Admin { name: "admin".into() })
    }))
    .routing(|r| {
        // Asking for Principal enforces auth (401 otherwise).
        r.get("/me", |Principal(u): Principal<Admin>| async move {
            u.name
        });
    })
}

Prefer secure_compare (or a real store) over == on secrets in production. See Authentication.

6. Shared application state

Ktor

// Often: attributes, singletons, or a DI framework
val store = NoteStore()
// … put store where handlers can reach it

Churust

#![allow(unused)]
fn main() {
struct Store { notes: Mutex<Vec<Note>> }

Churust::server()
    .state(Store { notes: Mutex::new(Vec::new()) })
    .routing(|r| {
        r.get("/notes", |s: State<Store>| async move {
            // …
        });
    })
}

Typed .state(T) + State<T> replace “reach into the application container.” Use interior mutability (Mutex, channels, …) when handlers update shared data.

7. Configuration

Ktor

# application.conf
ktor {
    deployment {
        port = 8080
        port = ${?PORT}
    }
}

Churust

# churust.toml
[server]
host = "0.0.0.0"
port = 8080

export CHURUST_SERVER_PORT=9090

#![allow(unused)]
fn main() {
Churust::from_config()
    .port(8080) // code still wins over env/file when chained
    .routing(|r| { /* … */ })
}

Precedence: defaults < churust.toml < CHURUST_* < builder DSL. Details: State & configuration.

8. Testing

Ktor

testApplication {
    application { module() }
    val response = client.get("/ping")
    assertEquals(HttpStatusCode.OK, response.status)
}

Churust

#![allow(unused)]
fn main() {
let app = Churust::server()
    .routing(|r| {
        r.get("/ping", |_c: Call| async { "pong" });
    })
    .build();

let res = TestClient::new(app).get("/ping").send().await;
assert_eq!(res.status(), StatusCode::OK);
assert_eq!(res.text(), "pong");
}

No socket bind: the full pipeline runs in-process, same idea as testApplication. See Testing.

What stays “Rust” on purpose

Churust does not try to feel like Kotlin. It reuses Ktor’s application shape so you do not relearn “what a server is,” then leans on Rust where it matters:

You still learn Rust. You should not have to learn a fragmented web stack at the same time.

Concept map (cheat sheet)

Ktor                         Churust
────                         ───────
Application.module()    →    Churust::server()…start()
routing { }             →    .routing(|r| { })
install(Feature)        →    .install(plugin)  + Cargo feature
call                    →    Call  |  extractors
receive / respond       →    Json / IntoResponse
principal               →    Principal<P>
attributes / DI         →    .state(T) + State<T>
application.conf        →    churust.toml + CHURUST_* + DSL
testApplication         →    TestClient
embeddedServer / Netty  →    hyper (HTTP) + rustls (TLS) + tokio

Next

• Quick start — run your first binary
• Handlers & extractors — depth on types
• JSON API recipe — plugins + auth end-to-end
• Pipeline & plugins — phase model

Installation & features

Depend on the umbrella crate

[dependencies]
churust = "0.3"

Plugins and transports are opt-in features on churust. Prefer enabling features on the umbrella crate rather than depending on plugin crates directly:

churust = { version = "0.3", features = ["full", "ws", "fs", "tls"] }

Default features are empty: plain churust = "0.3" compiles the core engine and nothing else.

Every Churust crate is released in lockstep on one version number, so churust-core, churust-json, and the rest always match the umbrella version.

Feature matrix

full enables the plugin set. Transports (ws, fs, tls, http3, multipart) stay opt-in individually — each is a protocol surface, not only an ergonomic helper.

Common combinations

# JSON API with auth and logging
churust = { version = "0.3", features = ["json", "logging", "cors", "auth"] }
# same as:
churust = { version = "0.3", features = ["full"] }

# Real-time chat
churust = { version = "0.3", features = ["ws"] }

# Static site + streaming
churust = { version = "0.3", features = ["fs"] }

# Production HTTPS
churust = { version = "0.3", features = ["tls"] }

Serde

Typed query/path/JSON bodies need Serde where you define types:

serde = { version = "1", features = ["derive"] }

Tokio

Usually do not add tokio yourself. Use churust::tokio for channels, timers, and select!. If you need a tokio feature Churust does not enable, add tokio with that feature — Cargo unifies the two.

MSRV

Churust requires Rust 1.96+. CI pins that toolchain.

API reference

• docs.rs/churust
• Feature flags reference
• Crate map

Project layout

Your application (typical)

my-api/
├── Cargo.toml
├── churust.toml          # optional layered config
├── src/
│   └── main.rs
└── public/               # if you serve static files
    └── index.html

Minimal Cargo.toml:

[package]
name = "my-api"
version = "0.1.0"
edition = "2021"

[dependencies]
churust = { version = "0.3", features = ["full"] }
serde = { version = "1", features = ["derive"] }

Workspace crates (the framework itself)

If you browse or contribute to Churust:

Runnable examples live under examples/:

Where docs live

Next

→ Routing & guards

Routing & guards

Routes are registered on a RouteBuilder inside .routing(|r| { ... }).

HTTP methods

#![allow(unused)]
fn main() {
r.get("/items", handler);
r.post("/items", handler);
r.put("/items/{id}", handler);
r.patch("/items/{id}", handler);
r.delete("/items/{id}", handler);
// and other methods supported by the builder
}

Path parameters

Segments in {braces} are captured and available via the Path extractor:

#![allow(unused)]
fn main() {
r.get("/users/{id}", |Path(id): Path<u64>| async move {
    format!("user #{id}")
});
}

Path supports scalars, tuples, and structs that deserialize from path parts.

Catch-all segments

A trailing {name...} matches the rest of the path (used by static file serving):

#![allow(unused)]
fn main() {
r.get(
    "/{path...}",
    StaticFiles::dir("./public").index("index.html").handler(),
);
}

Requires the fs feature for StaticFiles.

Automatic HEAD and OPTIONS

Churust provides correct HTTP behavior out of the box:

• Automatic HEAD for GET routes
• Automatic OPTIONS, including OPTIONS *
• One Allow header that both 405 and OPTIONS agree on

Route guards

Several routes may share a path when a guard distinguishes them, for example guard::header, guard::host, or a custom predicate. The first matching route with a satisfied guard wins; ambiguity is refused rather than guessed.

Path policy

PathPolicy decides what happens to non-canonical paths such as //a or /a//b:

Silent collapsing can make prefix-based auth checks bypassable and cache identity ambiguous — prefer strict or explicit redirects.

Configure via churust.toml (path_policy) or the builder DSL. See Configuration keys.

Mounting groups

Compose related routes under a prefix when the API grows; keep handlers small and push shared middleware with intercept where you need route-tree-scoped behavior (see Pipeline & plugins).

Next

→ Handlers & extractors

Handlers & extractors

A handler is an async closure or function that returns anything implementing IntoResponse. Arguments are extractors.

Two styles

Call-style — take the whole Call:

#![allow(unused)]
fn main() {
r.get("/", |_call: Call| async { "ok" });
}

Extractor-style — declare only what you need:

#![allow(unused)]
fn main() {
r.get(
    "/greet",
    |Query(s): Query<Search>, g: State<Greeter>| async move {
        format!("{}, {}!", g.prefix, s.q)
    },
);
}

You can mix both styles across the app freely.

Extractor categories

FromCallParts (request head)

Borrow the request head. Usable in any argument position:

FromCall (request body)

Consume the body. Last argument only — the body is a one-shot stream:

The split is enforced by the compiler, not convention: two body-consuming arguments do not compile. Every FromCallParts type is also usable last.

Optional extractors

Wrap any extractor that implements OptionalFromCallParts in Option<T> (Query, Path, Header, BearerToken, …):

• Absent → None
• Malformed → still an error

A typo’d query string does not quietly become a default.

Hybrid example

#![allow(unused)]
fn main() {
r.post(
    "/notes",
    |Principal(_admin): Principal<AdminUser>,
     s: State<Store>,
     Json(input): Json<NewNote>| async move {
        // ...
        (StatusCode::CREATED, Json(note))
    },
);
}

Here auth and state come from parts; the JSON body is last.

Handler return types

Anything IntoResponse:

• &str / String / Bytes
• StatusCode
• (StatusCode, T)
• Json<T> (feature json)
• Response (fully controlled)
• Streaming via Response::stream and Body::from_stream

Errors in handlers

Implement IntoError on your error type so ? works in handlers without leaking internal Display text to clients. See Responses & errors.

Next

→ Responses & errors

Responses & errors

Building responses

Handlers return types that implement IntoResponse:

#![allow(unused)]
fn main() {
// 200 text/plain-ish defaults for strings
r.get("/ping", |_c: Call| async { "pong" });

// Explicit status + body
r.post("/items", |_c: Call| async {
    (StatusCode::CREATED, "created")
});

// JSON (feature `json`)
r.get("/note", |_c: Call| async {
    Json(serde_json::json!({ "ok": true }))
});
}

Streaming

Body is always available (no feature flag). Stream large or dynamic payloads without buffering everything in memory:

#![allow(unused)]
fn main() {
use churust::Body;

r.get("/numbers", |_c: Call| async {
    let chunks = futures_util::stream::iter(
        (1..=5).map(|i| Ok::<_, std::io::Error>(bytes::Bytes::from(format!("{i}\n")))),
    );
    Response::stream("text/plain", Body::from_stream(chunks))
});
}

Custom error pages

Use on_error on the app builder to render any 4xx / 5xx, including routing failures, with your own HTML or JSON.

With ContentNegotiation installed (feature json), errors can be rendered as JSON for API clients.

IntoError

Implement IntoError on your domain error type so handlers can use ?. Churust maps the error to an HTTP status and a safe client-facing body without exposing internal details from Display by default.

Transport-level errors

Security headers and limits apply even when a handler never runs — for example 413 (body too large), 400, and 408 produced by the transport. See Security defaults.

Correct HTTP semantics

• Conditional GET for static files (ETag / Last-Modified / 304)
• Byte ranges (206 / 416) for static files
• Ambiguous framing (both Transfer-Encoding and Content-Length) is refused so leftover bytes cannot become the next request behind a proxy
• Repeated query keys on a scalar field are an error, not silent first/last wins

Next

→ Pipeline & plugins

Pipeline & plugins

Churust borrows Ktor’s mental model: plugins install middleware into a named pipeline.

Phases

Phase order is fixed and deterministic, regardless of install order:

1. Setup
2. Monitoring
3. Plugins
4. Call
5. Fallback

Middleware owns the Call, may mutate it, call next.run(call), and post-process the Response (onion model).

Installing plugins

#![allow(unused)]
fn main() {
Churust::server()
    .install(CallLogging::new())
    .install(ContentNegotiation::new())
    .install(Cors::new().allow_origin("http://localhost:3000"))
    .install(Auth::bearer(|token: String| async move {
        (token == "admin-token").then(|| Admin { name: "admin".into() })
    }))
    .routing(|r| { /* ... */ })
}

Order of .install(...) can still matter for relative stacking within a phase, but you never get a surprise reordering across phases.

Built-in plugins (feature-gated)

See Plugins & features for one page per capability.

Scoped middleware

Use intercept when middleware should apply only to part of the route tree rather than the whole application.

Tower interoperability

With the tower integration path, you can run any tower::Service as middleware so tower-http layers work without Churust reimplementing them.

Writing your own plugin

Implement the Plugin trait: register one or more Middleware values into the phase that matches their job (logging → Monitoring, auth → Plugins, etc.). Keep side effects explicit and prefer failing at startup when configuration is invalid.

Next

→ State & configuration

State & configuration

Typed app state

Attach shared state with .state(T), then extract it with State<T>:

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct Greeter {
    prefix: String,
}

Churust::server()
    .state(Greeter {
        prefix: "Hello".into(),
    })
    .routing(|r| {
        r.get(
            "/greet",
            |Query(s): Query<Search>, g: State<Greeter>| async move {
                format!("{}, {}!", g.prefix, s.q)
            },
        );
    })
}

T must be Send + Sync + 'static. Use interior mutability (Mutex, RwLock, channels, etc.) when handlers need to update shared data.

You can register multiple distinct state types; extractors select by type.

Layered configuration

Precedence (lowest → highest):

1. Built-in defaults
2. churust.toml
3. Environment variables (CHURUST_*)
4. Code DSL (.host(), .port(), …)

churust.toml

[server]
host = "0.0.0.0"
port = 8080
max_body_bytes = 1048576
request_timeout_ms = 30000
keep_alive_ms = 75000
max_connections = 25000
max_tls_handshakes = 256
tls_handshake_timeout_ms = 10000
shutdown_timeout_ms = 30000
path_policy = "strict"         # strict | redirect | collapse

[tls]            # requires the `tls` feature
cert = "cert.pem"
key  = "key.pem"

Loading config

#![allow(unused)]
fn main() {
Churust::from_config() // churust.toml + env
    .host("127.0.0.1") // DSL wins
    .port(8080)
    .routing(|r| { /* ... */ })
    .start()
    .await
}

Environment example: CHURUST_SERVER_PORT=9090.

Code-only

#![allow(unused)]
fn main() {
Churust::server()
    .host("127.0.0.1")
    .port(8080)
}

Deployment knobs

Useful builder / config fields include:

• Idle keep-alive
• Listen backlog
• Connection cap
• TLS handshake cap and timeout (bounds queueing as well as the handshake)
• HTTP/2 stream and header limits
• Shutdown grace period (bounded drain)
• Multiple bind addresses
• Unix domain sockets that refuse to unlink a live socket

Full key list: Configuration keys.

Cookies & sessions

Core includes a cookie primitive with safe defaults (HttpOnly, SameSite=Lax) and HMAC-SHA256 signed cookie sessions. For revocable server-side sessions, use Redis sessions (redis feature).

Next

→ Testing with TestClient

Testing with TestClient

Drive the full pipeline in-process without binding a socket.

Basic usage

Build an App with .build() instead of .start(), then wrap it:

use churust::prelude::*;
use churust::TestClient;

#[churust::main]
async fn main() {
    let app = Churust::server()
        .routing(|r| {
            r.get("/ping", |_c: Call| async { "pong" });
        })
        .build();

    let res = TestClient::new(app).get("/ping").send().await;
    assert_eq!(res.status(), StatusCode::OK);
    assert_eq!(res.text(), "pong");
}

In real tests, use your test harness’s async runtime (for example #[tokio::test] or Churust’s main only in binaries).

Requests

#![allow(unused)]
fn main() {
let client = TestClient::new(app);

let res = client
    .post("/notes")
    .header("authorization", "Bearer admin-token")
    .header("content-type", "application/json")
    .body(r#"{"text":"hi"}"#)
    .send()
    .await;

assert_eq!(res.status(), StatusCode::CREATED);
}

Helpers include get, post, put, delete, and a generic request(method, uri).

Assertions

#![allow(unused)]
fn main() {
res.status()
res.headers()
res.header("content-type")
res.body_bytes()
res.text()
}

Tips

• Install the same plugins your production app uses so tests exercise CORS, auth, and content negotiation.
• Prefer small pure handlers plus a thin fn app() -> App factory shared by binary and tests.
• Failures at startup (duplicate routes, missing static root) surface when you call .build() / .start() — keep that in CI.

Next

→ Plugins overview

Plugins & features overview

Everything below is opt-in. Core routing and handlers work with zero features. Enable only what you need.

Plugin crates (via churust features)

features = ["full"] enables: json, logging, cors, auth, ratelimit, compression, templates.

Transport / core features

Pattern

churust = { version = "0.3", features = ["json", "auth"] }

#![allow(unused)]
fn main() {
use churust::prelude::*;

Churust::server()
    .install(/* plugins */)
    .routing(|r| { /* routes that use extractors from those plugins */ })
}

Full matrix: Feature flags.

JSON & content negotiation

feature: json

Enable

churust = { version = "0.3", features = ["json"] }

Json<T>

Extractor (request body) and responder (response body):

#![allow(unused)]
fn main() {
use churust::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct NewNote { text: String }

#[derive(Serialize)]
struct Note { id: u64, text: String }

r.post("/notes", |Json(input): Json<NewNote>| async move {
    let note = Note { id: 1, text: input.text };
    (StatusCode::CREATED, Json(note))
});
}

Json<T> consumes the body — use it as the last handler argument (or only body consumer).

ContentNegotiation

Install so errors and negotiated responses can render as JSON for API clients:

#![allow(unused)]
fn main() {
.install(ContentNegotiation::new())
}

With auth (typed principal)

#![allow(unused)]
fn main() {
r.post(
    "/notes",
    |Principal(_a): Principal<Admin>,
     Json(input): Json<NewNote>| async move {
        Json(input)
    },
);
}

Requires auth as well as json. Full walkthrough: JSON API recipe.

API reference

• docs.rs/churust-json

Logging & request IDs

feature: logging

Enable

churust = { version = "0.3", features = ["logging"] }

Install

#![allow(unused)]
fn main() {
.install(CallLogging::new())
}

CallLogging uses the tracing ecosystem for structured request logs.

Request correlation

Churust attaches a request id to every log line, echoes it as x-request-id, and continues an inbound W3C traceparent when present. That behavior is part of the core request path; pair it with CallLogging for readable structured logs in development and production.

Tips

• Configure a tracing subscriber in main (or your process bootstrap) so logs actually appear.
• Prefer request ids over grepping timestamps when correlating client and server logs.

API reference

• docs.rs/churust-logging

CORS

feature: cors

Enable

churust = { version = "0.3", features = ["cors"] }

Restrictive (recommended for production)

Cors::new() starts with no allowed origins, GET/POST only, no credentials. Name the origins your browser client is actually served from:

#![allow(unused)]
fn main() {
.install(
    Cors::new()
        .allow_origin("http://localhost:3000")
        .allow_origin("https://app.example.com")
)
}

Chain builder methods for methods, headers, credentials, and max-age as needed (see docs.rs).

Development / public read-only APIs

#![allow(unused)]
fn main() {
.install(Cors::allow_any_origin_insecure())
}

The name is deliberate: reflecting any origin is fine for a public, unauthenticated, read-only API and convenient locally. It is dangerous if ambient credentials (cookies, extension-injected tokens) can authorize requests.

Note: Access-Control-Allow-Origin: * cannot be combined with credentials. Use an explicit origin list and .allow_credentials(true) when you need cookies on cross-origin calls.

Preflight

The plugin handles CORS preflight (OPTIONS) according to the configured policy.

API reference

• docs.rs/churust-cors

Authentication

feature: auth

Enable

churust = { version = "0.3", features = ["auth"] }

Model

1. Install an Auth plugin that verifies credentials and produces a principal type P.
2. Handlers that need authentication take Principal<P>.
3. If verification failed or the header was missing, the handler never runs — the client gets 401. Auth is enforced by the type system, so you cannot “forget” the check on a protected route.

Bearer

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct Admin { name: String }

.install(Auth::bearer(|token: String| async move {
    (token == "admin-token").then(|| Admin { name: "admin".into() })
}))
.routing(|r| {
    r.get("/me", |Principal(u): Principal<Admin>| async move { u.name });
})
}

curl -H 'authorization: Bearer admin-token' localhost:8080/me

Production warning

Do not compare tokens with == against a hard-coded secret in real apps. Use churust::secure_compare (or constant-time compare against a store) so timing does not leak how much of a guess was right.

Basic

#![allow(unused)]
fn main() {
.install(
    Auth::basic(|user, pass| async move {
        // Only over TLS — Basic is reversibly encoded, not encrypted.
        verify_user(user, pass).await
    })
    // Named in the 401 challenge; browsers show it in the login dialog.
    .realm("admin area"),
)
}

An unauthenticated request to a Principal-protected route answers 401 with WWW-Authenticate: Basic realm="…". The realm defaults to restricted. Install Basic and Bearer together and a 401 offers both challenges, in installation order.

JWT

Auth::jwt(...) validates JWTs and exposes claims as the principal. See docs.rs/churust-auth for the builder and claim types.

Login / logout layer

Churust also provides an identity layer over sessions with absolute and idle deadlines. Pair with cookie sessions or Redis when you need server-side revocation.

Example

Full JSON CRUD with bearer auth: examples/api and the JSON API recipe.

API reference

• docs.rs/churust-auth

Rate limiting

feature: ratelimit

Enable

churust = { version = "0.3", features = ["ratelimit"] }

Install

GCRA-based limiting — bursts are smoothed and Retry-After is exact rather than estimated:

#![allow(unused)]
fn main() {
use std::time::Duration;

.install(
    RateLimit::per_minute(60)
        .burst(10)
)
}

Helpers: RateLimit::per_second, per_minute, per_hour, or RateLimit::per(limit, period).

Keying

By default keys use the peer address. IPv6 peers are bucketed by network prefix (typically /64), because a subscriber is handed a whole prefix and limiting each address separately limits nobody.

Custom keys (return None to skip limiting for that request):

#![allow(unused)]
fn main() {
.install(
    RateLimit::per_minute(60).by(|call| {
        // e.g. API key header
        call.header("x-api-key").map(str::to_owned)
    })
)
}

Tuning

API reference

• docs.rs/churust-ratelimit

Compression

feature: compression

Enable

churust = { version = "0.3", features = ["compression"] }

Install

Negotiates Accept-Encoding and compresses response bodies (including streams) with brotli, gzip, and/or deflate:

#![allow(unused)]
fn main() {
.install(
    Compression::new()
        .min_size(1024)
        .level(Level::Default)
)
}

Options

compressible_by_default(content_type) documents which media types compress by default.

API reference

• docs.rs/churust-compression

Templates

feature: templates

Enable

churust = { version = "0.3", features = ["templates"] }

Setup

Templates are parsed at startup (fail fast). Output is HTML-escaped for safety regardless of the template file name, because the rendered response is served as HTML either way.

#![allow(unused)]
fn main() {
// From directory
let templates = Templates::from_dir("templates")?;

// Or build incrementally
let templates = Templates::new()
    .add("hello", "Hello, {{ name }}!")?;

// Optional minijinja environment tweaks
let templates = templates.configure(|env| {
    // env.add_filter(...);
});
}

Install as a plugin so handlers receive a Renderer:

#![allow(unused)]
fn main() {
.install(templates)
}

Render in a handler

#![allow(unused)]
fn main() {
r.get("/", |r: Renderer| async move {
    r.render("hello", context! { name => "Churust" })
});
}

Renderer::render / render_with_status return a Response. The context! macro is provided by the templates crate (re-exported through the umbrella when the feature is on — check prelude / crate docs for the exact import path in your version).

API reference

• docs.rs/churust-templates

Redis sessions

feature: redis

Enable

churust = { version = "0.3", features = ["redis"] }

Why Redis?

Cookie-only sessions cannot be revoked from the server without a shared store. RedisStore is a revocable server-side SessionStore: logging out actually invalidates the session, and a revocation that could not be carried out is an error rather than a cheerful 200 over a session that is still live.

Construct

#![allow(unused)]
fn main() {
use churust::prelude::*;
// Redis client type comes from the redis crate dependency of churust-redis

let client = redis::Client::open("redis://127.0.0.1/")?;
let store = RedisStore::from_client(client)
    .ttl(3600)
    .prefix("churust:sess:")
    .sliding(true);
}

Wire the store into your session / login configuration as documented on docs.rs for the version you ship.

API reference

• docs.rs/churust-redis

HTTP client

feature: client client-tls for HTTPS

Enable

churust = { version = "0.3", features = ["client"] }
# HTTPS:
churust = { version = "0.3", features = ["client-tls"] }

Overview

Outbound client built on the same hyper stack as the server: pooled, bounded, with transparent gzip/deflate decode and a decompression-bomb ceiling.

#![allow(unused)]
fn main() {
use churust::client::Client; // path may be re-exported via prelude when feature is on

let client = Client::new()
    .timeout(std::time::Duration::from_secs(10))
    .user_agent("my-app/0.1")?;

let res = client
    .get("https://httpbin.org/get")
    .header("x-request-id", "demo")
    .send()
    .await?;

println!("{} {}", res.status(), res.text()?);
}

Builder highlights

Request builder

#![allow(unused)]
fn main() {
client.post("https://api.example.com/items")
    .bearer(token)
    .json(&payload)
    .send()
    .await?;
}

Also: .query, .form, .body, .put, .patch, .delete, .head.

API reference

• docs.rs/churust-client

OpenAPI

feature: openapi

Implies json.

Enable

churust = { version = "0.3", features = ["openapi"] }

Idea

Generate an OpenAPI 3.1 document from the router. Paths and parameters come from routes; prose and schemas come from you. Drift is reported in both directions:

• undescribed() — routes missing documentation
• stale() — documented operations that no longer exist on the router

Build a document

#![allow(unused)]
fn main() {
use churust::prelude::*;
use http::Method;

let doc = OpenApi::new("Notes API", "0.1.0")
    .description("CRUD notes")
    .server("http://localhost:8080", Some("local"))
    .from_routes(&routes) // or build from your RouteBuilder export
    .operation(
        Method::POST,
        "/notes",
        Operation::new()
            .summary("Create note")
            .accepts("application/json")
            .response(201, "Created"),
    );
}

Mount the JSON document on a path:

#![allow(unused)]
fn main() {
// Inside routing, e.g.:
doc.mount(&mut r, "/openapi.json");
}

Exact mount helpers may take the document by reference — see docs.rs for the signature on your version.

Workflow tip

Fail CI if undescribed() or stale() is non-empty so the document cannot rot silently.

API reference

• docs.rs/churust-openapi

WebSockets

feature: ws

Enable

churust = { version = "0.3", features = ["ws"] }

Upgrade

A handler takes WebSocketUpgrade and calls on_upgrade. A plain GET to the route is rejected with 426 Upgrade Required.

#![allow(unused)]
fn main() {
use churust::prelude::*;
use churust::ws::{Message, WebSocketUpgrade};

r.get("/echo", |ws: WebSocketUpgrade| async move {
    ws.on_upgrade(|mut sock| async move {
        while let Some(Ok(msg)) = sock.recv().await {
            if matches!(msg, Message::Close) || sock.send(msg).await.is_err() {
                break;
            }
        }
    })
});
}

Broadcast room

Hold a broadcast channel in app state and select! between socket reads and channel receives. See the full example:

• Source: examples/chat
• Recipe: Chat room

cargo run -p chat
websocat ws://localhost:8080/echo
websocat ws://localhost:8080/room

Use churust::tokio for broadcast and select! — no separate tokio dependency required.

Limits

WebSocket frame and message caps are part of the secure defaults. WebSockets over HTTP/3 (Extended CONNECT) are not supported yet — see What is not supported.

API reference

• docs.rs/churust (ws module when feature is enabled)

Static files & streaming

feature: fs for StaticFiles · Body is always available

Enable static files

churust = { version = "0.3", features = ["fs"] }

Serve a directory

#![allow(unused)]
fn main() {
use churust::prelude::*;

r.get(
    "/{path...}",
    StaticFiles::dir("./public").index("index.html").handler(),
);
}

Behavior:

• Content-Type from file extension
• Optional directory index
• Path traversal (.., absolute paths, symlink escapes) → 404
• Streams file content in chunks
• Conditional GET (ETag / Last-Modified / 304) and byte ranges (206 / 416)

mkdir -p public && echo '<h1>Churust</h1>' > public/index.html
cargo run -p static-example
curl localhost:8080/
# Traversal rejected (curl otherwise normalizes ".." away):
curl -i --path-as-is 'localhost:8080/../Cargo.toml'   # 404

A missing static root fails at startup, not silently at runtime.

Streaming dynamic bodies

No feature flag:

#![allow(unused)]
fn main() {
use churust::Body;

r.get("/numbers", |_c: Call| async {
    let chunks = futures_util::stream::iter(
        (1..=5).map(|i| Ok::<_, std::io::Error>(bytes::Bytes::from(format!("{i}\n")))),
    );
    Response::stream("text/plain", Body::from_stream(chunks))
});
}

Example

examples/static · SPA recipe

Multipart uploads

feature: multipart

Enable

churust = { version = "0.3", features = ["multipart"] }

Two APIs

Both parse multipart/form-data. Prefer the streaming API for large uploads.

Body size still applies

Streaming changed what an upload costs in memory, not what it is allowed to weigh. max_body_bytes still bounds every request.

Handler sketch

#![allow(unused)]
fn main() {
// Buffered
r.post("/upload", |form: Multipart| async move {
    // iterate fields...
    StatusCode::NO_CONTENT
});

// Streamed — keep MultipartStream as the body extractor (last arg)
// r.post("/upload", |stream: MultipartStream| async move { ... });
}

Check docs.rs for the exact field iteration APIs on your version.

Non-goal

multipart/byteranges for multi-range requests is intentionally unsupported (RFC 9110 permits omitting it). See non-goals.

API reference

• docs.rs/churust / churust-core multipart module

TLS

feature: tls

Enable

churust = { version = "0.3", features = ["tls"] }

Config file

# churust.toml
[tls]
cert = "cert.pem"
key  = "key.pem"

#![allow(unused)]
fn main() {
Churust::from_config()
    .routing(|r| { /* ... */ })
    .start()
    .await
}

Programmatic

Use the core helper to build a rustls acceptor from PEM files (see acceptor_from_pem on docs.rs) and the builder’s TLS setters for your version.

Knobs

Both also bound QUIC handshakes when the http3 feature is on: a QUIC handshake is a TLS 1.3 handshake, asymmetric in the same way.

HTTP/2 over TLS is negotiated via ALPN. Plaintext h2c uses prior knowledge.

Production tips

• Prefer a reverse proxy (Caddy, nginx, Traefik) for cert automation when that fits your deploy model — or terminate TLS in-process with rustls when you need end-to-end in one binary.
• Never enable HTTP Basic auth without TLS.

Related

• HTTP/3 (requires TLS material for QUIC)
• Deployment

HTTP/3

feature: http3

Implies tls / QUIC credentials.

Enable

churust = { version = "0.3", features = ["http3"] }

What you get

HTTP/3 over QUIC on its own listener. Use advertise_http3 so responses can emit the Alt-Svc header clients need in order to try h3.

Setup sketch

1. Enable the feature and provide TLS certificates suitable for QUIC.
2. Configure the h3 listener (bind address + server config from PEM helpers in core).
3. Enable advertisement so browsers/clients discover the endpoint.

Exact builder methods live on docs.rs for your version (server_config_from_pem, h3 bind helpers).

Which [server] knobs apply

Enabling http3 starts a second listener, and a setting that reached only the TCP one would be a bound you believed you had. These all apply here:

header_read_timeout_ms is not applied here. Abandoning a request whose HEADERS frame never arrives leaks its stream id inside the h3 crate, which stops the connection ever closing — worse than the stall it would bound. What bounds the exposure instead is h2_max_concurrent_streams per connection and max_connections overall.

Two things behave differently here, both deliberately:

• keep_alive_ms = 0 has no QUIC meaning — a connection multiplexes streams and cannot close after one response — so the listener keeps the default 75000 ms idle bound instead.
• h2_max_concurrent_streams = 0 means "no limit" on HTTP/2 and cannot be translated: quinn allocates one slot per advertised stream when it builds a connection, so advertising a varint maximum is a four-quintillion-iteration loop triggered by the first packet from any peer. The listener keeps the default 200 instead.
• A request body is collected before dispatch, where the TCP path streams it. That is what lets a truncated body be refused before a handler ever runs on a fragment, which is undetectable afterwards because a truncated body is just a shorter body. The cost is one max_body_bytes per in-flight request.

serve reads these from the app. If you build a quinn::ServerConfig yourself and use serve_with_config, the transport parameters are yours — the per-stream deadlines still apply.

Limits

WebSockets over HTTP/3 (RFC 9220 Extended CONNECT) are not implemented; the ws feature uses the HTTP/1.1 upgrade handshake.

API reference

• docs.rs/churust-core http3 module

Recipe: JSON API

Build a small notes API with logging, CORS, JSON, and bearer auth — the same shape as examples/api.

Dependencies

[dependencies]
churust = { version = "0.3", features = ["full"] }
serde = { version = "1", features = ["derive"] }

Code

use churust::prelude::*;
use serde::{Deserialize, Serialize};
use std::sync::Mutex;

#[derive(Clone, Serialize, Deserialize)]
struct Note {
    id: u64,
    text: String,
}

#[derive(Deserialize)]
struct NewNote {
    text: String,
}

#[derive(Clone, Debug)]
struct AdminUser {
    _name: String,
}

struct Store {
    notes: Mutex<Vec<Note>>,
}

#[churust::main]
async fn main() -> std::io::Result<()> {
    Churust::server()
        .host("127.0.0.1")
        .port(8080)
        .state(Store {
            notes: Mutex::new(Vec::new()),
        })
        .install(CallLogging::new())
        .install(ContentNegotiation::new())
        .install(Cors::new().allow_origin("http://localhost:3000"))
        .install(Auth::bearer(|token: String| async move {
            // Demo only — use secure_compare + a real store in production.
            if token == "admin-token" {
                Some(AdminUser {
                    _name: "admin".into(),
                })
            } else {
                None
            }
        }))
        .routing(|r| {
            r.get("/notes", |s: State<Store>| async move {
                let notes = s.notes.lock().unwrap().clone();
                Json(notes)
            });
            r.post(
                "/notes",
                |Principal(_admin): Principal<AdminUser>,
                 s: State<Store>,
                 Json(input): Json<NewNote>| async move {
                    let mut notes = s.notes.lock().unwrap();
                    let id = notes.len() as u64 + 1;
                    let note = Note {
                        id,
                        text: input.text,
                    };
                    notes.push(note.clone());
                    (StatusCode::CREATED, Json(note))
                },
            );
        })
        .start()
        .await
}

Try it

cargo run -p api   # from the Churust repo

curl localhost:8080/notes
# []

curl -X POST localhost:8080/notes -d '{"text":"hi"}'
# {"error":"authentication required","status":401}

curl -X POST localhost:8080/notes \
  -H 'authorization: Bearer admin-token' \
  -H 'content-type: application/json' \
  -d '{"text":"hi"}'
# {"id":1,"text":"hi"}

Takeaways

• Principal<AdminUser> makes the POST route uncallable without auth.
• ContentNegotiation keeps error bodies JSON-friendly.
• CORS names real browser origins — not * — when credentials matter.

Recipe: chat room

WebSocket echo + broadcast room from examples/chat.

Dependencies

[dependencies]
churust = { version = "0.3", features = ["ws"] }

Code

use churust::prelude::*;
use churust::tokio::sync::broadcast;
use churust::ws::{Message, WebSocketUpgrade};
use std::sync::Arc;

#[derive(Clone)]
struct Room {
    tx: Arc<broadcast::Sender<String>>,
}

#[churust::main]
async fn main() -> std::io::Result<()> {
    let (tx, _rx) = broadcast::channel::<String>(100);
    Churust::server()
        .host("127.0.0.1")
        .port(8080)
        .state(Room { tx: Arc::new(tx) })
        .routing(|r| {
            r.get("/echo", |ws: WebSocketUpgrade| async move {
                ws.on_upgrade(|mut sock| async move {
                    while let Some(Ok(msg)) = sock.recv().await {
                        if matches!(msg, Message::Close) {
                            break;
                        }
                        if sock.send(msg).await.is_err() {
                            break;
                        }
                    }
                })
            });

            r.get(
                "/room",
                |room: State<Room>, ws: WebSocketUpgrade| async move {
                    let tx = room.tx.clone();
                    let mut rx = tx.subscribe();
                    ws.on_upgrade(move |mut sock| async move {
                        loop {
                            churust::tokio::select! {
                                incoming = sock.recv() => match incoming {
                                    Some(Ok(Message::Text(t))) => { let _ = tx.send(t); }
                                    Some(Ok(Message::Close)) | None => break,
                                    Some(Err(_)) => break,
                                    _ => {}
                                },
                                outgoing = rx.recv() => {
                                    if let Ok(text) = outgoing {
                                        if sock.send_text(text).await.is_err() { break; }
                                    }
                                }
                            }
                        }
                    })
                },
            );
        })
        .start()
        .await
}

Try it

cargo run -p chat
websocat ws://localhost:8080/echo
# two terminals:
websocat ws://localhost:8080/room

Plain HTTP GET → 426 Upgrade Required.

Recipe: SPA & static assets

Serve a frontend build directory and optional dynamic routes.

Dependencies

[dependencies]
churust = { version = "0.3", features = ["fs"] }

Pattern

use churust::prelude::*;

#[churust::main]
async fn main() -> std::io::Result<()> {
    Churust::server()
        .host("0.0.0.0")
        .port(8080)
        .routing(|r| {
            // API routes first
            r.get("/api/health", |_c: Call| async { "ok" });

            // Then the SPA / asset root
            r.get(
                "/{path...}",
                StaticFiles::dir("./dist").index("index.html").handler(),
            );
        })
        .start()
        .await
}

Notes

• Register API routes before the catch-all /{path...}.
• index("index.html") covers directory and SPA entry.
• For client-side routers that need “fallback to index.html on 404”, confirm whether your Churust version’s StaticFiles supports a fallback option; if not, serve index.html from a custom handler for unknown GET paths.
• Path traversal is rejected; the directory you pass is the whole reachable tree (symlinks that escape the root are refused).

Streaming alongside static

See examples/static for Body::from_stream next to StaticFiles.

Recipe: deployment

Binary

cargo build --release -p my-api
# target/release/my-api

Pin features you actually need to keep compile times and attack surface small.

Configuration in production

Prefer env over baking secrets into images:

export CHURUST_SERVER_HOST=0.0.0.0
export CHURUST_SERVER_PORT=8080
export CHURUST_SERVER_MAX_BODY_BYTES=2097152
./my-api

Or ship a churust.toml next to the binary and override with env/DSL as needed. See Configuration keys.

Process model

Reverse proxy sketch (nginx)

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # WebSockets:
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

If you rate-limit by peer address behind a proxy, key on a trusted forwarded client IP header instead of the proxy’s address — use RateLimit::by(...).

Containers

FROM rust:1.96 as build
WORKDIR /app
COPY . .
RUN cargo build --release -p my-api

FROM gcr.io/distroless/cc-debian12
COPY --from=build /app/target/release/my-api /my-api
ENV CHURUST_SERVER_HOST=0.0.0.0
ENV CHURUST_SERVER_PORT=8080
EXPOSE 8080
CMD ["/my-api"]

Adjust the runtime image for your glibc/musl and TLS needs.

Checklist

• Features limited to production needs
• Body/timeout/connection caps set consciously
• CORS origins are explicit
• Secrets via env or secret manager
• Security headers left on (see Security defaults)
• Health/readiness probes
• Load test with realistic keep-alive and payload sizes

Performance

Churust is fast, and this page is about being precise rather than loud: what was measured, against what, on what, and what the number does not cover.

Linux 6.12, server pinned to CPUs 0–7 and the load generator to 8–11, 64 keep-alive connections, one server running at a time, order rotated each round. Three routes returning constants. Full method: benchmarks/README.md.

actix-web leads on all three columns. Churust is not the fastest Rust web framework on this workload and this page will say so until it is.

axum, Ktor and Go were measured on an earlier eight-worker configuration and have not been re-run against this harness; their figures live in benchmarks/results/ rather than in this table, because quoting a number measured under one configuration beneath a table built under another is exactly how the corrections further down this page became necessary.

Read this before quoting the table

Worker count moves these numbers more than most code changes do. Both servers default to one worker per core; on this machine that default sits at different distances from each framework's optimum, so a default-vs-default table measures the defaults. Everything above is at four workers for every server. run_sharded(0) picks one per core, which is a starting point rather than an answer — sweep it for your hardware.

Nine rounds because fewer is not enough. Three consecutive five-round runs of identical code put Churust 3.6% ahead, then 11% ahead, then 5.9% behind; the between-run spread on this machine is wider than most of what is being measured. Read the ranges in benchmarks/results/, not just the medians.

A caveat on the throughput column specifically. CPU/req × req/s gives cores consumed: bare hyper 3.65, actix-web 3.85, Churust 3.98, all on four workers. Churust's workers are saturated while the other two have headroom, which raises the possibility that their throughput is bounded by the four-thread load generator rather than by the server. The CPU-per-request figures are measured directly and do not depend on saturation, so they are the ones to trust; the throughput ordering may be partly an artifact of the harness.

Sharding is a choice you make, and it is a large one. The same code on the same cores, with and without connection pinning — both figures from the earlier eight-worker run, kept because the comparison is the point and both sides were measured together:

1.94× the throughput, and better tail latency too once the per-connection handoff and the connection loop's per-wake bookkeeping were removed. Pinning a connection to one runtime for its life means a request waits for that worker rather than being picked up by whichever is idle.

With pipelining the order changes. actix-web reaches 5.96M requests a second against Churust's 4.45M — 1.34× — and does it on 1.14 µs of CPU per request against 1.70. Pipelining is not the shape most traffic has, which is why it is not the headline, but it is where Churust's dispatch path is furthest behind.

That gap is Churust's own, and it took a floor to find out. This page used to say the difference was hyper's HTTP/1 implementation against actix-http's, reasoning that Churust's dispatch layer measures 393 ns in isolation so the remainder had to belong to the stack underneath. That was arithmetic, not a measurement, and it was wrong. benchmarks/bench-hyper now runs the comparison against hyper and tokio with no framework on top — same routes, same responses, same one-runtime-per-core shape — and hyper is not the bottleneck:

hyper answers a request for less CPU than actix-web does, so it was never what the gap was made of. Churust's own layer costs 0.80 µs per request on top of the hyper it runs on, and that is the whole of the distance to actix-web.

The first 0.22 µs of that came back from one line. tokio::time::timeout takes its future by value, and the future it was being handed is the entire request — the pipeline, the handler, and the Call threaded through both, 2,616 bytes of it. Every request memcpy'd all of that into the timeout wrapper. Pinning it first (std::pin::pin!) hands over a Pin<&mut _> instead, and the future stays where it was already built. Churust went from 5.10 to 4.87 µs per request and 781,872 to 814,690 req/s, with the confirming run's slowest round faster than the old best one.

Where the 0.79 µs goes, and what it would take to close it.

Half of it is Churust's dispatch layer and half is the engine around it:

(Two figures have been published for dispatch, 393 ns and 672 ns, and both are right about different applications. benches/dispatch.rs builds the default server, which installs the security-headers middleware — a layer measuring 268–301 ns that bench-churust turns off. Measured in the wire configuration, dispatch is ~400 ns.)

First place is not reachable by making dispatch faster. Matching actix-web means shedding 790 − 120 = 670 ns, and the entire dispatch layer is ~400. A dispatch layer that cost nothing would leave Churust at 4.47 µs against actix's 4.20.

That is worth stating plainly because the obvious redesign was prototyped rather than assumed. Replacing Arc<dyn Handler> and the per-layer Pin<Box<dyn Future>> with monomorphised static dispatch measures 20 ns — and it inlines every handler's state machine into the request future, working against the only change this session that measurably helped. actix-web pays more vtable dispatches and more allocations per request than Churust does and is still faster. Erasure is not where the money is.

What is reachable without touching the public API is 60–110 ns (~1.7%): dropping #[async_trait] from the extractor traits, and router work — FxHash, inline path segments, fusing the three separate scans over the path.

And the largest single win does not show up on this page's charts at all, because it is disabled in the benchmark: the default configuration pays 268–301 ns for security headers, and on the plaintext path applies them twice — once in the middleware, once in the transport — where the second pass reserves six header slots on a map that already holds them, forcing a grow and a rehash to discover there is nothing to do. Every real deployment pays that; no benchmark here measures it.

axum's last place there is not about its routing — the keep-alive table shows that is fine. hyper answers each request in a pipelined batch with its own flush, and axum::serve exposes no way to turn the aggregation on, so a batch of 16 costs it 16 write syscalls. Churust can be asked (pipeline_flush).

Numbers move between runs, so read the ranges. The published figures are medians of five rounds with the running order rotated; the results file carries the spread for every row, and any row whose rounds differed by more than 3× is flagged rather than averaged into respectability.

Every route returns a constant. This measures dispatch overhead and says nothing about an application that talks to a database.

Getting the throughput in your own application

The measured configuration is not the default, on purpose. Three knobs:

App::run_sharded — one runtime per core

The default App::start runs every connection on one shared work-stealing runtime. That balances perfectly, and it lets a connection's read wakeup, its handler and its write each land on a different thread — an atomic, a cache miss and usually a syscall per hop. run_sharded gives each worker its own single-threaded runtime and pins a connection to one for its life.

use churust::prelude::*;
fn main() -> std::io::Result<()> {
    let app = Churust::server()
        .routing(|r| { r.get("/", |_c: Call| async { "hi" }); })
        .build();
    app.run_sharded(0) // 0 = one worker per core
}

Note there is no #[churust::main]: run_sharded builds and owns its runtimes, and wrapping it in another one leaves a multi-threaded runtime idling underneath the single-threaded ones doing the work.

Measured against the shared runtime: 1.94× the throughput (391k → 758k), and tail latency improved as well (444 µs → 246 µs). With per-connection affinity a worker whose connections are busy cannot borrow an idle worker's core, so a request that lands on a busy worker waits.

Choose run_sharded when throughput is the constraint and the requests are many, short and uniform. Keep start — the default — when the slowest percentile is a number anyone looks at.

pipeline_flush — only if your clients pipeline

#![allow(unused)]
fn main() {
use churust::prelude::*;
let _ =
Churust::server().pipeline_flush(true)
;
}

Answers a batch of pipelined requests with one flush instead of one per response. Off by default because a client that does not pipeline then waits for a flush that only comes once the connection has nothing left to read: measured on loopback with one request in flight, a median 90µs instead of 56µs. Turn it on only if you know the traffic pipelines.

tcp_nodelay — on by default, leave it

Nagle's algorithm holds a small write waiting for more to send while the peer's delayed ACK holds the acknowledgement waiting for a response; the standoff breaks on a timer. Churust disables it on every accepted connection. The only workload that wants it back is pipelining, and pipeline_flush gets the same coalescing without giving up the latency guarantee.

Where the speed-up came from

None of it was in routing or extraction, which is where a profiler points first:

1. Removing per-request atomics from shared cache lines. The request path cloned the application handle five times per request; each clone is an atomic read-modify-write on one cache line that every core is also writing to. Twelve workers sharing one application reached 1.29M req/s where twelve processes not sharing it reached 2.07M — the same code on the same cores, differing only in whether one integer was contended.
2. One runtime per core with connections pinned (run_sharded), with the latency cost documented above.
3. Dropping a per-request allocation in the extension map, plus the router, pipeline and response-body allocations listed in the changelog.
4. TCP_NODELAY on by default, which it should always have been.

On pipelined load the multiple is far larger — aggregating flushes is worth 4.1× on its own — but that is a workload most services do not have, and the 1.94× above is the one to plan around.

Running it yourself

docker build -f benchmarks/Dockerfile -t churust-bench .   # from the repo root
docker run --rm churust-bench

Docker is the supported path because the kernel matters more than anything else here: on macOS the loopback saturates around 45–50k round-trips a second, below what any of these servers can answer, and every framework reports the same number. The same Churust binary measures 47k there and 691k on Linux.

The harness refuses to measure unless all five apps return byte-identical responses on every route, so a result you get is a result about dispatch and not about servers doing different work. docker run -e APPS="churust axum" … runs a subset.

Feature flags

All features on the churust crate. Default features are empty.

Plugins

Data & docs

Transports

Examples

churust = "0.3"
churust = { version = "0.3", features = ["full"] }
churust = { version = "0.3", features = ["full", "ws", "fs", "tls"] }
churust = { version = "0.3", features = ["client-tls", "openapi"] }

Lockstep versioning: every churust-* crate shares the umbrella version.

Crate map

Dependency graph (conceptual)

your-app
   └── churust (umbrella)
         ├── churust-core
         ├── churust-macros
         └── optional plugin crates (features)

Prefer churust = { features = [...] } over depending on plugin crates directly so versions stay aligned.

Configuration keys

Loading

#![allow(unused)]
fn main() {
Churust::from_config() // defaults < churust.toml < env < later DSL
}

Environment variables use the CHURUST_ prefix with nested keys separated by _. Example: CHURUST_SERVER_PORT=9090.

[server]

Header-read timeouts cover a connection from accept time, so a peer that connects and stays silent is still bounded (slow-loris protection). It does not apply to HTTP/3 — see HTTP/3 for why, and for what bounds that transport instead.

Which transports a knob reaches

One setting should mean one thing on every transport this server speaks, so unless noted below a [server] key applies to HTTP/1.1, HTTP/2 and HTTP/3 alike. Two deliberate differences are worth knowing:

• keep_alive_ms = 0 means "answer and close". HTTP/1.1 closes after the response and HTTP/2 closes once nothing is in flight. A QUIC connection multiplexes streams and cannot be closed after a single response, so there is nothing for the setting to mean there — the HTTP/3 listener keeps the default 75000 ms idle bound rather than never expiring, which would leave a connection holding a max_connections permit for good.
• h2_max_concurrent_streams is named for HTTP/2 and also caps concurrent request streams per HTTP/3 connection. 0 means unlimited on HTTP/2 only: QUIC allocates against whatever cap is advertised, so HTTP/3 keeps the default.

An HTTP/3 request body is collected before the request is dispatched, where the TCP path streams it to the handler. That is what lets a body truncated mid-flight be refused without the handler running on a fragment, and the cost is one max_body_bytes per in-flight request — bounded by h2_max_concurrent_streams × max_connections.

[tls]

Requires the tls feature.

Example file

[server]
host = "0.0.0.0"
port = 8080
max_body_bytes = 1048576
request_timeout_ms = 30000
keep_alive_ms = 75000
max_connections = 25000
max_tls_handshakes = 256
tls_handshake_timeout_ms = 10000
shutdown_timeout_ms = 30000
path_policy = "strict"

[tls]
cert = "cert.pem"
key  = "key.pem"

Additional knobs (HTTP/2 limits, multi-bind, Unix sockets, backlog) may be available on the builder — see docs.rs/churust-core and State & configuration.

Security defaults

Churust aims to be secure by default. This page summarizes guarantees you get without turning on optional features.

Always on

Cookies

Cookie helper defaults: HttpOnly, SameSite=Lax. Prefer signed sessions; use Redis when revocation must be real.

Secrets

Use secure_compare for token/password compares. Never use plain == on secrets in production examples you copy forward.

Auth

• Bearer / Basic / JWT behind auth
• Basic only over TLS
• Principal<P> so protected handlers cannot forget the check

CORS

Default builder is restrictive (no origins). Wildcard allow_any_origin_insecure is explicit and uncomfortable on purpose.

TLS / HTTP

• Opt-in rustls TLS
• Ambiguous Transfer-Encoding + Content-Length refused
• WebSocket frame/message caps when ws is enabled

Static files

Traversal and symlink escape → 404. Missing root fails at startup.

What security is not

Churust does not replace:

• Application authorization design
• Secrets management
• Dependency auditing (cargo audit)
• Network policy / WAF

See also What is not supported.

What is not supported

Deliberate scope choices and known gaps. Tracked in detail in the production-readiness audit and roadmap.

On purpose

Pre-1.0

The public API may break in minor releases until 1.0. Pin versions in production and read the changelog.

Want something sooner?

Make the case in Discussions → Ideas.

Changelog & migration

Releases

Full history lives in the repository:

CHANGELOG.md

Current series documented in this guide: 0.3.x.

How Churust versions

• All churust* crates share one version (lockstep).
• Pre-1.0: breaking changes may appear in minor bumps (0.3 → 0.4).
• Prefer caret pins on the minor you tested: churust = "0.3".

Migrating between minors

1. Read the changelog section for the target version.
2. cargo update -p churust (or bump the pin) and rebuild with -D warnings if you match project CI.
3. Re-run examples or your TestClient suite.
4. Check renamed APIs (example: CORS permissive → allow_any_origin_insecure in 0.3).

docs.rs

API docs for every published version:

• https://docs.rs/churust

This book

The site tracks main of the guide source under book/. Older framework versions may differ slightly; when in doubt, match code samples to the crate version on crates.io.

Contributing

Contributions are welcome. Read the full guide first:

CONTRIBUTING.md

Short version

• Churust keeps a narrow scope
• Tests come first
• Anything optional is feature-gated so default builds never change
• Warnings are errors in CI
• MSRV is 1.96

Before you open a PR

Run the full gate listed in CONTRIBUTING (fmt, clippy feature matrix, test matrix, examples, docs). For this documentation site:

cargo install mdbook --locked --version 0.4.48   # once
cd book && mdbook build

Channels

Design specs live under docs/design/ (internal milestones, not product version numbers).

Support

Start here

Question or bug?

Use Discussions for “how do I…” or “is this supposed to…”. Use Issues when you can show something is broken.

Making questions answerable

Include:

• Churust version and enabled features
• rustc --version
• Smallest code that shows the problem
• Expected vs actual behavior
• Full error text

Response times

Maintained in spare time. Expect a few days; security reports follow SECURITY.md.

Sponsor

GitHub Sponsors funds maintenance, not feature bounties. Features are decided on merit in Discussions.

Full text: SUPPORT.md.