diff options
| author | tv <tv@krebsco.de> | 2026-11-19 14:11:39 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 15:18:45 +0100 |
| commit | 27b76d5748f23a879d9fc82c725a58b514020ef9 (patch) | |
| tree | d0201eed80c9c4a2db3f2e6281cac51dbc126ba6 | |
| parent | 8347900a553a3c4c9f9d3fc4a539fd31b41b07d3 (diff) | |
fork: a fork's check says what its version changes, rules among it
A node holding the history up to a fork's heads said whether it builds
the root, what it holds that those heads lack, and which parties' keys
the fork's version gives otherwise. A founder could change the rules, or
only their order, which says who writes where, and nobody joining was
shown it.
The check now says what the fork's version changes of the version
current at those heads, a line each as a proposal's are shown
(`client::changes`): `changes` in POST /events/fork, and
`continuum-party check` prints them. federation.md and the forking
guide say so, and that a fork's ID is compared whole: a founder trying
versions can steer its first few digits.
| -rw-r--r-- | docs/federation.md | 6 | ||||
| -rw-r--r-- | docs/guides/federation/forking-and-following.md | 15 | ||||
| -rw-r--r-- | docs/openapi.yaml | 11 | ||||
| -rw-r--r-- | src/api/events.rs | 7 | ||||
| -rw-r--r-- | src/federation/fork.rs | 26 | ||||
| -rw-r--r-- | src/federation/party.rs | 12 |
6 files changed, 61 insertions, 16 deletions
diff --git a/docs/federation.md b/docs/federation.md index f36eabd..e47da93 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -619,12 +619,14 @@ store of its own from the federation's ([`store.md`](store.md), [Forks](store.md heads with that version current. Every proposal is a chance to fork: the version is usually one that didn't pass. 2. A fork is named by its root's ID, which nobody can steer to a given name, the - federation it came from least of all. It takes only events with its root in their + federation it came from least of all; a few of its first digits can be, by trying + versions, so an ID is compared whole. It takes only events with its root in their history: what the stayers sign after it isn't taken there, nor what the fork's parties sign after it in the federation they left. 3. The others join it as a node joins any swarm, by its ID. A node holding the history up to those heads builds the root and checks it, says what it holds that those heads - lack, and, party by party, whether the fork's version gives it the keys it had there: + lack, what the fork's version changes of the one current there, its rules and their + order among it, and, party by party, whether it gives the party the keys it had there: a founder may give a party that didn't go keys of its own. A node that doesn't hold that history takes the root on its operator's word, as its operator names the fork. diff --git a/docs/guides/federation/forking-and-following.md b/docs/guides/federation/forking-and-following.md index ffc4fae..dafa974 100644 --- a/docs/guides/federation/forking-and-following.md +++ b/docs/guides/federation/forking-and-following.md @@ -55,14 +55,21 @@ A node holding the history up to the fork's heads builds its root and checks it: continuum-party --node http://lass:secret@localhost:3000 check fork-root # 7c55…: built here, byte for byte # its heads lack 0c7e… +# its version changes: +# changes: "3a90…" -> "b41f…" +# keys.makefu: {"keys":["ssh-ed25519 AAAA…"],"since":2} -> {"keys":[…],"since":5} +# nodes.lass: {"nodes":["continuum:9c07…"],"since":0} -> {…,"since":5} +# number: 4 -> 5 # makefu's keys: ["ssh-ed25519 AAAA…"] here, ["ssh-ed25519 AAAA…"] in the fork ``` Whether it builds that root at those heads; what it took that the heads lack (neither -among them, in their history, nor above them), which the fork doesn't hold; and, party by -party, the keys the fork's version gives otherwise than the party had at those heads. A -node that doesn't hold that history takes the root on its operator's word, who names the -fork by its ID. +among them, in their history, nor above them), which the fork doesn't hold; what the +fork's version changes of the one current at those heads, field by field, its rules and +their order among them, which say who writes where; and, party by party, the keys the +fork's version gives otherwise than the party had at those heads. A node that doesn't +hold that history takes the root on its operator's word, who names the fork by its ID: +compare that ID whole, as a founder trying versions can steer its first few digits. ## Following diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 4982cac..6cef2f2 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1694,7 +1694,10 @@ paths: byte for byte, and why it builds none where it doesn't (heads it doesn't hold, a version that is no fork); what it holds that those heads lack (`lacking`: events it took that are neither among them, nor in their history, nor above - them); and the parties whose keys the fork's version gives otherwise than they + them); what the fork's version changes of the version current at those heads, a + line each as `field: before -> after`, its rules among them, `keys` and `nodes` + party by party (`changes`); and the parties whose keys the fork's version gives + otherwise than they had at those heads, each with its keys there and in the fork. A node that doesn't hold that history takes a fork's root on its operator's word, who names the fork by its ID (`--store-id`). @@ -1712,7 +1715,7 @@ paths: application/json: schema: type: object - required: [fork, builds, why, lacking, keys] + required: [fork, builds, why, lacking, changes, keys] properties: fork: type: string @@ -1725,6 +1728,10 @@ paths: type: array items: type: string + changes: + type: array + items: + type: string keys: type: object additionalProperties: diff --git a/src/api/events.rs b/src/api/events.rs index 45c9a32..a3781c1 100644 --- a/src/api/events.rs +++ b/src/api/events.rs @@ -399,9 +399,9 @@ async fn make_fork(State(state): State<AppState>, Json(forking): Json<Forking>) /// `POST /events/fork`: what this node finds of the fork whose root is the body's first /// line, as the file its founders start from holds it: whether it builds that root at -/// its heads, and why not; what it holds that those heads lack; and the parties whose keys -/// the fork's version gives otherwise than they had there, each with its keys there and in -/// the fork. +/// its heads, and why not; what it holds that those heads lack; what the fork's version +/// changes of the one current there, a line each; and the parties whose keys the fork's +/// version gives otherwise than they had there, each with its keys there and in the fork. async fn check_fork(State(state): State<AppState>, body: Bytes) -> Response { let (root, _) = fork::read_root_file(&body); match state.holding.with(|store| fork::check(store, &root)) { @@ -418,6 +418,7 @@ async fn check_fork(State(state): State<AppState>, body: Bytes) -> Response { "builds": check.builds, "why": check.why, "lacking": ids(check.lacking), + "changes": check.changes, "keys": keys, })) .into_response() diff --git a/src/federation/fork.rs b/src/federation/fork.rs index 59b744f..c5ce727 100644 --- a/src/federation/fork.rs +++ b/src/federation/fork.rs @@ -1,9 +1,10 @@ //! Forks (`docs/federation.md`, Forks): a node holding a federation's history makes the //! root of a fork at heads it holds, by a version (`make`), and checks one it is given //! (`check`): whether it builds that root at its heads, what it holds that those heads -//! lack, and, party by party, the keys the fork's version gives where they aren't the -//! keys the party had there. A node that doesn't hold that history takes a fork's root on -//! its operator's word, who names the fork by its root's ID (`--store-id`). +//! lack, what the fork's version changes of the one current there, and, party by party, +//! the keys the fork's version gives where they aren't the keys the party had there. A +//! node that doesn't hold that history takes a fork's root on its operator's word, who +//! names the fork by its root's ID (`--store-id`). //! //! A fork's founders start its swarm from a file holding its root on the first line, and //! the events the root keeps, each on a line of its own (`--store-root`): JCS writes no @@ -60,14 +61,18 @@ pub(crate) struct Check { /// What it holds that those heads lack: events it took that are neither among them, /// nor in their history, nor above them. pub(crate) lacking: Vec<Id>, + /// What the fork's version changes of the version current at those heads, a line each + /// (`client::changes`): its rules among them, whose order says who writes where. + pub(crate) changes: Vec<String>, /// Each party whose keys the fork's version gives otherwise than the party had at /// those heads, with its keys there and in the fork. pub(crate) keys: Vec<(String, Vec<String>, Vec<String>)>, } /// What `store` finds of the fork whose root is `root`: as a node holding the history up -/// to its heads builds it, says what it holds that those heads lack, and, party by party, -/// whether the fork's version gives it the keys it had there. +/// to its heads builds it, says what it holds that those heads lack, what the fork's +/// version changes of the one current there, and, party by party, whether it gives the +/// party the keys it had there. pub(crate) fn check(store: &Store<Federation>, root: &[u8]) -> Result<Check, String> { let checkpoint = Checkpoint::read(root).ok_or("no checkpoint, so no fork's root")?; if checkpoint.at.is_empty() { @@ -84,12 +89,14 @@ pub(crate) fn check(store: &Store<Federation>, root: &[u8]) -> Result<Check, Str builds, why, lacking: Vec::new(), + changes: Vec::new(), keys: Vec::new(), }); } let lacking = store.left_out(heads, store.taken()); let at = store.state_at(heads); let current = at.current(); + let changes = super::client::changes(¤t.json, &version.json); let sorted = |mut keys: Vec<String>| { keys.sort(); keys @@ -121,6 +128,7 @@ pub(crate) fn check(store: &Store<Federation>, root: &[u8]) -> Result<Check, Str builds, why, lacking, + changes, keys, }) } @@ -148,12 +156,20 @@ mod tests { assert_eq!(read_root_file(&first.root()), (first.root(), Vec::new())); assert!(make(&store, &[Id::of(b"not held")], &spec.json()).is_err()); let check = check(&store, &root).unwrap(); + // What the fork's version changes: what it changes, tv's node list, its number. + let [changes, nodes, number] = check.changes.as_slice() else { + panic!("{:?}", check.changes); + }; + assert_eq!(*changes, format!("changes: null -> \"{}\"", first.hash())); + assert!(nodes.starts_with("nodes.tv: ") && nodes.ends_with(r#""since":1}"#)); + assert_eq!(number, "number: 0 -> 1"); assert_eq!( check, Check { builds: true, why: None, lacking: Vec::new(), + changes: check.changes.clone(), keys: Vec::new(), } ); diff --git a/src/federation/party.rs b/src/federation/party.rs index d829cc9..de8d9f9 100644 --- a/src/federation/party.rs +++ b/src/federation/party.rs @@ -351,6 +351,18 @@ pub(crate) async fn main() -> Result<()> { for id in check["lacking"].as_array().into_iter().flatten() { println!("its heads lack {}", id.as_str().unwrap_or_default()); } + let changes: Vec<&str> = check["changes"] + .as_array() + .into_iter() + .flatten() + .filter_map(JsonValue::as_str) + .collect(); + if !changes.is_empty() { + println!("its version changes:"); + } + for line in changes { + println!(" {line}"); + } for (party, keys) in check["keys"].as_object().into_iter().flatten() { println!( "{party}'s keys: {} here, {} in the fork", |
