peerpigeon 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +141 -1365
  2. package/cli.js +1382 -0
  3. package/dist/peerpigeon-browser.js +12290 -0
  4. package/dist/peerpigeon-browser.js.map +7 -0
  5. package/docs/API_DOCUMENTATION.md +1945 -0
  6. package/docs/BOOTSTRAP_HUBS.md +319 -0
  7. package/docs/CLI_README.md +371 -0
  8. package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
  9. package/docs/HUB_QUICK_REF.md +107 -0
  10. package/docs/HUB_SCRIPTS.md +331 -0
  11. package/docs/HUB_SYSTEM.md +552 -0
  12. package/docs/MIGRATION_COMPLETE.md +93 -0
  13. package/docs/NETWORK_NAMESPACES.md +212 -0
  14. package/docs/README.md +107 -0
  15. package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
  16. package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
  17. package/examples/bootstrap-hub-example.js +292 -0
  18. package/examples/browser/README.md +278 -0
  19. package/examples/browser/app.js +2426 -49
  20. package/examples/browser/index.html +482 -543
  21. package/examples/browser/minimal/README.md +55 -0
  22. package/examples/browser/minimal/index.html +75 -0
  23. package/examples/browser/minimal/minimal.js +234 -0
  24. package/examples/browser/styles.css +687 -1425
  25. package/examples/browser/test-bundle.html +35 -0
  26. package/examples/browser-2/index.html +30 -0
  27. package/examples/browser-2/package.json +21 -0
  28. package/examples/browser-2/src/App-simple.vue +21 -0
  29. package/examples/browser-2/src/App.vue +420 -0
  30. package/examples/browser-2/src/components/CryptoView.vue +1661 -0
  31. package/examples/browser-2/src/components/DHTView.vue +1281 -0
  32. package/examples/browser-2/src/components/DebugView.vue +1773 -0
  33. package/examples/browser-2/src/components/MediaView.vue +1048 -0
  34. package/examples/browser-2/src/components/MessagingView.vue +775 -0
  35. package/examples/browser-2/src/components/NetworkView.vue +930 -0
  36. package/examples/browser-2/src/components/StorageView.vue +1376 -0
  37. package/examples/browser-2/src/main.js +5 -0
  38. package/examples/browser-2/src/stores/peerpigeon.js +895 -0
  39. package/examples/browser-2/vite.config.js +6 -0
  40. package/examples/hub-example.js +186 -0
  41. package/examples/multi-hub-test.js +186 -0
  42. package/examples/node/README.md +2 -2
  43. package/examples/node/storage-test.js +141 -6
  44. package/examples/selective-streaming-demo.html +698 -0
  45. package/examples/standard-events-demo.js +126 -0
  46. package/package.json +33 -16
  47. package/server/index.js +1032 -98
  48. package/server/start.js +49 -0
  49. package/src/ConnectionManager.js +239 -225
  50. package/src/CryptoManager.js +147 -18
  51. package/src/DebugLogger.js +0 -7
  52. package/src/DistributedStorageManager.js +245 -205
  53. package/src/EnvironmentDetector.js +109 -2
  54. package/src/EventEmitter.js +79 -1
  55. package/src/EvictionManager.js +10 -9
  56. package/src/GossipManager.js +163 -11
  57. package/src/LexicalStorageInterface.js +332 -0
  58. package/src/PeerConnection.js +333 -310
  59. package/src/PeerPigeonMesh.js +577 -135
  60. package/src/SignalingClient.js +14 -243
  61. package/src/SignalingHandler.js +31 -10
  62. package/src/StorageManager.js +0 -39
  63. package/src/WebDHT-Simple.js +389 -0
  64. package/src/WebDHT.js +363 -1165
  65. package/src/browser-entry.js +40 -0
  66. package/examples/browser/assets/images/favicon.png +0 -0
  67. package/examples/browser/assets/images/pigeon.png +0 -0
  68. package/examples/browser/crypto-test.html +0 -427
  69. package/examples/browser/ui-old.js +0 -1926
  70. package/examples/browser/ui.js +0 -3010
  71. package/websocket-server/README.md +0 -247
  72. package/websocket-server/server.js +0 -391
