aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-17 16:32:23 +0000
committertv <tv@krebsco.de>2026-11-17 17:36:18 +0100
commit393fb4d70fc6bf88debc4ca13d644ea7de9602f5 (patch)
treed0df529c52d5b726e6be91124f2eadf2187e8183 /docs
parent1bbb45bfe7c9c437373aefa08a6a985bc260f520 (diff)
dashboard: the federation, in a swarm holding a storeHEADmaster
In a swarm holding a store, the snapshot names the node's party, and the document box shows what counts as the node reads it, read every 5 s: the current version, the parties with their keys and nodes, the rules, the values at places as a tree with who writes there, the proposals on the version with where each stands, who voted what and what its version changes, and what the node refused. `document` beside `remake…` shows the document underneath. Where the node votes for its party by itself, a proposal that can still pass has a vote of each kind, cast through the node on a second click. The page writes no values: a party signs its writes with its key.
Diffstat (limited to 'docs')
-rw-r--r--docs/dashboard.md41
-rw-r--r--docs/guides/federation/proposing-and-voting.md3
-rw-r--r--docs/guides/federation/watching.md7
-rw-r--r--docs/openapi.yaml3
4 files changed, 52 insertions, 2 deletions
diff --git a/docs/dashboard.md b/docs/dashboard.md
index ec99f97..d11bf3c 100644
--- a/docs/dashboard.md
+++ b/docs/dashboard.md
@@ -387,6 +387,39 @@ archive retention (`replayWindow`, `archiveRetention`: epochs, an age, or both;
empty, the defaults). The answer shows below: the remake's ID, or why it was refused
(and the API's override, if any). The map shows the votes as they come.
+## Federation
+
+In a swarm holding a store ([`guides/federation/`](guides/federation/README.md)), the
+document box shows what counts, as this node reads it, instead of the document: its
+title says `Federation`. `document` beside `remake…` shows the document underneath (the
+events at `_continuum/events` and each node's protocol data), and `federation` the
+federation again; the page keeps the choice. While shown, it is read every 5 s:
+
+* the current version, by its number and hash; the store, its checkpoint (`the root`
+ until the store moved to one) and how many events it took after it; the party this
+ node is of, and whether it votes for it by itself;
+* **parties**: each party's keys and nodes, as they count, each node with its alias and
+ whether it is a member;
+* **rules**: in order, each rule's path and who writes there;
+* **values**: each place holding a value, as a tree by its path's segments, with its
+ value and who writes there by the rules; the field above it lists only the places
+ whose path holds what is typed in it;
+* **proposals on version …**: each proposal on the current version, by its hash:
+ whether it passed, is dead, or can still pass; the parties voting `true` and `false`;
+ how many events propose it and how many votes are on it; and what its version changes
+ of the current one, a line each, as `continuum-party proposals` says it;
+* **refused**: what this node refused by what it took before (keys voted twice: tell its
+ party), what it dropped as its operator says, and what it refused as every node does,
+ each with its kind and why.
+
+Where this node votes for its party by itself, a proposal that can still pass has `vote
+true` and `vote false`: a vote through this node, by its party's record, cast on a
+second click within 3 s (`vote true: sure?`), as a vote isn't taken back. The answer
+shows beside them: the vote's ID, or why the node didn't cast it. Elsewhere the party
+votes with its client (`continuum-party vote`), and the page says so. The page writes
+no values: a party signs its writes with its key, which the page doesn't hold
+(`continuum-party write`).
+
## Console
The messages this node exchanged with its peers, one by one: when (on the 24-hour
@@ -533,4 +566,10 @@ Edits go through the store API too, as the user the page was opened as: `PUT
items each on its own (`PUT /store/<path>/<index>`), a new key with `PUT
/store/<path>/<key>`, an inserted item with `POST /store/<path>/<index>` (`-1` the end;
an index past the end is refused), and `DELETE /store/<path>`. The dashboard itself
-writes nothing to the document: only edits do.
+writes nothing to the document: only edits and votes do.
+
+**The federation** is read through the events API: `GET /events` every 5 s, and where
+the store's heads changed, `GET /events/counts`, `GET /events/refused`, and for each
+proposal not read before, the first event proposing it (`GET /events/{id}`), whose
+`proposal` is its version. Who writes at a place is the first rule whose path matches
+it (`Version::writer`). A vote is `POST /admin/events/vote`.
diff --git a/docs/guides/federation/proposing-and-voting.md b/docs/guides/federation/proposing-and-voting.md
index b25e9d9..8c9c66f 100644
--- a/docs/guides/federation/proposing-and-voting.md
+++ b/docs/guides/federation/proposing-and-voting.md
@@ -134,6 +134,9 @@ continuum-party --node http://tv:secret@localhost:3000 proposals
# number: 0 -> 1
```
+A node's dashboard shows them so too, and where the node votes for its party by itself,
+votes through it ([`dashboard.md`](../../dashboard.md), Federation).
+
`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
diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md
index b66d5b4..c04a6a3 100644
--- a/docs/guides/federation/watching.md
+++ b/docs/guides/federation/watching.md
@@ -23,6 +23,13 @@ besides it, the node's store, through its API and its log.
checkpoint would let nodes forget; a node voting by itself proposes one at a count you
set ([`voting-by-itself.md`](voting-by-itself.md)).
+## On the dashboard
+
+A node's dashboard (`/admin/dashboard`) shows the same in its document box, read every
+5 s: the version, the parties and which of their nodes are members, the values, the
+proposals with who voted what and what each changes, and what the node refused
+([`dashboard.md`](../../dashboard.md), Federation).
+
## In the log
At warn or error:
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 5cffccf..2017f15 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1226,7 +1226,8 @@ paths:
tags: [Admin]
summary: Dashboard state
description: |
- The dashboard's latest snapshot: `node` (`id`, `alias`), `page` (the page's
+ The dashboard's latest snapshot: `node` (`id`, `alias`, and `party`: in a swarm
+ holding a store, the party the node is of, else null), `page` (the page's
version, a hash: a page showing another reloads), `stats` (as
`/admin/stats`), `peers` (as `/peers`) and `graph`: `members` (by node ID,
those of the member list, and any of this node's links goes to: `alias`, `self`,