peerpigeon 1.0.0 → 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/dist/peerpigeon-browser.js +250 -90
- package/dist/peerpigeon-browser.js.map +4 -4
- package/docs/API_DOCUMENTATION.md +31 -0
- package/docs/CUSTOM_HUB_NAMESPACES.md +182 -0
- package/docs/CUSTOM_NAMESPACE_IMPLEMENTATION.md +187 -0
- package/docs/HUB_QUICK_REF.md +2 -1
- package/docs/HUB_SCRIPTS.md +10 -0
- package/docs/HUB_SYSTEM.md +49 -2
- package/docs/PIGEONRTC_MIGRATION.md +280 -0
- package/docs/README.md +1 -0
- package/examples/browser/app.js +1 -1
- package/examples/hub-example.js +4 -1
- package/examples/programmatic-namespace-example.js +108 -0
- package/index.js +7 -1
- package/package.json +2 -1
- package/server/index.js +27 -1
- package/server/start.js +3 -0
- package/src/EnvironmentDetector.js +59 -82
- package/src/MediaManager.js +12 -2
- package/src/PeerConnection.js +10 -1
- package/src/PeerPigeonMesh.js +8 -9
- package/src/PigeonRTC-browser.js +247 -0
- package/src/browser-entry.js +20 -2
|
@@ -1732,12 +1732,15 @@ new PeerPigeonServer(options = {})
|
|
|
1732
1732
|
- `options.maxMessageSize` (number, default: 1048576) - Max message size in bytes (1MB)
|
|
1733
1733
|
- `options.maxPortRetries` (number, default: 10) - Port retry attempts if port in use
|
|
1734
1734
|
- `options.isHub` (boolean, default: false) - Run as a hub server
|
|
1735
|
+
- `options.hubMeshNamespace` (string, default: 'pigeonhub-mesh') - Network namespace for hub-to-hub connections
|
|
1735
1736
|
- `options.hubPeerId` (string, optional) - Custom hub peer ID (auto-generated if hub)
|
|
1736
1737
|
- `options.bootstrapHubs` (Array<string>, default: []) - URIs of bootstrap hubs to connect to
|
|
1737
1738
|
- `options.autoConnect` (boolean, default: true) - Auto-connect to bootstrap hubs
|
|
1738
1739
|
- `options.reconnectInterval` (number, default: 5000) - Hub reconnect interval in ms
|
|
1739
1740
|
- `options.maxReconnectAttempts` (number, default: 10) - Max hub reconnection attempts
|
|
1740
1741
|
|
|
1742
|
+
**Note:** All hubs in the same network must use the same `hubMeshNamespace` to discover and connect to each other. The default `'pigeonhub-mesh'` namespace works for most deployments, but you can specify a custom namespace to isolate different hub networks.
|
|
1743
|
+
|
|
1741
1744
|
#### Methods
|
|
1742
1745
|
|
|
1743
1746
|
#### `async start()`
|
|
@@ -1762,6 +1765,7 @@ Get comprehensive server statistics.
|
|
|
1762
1765
|
isRunning: boolean,
|
|
1763
1766
|
isHub: boolean,
|
|
1764
1767
|
hubPeerId: string | null,
|
|
1768
|
+
hubMeshNamespace: string, // Current hub mesh namespace
|
|
1765
1769
|
connections: number,
|
|
1766
1770
|
peers: number,
|
|
1767
1771
|
hubs: number,
|
|
@@ -1795,6 +1799,33 @@ Get list of all connected peers.
|
|
|
1795
1799
|
|
|
1796
1800
|
**Returns:** `Array<Object>` - Array of peer information objects
|
|
1797
1801
|
|
|
1802
|
+
#### `getHubMeshNamespace()`
|
|
1803
|
+
Get the current hub mesh namespace.
|
|
1804
|
+
|
|
1805
|
+
**Returns:** `string` - Current hub mesh namespace
|
|
1806
|
+
|
|
1807
|
+
```javascript
|
|
1808
|
+
const namespace = server.getHubMeshNamespace();
|
|
1809
|
+
console.log('Hub namespace:', namespace); // 'pigeonhub-mesh'
|
|
1810
|
+
```
|
|
1811
|
+
|
|
1812
|
+
#### `setHubMeshNamespace(namespace)`
|
|
1813
|
+
Set the hub mesh namespace. Can only be called when server is stopped.
|
|
1814
|
+
|
|
1815
|
+
**Parameters:**
|
|
1816
|
+
- `namespace` (string) - New hub mesh namespace (non-empty string)
|
|
1817
|
+
|
|
1818
|
+
**Returns:** `string` - The set namespace
|
|
1819
|
+
**Throws:** Error if server is running or namespace is invalid
|
|
1820
|
+
|
|
1821
|
+
```javascript
|
|
1822
|
+
// Must be called before starting the server
|
|
1823
|
+
server.setHubMeshNamespace('production-mesh');
|
|
1824
|
+
await server.start();
|
|
1825
|
+
```
|
|
1826
|
+
|
|
1827
|
+
**Important:** All hubs in the same network must use the same namespace to discover each other.
|
|
1828
|
+
|
|
1798
1829
|
#### `broadcastToOthers(senderPeerId, message)`
|
|
1799
1830
|
Broadcast to all peers except sender.
|
|
1800
1831
|
|
|
@@ -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
|
package/docs/HUB_QUICK_REF.md
CHANGED
package/docs/HUB_SCRIPTS.md
CHANGED
|
@@ -58,6 +58,14 @@ BOOTSTRAP=ws://hub1.example.com:3000,ws://hub2.example.com:3000 npm run hub
|
|
|
58
58
|
HUB_ID=a1b2c3d4e5f6789012345678901234567890abcd npm run hub
|
|
59
59
|
```
|
|
60
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
|
+
|
|
61
69
|
### Disable Auto-Connect
|
|
62
70
|
|
|
63
71
|
```bash
|
|
@@ -82,6 +90,7 @@ PORT=3002 node scripts/start-hub.js # Custom port
|
|
|
82
90
|
- `HOST` - Host address (default: localhost)
|
|
83
91
|
- `BOOTSTRAP` - Comma-separated bootstrap hub URIs
|
|
84
92
|
- `HUB_ID` - Custom 40-character hex peer ID
|
|
93
|
+
- `HUB_MESH_NAMESPACE` - Custom hub mesh namespace (default: pigeonhub-mesh)
|
|
85
94
|
- `AUTO_CONNECT` - Auto-connect to bootstrap (default: true)
|
|
86
95
|
|
|
87
96
|
**Command Line Flags:**
|
|
@@ -101,6 +110,7 @@ HUB_COUNT=6 node scripts/start-hub-network.js # Start 6 hubs (ports 3000-3005)
|
|
|
101
110
|
- `HUB_COUNT` - Number of hubs to start (default: 4)
|
|
102
111
|
- `START_PORT` - Starting port number (default: 3000)
|
|
103
112
|
- `HOST` - Host address (default: localhost)
|
|
113
|
+
- `HUB_MESH_NAMESPACE` - Custom hub mesh namespace (default: pigeonhub-mesh)
|
|
104
114
|
|
|
105
115
|
**Features:**
|
|
106
116
|
- Starts bootstrap hub first
|
package/docs/HUB_SYSTEM.md
CHANGED
|
@@ -39,9 +39,9 @@ PeerPigeon supports a hub system where certain nodes can act as **hubs** - long-
|
|
|
39
39
|
(app-net) (app-net) (app-net)
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
## Hub Namespace: `pigeonhub-mesh`
|
|
42
|
+
## Hub Namespace: `pigeonhub-mesh` (Configurable)
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
By default, the `pigeonhub-mesh` namespace is reserved for hub-to-hub connections. However, you can configure a custom hub mesh namespace for your deployment. When a hub announces on this namespace:
|
|
45
45
|
|
|
46
46
|
1. The signaling server identifies it as a hub
|
|
47
47
|
2. It's registered in the hub registry
|
|
@@ -49,6 +49,8 @@ The `pigeonhub-mesh` namespace is reserved for hub-to-hub connections. When a hu
|
|
|
49
49
|
4. Other hubs are notified about this new hub
|
|
50
50
|
5. Hubs can then establish WebRTC connections to each other
|
|
51
51
|
|
|
52
|
+
**Note:** All hubs in the same network must use the same namespace to discover and connect to each other.
|
|
53
|
+
|
|
52
54
|
## Server Configuration
|
|
53
55
|
|
|
54
56
|
### Creating a Hub Server
|
|
@@ -60,6 +62,7 @@ const hubServer = new PeerPigeonServer({
|
|
|
60
62
|
port: 3000,
|
|
61
63
|
host: 'localhost',
|
|
62
64
|
isHub: true, // Mark this server as a hub
|
|
65
|
+
hubMeshNamespace: 'pigeonhub-mesh', // Optional: defaults to 'pigeonhub-mesh'
|
|
63
66
|
maxConnections: 1000,
|
|
64
67
|
cleanupInterval: 30000
|
|
65
68
|
});
|
|
@@ -76,6 +79,50 @@ hubServer.on('hubUnregistered', ({ peerId, totalHubs }) => {
|
|
|
76
79
|
await hubServer.start();
|
|
77
80
|
```
|
|
78
81
|
|
|
82
|
+
### Using a Custom Hub Namespace
|
|
83
|
+
|
|
84
|
+
You can use a custom namespace for your hub network to isolate different hub deployments:
|
|
85
|
+
|
|
86
|
+
```javascript
|
|
87
|
+
const hubServer = new PeerPigeonServer({
|
|
88
|
+
port: 3000,
|
|
89
|
+
host: 'localhost',
|
|
90
|
+
isHub: true,
|
|
91
|
+
hubMeshNamespace: 'my-custom-hub-mesh', // Custom namespace
|
|
92
|
+
maxConnections: 1000
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
All hubs in the same deployment should use the same `hubMeshNamespace` to form a unified hub mesh.
|
|
97
|
+
|
|
98
|
+
### Programmatic API for Hub Namespace
|
|
99
|
+
|
|
100
|
+
You can also get and set the hub mesh namespace programmatically:
|
|
101
|
+
|
|
102
|
+
```javascript
|
|
103
|
+
// Create hub with default namespace
|
|
104
|
+
const hubServer = new PeerPigeonServer({
|
|
105
|
+
port: 3000,
|
|
106
|
+
isHub: true
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
// Get current namespace
|
|
110
|
+
const namespace = hubServer.getHubMeshNamespace();
|
|
111
|
+
console.log('Current namespace:', namespace); // 'pigeonhub-mesh'
|
|
112
|
+
|
|
113
|
+
// Set custom namespace (only when server is not running)
|
|
114
|
+
hubServer.setHubMeshNamespace('production-mesh');
|
|
115
|
+
|
|
116
|
+
// Start the server
|
|
117
|
+
await hubServer.start();
|
|
118
|
+
|
|
119
|
+
// Get server stats including namespace
|
|
120
|
+
const stats = hubServer.getStats();
|
|
121
|
+
console.log('Hub mesh namespace:', stats.hubMeshNamespace);
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Important:** You can only change the namespace when the server is stopped. Attempting to change it while running will throw an error.
|
|
125
|
+
|
|
79
126
|
### Creating a Regular Server
|
|
80
127
|
|
|
81
128
|
```javascript
|