forge_primitives/

settings.rs

//! The effective-config document a server pushes to every client.
//!
//! One document is built per load and shared by every connection: the areas
//! `forge.toml` is read into, every key's effective value, and the class that
//! says when an edit to that key takes effect. Values cross as the file loads
//! them, unredacted - the socket is reached over loopback or the private
//! network, which is the boundary.

use serde::{Deserialize, Serialize};

/// When an edit to a key takes effect.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EffectClass {
    /// Read on the key's next use.
    Live,
    /// Read when a session or a connection opens.
    NextSession,
    /// Built once at boot; an edit needs a restart.
    Restart,
    /// The loader accepts the key and nothing reads it yet.
    NotReadYet,
}

impl EffectClass {
    /// The word the page draws and the class catalogue's own name.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Live => "live",
            Self::NextSession => "next session",
            Self::Restart => "restart",
            Self::NotReadYet => "not read yet",
        }
    }
}

/// The shape of a key's value, so a client picks a drawing without guessing
/// from the text.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SettingKind {
    String,
    Number,
    Bool,
    List,
    Table,
    Set,
}

/// The control a key's value is edited with.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EditKind {
    String,
    Number,
    Bool,
    Enum,
    List,
}

/// One change in a batched save.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SettingsEditOp {
    Set,
    Add,
    Remove,
}

/// One edit a client asks the server to apply to `forge.toml`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsEditRequest {
    /// The area the page was drawing when the edit was made.
    pub area: String,
    /// The key's concrete path for a set or a leaf's removal, and the
    /// entry's path for an entry's add or removal.
    pub key_path: String,
    /// The catalogue pattern the key fills. Empty for an entry edit.
    #[serde(default)]
    pub pattern: String,
    pub op: SettingsEditOp,
    /// The new value: the key's value for a set, or an entry's fields for an
    /// add. Absent for a removal.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub value: Option<serde_json::Value>,
}

/// What the editor needs to draw a key's control and to know which entry it
/// belongs to.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsEdit {
    pub kind: EditKind,
    /// The accepted names for an `enum`, empty otherwise.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed: Vec<String>,
    /// Whether adding the owning entry requires the key.
    pub required: bool,
    /// The repeated entry a key belongs to: `account`, `project`, `slack`,
    /// `model` or `org`. Absent for a table's own keys.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub group: Option<String>,
}

/// One key's change in a held write.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsWriteChange {
    /// The concrete catalogue path the change names.
    pub key: String,
    /// The value the key stands at now; `null` when it is unset.
    pub current: serde_json::Value,
    /// The value the change would leave; `null` when it clears the key.
    pub proposed: serde_json::Value,
    /// Whether the change clears the key rather than setting it.
    pub unset: bool,
}

/// One configuration write held for the reader's approval.
///
/// The blocked `settings__set` / `settings__unset` handler awaits the
/// answer, and nothing reaches `forge.toml` unless it approved: this is the
/// shape the dock draws while it waits, so it carries what a person decides
/// on - every key in the save, what it holds now, and what the write would
/// leave. A batch is one ask and one approval because a section's keys can
/// be mutually required: neither half can land alone.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsWriteAsk {
    /// The write's own id, which is what an answer is addressed by.
    pub id: uuid::Uuid,
    /// The keys the one write changes, in the caller's order.
    pub edits: Vec<SettingsWriteChange>,
}

/// What ended a held write, which a view that did not answer it has no other
/// way to learn.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SettingsWriteEnding {
    /// The reader approved it and the edit was written.
    Applied,
    /// The reader declined it; nothing was written.
    Declined,
    /// The reader approved it and the write did not land, in the writer's
    /// own words. The ending is emitted after the write, so `Applied` above
    /// never stands for a failed one.
    Refused { message: String },
    /// The asking session went away before the write was settled.
    Abandoned,
}

/// One area of the config, as the page's sub-nav lists it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsArea {
    pub id: String,
    pub name: String,
    pub note: String,
    pub keys: Vec<SettingsKey>,
}

/// One key's effective value and the class that says when a change lands.
///
/// Hand-written `Debug`: a key's value can be an account token, and the frame
/// is the page's read rather than a diagnostic. The class and path stay
/// legible; the value never prints.
#[derive(Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsKey {
    /// The concrete key path, with the instance where the table repeats:
    /// `server.port`, `accounts.Subspace.token`.
    pub path: String,
    /// The key's own name as a row draws it: the catalogue key's leaf, or
    /// the slug or flag a repeated key names. A name may contain dots, so
    /// a reader cannot cut it from `path`.
    pub leaf: String,
    /// The instance names the row belongs to, from the table's repeat keys:
    /// an account, an org and a project, a Slack table and workspace, a
    /// model, a server table. Empty when the area's keys do not repeat.
    pub group: Vec<String>,
    /// The catalogue pattern the path fills, so the writer can locate the
    /// TOML item without re-parsing a display path: `accounts[].token`.
    pub pattern: String,
    pub kind: SettingKind,
    /// In the shape `kind` names: a JSON string, number, bool, array of
    /// strings, or object of string values. `null` for a key the file does
    /// not set.
    pub value: serde_json::Value,
    pub class: EffectClass,
    pub edit: SettingsEdit,
}

impl std::fmt::Debug for SettingsKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SettingsKey")
            .field("path", &self.path)
            .field("leaf", &self.leaf)
            .field("group", &self.group)
            .field("pattern", &self.pattern)
            .field("kind", &self.kind)
            .field("value", &"[redacted]")
            .field("class", &self.class)
            .field("edit", &self.edit)
            .finish()
    }
}

/// The header's own totals, built with the document so a client does not
/// count for itself.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct SettingsTotals {
    pub keys: usize,
    pub areas: usize,
}

/// The whole effective config, pushed on attach and after every applied
/// reload.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettingsDocument {
    /// The forge version that built it.
    pub version: String,
    /// The resolved `forge.toml` path.
    pub source: String,
    /// The fingerprint of the raw file text this document was built from.
    /// A save carries it, and a file that has moved since refuses the save.
    pub fingerprint: String,
    pub totals: SettingsTotals,
    pub areas: Vec<SettingsArea>,
}

impl SettingsDocument {
    /// A fresh total over the areas, so a builder cannot ship a count that
    /// disagrees with what it drew.
    pub fn with_totals(mut self) -> Self {
        self.totals = SettingsTotals {
            keys: self.areas.iter().map(|area| area.keys.len()).sum(),
            areas: self.areas.len(),
        };
        self
    }
}

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

    /// The frame is the page's read, not a diagnostic: a token that rides in
    /// it must not print through a debug log.
    #[test]
    fn a_keys_debug_never_prints_its_value() {
        let key = SettingsKey {
            path: "accounts.Primary.token".to_owned(),
            leaf: "token".to_owned(),
            group: vec!["Primary".to_owned()],
            pattern: "accounts[].token".to_owned(),
            kind: SettingKind::String,
            value: serde_json::json!("sk-a-real-token"),
            class: EffectClass::Live,
            edit: SettingsEdit {
                kind: EditKind::String,
                allowed: Vec::new(),
                required: true,
                group: Some("account".to_owned()),
            },
        };
        let shown = format!("{key:?}");
        assert!(!shown.contains("sk-a-real-token"), "the value printed: {shown}");
        assert!(shown.contains("accounts.Primary.token"), "the path stayed legible: {shown}");
    }
}