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.
@@ -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
@@ -104,4 +104,5 @@ pm2 startup
104
104
  - Host: localhost
105
105
  - Reconnect Interval: 5 seconds
106
106
  - Max Reconnect Attempts: 10
107
- - Hub Mesh Namespace: pigeonhub-mesh
107
+ - Hub Mesh Namespace: pigeonhub-mesh (configurable via `HUB_MESH_NAMESPACE`)
108
+
@@ -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
@@ -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
- The `pigeonhub-mesh` namespace is reserved for hub-to-hub connections. When a hub announces on this namespace:
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