webx_core/route/

binding.rs

//! Request model binding — the runtime half of `#[derive(WebxRequestMeta)]`.
//!
//! A request struct declares where each field comes from (`#[frompath]`,
//! `#[fromquery]`, `#[frombody]`, `#[fromform]`, `#[fromheader]`,
//! `#[fromclaim]`). The derive compiles that declaration into a
//! [`RequestModel::bind`] implementation; this module provides the value
//! providers and coercion helpers that implementation calls.
//!
//! # Why not `serde` for query/path/header/claim
//!
//! HTTP values are *strings*, often repeated (`?id=1&id=2`), and a failure in
//! one field must not hide the others. `serde_json` models documents, not HTTP
//! values, so it cannot coerce `"2"` into `u32`, cannot represent repeated keys,
//! and fails at the first error. Here every scalar is parsed with [`FromStr`],
//! lists keep every occurrence, and failures accumulate in a [`Binder`] so the
//! response can report all of them at once.
//!
//! JSON bodies stay with `serde`: the derive generates a hidden body struct
//! containing only the body-bound fields, so `rename`, `flatten`, `default` and
//! custom deserializers keep working exactly as written.

use crate::auth::IClaims;
use crate::error::{Error, Result};
use crate::form::{FormFile, MultipartForm};
use crate::http::IHttpContext;
use crate::problem::{FieldError, ProblemDetails};
use crate::route::scan::ParamMeta;
use std::collections::HashMap;
use std::future::Future;
use std::pin::Pin;
use std::str::FromStr;

/// Where a request field's value comes from.
///
/// [`Source::Auto`] is the absence of an explicit marker; the generated binder
/// then resolves it from the request method:
///
/// * `GET` / `HEAD` / `DELETE` / `OPTIONS` — query string, then the route;
/// * `POST` / `PUT` / `PATCH` — JSON body, then form, then query string;
/// * `multipart/form-data` — form, then query string.
///
/// Headers and claims are never implicit: a header or token that happens to
/// share a field name must not silently win.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Source {
    /// A `{name}` segment of the route template.
    Path,
    /// A query-string key (`?name=value`, repeatable).
    Query,
    /// A `multipart/form-data` part (text or file).
    Form,
    /// An HTTP header, looked up case-insensitively.
    Header,
    /// A claim from the authenticated principal.
    Claim,
    /// The JSON request body.
    Body,
    /// No marker: inferred from the request method.
    Auto,
}

impl Source {
    /// The OpenAPI `in` value (`""` for [`Source::Auto`], resolved per route).
    pub const fn as_str(self) -> &'static str {
        match self {
            Source::Path => "path",
            Source::Query => "query",
            Source::Form => "form",
            Source::Header => "header",
            Source::Claim => "claim",
            Source::Body => "body",
            Source::Auto => "",
        }
    }

    /// Whether an explicitly marked field must be present.
    pub const fn is_explicit(self) -> bool {
        !matches!(self, Source::Auto)
    }
}

/// Whether `method` carries a JSON body by default (ASP.NET Core's rule).
pub fn is_body_method(method: &str) -> bool {
    matches!(method, "POST" | "PUT" | "PATCH")
}

/// A type that can be constructed from an HTTP request.
///
/// Implemented by `#[derive(WebxRequestMeta)]`. The endpoint macros call
/// [`RequestModel::bind`] before dispatching to the handler, so a request type
/// without the derive does not compile.
///
/// ```ignore
/// #[derive(Default, Deserialize, WebxRequestMeta)]
/// pub struct GetUserRequest {
///     #[frompath]
///     pub id: String,
///     #[fromquery]
///     pub expand: Option<String>,
/// }
/// ```
#[diagnostic::on_unimplemented(
    message = "`{Self}` cannot be bound from an HTTP request",
    label = "add `#[derive(WebxRequestMeta)]` to this request struct",
    note = "the endpoint macros call `RequestModel::bind`; the derive is what implements it"
)]
pub trait RequestModel: Sized + Send + 'static {
    /// OpenAPI parameter metadata for this request type.
    ///
    /// Sources are `"path"`, `"query"`, `"header"`, `"form"`, `"body"`,
    /// `"claim"`, or `""` for an unmarked field resolved by the route method.
    fn param_meta() -> &'static [ParamMeta];

    /// Bind an instance from the live request context.
    fn bind<'a>(
        ctx: &'a mut dyn IHttpContext,
    ) -> Pin<Box<dyn Future<Output = Result<Self>> + Send + 'a>>;
}

