From 1ed4ccdb0cd3a9407b6101b1bc595df2a451a18d Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 16:10:34 +0000 Subject: events: counts names who voted what, and whether a proposal passed or is dead `GET /events/counts` gives each proposal on the current version the parties voting `true` and `false` (`yes`, `no`), whether it passed and whether it is dead (`passed`, `dead`), as the node reads its votes (`State::tally`, which the fold judges by too), so that reading where a vote stands takes no fetch of every vote. A party's client still decides its votes by the votes it checks itself. --- docs/guides/federation/proposing-and-voting.md | 20 +++++- docs/guides/federation/watching.md | 3 +- docs/guides/federation/writing-and-reading.md | 3 +- docs/openapi.yaml | 19 +++++- src/api/events.rs | 13 +++- src/federation/fold.rs | 85 +++++++++++++++++++++----- 6 files changed, 120 insertions(+), 23 deletions(-) diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md index ee9a46a..3f4aa0f 100644 --- a/docs/guides/federation/proposing-and-voting.md +++ b/docs/guides/federation/proposing-and-voting.md @@ -113,6 +113,20 @@ kills it the sooner, and frees its backers for another. ## Following a vote `GET /events/counts` names each proposal on the current version with the events -proposing it (`proposals`) and the votes on it (`votes`), each by its ID; `GET -/events/{id}` shows a vote, signed by its party. A node writes nothing more than the -version once it passed; the parties' records keep their votes. +proposing it (`proposals`) and the votes on it (`votes`), each by its ID; the parties +voting `true` (`yes`) and `false` (`no`); and whether it passed (`passed`) and whether +it is dead (`dead`), as the node reads its votes: + +```sh +curl -s -u tv:secret localhost:3000/events/counts | jq .proposals +# {"8d02…":{"dead":true,"no":["lass"],"passed":false,"proposals":["c41e…"], +# "votes":["5a77…","e019…"],"yes":["tv"]}} +``` + +`GET /events/{id}` shows a proposing event, the version it proposes in `proposal`, and +a vote, signed by its party. A node lacking some votes reads a proposal as neither passed +nor dead where another reads it dead; no vote takes either back. A dead proposal stays +listed until a version passes on the current one, and a passed one is written at once; +then every proposal on the version before lapses. A party's client decides its votes by +the votes it checks itself, never by what a node says of them; the parties' records keep +their votes. diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md index e83408f..b66d5b4 100644 --- a/docs/guides/federation/watching.md +++ b/docs/guides/federation/watching.md @@ -13,7 +13,8 @@ besides it, the node's store, through its API and its log. read its store ([`when-things-go-wrong.md`](when-things-go-wrong.md), A node doing less than it should). * **Proposals on the current version** (`proposals` in `GET /events/counts`): each with - the votes on it; the party's record says what it voted. + who voted what, and whether it passed or is dead; the party's record says what it + voted. * **The version** (`.version.number` in `GET /events/counts`): a change nobody expected is worth a look at what passed and who voted for it. * **The members** (`members` in `GET /events/counts`): a node of your party missing diff --git a/docs/guides/federation/writing-and-reading.md b/docs/guides/federation/writing-and-reading.md index 0e6865c..a9e0c5a 100644 --- a/docs/guides/federation/writing-and-reading.md +++ b/docs/guides/federation/writing-and-reading.md @@ -97,7 +97,8 @@ Votes and proposals aren't signed again: their version is behind. * `values`: each place holding a value, with it; * `members`: each node of the swarm, with its party, `[node, party]`; * `proposals`: the proposals on the current version, by hash, each with the events - proposing it and the votes on it ([`proposing-and-voting.md`](proposing-and-voting.md)). + proposing it, the votes on it, the parties voting `true` and `false`, and whether it + passed and whether it is dead ([`proposing-and-voting.md`](proposing-and-voting.md)). `GET /events/{id}` is an event's bytes, as its party signed them: anyone can check its signature, an SSH signature over its bytes without `sig` (namespace diff --git a/docs/openapi.yaml b/docs/openapi.yaml index c2cee82..789ee6c 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1509,7 +1509,10 @@ paths: (its number, its hash, and the version itself), each party's keys and nodes, the value at each place, the members, each `[node, party]`, and the proposals on the current version, by their hash, each with the IDs of the events proposing it - (`proposals`) and of the votes on it (`votes`). + (`proposals`) and of the votes on it (`votes`), the parties voting `true` (`yes`) + and `false` (`no`), whether it passed (`passed`: two thirds of the parties voted + `true`) and whether it is dead (`dead`: so many voted `false` that the rest can't + pass it). A passed proposal is written at once, and lapses with the rest. responses: '200': description: What counts. @@ -1535,7 +1538,7 @@ paths: type: object additionalProperties: type: object - required: [proposals, votes] + required: [proposals, votes, yes, no, passed, dead] properties: proposals: type: array @@ -1545,6 +1548,18 @@ paths: type: array items: type: string + yes: + type: array + items: + type: string + no: + type: array + items: + type: string + passed: + type: boolean + dead: + type: boolean '404': $ref: '#/components/responses/Error' /events/refused: diff --git a/src/api/events.rs b/src/api/events.rs index 9fa8786..b388acc 100644 --- a/src/api/events.rs +++ b/src/api/events.rs @@ -111,7 +111,8 @@ async fn event(State(state): State, Path(id): Path) -> Respons /// `GET /events/counts`: what counts, as the store reads now: the current version, each /// party's keys and nodes, the values at places, the members, and the proposals on the -/// current version, each with the events proposing it and the votes on it. +/// current version, each with the events proposing it, the votes on it, the parties +/// voting `true` and `false`, and whether it passed and whether it is dead. async fn counts(State(state): State) -> Response { with_store(&state, |store| { let read = store.state(); @@ -138,9 +139,17 @@ async fn counts(State(state): State) -> Response { .ballots(¤t.hash) .into_iter() .map(|(hash, ballot)| { + let tally = read.tally(current, &hash); ( hash.to_string(), - json!({"proposals": ids(ballot.proposals), "votes": ids(ballot.votes)}), + json!({ + "proposals": ids(ballot.proposals), + "votes": ids(ballot.votes), + "yes": tally.yes, + "no": tally.no, + "passed": tally.passed, + "dead": tally.dead, + }), ) }) .collect(); diff --git a/src/federation/fold.rs b/src/federation/fold.rs index 78f5c39..89ce12c 100644 --- a/src/federation/fold.rs +++ b/src/federation/fold.rs @@ -49,6 +49,19 @@ pub(crate) struct Ballot { pub(crate) votes: Vec, } +/// What the votes on a proposal on a version make of it, as a store reads them. +#[derive(Debug, PartialEq, Eq)] +pub(crate) struct Tally<'a> { + /// The parties voting `true`. + pub(crate) yes: BTreeSet<&'a str>, + /// The parties voting `false`. + pub(crate) no: BTreeSet<&'a str>, + /// Whether it passed: two thirds of the parties of the version voted `true`. + pub(crate) passed: bool, + /// Whether it is dead: so many voted `false` that the rest can't pass it. + pub(crate) dead: bool, +} + /// A party's key set or node list. #[derive(Clone, Copy, PartialEq, Eq)] enum List { @@ -386,19 +399,17 @@ impl State { (yes, no) } - /// Whether a proposal on `on` passed here: two thirds of the parties of `on` voted - /// `true`. - fn passed(&self, on: &Version, proposal: &Id) -> bool { - let (yes, _) = self.votes(&on.hash, proposal); - 3 * yes.len() >= 2 * on.parties.len() - } - - /// Whether a proposal on `on` is dead here: so many voted `false` that the rest can't - /// pass it. - fn dead(&self, on: &Version, proposal: &Id) -> bool { - let (_, no) = self.votes(&on.hash, proposal); + /// What the votes here make of the proposal of hash `proposal` on `on`: who voted what, + /// whether it passed, and whether it is dead. + pub(crate) fn tally(&self, on: &Version, proposal: &Id) -> Tally<'_> { + let (yes, no) = self.votes(&on.hash, proposal); let parties = on.parties.len(); - 3 * (parties - no.len().min(parties)) < 2 * parties + Tally { + passed: 3 * yes.len() >= 2 * parties, + dead: 3 * (parties - no.len().min(parties)) < 2 * parties, + yes, + no, + } } /// Whether a signed event is taken here, at its history, `current` the version current @@ -461,7 +472,7 @@ impl State { _ => None, }) .collect(); - if backed.iter().any(|other| !self.dead(current, other)) { + if backed.iter().any(|other| !self.tally(current, other).dead) { return Err(Refused::new( "its party backs another proposal on that version, not dead", )); @@ -480,7 +491,7 @@ impl State { "its proposal isn't proposed on the version current at its history", )); } - if !self.passed(current, hash) { + if !self.tally(current, hash).passed { return Err(Refused::new("its proposal hasn't passed at its history")); } let next = Version::read(&self.proposed[hash]) @@ -781,6 +792,52 @@ mod tests { assert!(store.state().ballots(&next.hash()).is_empty()); } + /// Who voted what on a proposal, and whether it passed or is dead. + #[test] + fn a_tally_names_the_votes_and_whether_a_proposal_passed_or_is_dead() { + let (tv, lass, makefu) = (tv(), lass(), makefu()); + let spec = Spec::first(&[&tv, &lass, &makefu], &[]); + let mut store = federation(&spec); + let root = store.id(); + let on = spec.hash(); + let one = spec.after(on); + let mut two = spec.after(on); + two.rules.clear(); + let first = taken(store.offer(tv.propose(&[root], &one.json()))); + let second = taken(store.offer(tv.propose(&[root], &two.json()))); + let tally = |store: &Store, proposal: Id| { + let state = store.state(); + let tally = state.tally(state.current(), &proposal); + let parties = |set: BTreeSet<&str>| -> Vec { + set.into_iter().map(str::to_owned).collect() + }; + ( + parties(tally.yes), + parties(tally.no), + tally.passed, + tally.dead, + ) + }; + assert_eq!(tally(&store, one.hash()), (vec![], vec![], false, false)); + for (party, proposal, hash, yes) in [ + (&lass, first, one.hash(), true), + (&makefu, first, one.hash(), true), + (&lass, second, two.hash(), false), + (&makefu, second, two.hash(), false), + ] { + taken(store.offer(party.vote(&[proposal], on, hash, yes))); + } + let (lass, makefu) = ("lass".to_owned(), "makefu".to_owned()); + assert_eq!( + tally(&store, one.hash()), + (vec![lass.clone(), makefu.clone()], vec![], true, false) + ); + assert_eq!( + tally(&store, two.hash()), + (vec![], vec![lass, makefu], false, true) + ); + } + #[test] fn a_party_writes_where_a_rule_gives_it_the_place() { let (tv, lass) = (tv(), lass()); -- cgit v1.3.1