vld_tonic/

lib.rs

#![allow(clippy::result_large_err)]
//! # vld-tonic — tonic gRPC integration for the `vld` validation library
//!
//! Validate protobuf messages and gRPC metadata using `vld` schemas.
//!
//! ## Approaches
//!
//! | Function | Use case |
//! |---|---|
//! | [`validate`] / [`validate_ref`] | Validate a message that implements [`VldMessage`] (via [`impl_validate!`]) |
//! | [`validate_with`] / [`validate_with_ref`] | Validate against a separate `vld::schema!` struct |
//! | [`validate_metadata`] | Validate gRPC request metadata |
//! | [`metadata_interceptor`] | Tonic interceptor for automatic metadata validation |
//!
//! ## Quick example
//!
//! ```ignore
//! use serde::Serialize;
//! use tonic::{Request, Response, Status};
//!
//! // Protobuf message (generated by prost with serde support)
//! #[derive(Clone, Serialize)]
//! pub struct CreateUserRequest {
//!     pub name: String,
//!     pub email: String,
//! }
//!
//! // Attach validation rules
//! vld_tonic::impl_validate!(CreateUserRequest {
//!     name  => vld::string().min(2).max(100),
//!     email => vld::string().email(),
//! });
//!
//! // In your service handler:
//! async fn create_user(request: Request<CreateUserRequest>) -> Result<Response<()>, Status> {
//!     let msg = vld_tonic::validate(request)?;
//!     // msg is validated
//!     Ok(Response::new(()))
//! }
//! ```

use tonic::{Code, Request, Status};
use vld::error::VldError;
use vld::schema::VldParse;

// ========================= Error conversion ==================================

/// Convert a [`VldError`] into a [`tonic::Status`] with `INVALID_ARGUMENT` code.
///
/// The status message contains a JSON object with structured error details.
pub fn vld_status(error: &VldError) -> Status {
    vld_status_with_code(error, Code::InvalidArgument)
}

/// Convert a [`VldError`] into a [`tonic::Status`] with a custom gRPC code.
pub fn vld_status_with_code(error: &VldError, code: Code) -> Status {
    let issues: Vec<serde_json::Value> = error
        .issues
        .iter()
        .map(|issue| {
            let path: String = issue
                .path
                .iter()
                .map(|p| p.to_string())
                .collect::<Vec<_>>()
                .join(".");
            serde_json::json!({
                "path": path,
                "message": issue.message,
                "code": format!("{:?}", issue.code),
            })
        })
        .collect();

    let body = serde_json::json!({
        "error": "VALIDATION_ERROR",
        "message": "Request validation failed",
        "details": issues,
    });

    Status::new(code, body.to_string())
}

// ========================= VldMessage trait ===================================

/// Trait for message types that can be validated with vld.
///
/// Implement via the [`impl_validate!`] macro, or manually.
pub trait VldMessage {
    /// Validate this message against its rules.
    fn vld_validate(&self) -> Result<(), VldError>;
}

// ========================= Message validation ================================

/// Validate a gRPC request message that implements [`VldMessage`].
///
/// Consumes the request and returns the validated message,
/// or `Status::INVALID_ARGUMENT` on failure.
///
/// # Example
///
/// ```ignore
/// async fn handler(request: Request<MyMessage>) -> Result<Response<()>, Status> {
///     let msg = vld_tonic::validate(request)?;
///     // use msg...
///     Ok(Response::new(()))
/// }
/// ```
pub fn validate<T: VldMessage>(request: Request<T>) -> Result<T, Status> {
    let message = request.into_inner();
    message.vld_validate().map_err(|e| vld_status(&e))?;
    Ok(message)
}

/// Validate a message reference without consuming the request.
pub fn validate_ref<T: VldMessage>(message: &T) -> Result<(), Status> {
    message.vld_validate().map_err(|e| vld_status(&e))
}

// ========================= Schema-based validation ===========================

/// Validate a gRPC request message against a separate vld schema type.
///
/// The message is serialized to JSON via serde, then validated using
/// `S::vld_parse_value()`. Useful when you have a `vld::schema!` struct
/// that mirrors the protobuf message fields.
///
/// # Example
///
/// ```ignore
/// vld::schema! {
///     struct UserSchema {
///         name: String => vld::string().min(2),
///         email: String => vld::string().email(),
///     }
/// }
///
/// async fn handler(request: Request<CreateUserRequest>) -> Result<Response<()>, Status> {
///     let msg = vld_tonic::validate_with::<UserSchema, _>(request)?;
///     Ok(Response::new(()))
/// }
/// ```
pub fn validate_with<S, T>(request: Request<T>) -> Result<T, Status>
where
    S: VldParse,
    T: serde::Serialize,
{
    let message = request.into_inner();
    validate_with_ref::<S, T>(&message)?;
    Ok(message)
}

/// Validate a message reference against a separate vld schema type.
pub fn validate_with_ref<S, T>(message: &T) -> Result<(), Status>
where
    S: VldParse,
    T: serde::Serialize,
{
    let json = serde_json::to_value(message)
        .map_err(|e| Status::internal(format!("Serialization error: {}", e)))?;
    S::vld_parse_value(&json).map_err(|e| vld_status(&e))?;
    Ok(())
}

// ========================= Metadata validation ===============================