/// The value providers a generated [`RequestModel::bind`] reads from.
///
/// Borrowed from the request context: binding never copies the route, query or
/// header maps, and the form is shared through the request's cached parse.
pub struct BindInput<'a> {
    /// Route parameters captured by the router (`{}` segments).
    pub path: &'a HashMap<String, String>,
    /// Query string, last value per key (the compatibility view).
    pub query: &'a HashMap<String, String>,
    /// Query string, every value per key; `None` when the host does not
    /// provide multi-value parsing.
    pub query_multi: Option<&'a HashMap<String, Vec<String>>>,
    /// The authenticated principal, when the request is authenticated.
    pub claims: Option<&'a dyn IClaims>,
    /// The parsed `multipart/form-data` body, when the request is multipart.
    pub form: Option<&'a MultipartForm>,
    /// Whether the route method is `POST`, `PUT` or `PATCH`.
    pub is_body: bool,
    /// Whether the request declares `multipart/form-data`.
    pub is_multipart: bool,
}

impl<'a> BindInput<'a> {
    /// The route value for `name`.
    pub fn path_one(&self, name: &str) -> Option<&'a str> {
        self.path.get(name).map(String::as_str)
    }

    /// Every route value for `name`, comma-separated lists expanded.
    ///
    /// A route segment is a single value, but `{ids}` accepting `1,2,3` is a
    /// convenient way to bind `Vec<T>` from the path — the same rule query
    /// values follow.
    pub fn path_list(&self, name: &str) -> Vec<&'a str> {
        match self.path.get(name) {
            Some(value) => split_one(value),
            None => Vec::new(),
        }
    }

    /// The last query value for `name`.
    pub fn query_one(&self, name: &str) -> Option<&'a str> {
        if let Some(multi) = self.query_multi {
            if let Some(values) = multi.get(name) {
                return values.last().map(String::as_str);
            }
        }
        self.query.get(name).map(String::as_str)
    }

    /// Every query value for `name`, comma-separated lists expanded.
    pub fn query_list(&self, name: &str) -> Vec<&'a str> {
        if let Some(multi) = self.query_multi {
            if let Some(values) = multi.get(name) {
                return split_values(values);
            }
        }
        match self.query.get(name) {
            Some(value) => split_one(value),
            None => Vec::new(),
        }
    }

    /// The first text part named `name` in the form.
    pub fn form_one(&self, name: &str) -> Option<&'a str> {
        self.form?.text(name)
    }

    /// Every text part named `name`, comma-separated lists expanded.
    pub fn form_list(&self, name: &str) -> Vec<&'a str> {
        match self.form {
            Some(form) => form.texts(name).flat_map(split_one).collect(),
            None => Vec::new(),
        }
    }

    /// The first file part named `name`.
    pub fn file(&self, name: &str) -> Option<&'a FormFile> {
        self.form?.file(name)
    }

    /// Every file part named `name`, in order.
    pub fn files(&self, name: &str) -> Vec<&'a FormFile> {
        match self.form {
            Some(form) => form.files_named(name).collect(),
            None => Vec::new(),
        }
    }

    /// A claim value by key.
    ///
    /// `sub` / `subject` resolve to the subject, `tenant_id` to the tenant
    /// helper, and anything else to the raw claims map.
    pub fn claim(&self, key: &str) -> Option<&'a str> {
        let claims = self.claims?;
        match key {
            "sub" | "subject" | "user_id" => Some(claims.subject()),
            "tenant_id" | "tenant" => claims.get_tenantid(),
            other => claims.claims().get(other).map(String::as_str),
        }
    }

    /// A claim as a list: `roles` / `permissions` use their dedicated slots,
    /// anything else is comma-separated.
    pub fn claim_list(&self, key: &str) -> Vec<&'a str> {
        let Some(claims) = self.claims else {
            return Vec::new();
        };
        match key {
            "roles" => claims.roles().iter().map(String::as_str).collect(),
            "permissions" => claims.permissions().iter().map(String::as_str).collect(),
            other => match self.claim(other) {
                Some(value) => split_one(value),
                None => Vec::new(),
            },
        }
    }
}

/// Convert a JSON body deserialization failure into a field-level 400.
///
/// `serde_json` reports the offending field for the common cases; those become
/// `errors.<field>` entries, and everything else is reported at the body level
/// under the empty key — the same convention ASP.NET Core uses for a body
/// model that cannot be bound at all.
pub fn body_error(error: serde_json::Error) -> Error {
    let message = error.to_string();
    let field = extract_error_field(&message)
        .unwrap_or_default()
        .to_string();
    ProblemDetails::validation(vec![FieldError::new(field, message)]).to_error()
}

