qubit-redact 0.5.0

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Mutable builder for immutable redaction policies.

use super::FieldNameMatching;
use super::MaskPolicy;
use super::MaskingPolicy;
use super::PolicyError;
use super::PolicyLocation;
use super::RedactionFloor;
use super::RedactionLimits;
use super::RedactionLimitsBuilder;
use super::RedactionPolicy;
use super::RedactionRules;
use super::RedactionRulesBuilder;
use super::SensitiveFieldPreset;
use super::Sensitivity;
#[cfg(feature = "json")]
use super::UnkeyedJsonValuePolicy;
use super::UnknownFieldPolicy;

/// Mutable construction state for an immutable [`RedactionPolicy`].
///
/// Configuration setters are available through the grouped views returned by
/// [`Self::fields`] and [`Self::limits`], with feature-specific HTTP and URI
/// views when those formats are enabled.
/// Duplicate consuming setters are intentionally not available at this level:
///
/// ```compile_fail
/// use qubit_redact::{RedactionPolicy, Sensitivity};
///
/// let _ = RedactionPolicy::builder().raise("token", Sensitivity::Secret);
/// ```
///
/// # Examples
///
/// ```
/// use qubit_redact::RedactionPolicy;
///
/// let policy = RedactionPolicy::builder()
///     .fields(|fields| {
///         let _ = fields.secret_sensitive("api_token");
///     })
///     .expect("valid field rules")
///     .build()
///     .expect("valid policy");
/// assert!(policy.sensitivity_for("api_token").is_some());
/// ```
#[derive(Debug, Clone)]
pub struct RedactionPolicyBuilder {
    /// Whether the resulting policy bypasses redaction.
    disabled: bool,
    /// Mutable application field rules.
    rules: RedactionRulesBuilder,
    /// Shared masking strategies by sensitivity.
    masking: MaskingPolicy,
    /// Optional minimum-protection floor.
    floor: Option<RedactionFloor>,
    /// Resource limits for each transaction.
    limits: RedactionLimits,
    /// Mutable HTTP-specific policy state.
    #[cfg(feature = "http")]
    http: crate::formats::http::HttpPolicyBuilder,
    /// Mutable URI-specific policy state.
    #[cfg(feature = "uri")]
    uri: crate::formats::uri::UriPolicyBuilder,
    /// Handling for JSON scalars without a field key.
    #[cfg(feature = "json")]
    unkeyed_json_value_policy: UnkeyedJsonValuePolicy,
}

impl RedactionPolicyBuilder {
    /// Creates an empty application-rule builder with the standard floor.
    #[must_use]
    pub fn new() -> Self {
        Self {
            disabled: false,
            rules: RedactionRulesBuilder::empty(PolicyLocation::Rules),
            masking: MaskingPolicy::default(),
            floor: Some(RedactionFloor::standard()),
            limits: RedactionLimits::default(),
            #[cfg(feature = "http")]
            http: crate::formats::http::HttpPolicyBuilder::new(),
            #[cfg(feature = "uri")]
            uri: crate::formats::uri::UriPolicyBuilder::new(),
            #[cfg(feature = "json")]
            unkeyed_json_value_policy: UnkeyedJsonValuePolicy::PassThrough,
        }
    }
    /// Copies the immutable policy into mutable builder state.
    #[must_use]
    pub(super) fn from_policy(policy: &RedactionPolicy) -> Self {
        Self {
            disabled: policy.is_disabled(),
            rules: RedactionRulesBuilder::from_inner(&policy.rules().clone_application(), PolicyLocation::Rules),
            masking: policy.masking().clone(),
            floor: policy.rules().floor().cloned(),
            limits: *policy.limits(),
            #[cfg(feature = "http")]
            http: crate::formats::http::HttpPolicyBuilder::from_policy(policy.http()),
            #[cfg(feature = "uri")]
            uri: crate::formats::uri::UriPolicyBuilder::from_policy(policy.uri()),
            #[cfg(feature = "json")]
            unkeyed_json_value_policy: policy.unkeyed_json_value_policy(),
        }
    }

