fraiseql_core/validation/

rules.rs

//! Validation rule types and definitions.
//!
//! This module defines the validation rules that can be applied to input fields
//! in a GraphQL schema. Rules are serializable and can be embedded in the compiled schema.

use std::fmt;

use regex::Regex;
use serde::{Deserialize, Deserializer, Serialize, Serializer};

/// A regex pattern compiled once at construction or deserialisation time.
///
/// Stores both the compiled [`Regex`] and the source string so that the rule
/// remains [`Clone`] / [`PartialEq`] / [`Serialize`] without needing to
/// recompile on every match. Compilation errors surface at the construction
/// site (e.g. schema load) rather than per-request on the validation hot path.
#[derive(Debug, Clone)]
pub struct CompiledPattern {
    /// Original pattern source — preserved for serde round-trip and diagnostics.
    source: String,
    /// Pre-compiled regex matcher.
    regex:  Regex,
}

impl CompiledPattern {
    /// Compile a regex pattern.
    ///
    /// # Errors
    ///
    /// Returns the underlying [`regex::Error`] if `pattern` is not a valid
    /// regular expression.
    pub fn new(pattern: impl Into<String>) -> Result<Self, regex::Error> {
        let source = pattern.into();
        let regex = Regex::new(&source)?;
        Ok(Self { source, regex })
    }

    /// Borrow the compiled regex for matching.
    #[must_use]
    pub const fn regex(&self) -> &Regex {
        &self.regex
    }

    /// Borrow the original pattern source.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.source
    }

    /// Test whether the input string matches this pattern.
    #[must_use]
    pub fn is_match(&self, value: &str) -> bool {
        self.regex.is_match(value)
    }
}

impl fmt::Display for CompiledPattern {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.source)
    }
}

impl PartialEq for CompiledPattern {
    fn eq(&self, other: &Self) -> bool {
        self.source == other.source
    }
}

impl Eq for CompiledPattern {}

impl Serialize for CompiledPattern {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(&self.source)
    }
}

impl<'de> Deserialize<'de> for CompiledPattern {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        use serde::de::Error;
        let source = String::deserialize(deserializer)?;
        Self::new(source).map_err(D::Error::custom)
    }
}

impl TryFrom<String> for CompiledPattern {
    type Error = regex::Error;

    fn try_from(value: String) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

impl TryFrom<&str> for CompiledPattern {
    type Error = regex::Error;

    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

/// A validation rule that can be applied to a field.
///
/// Rules define constraints on field values and are evaluated during input validation.
/// Multiple rules can be combined on a single field.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", content = "value")]
#[non_exhaustive]
pub enum ValidationRule {
    /// Field is required (non-null) and must have a value.
    #[serde(rename = "required")]
    Required,

    /// Field value must match a regular expression pattern.
    ///
    /// The `pattern` is compiled once when the rule is constructed (or
    /// deserialised from the compiled schema), so the regex engine is not
    /// re-invoked per request.
    #[serde(rename = "pattern")]
    Pattern {
        /// The regex pattern to match — compiled at construction.
        pattern: CompiledPattern,
        /// Optional error message for when pattern doesn't match.
        message: Option<String>,
    },

    /// String field length constraints, counted in characters (see
    /// [`check_length`]).
    #[serde(rename = "length")]
    Length {
        /// Minimum length (inclusive).
        min: Option<usize>,
        /// Maximum length (inclusive).
        max: Option<usize>,
    },

    /// Numeric field range constraints.
    #[serde(rename = "range")]
    Range {
        /// Minimum value (inclusive).
        min: Option<i64>,
        /// Maximum value (inclusive).
        max: Option<i64>,
    },

    /// Field value must be one of allowed enum values.
    #[serde(rename = "enum")]
    Enum {
        /// List of allowed values.
        values: Vec<String>,
    },

    /// Checksum validation for structured data.
    #[serde(rename = "checksum")]
    Checksum {
        /// Algorithm to use (e.g., "luhn", "mod97").
        algorithm: String,
    },

    /// Cross-field validation rule.
    #[serde(rename = "cross_field")]
    CrossField {
        /// Reference to another field to compare against.
        field:    String,
        /// Comparison operator ("lt", "lte", "eq", "gte", "gt").
        operator: String,
    },

    /// Conditional validation - only validate if condition is met.
    #[serde(rename = "conditional")]
    Conditional {
        /// The condition expression.
        condition:  String,
        /// Rules to apply if condition is true.
        then_rules: Vec<Box<ValidationRule>>,
    },

    /// Composite rule - all rules must pass.
    #[serde(rename = "all")]
    All(Vec<ValidationRule>),

    /// Composite rule - at least one rule must pass.
    #[serde(rename = "any")]
    Any(Vec<ValidationRule>),

    /// Exactly one field from the set must be provided (mutually exclusive).
    ///
    /// Useful for "create or reference" patterns where you must provide EITHER
    /// an ID to reference an existing entity OR the fields to create a new one,
    /// but not both.
    ///
    /// # Example
    /// ```
    /// use fraiseql_core::validation::ValidationRule;
    /// // Either provide entityId OR (name + description), but not both
    /// let _rule = ValidationRule::OneOf { fields: vec!["name".to_string(), "description".to_string()] };
    /// ```
    #[serde(rename = "one_of")]
    OneOf {
        /// List of field names - exactly one must be provided
        fields: Vec<String>,
    },

