Add

modules/hyperswarm.md

@@ -1,39 +1,131 @@
-# Hyperswarm - Topic Swarming
+# Hyperswarm - Core Swarm Library (holepunchto/hyperswarm)
 
-## Expansion: Client/Server Modes
+Latest version: **4.16.0** (main branch)
 
-Hyperswarm: High-level DHT wrapper for bidirectional conns.
+GitHub: [holepunchto/hyperswarm](https://github.com/holepunchto/hyperswarm) (~1.2k stars)
+Docs: [docs.pears.com/building-blocks/hyperswarm](https://docs.pears.com/building-blocks/hyperswarm)
+NPM: `npm install hyperswarm`
 
-**Modes**: {server:true} announce, {client:true} lookup.
+## Overview
+High-level API for topic-based peer discovery and bidirectional connections over HyperDHT.
+- **Topics**: 32-byte Buffers.
+- **Modes**: `server: true` (announce/accept), `client: true` (lookup/connect).
+- **Features**: Firewall, suspend/resume (mobile/battery), direct peer join, stats.
+- **Scale**: 10k+ peers possible with firewall (from prior notes).
 
-**Firewall**: fn(conn) => reject.
+## Package.json Diags
+| Dependency | Version |
+|------------|---------|
+| hyperdht | ^6.21.0 |
+| b4a | ^1.3.1 |
+| bare-events | ^2.2.0 |
+| safety-catch | ^1.0.2 |
+| shuffled-priority-queue | ^2.1.0 |
+| streamx | ^2.22.1 |
+| unslab | ^1.3.0 |
 
-**Suspend**: Battery/mobile pause.
+Dev: brittle, lunte, etc.
 
-## Advanced Ex
+## Constructor Options
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| keyPair | NoiseKeyPair | new | DHT keypair |
+| seed | Buffer(32) | null | Deterministic keypair seed |
+| maxPeers | number | 64 | Max peer conns |
+| firewall | fn(pubKey)→bool | allow all | Reject conn if true |
+| dht | HyperDHT | new | Custom DHT |
+| maxParallel | number | 3 | Concurrent conns |
+| ... | | | See README |
 
+**Source consts**: MAX_PEERS=64, MAX_PARALLEL=3, MAX_CLIENT_CONNECTIONS=∞
+
+## Properties
+| Property | Type | Description |
+|----------|------|-------------|
+| connecting | number | In-progress conns |
+| connections | Set | Active sockets |
+| peers | Map<hexPubKey, PeerInfo> | Connected peers |
+| dht | HyperDHT | Underlying DHT |
+
+## Events
+| Event | Args | Description |
+|-------|------|-------------|
+| connection | (socket, peerInfo) | New encrypted conn |
+| update | () | State changed (connecting, conns) |
+| ban | (peerInfo, err) | Peer banned (firewall etc.) |
+
+## Key Methods
 ```js
-const swarm = new Hyperswarm({
-  firewall(conn) { return conn.remotePublicKey.equals(trusted) }
-})
-
-swarm.join(topic, { client: true, server: true })
-swarm.on('connection', (conn, info) => {
-  conn.pipe(protomuxServer()).pipe(conn)
-})
-
-swarm.flush().then(() => console.log('Discovery cycle done'))
+const swarm = new Hyperswarm()
+const disc = swarm.join(topic, { server: true, client: true })
+await disc.flushed()  // Announce done
+await swarm.flush()   // All pending conns
+await swarm.suspend() // Pause
 ```
 
-**Status**:
+| Method | Returns | Notes |
+|--------|---------|-------|
+| join(topic, opts) | PeerDiscovery | Join topic |
+| leave(topic) | Promise | Stop discovery/announce |
+| joinPeer(pubKey) | void | Direct conn to peer |
+| leavePeer(pubKey) | void | Stop direct attempts |
+| flush() | Promise<bool> | Await DHT + conns |
+| listen() | Promise | Start server |
+| status(topic) | PeerDiscovery \| null | Get discovery |
+| destroy() | Promise | Cleanup |
 
-- peers.size
-- reliablePeers (persistent)
+## PeerDiscovery API
+| Method | Notes |
+|--------|-------|
+| flushed() | Await announce |
+| refresh({client,server}) | Toggle modes, reannounce |
+| destroy() | Leave |
 
-**Tools**: hyperswarm-doctor JSON dump.
+## PeerInfo API
+| Property/Method | Type | Notes |
+|-----------------|------|-------|
+| publicKey | Buffer(32) | Noise pubkey |
+| topics | Buffer[] | Associated topics (client only) |
+| prioritized | bool | Fast reconnect |
+| ban(banned?:bool) | void | Ban/unban |
 
-**Scale**: 10k+ peers ok w/ firewall.
+## Examples
 
-**Inter**: Hypercore.replicate(conn), HRPC.
+### Basic (from example.js)
+```js
+const Hyperswarm = require('hyperswarm')
+const swarm1 = new Hyperswarm({ seed: Buffer.alloc(32).fill(4) })
+const swarm2 = new Hyperswarm({ seed: Buffer.alloc(32).fill(5) })
 
-~1500 chars added.
+swarm1.on('connection', (conn) => { /* server */ })
+swarm2.on('connection', (conn) => { /* client */ })
+
+const topic = Buffer.alloc(32).fill(7)
+const disc1 = swarm1.join(topic)
+await disc1.flushed()
+swarm2.join(topic)
+```
+
+### Advanced Firewall + Protomux
+```js
+const swarm = new Hyperswarm({
+  firewall(conn) { return !conn.remotePublicKey.equals(trustedKey) }
+})
+swarm.join(topic, { client: true, server: true })
+swarm.on('connection', (conn, info) => {
+  const mux = conn.pipe(protomux()).pipe(conn)  // HRPC etc.
+})
+await swarm.flush()
+```
+
+## Diagnostics & Tools
+- **Runtime**: `swarm.stats` (connects.client.opened/closed/attempted, server.*, bannedPeers, updates)
+- **hyperswarm-doctor**: `npm i -g @hyperswarm/doctor`
+  - `hyperswarm-doctor` : JSON dump
+  - `--server` : Test server
+  - `--client=pubkey` : Test client
+- **Source**: RetryTimer, shuffled-priority-queue for peer queueing. Errors: ERR_FIREWALL, etc.
+
+**Note**: Git clone failed (network?); used GitHub raw fetches. Repo structure: lib/ (core), index.js (main), test/.
+
+~5000+ chars added. Core lib documented with tables/code/diags.