fn extract_error_field(message: &str) -> Option<&str> {
    for marker in ["missing field `", "unknown field `", "duplicate field `"] {
        if let Some((_, rest)) = message.split_once(marker) {
            if let Some((name, _)) = rest.split_once('`') {
                return Some(name);
            }
        }
    }
    None
}

/// A field-level body failure: the JSON key was present but its value did not
/// match the field type.
pub fn body_field_error(field: &str, error: serde_json::Error) -> Error {
    ProblemDetails::validation(vec![FieldError::new(
        field,
        format!("The `{field}` field is invalid: {error}"),
    )])
    .to_error()
}

/// Remove `key` (or one of `aliases`) from a JSON object.
///
/// `serde`'s `rename`/`alias` are resolved by the derive; this looks the
/// resolved keys up and takes ownership of the value, so the remaining map only
/// holds keys no field claimed (which `deny_unknown_fields` can reject).
pub fn take_body_field(
    object: &mut serde_json::Map<String, serde_json::Value>,
    key: &str,
    aliases: &[&str],
) -> Option<serde_json::Value> {
    if let Some(value) = object.remove(key) {
        return Some(value);
    }
    for alias in aliases {
        if let Some(value) = object.remove(*alias) {
            return Some(value);
        }
    }
    None
}

/// Split one raw value on commas, dropping empty segments.
fn split_one(value: &str) -> Vec<&str> {
    if value.contains(',') {
        value
            .split(',')
            .map(str::trim)
            .filter(|part| !part.is_empty())
            .collect()
    } else {
        vec![value]
    }
}

/// Expand one optional raw value into a list, splitting on commas.
///
/// Public because the derive uses it for `Vec<T>` header fields, which carry a
/// single comma-separated line.
pub fn split_csv(value: Option<&str>) -> Vec<&str> {
    match value {
        Some(value) => split_one(value),
        None => Vec::new(),
    }
}

/// Split every raw value on commas, flattening the results.
fn split_values(values: &[String]) -> Vec<&str> {
    let mut out = Vec::with_capacity(values.len());
    for value in values {
        out.extend(split_one(value));
    }
    out
}

/// Accumulates field-level binding failures into one 400 response.
///
/// Binding is best-effort: a bad field records an error and yields `None`, the
/// remaining fields still bind, and the request is rejected once at the end
/// with every failure listed — matching ASP.NET Core's `ModelState`.
#[derive(Default)]
pub struct Binder {
    errors: Vec<FieldError>,
}

impl Binder {
    /// A binder with no recorded errors.
    pub fn new() -> Self {
        Self::default()
    }

    /// Whether any field failed.
    pub fn has_errors(&self) -> bool {
        !self.errors.is_empty()
    }

    /// The recorded failures, in binding order.
    pub fn errors(&self) -> &[FieldError] {
        &self.errors
    }

    /// Consume the binder, yielding the 400 `ProblemDetails` error.
    ///
    /// The response body carries `errors` as `{ "field": ["message"] }`.
    pub fn into_error(self) -> Error {
        ProblemDetails::validation(self.errors).to_error()
    }

    /// Record the canonical "required" failure for `field`.
    pub fn missing(&mut self, field: &str) {
        self.errors.push(FieldError::new(
            field,
            format!("The `{field}` field is required."),
        ));
    }

    /// Record an unparsable value for `field`.
    pub fn invalid(&mut self, field: &str, kind: &str, value: &str) {
        self.errors.push(FieldError::new(
            field,
            format!("The `{field}` field must be a valid {kind} (got `{value}`)."),
        ));
    }

    /// Record a JSON key that no field claimed (`deny_unknown_fields`).
    pub fn unknown_field(&mut self, name: &str) {
        self.errors.push(FieldError::new(
            "",
            format!("The body contains an unknown field `{name}`."),
        ));
    }

    /// Parse a required scalar.
    ///
    /// Returns `None` (and records an error) when the value is absent or
    /// unparsable; the caller checks [`Binder::has_errors`] before building the
    /// request.
    pub fn required<T: FromStr>(
        &mut self,
        raw: Option<&str>,
        field: &str,
        kind: &str,
    ) -> Option<T> {
        let Some(raw) = raw else {
            self.missing(field);
            return None;
        };
        match raw.parse::<T>() {
            Ok(value) => Some(value),
            Err(_) => {
                self.invalid(field, kind, raw);
                None
            }
        }
    }

