arcly-http-core 0.6.1

Foundation crate for arcly-http: zero-lock DI engine, HTTP boundary, unified request pipeline, auth, resilience, observability, and OpenAPI. Use the `arcly-http` facade instead of depending on this directly.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//! `Validated<T>` -- type-branded, deserialized-and-validated request payload.
//!
//! Unlike the `#[Body] dto: T` shorthand (which validates silently), `Validated<T>`
//! makes the validation contract visible at the type level. Functions that only
//! accept pre-validated inputs declare `Validated<T>` in their signature;
//! the type system enforces the invariant across the call stack.
//!
//! ## Usage
//!
//! ```rust,ignore
//! async fn create_user(ctx: RequestContext) -> Result<Json<User>, HttpException> {
//!     let dto = Validated::<CreateUserDto>::from_body(&ctx)?;
//!     service.create(dto.into_inner()).await
//! }
//! ```
//!
//! ## RFC 7807 Error Shape
//!
//! Deserialize failure  -> `400 Bad Request`  (`bad-request` problem type)
//! Constraint violation -> `422 Unprocessable Entity` (`validation` problem type)
//!                         with per-field `errors` array

use std::ops::Deref;

use serde::de::DeserializeOwned;
use validator::Validate;

use crate::web::context::RequestContext;
use crate::web::error::{HttpException, Validation};
use crate::web::extract::{extract_body_json, extract_query};

// ─── The wrapper type ────────────────────────────────────────────────────────

/// A payload `T` that has been deserialized **and** validated.
///
/// Construction is possible only through [`from_body`](Self::from_body) or
/// [`from_query`](Self::from_query) (plus [`assume_valid`](Self::assume_valid)
/// for test fixtures). All other callers receive a `T` provably free of
/// constraint violations.
#[derive(Debug, Clone)]
pub struct Validated<T>(T);

impl<T> Validated<T> {
    /// Consume the wrapper, returning the validated inner value.
    #[inline]
    pub fn into_inner(self) -> T {
        self.0
    }

    /// Borrow the validated inner value.
    #[inline]
    pub fn inner(&self) -> &T {
        &self.0
    }

    /// Construct without validation -- use **only** in unit-test fixtures where
    /// the value is already known good. Never call in handler code.
    #[inline]
    pub fn assume_valid(v: T) -> Self {
        Self(v)
    }
}

impl<T> Deref for Validated<T> {
    type Target = T;
    #[inline]
    fn deref(&self) -> &T {
        &self.0
    }
}

// ─── Extraction from RequestContext ─────────────────────────────────────────

impl<T: DeserializeOwned + Validate> Validated<T> {
    /// Deserialize `T` from the JSON request body, then run `T::validate()`.
    ///
    /// Returns `Err(HttpException)` on either step, converting automatically
    /// into the RFC 7807 problem shape:
    ///
    /// | Failure             | Status | `type` field     |
    /// |---------------------|--------|------------------|
    /// | Malformed JSON      | 400    | `bad-request`    |
    /// | Constraint violated | 422    | `validation`     |
    pub fn from_body(ctx: &RequestContext) -> Result<Self, HttpException> {
        let v: T = extract_body_json(ctx)?;
        v.validate()
            .map_err(|e| HttpException::from(Validation::from(e)))?;
        Ok(Self(v))
    }

    /// Deserialize `T` from the URL query string, then validate.
    ///
    /// Same error shape as [`from_body`](Self::from_body).
    pub fn from_query(ctx: &RequestContext) -> Result<Self, HttpException> {
        let v: T = extract_query(ctx)?;
        v.validate()
            .map_err(|e| HttpException::from(Validation::from(e)))?;
        Ok(Self(v))
    }
}