Skip to main content

Crate axum_serde_boundary

Crate axum_serde_boundary 

Source
Expand description

§axum-serde-boundary

Crates.io Documentation CI License Downloads

A typed Serde HTTP boundary for axum: streaming request-body extraction, Accept-negotiated streaming responses, and a machine-readable error envelope.

Handlers return Result<Dto, DomainError>; this crate settles which representation goes on the wire and renders it — without the handler parsing headers, choosing a serializer, or ever materializing a body:

  • SerdeBody<T> — decodes the request body in the format named by Content-Type (JSON by default; MessagePack and Postcard supported), incrementally on a blocking worker: the HTTP task never owns the complete body. Failures are typed — 415 for an unsupported media type, 413 when the body limit trips, 400 with decoder detail — and always carry the error envelope, never plain text.
  • ResponseTable — the application’s declared representations in preference order, each a validated MediaType plus a streaming format (serde-stream-formats) and a payload-or-envelope mode, with a per-entry error-rendering policy. negotiate(accept) settles one Negotiated before the domain operation runs, so an unsatisfiable request 406es up front.
  • Negotiated::respond(result) — streams the success payload in the negotiated format (bounded chunks, backpressure; a serialization failure surfaces as a typed body error, never a silent truncation), or renders the failure as a ResponseEnvelope with the error’s HttpErrorContract status, typed CODE_* wire code, and optional retry-after. 204 No Content stays bodyless.
  • ResponseEnvelope<T> / ErrorBody — the envelope shape: payload or error plus at most 16 warnings; error codes are always typed constants, and applications extend the set with their own.
use axum_serde_boundary::{
    MediaType, ResponseMode, ResponseRepresentation, ResponseTable, SerdeBody,
};
use serde_stream_formats::EncodeFormat;

let table = ResponseTable::try_new(vec![
    ResponseRepresentation::new(
        MediaType::try_new("application/json")?,
        EncodeFormat::Json,
        ResponseMode::Payload,
    ),
    ResponseRepresentation::new(
        MediaType::try_new("application/vnd.example.envelope+json")?,
        EncodeFormat::Json,
        ResponseMode::Envelope,
    ),
])?;

// In a handler:
async fn create(body: SerdeBody<Point>) -> axum::response::Response {
    let negotiated = table.negotiate(Some("application/json")).unwrap();
    negotiated.respond::<_, axum_serde_boundary::BoundaryError>(Ok(body.0))
}

Everything streams: responses are encoded through a bounded channel (64 KiB chunks) and requests are decoded from the live stream. There is no Vec<u8> of a whole body anywhere on the success path — the one deliberate exception is the error envelope, which is small, bounded, and encoded before headers are sent so the status is always truthful.

§License

Licensed under either of:

Structs§

BoundaryRejection
A boundary failure raised by an extractor, rendered as the typed JSON error envelope.
ErrorBody
The machine-readable error contract carried by every error response (and by failure envelopes).
FieldError
One invalid field in a request body.
InvalidMediaType
Why a media type was rejected.
InvalidResponseTable
Why a response table was rejected at construction.
MediaType
A validated, concrete type/subtype media type — the one media-type value shared across the negotiation family: representation declarations here, response tables and Content-Type stamps in boundary crates.
Negotiated
The settled outcome of negotiation: everything response rendering needs, detached from the table.
ResponseEnvelope
The envelope-mode response body: the payload (on success) or the error contract (on failure), plus bounded operation metadata.
ResponseRepresentation
One declared response representation: the media type Accept selects (and the success Content-Type stamp), the streaming format that renders it, the payload/envelope mode, and how errors render when this representation is negotiated.
ResponseTable
The application’s response representations in server preference order. The first entry is the contract default: it serves absent and empty Accept headers, and wildcard ranges resolve to it.
SerdeBody
A typed request body decoded in the structured format named by the request’s Content-Type.
ValidationDetails
Field-level detail for a request validation failure.

Enums§

BoundaryError
A failure at the Serde HTTP boundary.
ResponseMode
How the typed result is represented on the wire.

Traits§

HttpErrorContract
How a domain error crosses the HTTP boundary: its status code, its typed CODE_* wire code, and its client-consumable error body.

Functions§

render_error
Render an error body as a failure envelope in format, stamped as media_type.