summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-19 13:50:25 +0000
committertv <tv@krebsco.de>2026-11-19 14:53:47 +0100
commit7d91c37ec1c606f70ec7a90ce9be4b0aa5c518c4 (patch)
tree9116ed3a2fbc69cba32500d2b8b48f85c6d46c51 /docs
parentc1bf987314774d135316d95480baeb6eb7e1dc70 (diff)
peers: what each peer said it speaks and knows, in GET /peers
GET /peers shows, of each peer, what it said with its handshakes (SPEAKS): its `knows`, the wire versions it speaks, the oldest and the newest, and the newest revision of the federation it knows; null where it said nothing, a build from before SPEAKS or no handshake from it since the node started. `localKnows` is the node's own. So every swarm, federated or not, shows which builds its nodes run, as far as each heard. `swarm::speaking::shown` shapes it, for GET /events/counts too, whose `knows` is the same; docs/openapi.yaml has it once, as `Knows`. Without the federation feature, a revision reads as one this continuum doesn't know. `Speaking::of` is now used in every build, not only federated ones, which warned of it as dead code.
Diffstat (limited to 'docs')
-rw-r--r--docs/openapi.yaml53
-rw-r--r--docs/operations.md3
-rw-r--r--docs/peers.md9
3 files changed, 42 insertions, 23 deletions
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index b1e1e28..4982cac 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1596,23 +1596,9 @@ paths:
knows:
type: object
additionalProperties:
- type: [object, 'null']
- required: [wire, revision]
- properties:
- wire:
- type: array
- items:
- type: integer
- revision:
- type: [object, 'null']
- required: [number, id, named]
- properties:
- number:
- type: [integer, 'null']
- id:
- type: string
- named:
- type: string
+ oneOf:
+ - $ref: '#/components/schemas/Knows'
+ - type: 'null'
values:
type: object
members:
@@ -2700,7 +2686,7 @@ components:
PeerList:
type: object
- required: [localAddresses, localEpoch, localHeads, localReaches, peers]
+ required: [localAddresses, localEpoch, localHeads, localReaches, localKnows, peers]
properties:
localAlias:
type: [string, 'null']
@@ -2719,12 +2705,38 @@ components:
items:
type: string
description: The members this node reaches (an active session with each, answering), by node ID, as it last told its neighbours.
+ localKnows:
+ $ref: '#/components/schemas/Knows'
peers:
type: object
description: By node ID.
additionalProperties:
$ref: '#/components/schemas/Peer'
+ Knows:
+ type: object
+ description: What a node says it speaks and knows (SPEAKS, docs/peers.md), what decides which builds work together.
+ required: [wire, revision]
+ properties:
+ wire:
+ type: array
+ items:
+ type: integer
+ description: The wire versions it speaks, the oldest and the newest.
+ revision:
+ type: [object, 'null']
+ description: The newest revision of the federation it knows; null where it knows none (built without the federation).
+ required: [number, id, named]
+ properties:
+ number:
+ type: [integer, 'null']
+ description: Null where this node doesn't know the revision.
+ id:
+ type: string
+ named:
+ type: string
+ description: As people read it.
+
Peer:
type: object
required: [addresses, status, handshakeComplete, hasPendingDelivery, neighbour, traffic, incidents]
@@ -2828,6 +2840,11 @@ components:
items:
type: string
description: The members it said it reaches, by node ID (those in our member list); null before it said so since its session began (handshake, or back from dormant).
+ knows:
+ oneOf:
+ - $ref: '#/components/schemas/Knows'
+ - type: 'null'
+ description: What it said it speaks and knows with its handshakes (SPEAKS); null where it said nothing, a build from before SPEAKS, or no handshake from it since this node started.
traffic:
$ref: '#/components/schemas/Traffic'
incidents:
diff --git a/docs/operations.md b/docs/operations.md
index 97fee26..f64bc13 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -112,7 +112,8 @@ Before 1.0.0, any release may be a flag day; its tag's message says whether it i
What decides which builds work together, a build says (`-V` the release alone): the wire
versions it speaks, the federation and the revisions of it it knows (with the
`federation` feature), and the Automerge it makes documents with. `continuum-party
---version` says the same.
+--version` says the same. Of the wire versions and the revision, a node tells its peers
+too: each peer's, as far as the node heard, is its `knows` in `GET /peers`.
```sh
continuum --version
diff --git a/docs/peers.md b/docs/peers.md
index d2f822f..34023db 100644
--- a/docs/peers.md
+++ b/docs/peers.md
@@ -99,10 +99,11 @@ Before each HELLO and each HELLO_REPLY, a node sends SPEAKS: the wire versions i
and the newest revision of the federation it knows, as its build has them. It stands
outside the wire versions, laid out as no build changes, so that a peer on another build
reads it too, once that peer reads the node's WHO and ME
-([Node IDs and addresses](#node-ids-and-addresses)): what each peer said shows in `knows`
-of `GET /events/counts`, for the nodes a federated store's parties list. A build from
-before SPEAKS takes it for a message of another wire version, and logs that once of the
-peer ([`operations.md`](operations.md), [Upgrading](operations.md#upgrading)).
+([Node IDs and addresses](#node-ids-and-addresses)): what each peer said shows as its
+`knows` in `GET /peers`, the node's own as `localKnows`, and in `GET /events/counts` for
+the nodes a federated store's parties list. A build from before SPEAKS takes it for a
+message of another wire version, and logs that once of the peer
+([`operations.md`](operations.md), [Upgrading](operations.md#upgrading)).
Every HELLO carries a random id of the sender's current run, and the HELLO_REPLY echoes
it. A reply with another id answers a HELLO from an earlier run (delivered late, or