peerpigeon 0.1.1 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +141 -1365
- package/cli.js +1382 -0
- package/dist/peerpigeon-browser.js +12290 -0
- package/dist/peerpigeon-browser.js.map +7 -0
- package/docs/API_DOCUMENTATION.md +1945 -0
- package/docs/BOOTSTRAP_HUBS.md +319 -0
- package/docs/CLI_README.md +371 -0
- package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
- package/docs/HUB_QUICK_REF.md +107 -0
- package/docs/HUB_SCRIPTS.md +331 -0
- package/docs/HUB_SYSTEM.md +552 -0
- package/docs/MIGRATION_COMPLETE.md +93 -0
- package/docs/NETWORK_NAMESPACES.md +212 -0
- package/docs/README.md +107 -0
- package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
- package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
- package/examples/bootstrap-hub-example.js +292 -0
- package/examples/browser/README.md +278 -0
- package/examples/browser/app.js +2426 -49
- package/examples/browser/index.html +481 -630
- package/examples/browser/minimal/README.md +55 -0
- package/examples/browser/minimal/index.html +75 -0
- package/examples/browser/minimal/minimal.js +234 -0
- package/examples/browser/styles.css +687 -1425
- package/examples/browser/test-bundle.html +35 -0
- package/examples/browser-2/index.html +30 -0
- package/examples/browser-2/package.json +21 -0
- package/examples/browser-2/src/App-simple.vue +21 -0
- package/examples/browser-2/src/App.vue +420 -0
- package/examples/browser-2/src/components/CryptoView.vue +1661 -0
- package/examples/browser-2/src/components/DHTView.vue +1281 -0
- package/examples/browser-2/src/components/DebugView.vue +1773 -0
- package/examples/browser-2/src/components/MediaView.vue +1048 -0
- package/examples/browser-2/src/components/MessagingView.vue +775 -0
- package/examples/browser-2/src/components/NetworkView.vue +930 -0
- package/examples/browser-2/src/components/StorageView.vue +1376 -0
- package/examples/browser-2/src/main.js +5 -0
- package/examples/browser-2/src/stores/peerpigeon.js +895 -0
- package/examples/browser-2/vite.config.js +6 -0
- package/examples/hub-example.js +186 -0
- package/examples/multi-hub-test.js +186 -0
- package/examples/node/README.md +2 -2
- package/examples/selective-streaming-demo.html +698 -0
- package/examples/standard-events-demo.js +126 -0
- package/package.json +33 -16
- package/server/index.js +1032 -98
- package/server/start.js +49 -0
- package/src/ConnectionManager.js +239 -225
- package/src/CryptoManager.js +147 -18
- package/src/DebugLogger.js +0 -7
- package/src/DistributedStorageManager.js +224 -205
- package/src/EnvironmentDetector.js +109 -2
- package/src/EventEmitter.js +79 -1
- package/src/EvictionManager.js +10 -9
- package/src/GossipManager.js +163 -11
- package/src/PeerConnection.js +333 -310
- package/src/PeerPigeonMesh.js +577 -135
- package/src/SignalingClient.js +14 -243
- package/src/SignalingHandler.js +31 -10
- package/src/StorageManager.js +0 -39
- package/src/WebDHT-Simple.js +389 -0
- package/src/WebDHT.js +363 -1165
- package/src/browser-entry.js +40 -0
- package/examples/browser/assets/images/favicon.png +0 -0
- package/examples/browser/assets/images/pigeon.png +0 -0
- package/examples/browser/crypto-test.html +0 -427
- package/examples/browser/ui-old.js +0 -1926
- package/examples/browser/ui.js +0 -3391
- package/websocket-server/README.md +0 -247
- package/websocket-server/server.js +0 -391
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
# Network Namespaces in PeerPigeon
|
|
2
|
+
|
|
3
|
+
PeerPigeon now supports **named network segregation** with automatic global mesh fallback, allowing you to create isolated peer-to-peer networks for different purposes while maintaining connectivity when needed.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
### Named Networks
|
|
8
|
+
- Create isolated mesh networks with custom names (e.g., "gaming", "work", "family")
|
|
9
|
+
- Peers in different networks cannot discover or connect to each other directly
|
|
10
|
+
- Messages, DHT data, and storage are fully isolated by network namespace
|
|
11
|
+
- Backward compatible with existing deployments using the "global" network
|
|
12
|
+
|
|
13
|
+
### Global Fallback
|
|
14
|
+
- When a named network has insufficient peers, automatically fall back to the global network
|
|
15
|
+
- Seamlessly return to the original network when peers become available
|
|
16
|
+
- Configurable fallback behavior (can be disabled if strict isolation is required)
|
|
17
|
+
|
|
18
|
+
### Data Isolation
|
|
19
|
+
- **Gossip Messages**: Network-scoped message propagation
|
|
20
|
+
- **WebDHT**: Namespaced key-value storage with network prefixes
|
|
21
|
+
- **Peer Discovery**: Network-filtered peer announcements
|
|
22
|
+
- **Signaling**: Network-tagged signaling messages
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
### Basic Setup
|
|
27
|
+
|
|
28
|
+
```javascript
|
|
29
|
+
// Create a mesh in a specific network
|
|
30
|
+
const mesh = new PeerPigeon.PeerPigeonMesh({
|
|
31
|
+
networkName: 'gaming', // Join the "gaming" network
|
|
32
|
+
allowGlobalFallback: true, // Allow fallback to global network
|
|
33
|
+
maxPeers: 3,
|
|
34
|
+
minPeers: 2
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
await mesh.init();
|
|
38
|
+
await mesh.connect('ws://localhost:3000');
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Network Management
|
|
42
|
+
|
|
43
|
+
```javascript
|
|
44
|
+
// Change network (only when disconnected)
|
|
45
|
+
mesh.setNetworkName('work');
|
|
46
|
+
|
|
47
|
+
// Check current network status
|
|
48
|
+
const status = mesh.getStatus();
|
|
49
|
+
console.log('Current network:', status.networkName);
|
|
50
|
+
console.log('Original network:', status.originalNetworkName);
|
|
51
|
+
console.log('In fallback mode:', status.isInFallbackMode);
|
|
52
|
+
|
|
53
|
+
// Configure fallback behavior
|
|
54
|
+
mesh.setAllowGlobalFallback(false); // Disable fallback for strict isolation
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Event Handling
|
|
58
|
+
|
|
59
|
+
```javascript
|
|
60
|
+
// Listen for network status changes
|
|
61
|
+
mesh.addEventListener('statusChanged', (event) => {
|
|
62
|
+
if (event.type === 'network') {
|
|
63
|
+
console.log('Network status:', event.message);
|
|
64
|
+
console.log('Current network:', event.networkName);
|
|
65
|
+
console.log('Fallback mode:', event.fallbackMode);
|
|
66
|
+
}
|
|
67
|
+
});
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Browser UI Support
|
|
71
|
+
|
|
72
|
+
The browser-2 example now includes a Network tab with:
|
|
73
|
+
|
|
74
|
+
- **Current Network Display**: Shows active network and fallback status
|
|
75
|
+
- **Network Switching**: Easy switching between named networks
|
|
76
|
+
- **Quick Networks**: Predefined network buttons (global, gaming, work, family, test)
|
|
77
|
+
- **Fallback Controls**: Toggle global fallback on/off
|
|
78
|
+
- **Network Health**: Real-time peer count and connection status
|
|
79
|
+
|
|
80
|
+
## API Reference
|
|
81
|
+
|
|
82
|
+
### Constructor Options
|
|
83
|
+
|
|
84
|
+
```javascript
|
|
85
|
+
const mesh = new PeerPigeon.PeerPigeonMesh({
|
|
86
|
+
networkName: 'global', // Network name (default: 'global')
|
|
87
|
+
allowGlobalFallback: true, // Allow global fallback (default: true)
|
|
88
|
+
// ... other existing options
|
|
89
|
+
});
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Methods
|
|
93
|
+
|
|
94
|
+
- `setNetworkName(name)` - Change network (only when disconnected)
|
|
95
|
+
- `getNetworkName()` - Get current network name
|
|
96
|
+
- `getOriginalNetworkName()` - Get original network name (before fallback)
|
|
97
|
+
- `isUsingGlobalFallback()` - Check if currently in fallback mode
|
|
98
|
+
- `setAllowGlobalFallback(allow)` - Enable/disable global fallback
|
|
99
|
+
|
|
100
|
+
### Status Properties
|
|
101
|
+
|
|
102
|
+
The `getStatus()` method now includes:
|
|
103
|
+
|
|
104
|
+
```javascript
|
|
105
|
+
{
|
|
106
|
+
networkName: 'gaming', // Current network
|
|
107
|
+
originalNetworkName: 'gaming', // Original network
|
|
108
|
+
isInFallbackMode: false, // Whether in fallback mode
|
|
109
|
+
allowGlobalFallback: true, // Fallback setting
|
|
110
|
+
// ... other existing status properties
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Use Cases
|
|
115
|
+
|
|
116
|
+
### Gaming Communities
|
|
117
|
+
```javascript
|
|
118
|
+
// Create isolated gaming networks
|
|
119
|
+
const gamingMesh = new PeerPigeon.PeerPigeonMesh({
|
|
120
|
+
networkName: 'minecraft-server-1',
|
|
121
|
+
allowGlobalFallback: false // Strict isolation
|
|
122
|
+
});
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Work Teams
|
|
126
|
+
```javascript
|
|
127
|
+
// Create private work networks with fallback
|
|
128
|
+
const workMesh = new PeerPigeon.PeerPigeonMesh({
|
|
129
|
+
networkName: 'team-alpha',
|
|
130
|
+
allowGlobalFallback: true // Fall back to global if team is offline
|
|
131
|
+
});
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Family Networks
|
|
135
|
+
```javascript
|
|
136
|
+
// Create family networks for private sharing
|
|
137
|
+
const familyMesh = new PeerPigeon.PeerPigeonMesh({
|
|
138
|
+
networkName: 'smith-family',
|
|
139
|
+
allowGlobalFallback: false // Keep family data private
|
|
140
|
+
});
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Migration Guide
|
|
144
|
+
|
|
145
|
+
### Existing Applications
|
|
146
|
+
Existing PeerPigeon applications continue to work without changes. They automatically use the "global" network namespace.
|
|
147
|
+
|
|
148
|
+
### Adding Network Support
|
|
149
|
+
1. Add `networkName` to constructor options
|
|
150
|
+
2. Optionally configure `allowGlobalFallback`
|
|
151
|
+
3. Handle network status events
|
|
152
|
+
4. Update UI to show current network (optional)
|
|
153
|
+
|
|
154
|
+
## Implementation Details
|
|
155
|
+
|
|
156
|
+
### Signaling Protocol
|
|
157
|
+
All signaling messages now include a `networkName` field:
|
|
158
|
+
|
|
159
|
+
```javascript
|
|
160
|
+
{
|
|
161
|
+
type: 'offer',
|
|
162
|
+
data: { /* offer data */ },
|
|
163
|
+
networkName: 'gaming',
|
|
164
|
+
// ... other fields
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### DHT Storage
|
|
169
|
+
Keys are automatically prefixed with the network name:
|
|
170
|
+
- User key: `"mykey"`
|
|
171
|
+
- Stored as: `"gaming:mykey"`
|
|
172
|
+
|
|
173
|
+
### Gossip Messages
|
|
174
|
+
Messages include network namespace and are filtered on receipt:
|
|
175
|
+
|
|
176
|
+
```javascript
|
|
177
|
+
{
|
|
178
|
+
id: 'msg-123',
|
|
179
|
+
type: 'gossip',
|
|
180
|
+
content: 'Hello network!',
|
|
181
|
+
networkName: 'gaming',
|
|
182
|
+
// ... other fields
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Fallback Logic
|
|
187
|
+
1. Monitor network health (peer count, discovery)
|
|
188
|
+
2. If original network becomes empty, activate global fallback
|
|
189
|
+
3. Periodically check if original network has peers
|
|
190
|
+
4. Automatically return to original network when viable
|
|
191
|
+
|
|
192
|
+
## Best Practices
|
|
193
|
+
|
|
194
|
+
1. **Choose meaningful network names** - Use descriptive names like "project-alpha" or "family-chat"
|
|
195
|
+
2. **Consider fallback carefully** - Enable for public/social networks, disable for private/sensitive networks
|
|
196
|
+
3. **Monitor network status** - Listen for status events to inform users about network changes
|
|
197
|
+
4. **Test isolation** - Verify that different networks cannot access each other's data
|
|
198
|
+
5. **Plan for empty networks** - Consider what happens when you're the first/only peer in a network
|
|
199
|
+
|
|
200
|
+
## Limitations
|
|
201
|
+
|
|
202
|
+
1. **Disconnect required for network change** - Must disconnect before switching networks
|
|
203
|
+
2. **No cross-network communication** - Networks are fully isolated (by design)
|
|
204
|
+
3. **Signaling server support** - Requires updated signaling server for optimal peer counting
|
|
205
|
+
4. **Fallback detection** - Current implementation uses simple heuristics for network health
|
|
206
|
+
|
|
207
|
+
## Future Enhancements
|
|
208
|
+
|
|
209
|
+
- **Signaling server integration** - Better peer counting and network health detection
|
|
210
|
+
- **Network bridging** - Optional cross-network message relay for authorized peers
|
|
211
|
+
- **Network discovery** - Discover available networks through the signaling server
|
|
212
|
+
- **Persistent preferences** - Remember preferred networks across sessions
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# PeerPigeon Documentation
|
|
2
|
+
|
|
3
|
+
Complete documentation for PeerPigeon - a WebRTC-based peer-to-peer mesh networking library.
|
|
4
|
+
|
|
5
|
+
## 📚 Core Documentation
|
|
6
|
+
|
|
7
|
+
### Getting Started
|
|
8
|
+
- **[Main README](../README.md)** - Quick start and overview
|
|
9
|
+
- **[API Documentation](API_DOCUMENTATION.md)** - Complete API reference
|
|
10
|
+
- **[CLI Guide](CLI_README.md)** - Command-line interface usage
|
|
11
|
+
|
|
12
|
+
### Advanced Features
|
|
13
|
+
- **[Network Namespaces](NETWORK_NAMESPACES.md)** - Create isolated peer networks
|
|
14
|
+
- **[Selective Streaming](SELECTIVE_STREAMING_GUIDE.md)** - Optimize media streaming bandwidth
|
|
15
|
+
- **[Hub System Overview](HUB_SYSTEM.md)** - Multi-server mesh architecture
|
|
16
|
+
- **[Hub Quick Reference](HUB_QUICK_REF.md)** - Quick start for hub deployment
|
|
17
|
+
- **[Hub Scripts](HUB_SCRIPTS.md)** - Automation scripts for hubs
|
|
18
|
+
- **[Bootstrap Hubs](BOOTSTRAP_HUBS.md)** - Hub discovery and federation
|
|
19
|
+
|
|
20
|
+
## 📖 Guides by Topic
|
|
21
|
+
|
|
22
|
+
### Messaging & Communication
|
|
23
|
+
- **Gossip Protocol** - Reliable broadcast messaging (see API_DOCUMENTATION.md)
|
|
24
|
+
- **Direct Messaging** - Peer-to-peer communication (see API_DOCUMENTATION.md)
|
|
25
|
+
- **Event System** - Standard Node.js EventEmitter API (see API_DOCUMENTATION.md)
|
|
26
|
+
|
|
27
|
+
### Storage & Data
|
|
28
|
+
- **WebDHT** - Low-level distributed hash table (see API_DOCUMENTATION.md)
|
|
29
|
+
- **DistributedStorageManager** - High-level encrypted storage (see API_DOCUMENTATION.md)
|
|
30
|
+
- **Storage Spaces** - Organized data namespaces (see API_DOCUMENTATION.md)
|
|
31
|
+
- **CRDT Support** - Conflict-free collaborative editing (see API_DOCUMENTATION.md)
|
|
32
|
+
|
|
33
|
+
### Media & Streaming
|
|
34
|
+
- **Media Manager** - Audio/video stream management (see API_DOCUMENTATION.md)
|
|
35
|
+
- **Selective Streaming** - Bandwidth optimization (see SELECTIVE_STREAMING_GUIDE.md)
|
|
36
|
+
- **Stream Controls** - Dynamic stream management (see API_DOCUMENTATION.md)
|
|
37
|
+
|
|
38
|
+
### Network Architecture
|
|
39
|
+
- **XOR Distance Routing** - Kademlia-inspired topology (see API_DOCUMENTATION.md)
|
|
40
|
+
- **Mesh Optimization** - Automatic peer selection (see API_DOCUMENTATION.md)
|
|
41
|
+
- **Eviction Strategy** - Smart peer replacement (see API_DOCUMENTATION.md)
|
|
42
|
+
- **Network Namespaces** - Isolated networks (see NETWORK_NAMESPACES.md)
|
|
43
|
+
|
|
44
|
+
### Server & Infrastructure
|
|
45
|
+
- **Signaling Server** - WebSocket server setup (see API_DOCUMENTATION.md)
|
|
46
|
+
- **Hub System** - Multi-server federation (see HUB_SYSTEM.md)
|
|
47
|
+
- **Bootstrap Hubs** - Hub discovery (see BOOTSTRAP_HUBS.md)
|
|
48
|
+
- **CLI Tools** - Command-line utilities (see CLI_README.md)
|
|
49
|
+
|
|
50
|
+
## 🔧 Reference Documents
|
|
51
|
+
|
|
52
|
+
### Migration & Maintenance
|
|
53
|
+
- **[Migration Complete](MIGRATION_COMPLETE.md)** - WebSocket server migration notes
|
|
54
|
+
- **[Test Cleanup](TEST_CLEANUP_COMPLETE.md)** - Test suite cleanup notes
|
|
55
|
+
|
|
56
|
+
## 💡 Examples
|
|
57
|
+
|
|
58
|
+
### Code Examples
|
|
59
|
+
- **[Browser Examples](../examples/browser/)** - Web application examples
|
|
60
|
+
- **[Node.js Examples](../examples/node/)** - Server-side examples
|
|
61
|
+
- **[NativeScript Examples](../examples/nativescript/)** - Mobile app examples
|
|
62
|
+
|
|
63
|
+
### Quick Examples
|
|
64
|
+
|
|
65
|
+
#### Basic Mesh Setup
|
|
66
|
+
```javascript
|
|
67
|
+
import { PeerPigeonMesh } from 'peerpigeon';
|
|
68
|
+
|
|
69
|
+
const mesh = new PeerPigeonMesh({ enableWebDHT: true });
|
|
70
|
+
await mesh.init();
|
|
71
|
+
await mesh.connect('ws://localhost:3000');
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
#### Message Broadcasting
|
|
75
|
+
```javascript
|
|
76
|
+
mesh.sendMessage('Hello, everyone!');
|
|
77
|
+
mesh.on('messageReceived', ({ from, content }) => {
|
|
78
|
+
console.log(`${from}: ${content}`);
|
|
79
|
+
});
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
#### Distributed Storage
|
|
83
|
+
```javascript
|
|
84
|
+
await mesh.storage.put('key', { data: 'value' });
|
|
85
|
+
const value = await mesh.storage.get('key');
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
#### Media Streaming
|
|
89
|
+
```javascript
|
|
90
|
+
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
|
|
91
|
+
mesh.media.addLocalStream(stream, 'camera');
|
|
92
|
+
mesh.media.streamToPeer('peer-id', 'camera', { video: true, audio: true });
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## 🔗 External Resources
|
|
96
|
+
|
|
97
|
+
- **GitHub Repository**: [github.com/draeder/peerpigeon](https://github.com/draeder/peerpigeon)
|
|
98
|
+
- **npm Package**: [npmjs.com/package/peerpigeon](https://www.npmjs.com/package/peerpigeon)
|
|
99
|
+
- **Issue Tracker**: [github.com/draeder/peerpigeon/issues](https://github.com/draeder/peerpigeon/issues)
|
|
100
|
+
|
|
101
|
+
## 📝 License
|
|
102
|
+
|
|
103
|
+
All documentation is provided under the MIT License.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
**Need help?** Check out the examples or open an issue on GitHub!
|