configbuilder-pattern-substitution 0.1.0

configbuilder-pattern: substitution domain, trait contract + reference implementation. No -svc counterpart.
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

use crate::SubstitutionError;

/// Policy for controlling which environment variables may be substituted into config values.
///
/// Implementations decide whether a variable name is allowed. The loader calls
/// `validate` on every `{{VAR_NAME}}` placeholder before substituting it;
/// rejection returns a config I/O error to the caller.
///
/// Built-in implementations: [`PrefixWhitelistPolicy`], [`PatternWhitelistPolicy`],
/// [`CompositePolicy`]. For tests only: `AllowAllPolicy` (requires the
/// `test-utils` feature). Implement this trait when the built-ins do not match
/// your security requirements.
///
/// [`PrefixWhitelistPolicy`]: crate::PrefixWhitelistPolicy
/// [`PatternWhitelistPolicy`]: crate::PatternWhitelistPolicy
/// [`CompositePolicy`]: crate::CompositePolicy
pub trait SubstitutionPolicy: Send + Sync {
    /// Decide whether `var_name` may be substituted into a config value.
    ///
    /// Return `Ok(())` to permit substitution or `Err(reason)` to reject it.
    /// The `reason` string is included verbatim in the config I/O error message
    /// returned to the caller.
    fn validate(&self, var_name: &str) -> Result<(), SubstitutionError>;

    /// Human-readable label included in rejection error messages.
    ///
    /// Defaults to `"custom policy"`. Override to identify your policy by name in
    /// logs and error output.
    fn description(&self) -> String {
        "custom policy".to_string()
    }
}