diff options
| author | tv <tv@krebsco.de> | 2026-11-19 01:48:57 +0000 |
|---|---|---|
| committer | tv <tv@krebsco.de> | 2026-11-19 03:19:19 +0100 |
| commit | 101080b8a62709cd2606dece086f959781bdf38f (patch) | |
| tree | 618e9acdd6e5d311ece2cf5b213432257c31bc39 | |
| parent | e0075264e9efdd4c8a32290c0d5643e7f48bfb14 (diff) | |
vote: a follower copies no false, lapses nothing others back, waits after a move
A node following a party (`--store-follow`) handed it more than the text said:
* it copied the party's `false`: one party's nay freed bound followers, and its `true`
shown to some and its `false` to the rest passed a checkpoint at one history and made it
dead at another. It copies the `true` alone now, on any version too;
* a checkpoint lapses every other proposal: the followed party ended any proposal it
disliked by passing one. A node follows a checkpoint only where no proposal that changes
more can still pass that someone but its proposer backs;
* nothing bounded how often the store moved, so fresh events could be left out of every
checkpoint; and a node just started held nothing for a while, so the voters' rule kept
nothing. A node backs, and proposes, a checkpoint only once its store held its
checkpoint, or ran, for a while (`--store-back-after`, ten minutes unless set), by itself
or by hand.
`federation.md` says what following hands over, and row 58 what a follower on any
version copies; the guides and the example say the rest.
| -rw-r--r-- | docs/example.toml | 8 | ||||
| -rw-r--r-- | docs/federation.md | 27 | ||||
| -rw-r--r-- | docs/guides/federation/checkpoints.md | 7 | ||||
| -rw-r--r-- | docs/guides/federation/voting-by-itself.md | 15 | ||||
| -rw-r--r-- | src/config/mod.rs | 14 | ||||
| -rw-r--r-- | src/federation/vote.rs | 176 | ||||
| -rw-r--r-- | src/lib.rs | 1 |
7 files changed, 194 insertions, 54 deletions
diff --git a/docs/example.toml b/docs/example.toml index 7f01df7..4bb5c98 100644 --- a/docs/example.toml +++ b/docs/example.toml @@ -151,10 +151,11 @@ htpasswd = "/etc/continuum/htpasswd" # Behind the `federation` feature: this node votes and proposes for its party by itself # (docs/federation.md, Votes a node casts by itself), with a key its party's version # names, kept here, and its party's one record of its votes; its party then votes by -# hand only through it (POST /admin/events/vote). It follows the parties named (by -# default only on versions that only move to a checkpoint), votes `false` on a +# hand only through it (POST /admin/events/vote). It follows the `true` of the parties +# named (by default only on versions that only move to a checkpoint), votes `false` on a # checkpoint proposed beside one it backs, if told, and proposes a checkpoint once it -# holds so many events beyond its checkpoint, or so long after it moved there. +# holds so many events beyond its checkpoint, or so long after it moved there; it backs +# and proposes none sooner than store-back-after after a move or its start. # store-vote-key = "/var/lib/continuum/party.key" # store-vote-record = "/var/lib/continuum/party-record.json" # store-follow = ["lass"] @@ -163,6 +164,7 @@ htpasswd = "/etc/continuum/htpasswd" # store-propose-events = 10000 # store-propose-every = "7d" # store-held-for = "10m" +# store-back-after = "10m" # SSH keys, as authorized_keys lines (ssh-ed25519 <base64> [comment]), whose signature # on a strict remake's manifest this node takes: the values kept when the swarm turns diff --git a/docs/federation.md b/docs/federation.md index ade27a9..784915a 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -505,14 +505,18 @@ A party may have one of its nodes vote and propose for it, by rules its operator the rules are written nowhere in the swarm, and every node judges what such a node signs as it judges any vote or proposal. The design has two in mind: -* **Following**: back a proposal where a party the rule names backed it, and vote - `false` where that party did; a proposal binds its proposer to nothing, so following - one would bind the node where that party is free. By default it follows only on a - version that only moves to a checkpoint ([Checkpoints](#checkpoints)), a `true` as a - `false`; its operator may have it follow on any version, which hands that party the - node's vote, its `false` among it: a party followed so by more than a third of the - parties, its key kept on a node, ends every proposal, the one naming that key anew among - them. +* **Following**: back a proposal where a party the rule names backed it; a proposal + binds its proposer to nothing, so following one would bind the node where that party is + free. A `false` it copies not: copied, one party's `false` would free bound followers, + and its `true` shown to some and its `false` to the rest would pass a proposal at one + history and make it dead at another. By default it follows only on a version that only + moves to a checkpoint ([Checkpoints](#checkpoints)), and only where no proposal that + changes more can still pass, but one nobody backs but its proposer: such a version + lapses every other proposal, and the party it follows would end any it disliked by + passing one. Even so, the parties following one hand it their votes on checkpoints: with + them, it passes one at heads of its choosing, by the voters' rule (below). Its operator + may have it follow on any version, which hands that party the node's `true`: a party + followed so by two thirds of the parties, its key kept on a node, passes what it backs. * **Proposing a checkpoint**: propose a version that only moves to a checkpoint, at heads the node has held for a while, once conditions its operator sets are met: so many events or bytes held beyond its checkpoint, so many versions since it, or so long @@ -529,7 +533,10 @@ rule for checkpoints, none for a version that changes more than its number, what changes and its checkpoint, which it checks against the current one, nor for one whose heads leave out what it held for a while ([Checkpoints](#checkpoints)). Where two checkpoints are proposed at once, the votes split, as any do; a rule may vote `false` on -the one it doesn't back, so that one dies and its backers are free. A node that stopped +the one it doesn't back, so that one dies and its backers are free. It backs, and +proposes, a checkpoint only once its store held its checkpoint, or ran, for a while, by +its own clock: so the parties it follows move the store at most once that long, and a +node just started, which holds nothing for a while yet, backs none. A node that stopped at a version it doesn't read casts nothing, by itself or by hand, as what it reads is behind ([Changing the federation](#changing-the-federation)). @@ -722,7 +729,7 @@ fold, with crafted events. *Sim*: a simulation. *Bench*: measured, not judged. | 55 | A checkpoint a node can't build, handed to it by peers, or a fork's root it can't check | Taken only where its operator pinned it, or named the fork | unit | | 56 | Two versions changing one, naming different checkpoints | As 12: each node keeps the one it took, and moves to its checkpoint | unit | | 57 | A key added back, or a place given back, after a checkpoint | Brings back nothing signed before the checkpoint that counted no more there | unit | -| 58 | A party a node follows backs, or votes `false` on, a version that changes more than its checkpoint | By default the node follows neither; one following on any version does, as its operator chose | unit | +| 58 | A party a node follows backs, or votes `false` on, a version that changes more than its checkpoint | By default the node follows neither; one following on any version backs the one, as its operator chose, and copies no `false` | unit | | 59 | Two checkpoints proposed at once, by nodes voting by themselves | The votes split; nays from the nodes backing one make the other dead, and its backers are free | sim | | 60 | Two nodes of one party, each voting by itself | They can vote twice, answered as any party voting twice: a party has one node vote by itself | — | | 61 | A key a version names, kept on a node that votes by itself, stolen with it | As 23: it counts while that version is current | unit | diff --git a/docs/guides/federation/checkpoints.md b/docs/guides/federation/checkpoints.md index 69debaf..345bc98 100644 --- a/docs/guides/federation/checkpoints.md +++ b/docs/guides/federation/checkpoints.md @@ -50,8 +50,11 @@ only so, and so does a vote by hand through it (`continuum-party vote … --thro party's client voting on its own (`continuum-party vote`) checks no heads: check them yourself, or vote through such a node. -* `--store-follow PARTY,…` has a node voting by itself follow those parties' votes, by - default on versions that only move to a checkpoint, and still by that rule. +* `--store-follow PARTY,…` has a node voting by itself follow those parties' `true`, + by default on versions that only move to a checkpoint, and still by that rule, but not + where a proposal changing more can still pass that someone but its proposer backs. +* `--store-back-after` (ten minutes unless set) has it back none before its store held its + checkpoint, or ran, that long. * `--store-nay-beside` has it vote `false` on every other version only moving to a checkpoint, where it backs one that can still pass: of two checkpoints proposed at once, the other dies, and its backers are free. diff --git a/docs/guides/federation/voting-by-itself.md b/docs/guides/federation/voting-by-itself.md index b88947a..97f4eff 100644 --- a/docs/guides/federation/voting-by-itself.md +++ b/docs/guides/federation/voting-by-itself.md @@ -37,11 +37,16 @@ or `POST /admin/events/vote` with `{"proposal": "8d02…", "yes": true}`. ## Its rules * **Following** (`--store-follow PARTY,…`): it votes `true` on a proposal where a party - it follows voted `true`, and `false` where one voted `false`; by default only on a - version that only moves to a checkpoint. With `--store-follow-any`, on any version: - that hands those parties the node's vote, its `false` among it. A party followed so by - more than a third of the parties, with its key kept on a node, can end every proposal, - the one naming that key anew among them. + it follows voted `true`, never `false`; by default only on a version that only moves to + a checkpoint, and only where no proposal changing more can still pass that someone but + its proposer backs, as a checkpoint lapses it. Even so, the parties following one hand + it their votes on checkpoints. With `--store-follow-any`, on any version: that hands + those parties the node's `true`. A party followed so by two thirds of the parties, with + its key kept on a node, passes what it backs. +* **After a move** (`--store-back-after`, ten minutes unless set): it backs, and proposes, + no checkpoint until its store held its checkpoint, or ran, that long by its own clock, + by itself or by hand: the parties it follows move the store once that long at most, and + just started, it holds nothing for a while yet. * **Proposing checkpoints** (`--store-propose-events COUNT`, `--store-propose-every DURATION`): once it holds so many events beyond its checkpoint, or so long after its store moved there by its own clock, it proposes a version that only moves to a diff --git a/src/config/mod.rs b/src/config/mod.rs index 8196db6..412753e 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -312,6 +312,14 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[ Some("10m"), "With store-vote-key: how long it holds an event before it holds it for a while: it proposes a checkpoint at the heads of such, and backs none whose heads leave out one it held for a while before it was proposed.", ), + #[cfg(feature = "federation")] + option( + "store-back-after", + Kind::Duration, + "DURATION", + Some("10m"), + "With store-vote-key: how long its store holds its checkpoint, or runs, by its own clock, before it backs or proposes a later one, by itself or by hand: a party it follows moves the store once that long at most, and just started it backs none, as it holds nothing for a while yet.", + ), option( "strict-keys", Kind::List, @@ -832,6 +840,12 @@ pub(crate) struct Settings { with = "crate::units::duration_option" )] pub(crate) store_held_for: Duration, + #[cfg(feature = "federation")] + #[serde( + default = "default_store_held_for", + with = "crate::units::duration_option" + )] + pub(crate) store_back_after: Duration, #[serde(default)] pub(crate) strict_keys: Vec<String>, diff --git a/src/federation/vote.rs b/src/federation/vote.rs index 693339e..bf866e7 100644 --- a/src/federation/vote.rs +++ b/src/federation/vote.rs @@ -3,9 +3,10 @@ //! any vote or proposal. //! //! * **Following**: it votes `true` on a proposal on the current version where a party it -//! follows voted `true`, and `false` where one voted `false`; by default only on a -//! version that only moves to a checkpoint (`Version::only_moves_on`), a `true` as a -//! `false`. +//! follows voted `true`, never `false`; by default only on a version that only moves to a +//! checkpoint (`Version::only_moves_on`), and then only where no proposal that changes +//! more can still pass, but one nobody backs but its proposer (`holds_back`), as such a +//! version lapses it. //! * **Proposing a checkpoint**: once so many events are held beyond its checkpoint, or so //! long after it moved there by its own clock, it proposes a version that only moves to //! a checkpoint, at the heads of what it held for a while, where nothing that can still @@ -20,7 +21,9 @@ //! one record of its votes kept on it; and, by the voters' rule, backs a version naming a //! checkpoint only where it changes nothing of the current one but its number, what it //! changes and its checkpoint, and its heads leave out nothing it held for a while before -//! it was proposed (`Store::left_out`). +//! it was proposed (`Store::left_out`), and only once its store held its checkpoint, or +//! ran, for a while (`Rules::back_after`): a party it follows moves the store once that +//! long at most, and a node just started backs none, as it holds nothing for a while yet. use std::collections::BTreeSet; use std::time::Duration; @@ -48,6 +51,9 @@ pub(crate) struct Rules { pub(crate) held_for: Duration, /// Voting `false` on a checkpoint proposed beside one it backs. pub(crate) nay_beside: bool, + /// How long its store holds its checkpoint, or runs, before it backs or proposes a + /// later one. + pub(crate) back_after: Duration, } /// What the node sees: its store, how long it has held each event it took, and how long @@ -144,7 +150,8 @@ fn proposed(seen: &Seen<'_>, current: &Version) -> Vec<Proposed> { /// Whether the node backs `version`, proposed `proposed_held` ago, by the voters' rule: one /// naming a checkpoint only where it changes nothing of `current` but its number, what it /// changes and its checkpoint, and its heads leave out nothing the node held for a while -/// before it was proposed, proposals and votes aside, which lapse with the move. +/// before it was proposed, proposals and votes aside, which lapse with the move; and only +/// once its store held its checkpoint, or ran, for a while (`Rules::back_after`). pub(crate) fn backs_checkpoint( seen: &Seen<'_>, rules: &Rules, @@ -160,6 +167,13 @@ pub(crate) fn backs_checkpoint( "a checkpoint that changes more than its number and what it changes".to_owned(), ); } + if seen.since_move < rules.back_after { + return Err(format!( + "its store held its checkpoint, or ran, {}s: it backs a later one after {}s", + seen.since_move.as_secs(), + rules.back_after.as_secs() + )); + } let before = proposed_held + rules.held_for; // Proposals and votes lapse with the move: they count no more on the version after. let lapsing = |id: &Id| { @@ -194,6 +208,12 @@ fn alive(current: &Version, proposed: &Proposed) -> bool { 3 * (parties - proposed.no.len().min(parties)) >= 2 * parties } +/// Whether `proposed` holds back a version that only moves to a checkpoint, which would +/// lapse it: it can still pass, and someone but its proposer backs it. +fn holds_back(current: &Version, proposed: &Proposed) -> bool { + alive(current, proposed) && !proposed.yes.is_subset(&proposed.proposers) +} + /// What a node voting by itself by `rules` signs now, as it sees its store, by /// its party's `record`: its votes, at most one `true`, and a proposal of a checkpoint. pub(crate) fn decide(seen: &Seen<'_>, rules: &Rules, record: &Record) -> Vec<Act> { @@ -218,36 +238,48 @@ pub(crate) fn decide(seen: &Seen<'_>, rules: &Rules, record: &Record) -> Vec<Act .flat_map(|proposed| proposed.votes.iter().cloned()) .collect(); for proposed in &all { - let follows = - |votes: &BTreeSet<String>| rules.follow.iter().any(|party| votes.contains(party)); - let yes = if own.contains(&proposed.hash) || follows(&proposed.yes) { - true - } else if follows(&proposed.no) { - false - } else { + let own_one = own.contains(&proposed.hash); + // A `false` it copies not: one party's would free bound followers. + let follows = rules + .follow + .iter() + .any(|party| proposed.yes.contains(party)); + if !own_one && !follows { continue; - }; + } let moves_on = proposed .version .as_ref() .is_some_and(|version| version.only_moves_on(¤t)); - if !own.contains(&proposed.hash) && !rules.follow_any && !moves_on { + if !own_one && !rules.follow_any && !moves_on { + continue; + } + // A checkpoint lapses what else is proposed: the party it follows may not end so + // a proposal that changes more. + let lapses = all.iter().any(|other| { + other.hash != proposed.hash + && !other + .version + .as_ref() + .is_some_and(|version| version.only_moves_on(¤t)) + && holds_back(¤t, other) + }); + if !own_one && moves_on && lapses { continue; } // One `true` at a time, for a version, by the voters' rule. - if yes - && (backed - || proposed.version.as_ref().is_none_or(|version| { - backs_checkpoint(seen, rules, ¤t, version, proposed.held).is_err() - })) + if backed + || proposed.version.as_ref().is_none_or(|version| { + backs_checkpoint(seen, rules, ¤t, version, proposed.held).is_err() + }) { continue; } - if let Ok(kept) = record.may_vote(¤t, proposed.hash, &proposed.json, yes, &nays) { - backed |= yes; + if let Ok(kept) = record.may_vote(¤t, proposed.hash, &proposed.json, true, &nays) { + backed = true; acts.push(Act::Vote { proposal: proposed.hash, - yes, + yes: true, nays: kept, }); } @@ -369,7 +401,7 @@ fn checkpoint(seen: &Seen<'_>, rules: &Rules, current: &Version, all: &[Proposed || rules .propose_every .is_some_and(|every| seen.since_move >= every); - if !due { + if !due || seen.since_move < rules.back_after { return None; } let blocked = all.iter().any(|proposed| { @@ -377,7 +409,7 @@ fn checkpoint(seen: &Seen<'_>, rules: &Rules, current: &Version, all: &[Proposed version.only_moves_on(current) && backs_checkpoint(seen, rules, current, version, proposed.held).is_ok() }); - alive(current, proposed) && (backs || !proposed.yes.is_subset(&proposed.proposers)) + (alive(current, proposed) && backs) || holds_back(current, proposed) }); if blocked { return None; @@ -506,11 +538,12 @@ mod tests { &acts[0], Act::Vote { proposal, yes: true, .. } if *proposal == checkpoint.hash() )); + // On any version, the checkpoint still; the other's `false` it copies not. let any = Rules { follow_any: true, ..rules.clone() }; - assert_eq!(decide(&seen(&store, &long), &any, &record).len(), 2); + assert_eq!(decide(&seen(&store, &long), &any, &record).len(), 1); // Heads leaving out what it held for a while before it was proposed: not backed. let later = taken( &mut store, @@ -528,7 +561,8 @@ mod tests { /// Row 58 (`docs/federation.md`): a party the node follows backs, or votes `false` on, /// a version that changes more than moving to a checkpoint: by default the node follows - /// neither; one following on any version, as its operator chose, follows both. + /// neither; one following on any version, as its operator chose, backs the one, and + /// copies the `false` not. #[test] fn federation_attack_58() { let (tv, _, _, first, mut store) = three(); @@ -563,15 +597,89 @@ mod tests { ..rules }; let acts = decide(&seen(&store, &long), &any, &record); - assert_eq!(acts.len(), 2); - assert!(acts.iter().any(|act| matches!( - act, + assert_eq!(acts.len(), 1); + assert!(matches!( + &acts[0], Act::Vote { proposal, yes: true, .. } if *proposal == backed.hash() - ))); - assert!(acts.iter().any(|act| matches!( - act, - Act::Vote { proposal, yes: false, .. } if *proposal == opposed.hash() - ))); + )); + } + + /// A party the node follows backs a checkpoint while a proposal that changes more, + /// which another party backs, can still pass: the node backs it not, as it would lapse + /// that one; while nobody but its proposer backs that one, it does. + #[test] + fn a_follower_lets_no_checkpoint_lapse_what_others_back() { + let (tv, lass, _, first, mut store) = three(); + let root = store.id(); + let on = first.hash(); + let write = taken( + &mut store, + tv.write(&[root], "home/tv/a", harness::str("1")), + ); + let mut checkpoint = first.after(on); + checkpoint.checkpoint = Some(vec![write]); + let mut other = first.after(on); + other + .rules + .push(("names/x".to_owned(), harness::str("lass"))); + let proposal = taken(&mut store, tv.propose(&[write], &checkpoint.json())); + let elsewhere = taken(&mut store, lass.propose(&[root], &other.json())); + taken( + &mut store, + tv.vote(&[proposal], on, checkpoint.hash(), true), + ); + let rules = Rules { + follow: vec!["tv".to_owned()], + ..Rules::default() + }; + let long = |_: &Id| Some(Duration::from_secs(3600)); + let record = record(&store, "makefu"); + // lass proposed the other, and backs it alone: the checkpoint, followed. + taken(&mut store, lass.vote(&[elsewhere], on, other.hash(), true)); + assert_eq!(decide(&seen(&store, &long), &rules, &record).len(), 1); + // Backed by another too: not. + taken(&mut store, tv.vote(&[elsewhere], on, other.hash(), true)); + assert!(decide(&seen(&store, &long), &rules, &record).is_empty()); + } + + /// A node backs no checkpoint, and proposes none, before its store held its checkpoint, + /// or ran, for a while: a party it follows moves the store once that long at most, and + /// just started it holds nothing for a while yet. + #[test] + fn a_node_backs_no_checkpoint_soon_after_a_move_or_its_start() { + let (tv, _, _, first, mut store) = three(); + let root = store.id(); + let on = first.hash(); + let write = taken( + &mut store, + tv.write(&[root], "home/tv/a", harness::str("1")), + ); + let mut checkpoint = first.after(on); + checkpoint.checkpoint = Some(vec![write]); + let proposal = taken(&mut store, tv.propose(&[write], &checkpoint.json())); + taken( + &mut store, + tv.vote(&[proposal], on, checkpoint.hash(), true), + ); + let rules = Rules { + follow: vec!["tv".to_owned()], + propose_events: Some(1), + back_after: Duration::from_secs(600), + ..Rules::default() + }; + let long = |_: &Id| Some(Duration::from_secs(3600)); + let record = record(&store, "makefu"); + let soon = Seen { + store: &store, + held: &long, + since_move: Duration::from_secs(60), + }; + assert!(decide(&soon, &rules, &record).is_empty()); + let later = Seen { + since_move: Duration::from_secs(700), + ..soon + }; + assert_eq!(decide(&later, &rules, &record).len(), 1); } #[test] @@ -70,6 +70,7 @@ fn voter(args: &config::Settings) -> Result<Option<federation::held::Voter>> { propose_events: args.store_propose_events, propose_every: args.store_propose_every, held_for: args.store_held_for, + back_after: args.store_back_after, }, })) } |