@@ -0,0 +1,319 @@
1
+ # Bootstrap Hub Implementation - Summary
2
+
3
+ ## Overview
4
+
5
+ Added automatic bootstrap hub connectivity for PeerPigeon hubs. Hubs can now automatically connect to a primary bootstrap hub (default port 3000) or custom bootstrap URIs, enabling automatic hub mesh network formation.
6
+
7
+ ## Changes Made
8
+
9
+ ### 1. Server Configuration
10
+
11
+ #### New Constructor Options:
12
+ ```javascript
13
+ {
14
+ isHub: true, // Enable hub mode
15
+ bootstrapHubs: [], // Array of bootstrap hub URIs
16
+ autoConnect: true, // Auto-connect to bootstrap hubs
17
+ reconnectInterval: 5000, // Reconnection delay in ms
18
+ maxReconnectAttempts: 10, // Max reconnection attempts
19
+ hubPeerId: 'auto-generated' // Custom hub peer ID (optional)
20
+ }
21
+ ```
22
+
23
+ ### 2. New Server Properties
24
+
25
+ - `this.bootstrapHubs` - Array of bootstrap hub URIs
26
+ - `this.autoConnect` - Whether to auto-connect on start
27
+ - `this.reconnectInterval` - Time between reconnection attempts
28
+ - `this.maxReconnectAttempts` - Maximum reconnection attempts
29
+ - `this.hubPeerId` - This hub's peer ID (auto-generated if not provided)
30
+ - `this.bootstrapConnections` - Map of bootstrap URI → connection info
31
+
32
+ ### 3. New Methods
33
+
34
+ #### `generatePeerId()`
35
+ Generates a random 40-character hexadecimal peer ID.
36
+
37
+ #### `connectToBootstrapHubs()`
38
+ Initiates connections to all configured bootstrap hubs. Called automatically on `start()` if `autoConnect` is true.
39
+
40
+ #### `connectToHub(uri, attemptNumber = 0)`
41
+ Connects to a specific bootstrap hub URI. Handles:
42
+ - WebSocket connection establishment
43
+ - Automatic hub announcement on `pigeonhub-mesh`
44
+ - Reconnection on failure with exponential backoff
45
+ - Self-connection prevention
46
+
47
+ #### `announceToHub(ws)`
48
+ Sends hub announcement message to a bootstrap hub:
49
+ ```javascript
50
+ {
51
+ type: 'announce',
52
+ networkName: 'pigeonhub-mesh',
53
+ data: {
54
+ isHub: true,
55
+ port: this.port,
56
+ host: this.host,
57
+ capabilities: ['signaling', 'relay']
58
+ }
59
+ }
60
+ ```
61
+
62
+ #### `handleBootstrapMessage(uri, message)`
63
+ Processes messages from bootstrap hubs:
64
+ - `connected` - Connection acknowledgment
65
+ - `peer-discovered` - Other hub discovery
66
+ - `peer-disconnected` - Hub disconnection
67
+ - `offer/answer/ice-candidate` - WebRTC signaling
68
+ - `pong` - Heartbeat response
69
+
70
+ #### `disconnectFromBootstrapHubs()`
71
+ Closes all bootstrap hub connections. Called automatically on `stop()`.
72
+
73
+ ### 4. New Events
74
+
75
+ #### `bootstrapConnected`
76
+ Emitted when successfully connected to a bootstrap hub.
77
+ ```javascript
78
+ { uri: 'ws://localhost:3000' }
79
+ ```
80
+
81
+ #### `bootstrapDisconnected`
82
+ Emitted when disconnected from a bootstrap hub.
83
+ ```javascript
84
+ { uri: 'ws://localhost:3000', code: 1000, reason: 'Normal closure' }
85
+ ```
86
+
87
+ #### `hubDiscovered`
88
+ Emitted when another hub is discovered through a bootstrap connection.
89
+ ```javascript
90
+ { peerId: 'abc123...', via: 'ws://localhost:3000', data: {...} }
91
+ ```
92
+
93
+ #### `bootstrapSignaling`
94
+ Emitted when WebRTC signaling messages are received from a bootstrap hub.
95
+ ```javascript
96
+ { type: 'offer', data: {...}, fromPeerId: 'def456...', uri: 'ws://localhost:3000' }
97
+ ```
98
+
99
+ ### 5. Enhanced Methods
100
+
101
+ #### `start()`
102
+ Now automatically connects to bootstrap hubs after server starts if `isHub: true` and `autoConnect: true`.
103
+
104
+ #### `stop()`
105
+ Now disconnects from all bootstrap hubs before shutting down.
106
+
107
+ #### `getStats()`
108
+ Now includes bootstrap hub connection statistics:
109
+ ```javascript
110
+ {
111
+ ...existing stats,
112
+ hubPeerId: 'abc123...',
113
+ bootstrapHubs: {
114
+ total: 2,
115
+ connected: 1
116
+ }
117
+ }
118
+ ```
119
+
120
+ #### `getHubStats()`
121
+ Now includes detailed bootstrap hub information:
122
+ ```javascript
123
+ {
124
+ ...existing stats,
125
+ bootstrapHubs: [
126
+ {
127
+ uri: 'ws://localhost:3000',
128
+ connected: true,
129
+ lastAttempt: 1696334400000,
130
+ attemptNumber: 0
131
+ }
132
+ ]
133
+ }
134
+ ```
135
+
136
+ ## Usage Examples
137
+
138
+ ### Example 1: Bootstrap Hub (Primary)
139
+ ```javascript
140
+ const bootstrap = new PeerPigeonServer({
141
+ port: 3000,
142
+ isHub: true,
143
+ autoConnect: false // This IS the bootstrap, don't connect to others
144
+ });
145
+
146
+ await bootstrap.start();
147
+ ```
148
+
149
+ ### Example 2: Secondary Hub (Auto-connect)
150
+ ```javascript
151
+ const hub = new PeerPigeonServer({
152
+ port: 3001,
153
+ isHub: true,
154
+ autoConnect: true // Automatically connects to ws://localhost:3000
155
+ });
156
+
157
+ hub.on('bootstrapConnected', ({ uri }) => {
158
+ console.log(`Connected to ${uri}`);
159
+ });
160
+
161
+ hub.on('hubDiscovered', ({ peerId }) => {
162
+ console.log(`Discovered hub: ${peerId}`);
163
+ });
164
+
165
+ await hub.start();
166
+ ```
167
+
168
+ ### Example 3: Custom Bootstrap URIs
169
+ ```javascript
170
+ const hub = new PeerPigeonServer({
171
+ port: 3002,
172
+ isHub: true,
173
+ bootstrapHubs: [
174
+ 'ws://hub1.example.com:3000',
175
+ 'ws://hub2.example.com:3000'
176
+ ],
177
+ reconnectInterval: 3000,
178
+ maxReconnectAttempts: 5
179
+ });
180
+
181
+ await hub.start();
182
+ ```
183
+
184
+ ## Network Topology
185
+
186
+ ### Single Bootstrap Hub
187
+ ```
188
+ Bootstrap Hub (3000)
189
+ ↑
190
+ ├── Hub 1 (3001)
191
+ ├── Hub 2 (3002)
192
+ └── Hub 3 (3003)
193
+ ```
194
+
195
+ ### Redundant Bootstrap Hubs
196
+ ```
197
+ Bootstrap 1 (3000) ←→ Hub A (3005)
198
+ Bootstrap 2 (3001) ←→ Hub A (3005)
199
+ Bootstrap 3 (3002) ←→ Hub A (3005)
200
+ ```
201
+
202
+ ## Automatic Features
203
+
204
+ ### 1. **Connection Management**
205
+ - Automatic connection on start
206
+ - Self-connection prevention
207
+ - Connection health monitoring
208
+
209
+ ### 2. **Reconnection Logic**
210
+ - Automatic reconnection on disconnect
211
+ - Exponential backoff with configurable interval
212
+ - Maximum attempt limit to prevent infinite loops
213
+
214
+ ### 3. **Hub Discovery**
215
+ - Automatic announcement to bootstrap hub
216
+ - Reception of peer-discovered messages for other hubs
217
+ - Event emission for application-level handling
218
+
219
+ ### 4. **Cleanup**
220
+ - Automatic disconnection on server stop
221
+ - Cancellation of pending reconnection timers
222
+ - Proper WebSocket closure
223
+
224
+ ## Benefits
225
+
226
+ 1. **Zero Configuration**: Secondary hubs automatically find port 3000
227
+ 2. **Easy Setup**: Just set `isHub: true` and `autoConnect: true`
228
+ 3. **Redundancy**: Support for multiple bootstrap hubs
229
+ 4. **Resilience**: Automatic reconnection with backoff
230
+ 5. **Discovery**: Hubs automatically discover each other
231
+ 6. **Monitoring**: Events for connection state tracking
232
+
233
+ ## Files Modified
234
+
235
+ 1. **server/index.js**
236
+ - Added WebSocket client import
237
+ - Added bootstrap configuration options
238
+ - Added `generatePeerId()` method
239
+ - Added bootstrap connection methods
240
+ - Enhanced `start()` and `stop()` methods
241
+ - Enhanced `getStats()` and `getHubStats()` methods
242
+
243
+ 2. **HUB_SYSTEM.md**
244
+ - Added "Bootstrap Hub Configuration" section
245
+ - Added bootstrap methods to API documentation
246
+ - Added bootstrap events documentation
247
+
248
+ 3. **examples/bootstrap-hub-example.js** (NEW)
249
+ - Comprehensive examples of bootstrap hub usage
250
+ - Single bootstrap network example
251
+ - Redundant bootstrap network example
252
+ - Configuration examples
253
+
254
+ ## Migration Guide
255
+
256
+ ### For Existing Hubs
257
+
258
+ If you have existing hub deployments, you can add bootstrap connectivity:
259
+
260
+ **Before:**
261
+ ```javascript
262
+ const hub = new PeerPigeonServer({
263
+ port: 3001,
264
+ isHub: true
265
+ });
266
+ await hub.start();
267
+ ```
268
+
269
+ **After:**
270
+ ```javascript
271
+ const hub = new PeerPigeonServer({
272
+ port: 3001,
273
+ isHub: true,
274
+ autoConnect: true // Add this line
275
+ });
276
+ await hub.start();
277
+ // Hub now automatically connects to ws://localhost:3000
278
+ ```
279
+
280
+ ### Disable Auto-Connect
281
+
282
+ To maintain existing behavior without bootstrap connections:
283
+
284
+ ```javascript
285
+ const hub = new PeerPigeonServer({
286
+ port: 3001,
287
+ isHub: true,
288
+ autoConnect: false // Explicitly disable
289
+ });
290
+ ```
291
+
292
+ ## Testing
293
+
294
+ Run the example to test bootstrap hub functionality:
295
+
296
+ ```bash
297
+ node examples/bootstrap-hub-example.js
298
+ ```
299
+
300
+ This will:
301
+ 1. Start a bootstrap hub on port 3000
302
+ 2. Start three secondary hubs on ports 3001-3003
303
+ 3. Display connection statistics
304
+ 4. Show hub discovery events
305
+ 5. Demonstrate automatic reconnection
306
+
307
+ ## Future Enhancements
308
+
309
+ Potential future improvements:
310
+ - WebRTC data channel connections between hubs
311
+ - Hub load balancing
312
+ - Geographic hub routing
313
+ - Hub health monitoring
314
+ - Metrics and analytics
315
+ - Hub authentication/authorization
316
+
317
+ ## Conclusion
318
+
319
+ The bootstrap hub system enables seamless hub mesh network formation with minimal configuration. Hubs can now automatically discover and connect to each other, creating a robust and scalable infrastructure for PeerPigeon applications.
@@ -0,0 +1,371 @@
1
+ # PeerPigeon CLI
2
+
3
+ A comprehensive command-line interface for PeerPigeon mesh networking.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install -g peerpigeon-cli
9
+ ```
10
+
11
+ Or use directly with npx:
12
+
13
+ ```bash
14
+ npx peerpigeon-cli --help
15
+ ```
16
+
17
+ ## Quick Start
18
+
19
+ ### 1. Start a Signaling Server
20
+
21
+ ```bash
22
+ peerpigeon server --port 3000
23
+ ```
24
+
25
+ ### 2. Initialize and Connect to Mesh
26
+
27
+ ```bash
28
+ # Interactive mode
29
+ peerpigeon init --url wss://localhost:3000 --interactive
30
+
31
+ # Or connect and send a message
32
+ peerpigeon init --url wss://localhost:3000
33
+ peerpigeon send "Hello mesh network!"
34
+ ```
35
+
36
+ ### 3. Interactive Mode
37
+
38
+ Start an interactive session with automatic connection:
39
+
40
+ ```bash
41
+ peerpigeon interactive
42
+ ```
43
+
44
+ ## Commands
45
+
46
+ ### Core Commands
47
+
48
+ #### `peerpigeon init [options]`
49
+ Initialize and connect to mesh network.
50
+
51
+ **Options:**
52
+ - `-u, --url <url>` - Signaling server URL
53
+ - `-p, --peer-id <id>` - Custom peer ID
54
+ - `--max-peers <n>` - Maximum peers (default: 3)
55
+ - `--min-peers <n>` - Minimum peers (default: 2)
56
+ - `--no-auto-discovery` - Disable auto discovery
57
+ - `--enable-webdht` - Enable WebDHT
58
+ - `--enable-crypto` - Enable encryption
59
+ - `-i, --interactive` - Start interactive mode
60
+
61
+ ```bash
62
+ peerpigeon init --url wss://signaling.example.com --max-peers 5 --interactive
63
+ ```
64
+
65
+ #### `peerpigeon send <message>`
66
+ Send broadcast message to all peers.
67
+
68
+ ```bash
69
+ peerpigeon send "Hello everyone!"
70
+ peerpigeon send '{"type": "data", "value": 42}'
71
+ ```
72
+
73
+ #### `peerpigeon dm <peerId> <message>`
74
+ Send direct message to specific peer.
75
+
76
+ ```bash
77
+ peerpigeon dm abc12345... "Hello specific peer!"
78
+ ```
79
+
80
+ ### Status and Information
81
+
82
+ #### `peerpigeon status`
83
+ Show mesh network status.
84
+
85
+ ```bash
86
+ peerpigeon status
87
+ ```
88
+
89
+ **Output:**
90
+ ```
91
+ 📊 Mesh Network Status
92
+
93
+ Peer ID: abc123def456...
94
+ Connected: Yes
95
+ Signaling: wss://localhost:3000
96
+ Peers: 2/3 connected, 5 discovered
97
+ Auto Discovery: Enabled
98
+ Eviction: Enabled
99
+ XOR Routing: Enabled
100
+ WebDHT: Enabled
101
+ Crypto: Disabled
102
+ Uptime: 120s
103
+ ```
104
+
105
+ #### `peerpigeon peers`
106
+ List connected and discovered peers.
107
+
108
+ ```bash
109
+ peerpigeon peers
110
+ ```
111
+
112
+ ### Media Streaming
113
+
114
+ #### `peerpigeon media start [options]`
115
+ Start media streaming.
116
+
117
+ **Options:**
118
+ - `--video` - Enable video
119
+ - `--audio` - Enable audio
120
+
121
+ ```bash
122
+ peerpigeon media start --video --audio
123
+ ```
124
+
125
+ #### `peerpigeon media stop`
126
+ Stop media streaming.
127
+
128
+ ```bash
129
+ peerpigeon media stop
130
+ ```
131
+
132
+ ### Distributed Hash Table (DHT)
133
+
134
+ #### `peerpigeon dht put <key> <value> [options]`
135
+ Store data in DHT.
136
+
137
+ **Options:**
138
+ - `--ttl <ms>` - Time to live in milliseconds
139
+
140
+ ```bash
141
+ peerpigeon dht put "user:profile" '{"name": "Alice", "age": 30}'
142
+ peerpigeon dht put "temp:data" "temporary" --ttl 60000
143
+ ```
144
+
145
+ #### `peerpigeon dht get <key>`
146
+ Retrieve data from DHT.
147
+
148
+ ```bash
149
+ peerpigeon dht get "user:profile"
150
+ ```
151
+
152
+ ### Server Management
153
+
154
+ #### `peerpigeon server [options]`
155
+ Start signaling server.
156
+
157
+ **Options:**
158
+ - `-p, --port <port>` - Server port (default: 3000)
159
+ - `-h, --host <host>` - Server host (default: localhost)
160
+ - `--max-peers <n>` - Maximum peers (default: 100)
161
+
162
+ ```bash
163
+ peerpigeon server --port 8080 --host 0.0.0.0
164
+ ```
165
+
166
+ ### Debug and Development
167
+
168
+ #### `peerpigeon debug <module> [options]`
169
+ Enable debug logging.
170
+
171
+ **Options:**
172
+ - `-a, --all` - Enable all modules
173
+
174
+ ```bash
175
+ peerpigeon debug PeerPigeonMesh
176
+ peerpigeon debug --all
177
+ ```
178
+
179
+ ### Interactive Mode
180
+
181
+ #### `peerpigeon interactive`
182
+ Start interactive mode for real-time messaging.
183
+
184
+ ```bash
185
+ peerpigeon interactive
186
+ ```
187
+
188
+ **Interactive Commands:**
189
+ - Type messages to broadcast
190
+ - `/dm <peerId> <message>` - Send direct message
191
+ - `/status` - Show status
192
+ - `/peers` - List peers
193
+ - `/media start` - Start media streaming
194
+ - `/media stop` - Stop media streaming
195
+ - `/dht put <key> <value>` - Store in DHT
196
+ - `/dht get <key>` - Get from DHT
197
+ - `/quit` - Exit
198
+
199
+ ## Configuration
200
+
201
+ The CLI automatically saves configuration and history in `~/.peerpigeon/`:
202
+
203
+ - `config.json` - Connection settings and preferences
204
+ - `history.json` - Message and connection history
205
+
206
+ ### Configuration File Format
207
+
208
+ ```json
209
+ {
210
+ "signalingUrl": "wss://localhost:3000",
211
+ "peerId": "abc123def456...",
212
+ "maxPeers": 3,
213
+ "minPeers": 2,
214
+ "autoDiscovery": true,
215
+ "enableWebDHT": true,
216
+ "enableCrypto": false
217
+ }
218
+ ```
219
+
220
+ ## Examples
221
+
222
+ ### Simple Chat Network
223
+
224
+ Terminal 1 (Start server):
225
+ ```bash
226
+ peerpigeon server
227
+ ```
228
+
229
+ Terminal 2 (Peer 1):
230
+ ```bash
231
+ peerpigeon init --url wss://localhost:3000 --interactive
232
+ > Hello from peer 1!
233
+ ```
234
+
235
+ Terminal 3 (Peer 2):
236
+ ```bash
237
+ peerpigeon init --url wss://localhost:3000 --interactive
238
+ > Hello from peer 2!
239
+ ```
240
+
241
+ ### Video Conference Setup
242
+
243
+ Terminal 1 (Peer with video):
244
+ ```bash
245
+ peerpigeon init --url wss://localhost:3000
246
+ peerpigeon media start --video --audio
247
+ ```
248
+
249
+ Terminal 2 (Peer joining):
250
+ ```bash
251
+ peerpigeon init --url wss://localhost:3000 --interactive
252
+ /media start --audio
253
+ ```
254
+
255
+ ### Distributed Data Storage
256
+
257
+ ```bash
258
+ # Store user data
259
+ peerpigeon dht put "users:alice" '{"name": "Alice", "status": "online"}'
260
+
261
+ # Retrieve data from another peer
262
+ peerpigeon dht get "users:alice"
263
+
264
+ # Store temporary data with expiration
265
+ peerpigeon dht put "session:temp" "temporary data" --ttl 300000
266
+ ```
267
+
268
+ ### Custom Mesh Configuration
269
+
270
+ ```bash
271
+ # Large mesh with custom settings
272
+ peerpigeon init \
273
+ --url wss://signaling.example.com \
274
+ --max-peers 10 \
275
+ --min-peers 3 \
276
+ --enable-webdht \
277
+ --enable-crypto \
278
+ --interactive
279
+ ```
280
+
281
+ ## Environment Variables
282
+
283
+ - `PEERPIGEON_SIGNALING_URL` - Default signaling server URL
284
+ - `PEERPIGEON_PEER_ID` - Default peer ID
285
+ - `PEERPIGEON_MAX_PEERS` - Default maximum peers
286
+ - `PEERPIGEON_DEBUG` - Comma-separated list of modules to debug
287
+
288
+ ```bash
289
+ export PEERPIGEON_SIGNALING_URL=wss://my-signaling.com
290
+ export PEERPIGEON_DEBUG=PeerPigeonMesh,ConnectionManager
291
+ peerpigeon init --interactive
292
+ ```
293
+
294
+ ## Error Handling
295
+
296
+ The CLI provides detailed error messages and suggestions:
297
+
298
+ ```bash
299
+ # Connection failure
300
+ peerpigeon init --url wss://invalid-server.com
301
+ # ✗ [12:34:56] Error: Connection failed: ENOTFOUND invalid-server.com
302
+
303
+ # Missing dependencies
304
+ peerpigeon media start --video
305
+ # ⚠ [12:34:56] Warning: Camera access denied. Check permissions.
306
+
307
+ # Invalid commands
308
+ peerpigeon invalid-command
309
+ # ✗ [12:34:56] Error: Unknown command. Use --help for available commands.
310
+ ```
311
+
312
+ ## Integration with Node.js Applications
313
+
314
+ Use the CLI programmatically:
315
+
316
+ ```javascript
317
+ import { spawn } from 'child_process';
318
+
319
+ // Start peer and send message
320
+ const peer = spawn('peerpigeon', ['init', '--url', 'wss://localhost:3000']);
321
+ setTimeout(() => {
322
+ spawn('peerpigeon', ['send', 'Hello from Node.js!']);
323
+ }, 2000);
324
+ ```
325
+
326
+ ## Troubleshooting
327
+
328
+ ### Common Issues
329
+
330
+ 1. **Connection refused**
331
+ ```bash
332
+ # Check if signaling server is running
333
+ peerpigeon server --port 3000
334
+ ```
335
+
336
+ 2. **No peers discovered**
337
+ ```bash
338
+ # Check auto-discovery is enabled
339
+ peerpigeon status
340
+ # Enable if disabled
341
+ peerpigeon init --auto-discovery
342
+ ```
343
+
344
+ 3. **Media permissions denied**
345
+ ```bash
346
+ # Check browser/system permissions for camera/microphone
347
+ peerpigeon media start --audio # Try audio only first
348
+ ```
349
+
350
+ 4. **DHT operations failing**
351
+ ```bash
352
+ # Ensure WebDHT is enabled
353
+ peerpigeon init --enable-webdht
354
+ ```
355
+
356
+ ### Debug Mode
357
+
358
+ Enable debug logging for troubleshooting:
359
+
360
+ ```bash
361
+ peerpigeon debug --all
362
+ peerpigeon init --url wss://localhost:3000 --interactive
363
+ ```
364
+
365
+ ## License
366
+
367
+ MIT License - see LICENSE file for details.
368
+
369
+ ## Contributing
370
+
371
+ Contributions welcome! Please see CONTRIBUTING.md for guidelines.