Crate churust_core

Expand description

Churust core kernel: the engine, routing, request pipeline, and extractors that power the Churust web framework.

Churust is a Ktor-inspired, async-first web framework for Rust. This crate (churust-core) is the foundation every other Churust crate builds on. It provides:

A fluent Churust::server builder (AppBuilder) for assembling an App from routes, shared state, middleware, and configuration.
A trie-based Router supporting static segments, {param} captures, and trailing {name...} wildcards.
The per-request Call context — the single object every handler receives.
An onion-style middleware pipeline ordered by Phase.
Type-safe extractors (Path, Query, State, BearerToken) plus the FromCall/FromCallParts traits that let handlers take typed arguments.
A flexible Response/IntoResponse model and a status-carrying Error type.
Layered Config loading (defaults < churust.toml < CHURUST_* env < code) and optional TLS (feature tls).
An in-process TestClient for fast, socket-free integration tests.

§Example

Build an app, register a route, and exercise it with the in-process test client (no socket is bound, so this runs in any environment):

use churust_core::{Churust, Call, TestClient};
let app = Churust::server()
    .routing(|r| {
        r.get("/", |_c: Call| async { "Hello, Churust!" });
    })
    .build();

let res = TestClient::new(app).get("/").send().await;
assert_eq!(res.status().as_u16(), 200);
assert_eq!(res.text(), "Hello, Churust!");

To actually serve traffic, call App::start (binds a socket and serves until Ctrl-C) or AppBuilder::start.

Re-exports§

pub use body::Body;
pub use error::Error;
pub use error::IntoError;
pub use error::Result;
pub use response::IntoResponse;
pub use response::Response;
pub use call::BodyStream;
pub use call::Call;
pub use call::Params;
pub use call::PeerAddr;
pub use handler::boxed;
pub use handler::BoxHandler;
pub use handler::Handler;
pub use handler::IntoHandler;
pub use state::StateMap;
pub use extract::check_body_limit;
pub use extract::BearerToken;
pub use extract::Either;
pub use extract::Form;
pub use extract::FromCall;
pub use extract::FromCallParts;
pub use extract::Header;
pub use extract::HeaderName;
pub use extract::OptionalFromCallParts;
pub use extract::Path;
pub use extract::Payload;
pub use extract::Query;
pub use extract::RouteBodyLimit;
pub use extract::State;
pub use path::PathPolicy;
pub use router::allow_header_value;
pub use router::Match;
pub use router::RouteBuilder;
pub use router::Router;
pub use pipeline::Endpoint;
pub use pipeline::Middleware;
pub use pipeline::Next;
pub use pipeline::Phase;
pub use config::Config;
pub use config::ServerSection;
pub use config::TlsSection;
pub use app::App;
pub use app::AppBuilder;
pub use app::Churust;
pub use app::Plugin;
pub use app::ServerConfig;
pub use security::SecurityHeaders;
pub use cookie::Cookie;
pub use cookie::SameSite;
pub use multipart::Field;
pub use multipart::Multipart;
pub use multipart::MultipartStream;
pub use multipart::Part;
pub use session::CookieStore;
pub use session::Session;
pub use session::SessionStore;
pub use session::Sessions;
pub use session::SESSION_ID_KEY;
pub use identity::Authenticated;
pub use identity::Identities;
pub use identity::Identity;
pub use guard::BoxGuard;
pub use guard::Guard;
pub use ws::WebSocket;
pub use ws::WebSocketUpgrade;
pub use fs::StaticFiles;
pub use test::TestClient;
pub use test::TestRequest;
pub use test::TestResponse;

Modules§

app: Application assembly: the Churust entry point, the AppBuilder DSL, the immutable App, the Plugin trait, and the resolved ServerConfig.
body: The response Body: either a fully-buffered Bytes payload or a lazy stream of byte chunks (for files, large/dynamic responses, SSE, etc.).
call: The per-request Call context — the single object every handler receives.
config: Layered configuration: defaults < churust.toml < env (CHURUST_*) < code.
cookie: Cookies: reading a request’s, and building Set-Cookie. Cookies: reading them off a request and building Set-Cookie.
engine: The hyper-based HTTP/1.1 serving engine that drives an App over a real socket.
error: The status-carrying Error type and the crate-wide Result alias.
extract: Extractors: typed handler arguments derived from a Call.
fs: Static file serving (feature fs).
guard: Route guards — predicates that select among routes sharing a method and path. Route guards: predicates that decide whether a registered route may serve a request, beyond matching its method and path.
handler: Handlers: the Handler trait, handler closures, and the glue that turns extractor closures into stored handlers.
http3: HTTP/3 over QUIC (feature http3). HTTP/3 over QUIC (feature http3).
identity: Login, logout, and the two deadlines that end a login. Who the visitor is: login, logout, and the two deadlines that end a login.
multipart: multipart/form-data bodies (feature multipart). multipart/form-data bodies (feature multipart) — file uploads.
path: Percent-decoding and canonicalisation for URL path segments. Percent-decoding for URL path segments.
pipeline: The request pipeline: Middleware, the Phase ordering, the Next continuation, and the Endpoint terminal.
response: The buffered Response type and the IntoResponse conversion trait.
router: The trie-based Router, its Match result, and the RouteBuilder DSL used inside AppBuilder::routing.
security: Security response headers applied by default. See SecurityHeaders. Security response headers, applied to every response by default.
session: Sessions carried by a cookie. Sessions: per-visitor state carried by a cookie.
state: Type-keyed shared application state (a minimal DI registry).
test: In-process test harness. Drives App::process directly — no socket bind.
tls: TLS support (feature tls). Loads a PEM cert chain + private key and builds a tokio_rustls::TlsAcceptor with rustls’ safe defaults.
tower: Run a tower::Service as Churust Middleware.
ws: WebSocket support (feature ws).

Functions§

block: Run a blocking operation without stalling the async runtime.
secure_compare: Compare two secrets without leaking their contents through timing.