WebSocket gossip mesh with K=6 neighbor selection, peer discovery, routing tables, partition healing, and self-healing topology.
The gossip mesh is the communication backbone of the network. Every node maintains WebSocket connections to a carefully selected set of neighbors, forming an overlay network optimized for low-latency message propagation and partition resistance.
All mesh communication flows over WebSocket connections at the /gossip endpoint. The protocol is binary-framed with typed message envelopes.
Every gossip connection is authenticated on handshake:
"gossip-auth:{timestamp}" using its Ed25519 private keyActive connections send a Ping frame every 20 seconds. The round-trip time (RTT) from each Pong response is recorded and used for:
avgRtt field propagationEach node maintains exactly 6 neighbor connections, selected across three tiers to balance latency, reach, and resilience:
| Tier | Count | Selection Criteria |
|---|---|---|
| Close | 3 | Lowest effective RTT, scored as measuredRtt + hopCount * 50ms |
| Mid-range | 2 | Bridge nodes that connect different clusters in the topology |
| Random | 1 | Random selection from all known peers, rotated periodically |
The 3 close neighbors optimize for speed. The 2 mid-range neighbors ensure messages can cross cluster boundaries efficiently. The 1 random neighbor provides partition healing -- if the network splits, random connections are most likely to bridge the gap.
Nodes discover peers through four mechanisms, tried in order:
/network/discover endpoint for the current list of healthy nodes.Each layer is tried only if the previous layer yielded insufficient peers.
Every 60 seconds, each node sends a peer exchange message to its neighbors containing 20 peers selected as:
This mix ensures high-quality peers propagate quickly while random selection prevents the network from converging on a small set of "popular" nodes.
Every node maintains a routing table with an entry for each known peer:
| Field | Description |
|---|---|
nodeId | 16-byte unique node identifier |
pubkey | Ed25519 public key for signature verification |
wsUrl | WebSocket URL for direct connection |
lastSeenAt | Timestamp of last heartbeat or direct message |
measuredRtt | Directly measured round-trip time (from Ping/Pong) |
reportedRtt | RTT reported by the peer in its heartbeat |
hopCount | Number of hops from this node to the peer |
isNeighbor | Whether this peer is one of the 6 active neighbors |
lastSeenAt is within the last 10 minutesThe rebalancer runs every 5 minutes by default, with adaptive timing between 2-10 minutes based on network stability:
The adaptive interval shortens to 2 minutes when the network is unstable (frequent node departures) and extends to 10 minutes when the topology is stable.
When a neighbor goes offline, the self-healing protocol activates:
If multiple neighbors go offline simultaneously, the node processes them sequentially with the 30-second cooldown between each, then triggers a single full rebalance at the end.