peerpigeon 0.1.1 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +141 -1365
- package/cli.js +1382 -0
- package/dist/peerpigeon-browser.js +12290 -0
- package/dist/peerpigeon-browser.js.map +7 -0
- package/docs/API_DOCUMENTATION.md +1945 -0
- package/docs/BOOTSTRAP_HUBS.md +319 -0
- package/docs/CLI_README.md +371 -0
- package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
- package/docs/HUB_QUICK_REF.md +107 -0
- package/docs/HUB_SCRIPTS.md +331 -0
- package/docs/HUB_SYSTEM.md +552 -0
- package/docs/MIGRATION_COMPLETE.md +93 -0
- package/docs/NETWORK_NAMESPACES.md +212 -0
- package/docs/README.md +107 -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 +186 -0
- package/examples/multi-hub-test.js +186 -0
- package/examples/node/README.md +2 -2
- package/examples/selective-streaming-demo.html +698 -0
- package/examples/standard-events-demo.js +126 -0
- package/package.json +33 -16
- package/server/index.js +1032 -98
- package/server/start.js +49 -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 +109 -2
- package/src/EventEmitter.js +79 -1
- package/src/EvictionManager.js +10 -9
- package/src/GossipManager.js +163 -11
- package/src/PeerConnection.js +333 -310
- package/src/PeerPigeonMesh.js +577 -135
- 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 +40 -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
|
@@ -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.
|