first commit

docs/networking/drive/drive-webrtc/src/peer-manager/topology/super-peer.md

@@ -0,0 +1,78 @@
+# SuperPeerStrategy
+
+## Purpose
+
+The super-peer topology lets well-resourced nodes act as relays for
+the rest of the mesh. Super peers form a full mesh among themselves
+and admit any peer that contacts them; ordinary peers connect only
+to a bounded number of super peers (default 3) and never to each
+other. This dramatically reduces connection count for large meshes
+while preserving multi-hop reachability between every pair of peers.
+
+## Features
+
+- `selfIsSuperPeer` flag switches the admission policy between
+  "accept anyone" and "connect outbound only to super peers".
+- `targetSuperPeers` caps a non-super peer's outbound super-peer
+  connections (default 3).
+- Super peers prefer evicting non-super peers when at capacity so
+  the super-peer backbone stays healthy.
+
+## Usage: Basic Example
+
+```ts
+import { SuperPeerStrategy } from "@suaveplan/drive-webrtc";
+
+const strategy = new SuperPeerStrategy({
+    selfIsSuperPeer: false,
+    superPeerIds: new Set(["sp-1", "sp-2", "sp-3"]),
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { SuperPeerStrategy } from "@suaveplan/drive-webrtc";
+
+const strategy = new SuperPeerStrategy({
+    selfIsSuperPeer: true,
+    superPeerIds: new Set(["sp-1", "sp-2"]),
+    targetSuperPeers: 2,
+});
+
+const decision = strategy.admitOrEvict(currentPeers, newPeer, {
+    maxPeers: 32,
+    selfPeerId: "sp-1",
+    metricsFor: (id) => tracker.get(id),
+});
+```
+
+## API Reference
+
+### `new SuperPeerStrategy(options)`
+
+- `selfIsSuperPeer: boolean`.
+- `superPeerIds: ReadonlySet<string>`.
+- `targetSuperPeers?: number` (default `3`).
+
+### `selectConnections(current, newPeer, options)`
+
+- Super peers: connect to every newcomer up to `maxPeers`.
+- Non-super peers: connect only to peers in `superPeerIds`, up to
+  `targetSuperPeers` simultaneously.
+
+### `admitOrEvict(current, newPeer, options)`
+
+- Super peer self: admit any newcomer; evict lowest-scoring
+  non-super peer when at capacity.
+- Non-super peer self: admit only super peers below
+  `targetSuperPeers`.
+
+## Implementation Notes
+
+- The strategy treats super-peer identity as static configuration.
+  Promoting a peer to super status during runtime requires rebuilding
+  the strategy with an updated `superPeerIds` set.
+- Eviction only targets non-super peers when self is super; the
+  rationale is that super-peer-to-super-peer links carry the most
+  routing traffic and must remain stable.