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,172 @@
|
|
|
1
|
+
# Documentation Reorganization - Complete ✅
|
|
2
|
+
|
|
3
|
+
## Summary
|
|
4
|
+
|
|
5
|
+
Successfully reorganized all documentation into a structured `docs/` folder and created a new concise README.md that highlights key features with practical examples.
|
|
6
|
+
|
|
7
|
+
## Changes Made
|
|
8
|
+
|
|
9
|
+
### ✅ New Structure
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
PeerPigeon/
|
|
13
|
+
├── README.md (NEW - concise, example-focused)
|
|
14
|
+
├── docs/
|
|
15
|
+
│ ├── README.md (NEW - documentation index)
|
|
16
|
+
│ ├── API_DOCUMENTATION.md
|
|
17
|
+
│ ├── BOOTSTRAP_HUBS.md
|
|
18
|
+
│ ├── CLI_README.md
|
|
19
|
+
│ ├── HUB_QUICK_REF.md
|
|
20
|
+
│ ├── HUB_SCRIPTS.md
|
|
21
|
+
│ ├── HUB_SYSTEM.md
|
|
22
|
+
│ ├── MIGRATION_COMPLETE.md
|
|
23
|
+
│ ├── NETWORK_NAMESPACES.md
|
|
24
|
+
│ ├── SELECTIVE_STREAMING_GUIDE.md
|
|
25
|
+
│ └── TEST_CLEANUP_COMPLETE.md
|
|
26
|
+
├── examples/
|
|
27
|
+
│ ├── browser/README.md
|
|
28
|
+
│ ├── node/README.md
|
|
29
|
+
│ └── nativescript/README.md
|
|
30
|
+
└── ...
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### ✅ New README.md Features
|
|
34
|
+
|
|
35
|
+
The new README is much more concise and user-friendly:
|
|
36
|
+
|
|
37
|
+
1. **Clear Value Proposition** - Immediate understanding of what PeerPigeon does
|
|
38
|
+
2. **Key Features List** - 8 main features highlighted with emojis
|
|
39
|
+
3. **Quick Start** - Installation and basic usage in < 20 lines
|
|
40
|
+
4. **Practical Examples** - 5 real-world code examples:
|
|
41
|
+
- Distributed Storage
|
|
42
|
+
- Selective Media Streaming
|
|
43
|
+
- Network Namespaces
|
|
44
|
+
- Hub System
|
|
45
|
+
- Advanced Configuration
|
|
46
|
+
5. **Architecture Overview** - Simple ASCII diagram
|
|
47
|
+
6. **Documentation Links** - Well-organized links to detailed docs
|
|
48
|
+
7. **Testing Commands** - Clear test instructions
|
|
49
|
+
8. **Contributing & License** - Standard OSS information
|
|
50
|
+
|
|
51
|
+
**Old README**: 1,517 lines (overwhelming)
|
|
52
|
+
**New README**: ~150 lines (focused & actionable)
|
|
53
|
+
|
|
54
|
+
### ✅ Documentation Index
|
|
55
|
+
|
|
56
|
+
Created `docs/README.md` as a comprehensive documentation hub:
|
|
57
|
+
- Organized by topic (Core, Messaging, Storage, Media, Network, Server)
|
|
58
|
+
- Quick code examples for common tasks
|
|
59
|
+
- Links to all detailed documentation
|
|
60
|
+
- Easy navigation for developers
|
|
61
|
+
|
|
62
|
+
### ✅ Updated Files
|
|
63
|
+
|
|
64
|
+
1. **`package.json`**
|
|
65
|
+
- Updated `files` array to include `docs/` instead of individual doc files
|
|
66
|
+
- Cleaner package distribution
|
|
67
|
+
|
|
68
|
+
2. **`docs/HUB_SCRIPTS.md`**
|
|
69
|
+
- Fixed cross-references to other docs (now in same folder)
|
|
70
|
+
|
|
71
|
+
## Benefits
|
|
72
|
+
|
|
73
|
+
### For New Users
|
|
74
|
+
- **Quick Start** - Get running in < 5 minutes with clear examples
|
|
75
|
+
- **Feature Discovery** - Key features immediately visible
|
|
76
|
+
- **Progressive Learning** - Start simple, dive deep when needed
|
|
77
|
+
|
|
78
|
+
### For Experienced Users
|
|
79
|
+
- **Quick Reference** - Examples right in README
|
|
80
|
+
- **Organized Docs** - All documentation in one place (`docs/`)
|
|
81
|
+
- **Easy Navigation** - Documentation index with topic-based organization
|
|
82
|
+
|
|
83
|
+
### For Maintainers
|
|
84
|
+
- **Cleaner Repository** - All docs organized in `docs/`
|
|
85
|
+
- **Easier Updates** - Cross-references are simpler (same folder)
|
|
86
|
+
- **Better Discovery** - GitHub shows README, docs/ is obvious next step
|
|
87
|
+
|
|
88
|
+
## Documentation Organization
|
|
89
|
+
|
|
90
|
+
### Core User Docs
|
|
91
|
+
- **README.md** - Entry point, quick start, examples
|
|
92
|
+
- **docs/API_DOCUMENTATION.md** - Complete API reference
|
|
93
|
+
- **docs/CLI_README.md** - Command-line tools
|
|
94
|
+
|
|
95
|
+
### Feature Guides
|
|
96
|
+
- **docs/NETWORK_NAMESPACES.md** - Isolated networks
|
|
97
|
+
- **docs/SELECTIVE_STREAMING_GUIDE.md** - Media optimization
|
|
98
|
+
- **docs/HUB_SYSTEM.md** - Multi-server architecture
|
|
99
|
+
- **docs/HUB_QUICK_REF.md** - Hub quick start
|
|
100
|
+
- **docs/HUB_SCRIPTS.md** - Hub automation
|
|
101
|
+
- **docs/BOOTSTRAP_HUBS.md** - Hub federation
|
|
102
|
+
|
|
103
|
+
### Maintenance Docs
|
|
104
|
+
- **docs/MIGRATION_COMPLETE.md** - Server migration notes
|
|
105
|
+
- **docs/TEST_CLEANUP_COMPLETE.md** - Test cleanup notes
|
|
106
|
+
|
|
107
|
+
### Example Docs
|
|
108
|
+
- **examples/browser/README.md** - Browser examples
|
|
109
|
+
- **examples/node/README.md** - Node.js examples
|
|
110
|
+
- **examples/nativescript/README.md** - Mobile examples
|
|
111
|
+
|
|
112
|
+
## Migration Notes
|
|
113
|
+
|
|
114
|
+
### For Users
|
|
115
|
+
- All doc links in the new README point to `docs/` folder
|
|
116
|
+
- Examples remain in `examples/` (unchanged)
|
|
117
|
+
- Package.json correctly includes `docs/` in published package
|
|
118
|
+
|
|
119
|
+
### For Contributors
|
|
120
|
+
- New docs should go in `docs/` folder
|
|
121
|
+
- README should stay concise - link to detailed docs
|
|
122
|
+
- Cross-references within docs/ use relative paths
|
|
123
|
+
|
|
124
|
+
## Before & After Comparison
|
|
125
|
+
|
|
126
|
+
### Old Structure (Root Level Clutter)
|
|
127
|
+
```
|
|
128
|
+
PeerPigeon/
|
|
129
|
+
├── README.md (1,517 lines - too long)
|
|
130
|
+
├── API_DOCUMENTATION.md
|
|
131
|
+
├── BOOTSTRAP_HUBS.md
|
|
132
|
+
├── CLI_README.md
|
|
133
|
+
├── HUB_QUICK_REF.md
|
|
134
|
+
├── HUB_SCRIPTS.md
|
|
135
|
+
├── HUB_SYSTEM.md
|
|
136
|
+
├── MIGRATION_COMPLETE.md
|
|
137
|
+
├── NETWORK_NAMESPACES.md
|
|
138
|
+
├── SELECTIVE_STREAMING_GUIDE.md
|
|
139
|
+
├── TEST_CLEANUP_COMPLETE.md
|
|
140
|
+
└── ... (10 MD files at root!)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### New Structure (Organized)
|
|
144
|
+
```
|
|
145
|
+
PeerPigeon/
|
|
146
|
+
├── README.md (150 lines - focused)
|
|
147
|
+
├── docs/ (all documentation organized here)
|
|
148
|
+
│ ├── README.md (navigation index)
|
|
149
|
+
│ └── ... (10 detailed guides)
|
|
150
|
+
├── examples/ (practical examples)
|
|
151
|
+
└── ... (clean root directory)
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
## SEO & Discovery Benefits
|
|
155
|
+
|
|
156
|
+
1. **GitHub README** - Shows concise, example-rich content
|
|
157
|
+
2. **npm Page** - Displays focused README with clear value prop
|
|
158
|
+
3. **Documentation Folder** - GitHub automatically highlights docs/ folder
|
|
159
|
+
4. **Search Engines** - Better keyword density in main README
|
|
160
|
+
|
|
161
|
+
## Next Steps (Optional Improvements)
|
|
162
|
+
|
|
163
|
+
Future enhancements to consider:
|
|
164
|
+
- [ ] Add badges for build status, coverage, etc.
|
|
165
|
+
- [ ] Create a CONTRIBUTING.md guide
|
|
166
|
+
- [ ] Add a CHANGELOG.md for version history
|
|
167
|
+
- [ ] Consider adding diagrams/screenshots to README
|
|
168
|
+
- [ ] Add "Star ⭐" call-to-action in README
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
**The documentation is now professional, organized, and user-friendly!** 🎉
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# PeerPigeon Hub Quick Reference
|
|
2
|
+
|
|
3
|
+
## NPM Scripts
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
# Start bootstrap hub (port 3000)
|
|
7
|
+
npm run hub:bootstrap
|
|
8
|
+
|
|
9
|
+
# Start secondary hub (port 3001, auto-connects to 3000)
|
|
10
|
+
npm run hub
|
|
11
|
+
|
|
12
|
+
# Start complete hub network (4 hubs on ports 3000-3003)
|
|
13
|
+
npm run hub:network
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Environment Variables
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# Custom port
|
|
20
|
+
PORT=4000 npm run hub
|
|
21
|
+
|
|
22
|
+
# Custom bootstrap
|
|
23
|
+
BOOTSTRAP=ws://hub.example.com:3000 npm run hub
|
|
24
|
+
|
|
25
|
+
# Multiple bootstrap hubs
|
|
26
|
+
BOOTSTRAP=ws://hub1.com:3000,ws://hub2.com:3000 npm run hub
|
|
27
|
+
|
|
28
|
+
# Custom hub ID
|
|
29
|
+
HUB_ID=abc123...xyz npm run hub
|
|
30
|
+
|
|
31
|
+
# Disable auto-connect
|
|
32
|
+
AUTO_CONNECT=false npm run hub
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Direct Script Usage
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# Bootstrap hub
|
|
39
|
+
node scripts/start-hub.js --bootstrap
|
|
40
|
+
|
|
41
|
+
# Secondary hub with custom config
|
|
42
|
+
PORT=3002 BOOTSTRAP=ws://localhost:3000 node scripts/start-hub.js
|
|
43
|
+
|
|
44
|
+
# Hub network with custom count
|
|
45
|
+
HUB_COUNT=6 node scripts/start-hub-network.js
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Monitoring
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# Health check
|
|
52
|
+
curl http://localhost:3000/health
|
|
53
|
+
|
|
54
|
+
# List hubs
|
|
55
|
+
curl http://localhost:3000/hubs
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Network Topology
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
Bootstrap (3000)
|
|
62
|
+
↑
|
|
63
|
+
├── Hub 1 (3001) ← auto-connects
|
|
64
|
+
├── Hub 2 (3002) ← auto-connects
|
|
65
|
+
└── Hub 3 (3003) ← auto-connects
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Production (PM2)
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# Bootstrap
|
|
72
|
+
pm2 start scripts/start-hub.js --name hub-3000 -- --bootstrap
|
|
73
|
+
|
|
74
|
+
# Secondary hubs
|
|
75
|
+
PORT=3001 pm2 start scripts/start-hub.js --name hub-3001
|
|
76
|
+
PORT=3002 pm2 start scripts/start-hub.js --name hub-3002
|
|
77
|
+
|
|
78
|
+
# Save & startup
|
|
79
|
+
pm2 save
|
|
80
|
+
pm2 startup
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Key Features
|
|
84
|
+
|
|
85
|
+
- ✅ Auto-connect to bootstrap hub
|
|
86
|
+
- 🔄 Auto-reconnect on disconnect
|
|
87
|
+
- 🔍 Automatic hub discovery
|
|
88
|
+
- 📊 Real-time statistics
|
|
89
|
+
- 🛡️ Graceful shutdown
|
|
90
|
+
- 🚀 Port auto-increment
|
|
91
|
+
|
|
92
|
+
## Events Displayed
|
|
93
|
+
|
|
94
|
+
- ✅ Peer connected/disconnected
|
|
95
|
+
- 🏢 Hub registered/unregistered
|
|
96
|
+
- 🔗 Bootstrap connected/disconnected
|
|
97
|
+
- 🔍 Hub discovered
|
|
98
|
+
- 📢 Peer announced
|
|
99
|
+
|
|
100
|
+
## Default Configuration
|
|
101
|
+
|
|
102
|
+
- Bootstrap Port: 3000
|
|
103
|
+
- Secondary Port: 3001
|
|
104
|
+
- Host: localhost
|
|
105
|
+
- Reconnect Interval: 5 seconds
|
|
106
|
+
- Max Reconnect Attempts: 10
|
|
107
|
+
- Hub Mesh Namespace: pigeonhub-mesh
|
|
@@ -0,0 +1,331 @@
|
|
|
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
|
+
### Disable Auto-Connect
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
AUTO_CONNECT=false npm run hub
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Script Files
|
|
68
|
+
|
|
69
|
+
### `scripts/start-hub.js`
|
|
70
|
+
|
|
71
|
+
Start a single hub with custom configuration.
|
|
72
|
+
|
|
73
|
+
**Usage:**
|
|
74
|
+
```bash
|
|
75
|
+
node scripts/start-hub.js # Secondary hub on port 3001
|
|
76
|
+
node scripts/start-hub.js --bootstrap # Bootstrap hub on port 3000
|
|
77
|
+
PORT=3002 node scripts/start-hub.js # Custom port
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**Environment Variables:**
|
|
81
|
+
- `PORT` - Port number (default: 3001 for secondary, 3000 for bootstrap)
|
|
82
|
+
- `HOST` - Host address (default: localhost)
|
|
83
|
+
- `BOOTSTRAP` - Comma-separated bootstrap hub URIs
|
|
84
|
+
- `HUB_ID` - Custom 40-character hex peer ID
|
|
85
|
+
- `AUTO_CONNECT` - Auto-connect to bootstrap (default: true)
|
|
86
|
+
|
|
87
|
+
**Command Line Flags:**
|
|
88
|
+
- `--bootstrap` or `-b` - Run as bootstrap hub (port 3000, no auto-connect)
|
|
89
|
+
|
|
90
|
+
### `scripts/start-hub-network.js`
|
|
91
|
+
|
|
92
|
+
Start a complete network of interconnected hubs.
|
|
93
|
+
|
|
94
|
+
**Usage:**
|
|
95
|
+
```bash
|
|
96
|
+
node scripts/start-hub-network.js # Start 4 hubs (ports 3000-3003)
|
|
97
|
+
HUB_COUNT=6 node scripts/start-hub-network.js # Start 6 hubs (ports 3000-3005)
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Environment Variables:**
|
|
101
|
+
- `HUB_COUNT` - Number of hubs to start (default: 4)
|
|
102
|
+
- `START_PORT` - Starting port number (default: 3000)
|
|
103
|
+
- `HOST` - Host address (default: localhost)
|
|
104
|
+
|
|
105
|
+
**Features:**
|
|
106
|
+
- Starts bootstrap hub first
|
|
107
|
+
- Starts secondary hubs with auto-connect
|
|
108
|
+
- Displays network topology
|
|
109
|
+
- Shows periodic statistics (every 30 seconds)
|
|
110
|
+
- Graceful shutdown of all hubs
|
|
111
|
+
|
|
112
|
+
## Hub Features
|
|
113
|
+
|
|
114
|
+
### Automatic Connection
|
|
115
|
+
|
|
116
|
+
Secondary hubs automatically connect to the bootstrap hub and discover other hubs through it.
|
|
117
|
+
|
|
118
|
+
### Auto-Reconnection
|
|
119
|
+
|
|
120
|
+
If a hub loses connection to the bootstrap, it automatically attempts to reconnect:
|
|
121
|
+
- Reconnect interval: 5 seconds
|
|
122
|
+
- Max attempts: 10
|
|
123
|
+
- Exponential backoff
|
|
124
|
+
|
|
125
|
+
### Event Monitoring
|
|
126
|
+
|
|
127
|
+
All scripts display real-time events:
|
|
128
|
+
- ✅ Peer connections
|
|
129
|
+
- 🏢 Hub registrations
|
|
130
|
+
- 🔗 Bootstrap connections
|
|
131
|
+
- 🔍 Hub discovery
|
|
132
|
+
- 📢 Peer announcements
|
|
133
|
+
|
|
134
|
+
### Statistics
|
|
135
|
+
|
|
136
|
+
Periodic statistics are displayed showing:
|
|
137
|
+
- Total connections
|
|
138
|
+
- Number of hubs
|
|
139
|
+
- Number of peers
|
|
140
|
+
- Active networks
|
|
141
|
+
- Bootstrap connection status
|
|
142
|
+
|
|
143
|
+
## Network Topologies
|
|
144
|
+
|
|
145
|
+
### Basic Topology
|
|
146
|
+
|
|
147
|
+
```
|
|
148
|
+
Bootstrap Hub (3000)
|
|
149
|
+
↑
|
|
150
|
+
├── Hub 1 (3001)
|
|
151
|
+
├── Hub 2 (3002)
|
|
152
|
+
└── Hub 3 (3003)
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Redundant Topology
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
# Hub 1 with multiple bootstrap hubs
|
|
159
|
+
BOOTSTRAP=ws://localhost:3000,ws://localhost:3001 PORT=3005 npm run hub
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
Bootstrap Hub 1 (3000) ←→ Hub (3005)
|
|
164
|
+
Bootstrap Hub 2 (3001) ←→ Hub (3005)
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Monitoring
|
|
168
|
+
|
|
169
|
+
### Health Check
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
curl http://localhost:3000/health
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Response:
|
|
176
|
+
```json
|
|
177
|
+
{
|
|
178
|
+
"status": "healthy",
|
|
179
|
+
"isHub": true,
|
|
180
|
+
"connections": 3,
|
|
181
|
+
"hubs": 2,
|
|
182
|
+
"peers": 1,
|
|
183
|
+
"networks": 2
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### List Connected Hubs
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
curl http://localhost:3000/hubs
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Response:
|
|
194
|
+
```json
|
|
195
|
+
{
|
|
196
|
+
"totalHubs": 3,
|
|
197
|
+
"hubs": [
|
|
198
|
+
{
|
|
199
|
+
"peerId": "abc123...",
|
|
200
|
+
"networkName": "pigeonhub-mesh",
|
|
201
|
+
"registeredAt": 1696334400000
|
|
202
|
+
}
|
|
203
|
+
]
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## Production Deployment
|
|
208
|
+
|
|
209
|
+
### Using PM2
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
# Install PM2
|
|
213
|
+
npm install -g pm2
|
|
214
|
+
|
|
215
|
+
# Start bootstrap hub
|
|
216
|
+
pm2 start scripts/start-hub.js --name hub-bootstrap -- --bootstrap
|
|
217
|
+
|
|
218
|
+
# Start secondary hubs
|
|
219
|
+
PORT=3001 pm2 start scripts/start-hub.js --name hub-3001
|
|
220
|
+
PORT=3002 pm2 start scripts/start-hub.js --name hub-3002
|
|
221
|
+
PORT=3003 pm2 start scripts/start-hub.js --name hub-3003
|
|
222
|
+
|
|
223
|
+
# Save configuration
|
|
224
|
+
pm2 save
|
|
225
|
+
|
|
226
|
+
# Setup auto-restart on reboot
|
|
227
|
+
pm2 startup
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Using Docker
|
|
231
|
+
|
|
232
|
+
Create a `Dockerfile`:
|
|
233
|
+
```dockerfile
|
|
234
|
+
FROM node:20
|
|
235
|
+
WORKDIR /app
|
|
236
|
+
COPY package*.json ./
|
|
237
|
+
RUN npm ci --only=production
|
|
238
|
+
COPY . .
|
|
239
|
+
CMD ["npm", "run", "hub"]
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Run:
|
|
243
|
+
```bash
|
|
244
|
+
# Bootstrap hub
|
|
245
|
+
docker run -p 3000:3000 -e PORT=3000 peerpigeon-hub --bootstrap
|
|
246
|
+
|
|
247
|
+
# Secondary hubs
|
|
248
|
+
docker run -p 3001:3001 -e PORT=3001 -e BOOTSTRAP=ws://bootstrap:3000 peerpigeon-hub
|
|
249
|
+
docker run -p 3002:3002 -e PORT=3002 -e BOOTSTRAP=ws://bootstrap:3000 peerpigeon-hub
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### Using Systemd
|
|
253
|
+
|
|
254
|
+
Create `/etc/systemd/system/peerpigeon-hub@.service`:
|
|
255
|
+
```ini
|
|
256
|
+
[Unit]
|
|
257
|
+
Description=PeerPigeon Hub on port %i
|
|
258
|
+
After=network.target
|
|
259
|
+
|
|
260
|
+
[Service]
|
|
261
|
+
Type=simple
|
|
262
|
+
User=peerpigeon
|
|
263
|
+
WorkingDirectory=/opt/peerpigeon
|
|
264
|
+
Environment="PORT=%i"
|
|
265
|
+
ExecStart=/usr/bin/node scripts/start-hub.js
|
|
266
|
+
Restart=always
|
|
267
|
+
|
|
268
|
+
[Install]
|
|
269
|
+
WantedBy=multi-user.target
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Enable and start:
|
|
273
|
+
```bash
|
|
274
|
+
# Bootstrap hub
|
|
275
|
+
systemctl enable peerpigeon-hub@3000
|
|
276
|
+
systemctl start peerpigeon-hub@3000
|
|
277
|
+
|
|
278
|
+
# Secondary hubs
|
|
279
|
+
systemctl enable peerpigeon-hub@3001
|
|
280
|
+
systemctl start peerpigeon-hub@3001
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
## Troubleshooting
|
|
284
|
+
|
|
285
|
+
### Port Already in Use
|
|
286
|
+
|
|
287
|
+
The hub will automatically try the next available port:
|
|
288
|
+
```
|
|
289
|
+
⚠️ Port 3000 is already in use
|
|
290
|
+
🔄 Trying port 3001...
|
|
291
|
+
✅ Port 3000 was in use, using port 3001 instead
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
### Can't Connect to Bootstrap
|
|
295
|
+
|
|
296
|
+
Check that the bootstrap hub is running:
|
|
297
|
+
```bash
|
|
298
|
+
curl http://localhost:3000/health
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Verify the bootstrap URI is correct:
|
|
302
|
+
```bash
|
|
303
|
+
BOOTSTRAP=ws://localhost:3000 npm run hub
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
### Hub Not Discovering Others
|
|
307
|
+
|
|
308
|
+
1. Ensure hubs are using `pigeonhub-mesh` namespace
|
|
309
|
+
2. Check that `autoConnect` is enabled
|
|
310
|
+
3. Verify network connectivity between hubs
|
|
311
|
+
4. Check firewall rules
|
|
312
|
+
|
|
313
|
+
### Memory Issues
|
|
314
|
+
|
|
315
|
+
Adjust Node.js memory limits:
|
|
316
|
+
```bash
|
|
317
|
+
NODE_OPTIONS="--max-old-space-size=4096" npm run hub:network
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
## Examples
|
|
321
|
+
|
|
322
|
+
See the `examples/` directory for more detailed examples:
|
|
323
|
+
- `examples/hub-example.js` - Basic hub usage
|
|
324
|
+
- `examples/bootstrap-hub-example.js` - Bootstrap hub examples
|
|
325
|
+
|
|
326
|
+
## Support
|
|
327
|
+
|
|
328
|
+
For more information, see:
|
|
329
|
+
- [HUB_SYSTEM.md](HUB_SYSTEM.md) - Complete hub system documentation
|
|
330
|
+
- [API_DOCUMENTATION.md](API_DOCUMENTATION.md) - API reference
|
|
331
|
+
- [README.md](../README.md) - Main project documentation
|