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.

Todo

• Support bitcode, bincode, ciborium, rmp, toml, serde_yaml, and serde_json
• Add custom MethodRouter to automatically encode responses in the correct format
• Add macro to derive all enabled formats for a struct/enum
• Add support for aide
• Add support for validator
• Support more formats (issues and PRs welcome)
• Add benchmarks?

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::{
  handler::IntoCodecResponse,
  routing::{get, post},
  Codec,
  extract::Accept,
};

// Shorthand for the following (assuming all features are enabled):
//
// #[derive(
//   serde::Serialize, serde::Deserialize,
//   bincode::Encode, bincode::Decode,
//   bitcode::Encode, bitcode::Decode,
// )]
// #[serde(crate = "...")]
// #[bincode(crate = "...")]
//
// NOTE: `bitcode` does not support `#[bitcode(crate = "...)]` yet,
// so the dependency must be specified in your `Cargo.toml` if enabled (and using this macro).
// Same goes for `validator`.
#[axum_codec::apply(encode, decode)]
struct User {
  name: String,
  age: u8,
}

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

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

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

/// Specify `impl IntoCodecResponse`, similar to `axum`
async fn greet(Codec(user): Codec<User>) -> impl IntoCodecResponse {
  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::post(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.
• msgpack: Enables MessagePack support.
• bincode: Enables Bincode support.
• bitcode: Enables Bitcode support.
• cbor: Enables CBOR 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.

License

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

Re-exports

• pub use extract::Accept;
• pub use handler::CodecHandler;

Modules

• extract
• handler
• routing

Structs

• Codec
  Codec extractor / response.

Enums

• CodecRejection
  Rejection used for Codec.
• ContentType

Traits

• CodecDecode
• CodecEncode

Attribute Macros

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