peerpigeon 0.1.1 → 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.
Files changed (70) hide show
  1. package/README.md +141 -1365
  2. package/cli.js +1382 -0
  3. package/dist/peerpigeon-browser.js +12290 -0
  4. package/dist/peerpigeon-browser.js.map +7 -0
  5. package/docs/API_DOCUMENTATION.md +1945 -0
  6. package/docs/BOOTSTRAP_HUBS.md +319 -0
  7. package/docs/CLI_README.md +371 -0
  8. package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
  9. package/docs/HUB_QUICK_REF.md +107 -0
  10. package/docs/HUB_SCRIPTS.md +331 -0
  11. package/docs/HUB_SYSTEM.md +552 -0
  12. package/docs/MIGRATION_COMPLETE.md +93 -0
  13. package/docs/NETWORK_NAMESPACES.md +212 -0
  14. package/docs/README.md +107 -0
  15. package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
  16. package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
  17. package/examples/bootstrap-hub-example.js +292 -0
  18. package/examples/browser/README.md +278 -0
  19. package/examples/browser/app.js +2426 -49
  20. package/examples/browser/index.html +481 -630
  21. package/examples/browser/minimal/README.md +55 -0
  22. package/examples/browser/minimal/index.html +75 -0
  23. package/examples/browser/minimal/minimal.js +234 -0
  24. package/examples/browser/styles.css +687 -1425
  25. package/examples/browser/test-bundle.html +35 -0
  26. package/examples/browser-2/index.html +30 -0
  27. package/examples/browser-2/package.json +21 -0
  28. package/examples/browser-2/src/App-simple.vue +21 -0
  29. package/examples/browser-2/src/App.vue +420 -0
  30. package/examples/browser-2/src/components/CryptoView.vue +1661 -0
  31. package/examples/browser-2/src/components/DHTView.vue +1281 -0
  32. package/examples/browser-2/src/components/DebugView.vue +1773 -0
  33. package/examples/browser-2/src/components/MediaView.vue +1048 -0
  34. package/examples/browser-2/src/components/MessagingView.vue +775 -0
  35. package/examples/browser-2/src/components/NetworkView.vue +930 -0
  36. package/examples/browser-2/src/components/StorageView.vue +1376 -0
  37. package/examples/browser-2/src/main.js +5 -0
  38. package/examples/browser-2/src/stores/peerpigeon.js +895 -0
  39. package/examples/browser-2/vite.config.js +6 -0
  40. package/examples/hub-example.js +186 -0
  41. package/examples/multi-hub-test.js +186 -0
  42. package/examples/node/README.md +2 -2
  43. package/examples/selective-streaming-demo.html +698 -0
  44. package/examples/standard-events-demo.js +126 -0
  45. package/package.json +33 -16
  46. package/server/index.js +1032 -98
  47. package/server/start.js +49 -0
  48. package/src/ConnectionManager.js +239 -225
  49. package/src/CryptoManager.js +147 -18
  50. package/src/DebugLogger.js +0 -7
  51. package/src/DistributedStorageManager.js +224 -205
  52. package/src/EnvironmentDetector.js +109 -2
  53. package/src/EventEmitter.js +79 -1
  54. package/src/EvictionManager.js +10 -9
  55. package/src/GossipManager.js +163 -11
  56. package/src/PeerConnection.js +333 -310
  57. package/src/PeerPigeonMesh.js +577 -135
  58. package/src/SignalingClient.js +14 -243
  59. package/src/SignalingHandler.js +31 -10
  60. package/src/StorageManager.js +0 -39
  61. package/src/WebDHT-Simple.js +389 -0
  62. package/src/WebDHT.js +363 -1165
  63. package/src/browser-entry.js +40 -0
  64. package/examples/browser/assets/images/favicon.png +0 -0
  65. package/examples/browser/assets/images/pigeon.png +0 -0
  66. package/examples/browser/crypto-test.html +0 -427
  67. package/examples/browser/ui-old.js +0 -1926
  68. package/examples/browser/ui.js +0 -3391
  69. package/websocket-server/README.md +0 -247
  70. package/websocket-server/server.js +0 -391
