From 7d91c37ec1c606f70ec7a90ce9be4b0aa5c518c4 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 13:50:25 +0000 Subject: 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. --- docs/openapi.yaml | 53 +++++++++++++++++++++++++++++++++++------------------ docs/operations.md | 3 ++- docs/peers.md | 9 +++++---- 3 files changed, 42 insertions(+), 23 deletions(-) (limited to 'docs') 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 -- cgit v1.3.1