5.2 ValidationError and ValidationKind

ValidationError and ValidationKind

Relevant source files

The following files were used as context for generating this wiki page:

• src/validation/error.rs

Purpose and Scope

This page details the typed error taxonomy implemented in src/validation/error.rs src/validation/error.rs:1-221. It covers ValidationKind, which defines stable machine-readable error categories; ValidationMeasure, which encapsulates observed numeric, count, or range metrics; and ValidationError, which combines these with a JSON-like path (path) to pinpoint protocol violations across wire payloads.

---

ValidationKind Taxonomy

The ValidationKind enum defines stable classification identifiers for protocol validation failures src/validation/error.rs:5-25. These identifiers form part of the crate's stable error contract; serde wrappers and fmt::Display rely on ValidationKind::as_str so that automated assertions can match against exact error variants src/validation/error.rs:7-9.

pub enum ValidationKind {
    NonFinite,
    OutOfRange,
    LengthMismatch,
    LimitExceeded,
    NestedMetadata,
    DuplicateIdentifier,
}

• NonFinite: Triggered when an f32 value is NaN or $\pm\infty$ src/validation/error.rs:11-13.
• OutOfRange: Triggered when a numeric value falls outside its documented inclusive range src/validation/error.rs:14-15.
• LengthMismatch: Triggered when two related sequences (such as values and valid_mask) differ in length src/validation/error.rs:16-17.
• LimitExceeded: Triggered when a collection length or string byte length exceeds bounds defined in ProtocolLimits src/validation/error.rs:18-19.
• NestedMetadata: Triggered when nested metadata violates structural policy, such as containing an empty key src/validation/error.rs:20-22.
• DuplicateIdentifier: Triggered when a list requiring unique keys (such as channel_id or layer_id) contains repeated identifiers src/validation/error.rs:23-24.

The ValidationKind::as_str method maps these variants to snake_case string slices src/validation/error.rs:27-40:

• NonFinite $\rightarrow$ "non_finite"
• OutOfRange $\rightarrow$ "out_of_range"
• LengthMismatch $\rightarrow$ "length_mismatch"
• LimitExceeded $\rightarrow$ "limit_exceeded"
• NestedMetadata $\rightarrow$ "nested_metadata"
• DuplicateIdentifier $\rightarrow$ "duplicate_identifier"

fmt::Display for ValidationKind forwards directly to as_str src/validation/error.rs:42-46.

Sources: src/validation/error.rs:5-46

Validation Taxonomy Mapping

graph TD
    ValidationFailure["Protocol Validation Failure"] --> VK["ValidationKind (src/validation/error.rs)"]
    VK --> NF["NonFinite: non_finite"]
    VK --> OOR["OutOfRange: out_of_range"]
    VK --> LM["LengthMismatch: length_mismatch"]
    VK --> LE["LimitExceeded: limit_exceeded"]
    VK --> NM["NestedMetadata: nested_metadata"]
    VK --> DI["DuplicateIdentifier: duplicate_identifier"]

Loading

Sources: src/validation/error.rs:10-25

---

ValidationMeasure and Quantification

To supply diagnostic context alongside error kinds, ValidationMeasure standardizes how observed metrics are represented src/validation/error.rs:48-60.

pub enum ValidationMeasure {
    Count(u64),
    Bytes(u64),
    Float(f32),
    Range { min: f32, max: f32 },
}

Equality comparisons (PartialEq and Eq) for floats and ranges are bit-level (to_bits()) to guarantee deterministic evaluation, particularly for NaN values src/validation/error.rs:62-82. fmt::Display formats counts and bytes as integers, floats using standard decimal representation, and ranges as bracketed intervals [min, max] src/validation/error.rs:84-92.

Sources: src/validation/error.rs:48-92

---

ValidationError Structure and Constructors

The ValidationError struct aggregates a failure path, a ValidationKind, and optional measured actual and limit values src/validation/error.rs:99-109.

pub struct ValidationError {
    pub path: String,
    pub kind: ValidationKind,
    pub actual: Option<ValidationMeasure>,
    pub limit: Option<ValidationMeasure>,
}

It exposes several factory constructors to simplify instantiation in validation rules src/validation/error.rs:111-188:

• ValidationError::non_finite(path, actual): Instantiates ValidationKind::NonFinite with a ValidationMeasure::Float src/validation/error.rs:113-121.
• ValidationError::out_of_range(path, actual, min, max): Instantiates ValidationKind::OutOfRange with observed float and range bounds src/validation/error.rs:125-132.
• ValidationError::length_mismatch(path, actual, expected): Instantiates ValidationKind::LengthMismatch with count measures src/validation/error.rs:135-143.
• ValidationError::limit_exceeded(path, actual, limit): Instantiates ValidationKind::LimitExceeded using count measures src/validation/error.rs:146-154.
• ValidationError::byte_limit(path, actual, limit): Instantiates ValidationKind::LimitExceeded using byte measures src/validation/error.rs:157-165.
• ValidationError::nested_metadata(path): Instantiates ValidationKind::NestedMetadata without metrics src/validation/error.rs:168-176.
• ValidationError::duplicate_identifier(path, identifier): Instantiates ValidationKind::DuplicateIdentifier src/validation/error.rs:179-188.

Sources: src/validation/error.rs:99-188

Validation Data Flow

graph TD
    PayloadField["Incoming Wire Field (src/models/)"] --> Validator["validate() Function (src/validation/)"]
    Validator -->|"Check Fails"| Constructor["ValidationError Constructor (src/validation/error.rs)"]
    Constructor --> Measure["ValidationMeasure (Count/Bytes/Float/Range)"]
    Measure --> ErrorStruct["ValidationError struct (path, kind, actual, limit)"]
    ErrorStruct --> Deserialization["serde / TryFrom Error Surface"]

Loading

Sources: src/validation/error.rs:111-188