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/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/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/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::>() + ); } 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")); +} 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