peerpigeon 0.1.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +141 -1365
  2. package/cli.js +1382 -0
  3. package/dist/peerpigeon-browser.js +12450 -0
  4. package/dist/peerpigeon-browser.js.map +7 -0
  5. package/docs/API_DOCUMENTATION.md +1976 -0
  6. package/docs/BOOTSTRAP_HUBS.md +319 -0
  7. package/docs/CLI_README.md +371 -0
  8. package/docs/CUSTOM_HUB_NAMESPACES.md +182 -0
  9. package/docs/CUSTOM_NAMESPACE_IMPLEMENTATION.md +187 -0
  10. package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
  11. package/docs/HUB_QUICK_REF.md +108 -0
  12. package/docs/HUB_SCRIPTS.md +341 -0
  13. package/docs/HUB_SYSTEM.md +599 -0
  14. package/docs/MIGRATION_COMPLETE.md +93 -0
  15. package/docs/NETWORK_NAMESPACES.md +212 -0
  16. package/docs/PIGEONRTC_MIGRATION.md +280 -0
  17. package/docs/README.md +108 -0
  18. package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
  19. package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
  20. package/examples/bootstrap-hub-example.js +292 -0
  21. package/examples/browser/README.md +278 -0
  22. package/examples/browser/app.js +2426 -49
  23. package/examples/browser/index.html +481 -630
  24. package/examples/browser/minimal/README.md +55 -0
  25. package/examples/browser/minimal/index.html +75 -0
  26. package/examples/browser/minimal/minimal.js +234 -0
  27. package/examples/browser/styles.css +687 -1425
  28. package/examples/browser/test-bundle.html +35 -0
  29. package/examples/browser-2/index.html +30 -0
  30. package/examples/browser-2/package.json +21 -0
  31. package/examples/browser-2/src/App-simple.vue +21 -0
  32. package/examples/browser-2/src/App.vue +420 -0
  33. package/examples/browser-2/src/components/CryptoView.vue +1661 -0
  34. package/examples/browser-2/src/components/DHTView.vue +1281 -0
  35. package/examples/browser-2/src/components/DebugView.vue +1773 -0
  36. package/examples/browser-2/src/components/MediaView.vue +1048 -0
  37. package/examples/browser-2/src/components/MessagingView.vue +775 -0
  38. package/examples/browser-2/src/components/NetworkView.vue +930 -0
  39. package/examples/browser-2/src/components/StorageView.vue +1376 -0
  40. package/examples/browser-2/src/main.js +5 -0
  41. package/examples/browser-2/src/stores/peerpigeon.js +895 -0
  42. package/examples/browser-2/vite.config.js +6 -0
  43. package/examples/hub-example.js +189 -0
  44. package/examples/multi-hub-test.js +186 -0
  45. package/examples/node/README.md +2 -2
  46. package/examples/programmatic-namespace-example.js +108 -0
  47. package/examples/selective-streaming-demo.html +698 -0
  48. package/examples/standard-events-demo.js +126 -0
  49. package/index.js +7 -1
  50. package/package.json +34 -16
  51. package/server/index.js +1058 -98
  52. package/server/start.js +52 -0
  53. package/src/ConnectionManager.js +239 -225
  54. package/src/CryptoManager.js +147 -18
  55. package/src/DebugLogger.js +0 -7
  56. package/src/DistributedStorageManager.js +224 -205
  57. package/src/EnvironmentDetector.js +88 -4
  58. package/src/EventEmitter.js +79 -1
  59. package/src/EvictionManager.js +10 -9
  60. package/src/GossipManager.js +163 -11
  61. package/src/MediaManager.js +12 -2
  62. package/src/PeerConnection.js +343 -311
  63. package/src/PeerPigeonMesh.js +576 -135
  64. package/src/PigeonRTC-browser.js +247 -0
  65. package/src/SignalingClient.js +14 -243
  66. package/src/SignalingHandler.js +31 -10
  67. package/src/StorageManager.js +0 -39
  68. package/src/WebDHT-Simple.js +389 -0
  69. package/src/WebDHT.js +363 -1165
  70. package/src/browser-entry.js +58 -0
  71. package/examples/browser/assets/images/favicon.png +0 -0
  72. package/examples/browser/assets/images/pigeon.png +0 -0
  73. package/examples/browser/crypto-test.html +0 -427
  74. package/examples/browser/ui-old.js +0 -1926
  75. package/examples/browser/ui.js +0 -3391
  76. package/websocket-server/README.md +0 -247
  77. package/websocket-server/server.js +0 -391
