From bf7b1d0e45188bf8397cae5979da3af588b8abc1 Mon Sep 17 00:00:00 2001 From: theBlanketBaron Date: Sun, 15 Nov 2026 18:20:08 -0500 Subject: [PATCH 1/2] RAL-196: serve's wiring in its own file, so src/main.rs is the client's src/main.rs held every command, serve among them, so the brief's builds read "can't tell" for each story that touched it. Serve's flags, their checks and the service's start move to src/serve.rs, and how --db and --head-file name the ledger moves to the store, with no change to what rally serve accepts or does. main only passes the command on, and a test keeps it so. src/serve.rs is placed with the service's files and src/main.rs with the client's. Co-Authored-By: Claude Fable 5.2 --- docs/brief.md | 9 +- docs/roadmap.md | 6 + src/builds.rs | 48 +++++-- src/lib.rs | 1 + src/main.rs | 345 +----------------------------------------------- src/serve.rs | 339 +++++++++++++++++++++++++++++++++++++++++++++++ src/store.rs | 22 +++ 7 files changed, 413 insertions(+), 357 deletions(-) create mode 100644 src/serve.rs diff --git a/docs/brief.md b/docs/brief.md index 65a0e48..8a29f87 100644 --- a/docs/brief.md +++ b/docs/brief.md @@ -48,10 +48,11 @@ rally's projects, with every list bounded and every note cut short (well under 2 - `service`: a file the service runs changed (`builds::SERVICE_MODULES`, or `Cargo.toml`, `Cargo.lock`, `build.rs`), listed in `service_files`. Only these are counted: "2 stories merged, not live on the service; the oldest for 6 h", and `count` and `oldest_age_ms` are theirs. - - `can't tell`: only files the service shares changed, listed in `shared_files`: `src/main.rs` (every - command, `serve` among them), `src/web.rs` (the viewer, and the roadmap parser the service uses) and - `src/lib.rs` unless its patch only names modules the service doesn't run; or a commit's files couldn't be - read. Read the diff. It's never counted as live. + - `can't tell`: only files the service shares changed, listed in `shared_files`: `src/web.rs` (the viewer, + and the roadmap parser the service uses) and `src/lib.rs` unless its patch only names modules the service + doesn't run; or a commit's files couldn't be read. Read the diff. It's never counted as live. + `src/main.rs` was one of these until RAL-196 moved `serve`'s flags and startup to `src/serve.rs`, which is + the service's: `main` now only passes that command on, and a test keeps it so. - `cli or viewer`: only code the CLI or the viewer runs changed. It's live wherever those are on a build that has it: `cli_build` says this CLI's commit, how far behind main it is and which stories it `lacks`, and `viewer_build` the build of the viewer `rally view` started on this machine, from its run file. diff --git a/docs/roadmap.md b/docs/roadmap.md index 97ba14c..3d5417c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1530,3 +1530,9 @@ principles named were durable, accurate and reactive. Found in rally 0x7 by plus told and is never called live; the rest say they change only the CLI, the viewer, docs or tests, and the section says which build this CLI and the viewer here are on; a test keeps every file in `src/` placed as the service's, shared or the client's; with tests of each reading (docs/brief.md). +- [ ] **RAL-196: Serve's wiring in its own file.** Follow-up to RAL-195, agreed with the watchman (2026-11-15): + `src/main.rs` held every command, `serve` among them, so the brief's builds read "can't tell" for each story + that touched it (three of the eight on 2026-11-15). Done when: `serve`'s flags, their checks and the service's + start are in `src/serve.rs`, and how the ledger is named by `--db` and `--head-file` is in the store, with no + change to what `rally serve` accepts or does; `src/main.rs` is placed with the client's files, and + `src/serve.rs` with the service's; with a test that `main` only passes `serve` on (docs/brief.md). diff --git a/src/builds.rs b/src/builds.rs index 238d2ca..deed3ab 100644 --- a/src/builds.rs +++ b/src/builds.rs @@ -90,17 +90,20 @@ pub const SERVICE_MODULES: &[&str] = &[ "next", "record", "secrets", + "serve", "server", "store", "views", "watchman_brief", ]; -/// The files every part shares: `main` holds each command, `serve` among them; `lib` names each -/// module; `web` is the viewer and also the roadmap parser the service's evidence checks use. -pub const SHARED_MODULES: &[&str] = &["lib", "main", "web"]; +/// The files every part shares: `lib` names each module; `web` is the viewer and also the roadmap +/// parser the service's evidence checks use. +pub const SHARED_MODULES: &[&str] = &["lib", "web"]; -/// The modules only the CLI or the viewer runs. +/// The modules only the CLI or the viewer runs. `main` is among them since RAL-196: it holds +/// every command but the service's, which it passes on whole to `serve` +/// (`tests::main_only_passes_serve_on` keeps it so). pub const CLIENT_MODULES: &[&str] = &[ "backup", "builds", @@ -113,6 +116,7 @@ pub const CLIENT_MODULES: &[&str] = &[ "init", "levi", "lock_holder", + "main", "merge_notes", "rebased", "resume", @@ -675,7 +679,7 @@ pub fn section(read: Read) -> Value { (a pull request's merge lists all it changed) go to the stories it names \ or brought, or to `unnamed` when it names none; a file the service runs \ (builds::SERVICE_MODULES, Cargo.toml, Cargo.lock, build.rs) waits on the \ - service; src/main.rs, src/web.rs and most of src/lib.rs are shared, so \ + service; src/web.rs and most of src/lib.rs are shared, so \ the path can't tell", }); } @@ -849,7 +853,7 @@ mod tests { ]}); let mut read = files(&[ ("a", &["docs/watchman.md", "src/session.rs"]), - ("b", &["src/main.rs", "src/session.rs"]), + ("b", &["src/web.rs", "src/session.rs"]), ( "d", &[ @@ -859,7 +863,7 @@ mod tests { ], ), ("e", &["web/app.js", "web/app.css"]), - ("f", &["src/server.rs", "src/main.rs"]), + ("f", &["src/server.rs", "src/web.rs"]), ]); // A patch to lib.rs that only names a module the service doesn't run changes nothing // the service runs. @@ -925,7 +929,7 @@ mod tests { assert_eq!( merged["summary"], "1 story merged, not live on the service; the oldest for 6 h; 1 story can't be told \ - from the paths (shared with the service: src/main.rs): read the diff; 4 stories \ + from the paths (shared with the service: src/web.rs): read the diff; 4 stories \ change only the CLI, the viewer, docs or tests: live wherever those builds have \ them (see cli_build and viewer_build)" ); @@ -1018,7 +1022,7 @@ mod tests { ("a", &["docs/watchman.md"]), ("b", &["src/server.rs", "tests/service.rs"]), ("c", &["docs/brief.md"]), - ("d", &["src/main.rs"]), + ("d", &["src/web.rs"]), ]))); let merged = &out["merged_not_live"]; assert_eq!(merged["stories"][0]["waits_on"], "nothing running"); @@ -1030,7 +1034,7 @@ mod tests { "unread": null}, {"commit": "ddddddd", "message": "a flag for every command", "age_ms": 8 * 3_600_000, "waits_on": "can't tell", "service_files": [], - "shared_files": ["src/main.rs"], "unread": null}, + "shared_files": ["src/web.rs"], "unread": null}, ]) ); assert_eq!( @@ -1040,7 +1044,7 @@ mod tests { assert_eq!(merged["oldest_age_ms"], 10 * 3_600_000); assert_eq!( merged["summary"], - "1 commit naming no story merged, not live on the service; the oldest for 10 h; 1 commit naming no story can't be told from the paths (shared with the service: src/main.rs): read the diff; 1 story changes only the CLI, the viewer, docs or tests: live wherever those builds have it (see cli_build and viewer_build)" + "1 commit naming no story merged, not live on the service; the oldest for 10 h; 1 commit naming no story can't be told from the paths (shared with the service: src/web.rs): read the diff; 1 story changes only the CLI, the viewer, docs or tests: live wherever those builds have it (see cli_build and viewer_build)" ); assert!(out["hint"].is_string(), "a commit waits on the service"); @@ -1174,7 +1178,8 @@ mod tests { assert_eq!(part_of("src/server.rs"), Part::Service); assert_eq!(part_of("src/views.rs"), Part::Service); assert_eq!(part_of("Cargo.lock"), Part::Service); - assert_eq!(part_of("src/main.rs"), Part::Shared); + assert_eq!(part_of("src/main.rs"), Part::Client); + assert_eq!(part_of("src/serve.rs"), Part::Service); assert_eq!(part_of("src/web.rs"), Part::Shared); assert_eq!(part_of("src/a_module_added_since.rs"), Part::Shared); assert_eq!(part_of("src/session.rs"), Part::Client); @@ -1202,6 +1207,25 @@ mod tests { ); } + /// RAL-196: `main` is the client's because all it does for the service is pass `serve` on. + /// If serve's wiring comes back into it, a change to it could be the service's again. + #[test] + fn main_only_passes_serve_on() { + let main = include_str!("main.rs"); + assert!( + main.contains("Command::Serve(args) => return rally::serve::run(location, args),"), + "main passes `serve` on whole" + ); + assert!(main.contains(" Serve(rally::serve::Args),")); + for services in ["server::", "RateLimit", "evidence::Settings"] { + assert!( + !main.contains(services), + "src/main.rs names {services}, which is the service's: keep it in src/serve.rs, \ + or move `main` back to builds::SHARED_MODULES" + ); + } + } + /// Every file in `src/` is placed in one list, so a new module makes its author say whether /// the service runs it; and the service's list holds what `server` and `store` name. #[test] diff --git a/src/lib.rs b/src/lib.rs index 766dd55..42f43f2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -53,6 +53,7 @@ pub mod roadmaps; pub mod scratch_pg; pub mod script; pub mod secrets; +pub mod serve; pub mod server; pub mod session; pub mod shims; diff --git a/src/main.rs b/src/main.rs index 148ac2c..61e7ef9 100644 --- a/src/main.rs +++ b/src/main.rs @@ -16,7 +16,7 @@ use rally::access::{Pairing, StateDir, write_private}; use rally::client; use rally::ledger::{State, TeamStatus}; use rally::record::{Kind, Record, Source}; -use rally::server::{self, RateLimit}; +use rally::serve::{parse_window, read_github_token}; use rally::store::{Head, Location, Store}; use rally::view; use rally::views::{self, Page}; @@ -128,93 +128,7 @@ enum InboxAction { #[derive(Subcommand)] enum Command { /// Run the service on this machine. Needs --db and --head-file. Prints where it's listening. - Serve { - /// The address to listen on, such as a LAN address and port. Never the open internet. - #[arg(long)] - bind: String, - #[arg(long, env = "RALLY_STATE_DIR")] - state_dir: PathBuf, - /// Requests a credential can make at once. - #[arg(long, default_value_t = RateLimit::default().burst)] - burst: f64, - /// Requests a credential regains per second. - #[arg(long, default_value_t = RateLimit::default().per_second)] - per_second: f64, - /// Writes a credential can make at once. - #[arg(long, default_value_t = RateLimit::default().write_burst)] - write_burst: f64, - /// Writes a credential regains per second. - #[arg(long, default_value_t = RateLimit::default().write_per_second)] - write_per_second: f64, - /// Refuse writes once the ledger's table in Postgres, with its indexes, reaches this size. - #[arg(long, default_value_t = RateLimit::default().max_ledger_bytes)] - max_ledger_bytes: u64, - /// Refuse writes while the disk under Postgres's data has less free space than this. - #[arg(long, default_value_t = RateLimit::default().min_free_bytes)] - min_free_bytes: u64, - /// Connections open at once, from anyone. - #[arg(long, default_value_t = RateLimit::default().max_connections)] - max_connections: usize, - /// Connections open at once from any one address. - #[arg(long, default_value_t = RateLimit::default().max_connections_per_address)] - max_connections_per_address: usize, - /// How long a connection may last, authenticated or not. - #[arg(long, default_value_t = RateLimit::default().connection_seconds)] - connection_seconds: f64, - /// Missing or wrong tokens one address can present at once. - #[arg(long, default_value_t = RateLimit::default().failed_token_burst)] - failed_token_burst: f64, - /// Failed token attempts an address regains per second. - #[arg(long, default_value_t = RateLimit::default().failed_token_per_second)] - failed_token_per_second: f64, - /// Checks and past-state reads a credential can make at once. - #[arg(long, default_value_t = RateLimit::default().heavy_burst)] - heavy_burst: f64, - /// Checks and past-state reads a credential regains per second. - #[arg(long, default_value_t = RateLimit::default().heavy_per_second)] - heavy_per_second: f64, - /// Refuse to start unless this binary and the operator key, and every directory above - /// each, are owned by root and writable by no one else, so that no agent on this host can - /// change either. It prints the operator's sudo steps if not. Needed to accept watchman - /// designations (RAL-51). See docs/designation.md. - #[arg(long, requires = "operator_key")] - secure: bool, - /// With --secure: the operator's OpenSSH public key, which designations must be signed by. - #[arg(long, requires = "secure")] - operator_key: Option, - /// How long a team waits for the operator's answer before it can shelve the story and - /// take its next one (RAL-56): a number with s, m, h or d. The operator agreed 5 minutes. - #[arg(long, env = "RALLY_OPERATOR_WINDOW", default_value = "5m", value_parser = parse_window)] - operator_window: u64, - /// How many shelves in a row, across the rally, with no answer from the operator between - /// them, mean the operator is away (RAL-56). The operator agreed 3. - #[arg(long, env = "RALLY_OPERATOR_AWAY_AFTER", default_value_t = 3, - value_parser = clap::value_parser!(u64).range(1..))] - operator_away_after: u64, - /// How long the operator is treated as away (RAL-56): no story waiting on the operator is - /// offered, and then each is asked again. The operator agreed 1 hour. - #[arg(long, env = "RALLY_OPERATOR_AWAY", default_value = "1h", value_parser = parse_window)] - operator_away: u64, - /// A read-only GitHub token, for checking submitted evidence (RAL-5, RAL-18). Without it, - /// each check is recorded as not checked. With --secure, it must be root-owned too. - #[arg(long, env = "RALLY_GITHUB_TOKEN_FILE")] - github_token_file: Option, - /// The GitHub owners, comma-separated, whose repositories the token may read open pull - /// requests' roadmaps in for `new-story` (RAL-68). Requests can't widen it. - #[arg(long, env = "RALLY_GITHUB_OWNERS", default_value = rally::evidence::DEFAULT_OWNERS)] - github_owners: String, - /// The credentials, comma-separated, that may open or close a rally (RAL-77), besides - /// one a designated watchman is bound to. Unset, any paired credential may, and each - /// answer says so. See docs/service.md. - #[arg(long, env = "RALLY_RALLY_OPENERS")] - rally_openers: Option, - /// The longest a submission's CI is waited for before its check is recorded as pending. - #[arg(long, default_value = "30m", value_parser = parse_window)] - evidence_ci_wait: u64, - /// How often a submission whose CI is still running is checked again. - #[arg(long, default_value = "1m", value_parser = parse_window)] - evidence_poll: u64, - }, + Serve(rally::serve::Args), /// Run the read-only viewer on this machine's loopback address. See docs/web.md. Web { #[arg(long, default_value = "127.0.0.1:7300")] @@ -1200,25 +1114,6 @@ enum Command { }, } -/// A window such as `90m` or `4h`, in milliseconds (RAL-56). -fn parse_window(text: &str) -> Result { - let bad = || format!("{text:?} isn't a window: give a number with s, m, h or d, such as 4h"); - let split = text.len().checked_sub(1).ok_or_else(bad)?; - let (number, unit) = text.split_at(split); - let number: u64 = number.parse().map_err(|_| bad())?; - let unit_ms: u64 = match unit { - "s" => 1_000, - "m" => 60_000, - "h" => 3_600_000, - "d" => 86_400_000, - _ => return Err(bad()), - }; - match number.checked_mul(unit_ms) { - Some(ms) if ms > 0 => Ok(ms), - _ => Err(bad()), - } -} - fn parse_state(text: &str) -> Result { serde_json::from_value(json!(text)).map_err(|_| { format!("{text:?} isn't a state: ready, claimed, in_review, verified or sent_back") @@ -1462,17 +1357,6 @@ fn wait_green( Ok((ended.code(), out)) } -/// The one GitHub token in the file at `path`. -fn read_github_token(path: &Path) -> Result { - let token = - std::fs::read_to_string(path).map_err(|e| format!("can't read {}: {e}", path.display()))?; - let token = token.trim().to_owned(); - if token.is_empty() || token.chars().any(|c| c.is_whitespace() || c.is_control()) { - return Err(format!("{} doesn't hold one token", path.display())); - } - Ok(token) -} - /// `rally check-github-token`: whether the token can merge, by trying to on a head that can't /// match (RAL-18). Succeeds only when the merge is refused for want of access. fn check_github_token(path: &Path, repo: &str, pull: u64) -> Result { @@ -3609,26 +3493,6 @@ fn create_new_private(path: &Path) -> Result<(), Box> { Ok(()) } -/// The ledger named by --db and --head-file, if any. -fn location( - db: Option, - head_file: Option, - password_file: Option, -) -> Result, Box> { - match (db, head_file) { - (Some(url), Some(head_file)) => Ok(Some(Location { - url, - head_file, - password_file, - })), - (Some(_), None) => Err("--db needs --head-file or RALLY_HEAD_FILE".into()), - (None, _) if password_file.is_some() => { - Err("--db-password-file is only for --db, on the host".into()) - } - (None, _) => Ok(None), - } -} - fn config_path(config: Option) -> Result> { match config { Some(path) => Ok(path), @@ -4164,71 +4028,6 @@ fn run_viewer( Ok(json!({"stopped": true}).to_string()) } -fn run_service( - location: &Location, - bind: &str, - state_dir: &Path, - limit: RateLimit, - rules: server::Rules, - evidence: rally::evidence::Settings, -) -> Result> { - let state = StateDir::open(state_dir)?; - // A listed credential that isn't paired can't open anything; say so, rather than refuse to - // start over a pairing revoked since. - for opener in rules.rally_openers.iter().flatten() { - if !matches!(state.paired(opener), Ok(Some(_))) { - eprintln!("rally: --rally-openers names {opener}, which isn't paired"); - } - } - let evidence_checked = evidence.token.is_some(); - let (_, _, fingerprint) = state.certificate()?; - let listener = TcpListener::bind(bind)?; - let listening = json!({"listening": listener.local_addr()?.to_string(), "fingerprint": fingerprint, - // The code that's running (RAL-156): what's live is a read, not a guess. - "commit": rally::commit(), - "operator_key": rules.operator_key.as_ref().map(rally::designation::OperatorKey::fingerprint), - "operator_window_ms": rules.operator_times.map(|times| times.window_ms), - "operator_away_after": rules.operator_times.map(|times| times.away_after), - "operator_away_ms": rules.operator_times.map(|times| times.away_ms), - "evidence_checked_with_token": evidence_checked, - "rally_openers": rules.rally_openers.as_ref().map_or_else( - || json!("any paired credential: set --rally-openers"), - |openers| json!(openers), - )}); - println!("{listening}"); - std::io::Write::flush(&mut std::io::stdout())?; - tokio::runtime::Runtime::new()?.block_on(server::serve( - listener, - location, - state, - limit, - rules, - Some(evidence), - ))?; - Ok(json!({"stopped": true}).to_string()) -} - -/// `--rally-openers` (RAL-77): unset is `None`, anyone; otherwise at least one credential name. -fn parse_rally_openers(text: Option<&str>) -> Result>, String> { - let Some(text) = text else { - return Ok(None); - }; - let openers: Vec = text - .split(',') - .map(str::trim) - .filter(|name| !name.is_empty()) - .map(str::to_owned) - .collect(); - if openers.is_empty() { - return Err( - "--rally-openers names no credential; leave it unset to let any \ - paired credential open a rally" - .into(), - ); - } - Ok(Some(openers)) -} - /// `rally init`: no ledger, service or credential involved. fn init( files: &[PathBuf], @@ -4266,149 +4065,13 @@ fn run(cli: Cli) -> Result> { Command::AddMachine { .. } | Command::Revoke { .. } | Command::Pair ); let password_file = cli.db_password_file.filter(|_| uses_database); - let location = location(cli.db, cli.head_file, password_file)?; + let location = Location::named(cli.db, cli.head_file, password_file)?; let ci_wait = match &cli.command { Command::Merge { ci_wait, .. } => Duration::from_secs(*ci_wait), _ => Duration::ZERO, }; let (kind, body) = match cli.command { - Command::Serve { - bind, - state_dir, - burst, - per_second, - write_burst, - write_per_second, - max_ledger_bytes, - min_free_bytes, - max_connections, - max_connections_per_address, - connection_seconds, - failed_token_burst, - failed_token_per_second, - heavy_burst, - heavy_per_second, - secure, - operator_key, - operator_window, - operator_away_after, - operator_away, - github_token_file, - github_owners, - rally_openers, - evidence_ci_wait, - evidence_poll, - } => { - let location = location.ok_or("serve needs --db and --head-file")?; - let token = match &github_token_file { - Some(path) => { - if secure { - rally::designation::check_owned(path, 0, None) - .map_err(|why| format!("--secure refused the GitHub token: {why}"))?; - } - Some(read_github_token(path)?) - } - None => None, - }; - let evidence = rally::evidence::Settings { - token, - owners: github_owners - .split(',') - .map(|owner| owner.trim().to_owned()) - .filter(|owner| !owner.is_empty()) - .collect(), - timing: rally::evidence::Timing { - ceiling_ms: evidence_ci_wait, - poll_ms: evidence_poll, - }, - test_base: match rally::evidence::test_base(secure) { - Ok(Some(base)) => { - eprintln!( - "rally serve: evidence checks use a stand-in GitHub at {base}, for tests ({})", - rally::evidence::TEST_BASE_VAR - ); - Some(base) - } - Ok(None) => None, - Err(why) => { - eprintln!("rally serve: {why}"); - None - } - }, - }; - let operator_key = if secure { - let key_path = operator_key.ok_or("--secure needs --operator-key")?; - let exe = std::env::current_exe()?; - for path in [&exe, &key_path] { - rally::designation::check_owned(path, 0, None).map_err(|why| { - format!( - "--secure refused: {why}.\n{}", - rally::designation::secure_steps(&exe, &key_path) - ) - })?; - } - Some(rally::designation::OperatorKey::read(&key_path)?) - } else { - None - }; - if !(connection_seconds > 0.0 && connection_seconds.is_finite()) { - return Err("--connection-seconds must be a positive number".into()); - } - // A burst below 1 would refuse everything, which is never what was meant. - for (name, burst, per_second) in [ - ("burst", burst, per_second), - ("write-burst", write_burst, write_per_second), - ( - "failed-token-burst", - failed_token_burst, - failed_token_per_second, - ), - ("heavy-burst", heavy_burst, heavy_per_second), - ] { - if !(burst >= 1.0 && burst.is_finite()) { - return Err(format!("--{name} must be at least 1").into()); - } - if !(per_second >= 0.0 && per_second.is_finite()) { - return Err( - format!("the rate that goes with --{name} can't be negative").into(), - ); - } - } - if max_connections == 0 || max_connections_per_address == 0 { - return Err("connection limits must be at least 1".into()); - } - let limit = RateLimit { - burst, - per_second, - write_burst, - write_per_second, - max_ledger_bytes, - min_free_bytes, - max_connections, - max_connections_per_address, - connection_seconds, - failed_token_burst, - failed_token_per_second, - heavy_burst, - heavy_per_second, - }; - return run_service( - &location, - &bind, - &state_dir, - limit, - server::Rules { - operator_key, - operator_times: Some(rally::store::OperatorTimes { - window_ms: operator_window, - away_after: usize::try_from(operator_away_after).unwrap_or(usize::MAX), - away_ms: operator_away, - }), - rally_openers: parse_rally_openers(rally_openers.as_deref())?, - }, - evidence, - ); - } + Command::Serve(args) => return rally::serve::run(location, args), Command::AddMachine { name, address, diff --git a/src/serve.rs b/src/serve.rs new file mode 100644 index 0000000..0e0f7b3 --- /dev/null +++ b/src/serve.rs @@ -0,0 +1,339 @@ +//! `rally serve`: the service's command, apart from every other command (RAL-196). +//! +//! `src/main.rs` holds each of the CLI's commands. While it held this one too, a change to it +//! couldn't be told from its path to leave the service alone, so the watchman's brief read +//! "can't tell" for every story that touched it (RAL-195). What the service runs at startup is +//! here: its flags, their checks, and the start of [`crate::server::serve`]. `main` only passes +//! the command on. + +use std::net::TcpListener; +use std::path::{Path, PathBuf}; + +use serde_json::json; + +use crate::access::StateDir; +use crate::server::{self, RateLimit}; +use crate::store::Location; + +/// The flags of `rally serve`. +#[derive(clap::Args)] +pub struct Args { + /// The address to listen on, such as a LAN address and port. Never the open internet. + #[arg(long)] + pub bind: String, + #[arg(long, env = "RALLY_STATE_DIR")] + pub state_dir: PathBuf, + /// Requests a credential can make at once. + #[arg(long, default_value_t = RateLimit::default().burst)] + pub burst: f64, + /// Requests a credential regains per second. + #[arg(long, default_value_t = RateLimit::default().per_second)] + pub per_second: f64, + /// Writes a credential can make at once. + #[arg(long, default_value_t = RateLimit::default().write_burst)] + pub write_burst: f64, + /// Writes a credential regains per second. + #[arg(long, default_value_t = RateLimit::default().write_per_second)] + pub write_per_second: f64, + /// Refuse writes once the ledger's table in Postgres, with its indexes, reaches this size. + #[arg(long, default_value_t = RateLimit::default().max_ledger_bytes)] + pub max_ledger_bytes: u64, + /// Refuse writes while the disk under Postgres's data has less free space than this. + #[arg(long, default_value_t = RateLimit::default().min_free_bytes)] + pub min_free_bytes: u64, + /// Connections open at once, from anyone. + #[arg(long, default_value_t = RateLimit::default().max_connections)] + pub max_connections: usize, + /// Connections open at once from any one address. + #[arg(long, default_value_t = RateLimit::default().max_connections_per_address)] + pub max_connections_per_address: usize, + /// How long a connection may last, authenticated or not. + #[arg(long, default_value_t = RateLimit::default().connection_seconds)] + pub connection_seconds: f64, + /// Missing or wrong tokens one address can present at once. + #[arg(long, default_value_t = RateLimit::default().failed_token_burst)] + pub failed_token_burst: f64, + /// Failed token attempts an address regains per second. + #[arg(long, default_value_t = RateLimit::default().failed_token_per_second)] + pub failed_token_per_second: f64, + /// Checks and past-state reads a credential can make at once. + #[arg(long, default_value_t = RateLimit::default().heavy_burst)] + pub heavy_burst: f64, + /// Checks and past-state reads a credential regains per second. + #[arg(long, default_value_t = RateLimit::default().heavy_per_second)] + pub heavy_per_second: f64, + /// Refuse to start unless this binary and the operator key, and every directory above + /// each, are owned by root and writable by no one else, so that no agent on this host can + /// change either. It prints the operator's sudo steps if not. Needed to accept watchman + /// designations (RAL-51). See docs/designation.md. + #[arg(long, requires = "operator_key")] + pub secure: bool, + /// With --secure: the operator's OpenSSH public key, which designations must be signed by. + #[arg(long, requires = "secure")] + pub operator_key: Option, + /// How long a team waits for the operator's answer before it can shelve the story and + /// take its next one (RAL-56): a number with s, m, h or d. The operator agreed 5 minutes. + #[arg(long, env = "RALLY_OPERATOR_WINDOW", default_value = "5m", value_parser = parse_window)] + pub operator_window: u64, + /// How many shelves in a row, across the rally, with no answer from the operator between + /// them, mean the operator is away (RAL-56). The operator agreed 3. + #[arg(long, env = "RALLY_OPERATOR_AWAY_AFTER", default_value_t = 3, + value_parser = clap::value_parser!(u64).range(1..))] + pub operator_away_after: u64, + /// How long the operator is treated as away (RAL-56): no story waiting on the operator is + /// offered, and then each is asked again. The operator agreed 1 hour. + #[arg(long, env = "RALLY_OPERATOR_AWAY", default_value = "1h", value_parser = parse_window)] + pub operator_away: u64, + /// A read-only GitHub token, for checking submitted evidence (RAL-5, RAL-18). Without it, + /// each check is recorded as not checked. With --secure, it must be root-owned too. + #[arg(long, env = "RALLY_GITHUB_TOKEN_FILE")] + pub github_token_file: Option, + /// The GitHub owners, comma-separated, whose repositories the token may read open pull + /// requests' roadmaps in for `new-story` (RAL-68). Requests can't widen it. + #[arg(long, env = "RALLY_GITHUB_OWNERS", default_value = crate::evidence::DEFAULT_OWNERS)] + pub github_owners: String, + /// The credentials, comma-separated, that may open or close a rally (RAL-77), besides + /// one a designated watchman is bound to. Unset, any paired credential may, and each + /// answer says so. See docs/service.md. + #[arg(long, env = "RALLY_RALLY_OPENERS")] + pub rally_openers: Option, + /// The longest a submission's CI is waited for before its check is recorded as pending. + #[arg(long, default_value = "30m", value_parser = parse_window)] + pub evidence_ci_wait: u64, + /// How often a submission whose CI is still running is checked again. + #[arg(long, default_value = "1m", value_parser = parse_window)] + pub evidence_poll: u64, +} + +/// Runs the service until it stops. `location` is the ledger's, from `--db` and `--head-file`. +pub fn run(location: Option, args: Args) -> Result> { + let Args { + bind, + state_dir, + burst, + per_second, + write_burst, + write_per_second, + max_ledger_bytes, + min_free_bytes, + max_connections, + max_connections_per_address, + connection_seconds, + failed_token_burst, + failed_token_per_second, + heavy_burst, + heavy_per_second, + secure, + operator_key, + operator_window, + operator_away_after, + operator_away, + github_token_file, + github_owners, + rally_openers, + evidence_ci_wait, + evidence_poll, + } = args; + let location = location.ok_or("serve needs --db and --head-file")?; + let token = match &github_token_file { + Some(path) => { + if secure { + crate::designation::check_owned(path, 0, None) + .map_err(|why| format!("--secure refused the GitHub token: {why}"))?; + } + Some(read_github_token(path)?) + } + None => None, + }; + let evidence = crate::evidence::Settings { + token, + owners: github_owners + .split(',') + .map(|owner| owner.trim().to_owned()) + .filter(|owner| !owner.is_empty()) + .collect(), + timing: crate::evidence::Timing { + ceiling_ms: evidence_ci_wait, + poll_ms: evidence_poll, + }, + test_base: match crate::evidence::test_base(secure) { + Ok(Some(base)) => { + eprintln!( + "rally serve: evidence checks use a stand-in GitHub at {base}, for tests ({})", + crate::evidence::TEST_BASE_VAR + ); + Some(base) + } + Ok(None) => None, + Err(why) => { + eprintln!("rally serve: {why}"); + None + } + }, + }; + let operator_key = if secure { + let key_path = operator_key.ok_or("--secure needs --operator-key")?; + let exe = std::env::current_exe()?; + for path in [&exe, &key_path] { + crate::designation::check_owned(path, 0, None).map_err(|why| { + format!( + "--secure refused: {why}.\n{}", + crate::designation::secure_steps(&exe, &key_path) + ) + })?; + } + Some(crate::designation::OperatorKey::read(&key_path)?) + } else { + None + }; + if !(connection_seconds > 0.0 && connection_seconds.is_finite()) { + return Err("--connection-seconds must be a positive number".into()); + } + // A burst below 1 would refuse everything, which is never what was meant. + for (name, burst, per_second) in [ + ("burst", burst, per_second), + ("write-burst", write_burst, write_per_second), + ( + "failed-token-burst", + failed_token_burst, + failed_token_per_second, + ), + ("heavy-burst", heavy_burst, heavy_per_second), + ] { + if !(burst >= 1.0 && burst.is_finite()) { + return Err(format!("--{name} must be at least 1").into()); + } + if !(per_second >= 0.0 && per_second.is_finite()) { + return Err(format!("the rate that goes with --{name} can't be negative").into()); + } + } + if max_connections == 0 || max_connections_per_address == 0 { + return Err("connection limits must be at least 1".into()); + } + let limit = RateLimit { + burst, + per_second, + write_burst, + write_per_second, + max_ledger_bytes, + min_free_bytes, + max_connections, + max_connections_per_address, + connection_seconds, + failed_token_burst, + failed_token_per_second, + heavy_burst, + heavy_per_second, + }; + run_service( + &location, + &bind, + &state_dir, + limit, + server::Rules { + operator_key, + operator_times: Some(crate::store::OperatorTimes { + window_ms: operator_window, + away_after: usize::try_from(operator_away_after).unwrap_or(usize::MAX), + away_ms: operator_away, + }), + rally_openers: parse_rally_openers(rally_openers.as_deref())?, + }, + evidence, + ) +} + +fn run_service( + location: &Location, + bind: &str, + state_dir: &Path, + limit: RateLimit, + rules: server::Rules, + evidence: crate::evidence::Settings, +) -> Result> { + let state = StateDir::open(state_dir)?; + // A listed credential that isn't paired can't open anything; say so, rather than refuse to + // start over a pairing revoked since. + for opener in rules.rally_openers.iter().flatten() { + if !matches!(state.paired(opener), Ok(Some(_))) { + eprintln!("rally: --rally-openers names {opener}, which isn't paired"); + } + } + let evidence_checked = evidence.token.is_some(); + let (_, _, fingerprint) = state.certificate()?; + let listener = TcpListener::bind(bind)?; + let listening = json!({"listening": listener.local_addr()?.to_string(), "fingerprint": fingerprint, + // The code that's running (RAL-156): what's live is a read, not a guess. + "commit": crate::commit(), + "operator_key": rules.operator_key.as_ref().map(crate::designation::OperatorKey::fingerprint), + "operator_window_ms": rules.operator_times.map(|times| times.window_ms), + "operator_away_after": rules.operator_times.map(|times| times.away_after), + "operator_away_ms": rules.operator_times.map(|times| times.away_ms), + "evidence_checked_with_token": evidence_checked, + "rally_openers": rules.rally_openers.as_ref().map_or_else( + || json!("any paired credential: set --rally-openers"), + |openers| json!(openers), + )}); + println!("{listening}"); + std::io::Write::flush(&mut std::io::stdout())?; + tokio::runtime::Runtime::new()?.block_on(server::serve( + listener, + location, + state, + limit, + rules, + Some(evidence), + ))?; + Ok(json!({"stopped": true}).to_string()) +} + +/// `--rally-openers` (RAL-77): unset is `None`, anyone; otherwise at least one credential name. +fn parse_rally_openers(text: Option<&str>) -> Result>, String> { + let Some(text) = text else { + return Ok(None); + }; + let openers: Vec = text + .split(',') + .map(str::trim) + .filter(|name| !name.is_empty()) + .map(str::to_owned) + .collect(); + if openers.is_empty() { + return Err( + "--rally-openers names no credential; leave it unset to let any \ + paired credential open a rally" + .into(), + ); + } + Ok(Some(openers)) +} + +/// The one GitHub token in the file at `path`. +pub fn read_github_token(path: &Path) -> Result { + let token = + std::fs::read_to_string(path).map_err(|e| format!("can't read {}: {e}", path.display()))?; + let token = token.trim().to_owned(); + if token.is_empty() || token.chars().any(|c| c.is_whitespace() || c.is_control()) { + return Err(format!("{} doesn't hold one token", path.display())); + } + Ok(token) +} + +/// A window such as `90m` or `4h`, in milliseconds (RAL-56). +pub fn parse_window(text: &str) -> Result { + let bad = || format!("{text:?} isn't a window: give a number with s, m, h or d, such as 4h"); + let split = text.len().checked_sub(1).ok_or_else(bad)?; + let (number, unit) = text.split_at(split); + let number: u64 = number.parse().map_err(|_| bad())?; + let unit_ms: u64 = match unit { + "s" => 1_000, + "m" => 60_000, + "h" => 3_600_000, + "d" => 86_400_000, + _ => return Err(bad()), + }; + match number.checked_mul(unit_ms) { + Some(ms) if ms > 0 => Ok(ms), + _ => Err(bad()), + } +} diff --git a/src/store.rs b/src/store.rs index 462776e..eb8ceca 100644 --- a/src/store.rs +++ b/src/store.rs @@ -135,6 +135,28 @@ pub struct Location { } impl Location { + /// The ledger `--db`, `--head-file` and `--db-password-file` name, if any: the service's, or + /// a host command's. Kept here, not with the CLI's commands, since it's how the service finds + /// its ledger (RAL-196). + pub fn named( + db: Option, + head_file: Option, + password_file: Option, + ) -> Result, String> { + match (db, head_file) { + (Some(url), Some(head_file)) => Ok(Some(Location { + url, + head_file, + password_file, + })), + (Some(_), None) => Err("--db needs --head-file or RALLY_HEAD_FILE".into()), + (None, _) if password_file.is_some() => { + Err("--db-password-file is only for --db, on the host".into()) + } + (None, _) => Ok(None), + } + } + /// The database's address without any password, for messages. pub fn redacted(&self) -> String { redact(&self.url) From 3b782a437448636ce1d3b691927ff834eb49c66f Mon Sep 17 00:00:00 2001 From: theBlanketBaron Date: Sun, 15 Nov 2026 18:25:04 -0500 Subject: [PATCH 2/2] RAL-196: the flags that name the ledger are declared in the store From the watchman's read: --db, --head-file and --db-password-file reach the service, so main.rs mustn't declare them and still read as the client's. They move to store::LedgerFlags, flattened into the CLI, and the test that main only passes serve on now also refuses those declarations in main.rs. rally --help and rally serve --help are unchanged. Co-Authored-By: Claude Fable 5.2 --- docs/brief.md | 3 ++- docs/roadmap.md | 3 ++- src/builds.rs | 15 ++++++++++++++- src/main.rs | 17 +++-------------- src/store.rs | 28 ++++++++++++++++++++++++++++ 5 files changed, 49 insertions(+), 17 deletions(-) diff --git a/docs/brief.md b/docs/brief.md index 8a29f87..d626a92 100644 --- a/docs/brief.md +++ b/docs/brief.md @@ -52,7 +52,8 @@ rally's projects, with every list bounded and every note cut short (well under 2 and the roadmap parser the service uses) and `src/lib.rs` unless its patch only names modules the service doesn't run; or a commit's files couldn't be read. Read the diff. It's never counted as live. `src/main.rs` was one of these until RAL-196 moved `serve`'s flags and startup to `src/serve.rs`, which is - the service's: `main` now only passes that command on, and a test keeps it so. + the service's, and the `--db`, `--head-file` and `--db-password-file` flags to the store: `main` now only + passes that command on and declares none of them, and a test keeps it so. - `cli or viewer`: only code the CLI or the viewer runs changed. It's live wherever those are on a build that has it: `cli_build` says this CLI's commit, how far behind main it is and which stories it `lacks`, and `viewer_build` the build of the viewer `rally view` started on this machine, from its run file. diff --git a/docs/roadmap.md b/docs/roadmap.md index dc78412..09a9e5d 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1542,6 +1542,7 @@ principles named were durable, accurate and reactive. Found in rally 0x7 by plus - [ ] **RAL-196: Serve's wiring in its own file.** Follow-up to RAL-195, agreed with the watchman (2026-11-15): `src/main.rs` held every command, `serve` among them, so the brief's builds read "can't tell" for each story that touched it (three of the eight on 2026-11-15). Done when: `serve`'s flags, their checks and the service's - start are in `src/serve.rs`, and how the ledger is named by `--db` and `--head-file` is in the store, with no + start are in `src/serve.rs`, and the `--db`, `--head-file` and `--db-password-file` flags are declared and read + in the store, with no change to what `rally serve` accepts or does; `src/main.rs` is placed with the client's files, and `src/serve.rs` with the service's; with a test that `main` only passes `serve` on (docs/brief.md). diff --git a/src/builds.rs b/src/builds.rs index deed3ab..a96c6b5 100644 --- a/src/builds.rs +++ b/src/builds.rs @@ -1217,7 +1217,20 @@ mod tests { "main passes `serve` on whole" ); assert!(main.contains(" Serve(rally::serve::Args),")); - for services in ["server::", "RateLimit", "evidence::Settings"] { + // The flags that name the ledger are the store's, flattened in: main declares none. + assert!(main.contains(" ledger: rally::store::LedgerFlags,")); + assert!(main.contains("cli.ledger.location(uses_database)?")); + for services in [ + "server::", + "RateLimit", + "evidence::Settings", + "RALLY_DB", + "RALLY_HEAD_FILE", + "cli.db", + "cli.head_file", + " head_file: ", + "Location {", + ] { assert!( !main.contains(services), "src/main.rs names {services}, which is the service's: keep it in src/serve.rs, \ diff --git a/src/main.rs b/src/main.rs index 61e7ef9..23993be 100644 --- a/src/main.rs +++ b/src/main.rs @@ -28,18 +28,8 @@ use rally::web::{ #[derive(Parser)] #[command(version = rally::version())] struct Cli { - /// Work directly on the ledger in this Postgres database, such as - /// postgres://rally@127.0.0.1/rally, rather than through the service. Needs --head-file. - #[arg(long, env = "RALLY_DB", hide_env_values = true)] - db: Option, - /// With --db: the ledger's head file, kept outside Postgres so that removing the newest - /// records shows. - #[arg(long, env = "RALLY_HEAD_FILE")] - head_file: Option, - /// With --db: a file holding the Postgres role's password, readable only by this account, so - /// the password stays out of the command line and the URL. - #[arg(long, env = "RALLY_DB_PASSWORD_FILE", hide_env_values = true)] - db_password_file: Option, + #[command(flatten)] + ledger: rally::store::LedgerFlags, /// The pairing file. Defaults to ~/.config/rally/client.json. #[arg(long, env = "RALLY_CONFIG")] config: Option, @@ -4064,8 +4054,7 @@ fn run(cli: Cli) -> Result> { cli.command, Command::AddMachine { .. } | Command::Revoke { .. } | Command::Pair ); - let password_file = cli.db_password_file.filter(|_| uses_database); - let location = Location::named(cli.db, cli.head_file, password_file)?; + let location = cli.ledger.location(uses_database)?; let ci_wait = match &cli.command { Command::Merge { ci_wait, .. } => Duration::from_secs(*ci_wait), _ => Duration::ZERO, diff --git a/src/store.rs b/src/store.rs index eb8ceca..aada27d 100644 --- a/src/store.rs +++ b/src/store.rs @@ -134,6 +134,34 @@ pub struct Location { pub password_file: Option, } +/// The flags that name a ledger for every command: `--db`, `--head-file` and +/// `--db-password-file`. Declared here, not with the CLI's commands, since they're how the service +/// finds its ledger: a change to them is a change to what the service runs (RAL-196). +#[derive(clap::Args)] +pub struct LedgerFlags { + /// Work directly on the ledger in this Postgres database, such as + /// postgres://rally@127.0.0.1/rally, rather than through the service. Needs --head-file. + #[arg(long, env = "RALLY_DB", hide_env_values = true)] + pub db: Option, + /// With --db: the ledger's head file, kept outside Postgres so that removing the newest + /// records shows. + #[arg(long, env = "RALLY_HEAD_FILE")] + pub head_file: Option, + /// With --db: a file holding the Postgres role's password, readable only by this account, so + /// the password stays out of the command line and the URL. + #[arg(long, env = "RALLY_DB_PASSWORD_FILE", hide_env_values = true)] + pub db_password_file: Option, +} + +impl LedgerFlags { + /// The ledger these name, if any. A command that never touches the database (`uses_database` + /// false) ignores a password file, so a stray setting doesn't block it. + pub fn location(self, uses_database: bool) -> Result, String> { + let password_file = self.db_password_file.filter(|_| uses_database); + Location::named(self.db, self.head_file, password_file) + } +} + impl Location { /// The ledger `--db`, `--head-file` and `--db-password-file` name, if any: the service's, or /// a host command's. Kept here, not with the CLI's commands, since it's how the service finds