@@ -0,0 +1,427 @@
1
+ # PeerPigeon Selective Streaming Guide
2
+
3
+ ## Overview
4
+
5
+ PeerPigeon now supports **selective streaming**, allowing you to control exactly which peers receive your media streams. This enables sophisticated streaming patterns including 1:1, 1:many, and many:many configurations with individual peer control.
6
+
7
+ ## Key Features
8
+
9
+ - **🎯 Selective Streaming**: Stream to specific peers only
10
+ - **📡 Broadcast Mode**: Traditional stream-to-all behavior
11
+ - **🔧 Dynamic Control**: Block/allow peers during active streaming
12
+ - **👥 Multiple Patterns**: Support for 1:1, 1:many, many:many topologies
13
+ - **📊 Status Monitoring**: Real-time streaming status for all peers
14
+
15
+ ## API Reference
16
+
17
+ ### Core Methods
18
+
19
+ #### `startSelectiveStream(peerIds, options)`
20
+ Start streaming to specific peers only.
21
+
22
+ ```javascript
23
+ // 1:1 streaming (single peer)
24
+ await mesh.startSelectiveStream('peer-id-123', {
25
+ video: true,
26
+ audio: true
27
+ });
28
+
29
+ // 1:many streaming (multiple peers)
30
+ await mesh.startSelectiveStream([
31
+ 'peer-id-123',
32
+ 'peer-id-456',
33
+ 'peer-id-789'
34
+ ], {
35
+ video: true,
36
+ audio: true
37
+ });
38
+ ```
39
+
40
+ **Parameters:**
41
+ - `peerIds` (string | string[]): Target peer ID(s) to stream to
42
+ - `options` (Object): Media stream options
43
+ - `video` (boolean): Enable video streaming
44
+ - `audio` (boolean): Enable audio streaming
45
+ - `deviceIds` (Object): Specific device IDs for camera/microphone
46
+
47
+ **Returns:** `Promise<MediaStream>` - The local media stream
48
+
49
+ #### `stopSelectiveStream(returnToBroadcast)`
50
+ Stop selective streaming with option to switch to broadcast mode.
51
+
52
+ ```javascript
53
+ // Stop streaming entirely
54
+ await mesh.stopSelectiveStream(false);
55
+
56
+ // Stop selective and switch to broadcast mode
57
+ await mesh.stopSelectiveStream(true);
58
+ ```
59
+
60
+ **Parameters:**
61
+ - `returnToBroadcast` (boolean): If true, switch to broadcast mode; if false, stop entirely
62
+
63
+ #### `enableStreamingForAllPeers()`
64
+ Switch to broadcast mode - stream to all connected peers.
65
+
66
+ ```javascript
67
+ await mesh.enableStreamingForAllPeers();
68
+ ```
69
+
70
+ #### `blockStreamingToPeers(peerIds)`
71
+ Block streaming to specific peers while maintaining streams to others.
72
+
73
+ ```javascript
74
+ // Block streaming to specific peers
75
+ await mesh.blockStreamingToPeers(['peer-id-456', 'peer-id-789']);
76
+
77
+ // Block single peer
78
+ await mesh.blockStreamingToPeers('peer-id-123');
79
+ ```
80
+
81
+ #### `allowStreamingToPeers(peerIds)`
82
+ Re-enable streaming to previously blocked peers.
83
+
84
+ ```javascript
85
+ // Allow streaming to specific peers
86
+ await mesh.allowStreamingToPeers(['peer-id-456', 'peer-id-789']);
87
+
88
+ // Allow single peer
89
+ await mesh.allowStreamingToPeers('peer-id-123');
90
+ ```
91
+
92
+ ### Status Methods
93
+
94
+ #### `getStreamingStatus()`
95
+ Get detailed streaming status for all connected peers.
96
+
97
+ ```javascript
98
+ const status = mesh.getStreamingStatus();
99
+ // Returns Map<string, StreamingStatus>
100
+ // StreamingStatus: {
101
+ // sendingStream: boolean,
102
+ // receivingStreams: boolean,
103
+ // streamType: 'broadcast' | 'selective' | 'none'
104
+ // }
105
+ ```
106
+
107
+ #### `isStreamingToAll()`
108
+ Check if currently streaming to all connected peers.
109
+
110
+ ```javascript
111
+ const isBroadcast = mesh.isStreamingToAll();
112
+ // Returns boolean
113
+ ```
114
+
115
+ #### `getStreamingPeers()`
116
+ Get list of peers currently receiving streams.
117
+
118
+ ```javascript
119
+ const streamingPeers = mesh.getStreamingPeers();
120
+ // Returns string[] - Array of peer IDs
121
+ ```
122
+
123
+ #### `getBlockedStreamingPeers()`
124
+ Get list of peers blocked from receiving streams.
125
+
126
+ ```javascript
127
+ const blockedPeers = mesh.getBlockedStreamingPeers();
128
+ // Returns string[] - Array of peer IDs
129
+ ```
130
+
131
+ ## Events
132
+
133
+ The selective streaming system emits several new events:
134
+
135
+ ### `selectiveStreamStarted`
136
+ Fired when selective streaming begins.
137
+
138
+ ```javascript
139
+ mesh.addEventListener('selectiveStreamStarted', (data) => {
140
+ console.log(`Selective ${data.streamType} streaming started`);
141
+ console.log(`Target peers: ${data.targetPeerIds.join(', ')}`);
142
+ console.log(`Stream:`, data.stream);
143
+ });
144
+ ```
145
+
146
+ ### `selectiveStreamStopped`
147
+ Fired when selective streaming stops.
148
+
149
+ ```javascript
150
+ mesh.addEventListener('selectiveStreamStopped', (data) => {
151
+ console.log(`Selective streaming stopped`);
152
+ console.log(`Switched to broadcast: ${data.returnToBroadcast}`);
153
+ });
154
+ ```
155
+
156
+ ### `broadcastStreamEnabled`
157
+ Fired when broadcast mode is enabled.
158
+
159
+ ```javascript
160
+ mesh.addEventListener('broadcastStreamEnabled', () => {
161
+ console.log('Broadcasting to all peers');
162
+ });
163
+ ```
164
+
165
+ ### `streamingBlockedToPeers`
166
+ Fired when peers are blocked from streaming.
167
+
168
+ ```javascript
169
+ mesh.addEventListener('streamingBlockedToPeers', (data) => {
170
+ console.log(`Blocked peers: ${data.blockedPeerIds.join(', ')}`);
171
+ });
172
+ ```
173
+
174
+ ### `streamingAllowedToPeers`
175
+ Fired when peers are allowed streaming access.
176
+
177
+ ```javascript
178
+ mesh.addEventListener('streamingAllowedToPeers', (data) => {
179
+ console.log(`Allowed peers: ${data.allowedPeerIds.join(', ')}`);
180
+ });
181
+ ```
182
+
183
+ ## Streaming Patterns
184
+
185
+ ### 1:1 Streaming (Private Call)
186
+ Stream to exactly one peer for private communication.
187
+
188
+ ```javascript
189
+ // Start 1:1 streaming
190
+ await mesh.startSelectiveStream('target-peer-id', {
191
+ video: true,
192
+ audio: true
193
+ });
194
+
195
+ console.log('Private call started');
196
+ ```
197
+
198
+ ### 1:Many Streaming (Broadcast to Group)
199
+ Stream to multiple selected peers (like a webinar or presentation).
200
+
201
+ ```javascript
202
+ // Select target audience
203
+ const audience = ['peer-1', 'peer-2', 'peer-3'];
204
+
205
+ // Start group streaming
206
+ await mesh.startSelectiveStream(audience, {
207
+ video: true,
208
+ audio: true
209
+ });
210
+
211
+ console.log(`Presenting to ${audience.length} participants`);
212
+ ```
213
+
214
+ ### Many:Many Streaming (Conference)
215
+ Multiple peers streaming to each other in various patterns.
216
+
217
+ ```javascript
218
+ // Each peer can define their own streaming targets
219
+ // Peer A streams to B and C
220
+ await meshA.startSelectiveStream(['peer-b', 'peer-c'], options);
221
+
222
+ // Peer B streams to A and C
223
+ await meshB.startSelectiveStream(['peer-a', 'peer-c'], options);
224
+
225
+ // Peer C streams only to A (selective participation)
226
+ await meshC.startSelectiveStream(['peer-a'], options);
227
+ ```
228
+
229
+ ### Dynamic Control During Streaming
230
+ Modify streaming targets while active.
231
+
232
+ ```javascript
233
+ // Start streaming to group
234
+ await mesh.startSelectiveStream(['peer-1', 'peer-2', 'peer-3'], options);
235
+
236
+ // Later: Block disruptive participant
237
+ await mesh.blockStreamingToPeers(['peer-2']);
238
+
239
+ // Later: Allow them back
240
+ await mesh.allowStreamingToPeers(['peer-2']);
241
+
242
+ // Or switch to broadcast mode
243
+ await mesh.stopSelectiveStream(true);
244
+ ```
245
+
246
+ ## Migration from Traditional Broadcasting
247
+
248
+ ### Before (Traditional Broadcasting)
249
+ ```javascript
250
+ // Old way - always streams to ALL connected peers
251
+ await mesh.startMedia({
252
+ video: true,
253
+ audio: true
254
+ });
255
+ // No control over who receives the stream
256
+ ```
257
+
258
+ ### After (Selective Streaming)
259
+ ```javascript
260
+ // New way - full control over streaming targets
261
+
262
+ // Option 1: Selective streaming
263
+ await mesh.startSelectiveStream(['peer-1', 'peer-2'], {
264
+ video: true,
265
+ audio: true
266
+ });
267
+
268
+ // Option 2: Traditional broadcast (still supported)
269
+ await mesh.enableStreamingForAllPeers();
270
+ await mesh.startMedia({
271
+ video: true,
272
+ audio: true
273
+ });
274
+
275
+ // Option 3: Use new selective method for broadcast
276
+ await mesh.startSelectiveStream(mesh.getConnectedPeerIds(), options);
277
+ ```
278
+
279
+ ## Best Practices
280
+
281
+ ### 1. Check Connected Peers
282
+ Always verify peers are connected before starting selective streaming.
283
+
284
+ ```javascript
285
+ const connectedPeers = mesh.getConnectedPeerIds();
286
+ const targetPeers = ['peer-1', 'peer-2'];
287
+
288
+ // Filter to only connected targets
289
+ const validTargets = targetPeers.filter(id => connectedPeers.includes(id));
290
+
291
+ if (validTargets.length > 0) {
292
+ await mesh.startSelectiveStream(validTargets, options);
293
+ } else {
294
+ console.log('No valid targets for streaming');
295
+ }
296
+ ```
297
+
298
+ ### 2. Monitor Streaming Status
299
+ Use status methods to keep UI updated.
300
+
301
+ ```javascript
302
+ function updateStreamingUI() {
303
+ const isStreaming = mesh.isStreamingToAll();
304
+ const streamingPeers = mesh.getStreamingPeers();
305
+ const blockedPeers = mesh.getBlockedStreamingPeers();
306
+
307
+ document.getElementById('streaming-mode').textContent =
308
+ isStreaming ? 'Broadcast' : 'Selective';
309
+ document.getElementById('active-peers').textContent =
310
+ streamingPeers.length;
311
+ document.getElementById('blocked-peers').textContent =
312
+ blockedPeers.length;
313
+ }
314
+
315
+ // Update on any streaming event
316
+ mesh.addEventListener('selectiveStreamStarted', updateStreamingUI);
317
+ mesh.addEventListener('streamingBlockedToPeers', updateStreamingUI);
318
+ mesh.addEventListener('streamingAllowedToPeers', updateStreamingUI);
319
+ ```
320
+
321
+ ### 3. Handle Errors Gracefully
322
+ Always wrap streaming operations in try-catch blocks.
323
+
324
+ ```javascript
325
+ async function startConferenceCall(participants) {
326
+ try {
327
+ await mesh.startSelectiveStream(participants, {
328
+ video: true,
329
+ audio: true
330
+ });
331
+ console.log('Conference started successfully');
332
+ } catch (error) {
333
+ console.error('Failed to start conference:', error);
334
+
335
+ // Fallback to broadcast mode
336
+ try {
337
+ await mesh.enableStreamingForAllPeers();
338
+ await mesh.startMedia({ video: true, audio: true });
339
+ console.log('Fallback to broadcast mode');
340
+ } catch (fallbackError) {
341
+ console.error('All streaming methods failed:', fallbackError);
342
+ }
343
+ }
344
+ }
345
+ ```
346
+
347
+ ### 4. Cleanup on Disconnect
348
+ Stop streaming when peers disconnect.
349
+
350
+ ```javascript
351
+ mesh.addEventListener('peerDisconnected', async (data) => {
352
+ const disconnectedPeer = data.peerId;
353
+ const streamingPeers = mesh.getStreamingPeers();
354
+
355
+ // If we were streaming only to the disconnected peer
356
+ if (streamingPeers.length === 1 && streamingPeers[0] === disconnectedPeer) {
357
+ await mesh.stopSelectiveStream(false);
358
+ console.log('Stopped streaming - target peer disconnected');
359
+ }
360
+ });
361
+ ```
362
+
363
+ ## Demo and Examples
364
+
365
+ Check out the complete demo at `examples/selective-streaming-demo.html` for a working implementation with UI controls.
366
+
367
+ ### Running the Demo
368
+
369
+ 1. Start a signaling server:
370
+ ```bash
371
+ npm run server
372
+ # or directly:
373
+ # node server/start.js
374
+ ```
375
+
376
+ 2. Open the demo in multiple browser tabs:
377
+ ```bash
378
+ # Open examples/selective-streaming-demo.html in 2+ browser tabs
379
+ ```
380
+
381
+ 3. Connect all tabs to the signaling server
382
+ 4. Experiment with different streaming patterns using the UI controls
383
+
384
+ ## Backward Compatibility
385
+
386
+ All existing PeerPigeon applications continue to work unchanged. The traditional `startMedia()` method still broadcasts to all connected peers by default. Selective streaming is purely additive functionality.
387
+
388
+ ## Use Cases
389
+
390
+ - **Video Conferences**: Each participant can choose who they stream to
391
+ - **Webinars**: Host streams to all, participants can selectively unmute to specific people
392
+ - **Private Calls**: 1:1 streaming for confidential conversations
393
+ - **Breakout Rooms**: Dynamic group formation with selective streaming
394
+ - **Gaming**: Players can stream to teammates but not opponents
395
+ - **Education**: Teachers can create focused groups for different lesson components
396
+ - **Moderation**: Ability to block disruptive participants while maintaining streams to others
397
+
398
+ ## Performance Considerations
399
+
400
+ - Selective streaming can reduce bandwidth usage by limiting stream targets
401
+ - Each peer connection requires separate encoding, so many targets still use significant resources
402
+ - The mesh forwarding system automatically handles indirect peer connections
403
+ - Monitor connection quality and adjust streaming targets accordingly
404
+
405
+ ## Troubleshooting
406
+
407
+ ### Common Issues
408
+
409
+ 1. **"No peers selected" error**: Ensure you've selected peers in the UI or passed valid peer IDs
410
+ 2. **Streaming not working**: Check that crypto keys are exchanged and data channels are ready
411
+ 3. **Peers not receiving streams**: Verify the target peers have called `allowRemoteStreamEmission()`
412
+ 4. **Performance issues**: Reduce number of streaming targets or lower video quality
413
+
414
+ ### Debug Information
415
+
416
+ ```javascript
417
+ // Check streaming status
418
+ console.log('Streaming Status:', mesh.getStreamingStatus());
419
+ console.log('Connected Peers:', mesh.getConnectedPeerIds());
420
+ console.log('Streaming To:', mesh.getStreamingPeers());
421
+ console.log('Blocked Peers:', mesh.getBlockedStreamingPeers());
422
+
423
+ // Monitor events
424
+ mesh.addEventListener('selectiveStreamStarted', console.log);
425
+ mesh.addEventListener('streamingBlockedToPeers', console.log);
426
+ mesh.addEventListener('streamingAllowedToPeers', console.log);
427
+ ```
@@ -0,0 +1,80 @@
1
+ # Test Cleanup - Complete ✅
2
+
3
+ ## Summary
4
+
5
+ Removed unused and unnecessary test files to streamline the test suite.
6
+
7
+ ## Removed Files
8
+
9
+ ### ❌ `test/event-emitter-test.js` (184 lines)
10
+ **Reason:** Unit test that was never integrated into CI or package.json scripts.
11
+ - Was a standalone test for EventEmitter methods
12
+ - Not referenced anywhere in the codebase
13
+ - If EventEmitter testing is needed, should be added to proper test framework
14
+
15
+ ### ❌ `test/manual-video-test.js` (967 lines)
16
+ **Reason:** Superseded by `manual-video-streaming-test.js`
17
+ - Old manual video test implementation
18
+ - Never added to package.json scripts
19
+ - The newer `manual-video-streaming-test.js` is actively maintained and in package.json
20
+
21
+ ### ❌ `test/run-video-streaming-test.js` (103 lines)
22
+ **Reason:** Unnecessary wrapper script
23
+ - Just a wrapper that spawns `video-streaming-test.js`
24
+ - Adds no real value - users can run tests directly with environment variables
25
+ - Example: `HEADLESS=false node test/video-streaming-test.js`
26
+
27
+ ## Updated
28
+
29
+ ### ✏️ `package.json`
30
+ - Removed `test:video:runner` script (pointed to deleted run-video-streaming-test.js)
31
+
32
+ ## Remaining Tests
33
+
34
+ The test suite now contains only actively used tests:
35
+
36
+ ### ✅ `test/browser-integration-test.js`
37
+ - **Purpose:** Main integration test for browser functionality
38
+ - **npm scripts:** `npm test`, `npm run test:browser`, `npm run test:browser:visual`
39
+ - **Used in:** CI pipeline (`npm run ci`)
40
+
41
+ ### ✅ `test/video-streaming-test.js`
42
+ - **Purpose:** Automated video streaming tests (1:1, 1:many, many:many)
43
+ - **npm scripts:** `npm run test:video`, `npm run test:video:visual`
44
+
45
+ ### ✅ `test/manual-video-streaming-test.js`
46
+ - **Purpose:** Interactive manual video streaming test with CLI controls
47
+ - **npm scripts:** `npm run test:video:manual`, `npm run test:video:manual:visual`
48
+
49
+ ## Available Test Commands
50
+
51
+ ```bash
52
+ # Main tests (runs in CI)
53
+ npm test # Browser integration test (headless)
54
+ npm run ci # Run lint + tests
55
+
56
+ # Browser tests
57
+ npm run test:browser # Browser integration (headless)
58
+ npm run test:browser:visual # Browser integration (headed)
59
+
60
+ # Video streaming tests
61
+ npm run test:video # Automated video tests (headless)
62
+ npm run test:video:visual # Automated video tests (headed)
63
+ npm run test:video:manual # Manual interactive test (headless)
64
+ npm run test:video:manual:visual # Manual interactive test (headed)
65
+
66
+ # Storage tests
67
+ npm run test:storage # Storage functionality test
68
+ ```
69
+
70
+ ## Benefits
71
+
72
+ 1. **Cleaner codebase** - Removed ~1,254 lines of unused test code
73
+ 2. **Less confusion** - No duplicate or abandoned tests
74
+ 3. **Easier maintenance** - Only maintaining tests that are actually run
75
+ 4. **Clear test suite** - All remaining tests are documented in package.json
76
+
77
+ ## Migration Notes
78
+
79
+ - If you were using `test:video:runner`, use `test:video` or `test:video:visual` instead
80
+ - If you need headless/headed mode, use the `:visual` variants or set `HEADLESS=false`