    /// At least one field from the set must be provided.
    ///
    /// Useful for optional but not-all-empty patterns.
    ///
    /// # Example
    /// ```
    /// use fraiseql_core::validation::ValidationRule;
    /// // Provide at least one of: email, phone, address
    /// let _rule = ValidationRule::AnyOf { fields: vec!["email".to_string(), "phone".to_string(), "address".to_string()] };
    /// ```
    #[serde(rename = "any_of")]
    AnyOf {
        /// List of field names - at least one must be provided
        fields: Vec<String>,
    },

    /// If a field is present, then other fields are required.
    ///
    /// Used for conditional requirements based on presence of another field.
    ///
    /// # Example
    /// ```
    /// use fraiseql_core::validation::ValidationRule;
    /// // If entityId is provided, then createdAt is required
    /// let _rule = ValidationRule::ConditionalRequired {
    ///     if_field_present: "entityId".to_string(),
    ///     then_required: vec!["createdAt".to_string()],
    /// };
    /// ```
    #[serde(rename = "conditional_required")]
    ConditionalRequired {
        /// If this field is present (not null/missing)
        if_field_present: String,
        /// Then these fields are required
        then_required:    Vec<String>,
    },

    /// If a field is absent/null, then other fields are required.
    ///
    /// Used for "provide this OR that" patterns at the object level.
    ///
    /// # Example
    /// ```
    /// use fraiseql_core::validation::ValidationRule;
    /// // If addressId is missing, then street+city+zip are required
    /// let _rule = ValidationRule::RequiredIfAbsent {
    ///     absent_field: "addressId".to_string(),
    ///     then_required: vec!["street".to_string(), "city".to_string(), "zip".to_string()],
    /// };
    /// ```
    #[serde(rename = "required_if_absent")]
    RequiredIfAbsent {
        /// If this field is absent/null
        absent_field:  String,
        /// Then these fields are required
        then_required: Vec<String>,
    },

    /// Field must be a valid email address (RFC 5321 practical subset).
    #[serde(rename = "email")]
    Email,

    /// Field must be a valid E.164 international phone number (e.g. `+14155552671`).
    #[serde(rename = "phone")]
    Phone,
}

impl ValidationRule {
    /// Check if this is a required field validation.
    #[must_use]
    pub const fn is_required(&self) -> bool {
        matches!(self, Self::Required)
    }

    /// Get a human-readable description of this rule.
    #[must_use]
    pub fn description(&self) -> String {
        match self {
            Self::Required => "Field is required".to_string(),
            Self::Pattern { message, .. } => {
                message.clone().unwrap_or_else(|| "Must match pattern".to_string())
            },
            Self::Length { min, max } => match (min, max) {
                (Some(m), Some(max_val)) => format!("Length between {} and {}", m, max_val),
                (Some(m), None) => format!("Length at least {}", m),
                (None, Some(max_val)) => format!("Length at most {}", max_val),
                (None, None) => "Length constraint".to_string(),
            },
            Self::Range { min, max } => match (min, max) {
                (Some(m), Some(max_val)) => format!("Value between {} and {}", m, max_val),
                (Some(m), None) => format!("Value at least {}", m),
                (None, Some(max_val)) => format!("Value at most {}", max_val),
                (None, None) => "Range constraint".to_string(),
            },
            Self::Enum { values } => format!("Must be one of: {}", values.join(", ")),
            Self::Checksum { algorithm } => format!("Invalid {}", algorithm),
            Self::CrossField { field, operator } => format!("Must be {} {}", operator, field),
            Self::Conditional { .. } => "Conditional validation".to_string(),
            Self::All(_) => "All rules must pass".to_string(),
            Self::Any(_) => "At least one rule must pass".to_string(),
            Self::OneOf { fields } => {
                format!("Exactly one of these must be provided: {}", fields.join(", "))
            },
            Self::AnyOf { fields } => {
                format!("At least one of these must be provided: {}", fields.join(", "))
            },
            Self::ConditionalRequired {
                if_field_present,
                then_required,
            } => {
                format!(
                    "If '{}' is provided, then {} must be provided",
                    if_field_present,
                    then_required.join(", ")
                )
            },
            Self::RequiredIfAbsent {
                absent_field,
                then_required,
            } => {
                format!(
                    "If '{}' is absent, then {} must be provided",
                    absent_field,
                    then_required.join(", ")
                )
            },
            Self::Email => "Must be a valid email address".to_string(),
            Self::Phone => "Must be a valid E.164 phone number (e.g. +14155552671)".to_string(),
        }
    }
}

/// Outcome of a [`ValidationRule::Length`] check.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LengthCheck {
    /// The value is within bounds.
    Ok,
    /// Shorter than `min`.
    TooShort {
        /// The configured minimum.
        min:    usize,
        /// The value's actual length, in characters.
        actual: usize,
    },
    /// Longer than `max`.
    TooLong {
        /// The configured maximum.
        max:    usize,
        /// The value's actual length, in characters.
        actual: usize,
    },
}

/// Evaluate a `Length` rule against `value`.
///
/// **Length is a count of characters, not bytes.** Four call sites evaluated
/// this rule independently and all four used `str::len()`, so `min: 3` accepted
/// `"é!"` (three bytes, two characters) and `max: 3` rejected `"éàü"` (six
/// bytes) — while every one of their error messages said "characters" (#720).
/// Routing all four through this function is what makes the messages true.
#[must_use]
pub fn check_length(value: &str, min: Option<usize>, max: Option<usize>) -> LengthCheck {
    let actual = value.chars().count();
    if let Some(min) = min {
        if actual < min {
            return LengthCheck::TooShort { min, actual };
        }
    }
    if let Some(max) = max {
        if actual > max {
            return LengthCheck::TooLong { max, actual };
        }
    }
    LengthCheck::Ok
}