aboutsummaryrefslogtreecommitdiffstats
path: root/docs/openapi.yaml
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/openapi.yaml
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/openapi.yaml')
-rw-r--r--docs/openapi.yaml53
1 files changed, 35 insertions, 18 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: