axum-valid

This crate provides a Valid type for use with Json, Path, Query, and Form extractors to validate entities implementing the Validate trait from the validator crate.

A ValidEx type is also available. Similar to Valid, ValidEx can execute validations requiring extra arguments with types that implement the ValidateArgs trait from the validator crate.

Additional extractors such as TypedHeader, MsgPack, Yaml, and others are supported through optional features. The complete list of supported extractors can be found in the Features section below.

Basic usage

cargo add axum-valid

use validator::Validate;
use serde::Deserialize;
use axum_valid::Valid;
use axum::extract::Query;
use axum::{Json, Router};
use axum::routing::{get, post};

#[derive(Debug, Validate, Deserialize)]
pub struct Pager {
    #[validate(range(min = 1, max = 50))]
    pub page_size: usize,
    #[validate(range(min = 1))]
    pub page_no: usize,
}

pub async fn pager_from_query(
    Valid(Query(pager)): Valid<Query<Pager>>,
) {
    assert!((1..=50).contains(&pager.page_size));
    assert!((1..).contains(&pager.page_no));
}

pub async fn pager_from_json(
    Valid(Json(pager)): Valid<Json<Pager>>,
) {
    assert!((1..=50).contains(&pager.page_size));
    assert!((1..).contains(&pager.page_no));
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let router = Router::new()
        .route("/query", get(pager_from_query))
        .route("/json", post(pager_from_json));
    axum::Server::bind(&([0u8, 0, 0, 0], 8080).into())
        .serve(router.into_make_service())
        .await?;
    Ok(())
}

When validation errors occur, the extractor will automatically return 400 with validation errors as the HTTP message body.

To see how each extractor can be used with Valid, please refer to the example in the documentation of the corresponding module.

Argument-Based Validation

Here's a basic example of using the ValidEx extractor to validate data in a Form using arguments:

use axum::routing::post;
use axum::{Form, Router};
use axum_valid::{Arguments, ValidEx};
use serde::Deserialize;
use std::ops::{RangeFrom, RangeInclusive};
use validator::{Validate, ValidateArgs, ValidationError};

// NOTE: When some fields use custom validation functions with arguments,
// `#[derive(Validate)]` will implement `ValidateArgs` instead of `Validate` for the type.
// The validation arguments will be a tuple of all the field validation args.
// In this example it is (&RangeInclusive<usize>, &RangeFrom<usize>).
// For more detailed information and understanding of `ValidateArgs` and their argument types, 
// please refer to the `validator` crate documentation.
#[derive(Debug, Validate, Deserialize)]
pub struct Pager {
    #[validate(custom(function = "validate_page_size", arg = "&'v_a RangeInclusive<usize>"))]
    pub page_size: usize,
    #[validate(custom(function = "validate_page_no", arg = "&'v_a RangeFrom<usize>"))]
    pub page_no: usize,
}

fn validate_page_size(v: usize, args: &RangeInclusive<usize>) -> Result<(), ValidationError> {
    args.contains(&v)
        .then_some(())
        .ok_or_else(|| ValidationError::new("page_size is out of range"))
}

fn validate_page_no(v: usize, args: &RangeFrom<usize>) -> Result<(), ValidationError> {
    args.contains(&v)
        .then_some(())
        .ok_or_else(|| ValidationError::new("page_no is out of range"))
}

// NOTE: Clone is required
#[derive(Debug, Clone)]
pub struct PagerValidArgs {
    page_size_range: RangeInclusive<usize>,
    page_no_range: RangeFrom<usize>,
}

// NOTE: This implementation allows PagerValidArgs to be the second member of ValidEx, and provides arguments for actual validation.
// The type mapping <Pager as ValidateArgs<'a>>::Args represents the combination of validators applied on each field of Pager.
// get() method returns the validating arguments to be used during validation.
impl<'a> Arguments<'a> for PagerValidArgs {
    type T = Pager;

    // NOTE: <Pager as ValidateArgs<'a>>::Args == (&RangeInclusive<usize>, &RangeFrom<usize>)
    fn get(&'a self) -> <Pager as ValidateArgs<'a>>::Args {
        (&self.page_size_range, &self.page_no_range)
    }
}

pub async fn pager_from_form_ex(ValidEx(Form(pager), _): ValidEx<Form<Pager>, PagerValidArgs>) {
    assert!((1..=50).contains(&pager.page_size));
    assert!((1..).contains(&pager.page_no));
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let router = Router::new()
        .route("/form", post(pager_from_form_ex))
        .with_state(PagerValidArgs {
            page_size_range: 1..=50,
            page_no_range: 1..,
        });
    // NOTE: The PagerValidArgs can also be stored in a XxxState,
    // make sure it implements FromRef<XxxState>.

    axum::Server::bind(&([0u8, 0, 0, 0], 8080).into())
        .serve(router.into_make_service())
        .await?;
    Ok(())
}

Current module documentation predominantly showcases Valid examples, the usage of ValidEx is analogous.

Features

Feature	Description	Module	Default	Example	Tests
default	Enables support for Path, Query, Json and Form	[path], [query], [json], [form]	✅	✅	✅
json	Enables support for Json	[json]	✅	✅	✅
query	Enables support for Query	[query]	✅	✅	✅
form	Enables support for Form	[form]	✅	✅	✅
typed_header	Enables support for TypedHeader	[typed_header]	❌	✅	✅
typed_multipart	Enables support for TypedMultipart and BaseMultipart from axum_typed_multipart	[typed_multipart]	❌	✅	✅
msgpack	Enables support for MsgPack and MsgPackRaw from axum-msgpack	[msgpack]	❌	✅	✅
yaml	Enables support for Yaml from axum-yaml	[yaml]	❌	✅	✅
extra	Enables support for Cached, WithRejection from axum-extra	[extra]	❌	✅	✅
extra_typed_path	Enables support for T: TypedPath from axum-extra	[extra::typed_path]	❌	✅	✅
extra_query	Enables support for Query from axum-extra	[extra::query]	❌	✅	✅
extra_form	Enables support for Form from axum-extra	[extra::form]	❌	✅	✅
extra_protobuf	Enables support for Protobuf from axum-extra	[extra::protobuf]	❌	✅	✅
all_extra_types	Enables support for all extractors above from axum-extra	N/A	❌	✅	✅
all_types	Enables support for all extractors above	N/A	❌	✅	✅
422	Use 422 Unprocessable Entity instead of 400 Bad Request as the status code when validation fails	[VALIDATION_ERROR_STATUS]	❌	✅	✅
into_json	Validation errors will be serialized into JSON format and returned as the HTTP body	N/A	❌	✅	✅
full	Enables all features	N/A	❌	✅	✅

Compatibility

To determine the compatible versions of axum-valid, axum-extra, axum-yaml and other dependencies that work together, please refer to the dependencies listed in the Cargo.toml file. The version numbers listed there will indicate the compatible versions.

License

This project is licensed under the MIT License.

References

• axum
• validator
• serde
• axum-extra
• axum-yaml
• axum-msgpack
• axum_typed_multipart