From 393fb4d70fc6bf88debc4ca13d644ea7de9602f5 Mon Sep 17 00:00:00 2001 From: tv Date: Tue, 17 Nov 2026 16:32:23 +0000 Subject: dashboard: the federation, in a swarm holding a store MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/dashboard.md | 41 ++- docs/guides/federation/proposing-and-voting.md | 3 + docs/guides/federation/watching.md | 7 + docs/openapi.yaml | 3 +- src/api/dashboard/check.js | 52 +++- src/api/dashboard/dashboard.html | 383 ++++++++++++++++++++++++- src/api/dashboard/mod.rs | 10 +- 7 files changed, 488 insertions(+), 11 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//`), a new key with `PUT /store//`, an inserted item with `POST /store//` (`-1` the end; an index past the end is refused), and `DELETE /store/`. 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`, diff --git a/src/api/dashboard/check.js b/src/api/dashboard/check.js index 95f805a..4292e7d 100644 --- a/src/api/dashboard/check.js +++ b/src/api/dashboard/check.js @@ -2,8 +2,9 @@ // dashboard_in_a_browser -- --ignored`, which serves this the page as the node does): the // page loads without errors; the peers table has a row per peer, and an update changes // cells without making the rows anew (`morphChildren`); the map draws a node per member; -// and with 300 members, laid out by round trip, the first drawing doesn't hold the page up -// for long (`LAYOUT_FOR_MS`). +// with 300 members, laid out by round trip, the first drawing doesn't hold the page up +// for long (`LAYOUT_FOR_MS`); and in a swarm holding a store, the document box shows the +// federation: who writes at a place, what a proposal changes, and the votes. // // Needs Node.js, Playwright's library (`playwright-core`) and its Chromium; `check.nix` // gives all three from nixpkgs. @@ -77,6 +78,53 @@ const check = (ok, what) => { check(map.ms < budget, `${n} members drawn in ${map.ms.toFixed(0)} ms (under ${budget})`); } + // The federation, as the node would answer (`GET /events`, `/events/counts`, …). + const federated = await tab.evaluate(() => { + const rules = [{ path: "home/{party}/**", writer: "{party}" }, + { path: "names/*", writer: "tv" }, { path: "names/**", writer: false }]; + const writers = ["home/tv/motd", "home/tv", "home/makefu/motd", "names/r", "names/r/s"] + .map(path => writerAt(rules, ["tv", "lass"], path)); + const version = { federation: 1, number: 0, changes: null, + keys: { tv: { since: 0, keys: ["ssh-ed25519 AAAA1"] }, + lass: { since: 0, keys: ["ssh-ed25519 AAAA2"] } }, + nodes: { tv: { since: 0, nodes: ["continuum:a"] }, lass: { since: 0, nodes: [] } }, + rules }; + const next = { ...version, number: 1, changes: "11", + keys: { ...version.keys, lass: { since: 1, keys: ["ssh-ed25519 AAAA3"] } } }; + state = { node: { id: "continuum:a", alias: "a", party: "tv" }, stats: {}, + peers: { localReaches: [], peers: {} }, graph: { members: {}, intended: {}, measured: {} } }; + federationTimer = 1; + federation.summary = { store: "aa", checkpoint: "aa", heads: ["bb"], taken: 3, + party: "tv", votesByItself: true }; + federation.heads = "bb"; + federation.counts = { version: { number: 0, hash: "11", version }, + parties: { tv: { keys: ["ssh-ed25519 AAAA1"], nodes: ["continuum:a"] }, + lass: { keys: ["ssh-ed25519 AAAA2"], nodes: [] } }, + values: { "home/tv/motd": "hello", "home/tv/hosts/laptop": { ip6: "42::1" } }, + members: [["continuum:a", "tv"]], + proposals: { "22": { proposals: ["cc"], votes: ["dd"], yes: ["tv"], no: [], + passed: false, dead: false } } }; + federation.refused = { own: [], dropped: [], refused: [] }; + federation.versions.set("22", next); + showFederation(); + renderFederation(true); + const tree = document.getElementById("federation"); + return { writers, title: document.getElementById("document-title").textContent, + shown: !document.getElementById("federation-scroll").hidden + && document.getElementById("document-scroll").hidden, + text: tree.textContent, votes: tree.querySelectorAll(".votes button").length }; + }); + check(JSON.stringify(federated.writers) === JSON.stringify(["tv", null, null, "tv", null]), + "who writes at a place is the first rule matching it: " + JSON.stringify(federated.writers)); + check(federated.title === "Federation" && federated.shown, + "in a swarm holding a store, the document box shows the federation"); + check(federated.text.includes("motd: \"hello\" by tv"), "a value, with who writes there"); + check(federated.text.includes("can still pass") && federated.text.includes("number: 0 -> 1") + && federated.text.includes('keys.lass: {"keys":["ssh-ed25519 AAAA2"],"since":0} -> ' + + '{"keys":["ssh-ed25519 AAAA3"],"since":1}'), + "a proposal: where it stands, and what its version changes, party by party"); + check(federated.votes === 2, "a proposal that can still pass has a vote of each kind"); + await tab.waitForTimeout(500); check(errors.length === 0, "no errors on the page" + (errors.length ? ": " + errors : "")); await browser.close(); diff --git a/src/api/dashboard/dashboard.html b/src/api/dashboard/dashboard.html index a20e64c..a918532 100644 --- a/src/api/dashboard/dashboard.html +++ b/src/api/dashboard/dashboard.html @@ -328,6 +328,15 @@ .tree details[open] > summary::before { content: "▾"; } .tree details > .note { padding-left: 1.1em; } .key { color: var(--muted); } + /* The federation (`#federation`): where a proposal stands, its votes, the filter. */ + #federation .standing { font-weight: 600; } + #federation .standing.passed { color: var(--ok); } + #federation .standing.dead { color: var(--bad); } + #federation .leaf { overflow-wrap: anywhere; } + #federation input.filter { width: 100%; box-sizing: border-box; font: inherit; + color: var(--fg); background: var(--bg); border: 1px solid var(--line); + border-radius: 4px; padding: 2px 4px; margin: 2px 0 4px; } + #federation .votes button.toggle { float: none; margin: 2px 6px 2px 0; } /* What a value or key means, after it (`gloss`): an alias, a time, a size. */ .gloss { color: var(--muted); } @@ -387,8 +396,9 @@
-

Document

+

Document