peerpigeon 0.1.0 → 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.
Files changed (72) hide show
  1. package/README.md +141 -1365
  2. package/cli.js +1382 -0
  3. package/dist/peerpigeon-browser.js +12290 -0
  4. package/dist/peerpigeon-browser.js.map +7 -0
  5. package/docs/API_DOCUMENTATION.md +1945 -0
  6. package/docs/BOOTSTRAP_HUBS.md +319 -0
  7. package/docs/CLI_README.md +371 -0
  8. package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
  9. package/docs/HUB_QUICK_REF.md +107 -0
  10. package/docs/HUB_SCRIPTS.md +331 -0
  11. package/docs/HUB_SYSTEM.md +552 -0
  12. package/docs/MIGRATION_COMPLETE.md +93 -0
  13. package/docs/NETWORK_NAMESPACES.md +212 -0
  14. package/docs/README.md +107 -0
  15. package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
  16. package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
  17. package/examples/bootstrap-hub-example.js +292 -0
  18. package/examples/browser/README.md +278 -0
  19. package/examples/browser/app.js +2426 -49
  20. package/examples/browser/index.html +482 -543
  21. package/examples/browser/minimal/README.md +55 -0
  22. package/examples/browser/minimal/index.html +75 -0
  23. package/examples/browser/minimal/minimal.js +234 -0
  24. package/examples/browser/styles.css +687 -1425
  25. package/examples/browser/test-bundle.html +35 -0
  26. package/examples/browser-2/index.html +30 -0
  27. package/examples/browser-2/package.json +21 -0
  28. package/examples/browser-2/src/App-simple.vue +21 -0
  29. package/examples/browser-2/src/App.vue +420 -0
  30. package/examples/browser-2/src/components/CryptoView.vue +1661 -0
  31. package/examples/browser-2/src/components/DHTView.vue +1281 -0
  32. package/examples/browser-2/src/components/DebugView.vue +1773 -0
  33. package/examples/browser-2/src/components/MediaView.vue +1048 -0
  34. package/examples/browser-2/src/components/MessagingView.vue +775 -0
  35. package/examples/browser-2/src/components/NetworkView.vue +930 -0
  36. package/examples/browser-2/src/components/StorageView.vue +1376 -0
  37. package/examples/browser-2/src/main.js +5 -0
  38. package/examples/browser-2/src/stores/peerpigeon.js +895 -0
  39. package/examples/browser-2/vite.config.js +6 -0
  40. package/examples/hub-example.js +186 -0
  41. package/examples/multi-hub-test.js +186 -0
  42. package/examples/node/README.md +2 -2
  43. package/examples/node/storage-test.js +141 -6
  44. package/examples/selective-streaming-demo.html +698 -0
  45. package/examples/standard-events-demo.js +126 -0
  46. package/package.json +33 -16
  47. package/server/index.js +1032 -98
  48. package/server/start.js +49 -0
  49. package/src/ConnectionManager.js +239 -225
  50. package/src/CryptoManager.js +147 -18
  51. package/src/DebugLogger.js +0 -7
  52. package/src/DistributedStorageManager.js +245 -205
  53. package/src/EnvironmentDetector.js +109 -2
  54. package/src/EventEmitter.js +79 -1
  55. package/src/EvictionManager.js +10 -9
  56. package/src/GossipManager.js +163 -11
  57. package/src/LexicalStorageInterface.js +332 -0
  58. package/src/PeerConnection.js +333 -310
  59. package/src/PeerPigeonMesh.js +577 -135
  60. package/src/SignalingClient.js +14 -243
  61. package/src/SignalingHandler.js +31 -10
  62. package/src/StorageManager.js +0 -39
  63. package/src/WebDHT-Simple.js +389 -0
  64. package/src/WebDHT.js +363 -1165
  65. package/src/browser-entry.js +40 -0
  66. package/examples/browser/assets/images/favicon.png +0 -0
  67. package/examples/browser/assets/images/pigeon.png +0 -0
  68. package/examples/browser/crypto-test.html +0 -427
  69. package/examples/browser/ui-old.js +0 -1926
  70. package/examples/browser/ui.js +0 -3010
  71. package/websocket-server/README.md +0 -247
  72. 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!