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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Machine-readable redaction summaries.

use super::RedactionReason;
use super::RedactionReasons;
use super::RedactionUsage;
use crate::output::RedactionCompletion;

/// Machine-readable summary of one redaction operation.
///
/// # Examples
///
/// ```
/// use qubit_redact::RedactionCompletion;
/// use qubit_redact::Redactor;
///
/// let output = Redactor::standard().redact_field("password", "raw-secret");
/// assert_eq!(output.summary().completion(), RedactionCompletion::Complete);
/// assert!(!output.summary().is_redaction_disabled());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RedactionSummary {
    /// Whether the operation intentionally bypassed redaction.
    redaction_disabled: bool,
    /// Final completion state of the operation.
    completion: RedactionCompletion,
    /// Reasons explaining degraded completion.
    reasons: RedactionReasons,
    /// Resource accounting captured by the operation.
    usage: RedactionUsage,
}

impl RedactionSummary {
    /// Creates a summary from runtime-owned completion, reasons, and usage.
    ///
    /// # Parameters
    ///
    /// - `redaction_disabled`: Whether the operation intentionally bypassed
    ///   redaction.
    /// - `completion`: Final state of the safe representation.
    /// - `reasons`: Independent causes recorded by the operation.
    /// - `usage`: Completed resource measurements.
    ///
    /// # Returns
    ///
    /// A summary retaining the supplied completion, reasons, and accounting.
    #[must_use]
    #[inline(always)]
    pub(crate) const fn from_parts(
        redaction_disabled: bool,
        completion: RedactionCompletion,
        reasons: RedactionReasons,
        usage: RedactionUsage,
    ) -> Self {
        Self {
            redaction_disabled,
            completion,
            reasons,
            usage,
        }
    }

    /// Creates a degraded summary.
    ///
    /// # Parameters
    ///
    /// - `reason`: Cause of the degraded safe representation.
    ///
    /// # Returns
    ///
    /// A truncated summary with the supplied reason and empty accounting.
    #[must_use]
    #[inline(always)]
    pub(crate) const fn truncated(reason: RedactionReason) -> Self {
        Self {
            redaction_disabled: false,
            completion: RedactionCompletion::Truncated,
            reasons: RedactionReasons::empty().with(reason),
            usage: RedactionUsage::empty(),
        }
    }

    /// Creates a summary for a transaction that exhausted safe output capacity.
    ///
    /// # Returns
    ///
    /// An exhausted summary with the output-limit reason and empty accounting.
    #[must_use]
    #[inline(always)]
    pub(crate) const fn exhausted() -> Self {
        Self {
            redaction_disabled: false,
            completion: RedactionCompletion::Exhausted,
            reasons: RedactionReasons::empty().with(RedactionReason::OutputLimitReached),
            usage: RedactionUsage::empty(),
        }
    }

    /// Returns completion state.
    ///
    /// # Returns
    ///
    /// The final completion state of the safe representation.
    #[must_use = "the completion state describes whether the output is complete"]
    #[inline(always)]
    pub const fn completion(self) -> RedactionCompletion {
        self.completion
    }

    /// Returns whether redaction was globally disabled for this operation.
    ///
    /// # Returns
    ///
    /// True when this operation intentionally bypassed redaction.
    #[must_use]
    #[inline(always)]
    pub const fn is_redaction_disabled(self) -> bool {
        self.redaction_disabled
    }

    /// Returns accumulated reasons.
    ///
    /// # Returns
    ///
    /// All machine-readable causes retained by the operation.
    #[must_use]
    #[inline(always)]
    pub const fn reasons(self) -> RedactionReasons {
        self.reasons
    }

    /// Returns resource use measured by the operation that produced this
    /// summary.
    ///
    /// # Returns
    ///
    /// The resource measurements associated with this operation.
    #[must_use]
    #[inline(always)]
    pub const fn usage(self) -> RedactionUsage {
        self.usage
    }
}