From b2509d65edd97cca87b30b34b3631d26c6958523 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Mon, 16 Nov 2026 02:38:48 +0000 Subject: [PATCH 1/3] docs(log): a sidecar checkpoint entry is keyed by origin= too The module doc and the sidecar_keys doc gave an entry's lookup keys as path= and blob=, but sidecar_keys also keys an included child checkpoint by origin=, so a parent finds every checkpoint of one child log by its origin. Both docs now list the three keys and which changes carry them. The code was right, so there is no failing test; the include test now also finds the two logged checkpoints by origin=. --- changelog.d/+sidecar-origin-key.doc.md | 2 ++ crates/rfc9162-log/src/sidecar.rs | 10 ++++++---- crates/rfc9162-log/tests/sidecar.rs | 8 +++++++- 3 files changed, 15 insertions(+), 5 deletions(-) create mode 100644 changelog.d/+sidecar-origin-key.doc.md diff --git a/changelog.d/+sidecar-origin-key.doc.md b/changelog.d/+sidecar-origin-key.doc.md new file mode 100644 index 0000000..af9786f --- /dev/null +++ b/changelog.d/+sidecar-origin-key.doc.md @@ -0,0 +1,2 @@ +`rfc9162-log`: The `sidecar` module doc and `sidecar_keys` list every lookup key an entry gets: `path=`, `blob=` for a put, and `origin=` for a child's checkpoint. +They left out `origin=`. diff --git a/crates/rfc9162-log/src/sidecar.rs b/crates/rfc9162-log/src/sidecar.rs index 63c7d9f..4856745 100644 --- a/crates/rfc9162-log/src/sidecar.rs +++ b/crates/rfc9162-log/src/sidecar.rs @@ -10,8 +10,9 @@ //! [`rfc9162_tiles::PackStore`] the whole sidecar is one file and its lock. //! //! An entry is one JSON line, [`Change`], and its lookup keys are -//! `path=` and `blob=`, so a path's history is a point lookup -//! and everything under a directory is a range over the sorted runs. A blob +//! `path=`, `blob=` for a put and `origin=` for a +//! child's checkpoint, so a path's history is a point lookup and +//! everything under a directory is a range over the sorted runs. A blob //! is stored once per content hash at `blob/` before the entry that //! names it is appended, so an entry never names a blob the store lacks. //! Entries are at most the tile log's entry length; file content goes in @@ -80,8 +81,9 @@ pub struct Found { pub located: Located, } -/// The lookup keys of a sidecar entry: `path=` and `blob=`. An entry that is -/// not a sidecar change has no keys. +/// The lookup keys of a sidecar entry: `path=`, `blob=` for a put and +/// `origin=` for a checkpoint. An entry that is not a sidecar change has no +/// keys. #[must_use] pub fn sidecar_keys() -> Keys { Arc::new(|entry: &[u8]| { diff --git a/crates/rfc9162-log/tests/sidecar.rs b/crates/rfc9162-log/tests/sidecar.rs index 6fbf12a..99f2985 100644 --- a/crates/rfc9162-log/tests/sidecar.rs +++ b/crates/rfc9162-log/tests/sidecar.rs @@ -6,7 +6,7 @@ use std::collections::BTreeMap; use ed25519_dalek::SigningKey; use rfc9162::{hex, leaf_hash, verify_inclusion}; -use rfc9162_log::{Op, Sidecar}; +use rfc9162_log::{AuthenticatedLog, Op, Sidecar}; use rfc9162_tiles::{Checkpoint, Note, PackStore, Signer, TileStore, Verifier}; fn meta(actor: &str) -> BTreeMap { @@ -270,4 +270,10 @@ fn a_parent_logs_its_children_s_checkpoints_and_refuses_an_equivocation() { assert!(found[1].located.run.is_some()); assert!(parent.tree_at(parent.size()).unwrap().is_empty()); assert!(parent.under("stacks").unwrap().len() == 2); + // Each is also found by the child's origin. + let by_origin = parent.log().find(b"origin=example.org/stack").unwrap(); + assert_eq!( + by_origin.iter().map(|l| l.entry.index).collect::>(), + found.iter().map(|f| f.index).collect::>() + ); } From 26d4a9d9c39121fc936718b492c0f5b880c0c34d Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Mon, 16 Nov 2026 02:39:05 +0000 Subject: [PATCH 2/3] test(log): rejected sidecar command lines open the pack and exit 1 The binary's doc and the book promise status 2 for a command line it does not take, but run opens DIR/.sidecar/pack and takes its lock before it looks at the command, and main tells a usage error from a store error by the wording of the message. An unknown command or a missing argument leaves a new sidecar beside the project, and a non-numeric tree SIZE, include without --trusted, or a --trusted line that is not a key exit 1. The test runs each and expects status 2 with no .sidecar created. --- crates/rfc9162-log/tests/sidecar_cli.rs | 41 +++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/crates/rfc9162-log/tests/sidecar_cli.rs b/crates/rfc9162-log/tests/sidecar_cli.rs index 46ce0fd..5eba793 100644 --- a/crates/rfc9162-log/tests/sidecar_cli.rs +++ b/crates/rfc9162-log/tests/sidecar_cli.rs @@ -113,3 +113,44 @@ fn a_project_is_synced_snapshotted_and_read_back_from_the_shell() { Some(1) ); } + +#[test] +fn a_command_line_it_does_not_take_is_status_2_and_opens_nothing() { + let dir = tempfile::tempdir().unwrap(); + let project = dir.path().join("project"); + std::fs::create_dir_all(&project).unwrap(); + let p = project.to_str().unwrap(); + let note = dir.path().join("child.note"); + std::fs::write(¬e, "not a note\n").unwrap(); + let n = note.to_str().unwrap(); + let mut wrong = Vec::new(); + for args in [ + vec!["frobnicate", "--dir", p], + vec!["history", "--dir", p], + vec!["tree", "--dir", p, "ten"], + vec!["diff", "--dir", p, "0"], + vec!["blob", "--dir", p], + vec!["snapshot", "--dir", p, "--origin", "example.org/etc"], + vec!["include", "--dir", p, "child", "--note", n], + vec![ + "include", + "--dir", + p, + "child", + "--note", + n, + "--trusted", + "nokey", + ], + ] { + let status = cli(&args).status.code(); + let opened = project.join(".sidecar").exists(); + if status != Some(2) || opened { + wrong.push(format!( + "{args:?}: status {status:?}, sidecar opened {opened}" + )); + } + let _ = std::fs::remove_dir_all(project.join(".sidecar")); + } + assert!(wrong.is_empty(), "{}", wrong.join("\n")); +} From c0a8610093296f560318b8d309eb1ca62e7ff152 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Mon, 16 Nov 2026 02:40:18 +0000 Subject: [PATCH 3/3] fix(log): check the sidecar command line before opening the pack parse now builds a typed command with every argument it takes checked, the numbers parsed and the --trusted lines read as verifiers, so any command line the binary does not take is status 2 before run opens DIR/.sidecar/pack. Everything run can fail on is a store, a file or a proof and is status 1, which replaces telling the two apart by the wording of the message. The binary's doc and the reference page say a rejected command line opens nothing. --- changelog.d/+sidecar-cli-usage.bugfix.md | 2 + crates/rfc9162-log/src/bin/sidecar.rs | 193 +++++++++++++---------- docs/src/reference/sidecar.md | 2 +- 3 files changed, 117 insertions(+), 80 deletions(-) create mode 100644 changelog.d/+sidecar-cli-usage.bugfix.md diff --git a/changelog.d/+sidecar-cli-usage.bugfix.md b/changelog.d/+sidecar-cli-usage.bugfix.md new file mode 100644 index 0000000..dff3bcc --- /dev/null +++ b/changelog.d/+sidecar-cli-usage.bugfix.md @@ -0,0 +1,2 @@ +`rfc9162-sidecar`: A command line the binary does not take exits with status 2 and opens nothing: the command and its arguments are checked before `DIR/.sidecar/pack` is opened. +An unknown command or a missing argument created the pack, and a non-numeric tree `SIZE`, `include` without `--trusted`, or a `--trusted` line that is not a key exited 1. diff --git a/crates/rfc9162-log/src/bin/sidecar.rs b/crates/rfc9162-log/src/bin/sidecar.rs index e91ee88..e11a1b3 100644 --- a/crates/rfc9162-log/src/bin/sidecar.rs +++ b/crates/rfc9162-log/src/bin/sidecar.rs @@ -14,7 +14,8 @@ //! ``` //! //! Status 0 is done, 2 is a command line this binary does not take, 1 is a -//! store or a proof that did not answer. +//! store or a proof that did not answer. The command line is checked before +//! the pack is opened, so one it does not take leaves nothing at `DIR`. use std::collections::BTreeMap; use std::io::{self, Read, Write}; @@ -29,16 +30,39 @@ use rfc9162_tiles::{Checkpoint, Note, PackStore, Signer, Verifier}; const SIDECAR_DIR: &str = ".sidecar"; struct Args { - command: String, - dir: Option, - key: Option, - origin: Option, - note: Option, + dir: PathBuf, + command: Command, out: Option, skip: Vec, - trusted: Vec, meta: BTreeMap, - rest: Vec, +} + +/// A command with the arguments it takes, each checked. +enum Command { + Init, + Sync, + Snapshot { + key: PathBuf, + origin: String, + }, + History { + path: String, + }, + Tree { + size: Option, + }, + Diff { + from: u64, + to: u64, + }, + Blob { + hex: String, + }, + Include { + path: String, + note: PathBuf, + trusted: Vec, + }, } fn usage(what: &str) -> ExitCode { @@ -49,41 +73,83 @@ fn usage(what: &str) -> ExitCode { fn parse(argv: Vec) -> Result { let mut it = argv.into_iter(); - let command = it.next().ok_or("a command is needed")?; - let mut args = Args { - command, - dir: None, - key: None, - origin: None, - note: None, - out: None, - skip: Vec::new(), - trusted: Vec::new(), - meta: BTreeMap::new(), - rest: Vec::new(), - }; + let name = it.next().ok_or("a command is needed")?; + let (mut dir, mut key, mut origin, mut note, mut out) = (None, None, None, None, None); + let (mut skip, mut trusted, mut meta, mut rest) = + (Vec::new(), Vec::new(), BTreeMap::new(), Vec::new()); while let Some(arg) = it.next() { let mut value = |flag: &str| it.next().ok_or(format!("{flag} needs a value")); match arg.as_str() { - "--dir" => args.dir = Some(PathBuf::from(value("--dir")?)), - "--key" => args.key = Some(PathBuf::from(value("--key")?)), - "--origin" => args.origin = Some(value("--origin")?), - "--note" => args.note = Some(PathBuf::from(value("--note")?)), - "--out" => args.out = Some(PathBuf::from(value("--out")?)), - "--skip" => args.skip.push(value("--skip")?), - "--trusted" => args.trusted.push(value("--trusted")?), + "--dir" => dir = Some(PathBuf::from(value("--dir")?)), + "--key" => key = Some(PathBuf::from(value("--key")?)), + "--origin" => origin = Some(value("--origin")?), + "--note" => note = Some(PathBuf::from(value("--note")?)), + "--out" => out = Some(PathBuf::from(value("--out")?)), + "--skip" => skip.push(value("--skip")?), + "--trusted" => trusted.push(value("--trusted")?), "--meta" => { let pair = value("--meta")?; let (k, v) = pair .split_once('=') .ok_or(format!("--meta {pair:?} is not K=V"))?; - args.meta.insert(k.to_string(), v.to_string()); + meta.insert(k.to_string(), v.to_string()); } other if other.starts_with("--") => return Err(format!("unknown flag {other}")), - _ => args.rest.push(arg), + _ => rest.push(arg), } } - Ok(args) + let number = |what: &str, text: &str| { + text.parse::() + .map_err(|_| format!("{what} {text:?} is not a number")) + }; + let command = match name.as_str() { + "init" => Command::Init, + "sync" => Command::Sync, + "snapshot" => Command::Snapshot { + key: key.ok_or("--key KEY.pem is needed")?, + origin: origin.ok_or("--origin ORIGIN is needed")?, + }, + "history" => Command::History { + path: rest.first().cloned().ok_or("history needs a PATH")?, + }, + "tree" => Command::Tree { + size: rest.first().map(|t| number("SIZE", t)).transpose()?, + }, + "diff" => match rest.as_slice() { + [from, to, ..] => Command::Diff { + from: number("FROM", from)?, + to: number("TO", to)?, + }, + _ => return Err("diff needs FROM TO".to_string()), + }, + "blob" => Command::Blob { + hex: rest.first().cloned().ok_or("blob needs HEX")?, + }, + "include" => { + let path = rest.first().cloned().ok_or("include needs a PATH")?; + let note = note.ok_or("--note FILE is needed")?; + if trusted.is_empty() { + return Err("--trusted KEYLINE is needed at least once".to_string()); + } + let trusted = trusted + .iter() + .map(|line| Verifier::parse(line).map_err(|e| format!("--trusted {line:?}: {e}"))) + .collect::, _>>()?; + Command::Include { + path, + note, + trusted, + } + } + other => return Err(format!("unknown command {other}")), + }; + Ok(Args { + dir: dir.ok_or("--dir DIR is needed")?, + command, + out, + skip, + meta, + }) } fn open(dir: &Path) -> Result { @@ -92,13 +158,13 @@ fn open(dir: &Path) -> Result { } fn run(args: &Args) -> Result<(), String> { - let dir = args.dir.as_deref().ok_or("--dir DIR is needed")?; + let dir = args.dir.as_path(); let store = open(dir)?; let mut sidecar = Sidecar::open(&store).map_err(|e| format!("sidecar: {e}"))?; let out = io::stdout(); let mut out = out.lock(); - match args.command.as_str() { - "init" => { + match &args.command { + Command::Init => { writeln!( out, "sidecar at {} size {}", @@ -107,7 +173,7 @@ fn run(args: &Args) -> Result<(), String> { ) .ok(); } - "sync" => { + Command::Sync => { let mut skip: Vec<&str> = vec![SIDECAR_DIR]; skip.extend(args.skip.iter().map(String::as_str)); let synced = sidecar @@ -135,9 +201,7 @@ fn run(args: &Args) -> Result<(), String> { ) .ok(); } - "snapshot" => { - let key = args.key.as_deref().ok_or("--key KEY.pem is needed")?; - let origin = args.origin.as_deref().ok_or("--origin ORIGIN is needed")?; + Command::Snapshot { key, origin } => { let signing = SigningKey::read_pkcs8_pem_file(key) .map_err(|e| format!("read signing key {}: {e}", key.display()))?; let signer = Signer::new(origin, signing).map_err(|e| format!("signer: {e}"))?; @@ -155,17 +219,13 @@ fn run(args: &Args) -> Result<(), String> { ) .ok(); } - "history" => { - let path = args.rest.first().ok_or("history needs a PATH")?; + Command::History { path } => { for found in sidecar.history(path).map_err(|e| format!("history: {e}"))? { writeln!(out, "{}", describe(found.index, &found.change)).ok(); } } - "tree" => { - let size = match args.rest.first() { - Some(text) => text.parse::().map_err(|_| "SIZE is a number")?, - None => sidecar.size(), - }; + Command::Tree { size } => { + let size = size.unwrap_or_else(|| sidecar.size()); for (path, (index, change)) in sidecar.tree_at(size).map_err(|e| format!("tree: {e}"))? { @@ -178,23 +238,12 @@ fn run(args: &Args) -> Result<(), String> { .ok(); } } - "diff" => { - let from = args - .rest - .first() - .and_then(|t| t.parse::().ok()) - .ok_or("diff needs FROM TO")?; - let to = args - .rest - .get(1) - .and_then(|t| t.parse::().ok()) - .ok_or("diff needs FROM TO")?; - for (index, change) in sidecar.diff(from, to).map_err(|e| format!("diff: {e}"))? { + Command::Diff { from, to } => { + for (index, change) in sidecar.diff(*from, *to).map_err(|e| format!("diff: {e}"))? { writeln!(out, "{}", describe(index, &change)).ok(); } } - "blob" => { - let hex = args.rest.first().ok_or("blob needs HEX")?; + Command::Blob { hex } => { let bytes = sidecar .blob(hex) .map_err(|e| format!("blob: {e}"))? @@ -205,28 +254,21 @@ fn run(args: &Args) -> Result<(), String> { None => out.write_all(&bytes).map_err(|e| format!("stdout: {e}"))?, } } - "include" => { - let path = args.rest.first().ok_or("include needs a PATH")?; - let note_path = args.note.as_deref().ok_or("--note FILE is needed")?; - if args.trusted.is_empty() { - return Err("--trusted KEYLINE is needed at least once".to_string()); - } + Command::Include { + path, + note: note_path, + trusted, + } => { let mut text = String::new(); std::fs::File::open(note_path) .and_then(|mut f| f.read_to_string(&mut text)) .map_err(|e| format!("read {}: {e}", note_path.display()))?; let note = Note::parse(&text).map_err(|e| format!("note: {e}"))?; - let trusted = args - .trusted - .iter() - .map(|line| Verifier::parse(line).map_err(|e| format!("trusted key: {e}"))) - .collect::, _>>()?; let index = sidecar - .include_checkpoint(path, ¬e, &trusted, args.meta.clone()) + .include_checkpoint(path, ¬e, trusted, args.meta.clone()) .map_err(|e| format!("include: {e}"))?; writeln!(out, "included {path} at {index}").ok(); } - other => return Err(format!("unknown command {other}")), } Ok(()) } @@ -258,13 +300,6 @@ fn main() -> ExitCode { }; match run(&args) { Ok(()) => ExitCode::SUCCESS, - Err(what) - if what.ends_with("is needed") - || what.starts_with("unknown command") - || what.contains("needs ") => - { - usage(&what) - } Err(what) => { eprintln!("rfc9162-sidecar: {what}"); ExitCode::from(1) diff --git a/docs/src/reference/sidecar.md b/docs/src/reference/sidecar.md index 2b8c9e7..ed61c1c 100644 --- a/docs/src/reference/sidecar.md +++ b/docs/src/reference/sidecar.md @@ -1,6 +1,6 @@ # rfc9162-sidecar -The binary in the `rfc9162-log` crate. Its rustdoc page is [`rfc9162_sidecar`](../api/rfc9162_sidecar/index.html). The pack for `--dir DIR` is `DIR/.sidecar/pack`. Each command opens that pack, holds the writer lock while it runs, and prints one line per result. Exit status 0 means the command finished. Exit status 2 means the command line is rejected. Exit status 1 means the store or a proof failed. +The binary in the `rfc9162-log` crate. Its rustdoc page is [`rfc9162_sidecar`](../api/rfc9162_sidecar/index.html). The pack for `--dir DIR` is `DIR/.sidecar/pack`. Each command opens that pack, holds the writer lock while it runs, and prints one line per result. Exit status 0 means the command finished. Exit status 2 means the command line is rejected; it is checked before the pack is opened, so nothing is created. Exit status 1 means the store or a proof failed. ```text rfc9162-sidecar init --dir DIR