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.
- package/README.md +141 -1365
- package/cli.js +1382 -0
- package/dist/peerpigeon-browser.js +12450 -0
- package/dist/peerpigeon-browser.js.map +7 -0
- package/docs/API_DOCUMENTATION.md +1976 -0
- package/docs/BOOTSTRAP_HUBS.md +319 -0
- package/docs/CLI_README.md +371 -0
- package/docs/CUSTOM_HUB_NAMESPACES.md +182 -0
- package/docs/CUSTOM_NAMESPACE_IMPLEMENTATION.md +187 -0
- package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
- package/docs/HUB_QUICK_REF.md +108 -0
- package/docs/HUB_SCRIPTS.md +341 -0
- package/docs/HUB_SYSTEM.md +599 -0
- package/docs/MIGRATION_COMPLETE.md +93 -0
- package/docs/NETWORK_NAMESPACES.md +212 -0
- package/docs/PIGEONRTC_MIGRATION.md +280 -0
- package/docs/README.md +108 -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 +189 -0
- package/examples/multi-hub-test.js +186 -0
- package/examples/node/README.md +2 -2
- package/examples/programmatic-namespace-example.js +108 -0
- package/examples/selective-streaming-demo.html +698 -0
- package/examples/standard-events-demo.js +126 -0
- package/index.js +7 -1
- package/package.json +34 -16
- package/server/index.js +1058 -98
- package/server/start.js +52 -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 +88 -4
- package/src/EventEmitter.js +79 -1
- package/src/EvictionManager.js +10 -9
- package/src/GossipManager.js +163 -11
- package/src/MediaManager.js +12 -2
- package/src/PeerConnection.js +343 -311
- package/src/PeerPigeonMesh.js +576 -135
- package/src/PigeonRTC-browser.js +247 -0
- 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 +58 -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,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
|
+
|