Module server 

Typed, fluent HTTP server construction.

This module provides a builder-oriented API for declaring HTTP routes and serving them with a built-in hyper-based HTTP engine. The entry point for every route is ServerMechanism, which pairs an HTTP method with a URL path and supports incremental enrichment — attaching a JSON body expectation, URL query parameter deserialisation, or shared state — before being finalised into a SocketType route handle via onconnect.

Completed routes are registered on a Server and served via one of the serve* methods, each of which returns a ServerFuture. A ServerFuture can be .await’d to run the server inline or called .background() on to spawn it as a background Tokio task and get a tokio::task::JoinHandle back. Graceful shutdown is available via Server::serve_with_graceful_shutdown and Server::serve_from_listener.

For runtime address migration, use Server::serve_managed: it starts the server immediately and returns a BackgroundServer handle that supports BackgroundServer::rebind (graceful shutdown + restart on a new address, all existing routes preserved) and BackgroundServer::stop.

Hot-reloading routes

BackgroundServer::mechanism pushes a new route into the running server’s shared route table without any restart or port gap. Because routes are stored in an Arc<RwLock<Vec<SocketType>>> shared between the caller and the server loop, the new route becomes visible to the next incoming request immediately.

Builder chains at a glance

Chain	Handler receives
ServerMechanism::method(path).onconnect(f)	nothing
.json::<T>().onconnect(f)	T: DeserializeOwned
.query::<T>().onconnect(f)	T: DeserializeOwned
.encryption::<T>(key).onconnect(f)	T: bincode::Decode<()> (decrypted body)
.encrypted_query::<T>(key).onconnect(f)	T: bincode::Decode<()> (decrypted query)
.state(s).onconnect(f)	S: Clone + Send + Sync
.state(s).json::<T>().onconnect(f)	(S, T)
.state(s).query::<T>().onconnect(f)	(S, T)
.state(s).encryption::<T>(key).onconnect(f)	(S, T) — decrypted body
.state(s).encrypted_query::<T>(key).onconnect(f)	(S, T) — decrypted query

For blocking handlers (not recommended in production) every finaliser also has an unsafe onconnect_sync counterpart.

#[mechanism] attribute macro

As an alternative to spelling out the builder chain by hand, the mechanism attribute macro collapses the entire server.mechanism(ServerMechanism::method(path) … .onconnect(handler)) call into a single decorated async fn.

Response helpers

Use the [reply!] macro as the most concise way to build a response:

// 200 OK, empty body
// reply!()
// 200 OK, JSON body
// reply!(json => item)
// 201 Created, JSON body
// reply!(json => item, status => Status::Created)

Re-exports

pub use super::SerializationKey;

Structs

BackgroundServer

A managed, background HTTP server returned by Server::serve_managed.

EmptyReply

An empty 200 OK reply — returned by reply!().

EncryptedBodyBuilder

Route builder that expects an authenticated-encrypted request body of type T (ChaCha20-Poly1305).

EncryptedQueryBuilder

Route builder that expects authenticated-encrypted URL query parameters of type T (ChaCha20-Poly1305).

HtmlReply

An HTML body reply — returned by html_reply.

JsonSocketBuilder

Route builder that expects and deserialises a JSON request body of type T.

QuerySocketBuilder

Route builder that expects and deserialises URL query parameters of type T.

Rejection

An HTTP-level error value returned from route handlers.

Server

The HTTP server that owns and dispatches a collection of SocketType routes.

ServerFuture

Opaque future returned by Server::serve, Server::serve_with_graceful_shutdown, and Server::serve_from_listener.

ServerMechanism

Entry point for building an HTTP route.

SocketType

A fully assembled, type-erased HTTP route ready to be registered on a Server.

StatefulEncryptedBodyBuilder

Route builder carrying shared state S and an authenticated-encrypted request body of type T (ChaCha20-Poly1305).

StatefulEncryptedQueryBuilder

Route builder carrying shared state S and authenticated-encrypted query parameters of type T (ChaCha20-Poly1305).

StatefulJsonSocketBuilder

Route builder that carries shared state S and expects a JSON body of type T.

StatefulQuerySocketBuilder

Route builder that carries shared state S and expects URL query parameters of type T.

StatefulSocketBuilder

Route builder that carries shared state S with no body or query expectation.

Enums

Status

A collection of common HTTP status codes used with the reply helpers.

Traits

Reply

A value that can be converted into a fully-formed HTTP response.

Functions

forbidden

Returns a 403 Forbidden rejection.

html_reply

Wraps content into a 200 OK HTML response.

reply

Returns an empty 200 OK reply result.

reply_sealed

Seals value with key and returns it as an application/octet-stream response (200 OK).

reply_sealed_with_status

Seals value with key, attaches the given HTTP status, and returns it as a result.

reply_with_json

Serialises json as a JSON body and returns it as a 200 OK reply result.

reply_with_status

Wraps reply with the given HTTP status code and returns it as a result.

reply_with_status_and_json

Serialises json as a JSON body, attaches the given HTTP status, and returns a result.

Attribute Macros

mechanism

Declare a server-side route.