peerpigeon 0.1.1 → 1.0.2

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