diff options
| -rw-r--r-- | CHANGELOG.md | 6 | ||||
| -rw-r--r-- | docs/guides/federation/forking-and-following.md | 23 | ||||
| -rw-r--r-- | src/federation/party.rs | 241 |
3 files changed, 246 insertions, 24 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index b2664b6..7840755 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ it from the release before ([`docs/operations.md`](docs/operations.md), ## Unreleased +* `continuum-party fork` takes the changes `propose` does, or a proposal's version + (`fork proposal PROPOSAL`), forking at the heads the node shows unless others are named + (`--at`); `--founder PARTY=NODE,…` names a founder's node list anew in the fork + ([`docs/guides/federation/forking-and-following.md`](docs/guides/federation/forking-and-following.md); + [`src/federation/party.rs`](src/federation/party.rs)). + * `continuum-party propose` takes the changes made most by what they are for: `admit`, `remove`, `give`, `take`, `keys`, `nodes`, `checkpoint` and `revision` write the next version so and propose it. Every proposal says first what it does, and asks on a diff --git a/docs/guides/federation/forking-and-following.md b/docs/guides/federation/forking-and-following.md index 4890a61..63b7c40 100644 --- a/docs/guides/federation/forking-and-following.md +++ b/docs/guides/federation/forking-and-following.md @@ -19,23 +19,34 @@ go. The rules are the design's ([`federation.md`](../../federation.md), 1. **Choose the heads** it forks at: heads a node of yours showed (`heads` in `GET /events`) and has held for a while. The fork keeps what counts there; what was - written after them stays behind. -2. **Write the fork's version**: it changes the version current at those heads (that + written after them stays behind. Without heads named, the client forks at those the + node shows. +2. **Choose the fork's version**: it changes the version current at those heads (that version's hash as `changes`), numbered one past it. It names anew (`since` its number) the keys of any party whose keys it changes, and the founders' own node lists, so that their nodes are members there. It leaves out the parties that don't go, and may name those that weren't among the first to go, with their keys as they were, so that they can follow whenever they like. 3. **Make its root**, as a node holding that history builds it, with the events it - keeps: + keeps, to a file. The client writes the version as `propose` does, by what it is for + ([`common-changes.md`](common-changes.md)), here without lass, `--founder` naming the + founders' node lists anew, the nodes they run the fork on: ```sh - continuum-party --node http://tv:secret@localhost:3000 fork fork.json 4a1d… 9e30… \ + continuum-party --node http://tv:secret@localhost:3000 fork remove lass \ + --founder tv=continuum:1f0a… --founder makefu=continuum:83c2… > fork-root + ``` + + or by the version of a proposal that didn't pass, as often (`fork proposal 8d02`), or + by a version written by hand, at the heads given, by ID or prefix: + + ```sh + continuum-party --node http://tv:secret@localhost:3000 fork fork.json 4a1d 9e30 \ > fork-root ``` - The fork is named by its root's ID, the SHA-256 of its root (the file's first line), - which nobody can steer. + `--at 4a1d 9e30` names the heads for the others. The fork is named by its root's ID, + the SHA-256 of its root (the file's first line), which nobody can steer. 4. **Start it**: a node carries one swarm, so the founders start the fork's nodes with files of their own (state, document, store file), from the root (`--store-root fork-root`), or by its ID through one of them (`--store-id`), each diff --git a/src/federation/party.rs b/src/federation/party.rs index 3dfd951..4b7820f 100644 --- a/src/federation/party.rs +++ b/src/federation/party.rs @@ -32,9 +32,13 @@ //! passed or is dead, who voted what, and what its version changes (`client::changes`); //! * `root FILE`: the root of the federation whose first version `FILE` holds (JSON), //! the file its founders start its swarm from (`--store-root`), to standard output; -//! * `fork FILE HEAD...`: the root of the fork at the heads named by the version `FILE` -//! holds, as the node builds it, with the events it keeps: the file the fork's founders -//! start its swarm from, to standard output; +//! * `fork FILE [HEAD...]`: the root of the fork at the heads named (those the node shows, +//! where none are) by the version `FILE` holds, as the node builds it, with the events +//! it keeps: the file the fork's founders start its swarm from, to standard output. +//! `fork proposal PROPOSAL` forks by the version a proposal proposes, and `fork admit`, +//! `remove`, `give`, `take`, `keys`, `nodes` and `revision` by the next version changed +//! as they say, as `propose` does; at the heads `--at` names, `--founder PARTY=NODE,…` +//! naming a party's node list anew in the fork; //! * `check FILE`: what the node finds of the fork whose root `FILE` holds: whether it //! builds it, what it holds that its heads lack, and the parties whose keys it gives //! otherwise. @@ -183,9 +187,30 @@ fn command() -> Command { ) .subcommand( Command::new("fork") - .about("The root of the fork at heads by the version a file holds, as the node builds it") - .arg(id("file")) - .arg(Arg::new("heads").num_args(1..).required(true)), + .about( + "The root of a fork, as the node builds it, to standard output: at the \ + heads the node shows, or those named; by the version a file holds (JSON), \ + a proposal's, or the next one changed as a subcommand says", + ) + .arg(id("file").help("A file holding the fork's version (JSON)")) + .arg( + Arg::new("heads") + .num_args(1..) + .help("The heads it forks at, by ID or prefix: those the node shows where none are"), + ) + .args_conflicts_with_subcommands(true) + .subcommand_negates_reqs(true) + .subcommand( + Command::new("proposal") + .about("By the version a proposal on the current version proposes") + .arg(id("proposal")), + ) + .subcommands( + intents() + .into_iter() + .filter(|intent| intent.get_name() != "checkpoint"), + ) + .mut_subcommands(|intent| intent.args(forking())), ) .subcommand( Command::new("check") @@ -234,7 +259,28 @@ fn proposing() -> [Arg; 2] { ] } -/// The changes `propose` makes by what they are for (`Intent`), a subcommand each. +/// The options of `fork`'s subcommands: the heads, and the founders' node lists. +fn forking() -> [Arg; 2] { + [ + Arg::new("at") + .long("at") + .value_name("HEAD") + .num_args(1..) + .action(ArgAction::Append) + .help("The heads it forks at, by ID or prefix: those the node shows where none are"), + Arg::new("founder") + .long("founder") + .value_name("PARTY=NODE,…") + .action(ArgAction::Append) + .help( + "Names the party's node list anew in the fork, so that these nodes are members \ + there: a founder's, its nodes there", + ), + ] +} + +/// The changes `propose` makes by what they are for (`Intent`), a subcommand each; `fork` +/// takes them too, but `checkpoint`. fn intents() -> Vec<Command> { let required = |name: &'static str| Arg::new(name).required(true); let keys = || { @@ -557,19 +603,45 @@ pub(crate) async fn main() -> Result<()> { return Ok(()); } if name == "fork" { - let version = version_in(sub.get_one::<String>("file").expect("required"))?; - // Each head by its ID, or a prefix of one of the heads the node shows. + let (version, heads) = match sub.subcommand() { + None => ( + version_in(sub.get_one::<String>("file").expect("required"))?, + strings(sub, "heads"), + ), + Some(("proposal", given)) => { + let counts = node.counts().await?; + let proposal = proposal_named(&counts, given)?; + let version = proposal_version(&node, &counts, proposal).await?; + let mut version: JsonValue = serde_json::from_slice(&version.bytes())?; + founders(&mut version, given)?; + let version = client::json(&version).map_err(|why| anyhow!(why))?; + (version, strings(given, "at")) + } + Some((intent, given)) => { + let current = node.current().await?; + let mut version = intended(¤t, &intent_of(&node, intent, given).await?)?; + founders(&mut version, given)?; + let version = client::json(&version).map_err(|why| anyhow!(why))?; + (version, strings(given, "at")) + } + }; + // Each head by its ID, or a prefix of one of the heads the node shows; those it + // shows, where none is named. let (_, shown) = node.summary().await?; let shown: Vec<String> = shown.iter().map(Id::to_string).collect(); - let shown: Vec<&str> = shown.iter().map(String::as_str).collect(); - let heads = strings(sub, "heads") - .iter() - .map(|head| { - client::named(head, &shown, "head") - .map(|id| id.to_string()) - .map_err(|why| anyhow!(why)) - }) - .collect::<Result<Vec<String>>>()?; + let heads = if heads.is_empty() { + shown + } else { + let shown: Vec<&str> = shown.iter().map(String::as_str).collect(); + heads + .iter() + .map(|head| { + client::named(head, &shown, "head") + .map(|id| id.to_string()) + .map_err(|why| anyhow!(why)) + }) + .collect::<Result<Vec<String>>>()? + }; let body = serde_json::json!({ "heads": heads, "version": serde_json::from_slice::<JsonValue>(&version.bytes())?, @@ -869,6 +941,50 @@ async fn intent_of(node: &Node, name: &str, given: &ArgMatches) -> Result<Intent }) } +/// `--founder PARTY=NODE,…` of `given`: each party's node list named anew in the fork's +/// version `version`, `since` its number, so that those nodes are members there. +fn founders(version: &mut JsonValue, given: &ArgMatches) -> Result<()> { + let number = version["number"].clone(); + for item in strings(given, "founder") { + let (party, nodes) = item + .split_once('=') + .with_context(|| format!("--founder {item:?}: PARTY=NODE,… it is"))?; + if version["keys"].get(party).is_none() { + bail!("--founder {party}: no party of the fork's version"); + } + let nodes = node_ids( + nodes + .split(',') + .filter(|node| !node.is_empty()) + .map(str::to_owned) + .collect(), + )?; + version["nodes"][party] = serde_json::json!({"since": number, "nodes": nodes}); + } + Ok(()) +} + +/// The version the proposal `proposal` on the current version proposes, as `counts` names +/// the event proposing it, and the node holds it. +async fn proposal_version(node: &Node, counts: &JsonValue, proposal: Id) -> Result<Json> { + let ballot = &counts["proposals"][proposal.to_string()]; + let Some(id) = ballot["proposals"][0].as_str().and_then(Id::from_hex) else { + bail!( + "{proposal}: {}", + ballot["none"] + .as_str() + .unwrap_or("the node names no event proposing it") + ); + }; + match Event::read(&node.event(&id).await?) { + Some(Event::Signed(Signed { + does: Does::Proposal { hash, version }, + .. + })) if hash == proposal => Ok(version), + _ => bail!("the node's {id} isn't the proposal it names"), + } +} + /// The keys `given` names, as the federation spells them (without comments): each an /// `authorized_keys` line itself, or a file of such lines, blank ones and `#` comments /// left out; none twice. @@ -1800,6 +1916,95 @@ mod tests { super::command().debug_assert(); } + /// `propose` and `fork` take a file, or a subcommand saying what the version is for, + /// with their options after it. + #[test] + fn a_version_by_its_file_or_by_what_it_is_for() { + let parsed = |args: &[&str]| { + super::command().try_get_matches_from(["continuum-party"].iter().chain(args)) + }; + let matches = parsed(&["propose", "next.json", "--yes"]).unwrap(); + let (_, propose) = matches.subcommand().unwrap(); + assert!(propose.subcommand().is_none()); + assert!(super::proposing_flags(propose).get_flag("yes")); + let matches = parsed(&[ + "propose", "admit", "makefu", "--keys", "a.pub", "b.pub", "--nodes", "n1", "--yes", + ]) + .unwrap(); + let (_, propose) = matches.subcommand().unwrap(); + let (intent, admit) = propose.subcommand().unwrap(); + assert_eq!(intent, "admit"); + assert_eq!(super::strings(admit, "keys"), ["a.pub", "b.pub"]); + assert_eq!(super::strings(admit, "nodes"), ["n1"]); + assert!(super::proposing_flags(propose).get_flag("yes")); + assert!(!super::proposing_flags(propose).get_flag("print")); + assert!(parsed(&["propose", "checkpoint", "--print"]).is_ok()); + assert!(parsed(&["propose"]).is_err()); + assert!(parsed(&["propose", "next.json", "admit", "makefu"]).is_err()); + + let matches = parsed(&["fork", "fork.json"]).unwrap(); + let (_, fork) = matches.subcommand().unwrap(); + assert!(super::strings(fork, "heads").is_empty()); + let matches = parsed(&[ + "fork", + "remove", + "lass", + "--at", + "4a1d", + "9e30", + "--founder", + "tv=n1,n2", + ]) + .unwrap(); + let (_, fork) = matches.subcommand().unwrap(); + let (intent, remove) = fork.subcommand().unwrap(); + assert_eq!(intent, "remove"); + assert_eq!(super::strings(remove, "at"), ["4a1d", "9e30"]); + assert_eq!(super::strings(remove, "founder"), ["tv=n1,n2"]); + let matches = parsed(&["fork", "proposal", "8d02"]).unwrap(); + let (_, fork) = matches.subcommand().unwrap(); + assert_eq!(fork.subcommand_name(), Some("proposal")); + // A fork is at heads of its own: `checkpoint` is a file's name there. + let matches = parsed(&["fork", "checkpoint"]).unwrap(); + let (_, fork) = matches.subcommand().unwrap(); + assert!(fork.subcommand().is_none()); + } + + /// `--founder PARTY=NODE,…` names a party's node list anew in a fork's version, `since` + /// its number; one that isn't a party of it, or a node that isn't one, refused. + #[test] + fn founders_name_their_nodes_anew() { + use crate::federation::harness::node_id; + let founder = |given: &str| { + let matches = super::command() + .try_get_matches_from([ + "continuum-party", + "fork", + "remove", + "lass", + "--founder", + given, + ]) + .unwrap(); + let (_, fork) = matches.subcommand().unwrap(); + let (_, remove) = fork.subcommand().unwrap(); + let mut version = serde_json::json!({ + "number": 5, + "keys": {"tv": {"since": 0, "keys": []}}, + "nodes": {"tv": {"since": 0, "nodes": []}}, + }); + super::founders(&mut version, remove).map(|()| version) + }; + let version = founder(&format!("tv={},{}", node_id(1), node_id(2))).unwrap(); + assert_eq!( + version["nodes"]["tv"], + serde_json::json!({"since": 5, "nodes": [node_id(1), node_id(2)]}) + ); + assert!(founder(&format!("lass={}", node_id(1))).is_err()); + assert!(founder("tv=elsewhere").is_err()); + assert!(founder("tv").is_err()); + } + /// `--key` gives a public key itself, or the first of a file's with how many more it /// holds, or a private key file's key; a file of neither, or none, gives nothing. #[test] |
