Crate axum_codec

Axum Codec

A body extractor for the Axum web framework.

Features

• Supports encoding and decoding of various formats with a single extractor.
• Provides a wrapper for axum::routing::method_routing to automatically encode responses in the correct format according to the specified Accept header (with a fallback to Content-Type, then one of the enabled formats).
• Provides an attribute macro (under the macros feature) to add derives for all enabled formats to a struct/enum.
• Zero-copy decoding with BorrowCodec.

Here’s a quick example that can do the following:

• Decode a User from the request body in any of the supported formats.
• Encode a Greeting to the response body in any of the supported formats.

use axum::{Router, response::IntoResponse};
use axum_codec::{
  response::IntoCodecResponse,
  routing::{get, post},
  Codec, Accept,
};

// Shorthand for the following (assuming all features are enabled):
//
// #[derive(
//   serde::Serialize, serde::Deserialize,
//   bincode::Encode, bincode::Decode,
//   bitcode::Encode, bitcode::Decode,
//   validator::Validate,
// )]
// #[serde(crate = "...")]
// #[bincode(crate = "...")]
// #[bitcode(crate = "...")]
// #[validator(crate = "...")]
#[axum_codec::apply(encode, decode)]
struct User {
  name: String,
  age: u8,
}

async fn me() -> Codec<User> {
  Codec(User {
    name: "Alice".into(),
    age: 42,
  })
}

/// A manual implementation of the handler above.
async fn manual_me(accept: Accept) -> impl IntoResponse {
  Codec(User {
    name: "Alice".into(),
    age: 42,
  })
  .into_codec_response(accept.into())
}

#[axum_codec::apply(encode)]
struct Greeting {
  message: String,
}

/// Specify `impl IntoCodecResponse`, similar to `axum`
async fn greet(Codec(user): Codec<User>) -> impl IntoCodecResponse {
  Codec(Greeting {
    message: format!("Hello, {}! You are {} years old.", user.name, user.age),
  })
}

#[tokio::main]
async fn main() {
  let app: Router = Router::new()
    .route("/me", get(me).into())
    .route("/manual", axum::routing::get(manual_me))
    .route("/greet", post(greet).into());

  let listener = tokio::net::TcpListener::bind(("127.0.0.1", 3000))
    .await
    .unwrap();

  // axum::serve(listener, app).await.unwrap();
}

Feature flags

• macros: Enables the axum_codec::apply attribute macro.
• json*: Enables JSON support.
• form: Enables x-www-form-urlencoded support.
• msgpack: Enables MessagePack support.
• bincode: Enables Bincode support.
• bitcode: Enables Bitcode support.
• yaml: Enables YAML support.
• toml: Enables TOML support.
• aide: Enables support for the Aide documentation library.
• validator: Enables support for the Validator validation library, validating all input when extracted with Codec<T>.

* Enabled by default.

A note about #[axum::debug_handler]

Since axum-codec uses its own IntoCodecResponse trait for encoding responses, it is not compatible with #[axum::debug_handler]. However, a new #[axum_codec::debug_handler] (and #[axum_codec::debug_middleware]) macro is provided as a drop-in replacement.

Roadmap

• Add codec! macro for defining custom codecs that use a different subset of enabled formats.

License

Dual-licensed under MIT or Apache License v2.0.

Re-exports

pub use extract::BorrowCodec;

pub use extract::Codec;

pub use handler::CodecHandler;

pub use rejection::CodecRejection;

pub use response::IntoCodecResponse;

pub use axum_codec_macros as macros;

Modules

extract

handler

rejection

response

routing

Structs

Accept

Extractor for the request’s desired response ContentType.

Enums

ContentType

Traits

CodecDecode

Decoder trait for deserializing bytes into all supported formats.

CodecEncode

Encoder trait for encoding a value into any supported format.

Attribute Macros

apply

A utility macro for automatically deriving the correct traits depending on the enabled features.

debug_handler

Generates better error messages when applied to handler functions.

debug_middleware

Generates better error messages when applied to middleware functions.