    /// Configures base field sensitivity rules transactionally.
    ///
    /// The closure writes into a temporary field draft. Field names are
    /// validated after the closure returns and the draft is applied only when
    /// every field is valid. The configuration methods inside the closure are
    /// therefore infallible and can be chained without a trailing `Ok(())`.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError`] when a field name is empty after
    /// canonicalization. The builder remains unchanged on error.
    pub fn fields<F>(self, configure: F) -> Result<Self, PolicyError>
    where
        F: FnOnce(&mut FieldsBuilder<'_>),
    {
        let mut draft = self.clone();
        let error = {
            let mut fields = FieldsBuilder {
                builder: &mut draft,
                error: None,
            };
            configure(&mut fields);
            fields.error.take()
        };
        if let Some(error) = error {
            return Err(error);
        }
        Ok(draft)
    }

    /// Configures HTTP policy through an isolated draft.
    ///
    /// The draft replaces this namespace only after the closure returns, so a
    /// failed build never partially updates the caller's builder.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError`] when the HTTP view records an invalid field
    /// rule. The original builder remains unchanged.
    #[cfg(feature = "http")]
    pub fn http<F>(self, configure: F) -> Result<Self, PolicyError>
    where
        F: FnOnce(&mut HttpPolicyBuilderView<'_>),
    {
        let mut draft = self.clone();
        let error = {
            let mut view = HttpPolicyBuilderView {
                builder: &mut draft,
                error: None,
            };
            configure(&mut view);
            view.error.take()
        };
        if let Some(error) = error {
            return Err(error);
        }
        Ok(draft)
    }

    /// Configures URI policy through an isolated draft.
    ///
    /// # Errors
    ///
    /// This operation is currently infallible. The result preserves the
    /// transactional shape shared by feature-specific builder views.
    #[cfg(feature = "uri")]
    pub fn uri<F>(self, configure: F) -> Result<Self, PolicyError>
    where
        F: FnOnce(&mut UriPolicyBuilderView<'_>),
    {
        let mut draft = self.clone();
        let mut view = UriPolicyBuilderView {
            builder: &mut draft.uri,
        };
        configure(&mut view);
        Ok(draft)
    }

    /// Configures transaction limits through a draft that is applied
    /// atomically.
    ///
    /// The closure mutates only a temporary limits builder. Once it returns,
    /// the completed limits replace this builder's limits as one update.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError`] when the completed limit set violates a
    /// cross-limit invariant. The original builder remains unchanged.
    pub fn limits<F>(mut self, configure: F) -> Result<Self, PolicyError>
    where
        F: FnOnce(&mut RedactionLimitsBuilder),
    {
        let mut limits = RedactionLimits::builder_from(&self.limits);
        configure(&mut limits);
        let limits = limits.build();
        limits.validate()?;
        self.limits = limits;
        Ok(self)
    }

    /// Validates that `field` has a non-empty canonical application-rule name.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFieldName`] at
    /// [`PolicyLocation::Rules`] when canonicalization leaves no name.
    pub fn validate_field_name(field: &str) -> Result<(), PolicyError> {
        RedactionRulesBuilder::validate_field_name(field, PolicyLocation::Rules)
    }

    /// Sets behavior for root and array JSON scalar values.
    ///
    /// This setter remains on the root builder because the JSON feature does
    /// not expose a separate grouped builder.
    #[cfg(feature = "json")]
    #[must_use]
    pub const fn unkeyed_json_value_policy(mut self, policy: UnkeyedJsonValuePolicy) -> Self {
        self.unkeyed_json_value_policy = policy;
        self
    }

    /// Validates and returns the immutable policy snapshot.
    ///
    /// # Errors
    ///
    /// Returns a [`PolicyError`] when final policy validation fails.
    pub fn build(self) -> Result<RedactionPolicy, PolicyError> {
        let rules = RedactionRules::new(self.rules.build_inner()?, self.floor);
        self.masking.validate(PolicyLocation::Rules)?;
        #[cfg(feature = "http")]
        let http = self.http.build()?;
        #[cfg(feature = "uri")]
        let uri = self.uri.build()?;
        Ok(RedactionPolicy::from_rules(
            rules,
            self.masking,
            self.limits,
            #[cfg(feature = "http")]
            http,
            #[cfg(feature = "uri")]
            uri,
            #[cfg(feature = "json")]
            self.unkeyed_json_value_policy,
            self.disabled,
        ))
    }
}

mod views {
    use super::FieldNameMatching;
    use super::MaskPolicy;
    use super::MaskingPolicy;
    use super::PolicyError;
    use super::PolicyLocation;
    use super::RedactionFloor;
    use super::RedactionPolicyBuilder;
    #[cfg(feature = "http")]
    use super::RedactionRules;
    use super::SensitiveFieldPreset;
    use super::Sensitivity;
    use super::UnknownFieldPolicy;

    /// Mutable view over the base field policy.
    pub struct FieldsBuilder<'a> {
        /// Root builder receiving validated field changes.
        pub(super) builder: &'a mut RedactionPolicyBuilder,
        /// First validation error recorded by the transactional view.
        pub(super) error: Option<PolicyError>,
    }

    impl FieldsBuilder<'_> {
        /// Raises one field's minimum sensitivity in a transactional draft.
        #[inline(always)]
        fn set_sensitive(&mut self, field: &str, level: Sensitivity) -> &mut Self {
            if self.error.is_none()
                && let Err(error) = self.builder.rules.raise(field, level)
            {
                self.error = Some(error);
            }
            self
        }

        /// Marks a field as low sensitivity.
        #[inline(always)]
        pub fn low_sensitive(&mut self, field: &str) -> &mut Self {
            self.set_sensitive(field, Sensitivity::Low)
        }

        /// Marks a field as medium sensitivity.
        #[inline(always)]
        pub fn medium_sensitive(&mut self, field: &str) -> &mut Self {
            self.set_sensitive(field, Sensitivity::Medium)
        }

        /// Marks a field as high sensitivity.
        #[inline(always)]
        pub fn high_sensitive(&mut self, field: &str) -> &mut Self {
            self.set_sensitive(field, Sensitivity::High)
        }

        /// Marks a field as secret sensitivity.
        #[inline(always)]
        pub fn secret_sensitive(&mut self, field: &str) -> &mut Self {
            self.set_sensitive(field, Sensitivity::Secret)
        }

        /// Raises a field's minimum sensitivity to `level`.
        #[inline(always)]
        pub fn sensitive(&mut self, level: Sensitivity, field: &str) -> &mut Self {
            self.set_sensitive(field, level)
        }

        /// Sets field-name matching for the base policy.
        #[inline(always)]
        pub fn matching(&mut self, matching: FieldNameMatching) -> &mut Self {
            self.builder.rules.matching(matching);
            self
        }

        /// Sets the base fallback for unknown fields.
        pub fn unknown_field_policy(&mut self, policy: UnknownFieldPolicy) -> &mut Self {
            self.builder.rules.unknown_field_policy(policy);
            self
        }

        /// Includes all fields from a built-in sensitive preset.
        pub fn include_preset(&mut self, preset: SensitiveFieldPreset) -> &mut Self {
            self.builder.rules.include_preset(preset);
            self
        }

        /// Raises a base field's minimum sensitivity.
        pub fn raise(&mut self, field: &str, level: Sensitivity) -> &mut Self {
            if self.error.is_none()
                && let Err(error) = self.builder.rules.raise(field, level)
            {
                self.error = Some(error);
            }
            self
        }

        /// Replaces one base field rule without weakening floors.
        pub fn override_level(&mut self, field: &str, level: Sensitivity) -> &mut Self {
            if self.error.is_none()
                && let Err(error) = self.builder.rules.override_level(field, level)
            {
                self.error = Some(error);
            }
            self
        }

        /// Adds a base exact allow rule.
        pub fn allow_exact(&mut self, field: &str) -> &mut Self {
            if self.error.is_none()
                && let Err(error) = self.builder.rules.allow_canonical_exact(field)
            {
                self.error = Some(error);
            }
            self
        }

        /// Adds a base suffix allow rule.
        pub fn allow_suffix(&mut self, field: &str) -> &mut Self {
            if self.error.is_none()
                && let Err(error) = self.builder.rules.allow_suffix(field)
            {
                self.error = Some(error);
            }
            self
        }

        /// Removes a base exact allow rule.
        pub fn remove_allow_exact(&mut self, field: &str) -> &mut Self {
            if self.error.is_none()
                && let Err(error) = self.builder.rules.remove_allow_canonical_exact(field)
            {
                self.error = Some(error);
            }
            self
        }

        /// Removes a base suffix allow rule.
        pub fn remove_allow_suffix(&mut self, field: &str) -> &mut Self {
            if self.error.is_none()
                && let Err(error) = self.builder.rules.remove_allow_suffix(field)
            {
                self.error = Some(error);
            }
            self
        }

        /// Removes all base allow rules.
        pub fn clear_allow_rules(&mut self) -> &mut Self {
            self.builder.rules.clear_allow_rules();
            self
        }

        /// Replaces the base minimum-protection floor.
        #[inline(always)]
        pub fn floor(&mut self, floor: RedactionFloor) -> &mut Self {
            self.builder.floor = Some(floor);
            self
        }

        /// Disables the base floor explicitly.
        pub fn disable_floor(&mut self) -> &mut Self {
            self.builder.floor = None;
            self
        }

        /// Replaces one shared masking level.
        pub fn mask(&mut self, level: Sensitivity, policy: MaskPolicy) -> &mut Self {
            let mut masking = MaskingPolicy::builder_from(&self.builder.masking);
            masking.policy(level, policy);
            let masking = masking.build();
            if self.error.is_none() {
                match masking.validate(PolicyLocation::Rules) {
                    Ok(()) => self.builder.masking = masking,
                    Err(error) => self.error = Some(error),
                }
            }
            self
        }
    }

    /// Mutable view over all HTTP context differences.
    #[cfg(feature = "http")]
    pub struct HttpPolicyBuilderView<'a> {
        /// Root builder receiving HTTP policy changes.
        pub(super) builder: &'a mut RedactionPolicyBuilder,
        /// First validation error recorded by the transactional view.
        pub(super) error: Option<PolicyError>,
    }

