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.
- package/README.md +141 -1365
- package/cli.js +1382 -0
- package/dist/peerpigeon-browser.js +12450 -0
- package/dist/peerpigeon-browser.js.map +7 -0
- package/docs/API_DOCUMENTATION.md +1976 -0
- package/docs/BOOTSTRAP_HUBS.md +319 -0
- package/docs/CLI_README.md +371 -0
- package/docs/CUSTOM_HUB_NAMESPACES.md +182 -0
- package/docs/CUSTOM_NAMESPACE_IMPLEMENTATION.md +187 -0
- package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
- package/docs/HUB_QUICK_REF.md +108 -0
- package/docs/HUB_SCRIPTS.md +341 -0
- package/docs/HUB_SYSTEM.md +599 -0
- package/docs/MIGRATION_COMPLETE.md +93 -0
- package/docs/NETWORK_NAMESPACES.md +212 -0
- package/docs/PIGEONRTC_MIGRATION.md +280 -0
- package/docs/README.md +108 -0
- package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
- package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
- package/examples/bootstrap-hub-example.js +292 -0
- package/examples/browser/README.md +278 -0
- package/examples/browser/app.js +2426 -49
- package/examples/browser/index.html +481 -630
- package/examples/browser/minimal/README.md +55 -0
- package/examples/browser/minimal/index.html +75 -0
- package/examples/browser/minimal/minimal.js +234 -0
- package/examples/browser/styles.css +687 -1425
- package/examples/browser/test-bundle.html +35 -0
- package/examples/browser-2/index.html +30 -0
- package/examples/browser-2/package.json +21 -0
- package/examples/browser-2/src/App-simple.vue +21 -0
- package/examples/browser-2/src/App.vue +420 -0
- package/examples/browser-2/src/components/CryptoView.vue +1661 -0
- package/examples/browser-2/src/components/DHTView.vue +1281 -0
- package/examples/browser-2/src/components/DebugView.vue +1773 -0
- package/examples/browser-2/src/components/MediaView.vue +1048 -0
- package/examples/browser-2/src/components/MessagingView.vue +775 -0
- package/examples/browser-2/src/components/NetworkView.vue +930 -0
- package/examples/browser-2/src/components/StorageView.vue +1376 -0
- package/examples/browser-2/src/main.js +5 -0
- package/examples/browser-2/src/stores/peerpigeon.js +895 -0
- package/examples/browser-2/vite.config.js +6 -0
- package/examples/hub-example.js +189 -0
- package/examples/multi-hub-test.js +186 -0
- package/examples/node/README.md +2 -2
- package/examples/programmatic-namespace-example.js +108 -0
- package/examples/selective-streaming-demo.html +698 -0
- package/examples/standard-events-demo.js +126 -0
- package/index.js +7 -1
- package/package.json +34 -16
- package/server/index.js +1058 -98
- package/server/start.js +52 -0
- package/src/ConnectionManager.js +239 -225
- package/src/CryptoManager.js +147 -18
- package/src/DebugLogger.js +0 -7
- package/src/DistributedStorageManager.js +224 -205
- package/src/EnvironmentDetector.js +88 -4
- package/src/EventEmitter.js +79 -1
- package/src/EvictionManager.js +10 -9
- package/src/GossipManager.js +163 -11
- package/src/MediaManager.js +12 -2
- package/src/PeerConnection.js +343 -311
- package/src/PeerPigeonMesh.js +576 -135
- package/src/PigeonRTC-browser.js +247 -0
- package/src/SignalingClient.js +14 -243
- package/src/SignalingHandler.js +31 -10
- package/src/StorageManager.js +0 -39
- package/src/WebDHT-Simple.js +389 -0
- package/src/WebDHT.js +363 -1165
- package/src/browser-entry.js +58 -0
- package/examples/browser/assets/images/favicon.png +0 -0
- package/examples/browser/assets/images/pigeon.png +0 -0
- package/examples/browser/crypto-test.html +0 -427
- package/examples/browser/ui-old.js +0 -1926
- package/examples/browser/ui.js +0 -3391
- package/websocket-server/README.md +0 -247
- 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
|
-
**
|
|
3
|
+
**WebRTC-based peer-to-peer mesh networking with intelligent routing, encrypted storage, and media streaming.**
|
|
4
4
|
|
|
5
5
|
[](https://badge.fury.io/js/peerpigeon)
|
|
6
6
|
[](https://opensource.org/licenses/MIT)
|
|
7
|
-
[](https://github.com/draeder/peerpigeon)
|
|
7
|
+
[](https://nodejs.org)
|
|
9
8
|
|
|
10
|
-
|
|
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
|
-
##
|
|
11
|
+
## ✨ Key Features
|
|
13
12
|
|
|
14
|
-
- **🕸️ True Mesh Networking
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
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
|
|
30
|
+
### Basic Usage
|
|
79
31
|
|
|
80
32
|
```javascript
|
|
81
33
|
import { PeerPigeonMesh } from 'peerpigeon';
|
|
82
34
|
|
|
83
|
-
// Create
|
|
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');
|
|
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
|
-
|
|
119
|
-
|
|
120
|
-
});
|
|
40
|
+
// Send messages
|
|
41
|
+
mesh.sendMessage('Hello, mesh!');
|
|
121
42
|
|
|
122
|
-
//
|
|
123
|
-
|
|
124
|
-
|
|
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
|
-
|
|
49
|
+
### Run Signaling Server
|
|
130
50
|
|
|
131
51
|
```bash
|
|
132
|
-
#
|
|
52
|
+
# Option 1: Use npm script
|
|
133
53
|
npm start
|
|
134
54
|
|
|
135
|
-
#
|
|
136
|
-
PORT=8080
|
|
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
|
-
|
|
205
|
-
|
|
58
|
+
# Option 3: Run as a hub (multi-server mesh)
|
|
59
|
+
npm run hub
|
|
206
60
|
```
|
|
207
61
|
|
|
208
|
-
|
|
62
|
+
## 📚 Examples
|
|
209
63
|
|
|
210
|
-
|
|
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
|
-
//
|
|
269
|
-
|
|
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
|
-
//
|
|
276
|
-
const
|
|
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
|
-
//
|
|
281
|
-
mesh.
|
|
282
|
-
|
|
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
|
-
###
|
|
78
|
+
### Selective Media Streaming
|
|
290
79
|
|
|
291
80
|
```javascript
|
|
292
|
-
//
|
|
293
|
-
|
|
294
|
-
|
|
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
|
-
|
|
302
|
-
|
|
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
|
-
//
|
|
306
|
-
mesh.
|
|
307
|
-
|
|
92
|
+
// Receive streams
|
|
93
|
+
mesh.media.on('remoteStreamAdded', ({ peerId, stream, label }) => {
|
|
94
|
+
videoElement.srcObject = stream;
|
|
308
95
|
});
|
|
309
96
|
```
|
|
310
97
|
|
|
311
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
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
|
-
|
|
552
|
-
|
|
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
|
-
|
|
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
|
-
|
|
716
|
-
Retrieve information about the network state and connected peers.
|
|
131
|
+
## 📖 Documentation
|
|
717
132
|
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
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
|
-
|
|
724
|
-
|
|
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
|
-
|
|
727
|
-
|
|
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
|
-
|
|
730
|
-
const discovered = mesh.getDiscoveredPeers();
|
|
150
|
+
## 🏗️ Architecture
|
|
731
151
|
|
|
732
|
-
|
|
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
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
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
|
-
|
|
749
|
-
|
|
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
|
-
|
|
177
|
+
## 🔧 Advanced Configuration
|
|
753
178
|
|
|
754
179
|
```javascript
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
//
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
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
|
-
#
|
|
1239
|
-
npm run test:
|
|
1240
|
-
npm run test:
|
|
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
|
-
#
|
|
1247
|
-
npm run
|
|
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
|
-
|
|
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
|
-
|
|
223
|
+
MIT © Daniel Raeder
|
|
1439
224
|
|
|
1440
|
-
##
|
|
225
|
+
## 🔗 Links
|
|
1441
226
|
|
|
1442
|
-
- **
|
|
1443
|
-
- **
|
|
1444
|
-
- **
|
|
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
|
-
**
|
|
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**
|