qubit-redact 0.9.0

Rule-driven redaction for fields, diagnostics, HTTP data, and Rust domain objects
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Fail-closed error returned when inspection cannot classify complete input.

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

use super::RedactionReasons;
use super::RedactionUsage;

/// An inconclusive redaction inspection.
///
/// Callers must treat this error as potentially sensitive. The error exposes
/// only bounded accounting and machine-readable reasons; it never retains the
/// original input or a partial sensitivity result.
///
/// # Examples
///
/// ```
/// use qubit_redact::RedactionPolicy;
/// use qubit_redact::RedactionReason;
/// use qubit_redact::Redactor;
///
/// let policy = RedactionPolicy::builder().limits(|limits| {
///     limits.max_input_bytes(0);
/// })?.build()?;
/// let error = Redactor::new(policy).inspect_field("id", "42").expect_err("no input allowed");
/// assert!(error.reasons().contains(RedactionReason::InputLimitReached));
/// # Ok::<(), qubit_redact::PolicyError>(())
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[must_use]
pub struct RedactionInspectionError {
    /// Causes that prevented a conclusive classification.
    reasons: RedactionReasons,
    /// Resources consumed before inspection stopped.
    usage: RedactionUsage,
}

impl RedactionInspectionError {
    /// Creates an error from runtime-owned failure metadata.
    ///
    /// # Parameters
    ///
    /// - `reasons`: Causes preventing complete classification.
    /// - `usage`: Resources consumed before inspection stopped.
    ///
    /// # Returns
    ///
    /// A value-free error retaining reasons and usage, without partial
    /// sensitivity.
    #[inline(always)]
    pub(crate) const fn new(reasons: RedactionReasons, usage: RedactionUsage) -> Self {
        Self { reasons, usage }
    }

    /// Returns the machine-readable causes of incomplete inspection.
    ///
    /// # Returns
    ///
    /// The accumulated causes of inconclusive inspection.
    #[must_use]
    #[inline(always)]
    pub const fn reasons(&self) -> RedactionReasons {
        self.reasons
    }

    /// Returns resources consumed before the inspection became inconclusive.
    ///
    /// # Returns
    ///
    /// Resources consumed before complete classification became unavailable.
    #[must_use]
    #[inline(always)]
    pub const fn usage(&self) -> RedactionUsage {
        self.usage
    }
}

impl fmt::Display for RedactionInspectionError {
    /// Writes a safe diagnostic that never includes inspected input.
    ///
    /// # Parameters
    ///
    /// - `formatter`: Destination receiving a value-free diagnostic.
    ///
    /// # Returns
    ///
    /// Success after writing the inconclusive-inspection diagnostic.
    ///
    /// # Errors
    ///
    /// Propagates a destination formatting error.
    #[inline(always)]
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("redaction inspection was inconclusive")
    }
}

impl Error for RedactionInspectionError {}