qubit_json/decode/diagnostic_policy.rs
1// =============================================================================
2// Copyright (c) 2025 - 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Defines the privacy policy for JSON decoding error diagnostics.
9
10/// Controls whether library-generated JSON decoding diagnostics retain
11/// input-derived details.
12///
13/// Redacted diagnostics are safe by default. Detailed diagnostics are intended
14/// only for controlled environments because they may contain input values.
15/// This policy does not redact errors returned by caller-provided validated
16/// number policies. [`super::JsonValidatedDecodeError::Policy`] preserves that
17/// error as its source, although the outer error's `Display` and `Debug` omit
18/// it. Callers are responsible for the contents and logging of their policy
19/// errors. See [`JsonValidatedDecodeError`](super::JsonValidatedDecodeError)
20/// for a complete example.
21///
22/// # Examples
23///
24/// ```
25/// use qubit_json::decode::DiagnosticPolicy;
26///
27/// let policy = DiagnosticPolicy::Redacted;
28/// assert_ne!(policy, DiagnosticPolicy::Detailed);
29/// ```
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
31pub enum DiagnosticPolicy {
32 /// Retains only stable classifications and source coordinates in
33 /// library-generated diagnostics.
34 ///
35 /// Redacted library diagnostics never retain unexpected bytes,
36 /// token/key/value text, or parser and Serde sources. Caller-provided
37 /// validated policy errors are not controlled by this variant.
38 #[default]
39 Redacted,
40 /// Retains complete serde messages and sources for diagnostic use.
41 Detailed,
42}