    /// Mutable view over URI-specific behavior.
    #[cfg(feature = "uri")]
    pub struct UriPolicyBuilderView<'a> {
        /// URI builder receiving view changes.
        pub(super) builder: &'a mut crate::formats::uri::UriPolicyBuilder,
    }

    #[cfg(feature = "uri")]
    impl UriPolicyBuilderView<'_> {
        /// Sets URI path visibility.
        pub fn path(&mut self, policy: crate::formats::uri::UriPathPolicy) -> &mut Self {
            self.builder.path_policy_mut(policy);
            self
        }

        /// Sets URI fragment visibility.
        pub fn fragment(&mut self, policy: crate::formats::uri::UriFragmentPolicy) -> &mut Self {
            self.builder.fragment_policy_mut(policy);
            self
        }
    }

    #[cfg(feature = "http")]
    impl HttpPolicyBuilderView<'_> {
        /// Returns the header context view.
        #[must_use]
        pub fn header(&mut self) -> HttpContextBuilderView<'_> {
            HttpContextBuilderView {
                builder: &mut self.builder.http,
                error: &mut self.error,
                context: crate::formats::http::HttpFieldContext::Header,
            }
        }

        /// Returns the query/form context view.
        #[must_use]
        pub fn query(&mut self) -> HttpContextBuilderView<'_> {
            HttpContextBuilderView {
                builder: &mut self.builder.http,
                error: &mut self.error,
                context: crate::formats::http::HttpFieldContext::Query,
            }
        }

        /// Returns the structured-body context view.
        #[must_use]
        pub fn body(&mut self) -> HttpContextBuilderView<'_> {
            HttpContextBuilderView {
                builder: &mut self.builder.http,
                error: &mut self.error,
                context: crate::formats::http::HttpFieldContext::Body,
            }
        }

        /// Sets URL path visibility for HTTP diagnostics.
        pub fn url_path(&mut self, policy: crate::formats::http::UrlPathPolicy) -> &mut Self {
            self.builder.http.url_path_mut(policy);
            self
        }

        /// Sets opaque text-body visibility for HTTP diagnostics.
        pub fn text_body(&mut self, policy: crate::formats::http::TextBodyPolicy) -> &mut Self {
            self.builder.http.text_body_mut(policy);
            self
        }

        /// Sets the same floor for every HTTP field context.
        pub fn floor_all(&mut self, floor: RedactionFloor) -> &mut Self {
            self.builder.http.floor_all_mut(floor);
            self
        }

        /// Disables every HTTP field-context floor explicitly.
        pub fn disable_all_floors(&mut self) -> &mut Self {
            self.builder.http.disable_all_floors_mut();
            self
        }

        /// Sets the handling of root and array JSON scalar values in HTTP
        /// bodies.
        pub fn unkeyed_json(&mut self, policy: crate::UnkeyedJsonValuePolicy) -> &mut Self {
            self.builder.unkeyed_json_value_policy = policy;
            self
        }
    }

    /// Mutable view over one HTTP field context.
    #[cfg(feature = "http")]
    pub struct HttpContextBuilderView<'a> {
        /// HTTP builder receiving context-specific changes.
        builder: &'a mut crate::formats::http::HttpPolicyBuilder,
        /// Shared transaction error slot.
        error: &'a mut Option<PolicyError>,
        /// Field context targeted by this view.
        context: crate::formats::http::HttpFieldContext,
    }

    #[cfg(feature = "http")]
    impl HttpContextBuilderView<'_> {
        /// Replaces all rules for this HTTP field context.
        pub fn replace_rules(&mut self, rules: RedactionRules) -> &mut Self {
            self.builder.rules_mut(self.context, rules);
            self
        }

        /// Raises a context field's minimum sensitivity.
        ///
        /// # Errors
        ///
        /// Returns [`PolicyError`] when `field` has no canonical name.
        pub fn raise(&mut self, field: &str, level: Sensitivity) -> Result<&mut Self, PolicyError> {
            if self.error.is_none()
                && let Err(error) = self.builder.raise_mut(self.context, field, level)
            {
                *self.error = Some(error.clone());
                return Err(error);
            }
            Ok(self)
        }

        /// Replaces a context field rule without weakening the base policy.
        ///
        /// # Errors
        ///
        /// Returns [`PolicyError`] when `field` has no canonical name.
        pub fn override_level(&mut self, field: &str, level: Sensitivity) -> Result<&mut Self, PolicyError> {
            if self.error.is_none()
                && let Err(error) = self.builder.override_level_mut(self.context, field, level)
            {
                *self.error = Some(error.clone());
                return Err(error);
            }
            Ok(self)
        }

        /// Adds a context exact allow rule; the base policy still applies.
        ///
        /// # Errors
        ///
        /// Returns [`PolicyError`] when `field` has no canonical name.
        pub fn allow_exact(&mut self, field: &str) -> Result<&mut Self, PolicyError> {
            if self.error.is_none()
                && let Err(error) = self.builder.allow_exact_mut(self.context, field)
            {
                *self.error = Some(error.clone());
                return Err(error);
            }
            Ok(self)
        }

        /// Adds a context suffix allow rule; the base policy still applies.
        ///
        /// # Errors
        ///
        /// Returns [`PolicyError`] when `field` has no canonical suffix.
        pub fn allow_suffix(&mut self, field: &str) -> Result<&mut Self, PolicyError> {
            if self.error.is_none()
                && let Err(error) = self.builder.allow_suffix_mut(self.context, field)
            {
                *self.error = Some(error.clone());
                return Err(error);
            }
            Ok(self)
        }

        /// Removes a context exact allow rule.
        ///
        /// # Errors
        ///
        /// Returns [`PolicyError`] when `field` has no canonical name.
        pub fn remove_allow_exact(&mut self, field: &str) -> Result<&mut Self, PolicyError> {
            if self.error.is_none()
                && let Err(error) = self.builder.remove_allow_exact_mut(self.context, field)
            {
                *self.error = Some(error.clone());
                return Err(error);
            }
            Ok(self)
        }

        /// Removes a context suffix allow rule.
        ///
        /// # Errors
        ///
        /// Returns [`PolicyError`] when `field` has no canonical suffix.
        pub fn remove_allow_suffix(&mut self, field: &str) -> Result<&mut Self, PolicyError> {
            if self.error.is_none()
                && let Err(error) = self.builder.remove_allow_suffix_mut(self.context, field)
            {
                *self.error = Some(error.clone());
                return Err(error);
            }
            Ok(self)
        }

        /// Removes all context allow rules.
        pub fn clear_allow_rules(&mut self) -> &mut Self {
            self.builder.clear_allow_rules_mut(self.context);
            self
        }

        /// Adds a context floor. Base protection remains independently
        /// effective.
        #[must_use]
        #[inline(always)]
        pub fn floor(&mut self, floor: RedactionFloor) -> &mut Self {
            self.builder.floor_mut(self.context, floor);
            self
        }

        /// Disables this context's explicit floor.
        pub fn disable_floor(&mut self) -> &mut Self {
            self.builder.disable_floor_mut(self.context);
            self
        }
    }
}

pub use views::FieldsBuilder;
#[cfg(feature = "http")]
pub use views::HttpContextBuilderView;
#[cfg(feature = "http")]
pub use views::HttpPolicyBuilderView;
#[cfg(feature = "uri")]
pub use views::UriPolicyBuilderView;

impl Default for RedactionPolicyBuilder {
    /// Creates a builder with the standard floor and default limits.
    fn default() -> Self {
        Self::new()
    }
}