measure 2-hop neighbourhood

2 files changed, 20 insertions, 1 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 8205845..20d2ccc 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -1519,7 +1519,7 @@ components:
 
     PeerList:
       type: object
-      required: [localAddresses, localEpoch, localHeads, peers]
+      required: [localAddresses, localEpoch, localHeads, localReaches, peers]
       properties:
         localAlias:
           type: [string, 'null']
@@ -1533,6 +1533,11 @@ components:
         localHeads:
           type: integer
           description: 'Heads of the local document (more than one: concurrent changes not yet merged).'
+        localReaches:
+          type: array
+          items:
+            type: string
+          description: The members this node reaches (an active session with each), by node ID, as it last told its neighbours.
         peers:
           type: object
           description: By node ID.
@@ -1630,6 +1635,11 @@ components:
         neighbour:
           type: boolean
           description: We keep it alive and sync with it on our own; other peers we only answer.
+        reaches:
+          type: [array, 'null']
+          items:
+            type: string
+          description: The members it said it reaches, by node ID (those in our member list); null before it said so, or once that is stale.
         traffic:
           $ref: '#/components/schemas/Traffic'
         incidents:
diff --git a/docs/peers.md b/docs/peers.md
index c0e574d..763f6aa 100644
--- a/docs/peers.md
+++ b/docs/peers.md
@@ -304,6 +304,15 @@ every member the writer's neighbour, but the writer may reach fewer of them (one
 NAT may reach a single one, one on libp2p alone none on Tor alone), and no node can tell
 which from where it is. A neighbour that has the changes already only answers.
 
+Every node tells its neighbours whom it reaches ([`swarm/reach.rs`](../src/swarm/reach.rs)): the members it
+has an active session with (handshake done, neither dormant nor unreachable), each by
+an 8-byte key (the hash its pair scores come from), in its keepalive STATUSes and
+their replies, and within 5 s when it changed; not in announcements of heads, which go
+often. So every node knows its 2-hop neighbourhood as measured, not as the member list
+says, for as long as it is fresh (two STATUS refreshes and a keepalive: 7 minutes with
+the default keepalive), and nothing goes into the document. `GET /peers` shows it
+(`localReaches`, and `reaches` per peer).
+
 ## Keepalive and self-healing
 
 ```mermaid