peerpigeon 0.1.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +141 -1365
- package/cli.js +1382 -0
- package/dist/peerpigeon-browser.js +12290 -0
- package/dist/peerpigeon-browser.js.map +7 -0
- package/docs/API_DOCUMENTATION.md +1945 -0
- package/docs/BOOTSTRAP_HUBS.md +319 -0
- package/docs/CLI_README.md +371 -0
- package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
- package/docs/HUB_QUICK_REF.md +107 -0
- package/docs/HUB_SCRIPTS.md +331 -0
- package/docs/HUB_SYSTEM.md +552 -0
- package/docs/MIGRATION_COMPLETE.md +93 -0
- package/docs/NETWORK_NAMESPACES.md +212 -0
- package/docs/README.md +107 -0
- package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
- package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
- package/examples/bootstrap-hub-example.js +292 -0
- package/examples/browser/README.md +278 -0
- package/examples/browser/app.js +2426 -49
- package/examples/browser/index.html +482 -543
- package/examples/browser/minimal/README.md +55 -0
- package/examples/browser/minimal/index.html +75 -0
- package/examples/browser/minimal/minimal.js +234 -0
- package/examples/browser/styles.css +687 -1425
- package/examples/browser/test-bundle.html +35 -0
- package/examples/browser-2/index.html +30 -0
- package/examples/browser-2/package.json +21 -0
- package/examples/browser-2/src/App-simple.vue +21 -0
- package/examples/browser-2/src/App.vue +420 -0
- package/examples/browser-2/src/components/CryptoView.vue +1661 -0
- package/examples/browser-2/src/components/DHTView.vue +1281 -0
- package/examples/browser-2/src/components/DebugView.vue +1773 -0
- package/examples/browser-2/src/components/MediaView.vue +1048 -0
- package/examples/browser-2/src/components/MessagingView.vue +775 -0
- package/examples/browser-2/src/components/NetworkView.vue +930 -0
- package/examples/browser-2/src/components/StorageView.vue +1376 -0
- package/examples/browser-2/src/main.js +5 -0
- package/examples/browser-2/src/stores/peerpigeon.js +895 -0
- package/examples/browser-2/vite.config.js +6 -0
- package/examples/hub-example.js +186 -0
- package/examples/multi-hub-test.js +186 -0
- package/examples/node/README.md +2 -2
- package/examples/node/storage-test.js +141 -6
- package/examples/selective-streaming-demo.html +698 -0
- package/examples/standard-events-demo.js +126 -0
- package/package.json +33 -16
- package/server/index.js +1032 -98
- package/server/start.js +49 -0
- package/src/ConnectionManager.js +239 -225
- package/src/CryptoManager.js +147 -18
- package/src/DebugLogger.js +0 -7
- package/src/DistributedStorageManager.js +245 -205
- package/src/EnvironmentDetector.js +109 -2
- package/src/EventEmitter.js +79 -1
- package/src/EvictionManager.js +10 -9
- package/src/GossipManager.js +163 -11
- package/src/LexicalStorageInterface.js +332 -0
- package/src/PeerConnection.js +333 -310
- package/src/PeerPigeonMesh.js +577 -135
- package/src/SignalingClient.js +14 -243
- package/src/SignalingHandler.js +31 -10
- package/src/StorageManager.js +0 -39
- package/src/WebDHT-Simple.js +389 -0
- package/src/WebDHT.js +363 -1165
- package/src/browser-entry.js +40 -0
- package/examples/browser/assets/images/favicon.png +0 -0
- package/examples/browser/assets/images/pigeon.png +0 -0
- package/examples/browser/crypto-test.html +0 -427
- package/examples/browser/ui-old.js +0 -1926
- package/examples/browser/ui.js +0 -3010
- package/websocket-server/README.md +0 -247
- package/websocket-server/server.js +0 -391
|
@@ -0,0 +1,552 @@
|
|
|
1
|
+
# PeerPigeon Hub System
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
PeerPigeon supports a hub system where certain nodes can act as **hubs** - long-standing servers that form their own mesh network while also serving regular peers. This creates a hybrid architecture that combines the benefits of centralized coordination with peer-to-peer connectivity.
|
|
6
|
+
|
|
7
|
+
## What are Hubs?
|
|
8
|
+
|
|
9
|
+
**Hubs** are special peers that:
|
|
10
|
+
- Run as persistent servers (not browser-based clients)
|
|
11
|
+
- Connect to each other on a reserved namespace called `pigeonhub-mesh`
|
|
12
|
+
- Still serve regular peers in their application networks
|
|
13
|
+
- Can be identified and tracked separately from regular peers
|
|
14
|
+
- Provide enhanced stability and routing for the mesh network
|
|
15
|
+
|
|
16
|
+
**Regular Peers** are:
|
|
17
|
+
- Typically browser clients or mobile apps
|
|
18
|
+
- Connect on application-specific networks (e.g., 'my-app-network')
|
|
19
|
+
- Can discover and connect to both hubs and other regular peers
|
|
20
|
+
- May have shorter lifespans (users opening/closing apps)
|
|
21
|
+
|
|
22
|
+
## Architecture
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
26
|
+
│ Signaling Server │
|
|
27
|
+
│ • Tracks both hubs and regular peers │
|
|
28
|
+
│ • Routes signaling messages │
|
|
29
|
+
│ • Maintains network namespaces │
|
|
30
|
+
└─────────────────────────────────────────────────────────────┘
|
|
31
|
+
│
|
|
32
|
+
┌───────────────────┼───────────────────┐
|
|
33
|
+
│ │ │
|
|
34
|
+
[Hub A] [Hub B] [Hub C]
|
|
35
|
+
(pigeonhub-mesh) (pigeonhub-mesh) (pigeonhub-mesh)
|
|
36
|
+
│ │ │
|
|
37
|
+
┌───┴───┐ ┌───┴───┐ ┌────┴────┐
|
|
38
|
+
[Peer 1][Peer 2] [Peer 3][Peer 4] [Peer 5][Peer 6]
|
|
39
|
+
(app-net) (app-net) (app-net)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Hub Namespace: `pigeonhub-mesh`
|
|
43
|
+
|
|
44
|
+
The `pigeonhub-mesh` namespace is reserved for hub-to-hub connections. When a hub announces on this namespace:
|
|
45
|
+
|
|
46
|
+
1. The signaling server identifies it as a hub
|
|
47
|
+
2. It's registered in the hub registry
|
|
48
|
+
3. It receives a list of all other connected hubs
|
|
49
|
+
4. Other hubs are notified about this new hub
|
|
50
|
+
5. Hubs can then establish WebRTC connections to each other
|
|
51
|
+
|
|
52
|
+
## Server Configuration
|
|
53
|
+
|
|
54
|
+
### Creating a Hub Server
|
|
55
|
+
|
|
56
|
+
```javascript
|
|
57
|
+
import { PeerPigeonServer } from './server/index.js';
|
|
58
|
+
|
|
59
|
+
const hubServer = new PeerPigeonServer({
|
|
60
|
+
port: 3000,
|
|
61
|
+
host: 'localhost',
|
|
62
|
+
isHub: true, // Mark this server as a hub
|
|
63
|
+
maxConnections: 1000,
|
|
64
|
+
cleanupInterval: 30000
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
// Listen for hub events
|
|
68
|
+
hubServer.on('hubRegistered', ({ peerId, totalHubs }) => {
|
|
69
|
+
console.log(`New hub registered: ${peerId}, Total: ${totalHubs}`);
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
hubServer.on('hubUnregistered', ({ peerId, totalHubs }) => {
|
|
73
|
+
console.log(`Hub unregistered: ${peerId}, Remaining: ${totalHubs}`);
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
await hubServer.start();
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Creating a Regular Server
|
|
80
|
+
|
|
81
|
+
```javascript
|
|
82
|
+
const regularServer = new PeerPigeonServer({
|
|
83
|
+
port: 3001,
|
|
84
|
+
host: 'localhost',
|
|
85
|
+
isHub: false, // Regular signaling server (default)
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
await regularServer.start();
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Bootstrap Hub Configuration
|
|
92
|
+
|
|
93
|
+
**Bootstrap hubs** allow hubs to automatically connect to each other, forming a hub mesh network without manual WebRTC connection setup.
|
|
94
|
+
|
|
95
|
+
### How Bootstrap Hubs Work
|
|
96
|
+
|
|
97
|
+
1. A primary hub runs on port 3000 (default) as the bootstrap hub
|
|
98
|
+
2. Secondary hubs automatically connect to the bootstrap hub when they start
|
|
99
|
+
3. Through the bootstrap hub, all hubs discover each other
|
|
100
|
+
4. Hubs can then establish WebRTC connections to create a mesh network
|
|
101
|
+
|
|
102
|
+
### Creating a Bootstrap Hub (Primary)
|
|
103
|
+
|
|
104
|
+
```javascript
|
|
105
|
+
const bootstrapHub = new PeerPigeonServer({
|
|
106
|
+
port: 3000,
|
|
107
|
+
host: 'localhost',
|
|
108
|
+
isHub: true,
|
|
109
|
+
autoConnect: false // Don't connect to other hubs (this IS the bootstrap)
|
|
110
|
+
});
|
|
111
|
+
|
|
112
|
+
await bootstrapHub.start();
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Creating a Hub that Auto-Connects to Bootstrap
|
|
116
|
+
|
|
117
|
+
```javascript
|
|
118
|
+
const secondaryHub = new PeerPigeonServer({
|
|
119
|
+
port: 3001,
|
|
120
|
+
host: 'localhost',
|
|
121
|
+
isHub: true,
|
|
122
|
+
autoConnect: true // Automatically connects to ws://localhost:3000
|
|
123
|
+
});
|
|
124
|
+
|
|
125
|
+
// Listen for bootstrap connection events
|
|
126
|
+
secondaryHub.on('bootstrapConnected', ({ uri }) => {
|
|
127
|
+
console.log(`Connected to bootstrap hub: ${uri}`);
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
secondaryHub.on('bootstrapDisconnected', ({ uri }) => {
|
|
131
|
+
console.log(`Disconnected from bootstrap hub: ${uri}`);
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
secondaryHub.on('hubDiscovered', ({ peerId, via }) => {
|
|
135
|
+
console.log(`Discovered hub ${peerId} via ${via}`);
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
await secondaryHub.start();
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Custom Bootstrap Hub URIs
|
|
142
|
+
|
|
143
|
+
```javascript
|
|
144
|
+
const hub = new PeerPigeonServer({
|
|
145
|
+
port: 3002,
|
|
146
|
+
isHub: true,
|
|
147
|
+
bootstrapHubs: [
|
|
148
|
+
'ws://hub1.example.com:3000',
|
|
149
|
+
'ws://hub2.example.com:3000'
|
|
150
|
+
],
|
|
151
|
+
reconnectInterval: 5000, // Reconnect after 5 seconds
|
|
152
|
+
maxReconnectAttempts: 10 // Try up to 10 times
|
|
153
|
+
});
|
|
154
|
+
|
|
155
|
+
await hub.start();
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Bootstrap Configuration Options
|
|
159
|
+
|
|
160
|
+
| Option | Type | Default | Description |
|
|
161
|
+
|--------|------|---------|-------------|
|
|
162
|
+
| `bootstrapHubs` | `string[]` | `[]` | Array of bootstrap hub URIs to connect to |
|
|
163
|
+
| `autoConnect` | `boolean` | `true` | Automatically connect to bootstrap hubs on start |
|
|
164
|
+
| `reconnectInterval` | `number` | `5000` | Milliseconds to wait before reconnection attempt |
|
|
165
|
+
| `maxReconnectAttempts` | `number` | `10` | Maximum number of reconnection attempts |
|
|
166
|
+
| `hubPeerId` | `string` | auto-generated | Custom peer ID for this hub |
|
|
167
|
+
|
|
168
|
+
### Bootstrap Hub Network Topology
|
|
169
|
+
|
|
170
|
+
```
|
|
171
|
+
Bootstrap Hub (3000)
|
|
172
|
+
↑
|
|
173
|
+
├── Hub 1 (3001)
|
|
174
|
+
├── Hub 2 (3002)
|
|
175
|
+
└── Hub 3 (3003)
|
|
176
|
+
|
|
177
|
+
All hubs discover each other through the bootstrap hub
|
|
178
|
+
and can establish direct WebRTC connections.
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Redundant Bootstrap Hubs
|
|
182
|
+
|
|
183
|
+
For high availability, you can configure multiple bootstrap hubs:
|
|
184
|
+
|
|
185
|
+
```javascript
|
|
186
|
+
const hub = new PeerPigeonServer({
|
|
187
|
+
port: 3005,
|
|
188
|
+
isHub: true,
|
|
189
|
+
bootstrapHubs: [
|
|
190
|
+
'ws://bootstrap1.example.com:3000',
|
|
191
|
+
'ws://bootstrap2.example.com:3000',
|
|
192
|
+
'ws://bootstrap3.example.com:3000'
|
|
193
|
+
]
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
await hub.start();
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
If one bootstrap hub goes down, the hub maintains connections to the others.
|
|
200
|
+
|
|
201
|
+
## Client-Side Usage
|
|
202
|
+
|
|
203
|
+
### Announcing as a Hub
|
|
204
|
+
|
|
205
|
+
When a hub client connects to the signaling server:
|
|
206
|
+
|
|
207
|
+
```javascript
|
|
208
|
+
// Connect to signaling server
|
|
209
|
+
const ws = new WebSocket('ws://localhost:3000?peerId=' + myPeerId);
|
|
210
|
+
|
|
211
|
+
// Announce as a hub on the hub mesh namespace
|
|
212
|
+
ws.send(JSON.stringify({
|
|
213
|
+
type: 'announce',
|
|
214
|
+
networkName: 'pigeonhub-mesh', // Reserved hub namespace
|
|
215
|
+
data: {
|
|
216
|
+
isHub: true, // Identify as a hub
|
|
217
|
+
hubVersion: '1.0.0',
|
|
218
|
+
capabilities: ['signaling', 'relay', 'storage'],
|
|
219
|
+
region: 'us-east-1'
|
|
220
|
+
}
|
|
221
|
+
}));
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### Announcing as a Regular Peer
|
|
225
|
+
|
|
226
|
+
```javascript
|
|
227
|
+
// Regular peer announcement
|
|
228
|
+
ws.send(JSON.stringify({
|
|
229
|
+
type: 'announce',
|
|
230
|
+
networkName: 'my-app-network', // Application-specific network
|
|
231
|
+
data: {
|
|
232
|
+
isHub: false, // Or omit this field
|
|
233
|
+
peerType: 'browser',
|
|
234
|
+
capabilities: ['messaging', 'video']
|
|
235
|
+
}
|
|
236
|
+
}));
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## Hub Discovery
|
|
240
|
+
|
|
241
|
+
When a hub announces, it automatically receives information about other hubs:
|
|
242
|
+
|
|
243
|
+
```javascript
|
|
244
|
+
ws.addEventListener('message', (event) => {
|
|
245
|
+
const message = JSON.parse(event.data);
|
|
246
|
+
|
|
247
|
+
if (message.type === 'peer-discovered') {
|
|
248
|
+
const { peerId, isHub, ...otherData } = message.data;
|
|
249
|
+
|
|
250
|
+
if (isHub) {
|
|
251
|
+
console.log(`Discovered hub: ${peerId}`);
|
|
252
|
+
// Initiate WebRTC connection to this hub
|
|
253
|
+
connectToHub(peerId);
|
|
254
|
+
} else {
|
|
255
|
+
console.log(`Discovered regular peer: ${peerId}`);
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
});
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
## API Methods
|
|
262
|
+
|
|
263
|
+
### Server Methods
|
|
264
|
+
|
|
265
|
+
#### `isPeerHub(peerId)`
|
|
266
|
+
Check if a connected peer is registered as a hub.
|
|
267
|
+
|
|
268
|
+
```javascript
|
|
269
|
+
if (server.isPeerHub(somePeerId)) {
|
|
270
|
+
console.log('This peer is a hub');
|
|
271
|
+
}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
#### `registerHub(peerId, hubInfo)`
|
|
275
|
+
Manually register a peer as a hub (usually done automatically).
|
|
276
|
+
|
|
277
|
+
```javascript
|
|
278
|
+
server.registerHub(peerId, {
|
|
279
|
+
region: 'us-west-2',
|
|
280
|
+
capabilities: ['relay']
|
|
281
|
+
});
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
#### `unregisterHub(peerId)`
|
|
285
|
+
Unregister a hub (usually done automatically on disconnect).
|
|
286
|
+
|
|
287
|
+
```javascript
|
|
288
|
+
server.unregisterHub(peerId);
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
#### `getConnectedHubs(excludePeerId)`
|
|
292
|
+
Get a list of all connected hubs.
|
|
293
|
+
|
|
294
|
+
```javascript
|
|
295
|
+
const hubs = server.getConnectedHubs();
|
|
296
|
+
hubs.forEach(hub => {
|
|
297
|
+
console.log(`Hub: ${hub.peerId}, Network: ${hub.networkName}`);
|
|
298
|
+
});
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
#### `getStats()`
|
|
302
|
+
Get server statistics including hub count.
|
|
303
|
+
|
|
304
|
+
```javascript
|
|
305
|
+
const stats = server.getStats();
|
|
306
|
+
console.log(`Total hubs: ${stats.hubs}`);
|
|
307
|
+
console.log(`Total peers: ${stats.peers}`);
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
#### `getHubStats()`
|
|
311
|
+
Get detailed hub statistics including bootstrap connections.
|
|
312
|
+
|
|
313
|
+
```javascript
|
|
314
|
+
const hubStats = server.getHubStats();
|
|
315
|
+
console.log(`Connected hubs: ${hubStats.connectedHubs}`);
|
|
316
|
+
console.log('Hub list:', hubStats.hubs);
|
|
317
|
+
console.log('Bootstrap hubs:', hubStats.bootstrapHubs);
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
#### `connectToBootstrapHubs()`
|
|
321
|
+
Manually trigger connection to bootstrap hubs (usually done automatically on start).
|
|
322
|
+
|
|
323
|
+
```javascript
|
|
324
|
+
await server.connectToBootstrapHubs();
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
#### `connectToHub(uri, attemptNumber)`
|
|
328
|
+
Connect to a specific hub URI.
|
|
329
|
+
|
|
330
|
+
```javascript
|
|
331
|
+
await server.connectToHub('ws://hub.example.com:3000');
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
#### `disconnectFromBootstrapHubs()`
|
|
335
|
+
Disconnect from all bootstrap hubs.
|
|
336
|
+
|
|
337
|
+
```javascript
|
|
338
|
+
server.disconnectFromBootstrapHubs();
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
#### `generatePeerId()`
|
|
342
|
+
Generate a random 40-character hex peer ID.
|
|
343
|
+
|
|
344
|
+
```javascript
|
|
345
|
+
const peerId = server.generatePeerId();
|
|
346
|
+
console.log(`Generated peer ID: ${peerId}`);
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
## HTTP Endpoints
|
|
350
|
+
|
|
351
|
+
### `/health`
|
|
352
|
+
Health check endpoint with hub information.
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
curl http://localhost:3000/health
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Response:
|
|
359
|
+
```json
|
|
360
|
+
{
|
|
361
|
+
"status": "healthy",
|
|
362
|
+
"timestamp": "2025-10-03T12:00:00.000Z",
|
|
363
|
+
"uptime": 3600,
|
|
364
|
+
"isHub": true,
|
|
365
|
+
"connections": 50,
|
|
366
|
+
"peers": 48,
|
|
367
|
+
"hubs": 2,
|
|
368
|
+
"networks": 3,
|
|
369
|
+
"memory": {...}
|
|
370
|
+
}
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
### `/hubs`
|
|
374
|
+
List all connected hubs.
|
|
375
|
+
|
|
376
|
+
```bash
|
|
377
|
+
curl http://localhost:3000/hubs
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
Response:
|
|
381
|
+
```json
|
|
382
|
+
{
|
|
383
|
+
"timestamp": "2025-10-03T12:00:00.000Z",
|
|
384
|
+
"totalHubs": 3,
|
|
385
|
+
"hubs": [
|
|
386
|
+
{
|
|
387
|
+
"peerId": "abc123...",
|
|
388
|
+
"networkName": "pigeonhub-mesh",
|
|
389
|
+
"registeredAt": 1696334400000,
|
|
390
|
+
"lastActivity": 1696334500000
|
|
391
|
+
}
|
|
392
|
+
]
|
|
393
|
+
}
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
## Events
|
|
397
|
+
|
|
398
|
+
### Server Events
|
|
399
|
+
|
|
400
|
+
#### `hubRegistered`
|
|
401
|
+
Emitted when a new hub is registered.
|
|
402
|
+
|
|
403
|
+
```javascript
|
|
404
|
+
server.on('hubRegistered', ({ peerId, totalHubs }) => {
|
|
405
|
+
console.log(`Hub ${peerId} registered. Total: ${totalHubs}`);
|
|
406
|
+
});
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
#### `hubUnregistered`
|
|
410
|
+
Emitted when a hub is unregistered.
|
|
411
|
+
|
|
412
|
+
```javascript
|
|
413
|
+
server.on('hubUnregistered', ({ peerId, totalHubs }) => {
|
|
414
|
+
console.log(`Hub ${peerId} unregistered. Remaining: ${totalHubs}`);
|
|
415
|
+
});
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
#### `peerAnnounced`
|
|
419
|
+
Emitted when any peer announces (includes `isHub` flag).
|
|
420
|
+
|
|
421
|
+
```javascript
|
|
422
|
+
server.on('peerAnnounced', ({ peerId, networkName, isHub }) => {
|
|
423
|
+
if (isHub) {
|
|
424
|
+
console.log(`Hub announced: ${peerId} on ${networkName}`);
|
|
425
|
+
}
|
|
426
|
+
});
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
#### `bootstrapConnected`
|
|
430
|
+
Emitted when successfully connected to a bootstrap hub.
|
|
431
|
+
|
|
432
|
+
```javascript
|
|
433
|
+
server.on('bootstrapConnected', ({ uri }) => {
|
|
434
|
+
console.log(`Connected to bootstrap hub: ${uri}`);
|
|
435
|
+
});
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
#### `bootstrapDisconnected`
|
|
439
|
+
Emitted when disconnected from a bootstrap hub.
|
|
440
|
+
|
|
441
|
+
```javascript
|
|
442
|
+
server.on('bootstrapDisconnected', ({ uri, code, reason }) => {
|
|
443
|
+
console.log(`Disconnected from ${uri}: ${code} - ${reason}`);
|
|
444
|
+
});
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
#### `hubDiscovered`
|
|
448
|
+
Emitted when another hub is discovered through a bootstrap connection.
|
|
449
|
+
|
|
450
|
+
```javascript
|
|
451
|
+
server.on('hubDiscovered', ({ peerId, via, data }) => {
|
|
452
|
+
console.log(`Discovered hub ${peerId} via ${via}`);
|
|
453
|
+
});
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
#### `bootstrapSignaling`
|
|
457
|
+
Emitted when WebRTC signaling messages are received from a bootstrap hub.
|
|
458
|
+
|
|
459
|
+
```javascript
|
|
460
|
+
server.on('bootstrapSignaling', ({ type, data, fromPeerId, uri }) => {
|
|
461
|
+
console.log(`Received ${type} from ${fromPeerId} via ${uri}`);
|
|
462
|
+
});
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
## Use Cases
|
|
466
|
+
|
|
467
|
+
### 1. Geographic Distribution
|
|
468
|
+
Deploy hubs in different regions that connect to each other, with local peers connecting to their nearest hub.
|
|
469
|
+
|
|
470
|
+
```
|
|
471
|
+
Hub-US-East ←→ Hub-US-West ←→ Hub-Europe
|
|
472
|
+
↓ ↓ ↓
|
|
473
|
+
[Peers] [Peers] [Peers]
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
### 2. Redundancy
|
|
477
|
+
Multiple hubs provide redundancy - if one hub goes down, peers can connect to another hub.
|
|
478
|
+
|
|
479
|
+
### 3. Load Balancing
|
|
480
|
+
Distribute peers across multiple hubs to balance load and improve performance.
|
|
481
|
+
|
|
482
|
+
### 4. Hierarchical Mesh
|
|
483
|
+
Create a two-tier mesh where hubs maintain a stable backbone network and peers connect locally.
|
|
484
|
+
|
|
485
|
+
## Best Practices
|
|
486
|
+
|
|
487
|
+
1. **Run hubs on reliable infrastructure** - Use dedicated servers, not browser clients
|
|
488
|
+
2. **Use meaningful hub identifiers** - Include region, purpose, or capabilities in hub data
|
|
489
|
+
3. **Monitor hub health** - Use the `/health` and `/hubs` endpoints for monitoring
|
|
490
|
+
4. **Implement hub failover** - Peers should be able to reconnect to a different hub
|
|
491
|
+
5. **Separate hub and peer networks** - Hubs use `pigeonhub-mesh`, peers use app-specific names
|
|
492
|
+
6. **Track hub statistics** - Use events and stats methods to monitor hub activity
|
|
493
|
+
|
|
494
|
+
## Security Considerations
|
|
495
|
+
|
|
496
|
+
- Validate hub announcements to prevent unauthorized hub registration
|
|
497
|
+
- Consider authentication for hub-to-hub connections
|
|
498
|
+
- Monitor for malicious hubs attempting to disrupt the network
|
|
499
|
+
- Implement rate limiting for hub registrations
|
|
500
|
+
- Use secure WebSocket connections (wss://) in production
|
|
501
|
+
|
|
502
|
+
## Migration Guide
|
|
503
|
+
|
|
504
|
+
If you have an existing PeerPigeon deployment:
|
|
505
|
+
|
|
506
|
+
1. Update your signaling server to the latest version
|
|
507
|
+
2. Identify which nodes should be hubs (usually long-running servers)
|
|
508
|
+
3. Configure those nodes with `isHub: true`
|
|
509
|
+
4. Have hub clients announce on `pigeonhub-mesh`
|
|
510
|
+
5. Regular peers continue using their existing network names
|
|
511
|
+
6. No changes needed to peer-to-peer communication
|
|
512
|
+
|
|
513
|
+
## Example Deployment
|
|
514
|
+
|
|
515
|
+
```bash
|
|
516
|
+
# Hub Server 1 (US East)
|
|
517
|
+
PORT=3000 REGION=us-east node hub-server.js
|
|
518
|
+
|
|
519
|
+
# Hub Server 2 (US West)
|
|
520
|
+
PORT=3001 REGION=us-west node hub-server.js
|
|
521
|
+
|
|
522
|
+
# Hub Server 3 (Europe)
|
|
523
|
+
PORT=3002 REGION=eu-west node hub-server.js
|
|
524
|
+
|
|
525
|
+
# Signaling Server (monitors all hubs)
|
|
526
|
+
PORT=8080 node signaling-server.js
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
## Troubleshooting
|
|
530
|
+
|
|
531
|
+
### Hubs not connecting to each other
|
|
532
|
+
|
|
533
|
+
- Verify hubs are announcing on `pigeonhub-mesh` namespace
|
|
534
|
+
- Check that `isHub: true` is included in announcement data
|
|
535
|
+
- Verify WebRTC connectivity between hubs
|
|
536
|
+
- Check firewall rules for hub-to-hub communication
|
|
537
|
+
|
|
538
|
+
### Hub not registered on server
|
|
539
|
+
|
|
540
|
+
- Ensure hub announces after connecting
|
|
541
|
+
- Verify announcement message includes `isHub: true` or uses `pigeonhub-mesh`
|
|
542
|
+
- Check server logs for registration confirmation
|
|
543
|
+
|
|
544
|
+
### Regular peers connecting to hub namespace
|
|
545
|
+
|
|
546
|
+
- Peers should NOT use `pigeonhub-mesh` as their network name
|
|
547
|
+
- Use application-specific network names for regular peers
|
|
548
|
+
- The server will still route messages correctly
|
|
549
|
+
|
|
550
|
+
## Conclusion
|
|
551
|
+
|
|
552
|
+
The PeerPigeon hub system provides a flexible way to create stable, scalable peer-to-peer networks. By combining persistent hub nodes with transient peer connections, you can build robust applications that leverage both centralized coordination and decentralized communication.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# WebSocket Server Migration - Complete ✅
|
|
2
|
+
|
|
3
|
+
## Summary
|
|
4
|
+
|
|
5
|
+
Successfully migrated from the legacy `websocket-server/` directory to the new `server/` module with the enhanced `PeerPigeonServer` class.
|
|
6
|
+
|
|
7
|
+
## What Changed
|
|
8
|
+
|
|
9
|
+
### ✅ Removed
|
|
10
|
+
- **`websocket-server/server.js`** - Legacy standalone server (448 lines)
|
|
11
|
+
- **`websocket-server/`** directory
|
|
12
|
+
|
|
13
|
+
### ✅ New Files
|
|
14
|
+
- **`server/start.js`** - New standalone server script that uses `PeerPigeonServer`
|
|
15
|
+
|
|
16
|
+
### ✅ Updated Files
|
|
17
|
+
|
|
18
|
+
1. **`package.json`**
|
|
19
|
+
- Changed `npm start` and `npm run server` to use `server/start.js`
|
|
20
|
+
- Updated lint scripts to check `server/` instead of `websocket-server/`
|
|
21
|
+
- Removed `websocket-server/` from published files
|
|
22
|
+
|
|
23
|
+
2. **Test Files**
|
|
24
|
+
- `test/browser-integration-test.js`
|
|
25
|
+
- `test/manual-video-test.js`
|
|
26
|
+
- `test/manual-video-streaming-test.js`
|
|
27
|
+
- `test/video-streaming-test.js`
|
|
28
|
+
- All now spawn `server/start.js` instead of `websocket-server/server.js`
|
|
29
|
+
|
|
30
|
+
3. **Development Files**
|
|
31
|
+
- `dev-runner.js` - Now uses `server/start.js`
|
|
32
|
+
|
|
33
|
+
4. **Documentation**
|
|
34
|
+
- `examples/browser/minimal/README.md` - Updated server start command
|
|
35
|
+
- `SELECTIVE_STREAMING_GUIDE.md` - Updated to use `npm run server`
|
|
36
|
+
|
|
37
|
+
## Benefits of New Server
|
|
38
|
+
|
|
39
|
+
The new `server/index.js` (`PeerPigeonServer` class) provides:
|
|
40
|
+
|
|
41
|
+
1. **Hub Support** - Can act as a hub with mesh networking capabilities
|
|
42
|
+
2. **Network Namespaces** - Isolate peers into different networks
|
|
43
|
+
3. **Bootstrap Connections** - Hubs can connect to other hubs
|
|
44
|
+
4. **Better API** - Event-driven architecture with EventEmitter
|
|
45
|
+
5. **Programmatic Usage** - Can be imported and used as a module
|
|
46
|
+
6. **Auto Port Selection** - Automatically tries next port if one is in use
|
|
47
|
+
7. **Better Cleanup** - More robust connection management
|
|
48
|
+
8. **Statistics API** - `getStats()` and `getHubStats()` methods
|
|
49
|
+
|
|
50
|
+
## Migration Commands
|
|
51
|
+
|
|
52
|
+
### Old Way
|
|
53
|
+
```bash
|
|
54
|
+
node websocket-server/server.js
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### New Way
|
|
58
|
+
```bash
|
|
59
|
+
npm run server
|
|
60
|
+
# or
|
|
61
|
+
node server/start.js
|
|
62
|
+
# or programmatically
|
|
63
|
+
import { PeerPigeonServer } from './server/index.js';
|
|
64
|
+
const server = new PeerPigeonServer({ port: 3000 });
|
|
65
|
+
await server.start();
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Environment Variables
|
|
69
|
+
|
|
70
|
+
The new server supports:
|
|
71
|
+
- `PORT` - Server port (default: 3000)
|
|
72
|
+
- `HOST` - Server host (default: localhost)
|
|
73
|
+
- `MAX_CONNECTIONS` - Max connections (default: 1000)
|
|
74
|
+
- `CORS_ORIGIN` - CORS origin (default: *)
|
|
75
|
+
|
|
76
|
+
## Testing
|
|
77
|
+
|
|
78
|
+
Server was tested and verified working:
|
|
79
|
+
```bash
|
|
80
|
+
✅ Server starts successfully
|
|
81
|
+
✅ Health endpoint responds: /health
|
|
82
|
+
✅ Backwards compatible with all existing tests
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Next Steps
|
|
86
|
+
|
|
87
|
+
1. ✅ All npm scripts updated
|
|
88
|
+
2. ✅ All tests migrated
|
|
89
|
+
3. ✅ Documentation updated
|
|
90
|
+
4. ✅ Old code removed
|
|
91
|
+
5. 🎉 Migration complete!
|
|
92
|
+
|
|
93
|
+
The codebase is now cleaner with a single, more powerful server implementation.
|