# 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.