    /// Parse an optional scalar: absent is `None`, present-but-invalid is an
    /// error (never silently `None`).
    pub fn optional<T: FromStr>(
        &mut self,
        raw: Option<&str>,
        field: &str,
        kind: &str,
    ) -> Option<T> {
        let raw = raw?;
        match raw.parse::<T>() {
            Ok(value) => Some(value),
            Err(_) => {
                self.invalid(field, kind, raw);
                None
            }
        }
    }

    /// Parse every occurrence of a repeated value into a list.
    ///
    /// An empty list is valid (ASP.NET Core binds missing collections as
    /// empty); unparsable elements are errors.
    pub fn list<T: FromStr>(&mut self, raw: &[&str], field: &str, kind: &str) -> Vec<T> {
        let mut out = Vec::with_capacity(raw.len());
        for value in raw {
            match value.parse::<T>() {
                Ok(parsed) => out.push(parsed),
                Err(_) => self.invalid(field, kind, value),
            }
        }
        out
    }

    /// Record a "required" failure for an already-extracted optional value.
    ///
    /// Used for body fields: `serde` has already validated the body, so a
    /// missing value here means the field was skipped by the shadow struct.
    pub fn take<T>(&mut self, value: Option<T>, field: &str) -> Option<T> {
        if value.is_none() {
            self.missing(field);
        }
        value
    }

    /// The first uploaded file, required.
    pub fn required_file(&mut self, file: Option<&FormFile>, field: &str) -> Option<FormFile> {
        match file {
            Some(file) => Some(file.clone()),
            None => {
                self.missing(field);
                None
            }
        }
    }

    /// The first uploaded file, optional.
    pub fn optional_file(&mut self, file: Option<&FormFile>) -> Option<FormFile> {
        file.cloned()
    }

    /// Every uploaded file under `name`.
    pub fn files(&mut self, files: Vec<&FormFile>) -> Vec<FormFile> {
        files.into_iter().cloned().collect()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashMap;

    #[test]
    fn required_reports_missing_and_invalid() {
        let mut binder = Binder::new();
        assert_eq!(binder.required::<u32>(None, "page", "integer"), None);
        assert_eq!(binder.required::<u32>(Some("abc"), "page", "integer"), None);
        assert_eq!(
            binder.required::<u32>(Some("2"), "page", "integer"),
            Some(2)
        );
        assert_eq!(binder.errors().len(), 2);
        assert!(binder.errors()[0].message.contains("required"));
    }

    #[test]
    fn optional_keeps_absent_as_none_and_rejects_invalid() {
        let mut binder = Binder::new();
        assert_eq!(binder.optional::<u32>(None, "page", "integer"), None);
        assert!(!binder.has_errors());
        assert_eq!(binder.optional::<u32>(Some("x"), "page", "integer"), None);
        assert!(binder.has_errors());
    }

    #[test]
    fn list_binds_every_occurrence() {
        let mut binder = Binder::new();
        assert_eq!(
            binder.list::<u32>(&["1", "2", "3"], "ids", "integer"),
            vec![1, 2, 3]
        );
        assert!(!binder.has_errors());
        assert_eq!(binder.list::<u32>(&["1", "x"], "ids", "integer"), vec![1]);
        assert!(binder.has_errors());
    }

    #[test]
    fn query_values_keep_every_occurrence_and_expand_comma_lists() {
        let path = HashMap::new();
        let query = HashMap::new();
        let mut multi: HashMap<String, Vec<String>> = HashMap::new();
        multi.insert("ids".into(), vec!["1".into(), "2,3".into()]);

        let input = BindInput {
            path: &path,
            query: &query,
            query_multi: Some(&multi),
            claims: None,
            form: None,
            is_body: false,
            is_multipart: false,
        };
        assert_eq!(input.query_list("ids"), vec!["1", "2", "3"]);
        assert_eq!(input.query_one("ids"), Some("2,3"));
    }

    #[test]
    fn error_body_groups_fields() {
        let mut binder = Binder::new();
        binder.missing("a");
        binder.missing("a");
        binder.missing("b");
        let error = binder.into_error();
        let Error::Problem(problem) = error else {
            panic!("expected Problem, got {error:?}");
        };
        assert_eq!(problem.status, 400);
        let errors = problem.extensions.as_ref().unwrap().get("errors").unwrap();
        assert_eq!(
            errors["a"],
            serde_json::json!(["The `a` field is required.", "The `a` field is required."])
        );
        assert_eq!(
            errors["b"],
            serde_json::json!(["The `b` field is required."])
        );
    }
}