Expand description
§axum-serde-boundary
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 byContent-Type(JSON by default;MessagePackand 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 validatedMediaTypeplus a streaming format (serde-stream-formats) and a payload-or-envelope mode, with a per-entry error-rendering policy.negotiate(accept)settles oneNegotiatedbefore 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 aResponseEnvelopewith the error’sHttpErrorContractstatus, typedCODE_*wire code, and optionalretry-after.204 No Contentstays 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:
- Apache License, Version 2.0 (
LICENSE-APACHE); - MIT License (
LICENSE-MIT).
§Links
Structs§
- Boundary
Rejection - A boundary failure raised by an extractor, rendered as the typed JSON error envelope.
- Error
Body - The machine-readable error contract carried by every error response (and by failure envelopes).
- Field
Error - One invalid field in a request body.
- Invalid
Media Type - Why a media type was rejected.
- Invalid
Response Table - Why a response table was rejected at construction.
- Media
Type - A validated, concrete
type/subtypemedia type — the one media-type value shared across the negotiation family: representation declarations here, response tables andContent-Typestamps in boundary crates. - Negotiated
- The settled outcome of negotiation: everything response rendering needs, detached from the table.
- Response
Envelope - The envelope-mode response body: the payload (on success) or the error contract (on failure), plus bounded operation metadata.
- Response
Representation - One declared response representation: the media type
Acceptselects (and the successContent-Typestamp), the streaming format that renders it, the payload/envelope mode, and how errors render when this representation is negotiated. - Response
Table - The application’s response representations in server preference
order. The first entry is the contract default: it serves absent
and empty
Acceptheaders, and wildcard ranges resolve to it. - Serde
Body - A typed request body decoded in the structured format named by the
request’s
Content-Type. - Validation
Details - Field-level detail for a request validation failure.
Enums§
- Boundary
Error - A failure at the Serde HTTP boundary.
- Response
Mode - How the typed result is represented on the wire.
Traits§
- Http
Error Contract - 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 asmedia_type.