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
package/README.md CHANGED
@@ -1,1457 +1,233 @@
1
1
  # PeerPigeon <img src="examples/browser/assets/images/favicon.png" alt="PeerPigeon Logo" width="32" height="32" align="right">
2
2
 
3
- **A WebRTC-based peer-to-peer mesh networking library with intelligent routing, gossip protocol messaging, and automated peer management.**
3
+ **WebRTC-based peer-to-peer mesh networking with intelligent routing, encrypted storage, and media streaming.**
4
4
 
5
5
  [![npm version](https://badge.fury.io/js/peerpigeon.svg)](https://badge.fury.io/js/peerpigeon)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
- [![Tests](https://img.shields.io/badge/Tests-23%2F23%20passing-brightgreen.svg)](https://github.com/draeder/peerpigeon)
8
- [![ESLint](https://img.shields.io/badge/ESLint-0%20errors-brightgreen.svg)](https://github.com/draeder/peerpigeon)
7
+ [![Node.js >= 14](https://img.shields.io/badge/node-%3E%3D14-brightgreen.svg)](https://nodejs.org)
9
8
 
10
- > **📊 Viewing Diagrams**: This README contains Mermaid diagrams. For proper visualization in VS Code, install the [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) extension.
9
+ PeerPigeon is a production-ready library for building decentralized applications with true mesh networking, encrypted distributed storage, and selective media streaming. It handles peer discovery, connection management, and message routing automatically.
11
10
 
12
- ## 🌟 Features
11
+ ## ✨ Key Features
13
12
 
14
- - **🕸️ True Mesh Networking**: Gossip protocol ensures messages reach all peers, not just direct connections
15
- - **📐 XOR Distance Routing**: Kademlia-inspired peer selection for optimal network topology
16
- - **🧠 Smart Eviction Strategy**: Automatically replaces distant peers with closer ones to optimize mesh topology
17
- - **🔍 Auto-Discovery**: Seamlessly connects to peers as they join the network
18
- - **⚡ WebSocket Signaling**: Real-time bidirectional communication for optimal performance
19
- - **🗄️ Distributed Hash Table (WebDHT)**: Store and retrieve data across the mesh with automatic replication
20
- - **📦 Distributed Storage Layer**: Encrypted, access-controlled storage with CRDT support for collaborative editing
21
- - **🎥 Media Streaming**: Built-in support for audio/video streaming between peers
22
- - **💬 Messaging System**: Direct messages and broadcast gossip protocol messaging
23
- - **🔧 Modular Architecture**: Clean separation of concerns with event-driven components
24
- - **💰 Cost-Optimized**: XOR-based routing reduces signaling server costs by ~95%
25
- - **🛡️ Memory Safe**: Comprehensive cleanup prevents memory leaks in long-running applications
26
-
27
- ## 🏗️ Architecture Overview
28
-
29
- ```mermaid
30
- graph TB
31
- subgraph Browser[Browser Environment]
32
- UI[User Interface] --> App[PeerPigeonMesh]
33
-
34
- App --> SC[SignalingClient]
35
- App --> PD[PeerDiscovery]
36
- App --> CM[ConnectionManager]
37
- App --> EM[EvictionManager]
38
- App --> GM[GossipManager]
39
- App --> MO[MeshOptimizer]
40
-
41
- CM --> PC1[PeerConnection A]
42
- CM --> PC2[PeerConnection B]
43
- CM --> PC3[PeerConnection ...]
44
-
45
- GM --> PC1
46
- GM --> PC2
47
- GM --> PC3
48
- end
49
-
50
- subgraph Network[Network Layer]
51
- PC1 -.->|WebRTC Data Channel| PA[Peer A]
52
- PC2 -.->|WebRTC Data Channel| PB[Peer B]
53
- PC3 -.->|WebRTC Data Channel| PC[Peer ...]
54
- end
55
-
56
- subgraph Signaling[Signaling Infrastructure]
57
- SC -->|HTTP/WebSocket| SS[Signaling Server]
58
- SS --> DB[(Message Storage)]
59
- end
60
-
61
- style App fill:#e1f5fe,color:#000000
62
- style GM fill:#e8f5e8,color:#000000
63
- style EM fill:#fff3e0,color:#000000
64
- style PD fill:#fce4ec,color:#000000
65
- ```
66
-
67
- > **Note**: If diagrams don't display, install the [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) extension in VS Code.
13
+ - **🕸️ True Mesh Networking** - Gossip protocol + XOR distance routing (Kademlia-inspired)
14
+ - **🌐 Network Namespaces** - Isolated peer networks with automatic global fallback
15
+ - **🗄️ Distributed Storage** - Encrypted, CRDT-enabled storage across the mesh
16
+ - **🎥 Selective Streaming** - Efficient audio/video streaming with bandwidth management
17
+ - **🏢 Hub System** - Connect multiple signaling servers for global peer discovery
18
+ - **🔐 End-to-End Encryption** - Built-in crypto for secure communication
19
+ - **💰 Cost Optimized** - Smart routing reduces server costs by ~95%
20
+ - **📱 Multi-Platform** - Browser, Node.js, NativeScript support
68
21
 
69
22
  ## 🚀 Quick Start
70
23
 
71
24
  ### Installation
72
25
 
73
26
  ```bash
74
- # Install PeerPigeon from npm
75
27
  npm install peerpigeon
76
28
  ```
77
29
 
78
- ### Basic Setup
30
+ ### Basic Usage
79
31
 
80
32
  ```javascript
81
33
  import { PeerPigeonMesh } from 'peerpigeon';
82
34
 
83
- // Create mesh instance
84
- const mesh = new PeerPigeonMesh({
85
- enableWebDHT: true, // Enable distributed hash table (default: true)
86
- peerId: 'custom-peer-id' // Optional: provide custom peer ID
87
- });
88
-
89
- // Initialize and connect
35
+ // Create and connect
36
+ const mesh = new PeerPigeonMesh({ enableWebDHT: true, enableCrypto: true });
90
37
  await mesh.init();
91
- await mesh.connect('ws://localhost:3000'); // Your signaling server URL
92
- ```
93
-
94
- ### Starting a WebSocket Server
95
-
96
- #### Option 1: Programmatic Server Setup (Recommended)
97
-
98
- ```javascript
99
- import { PeerPigeonServer } from 'peerpigeon';
100
-
101
- // Create and start the server
102
- const server = new PeerPigeonServer({
103
- port: 3000,
104
- host: 'localhost',
105
- maxConnections: 1000,
106
- cleanupInterval: 60000, // 1 minute
107
- peerTimeout: 300000 // 5 minutes
108
- });
109
-
110
- // Start the server
111
- await server.start();
112
-
113
- // Listen for events
114
- server.on('peerConnected', ({ peerId, totalConnections }) => {
115
- console.log(`Peer ${peerId} connected. Total: ${totalConnections}`);
116
- });
38
+ await mesh.connect('ws://localhost:3000');
117
39
 
118
- server.on('peerDisconnected', ({ peerId, totalConnections }) => {
119
- console.log(`Peer ${peerId} disconnected. Total: ${totalConnections}`);
120
- });
40
+ // Send messages
41
+ mesh.sendMessage('Hello, mesh!');
121
42
 
122
- // Graceful shutdown
123
- process.on('SIGINT', async () => {
124
- await server.stop();
125
- process.exit(0);
43
+ // Listen for messages
44
+ mesh.on('messageReceived', ({ from, content }) => {
45
+ console.log(`${from}: ${content}`);
126
46
  });
127
47
  ```
128
48
 
129
- #### Option 2: Standalone Server
49
+ ### Run Signaling Server
130
50
 
131
51
  ```bash
132
- # Run the standalone server (from npm package)
52
+ # Option 1: Use npm script
133
53
  npm start
134
54
 
135
- # Or run directly with custom configuration
136
- PORT=8080 HOST=0.0.0.0 npm start
137
- ```
138
-
139
- ### Messaging Examples
140
-
141
- ```javascript
142
- // Send a broadcast message to all peers
143
- const messageId = mesh.sendMessage('Hello, mesh network!');
144
-
145
- // Send a direct message to a specific peer
146
- const directMessageId = mesh.sendDirectMessage('target-peer-id', 'Private message');
147
-
148
- // Listen for incoming messages
149
- mesh.addEventListener('messageReceived', (data) => {
150
- console.log(`Message from ${data.from}: ${data.content}`);
151
- console.log(`Direct message: ${data.direct}`);
152
- });
153
- ```
154
-
155
- ### 🐛 Debug Configuration
156
-
157
- PeerPigeon includes a comprehensive debug system that allows you to control console output at a granular level. **By default, all console logging is disabled** to prevent noise in production.
158
-
159
- ```javascript
160
- import { PeerPigeonMesh, DebugLogger } from 'peerpigeon';
161
-
162
- // Enable debugging for specific modules
163
- DebugLogger.enableModules(['GossipManager', 'ConnectionManager']);
164
-
165
- // Enable all debugging (development mode)
166
- DebugLogger.enableAll();
167
-
168
- // Enable debugging conditionally
169
- if (process.env.NODE_ENV === 'development') {
170
- DebugLogger.enableAll();
171
- }
172
-
173
- // Create your mesh with debug output enabled
174
- const mesh = new PeerPigeonMesh(options);
175
- ```
176
-
177
- **Available Debug Modules:**
178
- - `PeerPigeonMesh` - Main mesh lifecycle events
179
- - `GossipManager` - Message propagation debugging
180
- - `ConnectionManager` - Peer connection management
181
- - `PeerConnection` - Individual WebRTC connections
182
- - `WebDHT` - Distributed hash table operations
183
- - `CryptoManager` - Encryption operations
184
- - `MediaManager` - Audio/video streaming
185
- - And many more...
186
-
187
- See [docs/DEBUG.md](docs/DEBUG.md) for complete documentation.
188
-
189
- ### WebDHT (Distributed Hash Table) Examples
190
-
191
- ```javascript
192
- // Store data in the distributed hash table
193
- await mesh.dhtPut('user-settings', { theme: 'dark', language: 'en' });
194
-
195
- // Retrieve data from the DHT
196
- const settings = await mesh.dhtGet('user-settings');
197
-
198
- // Subscribe to changes
199
- await mesh.dhtSubscribe('shared-counter');
200
- mesh.addEventListener('dhtValueChanged', (data) => {
201
- console.log(`Key ${data.key} changed to:`, data.newValue);
202
- });
55
+ # Option 2: Custom port
56
+ PORT=8080 npm start
203
57
 
204
- // Update a value and notify subscribers
205
- await mesh.dhtUpdate('shared-counter', 42);
58
+ # Option 3: Run as a hub (multi-server mesh)
59
+ npm run hub
206
60
  ```
207
61
 
208
- ### Distributed Storage Layer Examples
62
+ ## 📚 Examples
209
63
 
210
- ```javascript
211
- // Enable crypto for encryption support
212
- const mesh = new PeerPigeonMesh({
213
- enableCrypto: true,
214
- enableWebDHT: true
215
- });
216
-
217
- await mesh.cryptoManager.init();
218
- await mesh.connect('ws://localhost:3000');
219
-
220
- // Store private encrypted data
221
- await mesh.distributedStorage.store('user:profile', {
222
- name: 'Alice',
223
- email: 'alice@example.com'
224
- }, {
225
- isPublic: false, // Private (encrypted)
226
- isImmutable: false // Mutable for owner
227
- });
228
-
229
- // Store public data
230
- await mesh.distributedStorage.store('app:config', {
231
- version: '1.0.0',
232
- features: ['chat', 'files']
233
- }, {
234
- isPublic: true, // Public (not encrypted)
235
- isImmutable: true // Immutable for other peers
236
- });
237
-
238
- // Store collaborative document with CRDT
239
- await mesh.distributedStorage.store('doc:shared', {
240
- title: 'Shared Document',
241
- content: 'Initial content'
242
- }, {
243
- isPublic: true,
244
- enableCRDT: true // Enable collaborative editing
245
- });
246
-
247
- // Grant access to private data
248
- await mesh.distributedStorage.grantAccess('user:profile', otherPeer.peerId);
249
-
250
- // Retrieve data
251
- const profile = await mesh.distributedStorage.retrieve('user:profile');
252
-
253
- // Update data (owner only, or CRDT-enabled)
254
- await mesh.distributedStorage.update('user:profile', {
255
- name: 'Alice Smith',
256
- email: 'alice.smith@example.com'
257
- });
258
-
259
- // Listen for storage events
260
- mesh.addEventListener('storageDataUpdated', (event) => {
261
- console.log(`Data updated: ${event.key} (version ${event.version})`);
262
- });
263
- ```
264
-
265
- ### Media Streaming Examples
64
+ ### Distributed Storage
266
65
 
267
66
  ```javascript
268
- // Start local video stream
269
- const stream = await mesh.startMedia({ video: true, audio: true });
270
-
271
- // Toggle media
272
- mesh.toggleVideo(); // Enable/disable video
273
- mesh.toggleAudio(); // Enable/disable audio
67
+ // Store encrypted data across the mesh
68
+ await mesh.storage.put('myKey', { data: 'value' });
274
69
 
275
- // Get media devices
276
- const devices = await mesh.enumerateMediaDevices();
277
- console.log('Available cameras:', devices.cameras);
278
- console.log('Available microphones:', devices.microphones);
70
+ // Retrieve from any peer
71
+ const value = await mesh.storage.get('myKey');
279
72
 
280
- // Listen for remote streams
281
- mesh.addEventListener('remoteStream', (data) => {
282
- const { peerId, stream } = data;
283
- const videoElement = document.createElement('video');
284
- videoElement.srcObject = stream;
285
- videoElement.play();
286
- });
73
+ // Storage spaces for organization
74
+ const chatSpace = mesh.storage.getSpace('chat');
75
+ await chatSpace.put('message1', { text: 'Hello!' });
287
76
  ```
288
77
 
289
- ### Event Handling Examples
78
+ ### Selective Media Streaming
290
79
 
291
80
  ```javascript
292
- // Connection events
293
- mesh.addEventListener('connected', () => {
294
- console.log('Connected to signaling server');
295
- });
296
-
297
- mesh.addEventListener('peerConnected', (data) => {
298
- console.log(`Peer connected: ${data.peerId}`);
81
+ // Get local media
82
+ const stream = await navigator.mediaDevices.getUserMedia({
83
+ video: true,
84
+ audio: true
299
85
  });
300
86
 
301
- mesh.addEventListener('peerDisconnected', (data) => {
302
- console.log(`Peer disconnected: ${data.peerId}, reason: ${data.reason}`);
303
- });
87
+ // Selective streaming to specific peers
88
+ mesh.media.addLocalStream(stream, 'camera');
89
+ mesh.media.streamToPeer('peer-id-1', 'camera', { video: true, audio: true });
90
+ mesh.media.streamToPeer('peer-id-2', 'camera', { video: false, audio: true }); // Audio only
304
91
 
305
- // Status monitoring
306
- mesh.addEventListener('statusChanged', (data) => {
307
- console.log(`Status: ${data.type} - ${data.message}`);
92
+ // Receive streams
93
+ mesh.media.on('remoteStreamAdded', ({ peerId, stream, label }) => {
94
+ videoElement.srcObject = stream;
308
95
  });
309
96
  ```
310
97
 
311
- ### Configuration Examples
312
-
313
- ```javascript
314
- // Adjust mesh topology
315
- mesh.setMaxPeers(5); // Maximum peer connections
316
- mesh.setMinPeers(2); // Minimum peer connections
317
- mesh.setXorRouting(true); // Enable XOR-based routing
318
- mesh.setEvictionStrategy(true); // Enable smart peer eviction
319
-
320
- // Get current status
321
- const status = mesh.getStatus();
322
- console.log('Connected peers:', status.connectedCount);
323
- console.log('Discovered peers:', status.discoveredCount);
324
- ```
325
-
326
- ### Local Development Server
327
-
328
- **Option 1: Using npm package (Recommended)**
329
- ```bash
330
- # Install PeerPigeon globally or in your project
331
- npm install peerpigeon
332
-
333
- # Start the signaling server
334
- npm start
335
-
336
- # Or with custom configuration
337
- PORT=8080 HOST=0.0.0.0 npm start
338
-
339
- # Serve the browser examples using the built-in server
340
- npm run dev
341
- ```
342
-
343
- **Option 2: From source (for development)**
344
- ```bash
345
- # Clone the repository
346
- git clone https://github.com/draeder/peerpigeon.git
347
- cd peerpigeon
348
-
349
- # Start the WebSocket signaling server
350
- npm start
351
-
352
- # Serve the browser examples
353
- npm run dev
354
- ```
355
-
356
- #### Navigate to http://localhost:8080/examples/browser/
357
-
358
- ###### Test with query parameters
359
- http://localhost:8080/examples/browser/?api=ws://localhost:3000
360
-
361
- ## 🔄 System Flow Diagrams
362
-
363
- ### Peer Discovery & Connection Flow
364
-
365
- ```mermaid
366
- sequenceDiagram
367
- participant A as Peer A
368
- participant B as Peer B
369
- participant C as Peer C
370
- participant S as Signaling Server
371
-
372
- Note over A,C: Network Formation
373
- A->>S: announce (peerId, timestamp)
374
- B->>S: announce (peerId, timestamp)
375
- C->>S: announce (peerId, timestamp)
376
-
377
- S->>A: peer-discovered (B, C)
378
- S->>B: peer-discovered (A, C)
379
- S->>C: peer-discovered (A, B)
380
-
381
- Note over A,C: Smart Connection Logic
382
- A->>A: shouldInitiate(B)? (A > B lexicographically)
383
- A->>B: WebRTC offer (if true)
384
- B->>A: WebRTC answer
385
-
386
- A->>B: ICE candidate
387
- B->>A: ICE candidate
388
- Note over A,B: ✅ WebRTC Data Channel Ready
389
-
390
- Note over A,C: Topology Optimization
391
- C->>A: connection request
392
- A->>A: at capacity? should evict?
393
- A->>B: eviction notice (if applicable)
394
- Note over A,C: ✅ Connection established
395
- ```
396
-
397
- ### Gossip Protocol Message Flow
398
-
399
- ```mermaid
400
- flowchart TD
401
- Send[User sends message] --> CreateMsg["Create gossip message<br/>with ID, TTL=10"]
402
- CreateMsg --> StoreLocal["Store in seen messages<br/>to prevent loops"]
403
- StoreLocal --> EmitLocal[Emit to local UI]
404
- EmitLocal --> Broadcast[Send to all connected peers]
405
-
406
- Receive[Receive gossip message] --> CheckSeen{Already seen this message?}
407
- CheckSeen -->|Yes| Drop[Drop message]
408
- CheckSeen -->|No| CheckTTL{TTL > 0?}
409
- CheckTTL -->|No| Drop
410
- CheckTTL -->|Yes| CheckLoop{Sender in our path?}
411
- CheckLoop -->|Yes| Drop
412
- CheckLoop -->|No| Process[Process message]
413
-
414
- Process --> StoreSeen[Store in seen messages]
415
- StoreSeen --> EmitReceived[Emit to local UI]
416
- EmitReceived --> DecrementTTL["TTL--, add to path"]
417
- DecrementTTL --> Propagate["Forward to other peers<br/>except sender"]
418
-
419
- Propagate --> End[Message delivered]
420
- Drop --> End
421
-
422
- style Send fill:#e8f5e8,color:#000000
423
- style Receive fill:#e1f5fe,color:#000000
424
- style Drop fill:#ffebee,color:#000000
425
- style End fill:#f3e5f5,color:#000000
426
- ```
427
-
428
- ### Peer Connection & Isolation Prevention
429
-
430
- ```mermaid
431
- flowchart TD
432
- Discover[Peer Discovered] --> ShouldInit{Should we initiate connection?}
433
-
434
- ShouldInit --> CheckLex["Lexicographic rule:<br/>our ID > target ID?"]
435
- CheckLex -->|Yes| Connect[Initiate Connection]
436
- CheckLex -->|No| CheckIsolation{Are we isolated?}
437
-
438
- CheckIsolation -->|No connections| IsolationOverride["Override lexicographic rule<br/>to prevent isolation"]
439
- CheckIsolation -->|Has connections| Wait[Wait for peer to initiate to us]
440
-
441
- IsolationOverride --> NaturalInitiator{Can initiate to natural targets?}
442
- NaturalInitiator -->|Yes| ConnectNatural["Connect to peer where<br/>we're natural initiator"]
443
- NaturalInitiator -->|No| ConnectClosest["Connect to closest peer<br/>by XOR distance"]
444
-
445
- ConnectNatural --> Connect
446
- ConnectClosest --> Connect
447
-
448
- Connect --> WebRTC["WebRTC Handshake<br/>via signaling server"]
449
- WebRTC --> Success{Connection successful?}
450
-
451
- Success -->|Yes| CheckCapacity{At peer capacity?}
452
- Success -->|No| RetryLater["Retry with<br/>exponential backoff"]
453
-
454
- CheckCapacity -->|No| Maintain[Maintain connection]
455
- CheckCapacity -->|Yes| ConsiderEviction["Should evict<br/>existing peer?"]
456
-
457
- ConsiderEviction -->|No| Maintain
458
- ConsiderEviction -->|Yes| EvictFarthest["Evict farthest peer<br/>by XOR distance"]
459
-
460
- EvictFarthest --> Maintain
461
- Wait --> End[End]
462
- RetryLater --> End
463
- Maintain --> End
464
-
465
- style Discover fill:#e1f5fe,color:#000000
466
- style IsolationOverride fill:#fff3e0,color:#000000
467
- style EvictFarthest fill:#ffebee,color:#000000
468
- style Maintain fill:#e8f5e8,color:#000000
469
- ```
470
-
471
- ### Smart Eviction Strategy
472
-
473
- ```mermaid
474
- flowchart TD
475
- NewPeer[Incoming Connection Request] --> AtCapacity{At maximum peer capacity?}
476
-
477
- AtCapacity -->|No| Accept[Accept Connection]
478
- AtCapacity -->|Yes| CalcDistance["Calculate XOR distance<br/>from our peer ID"]
479
-
480
- CalcDistance --> FindFarthest["Find currently farthest<br/>connected peer"]
481
- FindFarthest --> Compare["New peer closer<br/>than farthest peer?"]
482
-
483
- Compare -->|No| Reject["Reject connection<br/>not worth evicting for"]
484
- Compare -->|Yes| SendEviction["Send eviction notice<br/>to farthest peer"]
485
-
486
- SendEviction --> DisconnectFarthest[Disconnect farthest peer]
487
- DisconnectFarthest --> AcceptNew[Accept new peer connection]
488
-
489
- AcceptNew --> OptimalTopology["Maintain optimal<br/>mesh topology"]
490
-
491
- Accept --> End[Connection Complete]
492
- Reject --> End
493
- OptimalTopology --> End
494
-
495
- style NewPeer fill:#e1f5fe,color:#000000
496
- style SendEviction fill:#fff3e0,color:#000000
497
- style DisconnectFarthest fill:#ffebee,color:#000000
498
- style AcceptNew fill:#e8f5e8,color:#000000
499
- ```
500
-
501
- ## � API Reference
502
-
503
- ### PeerPigeonServer Class
504
-
505
- When importing the server class, you can create and configure it programmatically:
98
+ ### Network Namespaces
506
99
 
507
100
  ```javascript
508
- import { PeerPigeonServer } from 'peerpigeon';
101
+ // Create isolated networks
102
+ const gameMesh = new PeerPigeonMesh({ networkName: 'game-lobby-1' });
103
+ const chatMesh = new PeerPigeonMesh({ networkName: 'chat-room-5' });
509
104
 
510
- const server = new PeerPigeonServer(options);
105
+ // Peers in different networks won't see each other
106
+ await gameMesh.connect('ws://localhost:3000');
107
+ await chatMesh.connect('ws://localhost:3000');
511
108
  ```
512
109
 
513
- #### Constructor Options
514
-
515
- - **`port`** (number) - Server port (default: 3000)
516
- - **`host`** (string) - Server host (default: 'localhost')
517
- - **`maxConnections`** (number) - Maximum concurrent connections (default: 1000)
518
- - **`cleanupInterval`** (number) - Cleanup interval in ms (default: 60000)
519
- - **`peerTimeout`** (number) - Peer timeout in ms (default: 300000)
520
- - **`corsOrigin`** (string) - CORS origin (default: '*')
521
- - **`maxMessageSize`** (number) - Max message size in bytes (default: 1MB)
522
-
523
- #### Methods
524
-
525
- - **`await server.start()`** - Start the server
526
- - **`await server.stop()`** - Stop the server
527
- - **`server.getStats()`** - Get server statistics
528
- - **`server.getPeers()`** - Get list of connected peers
529
-
530
- #### Events
531
-
532
- - **`started`** - Server started
533
- - **`stopped`** - Server stopped
534
- - **`peerConnected`** - Peer connected
535
- - **`peerDisconnected`** - Peer disconnected
536
- - **`peerAnnounced`** - Peer announced
537
- - **`peerGoodbye`** - Peer said goodbye
538
- - **`error`** - Server error
539
-
540
- #### Example: Custom Server Configuration
110
+ ### Hub System (Multi-Server)
541
111
 
542
112
  ```javascript
543
- import { PeerPigeonServer } from 'peerpigeon';
544
-
545
- const server = new PeerPigeonServer({
546
- port: 8080,
547
- maxConnections: 500,
548
- cleanupInterval: 30000
113
+ // Server 1 (bootstrap hub on port 3000)
114
+ const hub1 = new PeerPigeonServer({
115
+ port: 3000,
116
+ isHub: true
549
117
  });
118
+ await hub1.start();
550
119
 
551
- server.on('peerConnected', ({ peerId, totalConnections }) => {
552
- console.log(`New peer: ${peerId}, Total: ${totalConnections}`);
120
+ // Server 2 connects to hub1
121
+ const hub2 = new PeerPigeonServer({
122
+ port: 3001,
123
+ isHub: true,
124
+ bootstrapHubs: ['ws://localhost:3000']
553
125
  });
126
+ await hub2.start();
554
127
 
555
- await server.start();
556
- ```
557
-
558
- ### Client Library Exports
559
-
560
- ```javascript
561
- import { PeerPigeonMesh, PeerPigeonServer } from 'peerpigeon';
562
- ```
563
-
564
- - **`PeerPigeonMesh`** - Main mesh networking class (browser)
565
- - **`PeerPigeonServer`** - WebSocket signaling server class (Node.js)
566
- - **`PeerConnection`** - WebRTC peer connection wrapper
567
- - **`SignalingClient`** - WebSocket signaling client
568
- - **`WebDHT`** - Distributed hash table implementation
569
-
570
- ## �📚 Core Components
571
-
572
- ### PeerPigeonMesh
573
- Central coordinator that manages all mesh networking functionality and orchestrates the component interactions.
574
-
575
- ```javascript
576
- const mesh = new PeerPigeonMesh();
577
- await mesh.init();
578
- await mesh.connect('wss://your-signaling-server.com');
579
-
580
- // Send message to entire network via gossip protocol
581
- const messageId = mesh.sendMessage('Hello mesh network!');
582
-
583
- // Get network status
584
- const status = mesh.getStatus();
585
- console.log(`Connected to ${status.connectedCount}/${status.maxPeers} peers`);
586
-
587
- // Configure mesh behavior
588
- mesh.setMaxPeers(10);
589
- mesh.setAutoDiscovery(true);
590
- mesh.setEvictionStrategy(true);
591
- ```
592
-
593
- ### PeerDiscovery
594
- Manages peer discovery and implements smart connection logic with isolation prevention.
595
-
596
- **Key Features:**
597
- - **Lexicographic connection rule** prevents connection race conditions
598
- - **Isolation override** ensures peers with no connections can still connect
599
- - **XOR distance sorting** prioritizes closer peers for optimal topology
600
- - **Connection attempt tracking** prevents duplicate connection attempts
601
-
602
- ```javascript
603
- // Example of isolation override logic
604
- if (currentConnectionCount === 0 && discoveredPeers.length > 0) {
605
- // Override lexicographic rule to prevent isolation
606
- // Priority: natural initiators > closest peer by XOR distance
607
- }
608
- ```
609
-
610
- ### ConnectionManager
611
- Manages WebRTC peer connections, handles signaling, and routes messages to appropriate handlers.
612
-
613
- **Responsibilities:**
614
- - WebRTC connection establishment and management
615
- - Message routing to GossipManager and EvictionManager
616
- - Connection state tracking and cleanup
617
- - Retry logic with exponential backoff
618
- - Race condition prevention
619
-
620
- ### GossipManager
621
- Implements gossip protocol for reliable message propagation across the entire mesh network.
622
-
623
- **Protocol Features:**
624
- - **TTL (Time To Live)**: Messages expire after 10 hops to prevent infinite loops
625
- - **Seen message tracking**: Prevents duplicate message processing
626
- - **Path tracking**: Detects and prevents routing loops
627
- - **Broadcast guarantee**: Messages reach all peers, not just direct connections
628
-
629
- ```javascript
630
- // Gossip message structure
631
- {
632
- id: 'unique-message-id',
633
- type: 'gossip',
634
- subtype: 'chat',
635
- content: 'Hello network!',
636
- from: 'sender-peer-id',
637
- timestamp: Date.now(),
638
- ttl: 10,
639
- path: ['sender-peer-id', 'relay-peer-id', ...]
640
- }
641
- ```
642
-
643
- ### EvictionManager
644
- Implements smart peer eviction for optimal mesh topology using XOR distance calculations.
645
-
646
- **Eviction Strategy:**
647
- - Only evicts when at maximum peer capacity
648
- - Calculates XOR distances to determine peer relationships
649
- - Evicts farthest peer when a closer one wants to connect
650
- - Sends eviction notices before disconnecting peers
651
- - No cooldown periods - focuses purely on topology optimization
652
-
653
- ### MeshOptimizer
654
- Handles periodic mesh optimization and provides debugging utilities.
655
-
656
- **Optimization Features:**
657
- - Periodic connectivity analysis
658
- - Force connection to all discovered peers (for testing)
659
- - Mesh topology evaluation and recommendations
660
-
661
- ## ⚙️ Configuration & API
662
-
663
- The PeerPigeonMesh API provides methods for configuration, network management, messaging, and debugging. It is designed to be intuitive and event-driven.
664
-
665
- ### Initialization & Connection
666
- Methods to initialize the mesh and manage the connection to the signaling server.
667
-
668
- ```javascript
669
- // Initialize the mesh with a new, cryptographically secure peer ID.
670
- // This must be called before any other method.
671
- await mesh.init();
672
-
673
- // Connect to the signaling server to join the mesh network.
674
- await mesh.connect(signalingUrl);
675
-
676
- // Disconnect from the signaling server and all connected peers.
677
- mesh.disconnect();
678
- ```
679
-
680
- ### Configuration
681
- Configure the behavior of the mesh network. These setters can be called at any time.
682
-
683
- ```javascript
684
- // Set the maximum number of concurrent peer connections.
685
- // Default: 3, Min: 1, Max: 50
686
- mesh.setMaxPeers(10);
687
-
688
- // Set the minimum number of connections to maintain for network health.
689
- // Default: 2, Min: 0, Max: 49
690
- mesh.setMinPeers(2);
691
-
692
- // Enable or disable automatic connection to newly discovered peers.
693
- // Default: true
694
- mesh.setAutoDiscovery(true);
695
-
696
- // Enable or disable the smart eviction strategy to optimize topology.
697
- // Default: true
698
- mesh.setEvictionStrategy(true);
699
-
700
- // Enable or disable XOR distance-based routing for peer selection.
701
- // Default: true
702
- mesh.setXorRouting(true);
703
-
704
- // Enable or disable the WebDHT (Distributed Hash Table) functionality.
705
- // When disabled, all DHT methods will throw errors with helpful messages.
706
- // Default: true (enabled)
707
- // Can only be set during initialization in constructor options
708
- const mesh = new PeerPigeonMesh({ enableWebDHT: false }); // Disable DHT
709
-
710
- // Set the signaling connection type. Currently only 'websocket' is supported.
711
- // Default: 'websocket'
712
- mesh.setConnectionType('websocket');
128
+ // Peers on hub2 can discover peers on hub1!
713
129
  ```
714
130
 
715
- ### Network & Peer Information
716
- Retrieve information about the network state and connected peers.
131
+ ## 📖 Documentation
717
132
 
718
- ```javascript
719
- // Get a comprehensive status object with the current state of the mesh.
720
- // See "Status Object Structure" below for details.
721
- const status = mesh.getStatus();
133
+ ### Core Guides
134
+ - **[API Documentation](docs/API_DOCUMENTATION.md)** - Complete API reference
135
+ - **[CLI Guide](docs/CLI_README.md)** - Command-line interface
136
+ - **[Network Namespaces](docs/NETWORK_NAMESPACES.md)** - Isolated peer networks
137
+ - **[Selective Streaming](docs/SELECTIVE_STREAMING_GUIDE.md)** - Media streaming optimization
722
138
 
723
- // Get the number of currently connected peers.
724
- const count = mesh.getConnectedPeerCount();
139
+ ### Hub System
140
+ - **[Hub System Overview](docs/HUB_SYSTEM.md)** - Multi-server mesh architecture
141
+ - **[Hub Quick Reference](docs/HUB_QUICK_REF.md)** - Quick start guide for hubs
142
+ - **[Hub Scripts](docs/HUB_SCRIPTS.md)** - Hub automation scripts
143
+ - **[Bootstrap Hubs](docs/BOOTSTRAP_HUBS.md)** - Hub discovery and connection
725
144
 
726
- // Get an array of peer IDs for all connected peers.
727
- const peers = mesh.getPeers();
145
+ ### Examples
146
+ - **[Browser Examples](examples/browser/)** - Web applications
147
+ - **[Node.js Examples](examples/node/)** - Server-side usage
148
+ - **[NativeScript Examples](examples/nativescript/)** - Mobile apps
728
149
 
729
- // Get an array of peer IDs for all discovered but not-yet-connected peers.
730
- const discovered = mesh.getDiscoveredPeers();
150
+ ## 🏗️ Architecture
731
151
 
732
- // Check if the mesh can accept new incoming connections (i.e., not at maxPeers).
733
- const canAccept = mesh.canAcceptMorePeers();
152
+ PeerPigeon uses a modular architecture with smart routing:
734
153
 
735
- // Check if a peer is currently connected.
736
- const isConnected = mesh.hasPeer(peerId);
737
154
  ```
738
-
739
- ### Messaging
740
- Send messages to other peers in the network.
741
-
742
- ```javascript
743
- // Broadcast a message to the entire mesh network using the gossip protocol.
744
- // Returns a unique ID for the message.
745
- const messageId = mesh.sendMessage(content);
155
+ ┌─────────────────────────────────────────────┐
156
+ │ PeerPigeonMesh (Core) │
157
+ ├─────────────────────────────────────────────┤
158
+ │ • SignalingClient • PeerDiscovery │
159
+ │ • ConnectionManager • EvictionManager │
160
+ │ • GossipManager • MeshOptimizer │
161
+ │ • StorageManager • MediaManager │
162
+ └─────────────────────────────────────────────┘
163
+ │ │
164
+ ▼ ▼
165
+ ┌──────────────┐ ┌──────────────┐
166
+ │ WebSocket │ │ WebRTC │
167
+ │ Signaling │ │ DataChannel │
168
+ └──────────────┘ └──────────────┘
746
169
  ```
747
170
 
748
- ### Manual Peer Management
749
- Manually control connections to specific peers.
750
- ```
171
+ **Key Components:**
172
+ - **XOR Distance Routing** - Kademlia-inspired peer selection
173
+ - **Gossip Protocol** - Reliable message propagation
174
+ - **Smart Eviction** - Automatically optimizes mesh topology
175
+ - **CRDT Storage** - Conflict-free distributed data structures
751
176
 
752
- ### Event System
177
+ ## 🔧 Advanced Configuration
753
178
 
754
179
  ```javascript
755
- // === Connection Events ===
756
- mesh.addEventListener('peerConnected', (event) => {
757
- console.log(`✅ Peer connected: ${event.peerId.substring(0, 8)}...`);
758
- });
759
-
760
- mesh.addEventListener('peerDisconnected', (event) => {
761
- console.log(`❌ Peer disconnected: ${event.peerId.substring(0, 8)}... (${event.reason})`);
762
- });
763
-
764
- mesh.addEventListener('peerDiscovered', (event) => {
765
- console.log(`🔍 Peer discovered: ${event.peerId.substring(0, 8)}...`);
766
- });
767
-
768
- // === Messaging Events ===
769
- mesh.addEventListener('messageReceived', (event) => {
770
- console.log(`💬 Message from ${event.from.substring(0, 8)}...: "${event.content}"`);
771
- console.log(` Direct: ${event.direct}, Hops: ${event.hops || 0}`);
772
- });
773
-
774
- // === Network Events ===
775
- mesh.addEventListener('peerEvicted', (event) => {
776
- console.log(`🔄 Peer evicted: ${event.peerId.substring(0, 8)}... (${event.reason})`);
777
- });
778
-
779
- mesh.addEventListener('statusChanged', (event) => {
780
- console.log(`📊 Status: ${event.type} - ${event.message}`);
781
- });
782
-
783
- mesh.addEventListener('peersUpdated', () => {
784
- console.log(`📈 Peer list updated - Connected: ${mesh.getConnectedPeerCount()}`);
785
- });
786
- ```
787
-
788
- ### Status Object Structure
789
-
790
- ```javascript
791
- const status = mesh.getStatus();
792
- // Returns:
793
- {
794
- peerId: "abc123...", // Our peer ID
795
- connected: true, // Connected to signaling server
796
- connectedCount: 3, // Number of connected peers
797
- discoveredCount: 5, // Number of discovered peers
798
- maxPeers: 10, // Maximum peer limit
799
- minPeers: 2, // Minimum peer target
800
- autoDiscovery: true, // Auto-discovery enabled
801
- evictionStrategy: true, // Smart eviction enabled
802
- xorRouting: true, // XOR-based routing enabled
803
- connectionType: "websocket", // Current signaling method
804
- signalingUrl: "wss://...", // Signaling server URL
805
- uptime: 120000 // Milliseconds since connection
806
- }
807
- ```
808
-
809
- ## 🌐 Network Topology & XOR Routing
810
-
811
- ### XOR Distance Calculation
812
-
813
- PeerPigeon uses XOR distance (inspired by Kademlia DHT) to determine peer relationships:
814
-
815
- ```javascript
816
- // Example XOR distance calculation
817
- function calculateXorDistance(peerId1, peerId2) {
818
- let distance = 0n;
819
- for (let i = 0; i < Math.min(peerId1.length, peerId2.length); i += 2) {
820
- const byte1 = parseInt(peerId1.substr(i, 2), 16);
821
- const byte2 = parseInt(peerId2.substr(i, 2), 16);
822
- const xor = byte1 ^ byte2;
823
- distance = (distance << 8n) | BigInt(xor);
824
- }
825
- return distance;
826
- }
827
-
828
- // Peer A: 0x1234abcd...
829
- // Peer B: 0x1345cdef...
830
- // XOR: 0x0071661e... (smaller = closer)
831
- ```
832
-
833
- ### Topology Example
834
-
835
- ```mermaid
836
- graph TB
837
- subgraph MeshNetwork[Mesh Network with XOR Distance Optimization]
838
- A[Peer A: 0x1234...]
839
- B[Peer B: 0x1345...]
840
- C[Peer C: 0x5678...]
841
- D[Peer D: 0x9ABC...]
842
- E[Peer E: 0x9BCD...]
843
- end
844
-
845
- A -->|Direct connection XOR small| B
846
- A -->|Direct connection XOR medium| C
847
- A -.->|Would connect if capacity| D
848
-
849
- B -->|Direct connection XOR small| A
850
- B -->|Direct connection XOR large| C
851
-
852
- C -->|Direct connection XOR medium| A
853
- C -->|Direct connection XOR large| B
854
- C -.->|Would evict B for| D
855
-
856
- D -.->|Very close XOR distance| E
857
- D -->|Would connect to| C
858
-
859
- E -.->|Very close XOR distance| D
860
- E -->|Would evict distant peer to connect to D| D
861
-
862
- style A fill:#e1f5fe,color:#000000
863
- style B fill:#e8f5e8,color:#000000
864
- style C fill:#fff3e0,color:#000000
865
- style D fill:#fce4ec,color:#000000
866
- style E fill:#f3e5f5,color:#000000
867
- ```
868
-
869
- ### XOR Distance Benefits
870
-
871
- 1. **Optimal Peer Selection**: Peers with smaller XOR distances are preferred for connections
872
- 2. **Efficient Message Routing**: Gossip protocol naturally routes through relevant connections
873
- 3. **Scalable Discovery**: New peers only notify the closest existing peers, reducing overhead
874
- 4. **Network Resilience**: Multiple paths through the mesh ensure message delivery
875
- 5. **Cost Optimization**: Reduces signaling server load by ~95% through smart peer targeting
876
-
877
- ### Isolation Prevention
878
-
879
- The isolation prevention mechanism ensures network connectivity:
880
-
881
- ```javascript
882
- // Isolation override logic in PeerDiscovery
883
- if (currentConnectionCount === 0 && discoveredPeers.length > 0) {
884
- // Step 1: Try to connect to peers where we're the natural initiator
885
- const naturalInitiators = discoveredPeers.filter(peerId => this.peerId > peerId);
886
-
887
- if (naturalInitiators.length > 0) {
888
- // Connect to natural targets first
889
- return naturalInitiators.includes(targetPeerId);
890
- }
891
-
892
- // Step 2: If no natural targets, connect to closest peer by XOR distance
893
- const sortedByDistance = discoveredPeers.sort((a, b) => {
894
- const distA = calculateXorDistance(this.peerId, a);
895
- const distB = calculateXorDistance(this.peerId, b);
896
- return distA < distB ? -1 : 1;
897
- });
898
-
899
- return sortedByDistance[0] === targetPeerId;
900
- }
901
- ```
902
-
903
- ## 🔗 WebSocket Signaling
904
-
905
- PeerPigeon uses WebSocket signaling for real-time, bidirectional communication:
906
-
907
- ### WebSocket Signaling - Real-time Communication
908
- - **Real-time delivery**: Instant bidirectional message delivery
909
- - **Cost-efficient**: Persistent connections reduce connection overhead
910
- - **Modern browsers**: Chrome, Firefox, Safari, Edge with full support
911
- - **Use case**: Production applications requiring real-time performance
912
-
913
- ```javascript
914
- // WebSocket signaling is used by default
915
- const mesh = new PeerPigeonMesh();
916
- await mesh.connect('wss://your-websocket-server.com');
917
-
918
- // WebSocket connection automatically handles:
919
- // - Real-time peer discovery notifications
920
- // - WebRTC signaling message delivery
921
- // - Bidirectional communication
922
- // - Connection state management
923
- ```
924
-
925
- ### WebSocket Protocol Messages
926
-
927
- The WebSocket signaling supports these message types:
928
-
929
- | Message Type | Purpose | Data Structure |
930
- |--------------|---------|----------------|
931
- | `announce` | Peer joins network | `{peerId, timestamp}` |
932
- | `goodbye` | Peer leaves network | `{peerId, timestamp}` |
933
- | `offer` | WebRTC connection offer | `{type: 'offer', data: RTCSessionDescription, targetPeerId}` |
934
- | `answer` | WebRTC connection answer | `{type: 'answer', data: RTCSessionDescription, targetPeerId}` |
935
- | `ice-candidate` | ICE candidate exchange | `{type: 'ice-candidate', data: RTCIceCandidate, targetPeerId}` |
936
- | `cleanup` | Remove processed messages | `{type: 'cleanup', reason}` |
937
-
938
- ## 🚀 Deployment Options
939
-
940
- ### Option 1: Custom Signaling Server
941
-
942
- Implement your own signaling server with these required endpoints:
943
-
944
- ```typescript
945
- // Required endpoints for custom signaling server
946
-
947
- // WebSocket connection endpoint
948
- wss://your-server.com/signaling?peerId={peerId}
949
-
950
- // WebSocket message format for all signaling messages:
951
- {
952
- "type": "offer|answer|ice-candidate|announce|goodbye|ping",
953
- "data": "message-specific-data",
954
- "fromPeerId": "sender-peer-id",
955
- "targetPeerId": "recipient-peer-id", // optional for broadcasts
956
- "timestamp": 1234567890
957
- }
958
- ```
959
-
960
- ### Option 2: Development/Testing Setup
961
-
962
- For local development and testing:
963
-
964
- ```bash
965
- For local development and testing:
966
-
967
- ```bash
968
- # Serve with npm (preferred)
969
- npm run dev
970
-
971
- # Or with Node.js http-server
972
- npm install -g http-server
973
- http-server -p 8080
974
- ```
975
-
976
- # Use query parameters to pre-configure signaling
977
- open "http://localhost:8080/examples/browser/?api=wss://your-signaling-server.com/dev"
978
- ```
979
-
980
- **Development Features:**
981
- - Browser debugging tools integration
982
- - Console logging with peer ID prefixes
983
- - Global mesh access via `window.peerPigeonMesh`
984
- - Force connection utilities for testing
985
- - Real-time peer discovery and connection monitoring
986
-
987
- ## 🌐 Platform Compatibility & Requirements
988
-
989
- ### Supported Platforms
990
-
991
- | Platform | Environment | WebRTC Support | WebSocket Support | Status |
992
- |---------|-------------|----------------|-------------------|---------|
993
- | **Web Browsers** | Modern browsers | ✅ Native | ✅ Native | **Full Support** |
994
- | **Node.js** | Server-side | ⚠️ Via plugin | ✅ Via 'ws' | **Supported** |
995
- | **NativeScript** | Mobile apps | ⚠️ Via plugin | ✅ Native/Plugin | **Supported** |
996
- | **Web Workers** | Browser workers | ✅ Limited | ✅ Yes | **Basic Support** |
997
-
998
- ### Browser Compatibility
999
-
1000
- | Browser | Minimum Version | WebRTC Support | WebSocket Support | Status |
1001
- |---------|----------------|----------------|-------------------|---------|
1002
- | **Chrome** | 80+ | ✅ Full | ✅ Yes | **Recommended** |
1003
- | **Firefox** | 75+ | ✅ Full | ✅ Yes | **Recommended** |
1004
- | **Safari** | 14+ | ✅ Full | ✅ Yes | **Supported** |
1005
- | **Edge** | 80+ | ✅ Full | ✅ Yes | **Supported** |
1006
- | **Mobile Chrome** | 80+ | ✅ Full | ✅ Yes | **Supported** |
1007
- | **Mobile Safari** | 14+ | ✅ Full | ✅ Yes | **Supported** |
1008
-
1009
- ### Required Features
1010
- - **WebRTC**: RTCPeerConnection and RTCDataChannel support
1011
- - **ES6 Modules**: Dynamic imports and module syntax
1012
- - **Crypto API**: For cryptographically secure peer ID generation
1013
- - **WebSocket API**: For real-time signaling communication
1014
-
1015
- ### NativeScript Support
1016
-
1017
- PeerPigeon includes comprehensive NativeScript support:
1018
-
1019
- ```javascript
1020
- // NativeScript usage (same API as browser)
1021
- import { PeerPigeonMesh } from 'peerpigeon';
1022
-
1023
- const mesh = new PeerPigeonMesh();
1024
- await mesh.init(); // Automatically detects NativeScript environment
1025
-
1026
- // Environment detection
1027
- console.log('Environment:', mesh.environmentReport.runtime);
1028
- // { isNativeScript: true, platform: 'android' }
1029
- ```
1030
-
1031
- **NativeScript Features:**
1032
- - ✅ Environment detection with platform info (Android/iOS/visionOS)
1033
- - ✅ WebSocket signaling (native or via plugin)
1034
- - ✅ Storage management using NativeScript APIs
1035
- - ✅ Basic mesh networking capabilities
1036
- - ⚠️ WebRTC requires additional native plugins
1037
- - ⚠️ Media features require camera/microphone permissions
1038
-
1039
- See the [NativeScript example](examples/nativescript/) for complete setup instructions.
1040
-
1041
- ### Feature Detection
1042
-
1043
- PeerPigeon automatically detects browser capabilities:
1044
-
1045
- ```javascript
1046
- // Automatic capability detection
1047
- const mesh = new PeerPigeonMesh();
1048
- await mesh.init(); // Detects WebRTC, WebSocket support
1049
-
1050
- // Check detected capabilities
1051
- const status = mesh.getStatus();
1052
- console.log('Connection type:', status.connectionType); // 'websocket'
1053
- console.log('WebRTC support:', mesh.hasWebRTCSupport());
1054
- console.log('WebSocket support:', mesh.hasWebSocketSupport());
1055
- ```
1056
-
1057
- ## ⚡ Performance & Scalability
1058
-
1059
- ### Network Efficiency
1060
- - **Gossip TTL**: Messages expire after 10 hops to prevent network flooding
1061
- - **XOR Routing**: Only relevant peers receive discovery notifications (~95% reduction)
1062
- - **Connection Limits**: Configurable peer limits prevent resource exhaustion
1063
- - **Smart Eviction**: Maintains optimal topology without unnecessary reconnections
1064
-
1065
- ### Performance Metrics
1066
- Based on testing with browser networks:
1067
-
1068
- | Network Size | Avg Connection Time | Message Delivery | Memory Usage |
1069
- |--------------|-------------------|------------------|--------------|
1070
- | 2-5 peers | < 2 seconds | 100% success | ~5MB per peer |
1071
- | 6-10 peers | 2-4 seconds | 99.8% success | ~8MB per peer |
1072
- | 11-15 peers | 3-6 seconds | 99.5% success | ~12MB per peer |
1073
-
1074
- ### Best Practices for Performance
1075
-
1076
- 1. **Optimal Peer Limits**
1077
- ```javascript
1078
- // For most applications
1079
- mesh.setMaxPeers(8); // Sweet spot for connectivity vs resources
1080
- mesh.setMinPeers(3); // Ensures network resilience
1081
- ```
1082
-
1083
- 2. **Enable All Optimizations**
1084
- ```javascript
1085
- mesh.setEvictionStrategy(true); // Maintains optimal topology
1086
- mesh.setXorRouting(true); // Reduces signaling overhead
1087
- mesh.setAutoDiscovery(true); // Handles connections automatically
1088
- ```
1089
-
1090
- 3. **Monitor Connection Health**
1091
- ```javascript
1092
- mesh.addEventListener('statusChanged', (event) => {
1093
- if (event.type === 'warning') {
1094
- console.warn('Network issue:', event.message);
1095
- // Implement reconnection logic
1096
- }
1097
- });
1098
- ```
1099
-
1100
- ## 🔒 Security Considerations
1101
-
1102
- ### Built-in Security Features
1103
- - **Peer ID Generation**: Uses `crypto.getRandomValues()` for cryptographically secure peer IDs
1104
- - **WebRTC Encryption**: Built-in DTLS encryption for all peer-to-peer communication
1105
- - **Input Validation**: All peer IDs and messages are validated before processing
1106
- - **Message Limits**: TTL and size limits prevent abuse and resource exhaustion
1107
-
1108
- ### Deployment Security
1109
-
1110
- #### Signaling Server Security
1111
- ```bash
1112
- # Always use HTTPS/WSS for signaling endpoints
1113
- https://your-signaling-server.com/signaling # ✅ Secure
1114
- http://your-signaling-server.com/signaling # ❌ Insecure
1115
-
1116
- # Implement rate limiting
1117
- POST /signaling
1118
- X-Rate-Limit: 100 requests per minute per IP
1119
- ```
1120
-
1121
- ### Security Best Practices
1122
-
1123
- 1. **Validate All Inputs**
1124
- ```javascript
1125
- // PeerPigeon automatically validates:
1126
- // - Peer ID format (hexadecimal, correct length)
1127
- // - Message content (type, size limits)
1128
- // - WebRTC message structure
1129
- ```
1130
-
1131
- 2. **Implement Application-Level Security**
1132
- ```javascript
1133
- // Add your own message authentication
1134
- mesh.addEventListener('messageReceived', (event) => {
1135
- if (!validateMessageSignature(event.content, event.from)) {
1136
- console.warn('Ignoring message with invalid signature');
1137
- return;
1138
- }
1139
- // Process trusted message
1140
- });
1141
- ```
1142
-
1143
- 3. **Monitor for Abuse**
1144
- ```javascript
1145
- // Track message frequency per peer
1146
- const messageRates = new Map();
1147
- mesh.addEventListener('messageReceived', (event) => {
1148
- const rate = trackMessageRate(event.from);
1149
- if (rate > MAX_MESSAGES_PER_MINUTE) {
1150
- mesh.disconnectPeer(event.from, 'rate limit exceeded');
1151
- }
1152
- });
1153
- ```
1154
-
1155
- ## 🛠️ Development & Debugging
1156
-
1157
- ### Running Tests
1158
-
1159
- ```bash
1160
- # Install development dependencies
1161
- npm install
1162
-
1163
- # Start local development server
1164
- npm run dev
1165
- # or
1166
- npx http-server -p 8080
1167
-
1168
- # Open multiple browser tabs for testing
1169
- open http://localhost:8080/examples/browser/
1170
- open http://localhost:8080/examples/browser/
1171
- open http://localhost:8080/examples/browser/
1172
- ```
1173
-
1174
- ### Debugging Tools
1175
-
1176
- #### Built-in Debugging
1177
- ```javascript
1178
- // Global mesh access in browser
1179
- window.peerPigeonMesh.getStatus(); // Network status
1180
- window.peerPigeonMesh.getPeers(); // Connected peers
1181
- window.peerPigeonMesh.getDiscoveredPeers(); // Discovered peers
1182
- window.peerPigeonMesh.debugConnectivity(); // Detailed connectivity info
1183
-
1184
- // Force connections for testing
1185
- window.peerPigeonMesh.forceConnectToAllPeers();
1186
-
1187
- // Component access
1188
- window.peerPigeonSignaling; // SignalingClient instance
1189
- window.getPeerPigeonState(); // Complete application state
1190
- ```
1191
-
1192
- #### Browser Developer Tools
1193
- 1. **Console Logs**: Detailed connection and message flow with peer ID prefixes
1194
- 2. **Network Tab**: Monitor signaling server communication patterns
1195
- 3. **WebRTC Internals**: Chrome's `chrome://webrtc-internals/` for connection debugging
1196
- 4. **Application Tab**: LocalStorage inspection for persistent state
1197
-
1198
- #### Debugging Common Issues
1199
-
1200
- **Connection Problems:**
1201
- ```javascript
1202
- // Check connection prerequisites
1203
- console.log('Signaling connected:', mesh.getStatus().connected);
1204
- console.log('Discovered peers:', mesh.getDiscoveredPeers().length);
1205
- console.log('Connection attempts:', mesh.getConnectionAttempts());
1206
-
1207
- // Force retry connections
1208
- mesh.getDiscoveredPeers().forEach(peer => {
1209
- if (!mesh.hasPeer(peer.peerId)) {
1210
- mesh.connectToPeer(peer.peerId);
1211
- }
1212
- });
1213
- ```
1214
-
1215
- **Message Delivery Issues:**
1216
- ```javascript
1217
- // Check gossip protocol state
1218
- mesh.addEventListener('messageReceived', (event) => {
1219
- console.log('Message path:', event.path);
1220
- console.log('TTL remaining:', event.ttl);
1221
- console.log('Seen messages:', mesh.gossipManager.seenMessages.size);
1222
- });
1223
- ```
1224
-
1225
- ## 🧪 Testing & Development
1226
-
1227
- PeerPigeon includes a comprehensive testing framework with unit tests, integration tests, performance benchmarks, and automated CI/CD pipeline.
1228
-
1229
- ### Quick Start
180
+ const mesh = new PeerPigeonMesh({
181
+ // Core options
182
+ peerId: 'custom-peer-id', // Custom peer ID (40-char hex)
183
+ networkName: 'my-network', // Network namespace (default: 'global')
184
+ allowGlobalFallback: true, // Allow fallback to global network
185
+
186
+ // Features (all enabled by default)
187
+ enableWebDHT: true, // Distributed hash table
188
+ enableCrypto: true, // Encryption & key management
189
+
190
+ // Connection settings
191
+ maxPeers: 3, // Max concurrent connections
192
+ minPeers: 2, // Min connections to maintain
193
+ autoConnect: true, // Auto-connect on join
194
+ autoDiscovery: true, // Auto-discover peers
195
+
196
+ // Topology optimization
197
+ evictionStrategy: true, // Smart peer eviction
198
+ xorRouting: true // XOR distance-based routing
199
+ });
200
+ ```
201
+
202
+ ## 🧪 Testing
1230
203
 
1231
204
  ```bash
1232
- # Install dependencies
1233
- npm install
1234
-
1235
205
  # Run all tests
1236
206
  npm test
1237
207
 
1238
- # Run specific test suites
1239
- npm run test:unit # Unit tests only
1240
- npm run test:integration # Integration tests only
1241
- npm run test:custom # Custom test runners
1242
-
1243
- # Run with coverage
1244
- npm run test:coverage
208
+ # Browser integration tests
209
+ npm run test:browser
210
+ npm run test:browser:visual # With visible browser
1245
211
 
1246
- # Performance benchmarks
1247
- npm run benchmark
1248
-
1249
- # Linting
1250
- npm run lint
1251
- npm run lint:fix # Auto-fix issues
1252
-
1253
- # Full CI pipeline
1254
- npm run ci
1255
- ```
1256
-
1257
- ### Test Structure
1258
-
1259
- ```
1260
- test/
1261
- ├── unit/ # Unit tests (16 tests)
1262
- │ ├── crypto.test.js # CryptoManager tests (7 tests)
1263
- │ └── mesh.test.js # PeerPigeonMesh tests (9 tests)
1264
- ├── integration/ # Integration tests (7 tests)
1265
- │ ├── simple.test.js # Integration scenarios
1266
- │ └── integration-runner.js # Custom test runner
1267
- ├── setup.js # Jest configuration
1268
- ├── runner.js # Comprehensive test runner
1269
- └── benchmark.js # Performance benchmarks
1270
- ```
1271
-
1272
- ### Testing Framework Features
1273
-
1274
- - **🔧 Custom Test Runners**: Built-in Node.js test runners for comprehensive testing
1275
- - **🃏 Jest Integration**: Modern testing framework with ES modules support and coverage reporting
1276
- - **📊 Coverage Reports**: Detailed HTML and LCOV coverage reports
1277
- - **⚡ Performance Benchmarks**: Crypto operations, mesh performance, and memory usage
1278
- - **🔍 Linting**: ESLint with standard configuration (0 errors, 0 warnings)
1279
- - **🤖 CI/CD Pipeline**: Automated testing with proper resource cleanup
1280
- - **🛠️ Clean Test Termination**: All tests complete without hanging processes
1281
- - **⚡ Fast Execution**: Unit tests ~0.26s, full suite ~1.2s
1282
-
1283
- ### Available Commands
1284
-
1285
- ```bash
1286
- # Using npm scripts
1287
- npm test # Jest tests (23/23 passing)
1288
- npm run test:unit # Unit tests (16/16 passing)
1289
- npm run test:integration # Integration tests (7/7 passing)
1290
- npm run test:custom # Custom test runners
1291
- npm run test:all # Comprehensive test suite
1292
- npm run test:coverage # Coverage analysis
1293
- npm run test:watch # Watch mode
1294
- npm run lint # ESLint (0 errors, 0 warnings)
1295
- npm run lint:fix # Auto-fix linting issues
1296
- npm run benchmark # Performance benchmarks
1297
- npm run ci # Full CI pipeline
1298
-
1299
- # Using Makefile (shorter commands)
1300
- make test # Run tests
1301
- make lint # Run linting
1302
- make benchmark # Run benchmarks
1303
- make coverage # Generate coverage
1304
- make ci # Full CI check
1305
- make help # Show all commands
1306
- ```
1307
-
1308
- ### Test Categories
1309
-
1310
- #### Unit Tests (16 tests passing)
1311
- - **CryptoManager (7 tests)**: Encryption, decryption, key generation, signing
1312
- - **PeerPigeonMesh (9 tests)**: Core mesh functionality, message routing
1313
- - **Resource Management**: Timer cleanup, proper disconnection
1314
- - **Memory Safety**: No memory leaks or hanging processes
1315
-
1316
- #### Integration Tests (7 tests passing)
1317
- - **Peer Discovery**: Network join/leave scenarios
1318
- - **Message Propagation**: End-to-end gossip protocol testing
1319
- - **Network Resilience**: Connection management and cleanup
1320
- - **Multi-Peer Scenarios**: Real-world mesh networking tests
1321
-
1322
- #### Performance Benchmarks
1323
- - **Crypto Performance**: Key generation, encryption/decryption speed
1324
- - **Mesh Operations**: Peer connection, message routing efficiency
1325
- - **Memory Usage**: Memory leak detection, resource management
1326
- - **Network Performance**: Message throughput, latency analysis
1327
-
1328
- ### Coverage Reports
1329
-
1330
- After running `npm run test:coverage`, open `coverage/index.html` to view detailed coverage reports including:
1331
-
1332
- - Line coverage
1333
- - Function coverage
1334
- - Branch coverage
1335
- - Statement coverage
1336
-
1337
- ### Continuous Integration
1338
-
1339
- The project includes GitHub Actions workflows for:
1340
-
1341
- - **Multiple Node.js versions** (18.x, 20.x, 22.x)
1342
- - **Automated testing** on push/PR
1343
- - **Security audits**
1344
- - **Performance benchmarking**
1345
- - **Coverage reporting**
1346
-
1347
- ### Browser Testing Scenarios
1348
-
1349
- #### Multi-Tab Testing
1350
- ```bash
1351
- # Open multiple browser tabs for mesh testing
1352
- npm run dev
1353
-
1354
- # In separate terminal, open tabs
1355
- for i in {1..5}; do
1356
- open "http://localhost:8080/examples/browser/?debug=true&tab=$i"
1357
- done
1358
- ```
1359
-
1360
- #### Network Partition Testing
1361
- ```javascript
1362
- // Simulate network partition in browser console
1363
- mesh.disconnectPeer(specificPeerId, 'testing partition');
1364
-
1365
- // Monitor reconnection behavior
1366
- mesh.on('peerReconnected', (peerId) => {
1367
- console.log('Peer reconnected after partition:', peerId);
1368
- });
1369
- ```
1370
-
1371
- #### Encryption Testing
1372
- ```javascript
1373
- // Test encryption in browser
1374
- await mesh.crypto.generateKeyPair();
1375
- const encrypted = await mesh.encryptMessage('test message', targetPeerId);
1376
- const decrypted = await mesh.decryptMessage(encrypted, senderPeerId);
1377
- console.log('Encryption test:', decrypted === 'test message');
1378
- ```
1379
- setTimeout(() => {
1380
- console.log('Network recovered, connections:', mesh.getConnectedPeerCount());
1381
- }, 10000);
1382
- ```
1383
-
1384
- #### Load Testing
1385
- ```javascript
1386
- // Send messages rapidly to test gossip protocol
1387
- setInterval(() => {
1388
- mesh.sendMessage(`Load test message ${Date.now()}`);
1389
- }, 1000);
212
+ # Video streaming tests
213
+ npm run test:video
214
+ npm run test:video:visual # With visible browser
1390
215
  ```
1391
216
 
1392
217
  ## 🤝 Contributing
1393
218
 
1394
- We welcome contributions! Here's how to get started:
1395
-
1396
- ### Development Setup
1397
- ```bash
1398
- # Fork and clone the repository
1399
- git clone https://github.com/your-username/pigon.git
1400
- cd pigon
1401
-
1402
- # Create a feature branch
1403
- git checkout -b feature/amazing-improvement
1404
-
1405
- # Make your changes and test thoroughly
1406
- npm run dev
1407
- # Test with multiple browser instances
1408
-
1409
- # Commit with descriptive messages
1410
- git commit -m "Add isolation prevention to peer discovery
1411
-
1412
- - Implements lexicographic override when peer has no connections
1413
- - Prioritizes natural initiators over XOR distance
1414
- - Prevents permanent isolation in small networks
1415
- - Adds comprehensive logging for debugging"
1416
-
1417
- # Push and create pull request
1418
- git push origin feature/amazing-improvement
1419
- ```
1420
-
1421
- ### Contribution Guidelines
1422
-
1423
- 1. **Test with Multiple Peers**: Always test changes with 3-5 browser instances
1424
- 2. **Maintain Backward Compatibility**: Don't break existing API contracts
1425
- 3. **Add Comprehensive Logging**: Use consistent peer ID prefixes in logs
1426
- 4. **Update Documentation**: Include code examples and explanations
1427
- 5. **Follow Code Style**: Use consistent formatting and naming conventions
1428
-
1429
- ### Areas for Contribution
1430
- - **Performance Optimization**: Improve connection speed and memory usage
1431
- - **Security Enhancements**: Add message authentication and rate limiting
1432
- - **Testing Framework**: Automated testing for mesh network scenarios
1433
- - **Mobile Optimization**: Improve performance on mobile browsers
1434
- - **Documentation**: Examples, tutorials, and API improvements
219
+ Contributions are welcome! Please read our contributing guidelines and submit pull requests to our [GitHub repository](https://github.com/PeerPigeon/PeerPigeon).
1435
220
 
1436
221
  ## 📄 License
1437
222
 
1438
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
223
+ MIT © Daniel Raeder
1439
224
 
1440
- ## 🙏 Acknowledgments
225
+ ## 🔗 Links
1441
226
 
1442
- - **Kademlia DHT**: Inspired the XOR distance routing algorithm ([Paper](https://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf))
1443
- - **WebRTC Community**: For providing the foundation of peer-to-peer communication
1444
- - **Gossip Protocols**: Epidemic algorithms research for reliable message propagation
1445
- - **Open Source Community**: For feedback, testing, and continuous improvement
227
+ - **GitHub**: [github.com/PeerPigeon/PeerPigeon](https://github.com/PeerPigeon/PeerPigeon)
228
+ - **npm**: [npmjs.com/package/peerpigeon](https://www.npmjs.com/package/peerpigeon)
229
+ - **Issues**: [github.com/PeerPigeon/PeerPigeon/issues](https://github.com/PeerPigeon/PeerPigeon/issues)
1446
230
 
1447
231
  ---
1448
232
 
1449
- **Quick Links:**
1450
- - [Live Demo](http://localhost:8080/examples/browser/) (after starting local server)
1451
- - [Browser Examples](examples/browser/) - Complete web-based examples
1452
- - [Node.js Examples](examples/node/) - Server-side examples
1453
- - [NativeScript Examples](examples/nativescript/) - Mobile app examples
1454
- - [API Documentation](docs/API.md)
1455
- - [Deployment Guide](docs/DEPLOYMENT.md)
1456
- - [GitHub Issues](https://github.com/danrayadev/pigon/issues)
1457
- - [Contributing Guidelines](CONTRIBUTING.md)
233
+ **Built with ❤️ for the decentralized web**