@@ -0,0 +1,341 @@
1
+ # PeerPigeon Hub Scripts
2
+
3
+ Easy-to-use scripts for starting and managing PeerPigeon hubs.
4
+
5
+ ## Quick Start
6
+
7
+ ### Start a Bootstrap Hub (Port 3000)
8
+
9
+ ```bash
10
+ npm run hub:bootstrap
11
+ ```
12
+
13
+ This starts the primary hub that other hubs connect to.
14
+
15
+ ### Start a Secondary Hub (Port 3001)
16
+
17
+ ```bash
18
+ npm run hub
19
+ ```
20
+
21
+ This starts a hub that automatically connects to the bootstrap hub on port 3000.
22
+
23
+ ### Start a Complete Hub Network
24
+
25
+ ```bash
26
+ npm run hub:network
27
+ ```
28
+
29
+ This starts a network of 4 hubs:
30
+ - Bootstrap hub on port 3000
31
+ - Secondary hubs on ports 3001, 3002, 3003
32
+
33
+ All secondary hubs automatically connect to the bootstrap hub.
34
+
35
+ ## Advanced Usage
36
+
37
+ ### Custom Port
38
+
39
+ ```bash
40
+ PORT=4000 npm run hub
41
+ ```
42
+
43
+ ### Custom Bootstrap URI
44
+
45
+ ```bash
46
+ PORT=3005 BOOTSTRAP=ws://hub.example.com:3000 npm run hub
47
+ ```
48
+
49
+ ### Multiple Bootstrap Hubs (Redundancy)
50
+
51
+ ```bash
52
+ BOOTSTRAP=ws://hub1.example.com:3000,ws://hub2.example.com:3000 npm run hub
53
+ ```
54
+
55
+ ### Custom Hub ID
56
+
57
+ ```bash
58
+ HUB_ID=a1b2c3d4e5f6789012345678901234567890abcd npm run hub
59
+ ```
60
+
61
+ ### Custom Hub Mesh Namespace
62
+
63
+ ```bash
64
+ HUB_MESH_NAMESPACE=my-custom-mesh npm run hub
65
+ ```
66
+
67
+ **Note:** All hubs in the same deployment must use the same namespace to discover each other.
68
+
69
+ ### Disable Auto-Connect
70
+
71
+ ```bash
72
+ AUTO_CONNECT=false npm run hub
73
+ ```
74
+
75
+ ## Script Files
76
+
77
+ ### `scripts/start-hub.js`
78
+
79
+ Start a single hub with custom configuration.
80
+
81
+ **Usage:**
82
+ ```bash
83
+ node scripts/start-hub.js # Secondary hub on port 3001
84
+ node scripts/start-hub.js --bootstrap # Bootstrap hub on port 3000
85
+ PORT=3002 node scripts/start-hub.js # Custom port
86
+ ```
87
+
88
+ **Environment Variables:**
89
+ - `PORT` - Port number (default: 3001 for secondary, 3000 for bootstrap)
90
+ - `HOST` - Host address (default: localhost)
91
+ - `BOOTSTRAP` - Comma-separated bootstrap hub URIs
92
+ - `HUB_ID` - Custom 40-character hex peer ID
93
+ - `HUB_MESH_NAMESPACE` - Custom hub mesh namespace (default: pigeonhub-mesh)
94
+ - `AUTO_CONNECT` - Auto-connect to bootstrap (default: true)
95
+
96
+ **Command Line Flags:**
97
+ - `--bootstrap` or `-b` - Run as bootstrap hub (port 3000, no auto-connect)
98
+
99
+ ### `scripts/start-hub-network.js`
100
+
101
+ Start a complete network of interconnected hubs.
102
+
103
+ **Usage:**
104
+ ```bash
105
+ node scripts/start-hub-network.js # Start 4 hubs (ports 3000-3003)
106
+ HUB_COUNT=6 node scripts/start-hub-network.js # Start 6 hubs (ports 3000-3005)
107
+ ```
108
+
109
+ **Environment Variables:**
110
+ - `HUB_COUNT` - Number of hubs to start (default: 4)
111
+ - `START_PORT` - Starting port number (default: 3000)
112
+ - `HOST` - Host address (default: localhost)
113
+ - `HUB_MESH_NAMESPACE` - Custom hub mesh namespace (default: pigeonhub-mesh)
114
+
115
+ **Features:**
116
+ - Starts bootstrap hub first
117
+ - Starts secondary hubs with auto-connect
118
+ - Displays network topology
119
+ - Shows periodic statistics (every 30 seconds)
120
+ - Graceful shutdown of all hubs
121
+
122
+ ## Hub Features
123
+
124
+ ### Automatic Connection
125
+
126
+ Secondary hubs automatically connect to the bootstrap hub and discover other hubs through it.
127
+
128
+ ### Auto-Reconnection
129
+
130
+ If a hub loses connection to the bootstrap, it automatically attempts to reconnect:
131
+ - Reconnect interval: 5 seconds
132
+ - Max attempts: 10
133
+ - Exponential backoff
134
+
135
+ ### Event Monitoring
136
+
137
+ All scripts display real-time events:
138
+ - ✅ Peer connections
139
+ - 🏢 Hub registrations
140
+ - 🔗 Bootstrap connections
141
+ - 🔍 Hub discovery
142
+ - 📢 Peer announcements
143
+
144
+ ### Statistics
145
+
146
+ Periodic statistics are displayed showing:
147
+ - Total connections
148
+ - Number of hubs
149
+ - Number of peers
150
+ - Active networks
151
+ - Bootstrap connection status
152
+
153
+ ## Network Topologies
154
+
155
+ ### Basic Topology
156
+
157
+ ```
158
+ Bootstrap Hub (3000)
159
+ ↑
160
+ ├── Hub 1 (3001)
161
+ ├── Hub 2 (3002)
162
+ └── Hub 3 (3003)
163
+ ```
164
+
165
+ ### Redundant Topology
166
+
167
+ ```bash
168
+ # Hub 1 with multiple bootstrap hubs
169
+ BOOTSTRAP=ws://localhost:3000,ws://localhost:3001 PORT=3005 npm run hub
170
+ ```
171
+
172
+ ```
173
+ Bootstrap Hub 1 (3000) ←→ Hub (3005)
174
+ Bootstrap Hub 2 (3001) ←→ Hub (3005)
175
+ ```
176
+
177
+ ## Monitoring
178
+
179
+ ### Health Check
180
+
181
+ ```bash
182
+ curl http://localhost:3000/health
183
+ ```
184
+
185
+ Response:
186
+ ```json
187
+ {
188
+ "status": "healthy",
189
+ "isHub": true,
190
+ "connections": 3,
191
+ "hubs": 2,
192
+ "peers": 1,
193
+ "networks": 2
194
+ }
195
+ ```
196
+
197
+ ### List Connected Hubs
198
+
199
+ ```bash
200
+ curl http://localhost:3000/hubs
201
+ ```
202
+
203
+ Response:
204
+ ```json
205
+ {
206
+ "totalHubs": 3,
207
+ "hubs": [
208
+ {
209
+ "peerId": "abc123...",
210
+ "networkName": "pigeonhub-mesh",
211
+ "registeredAt": 1696334400000
212
+ }
213
+ ]
214
+ }
215
+ ```
216
+
217
+ ## Production Deployment
218
+
219
+ ### Using PM2
220
+
221
+ ```bash
222
+ # Install PM2
223
+ npm install -g pm2
224
+
225
+ # Start bootstrap hub
226
+ pm2 start scripts/start-hub.js --name hub-bootstrap -- --bootstrap
227
+
228
+ # Start secondary hubs
229
+ PORT=3001 pm2 start scripts/start-hub.js --name hub-3001
230
+ PORT=3002 pm2 start scripts/start-hub.js --name hub-3002
231
+ PORT=3003 pm2 start scripts/start-hub.js --name hub-3003
232
+
233
+ # Save configuration
234
+ pm2 save
235
+
236
+ # Setup auto-restart on reboot
237
+ pm2 startup
238
+ ```
239
+
240
+ ### Using Docker
241
+
242
+ Create a `Dockerfile`:
243
+ ```dockerfile
244
+ FROM node:20
245
+ WORKDIR /app
246
+ COPY package*.json ./
247
+ RUN npm ci --only=production
248
+ COPY . .
249
+ CMD ["npm", "run", "hub"]
250
+ ```
251
+
252
+ Run:
253
+ ```bash
254
+ # Bootstrap hub
255
+ docker run -p 3000:3000 -e PORT=3000 peerpigeon-hub --bootstrap
256
+
257
+ # Secondary hubs
258
+ docker run -p 3001:3001 -e PORT=3001 -e BOOTSTRAP=ws://bootstrap:3000 peerpigeon-hub
259
+ docker run -p 3002:3002 -e PORT=3002 -e BOOTSTRAP=ws://bootstrap:3000 peerpigeon-hub
260
+ ```
261
+
262
+ ### Using Systemd
263
+
264
+ Create `/etc/systemd/system/peerpigeon-hub@.service`:
265
+ ```ini
266
+ [Unit]
267
+ Description=PeerPigeon Hub on port %i
268
+ After=network.target
269
+
270
+ [Service]
271
+ Type=simple
272
+ User=peerpigeon
273
+ WorkingDirectory=/opt/peerpigeon
274
+ Environment="PORT=%i"
275
+ ExecStart=/usr/bin/node scripts/start-hub.js
276
+ Restart=always
277
+
278
+ [Install]
279
+ WantedBy=multi-user.target
280
+ ```
281
+
282
+ Enable and start:
283
+ ```bash
284
+ # Bootstrap hub
285
+ systemctl enable peerpigeon-hub@3000
286
+ systemctl start peerpigeon-hub@3000
287
+
288
+ # Secondary hubs
289
+ systemctl enable peerpigeon-hub@3001
290
+ systemctl start peerpigeon-hub@3001
291
+ ```
292
+
293
+ ## Troubleshooting
294
+
295
+ ### Port Already in Use
296
+
297
+ The hub will automatically try the next available port:
298
+ ```
299
+ ⚠️ Port 3000 is already in use
300
+ 🔄 Trying port 3001...
301
+ ✅ Port 3000 was in use, using port 3001 instead
302
+ ```
303
+
304
+ ### Can't Connect to Bootstrap
305
+
306
+ Check that the bootstrap hub is running:
307
+ ```bash
308
+ curl http://localhost:3000/health
309
+ ```
310
+
311
+ Verify the bootstrap URI is correct:
312
+ ```bash
313
+ BOOTSTRAP=ws://localhost:3000 npm run hub
314
+ ```
315
+
316
+ ### Hub Not Discovering Others
317
+
318
+ 1. Ensure hubs are using `pigeonhub-mesh` namespace
319
+ 2. Check that `autoConnect` is enabled
320
+ 3. Verify network connectivity between hubs
321
+ 4. Check firewall rules
322
+
323
+ ### Memory Issues
324
+
325
+ Adjust Node.js memory limits:
326
+ ```bash
327
+ NODE_OPTIONS="--max-old-space-size=4096" npm run hub:network
328
+ ```
329
+
330
+ ## Examples
331
+
332
+ See the `examples/` directory for more detailed examples:
333
+ - `examples/hub-example.js` - Basic hub usage
334
+ - `examples/bootstrap-hub-example.js` - Bootstrap hub examples
335
+
336
+ ## Support
337
+
338
+ For more information, see:
339
+ - [HUB_SYSTEM.md](HUB_SYSTEM.md) - Complete hub system documentation
340
+ - [API_DOCUMENTATION.md](API_DOCUMENTATION.md) - API reference
341
+ - [README.md](../README.md) - Main project documentation