data_privacy 0.12.2

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT License.

use core::fmt::Debug;
use std::fmt::Write;
use std::sync::Arc;

use crate::redaction_engine_builder::RedactionEngineBuilder;
use crate::redaction_engine_inner::RedactionEngineInner;
use crate::{DataClass, RedactedDebug, RedactedDisplay, RedactedToString, Redactor};

/// Lets you apply redaction to classified data.
///
/// You use [`RedactionEngineBuilder`] to create an instance of this type.
/// The builder lets you configure exactly which redactor to use to redact individual data classes encountered
/// while producing telemetry.
///
/// ## Example
///
/// ```rust
/// use data_privacy::simple_redactor::{SimpleRedactor, SimpleRedactorMode};
/// use data_privacy::{RedactionEngine, classified, taxonomy};
///
/// // The taxonomy defines the different data classes we will use in our application.
/// #[taxonomy(simple)]
/// enum SimpleTaxonomy {
///     Sensitive,
///     ExtremelySensitive,
/// }
///
/// // A struct holding some data classified as sensitive.
/// #[classified(SimpleTaxonomy::Sensitive)]
/// struct Name(String);
///
/// struct Person {
///     name: Name, // a bit of sensitive data we should not leak in logs
///     age: u32,
/// }
///
/// let person = Person {
///     name: Name("John Doe".to_string()),
///     age: 30,
/// };
///
/// let asterisk_redactor = SimpleRedactor::new();
/// let erasing_redactor = SimpleRedactor::with_mode(SimpleRedactorMode::Erase);
///
/// // Create the redaction engine. This is typically done once when the application starts.
/// let engine = RedactionEngine::builder()
///     .add_class_redactor(SimpleTaxonomy::Sensitive.data_class(), asterisk_redactor)
///     .set_fallback_redactor(erasing_redactor)
///     .build();
///
/// let mut output_buffer = String::new();
/// _ = engine.redacted_display(&person.name, &mut output_buffer);
///
/// // check that the data in the output buffer has indeed been redacted as expected.
/// assert_eq!(output_buffer, "********");
/// ```
#[derive(Clone, Default)]
pub struct RedactionEngine {
    inner: Arc<RedactionEngineInner>,
}

impl RedactionEngine {
    /// Constructs a new [`RedactionEngineBuilder`].
    #[must_use]
    pub fn builder() -> RedactionEngineBuilder {
        RedactionEngineBuilder::new()
    }

    #[must_use]
    pub(crate) fn new(mut inner: RedactionEngineInner) -> Self {
        inner.shrink();
        Self { inner: Arc::new(inner) }
    }

    /// Redacts a value implementing [`RedactedDebug`], sending the results to the output sink.
    ///
    /// # Errors
    ///
    /// This function returns [`Err`] if, and only if, writing to the provided output sink (which implements [`Write`]) returns [`Err`]. String redaction is considered an infallible operation;
    /// this function only returns a [`std::fmt::Result`] because writing to the underlying sink might fail and it must provide a way to propagate the fact that an error
    /// has occurred (as a [`std::fmt::Error`]) back up the stack.
    pub fn redacted_debug(&self, value: &impl RedactedDebug, output: &mut impl Write) -> core::fmt::Result {
        let d = core::fmt::from_fn(|f| value.fmt(self, f));
        write!(output, "{d:?}")
    }

    /// Redacts a value implementing [`RedactedDisplay`], sending the results to the output sink.
    ///
    /// # Errors
    ///
    /// This function returns [`Err`] if, and only if, writing to the provided output sink (which implements [`Write`]) returns [`Err`]. String redaction is considered an infallible operation;
    /// this function only returns a [`std::fmt::Result`] because writing to the underlying sink might fail and it must provide a way to propagate the fact that an error
    /// has occurred (as a [`std::fmt::Error`]) back up the stack.
    pub fn redacted_display(&self, value: &impl RedactedDisplay, output: &mut impl Write) -> core::fmt::Result {
        let d = core::fmt::from_fn(|f| value.fmt(self, f));
        write!(output, "{d}")
    }

    /// Redacts a value implementing [`RedactedToString`] and returns the redacted string.
    pub fn redacted_to_string(&self, value: &impl RedactedToString) -> String {
        value.to_redacted_string(self)
    }
}

impl Redactor for RedactionEngine {
    fn redacts(&self, data_class: &DataClass) -> bool {
        self.inner.redacts(data_class)
    }

    fn redact(&self, data_class: &DataClass, value: &str, output: &mut dyn Write) -> core::fmt::Result {
        if let Some(strategy) = self.inner.resolve(data_class) {
            strategy.redact(data_class, value, output)
        } else {
            // Redaction has been explicitly suppressed for this data class; pass through unmodified,
            // bypassing both class-specific and fallback redactors.
            output.write_str(value)
        }
    }
}

impl Debug for RedactionEngine {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        self.inner.fmt(f)
    }
}