yeti_types/

safety.rs

//! Deployment-safety declarations for toggleable internal crates.
//!
//! Every crate that adds a config-gated feature (anything that reads a
//! top-level section from yeti-config.yaml and may `enabled: true/false`)
//! exports a `pub const SAFETY: SafetyProfile` and submits it to the
//! inventory registry so:
//!
//!   * `yeti config lint` can validate config files against a deployment
//!     profile (local / fabric / self-host).
//!   * `yeti-feature-matrix` can render a human-readable capability table
//!     as `docs/reference/feature-matrix.md`.
//!   * CI can diff the generated matrix against the checked-in file and
//!     fail the PR if they drift.
//!
//! The crate's `Cargo.toml` may additionally be excluded from the
//! `fabric` cargo feature set, which is the strongest layer — a
//! fabric-excluded crate isn't in the binary at all.

/// Deployment-safety metadata for one toggleable crate or sub-feature.
///
/// Profiles are declared as `const` and collected via
/// `inventory::collect!`. At runtime the linter and matrix-generator
/// walk the registry and check each entry against the target deployment
/// profile (see `DeploymentProfile`).
#[derive(Debug, Clone, Copy)]
pub struct SafetyProfile {
    /// Config section / feature name this profile guards. Matches the
    /// top-level yeti-config.yaml key (e.g. `"workspace"`, `"ratelimit"`).
    /// Sub-features use a qualified key (e.g. `"admin.files"`).
    pub name: &'static str,

    /// Whether the crate may be enabled on multi-tenant Fabric
    /// deployments. `false` means the crate's functionality is unsafe
    /// in a shared-infrastructure context (typically because it grants
    /// ambient OS-level authority that cgroups alone can't contain).
    pub fabric_allowed: bool,

    /// Default `enabled:` state when the section is absent from config.
    /// `false` for anything fabric-unsafe (safe-by-default). `true` for
    /// always-on platform primitives (auth, telemetry).
    pub default_enabled: bool,

    /// Human-readable explanation. Shown in the feature matrix and in
    /// lint errors. Keep it short and answer "why is this the default?"
    pub rationale: &'static str,
}

/// Which deployment profile a config is being validated against.
///
/// Profiles differ in what they permit:
///   * `Local` — a developer's workstation. All crates permitted; the
///     operator IS the trust boundary.
///   * `SelfHost` — a single customer's self-hosted server. Defaults to
///     the same permissions as `Local`; operators can tighten by
///     providing their own profile override YAML.
///   * `Fabric` — multi-tenant cloud. Only `fabric_allowed: true`
///     crates may be enabled.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DeploymentProfile {
    /// Developer's local workstation. Permissive.
    Local,
    /// Single-tenant self-hosted deployment. Operator-trusted.
    SelfHost,
    /// Multi-tenant shared infrastructure. Restricted.
    Fabric,
}

impl DeploymentProfile {
    /// Parse a profile from a string (as passed to `yeti config lint
    /// --profile <name>`).
    #[must_use]
    pub fn from_name(name: &str) -> Option<Self> {
        match name {
            "local" => Some(Self::Local),
            "self-host" | "selfhost" => Some(Self::SelfHost),
            "fabric" => Some(Self::Fabric),
            _ => None,
        }
    }

    /// The name shown in CLI help + lint error output.
    #[must_use]
    pub const fn name(&self) -> &'static str {
        match self {
            Self::Local => "local",
            Self::SelfHost => "self-host",
            Self::Fabric => "fabric",
        }
    }
}

impl SafetyProfile {
    /// Whether this crate may be enabled under the given deployment
    /// profile. Used by `yeti config lint`.
    #[must_use]
    pub const fn allowed_under(&self, profile: DeploymentProfile) -> bool {
        match profile {
            DeploymentProfile::Fabric => self.fabric_allowed,
            // Local + SelfHost permit everything; the operator owns the
            // trust boundary. If a self-host operator wants to tighten,
            // they run `yeti config lint --profile fabric` as a stricter
            // gate.
            DeploymentProfile::Local | DeploymentProfile::SelfHost => true,
        }
    }
}

// Inventory registration — every toggleable crate calls
// `inventory::submit! { SAFETY }` at the top level. The linter and
// matrix-generator iterate via `inventory::iter::<SafetyProfile>`.
inventory::collect!(SafetyProfile);

/// Iterate every registered `SafetyProfile`. Returned in unspecified
/// order; callers that need deterministic output (e.g. matrix-generator)
/// should sort by `name`.
pub fn registered_profiles() -> impl Iterator<Item = &'static SafetyProfile> {
    inventory::iter::<SafetyProfile>()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn deployment_profile_from_name_round_trip() {
        for profile in [
            DeploymentProfile::Local,
            DeploymentProfile::SelfHost,
            DeploymentProfile::Fabric,
        ] {
            assert_eq!(DeploymentProfile::from_name(profile.name()), Some(profile));
        }
    }

    #[test]
    fn deployment_profile_from_name_accepts_aliases() {
        // The `self-host` canonical form + the `selfhost` alias both parse.
        assert_eq!(
            DeploymentProfile::from_name("selfhost"),
            Some(DeploymentProfile::SelfHost)
        );
        assert_eq!(
            DeploymentProfile::from_name("self-host"),
            Some(DeploymentProfile::SelfHost)
        );
    }

    #[test]
    fn deployment_profile_from_name_rejects_unknown() {
        assert_eq!(DeploymentProfile::from_name("production"), None);
        assert_eq!(DeploymentProfile::from_name(""), None);
    }

    #[test]
    fn allowed_under_fabric_respects_flag() {
        let unsafe_for_fabric = SafetyProfile {
            name: "test-unsafe",
            fabric_allowed: false,
            default_enabled: false,
            rationale: "",
        };
        let safe_for_fabric = SafetyProfile {
            name: "test-safe",
            fabric_allowed: true,
            default_enabled: true,
            rationale: "",
        };
        assert!(!unsafe_for_fabric.allowed_under(DeploymentProfile::Fabric));
        assert!(safe_for_fabric.allowed_under(DeploymentProfile::Fabric));
    }

    #[test]
    fn allowed_under_local_and_self_host_permits_all() {
        let unsafe_for_fabric = SafetyProfile {
            name: "test",
            fabric_allowed: false,
            default_enabled: false,
            rationale: "",
        };
        assert!(unsafe_for_fabric.allowed_under(DeploymentProfile::Local));
        assert!(unsafe_for_fabric.allowed_under(DeploymentProfile::SelfHost));
    }
}