aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/guides/federation/proposing-and-voting.md20
-rw-r--r--docs/guides/federation/watching.md3
-rw-r--r--docs/guides/federation/writing-and-reading.md3
-rw-r--r--docs/openapi.yaml19
-rw-r--r--src/api/events.rs13
-rw-r--r--src/federation/fold.rs85
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<AppState>, Path(id): Path<String>) -> 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<AppState>) -> Response {
with_store(&state, |store| {
let read = store.state();
@@ -138,9 +139,17 @@ async fn counts(State(state): State<AppState>) -> Response {
.ballots(&current.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<Id>,
}
+/// 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<Federation>, proposal: Id| {
+ let state = store.state();
+ let tally = state.tally(state.current(), &proposal);
+ let parties = |set: BTreeSet<&str>| -> Vec<String> {
+ 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());