/// Validate gRPC request metadata against a vld schema.
///
/// Metadata keys are converted from `kebab-case` to `snake_case`
/// (e.g. `x-request-id` → `x_request_id`).
/// String values are coerced: `"42"` → number, `"true"` → boolean.
///
/// # Example
///
/// ```ignore
/// vld::schema! {
///     #[derive(Debug, Clone)]
///     struct AuthMeta {
///         authorization: String => vld::string().min(1),
///     }
/// }
///
/// async fn handler(request: Request<MyMessage>) -> Result<Response<()>, Status> {
///     let auth: AuthMeta = vld_tonic::validate_metadata(&request)?;
///     println!("auth: {}", auth.authorization);
///     Ok(Response::new(()))
/// }
/// ```
pub fn validate_metadata<T, M>(request: &Request<M>) -> Result<T, Status>
where
    T: VldParse,
{
    let metadata = request.metadata();
    let mut map = serde_json::Map::new();

    for kv in metadata.iter() {
        match kv {
            tonic::metadata::KeyAndValueRef::Ascii(key, value) => {
                if let Ok(v) = value.to_str() {
                    let k = key.as_str().replace('-', "_");
                    map.insert(k, coerce_value(v));
                }
            }
            tonic::metadata::KeyAndValueRef::Binary(_, _) => {}
        }
    }

    let json = serde_json::Value::Object(map);
    T::vld_parse_value(&json).map_err(|e| vld_status(&e))
}

/// Retrieve a validated metadata struct from request extensions.
///
/// Use after [`metadata_interceptor`] has stored the validated value.
///
/// # Example
///
/// ```ignore
/// async fn handler(request: Request<MyMessage>) -> Result<Response<()>, Status> {
///     let auth = vld_tonic::validated_metadata::<AuthMeta, _>(&request)
///         .ok_or_else(|| Status::unauthenticated("Missing auth"))?;
///     Ok(Response::new(()))
/// }
/// ```
pub fn validated_metadata<T, M>(request: &Request<M>) -> Option<T>
where
    T: Clone + Send + Sync + 'static,
{
    request.extensions().get::<T>().cloned()
}

// ========================= Interceptor =======================================

/// A tonic interceptor function that validates request metadata.
///
/// The validated struct is stored in request extensions and can be
/// retrieved in handlers via [`validated_metadata`] or
/// `request.extensions().get::<T>()`.
///
/// # Example
///
/// ```ignore
/// use tonic::transport::Server;
///
/// vld::schema! {
///     #[derive(Debug, Clone)]
///     struct AuthMeta {
///         authorization: String => vld::string().min(1),
///     }
/// }
///
/// Server::builder()
///     .add_service(MyServiceServer::with_interceptor(
///         my_service,
///         vld_tonic::metadata_interceptor::<AuthMeta>,
///     ))
///     .serve(addr)
///     .await?;
/// ```
pub fn metadata_interceptor<T>(mut request: Request<()>) -> Result<Request<()>, Status>
where
    T: VldParse + Clone + Send + Sync + 'static,
{
    let validated: T = validate_metadata(&request)?;
    request.extensions_mut().insert(validated);
    Ok(request)
}

// ========================= Macro =============================================

/// Attach vld validation rules to a protobuf message type.
///
/// Generates `validate()` and `is_valid()` inherent methods (via
/// [`vld::impl_rules!`]) and implements the [`VldMessage`] trait.
///
/// # Example
///
/// ```ignore
/// // Protobuf message generated by prost (with serde support)
/// #[derive(Clone, PartialEq, prost::Message, serde::Serialize)]
/// pub struct CreateUserRequest {
///     #[prost(string, tag = "1")]
///     pub name: String,
///     #[prost(string, tag = "2")]
///     pub email: String,
///     #[prost(int32, tag = "3")]
///     pub age: i32,
/// }
///
/// vld_tonic::impl_validate!(CreateUserRequest {
///     name  => vld::string().min(2).max(50),
///     email => vld::string().email(),
///     age   => vld::number().int().min(0).max(150),
/// });
///
/// // Now you can use:
/// //   msg.validate()?;          — inherent method
/// //   msg.is_valid()            — inherent method
/// //   vld_tonic::validate(req)  — request helper
/// ```
#[macro_export]
macro_rules! impl_validate {
    ($name:ident { $($field:ident => $schema:expr),* $(,)? }) => {
        ::vld::impl_rules!($name { $($field => $schema),* });

        impl $crate::VldMessage for $name {
            fn vld_validate(&self) -> ::std::result::Result<(), ::vld::error::VldError> {
                self.validate()
            }
        }
    };
}

// ========================= Helpers ===========================================

fn coerce_value(s: &str) -> serde_json::Value {
    if s.is_empty() {
        return serde_json::Value::Null;
    }
    if s == "true" {
        return serde_json::Value::Bool(true);
    }
    if s == "false" {
        return serde_json::Value::Bool(false);
    }
    if let Ok(n) = s.parse::<i64>() {
        return serde_json::Value::Number(n.into());
    }
    if let Ok(n) = s.parse::<f64>() {
        if let Some(num) = serde_json::Number::from_f64(n) {
            return serde_json::Value::Number(num);
        }
    }
    serde_json::Value::String(s.to_string())
}

/// Prelude — import everything you need.
pub mod prelude {
    pub use crate::{
        impl_validate, metadata_interceptor, validate, validate_metadata, validate_ref,
        validate_with, validate_with_ref, validated_metadata, vld_status, vld_status_with_code,
        VldMessage,
    };
    pub use vld::prelude::*;
}