qubit-redact 0.4.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,
    InputOutputLimit,
    MaskPolicy,
    MaskingPolicy,
    PolicyError,
    PolicyLocation,
    RedactionFloor,
    RedactionLimits,
    RedactionPolicy,
    RedactionRules,
    RedactionRulesBuilder,
    SensitiveFieldPreset,
    Sensitivity,
    UnknownFieldPolicy,
};
#[cfg(feature = "json")]
use super::{
    JsonDepthBudget,
    UnkeyedJsonValuePolicy,
};

/// Mutable construction state for an immutable [`RedactionPolicy`].
#[must_use]
#[derive(Debug, Clone)]
pub struct RedactionPolicyBuilder {
    rules: RedactionRulesBuilder,
    masking: MaskingPolicy,
    floor: Option<RedactionFloor>,
    limits: RedactionLimits,
    #[cfg(feature = "http")]
    http: crate::http::HttpPolicyBuilder,
    #[cfg(feature = "uri")]
    uri: crate::uri::UriPolicyBuilder,
    #[cfg(feature = "json")]
    unkeyed_json_value_policy: UnkeyedJsonValuePolicy,
}

impl RedactionPolicyBuilder {
    /// Creates an empty application-rule builder with the standard floor.
    pub fn new() -> Self {
        Self {
            rules: RedactionRulesBuilder::empty(PolicyLocation::Rules),
            masking: MaskingPolicy::default(),
            floor: Some(RedactionFloor::standard()),
            limits: RedactionLimits::default(),
            #[cfg(feature = "http")]
            http: crate::http::HttpPolicyBuilder::new(),
            #[cfg(feature = "uri")]
            uri: crate::uri::UriPolicyBuilder::new(),
            #[cfg(feature = "json")]
            unkeyed_json_value_policy: UnkeyedJsonValuePolicy::PassThrough,
        }
    }
    pub(super) fn from_policy(policy: &RedactionPolicy) -> Self {
        Self {
            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::http::HttpPolicyBuilder::from_policy(policy.http()),
            #[cfg(feature = "uri")]
            uri: crate::uri::UriPolicyBuilder::from_policy(policy.uri()),
            #[cfg(feature = "json")]
            unkeyed_json_value_policy: policy.unkeyed_json_value_policy(),
        }
    }

