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,182 @@
1
+ # Custom Hub Network Namespaces
2
+
3
+ ## Overview
4
+
5
+ PeerPigeon hubs communicate with each other on a dedicated network namespace to form their own mesh network. By default, this namespace is `pigeonhub-mesh`, but you can configure a custom namespace for your deployment.
6
+
7
+ ## Why Use Custom Namespaces?
8
+
9
+ Custom hub namespaces allow you to:
10
+
11
+ 1. **Isolate Different Deployments** - Run multiple independent hub networks on the same signaling server
12
+ 2. **Environment Separation** - Use different namespaces for development, staging, and production environments
13
+ 3. **Multi-Tenant Systems** - Create separate hub networks for different organizations or customers
14
+ 4. **Testing and Development** - Test new hub configurations without affecting production hubs
15
+
16
+ ## Configuration
17
+
18
+ ### Environment Variable
19
+
20
+ The simplest way to set a custom namespace is via the `HUB_MESH_NAMESPACE` environment variable:
21
+
22
+ ```bash
23
+ # Start a hub with custom namespace
24
+ HUB_MESH_NAMESPACE=my-custom-mesh npm run hub
25
+
26
+ # Start a hub network with custom namespace
27
+ HUB_MESH_NAMESPACE=production-mesh node scripts/start-hub-network.js
28
+
29
+ # Start signaling server with custom namespace
30
+ HUB_MESH_NAMESPACE=dev-mesh npm run server
31
+ ```
32
+
33
+ ### Programmatic Configuration
34
+
35
+ You can also set the namespace programmatically when creating a server:
36
+
37
+ ```javascript
38
+ import { PeerPigeonServer } from './server/index.js';
39
+
40
+ const hubServer = new PeerPigeonServer({
41
+ port: 3000,
42
+ host: 'localhost',
43
+ isHub: true,
44
+ hubMeshNamespace: 'production-hub-mesh'
45
+ });
46
+
47
+ await hubServer.start();
48
+ ```
49
+
50
+ ## Important Considerations
51
+
52
+ ### All Hubs Must Use the Same Namespace
53
+
54
+ **Critical:** All hubs in the same deployment must use the **exact same namespace** to discover and connect to each other. If hubs use different namespaces, they won't be able to form a mesh network.
55
+
56
+ ```bash
57
+ # ✅ CORRECT - All hubs use the same namespace
58
+ HUB_MESH_NAMESPACE=production-mesh PORT=3000 npm run hub &
59
+ HUB_MESH_NAMESPACE=production-mesh PORT=3001 npm run hub &
60
+ HUB_MESH_NAMESPACE=production-mesh PORT=3002 npm run hub &
61
+
62
+ # ❌ WRONG - Hubs use different namespaces (won't connect)
63
+ HUB_MESH_NAMESPACE=production-mesh PORT=3000 npm run hub &
64
+ HUB_MESH_NAMESPACE=staging-mesh PORT=3001 npm run hub &
65
+ ```
66
+
67
+ ### Namespace Naming Guidelines
68
+
69
+ - Use lowercase letters, numbers, and hyphens
70
+ - Be descriptive and meaningful (e.g., `production-hub-mesh`, `dev-testing-mesh`)
71
+ - Avoid special characters that might cause issues in URLs or filenames
72
+ - Keep it consistent across your deployment
73
+
74
+ ### Default Namespace
75
+
76
+ If you don't specify a custom namespace, hubs will use the default `pigeonhub-mesh` namespace. This is fine for most deployments and ensures backward compatibility.
77
+
78
+ ## Use Cases
79
+
80
+ ### 1. Multi-Environment Deployment
81
+
82
+ ```bash
83
+ # Development environment
84
+ HUB_MESH_NAMESPACE=dev-mesh npm run hub
85
+
86
+ # Staging environment
87
+ HUB_MESH_NAMESPACE=staging-mesh npm run hub
88
+
89
+ # Production environment
90
+ HUB_MESH_NAMESPACE=production-mesh npm run hub
91
+ ```
92
+
93
+ ### 2. Multi-Tenant System
94
+
95
+ ```bash
96
+ # Organization A's hub network
97
+ HUB_MESH_NAMESPACE=org-a-mesh npm run hub
98
+
99
+ # Organization B's hub network
100
+ HUB_MESH_NAMESPACE=org-b-mesh npm run hub
101
+ ```
102
+
103
+ ### 3. Feature Testing
104
+
105
+ ```bash
106
+ # Production hubs
107
+ HUB_MESH_NAMESPACE=production-mesh npm run hub
108
+
109
+ # Experimental feature hubs (isolated from production)
110
+ HUB_MESH_NAMESPACE=experimental-features-mesh npm run hub
111
+ ```
112
+
113
+ ## Verification
114
+
115
+ You can verify that hubs are using the correct namespace by checking the server logs:
116
+
117
+ ```bash
118
+ # When starting a hub with custom namespace, you'll see:
119
+ 🚀 Starting PeerPigeon Hub...
120
+ 🌐 Using custom hub mesh namespace: production-mesh
121
+
122
+ ✅ Hub running on ws://localhost:3000
123
+ ```
124
+
125
+ You can also check the server's configuration programmatically:
126
+
127
+ ```javascript
128
+ console.log('Hub mesh namespace:', hubServer.hubMeshNamespace);
129
+ ```
130
+
131
+ ## Client Announcements
132
+
133
+ When clients want to connect as hubs, they should announce on the same namespace:
134
+
135
+ ```javascript
136
+ // Client announces as a hub
137
+ const announceMessage = {
138
+ type: 'announce',
139
+ networkName: 'production-mesh', // Use the same namespace as your hub deployment
140
+ data: {
141
+ isHub: true,
142
+ capabilities: ['signaling', 'relay']
143
+ }
144
+ };
145
+
146
+ ws.send(JSON.stringify(announceMessage));
147
+ ```
148
+
149
+ ## Troubleshooting
150
+
151
+ ### Hubs Not Discovering Each Other
152
+
153
+ **Problem:** Hubs are running but not forming connections.
154
+
155
+ **Solution:** Verify all hubs are using the same `hubMeshNamespace`:
156
+ - Check environment variables
157
+ - Review server logs for namespace information
158
+ - Ensure bootstrap hub URIs are correct
159
+
160
+ ### Mixed Namespace Configuration
161
+
162
+ **Problem:** Some hubs use default namespace, others use custom namespace.
163
+
164
+ **Solution:** Standardize the namespace across all hubs in your deployment. Either:
165
+ - Use default `pigeonhub-mesh` for all hubs (remove custom config)
166
+ - Set the same custom namespace for all hubs
167
+
168
+ ## Best Practices
169
+
170
+ 1. **Document Your Namespace** - Keep a record of which namespaces are used in which environments
171
+ 2. **Use Environment Variables** - Makes it easier to deploy the same code to different environments
172
+ 3. **Consistent Naming** - Use a naming convention across all your namespaces
173
+ 4. **Test Isolation** - Verify that hubs in different namespaces don't interfere with each other
174
+ 5. **Monitor Hub Connections** - Use the `/hubs` endpoint to verify hubs are discovering each other
175
+
176
+ ## Related Documentation
177
+
178
+ - [Hub System Overview](./HUB_SYSTEM.md)
179
+ - [Hub Scripts](./HUB_SCRIPTS.md)
180
+ - [Hub Quick Reference](./HUB_QUICK_REF.md)
181
+ - [API Documentation](./API_DOCUMENTATION.md)
182
+ - [Network Namespaces (for peers)](./NETWORK_NAMESPACES.md)
@@ -0,0 +1,187 @@
1
+ # Custom Hub Network Namespace Feature - Implementation Summary
2
+
3
+ ## Overview
4
+
5
+ Added support for custom hub network namespaces with a default fallback to `pigeonhub-mesh`. This allows deployments to isolate different hub networks while maintaining backward compatibility.
6
+
7
+ ## Changes Made
8
+
9
+ ### 1. Core Server Configuration (`server/index.js`)
10
+
11
+ **Modified:** Constructor to accept `hubMeshNamespace` option
12
+ - Added `options.hubMeshNamespace` parameter with default value `'pigeonhub-mesh'`
13
+ - Changed from hardcoded string to configurable option
14
+ - Maintains backward compatibility (defaults to existing behavior)
15
+
16
+ ```javascript
17
+ // Before:
18
+ this.hubMeshNamespace = 'pigeonhub-mesh';
19
+
20
+ // After:
21
+ this.hubMeshNamespace = options.hubMeshNamespace || 'pigeonhub-mesh';
22
+ ```
23
+
24
+ ### 2. Server Startup Scripts
25
+
26
+ #### `server/start.js`
27
+ - Added `HUB_MESH_NAMESPACE` environment variable support
28
+ - Passes namespace to PeerPigeonServer constructor
29
+ - Updated documentation comment
30
+
31
+ #### `scripts/start-hub.js`
32
+ - Added `HUB_MESH_NAMESPACE` environment variable support
33
+ - Displays custom namespace message when non-default value is used
34
+ - Updated usage documentation in header comment
35
+
36
+ #### `scripts/start-hub-network.js`
37
+ - Added `HUB_MESH_NAMESPACE` environment variable support
38
+ - Passes namespace to all hubs (bootstrap and secondary)
39
+ - Displays namespace in configuration output
40
+
41
+ ### 3. Documentation Updates
42
+
43
+ #### New Documentation
44
+ - **`docs/CUSTOM_HUB_NAMESPACES.md`** - Complete guide for custom namespaces
45
+ - Overview and use cases
46
+ - Configuration methods (env vars and programmatic)
47
+ - Important considerations
48
+ - Best practices
49
+ - Troubleshooting guide
50
+
51
+ #### Updated Documentation
52
+ - **`docs/HUB_SYSTEM.md`**
53
+ - Updated Hub Namespace section
54
+ - Added configuration examples showing custom namespaces
55
+ - Documented the hubMeshNamespace option
56
+
57
+ - **`docs/HUB_SCRIPTS.md`**
58
+ - Added HUB_MESH_NAMESPACE to environment variables section
59
+ - Added example usage
60
+ - Updated both start-hub.js and start-hub-network.js documentation
61
+
62
+ - **`docs/HUB_QUICK_REF.md`**
63
+ - Updated default configuration section
64
+ - Added note about configurability
65
+
66
+ - **`docs/API_DOCUMENTATION.md`**
67
+ - Added `hubMeshNamespace` parameter to PeerPigeonServer constructor docs
68
+ - Added explanation note about namespace consistency
69
+
70
+ - **`docs/README.md`**
71
+ - Added link to Custom Hub Namespaces guide
72
+
73
+ - **`examples/hub-example.js`**
74
+ - Updated comments to mention configurability
75
+ - Added note about custom namespaces
76
+
77
+ ### 4. Testing
78
+
79
+ Created `test/test-custom-namespace.js` to verify:
80
+ - Default namespace behavior (backward compatibility)
81
+ - Custom namespace via constructor option
82
+ - Environment variable support
83
+ - Regular server namespace configuration
84
+
85
+ All tests pass successfully.
86
+
87
+ ## Backward Compatibility
88
+
89
+ ✅ **Fully backward compatible** - All existing code continues to work without changes:
90
+ - Default namespace is still `'pigeonhub-mesh'`
91
+ - No breaking changes to API
92
+ - Existing hubs will continue to work without modification
93
+
94
+ ## Usage Examples
95
+
96
+ ### Environment Variable (Recommended)
97
+
98
+ ```bash
99
+ # Start a single hub with custom namespace
100
+ HUB_MESH_NAMESPACE=production-mesh npm run hub
101
+
102
+ # Start a hub network with custom namespace
103
+ HUB_MESH_NAMESPACE=staging-mesh node scripts/start-hub-network.js
104
+
105
+ # Multiple environments
106
+ HUB_MESH_NAMESPACE=dev-mesh PORT=3000 npm run hub &
107
+ HUB_MESH_NAMESPACE=prod-mesh PORT=4000 npm run hub &
108
+ ```
109
+
110
+ ### Programmatic Configuration
111
+
112
+ ```javascript
113
+ import { PeerPigeonServer } from './server/index.js';
114
+
115
+ const hub = new PeerPigeonServer({
116
+ port: 3000,
117
+ isHub: true,
118
+ hubMeshNamespace: 'my-custom-mesh'
119
+ });
120
+
121
+ await hub.start();
122
+ ```
123
+
124
+ ## Key Features
125
+
126
+ 1. **Default Fallback** - Uses `pigeonhub-mesh` if not specified
127
+ 2. **Environment Variable Support** - Easy deployment configuration
128
+ 3. **Programmatic API** - Full control via constructor options
129
+ 4. **Consistent Configuration** - All hubs must use same namespace
130
+ 5. **Complete Documentation** - Comprehensive guides and examples
131
+
132
+ ## Important Notes
133
+
134
+ ⚠️ **All hubs in the same network must use the same namespace** to discover and connect to each other.
135
+
136
+ ✅ **Use consistent naming** - Keep namespace consistent across all hubs in a deployment.
137
+
138
+ ✅ **Document your namespaces** - Maintain a record of which namespaces are used where.
139
+
140
+ ## Files Modified
141
+
142
+ 1. `server/index.js` - Core server configuration
143
+ 2. `server/start.js` - Standalone server startup
144
+ 3. `scripts/start-hub.js` - Single hub startup script
145
+ 4. `scripts/start-hub-network.js` - Hub network startup script
146
+ 5. `docs/HUB_SYSTEM.md` - Hub system documentation
147
+ 6. `docs/HUB_SCRIPTS.md` - Hub scripts documentation
148
+ 7. `docs/HUB_QUICK_REF.md` - Quick reference guide
149
+ 8. `docs/API_DOCUMENTATION.md` - API reference
150
+ 9. `docs/README.md` - Documentation index
151
+ 10. `examples/hub-example.js` - Hub example code
152
+
153
+ ## Files Created
154
+
155
+ 1. `docs/CUSTOM_HUB_NAMESPACES.md` - Comprehensive namespace guide
156
+ 2. `test/test-custom-namespace.js` - Feature verification tests
157
+
158
+ ## Testing
159
+
160
+ Run the test to verify the implementation:
161
+
162
+ ```bash
163
+ node test/test-custom-namespace.js
164
+ ```
165
+
166
+ All tests pass, confirming:
167
+ - ✅ Default namespace works
168
+ - ✅ Custom namespaces via constructor work
169
+ - ✅ Environment variable support works
170
+ - ✅ Regular servers support custom namespaces
171
+
172
+ ## Migration Path
173
+
174
+ For existing deployments:
175
+ 1. **No action required** - Default behavior unchanged
176
+ 2. To use custom namespaces:
177
+ - Set `HUB_MESH_NAMESPACE` environment variable
178
+ - Or pass `hubMeshNamespace` in constructor options
179
+ - Ensure all hubs use the same namespace
180
+
181
+ ## Future Enhancements
182
+
183
+ Possible future improvements:
184
+ - Hub discovery across multiple namespaces
185
+ - Namespace-based access controls
186
+ - Dynamic namespace switching
187
+ - Namespace registry and management API
@@ -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,108 @@
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 (configurable via `HUB_MESH_NAMESPACE`)
108
+