aboutsummaryrefslogtreecommitdiffstats
path: root/docs/guides/federation
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 21:49:18 +0000
committertv <tv@krebsco.de>2026-11-19 22:54:03 +0100
commit4c2a4dfdb88fb008e0ba915047207efb8418ce77 (patch)
tree7d550d6372a7ac38a65c7dea930c9474e949ac6a /docs/guides/federation
parent5aa649bcb366ed6863732dac68ce081bacdbe4a8 (diff)
continuum-party status: everything but the values, in colour, and as JSON
`status` becomes the one place to look (party/status.rs): everything about the federation at the node but the values, which `get` and `values` read. * the store: its ID, checkpoint, heads, what it took, its stop; * the node: its party, whether it votes by itself, the revisions it knows; * the version: number, hash, federation, revision, how many pass a change; * every party: the keys its version names and its key set, --key's marked, and its nodes, each with its name, how long ago the node heard from it, and what it runs (wire versions, newest revision); * every proposal on the current version: how it stands, who voted what and who not yet, who proposed it and what it does (version_lines, as `show` says it), what moving to its checkpoint refuses, why no client backs it; * what the node refused of its own; * the party the client works as: its --key, its record held against the node's votes, what `again` signs again; * the warnings of what may keep votes away (cut_off). It is built as one JSON object (`model`), which `--json` writes, its `format` (FORMAT, 1) raised where it changes otherwise than by more members; what people read is rendered from it (`render`), and may change from release to release. On a terminal, in colour (Paint): true colour where COLORTERM says so, 256 where TERM does, else the basic eight; none with NO_COLOR, TERM=dumb, or off a terminal. What is fine is green, what needs a look yellow, what is wrong red; headings and the shortest prefix naming a proposal bold.
Diffstat (limited to 'docs/guides/federation')
-rw-r--r--docs/guides/federation/watching.md64
1 files changed, 42 insertions, 22 deletions
diff --git a/docs/guides/federation/watching.md b/docs/guides/federation/watching.md
index 8105286..537e42b 100644
--- a/docs/guides/federation/watching.md
+++ b/docs/guides/federation/watching.md
@@ -7,38 +7,58 @@ store, through its API and its log.
## Through the API
-`continuum-party status` says most of what follows at a glance: the store and its
-version, the party's keys and nodes, the node's stop, the proposals on the current version,
-the versions the node refused of its own, and what the party signs again after a move:
+`continuum-party status` says everything about the federation at the node but the values
+(`get`, `values`), with what needs a look in colour on a terminal:
```
store 6d1e8a0c4f2b9d77…
checkpoint 6d1e8a0c4f2b9d77…
3 heads, 120 events taken after the checkpoint
+the node
+ lass's, voting for it by itself
+ knows the base revision, revision 1 (merge-events)
version 3 (a7c2e81b9d0453f6…)
federation 1, the base revision
- 3 parties, 2 passing a change:
- lass
- makefu
- tv
-tv
- keys the version names (votes, proposals, key set, node list):
- ssh-ed25519 SHA256:J1nQ…
- keys of its key set (writes):
- ssh-ed25519 SHA256:pX4c… (--key)
- ssh-ed25519 SHA256:r82M…
- nodes:
- continuum:5be1a3c09f2e4d6b… (alpha)
- continuum:77d0c2e4f6a8b0c2…
-the node: lass's
-1 proposal on version 3 (show says more):
- 8d02f1e3a5c7b9d0…: can still pass, 1 more `true` passing it (2 of 3); true: tv; false: nobody
+ 3 parties, 2 passing a change
+parties
+ lass
+ keys the version names (votes, proposals, key set, node list):
+ ssh-ed25519 SHA256:J1nQ…
+ keys of its key set (writes): the same
+ nodes:
+ continuum:9c07e2a4b6d8f0a1… (beta)
+ this node; wire 52; revision 1 (merge-events)
+ tv
+ keys the version names (votes, proposals, key set, node list):
+ ssh-ed25519 SHA256:pX4c…
+ keys of its key set (writes):
+ ssh-ed25519 SHA256:r82M… (--key)
+ nodes:
+ continuum:5be1a3c09f2e4d6b… (alpha)
+ heard 12 s ago; wire 52; the base revision
+proposals on version 3
+ 8d02f1e3a5c7b9d0…: can still pass, 1 more `true` passing it (2 of 3)
+ true: tv; false: nobody; not yet: lass, makefu
+ proposed by tv: version 4 on 3
+ lets makefu in: 1 key (ssh-ed25519 SHA256:2kq…); 1 node (continuum:e2a8…)
+refused
+ no version event of its own
+you: tv
+ --key ssh-ed25519 SHA256:r82M…: of the key set: writes
+ record tv.record: agrees with the node
```
IDs and hashes are cut short here; the client writes them whole, the shortest prefix
-naming a proposal in bold on a terminal, and keys by their fingerprints. Each node goes
-by the name it gave itself (`--alias`), where it did: `names` of each party in `GET
-/events/counts`; one that gave itself none goes by its ID alone.
+naming a proposal in bold, and keys by their fingerprints. It says of every party's nodes
+the names they gave themselves (`--alias`), how long ago the node heard from each, and
+what each runs (its wire versions and the newest revision it knows: the nodes to upgrade
+before a revision passes); of every proposal how it stands, who voted what and who not
+yet, and what it does, as `show` says it; and of the party it works as (its record's,
+`--party`'s, or else the node's), its `--key`, its record held against the votes the node
+shows, what `again` signs again, and what may keep votes away. What people read may change
+from release to release; `status --json` says the same as one JSON object, whose `format`
+says which: a later release raises it where the object changes otherwise than by more
+members.
* **A version the node refused** (`own` in `GET /events/refused` not empty): keys voted
twice, and nodes may be apart. Act on it at once