Crate axum_valid

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

Modules

• extra
  Support for extractors from axum-extra
• form
  Support for Form<T>
• json
  Support for Json<T>
• msgpack
  Support for MsgPack<T> and MsgPackRaw<T> from axum-msgpack
• path
  Support for Path<T>
• query
  Support for Query<T>
• typed_header
  Support for TypedHeader<T>
• typed_multipart
  Support for TypedMultipart<T> and BaseMultipart<T, R> from axum_typed_multipart
• yaml
  Support for Yaml<T> from axum-yaml

Structs

• Valid
  Valid data extractor
• ValidEx
  ValidEx data extractor

Enums

• ValidRejection
  ValidRejection is returned when the Valid extractor fails.

Constants

• VALIDATION_ERROR_STATUS
  Http status code returned when there are validation errors.

Traits

• Arguments
  Arguments provides the validation arguments for the data type T.
• HasValidate
  Trait for types that can supply a reference that can be validated.
• HasValidateArgs
  Trait for types that can supply a reference that can be validated using arguments.