boxmaker/docs/plans/M3a/04-brokerd-config.md

M3a task 04: brokerd's configuration

Branch: m3a (run git switch m3a; git status --short must be empty, otherwise stop) Commit subject: Add brokerd's configuration

Goal

brokerd.toml into a typed Config. This is a format we define: unknown keys are errors, in every table. It works like crates/loopd/src/config.rs; read that file first and follow its style.

# brokerd.toml — every key is optional
[paths]
home = "/var/lib/boxmaker"            # default: $BOXMAKER_HOME, then /var/lib/boxmaker
grants = "/etc/boxmaker/grants"

[sockets]
broker = "/var/lib/boxmaker/run/loop-broker/broker.sock"     # default: under home
admin = "/var/lib/boxmaker/run/owner-broker/admin.sock"      # default: under home

[approvals]
ttl_ms = 900000                       # 15 min

Files

• Copy: crates/brokerd/tests/config.rs, and the six files in crates/brokerd/tests/fixtures/config/
• Create: crates/brokerd/src/config.rs
• Modify: crates/brokerd/src/lib.rs (add pub mod config;), crates/brokerd/Cargo.toml, docs/dependencies.md, docs/implementer-log.md

brokerd gains three dependencies, all already in [workspace.dependencies]. Add to crates/brokerd/Cargo.toml under [dependencies]:

serde.workspace = true
serde_json.workspace = true
toml.workspace = true

In docs/dependencies.md, add brokerd to the "Used by" cell of the serde row and of the serde_json row (for example `proto`, `brokerd`). The toml row already names brokerd. Change nothing else in that file.

Interfaces

#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields, default)]
pub struct Paths { pub home: PathBuf, pub grants: PathBuf }

/// An empty path means "the default under `home`".
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Default)]
#[serde(deny_unknown_fields, default)]
pub struct Sockets { pub broker: PathBuf, pub admin: PathBuf }

#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields, default)]
pub struct Approvals { pub ttl_ms: u64 }

#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Default)]
#[serde(deny_unknown_fields)]
pub struct Config {
    #[serde(default)] pub paths: Paths,
    #[serde(default)] pub sockets: Sockets,
    #[serde(default)] pub approvals: Approvals,
}

#[derive(Debug)]
pub enum ConfigError { Read(PathBuf, std::io::Error), Parse(PathBuf, toml::de::Error) }

impl Config {
    pub fn parse(text: &str) -> Result<Config, toml::de::Error>;
    pub fn load(path: &Path) -> Result<Config, ConfigError>;
    pub fn broker_socket(&self) -> PathBuf;
    pub fn admin_socket(&self) -> PathBuf;
    pub fn audit_dir(&self) -> PathBuf;
    pub fn state_dir(&self) -> PathBuf;
}

Rules

1. impl Default for Paths: home is $BOXMAKER_HOME if the variable is set, otherwise /var/lib/boxmaker; grants is /etc/boxmaker/grants. Copy how loopd's Paths reads the variable (std::env::var_os). impl Default for Approvals: ttl_ms is 900_000.
2. deny_unknown_fields goes on all four structs: Paths, Sockets, Approvals and Config. The test checks an unknown key in each table and at the top level.
3. broker_socket(): if sockets.broker is empty, home joined with run/loop-broker/broker.sock; otherwise sockets.broker. admin_socket(): the same with run/owner-broker/admin.sock. Test for empty with as_os_str().is_empty(), as loopd's channel_socket does.
4. audit_dir() is home joined with audit. state_dir() is home joined with broker/sessions. Neither can be set on its own.
5. load: a file that cannot be read is ConfigError::Read(path, err), including a missing file; a file that does not parse is ConfigError::Parse(path, err). ConfigError implements Display (the path, : , the inner error) and std::error::Error, by hand.
6. Do not set or change environment variables anywhere, tests included.

Steps

• 1. Copy. git switch m3a, then mkdir -p crates/brokerd/tests/fixtures && cp docs/plans/M3a/files/crates/brokerd/tests/config.rs crates/brokerd/tests/ && cp -r docs/plans/M3a/files/crates/brokerd/tests/fixtures/config crates/brokerd/tests/fixtures/
• 2. See the test fail. cargo test -p brokerd --test config. Expected: it does not compile.
• 3. Add the dependencies, write config.rs, add pub mod config;. Run cargo build once so Cargo.lock is updated, then cargo fmt --all.
• 4. See the tests pass. cargo test -p brokerd --test config. Expected: 7 passed.
• 5. Run the gate. make gate. Expected last line: gate: ok.
• 6. Log and commit. git add crates/brokerd Cargo.lock docs/dependencies.md docs/implementer-log.md && git commit

Done when

• cargo test -p brokerd --test config reports 7 passed; make gate prints gate: ok.

Stop and report if

• [workspace.dependencies] in the root Cargo.toml lacks serde, serde_json or toml.
• A test seems to need an environment variable to be set.