Module server 

Typed, fluent HTTP server construction.

This module provides a builder-oriented API for declaring HTTP routes and serving them with warp under the hood. 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 with a single .await. Graceful shutdown is available via Server::serve_with_graceful_shutdown and Server::serve_from_listener.

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<()> (VEIL-decrypted body)
.encrypted_query::<T>(key).onconnect(f)	T: bincode::Decode<()> (VEIL-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) — VEIL-decrypted body
.state(s).encrypted_query::<T>(key).onconnect(f)	(S, T) — VEIL-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:

// Fluent form:
// server.mechanism(
//     ServerMechanism::post("/items")
//         .json::<NewItem>()
//         .onconnect(|body: NewItem| async move {
//             reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
//         })
// );

// Equivalent attribute form:
#[mechanism(server, POST, "/items", json)]
async fn create(body: NewItem) {
    reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
}

See the mechanism item for the full syntax reference.

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

EncryptedBodyBuilder

Route builder that expects a VEIL-encrypted request body of type T.

EncryptedQueryBuilder

Route builder that expects VEIL-encrypted URL query parameters of type T.

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.

Server

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

ServerMechanism

Entry point for building an HTTP route.

StatefulEncryptedBodyBuilder

Route builder carrying shared state S and a VEIL-encrypted request body of type T.

StatefulEncryptedQueryBuilder

Route builder carrying shared state S and VEIL-encrypted query parameters of type T.

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.

Functions

reply

Returns an empty 200 OK warp 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 warp result.

reply_with_json

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

reply_with_status

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

reply_with_status_and_json

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

Type Aliases

SocketType

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

Attribute Macros

mechanism

Concise route declaration for toolkit-zero socket-server routes.