    /// Returns the mutable base-field configuration view.
    pub fn fields(&mut self) -> FieldsBuilder<'_> {
        FieldsBuilder { builder: self }
    }

    /// Returns the mutable HTTP configuration view.
    #[cfg(feature = "http")]
    pub fn http(&mut self) -> HttpPolicyBuilderView<'_> {
        HttpPolicyBuilderView { builder: self }
    }

    /// Returns the mutable URI configuration view.
    #[cfg(feature = "uri")]
    pub fn uri(&mut self) -> UriPolicyBuilderView<'_> {
        UriPolicyBuilderView {
            builder: &mut self.uri,
        }
    }

    /// Returns the mutable static-limits configuration view.
    pub fn limits(&mut self) -> LimitsBuilder<'_> {
        LimitsBuilder { builder: 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)
    }

    /// Replaces the floor snapshot and marks it as explicitly configured.
    ///
    /// This is last-call-wins with [`Self::disable_floor`].
    pub fn floor(mut self, floor: RedactionFloor) -> Self {
        self.floor = Some(floor);
        self
    }
    /// Disables every floor, including the standard floor.
    ///
    /// # Security
    ///
    /// This removes minimum field protection. Call it only when this is an
    /// intentional, reviewed decision by the policy owner.
    pub fn disable_floor(mut self) -> Self {
        self.floor = None;
        self
    }

    /// Sets application field-name matching behavior.
    pub fn matching(mut self, matching: FieldNameMatching) -> Self {
        self.rules.matching(matching);
        self
    }

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

    /// Adds every sensitive field defined by `preset` to application rules.
    pub fn include_preset(mut self, preset: SensitiveFieldPreset) -> Self {
        self.rules.include_preset(preset);
        self
    }

    /// Raises application sensitivity for `field` to at least `level`.
    ///
    /// Repeated calls for the same canonical field are monotonic. When several
    /// differently named rules match one input field, final resolution uses
    /// the strongest matching sensitivity. For example, `token = Secret` and
    /// `access_token = Medium` resolve `OPENAI_ACCESS_TOKEN` to `Secret`.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFieldName`] when `field` has no canonical
    /// application-rule name.
    pub fn raise(
        mut self,
        field: &str,
        level: Sensitivity,
    ) -> Result<Self, PolicyError> {
        self.rules.raise(field, level)?;
        Ok(self)
    }

    /// Replaces the application sensitivity for `field` with `level`.
    ///
    /// This replaces only the same canonical rule. It does not weaken an
    /// enabled floor or a stronger overlapping rule with another name.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFieldName`] when `field` has no canonical
    /// application-rule name.
    pub fn override_level(
        mut self,
        field: &str,
        level: Sensitivity,
    ) -> Result<Self, PolicyError> {
        self.rules.override_level(field, level)?;
        Ok(self)
    }

    /// Allows one canonical exact application field name.
    ///
    /// An enabled floor remains independently effective for the same field.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFieldName`] when `field` has no canonical
    /// application-rule name.
    pub fn allow_canonical_exact(
        mut self,
        field: &str,
    ) -> Result<Self, PolicyError> {
        self.rules.allow_canonical_exact(field)?;
        Ok(self)
    }

    /// Allows one application field-name token suffix.
    ///
    /// An enabled floor remains independently effective for matching fields.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFieldName`] when `field` has no canonical
    /// application-rule name.
    pub fn allow_suffix(mut self, field: &str) -> Result<Self, PolicyError> {
        self.rules.allow_suffix(field)?;
        Ok(self)
    }

    /// Removes the exact application allow rule for `field` when present.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFieldName`] when `field` has no canonical
    /// application-rule name.
    pub fn remove_allow_canonical_exact(
        mut self,
        field: &str,
    ) -> Result<Self, PolicyError> {
        self.rules.remove_allow_canonical_exact(field)?;
        Ok(self)
    }

    /// Removes the suffix application allow rule for `field` when present.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFieldName`] when `field` has no canonical
    /// application-rule name.
    pub fn remove_allow_suffix(
        mut self,
        field: &str,
    ) -> Result<Self, PolicyError> {
        self.rules.remove_allow_suffix(field)?;
        Ok(self)
    }

    /// Removes every application allow rule.
    pub fn clear_allow_rules(mut self) -> Self {
        self.rules.clear_allow_rules();
        self
    }

    /// Sets the application masking policy for values at `level`.
    ///
    /// # Errors
    ///
    /// Returns [`PolicyError::EmptyFixedReplacement`] when `policy` supplies
    /// an empty fixed replacement.
    pub fn mask(
        mut self,
        level: Sensitivity,
        policy: MaskPolicy,
    ) -> Result<Self, PolicyError> {
        let masking = self.masking.with_policy(level, policy);
        masking.validate(PolicyLocation::Rules)?;
        self.masking = masking;
        Ok(self)
    }

    /// Sets the diagnostic-event input and output limits.
    pub const fn diagnostic_event(mut self, budget: InputOutputLimit) -> Self {
        self.limits = self.limits.with_diagnostic_event(budget);
        self
    }

    /// Sets the ordinary operation input and output limits.
    pub const fn ordinary_operation(
        mut self,
        budget: InputOutputLimit,
    ) -> Self {
        self.limits = self.limits.with_ordinary_operation(budget);
        self
    }

    /// Sets HTTP URL path handling in the unified policy.
    #[cfg(feature = "http")]
    pub fn url_path_policy(
        mut self,
        policy: crate::http::UrlPathPolicy,
    ) -> Self {
        self.http.url_path_mut(policy);
        self
    }

    /// Sets HTTP opaque text-body handling in the unified policy.
    #[cfg(feature = "http")]
    pub fn text_body_policy(
        mut self,
        policy: crate::http::TextBodyPolicy,
    ) -> Self {
        self.http.text_body_mut(policy);
        self
    }

    /// Sets HTTP structured body limits in the unified policy.
    #[cfg(feature = "http")]
    pub fn body_budget(mut self, budget: crate::http::BodyBudget) -> Self {
        self.limits = self.limits.with_http_body(budget);
        self
    }

    /// Sets URI path handling in the unified policy.
    #[cfg(feature = "uri")]
    pub fn path_policy(mut self, policy: crate::uri::UriPathPolicy) -> Self {
        self.uri = self.uri.path_policy(policy);
        self
    }

    /// Sets URI fragment handling in the unified policy.
    #[cfg(feature = "uri")]
    pub fn fragment_policy(
        mut self,
        policy: crate::uri::UriFragmentPolicy,
    ) -> Self {
        self.uri = self.uri.fragment_policy(policy);
        self
    }

    /// Sets the maximum JSON nesting depth used by JSON redaction.
    #[cfg(feature = "json")]
    pub const fn json_depth_budget(mut self, budget: JsonDepthBudget) -> Self {
        self.limits = self.limits.with_json_depth_budget(budget);
        self
    }

    /// Sets behavior for root and array JSON scalar values.
    #[cfg(feature = "json")]
    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,
        ))
    }
}

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

    /// Mutable view over the base field policy.
    #[must_use]
    pub struct FieldsBuilder<'a> {
        pub(super) builder: &'a mut RedactionPolicyBuilder,
    }

    impl FieldsBuilder<'_> {
        /// Sets field-name matching for the base policy.
        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,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.rules.raise(field, level)?;
            Ok(self)
        }

        /// Replaces one base field rule without weakening floors.
        pub fn override_level(
            &mut self,
            field: &str,
            level: Sensitivity,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.rules.override_level(field, level)?;
            Ok(self)
        }

        /// Adds a base exact allow rule.
        pub fn allow_exact(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.rules.allow_canonical_exact(field)?;
            Ok(self)
        }

        /// Adds a base suffix allow rule.
        pub fn allow_suffix(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.rules.allow_suffix(field)?;
            Ok(self)
        }

        /// Removes a base exact allow rule.
        pub fn remove_allow_exact(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.rules.remove_allow_canonical_exact(field)?;
            Ok(self)
        }

        /// Removes a base suffix allow rule.
        pub fn remove_allow_suffix(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.rules.remove_allow_suffix(field)?;
            Ok(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.
        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,
        ) -> Result<&mut Self, PolicyError> {
            let masking =
                self.builder.masking.clone().with_policy(level, policy);
            masking.validate(PolicyLocation::Rules)?;
            self.builder.masking = masking;
            Ok(self)
        }
    }

    /// Mutable view over all HTTP context differences.
    #[cfg(feature = "http")]
    #[must_use]
    pub struct HttpPolicyBuilderView<'a> {
        pub(super) builder: &'a mut RedactionPolicyBuilder,
    }

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

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

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

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

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

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

        /// Sets URL path visibility for HTTP diagnostics.
        pub fn url_path(
            &mut self,
            policy: crate::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::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::http::UnkeyedJsonValuePolicy,
        ) -> &mut Self {
            self.builder.unkeyed_json_value_policy = policy;
            self
        }
    }

    /// Mutable view over one HTTP field context.
    #[cfg(feature = "http")]
    #[must_use]
    pub struct HttpContextBuilderView<'a> {
        builder: &'a mut crate::http::HttpPolicyBuilder,
        context: crate::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.
        pub fn raise(
            &mut self,
            field: &str,
            level: Sensitivity,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.raise_mut(self.context, field, level)?;
            Ok(self)
        }

        /// Replaces a context field rule without weakening the base policy.
        pub fn override_level(
            &mut self,
            field: &str,
            level: Sensitivity,
        ) -> Result<&mut Self, PolicyError> {
            self.builder
                .override_level_mut(self.context, field, level)?;
            Ok(self)
        }

        /// Adds a context exact allow rule; the base policy still applies.
        pub fn allow_exact(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.allow_exact_mut(self.context, field)?;
            Ok(self)
        }

        /// Adds a context suffix allow rule; the base policy still applies.
        pub fn allow_suffix(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.allow_suffix_mut(self.context, field)?;
            Ok(self)
        }

        /// Removes a context exact allow rule.
        pub fn remove_allow_exact(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.remove_allow_exact_mut(self.context, field)?;
            Ok(self)
        }

        /// Removes a context suffix allow rule.
        pub fn remove_allow_suffix(
            &mut self,
            field: &str,
        ) -> Result<&mut Self, PolicyError> {
            self.builder.remove_allow_suffix_mut(self.context, field)?;
            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.
        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
        }
    }

    /// Mutable view over policy limits.
    #[must_use]
    pub struct LimitsBuilder<'a> {
        pub(super) builder: &'a mut RedactionPolicyBuilder,
    }

    impl LimitsBuilder<'_> {
        /// Sets the cumulative diagnostic-event limit.
        pub fn diagnostic_event(
            &mut self,
            limit: InputOutputLimit,
        ) -> &mut Self {
            self.builder.limits =
                self.builder.limits.with_diagnostic_event(limit);
            self
        }

        /// Sets the independent ordinary-operation limit.
        pub fn ordinary_operation(
            &mut self,
            limit: InputOutputLimit,
        ) -> &mut Self {
            self.builder.limits =
                self.builder.limits.with_ordinary_operation(limit);
            self
        }

        /// Sets the local HTTP body limit.
        #[cfg(feature = "http")]
        pub fn http_body(
            &mut self,
            limit: crate::http::BodyBudget,
        ) -> &mut Self {
            self.builder.limits = self.builder.limits.with_http_body(limit);
            self
        }

        /// Sets the JSON recursion-depth limit.
        #[cfg(feature = "json")]
        pub fn json_depth(&mut self, limit: JsonDepthBudget) -> &mut Self {
            self.builder.limits =
                self.builder.limits.with_json_depth_budget(limit);
            self
        }
    }
}

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

impl Default for RedactionPolicyBuilder {
    fn default() -> Self {
        Self::new()
    }
}