qubit-redact 0.9.0

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Errors reported while building a redaction policy.

use std::error::Error;
use std::fmt;

use super::PolicyLocation;
use super::Sensitivity;

/// Error returned when a redaction policy contains an invalid rule.
///
/// # Examples
///
/// ```
/// use qubit_redact::{PolicyError, RedactionPolicy, Sensitivity};
///
/// let error = RedactionPolicy::builder()
///     .fields(|fields| {
///         fields.raise("", Sensitivity::Secret);
///     })
///     .expect_err("an empty field name is invalid");
/// assert!(matches!(error, PolicyError::EmptyFieldName { .. }));
/// ```
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
#[must_use]
pub enum PolicyError {
    /// A supplied field name is empty after canonicalization.
    EmptyFieldName {
        /// Location where the invalid field was configured.
        location: PolicyLocation,
    },
    /// A fixed mask has an empty replacement at the indicated level.
    EmptyFixedReplacement {
        /// Location where the fixed mask was configured.
        location: PolicyLocation,
        /// Sensitivity level containing the invalid fixed mask.
        level: Sensitivity,
    },
    /// The configured output ceiling cannot be represented by Rust's
    /// collection allocators on this platform.
    OutputLimitTooLarge {
        /// Rejected configured output limit.
        maximum: usize,
    },
    /// The logical Serde payload ceiling exceeds addressable capacity.
    #[cfg(feature = "serde")]
    SerdePayloadLimitTooLarge {
        /// Rejected configured scalar payload limit.
        maximum: usize,
    },
}

impl fmt::Display for PolicyError {
    /// Formats a concise description of the invalid policy configuration.
    ///
    /// # Parameters
    ///
    /// * `formatter` - Destination formatting context.
    ///
    /// # Returns
    ///
    /// The formatter result from writing the error description.
    ///
    /// # Errors
    ///
    /// Returns [`fmt::Error`] when the destination rejects a write.
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::EmptyFieldName { location } => {
                write!(formatter, "field name is empty after canonicalization in {location}",)
            }
            Self::EmptyFixedReplacement { location, level } => write!(
                formatter,
                "fixed mask replacement for {level:?} sensitivity is empty in {location}",
            ),
            #[cfg(feature = "serde")]
            Self::SerdePayloadLimitTooLarge { maximum } => write!(
                formatter,
                "Serde payload limit {maximum} exceeds this platform's addressable collection capacity",
            ),
            Self::OutputLimitTooLarge { maximum } => write!(
                formatter,
                "output limit {maximum} exceeds this platform's addressable collection capacity",
            ),
        }
    }
}

impl Error for PolicyError {}