https://github.com/matteopolak/axum-codec
A multi-codec extractor and response writer for Axum.
https://github.com/matteopolak/axum-codec
axum bincode bitcode cbor json msgpack rust
Last synced: 2 months ago
JSON representation
A multi-codec extractor and response writer for Axum.
- Host: GitHub
- URL: https://github.com/matteopolak/axum-codec
- Owner: matteopolak
- License: apache-2.0
- Created: 2024-07-09T20:03:59.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-02-22T17:42:48.000Z (4 months ago)
- Last Synced: 2025-04-02T12:04:32.812Z (2 months ago)
- Topics: axum, bincode, bitcode, cbor, json, msgpack, rust
- Language: Rust
- Homepage: https://crates.io/crates/axum-codec
- Size: 242 KB
- Stars: 12
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# Axum Codec
[](https://crates.io/crates/axum-codec)
[](https://docs.rs/axum-codec/latest/axum_codec/)
[](https://github.com/matteopolak/axum-codec/actions)
A body extractor for the [Axum](https://github.com/tokio-rs/axum) web framework.
## Features
- Supports encoding and decoding of various formats with a single extractor.
- Provides a wrapper for [`axum::routing::method_routing`](https://docs.rs/axum/latest/axum/routing/method_routing/index.html) 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.
```rust
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 {
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) -> 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`](https://github.com/serde-rs/json) support.
- `form`: Enables [`x-www-form-urlencoded`](https://github.com/nox/serde_urlencoded) support.
- `msgpack`: Enables [`MessagePack`](https://github.com/3Hren/msgpack-rust) support.
- `bincode`: Enables [`Bincode`](https://github.com/bincode-org/bincode) support.
- `bitcode`: Enables [`Bitcode`](https://github.com/SoftbearStudios/bitcode) support.
- `yaml`: Enables [`YAML`](https://github.com/dtolnay/serde-yaml/releases) support.
- `toml`: Enables [`TOML`](https://github.com/toml-rs/toml) support.
- `aide`: Enables support for the [`Aide`](https://github.com/tamasfe/aide) documentation library.
- `validator`: Enables support for the [`Validator`](https://github.com/Keats/validator) validation library, validating all input when extracted with `Codec`.
\* 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.