peerpigeon 1.0.6 → 1.0.8

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.
@@ -0,0 +1,388 @@
1
+ # Broadcast Streaming API
2
+
3
+ The PeerPigeon Broadcast Streaming API allows you to stream data to all peers in the mesh network using the **gossip protocol**. This is useful for scenarios like:
4
+
5
+ - Broadcasting files to all participants across the entire mesh (multi-hop)
6
+ - Live streaming content to viewers anywhere in the network
7
+ - Distributing updates or media to all peers, even those not directly connected
8
+
9
+ ## Features
10
+
11
+ - **Gossip-based propagation**: Streams reach all peers in the mesh, even those multiple hops away
12
+ - **Multi-hop delivery**: Messages automatically propagate through the network (TTL-based)
13
+ - **Efficient streaming**: Uses WritableStream API for memory-efficient chunked transfers
14
+ - **Automatic deduplication**: Gossip protocol prevents duplicate chunk delivery
15
+ - **Error resilience**: Network continues functioning even if individual peers fail
16
+ - **Progress tracking**: Emits events for monitoring broadcast progress and completion
17
+ - **Flexible input**: Supports Files, Blobs, and custom ReadableStreams
18
+
19
+ ## How It Works
20
+
21
+ Unlike point-to-point streaming, broadcast streaming uses the gossip protocol to propagate stream chunks throughout the entire mesh network:
22
+
23
+ 1. **Chunk broadcasting**: Each chunk is sent as a gossip message with TTL (time-to-live)
24
+ 2. **Multi-hop propagation**: Peers relay chunks to their neighbors, reaching the entire network
25
+ 3. **Ordered reassembly**: Receiving peers buffer and reorder chunks automatically
26
+ 4. **Deduplication**: Gossip protocol ensures peers don't process duplicate chunks
27
+
28
+ **Network Reach**: Gossip broadcast reaches ALL peers in the mesh, not just directly connected ones.
29
+
30
+ ## Basic Usage
31
+
32
+ ### Broadcasting a File
33
+
34
+ ```javascript
35
+ import { PeerPigeonMesh } from 'peerpigeon';
36
+
37
+ const mesh = new PeerPigeonMesh();
38
+ await mesh.init();
39
+ await mesh.connect('ws://signaling-server:3000');
40
+
41
+ // Broadcast a file to all connected peers
42
+ const fileInput = document.getElementById('fileInput');
43
+ const file = fileInput.files[0];
44
+
45
+ await mesh.broadcastFile(file);
46
+ ```
47
+
48
+ ### Broadcasting a Blob
49
+
50
+ ```javascript
51
+ const text = 'Hello all peers!';
52
+ const blob = new Blob([text], { type: 'text/plain' });
53
+
54
+ await mesh.broadcastBlob(blob, {
55
+ filename: 'message.txt'
56
+ });
57
+ ```
58
+
59
+ ### Broadcasting a Custom Stream
60
+
61
+ ```javascript
62
+ // Create a readable stream from any source
63
+ const readableStream = new ReadableStream({
64
+ start(controller) {
65
+ // Push chunks to the stream
66
+ controller.enqueue(new Uint8Array([1, 2, 3]));
67
+ controller.close();
68
+ }
69
+ });
70
+
71
+ // Broadcast with metadata
72
+ await mesh.broadcastStream(readableStream, {
73
+ filename: 'data.bin',
74
+ mimeType: 'application/octet-stream',
75
+ totalSize: 1024
76
+ });
77
+ ```
78
+
79
+ ## Advanced Usage
80
+
81
+ ### Creating a Broadcast Stream Manually
82
+
83
+ For more control, you can create a writable broadcast stream and pipe data to it:
84
+
85
+ ```javascript
86
+ // Create a writable stream that broadcasts to all peers
87
+ const broadcastStream = mesh.createBroadcastStream({
88
+ filename: 'large-file.dat',
89
+ mimeType: 'application/octet-stream',
90
+ totalSize: 1024 * 1024 * 100 // 100MB
91
+ });
92
+
93
+ // Get a writer
94
+ const writer = broadcastStream.getWriter();
95
+
96
+ // Write chunks
97
+ await writer.write(chunk1);
98
+ await writer.write(chunk2);
99
+ await writer.write(chunk3);
100
+
101
+ // Close when done
102
+ await writer.close();
103
+ ```
104
+
105
+ ### Piping from a ReadableStream
106
+
107
+ ```javascript
108
+ const response = await fetch('https://example.com/large-file.zip');
109
+ const readableStream = response.body;
110
+
111
+ const broadcastStream = mesh.createBroadcastStream({
112
+ filename: 'download.zip',
113
+ mimeType: 'application/zip'
114
+ });
115
+
116
+ // Pipe directly from fetch to all peers
117
+ await readableStream.pipeTo(broadcastStream);
118
+ ```
119
+
120
+ ## Event Handling
121
+
122
+ ### Monitoring Broadcast Completion
123
+
124
+ ```javascript
125
+ mesh.addEventListener('broadcastStreamComplete', (event) => {
126
+ console.log(`Broadcast complete!`);
127
+ console.log(`Total bytes sent: ${event.totalBytes}`);
128
+ console.log(`Successful peers: ${event.successCount}/${event.totalPeers}`);
129
+ console.log(`Metadata:`, event.metadata);
130
+ });
131
+ ```
132
+
133
+ ### Handling Broadcast Failures
134
+
135
+ ```javascript
136
+ mesh.addEventListener('broadcastStreamAborted', (event) => {
137
+ console.error(`Broadcast aborted: ${event.reason}`);
138
+ console.log(`Stream ID: ${event.streamId}`);
139
+ });
140
+ ```
141
+
142
+ ### Receiving Broadcasts
143
+
144
+ Peers receiving broadcast streams get the standard `streamReceived` event:
145
+
146
+ ```javascript
147
+ mesh.addEventListener('streamReceived', async (event) => {
148
+ console.log(`Receiving stream from ${event.peerId}`);
149
+ console.log(`Metadata:`, event.metadata);
150
+
151
+ // Read the stream
152
+ const reader = event.stream.getReader();
153
+ const chunks = [];
154
+
155
+ while (true) {
156
+ const { done, value } = await reader.read();
157
+ if (done) break;
158
+ chunks.push(value);
159
+ }
160
+
161
+ // Process received data
162
+ const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
163
+ console.log(`Received ${totalLength} bytes`);
164
+
165
+ // Create a blob if needed
166
+ if (event.metadata.filename) {
167
+ const blob = new Blob(chunks, { type: event.metadata.mimeType });
168
+ const url = URL.createObjectURL(blob);
169
+ // Download or display the file
170
+ }
171
+ });
172
+ ```
173
+
174
+ ## API Reference
175
+
176
+ ### Methods
177
+
178
+ #### `createBroadcastStream(options)`
179
+
180
+ Creates a WritableStream that broadcasts data to all connected peers.
181
+
182
+ **Parameters:**
183
+ - `options` (object, optional):
184
+ - `streamId` (string): Custom stream ID (auto-generated if not provided)
185
+ - `type` (string): Stream type (default: 'broadcast')
186
+ - `filename` (string): Filename for the stream
187
+ - `mimeType` (string): MIME type of the content
188
+ - `totalSize` (number): Total size in bytes
189
+ - `chunkSize` (number): Chunk size for transmission
190
+
191
+ **Returns:** `WritableStream`
192
+
193
+ **Throws:** Error if no peers are connected
194
+
195
+ ---
196
+
197
+ #### `broadcastStream(readableStream, options)`
198
+
199
+ Broadcasts a ReadableStream to all connected peers.
200
+
201
+ **Parameters:**
202
+ - `readableStream` (ReadableStream): The stream to broadcast
203
+ - `options` (object, optional): Same as `createBroadcastStream`
204
+
205
+ **Returns:** `Promise<void>`
206
+
207
+ ---
208
+
209
+ #### `broadcastFile(file)`
210
+
211
+ Broadcasts a File to all connected peers.
212
+
213
+ **Parameters:**
214
+ - `file` (File): The file to broadcast
215
+
216
+ **Returns:** `Promise<void>`
217
+
218
+ ---
219
+
220
+ #### `broadcastBlob(blob, options)`
221
+
222
+ Broadcasts a Blob to all connected peers.
223
+
224
+ **Parameters:**
225
+ - `blob` (Blob): The blob to broadcast
226
+ - `options` (object, optional): Additional options (filename, etc.)
227
+
228
+ **Returns:** `Promise<void>`
229
+
230
+ ---
231
+
232
+ ### Events
233
+
234
+ #### `broadcastStreamComplete`
235
+
236
+ Emitted when a broadcast stream completes successfully.
237
+
238
+ **Event Data:**
239
+ ```javascript
240
+ {
241
+ streamId: string,
242
+ totalBytes: number,
243
+ totalChunks: number,
244
+ metadata: object
245
+ }
246
+ ```
247
+
248
+ ---
249
+
250
+ #### `broadcastStreamAborted`
251
+
252
+ Emitted when a broadcast stream is aborted.
253
+
254
+ **Event Data:**
255
+ ```javascript
256
+ {
257
+ streamId: string,
258
+ reason: string,
259
+ metadata: object
260
+ }
261
+ ```
262
+
263
+ ---
264
+
265
+ #### `streamReceived`
266
+
267
+ Emitted on receiving peers when a gossip stream starts. This event fires on ALL peers in the mesh as chunks propagate via gossip.
268
+
269
+ **Event Data:**
270
+ ```javascript
271
+ {
272
+ peerId: string,
273
+ streamId: string,
274
+ stream: ReadableStream,
275
+ metadata: object
276
+ }
277
+ ```
278
+
279
+ ---
280
+
281
+ #### `streamCompleted`
282
+
283
+ Emitted when a gossip stream is fully received.
284
+
285
+ **Event Data:**
286
+ ```javascript
287
+ {
288
+ peerId: string,
289
+ streamId: string,
290
+ totalChunks: number,
291
+ totalBytes: number
292
+ }
293
+ ```
294
+
295
+ ## Error Handling
296
+
297
+ The broadcast streaming API uses gossip protocol for resilience:
298
+
299
+ - Chunks propagate through the network with TTL (time-to-live)
300
+ - If some peers are unreachable, chunks route around them
301
+ - Network continues functioning even if individual peers fail
302
+ - Gossip deduplication prevents processing the same chunk multiple times
303
+
304
+ ```javascript
305
+ try {
306
+ await mesh.broadcastFile(file);
307
+ } catch (error) {
308
+ if (error.message.includes('All peer connections failed')) {
309
+ console.error('Broadcast failed: All peers disconnected');
310
+ } else {
311
+ console.error('Broadcast error:', error);
312
+ }
313
+ }
314
+ ```
315
+
316
+ ## Performance Considerations
317
+
318
+ ### Chunk Size
319
+
320
+ The default chunk size is optimized for most use cases, but you can customize it:
321
+
322
+ ```javascript
323
+ mesh.createBroadcastStream({
324
+ filename: 'large-file.dat',
325
+ chunkSize: 32768 // 32KB chunks
326
+ });
327
+ ```
328
+
329
+ - Smaller chunks (4-16KB): Better for real-time streaming, more overhead
330
+ - Larger chunks (32-64KB): Better throughput, higher latency
331
+
332
+ ### Memory Usage
333
+
334
+ Broadcast streams use memory efficiently by:
335
+ - Processing data in chunks
336
+ - Using backpressure to avoid overwhelming peers
337
+ - Cleaning up resources automatically
338
+
339
+ For very large files, the streaming API uses minimal memory as it doesn't load the entire file into memory.
340
+
341
+ ### Network Bandwidth
342
+
343
+ Broadcasting consumes bandwidth proportional to: `file_size × number_of_peers`
344
+
345
+ For example, broadcasting a 10MB file to 5 peers consumes approximately 50MB of upload bandwidth.
346
+
347
+ ## Examples
348
+
349
+ See the complete working example in `/examples/broadcast-stream-demo.html`.
350
+
351
+ ## Comparison with Other Methods
352
+
353
+ | Method | Use Case | Network Reach | Behavior |
354
+ |--------|----------|---------------|----------|
355
+ | `broadcastStream()` | Large files/media | **Entire mesh (multi-hop)** | Gossip-based chunked streaming |
356
+ | `broadcastBinaryData()` | Small binary messages | **Direct peers only** | Single-shot binary broadcast |
357
+ | `sendMessage()` | Text messages | **Entire mesh (multi-hop)** | Gossip protocol with TTL |
358
+ | `createStreamToPeer()` | 1:1 file transfer | **Single peer** | Direct P2P streaming |
359
+
360
+ ### Gossip vs Direct Streaming
361
+
362
+ **Broadcast Streaming (Gossip)**:
363
+ - ✅ Reaches **all peers** in the mesh (multi-hop)
364
+ - ✅ Survives **network partitions** and peer churn
365
+ - ✅ **Automatic deduplication** of chunks
366
+ - ✅ Works through **intermediate peers** as relays
367
+ - ⚠️ Higher **latency** due to multi-hop propagation
368
+ - ⚠️ More **bandwidth usage** (chunks propagate through multiple paths)
369
+
370
+ **Direct P2P Streaming** (createStreamToPeer):
371
+ - ✅ **Lower latency** - direct connection
372
+ - ✅ **Efficient bandwidth** usage
373
+ - ✅ Best for **1:1 file transfers**
374
+ - ❌ Only reaches **directly connected peer**
375
+ - ❌ Fails if **connection drops**
376
+
377
+ ## Browser Compatibility
378
+
379
+ The broadcast streaming API requires:
380
+ - WebRTC support
381
+ - Streams API (ReadableStream, WritableStream)
382
+ - Modern browsers: Chrome 89+, Firefox 88+, Safari 14.1+, Edge 89+
383
+
384
+ ## Next Steps
385
+
386
+ - See [STREAMING_API.md](./STREAMING_API.md) for peer-to-peer streaming
387
+ - See [BINARY_MESSAGES.md](./BINARY_MESSAGES.md) for binary messaging
388
+ - Check out the demo: `examples/broadcast-stream-demo.html`
@@ -0,0 +1,140 @@
1
+ # Peer Discovery and Connection Fixes
2
+
3
+ **Date**: November 21, 2025
4
+ **Issue**: Peers sometimes do not discover each other or connect using pigeonhub
5
+
6
+ ## Problems Identified
7
+
8
+ ### 1. **Duplicate Peer Announcement Handling** (`SignalingHandler.js`)
9
+ **Problem**: The `handlePeerAnnouncement` method was completely skipping re-announcements of already known peers, even if those peers had disconnected or the connection attempt had failed.
10
+
11
+ **Impact**: If a peer announcement was missed or a connection failed, peers would never retry connecting to each other.
12
+
13
+ **Fix**: Modified to:
14
+ - Check if peer is already actively connected before skipping
15
+ - Allow re-discovery to refresh timestamps
16
+ - Clean up stale connection attempts after 5 seconds
17
+ - Log the reason for accepting or rejecting announcements
18
+
19
+ ### 2. **Connection Attempt Cleanup** (`PeerDiscovery.js`)
20
+ **Problem**: The `addDiscoveredPeer` method was returning early for known peers without evaluating whether a connection should be attempted again.
21
+
22
+ **Impact**: Once a peer was discovered, even if connection attempts failed, no retry would occur unless the peer was completely removed from the discovered list.
23
+
24
+ **Fix**: Modified to:
25
+ - Always update timestamps for known peers
26
+ - Clean up stale connection attempts (>5 seconds old)
27
+ - Re-evaluate connection initiation even for known peers
28
+ - Add detailed logging for troubleshooting
29
+
30
+ ### 3. **Strict Connection Attempt Blocking** (`PeerDiscovery.js`)
31
+ **Problem**: The `shouldInitiateConnection` method was checking `connectionAttempts` at the start and returning false immediately if an attempt was in progress, which could block retries indefinitely.
32
+
33
+ **Impact**: If a connection attempt got stuck or timed out, the peer would never retry because the attempt tracking wasn't being cleared.
34
+
35
+ **Fix**: Removed the early return for `connectionAttempts.has(targetPeerId)` to allow the isolation override logic to work properly.
36
+
37
+ ### 4. **Connection Retry Logic** (`ConnectionManager.js`)
38
+ **Problem**: The `connectToPeer` method had overly strict duplicate connection prevention that didn't account for stuck or timed-out connections.
39
+
40
+ **Impact**: Connections that got stuck in "connecting" state would prevent retries, leaving peers permanently unable to connect.
41
+
42
+ **Fix**: Modified to:
43
+ - Check connection age before blocking retries
44
+ - Allow retries for stuck connections (>10 seconds)
45
+ - Allow retries for old connection attempts (>10 seconds)
46
+ - Increase max attempts for isolated peers (double the normal limit)
47
+ - Don't permanently remove peers after max attempts - just reset counters
48
+
49
+ ### 5. **Hub Peer Forwarding** (`server/index.js`)
50
+ **Problem**: When hubs received peer-discovered messages from bootstrap hubs or other hubs, they weren't relaying these announcements to OTHER connected hubs, only to local client peers.
51
+
52
+ **Impact**: In a multi-hub network, peers connected to different hubs wouldn't discover each other because the peer announcements weren't being propagated across the hub mesh.
53
+
54
+ **Fix**: Modified `handlePeerDiscovered` to:
55
+ - Relay peer-discovered messages to other connected hubs
56
+ - Forward to both bootstrap connections and incoming hub connections
57
+ - Avoid relaying back to the sender hub
58
+ - Add detailed logging for hub relay operations
59
+
60
+ ### 6. **Bootstrap Hub Message Handling** (`server/index.js`)
61
+ **Problem**: The `handleBootstrapMessage` was using `getActivePeers()` which could include hub peers when forwarding peer-discovered messages.
62
+
63
+ **Impact**: Hub peers would receive peer-discovered messages meant for client peers, causing unnecessary network traffic and potential confusion.
64
+
65
+ **Fix**: Modified to:
66
+ - Use `networkPeers.get(discoveredNetwork)` directly
67
+ - Filter out hub peers explicitly
68
+ - Only forward to client peers
69
+ - Add proper connection state checking
70
+
71
+ ## Testing
72
+
73
+ Created `test/peer-discovery-test.js` to verify the fixes:
74
+ - Tests multiple peers connecting to a hub
75
+ - Verifies peer discovery announcements
76
+ - Confirms connection establishment
77
+ - Uses staggered connection timing to test various scenarios
78
+ - Provides detailed color-coded output for debugging
79
+
80
+ ### Running the Test
81
+
82
+ ```bash
83
+ node test/peer-discovery-test.js
84
+ ```
85
+
86
+ ## Expected Behavior After Fixes
87
+
88
+ 1. **Initial Discovery**: When a peer announces itself to the hub, all other peers in the same network should receive a `peer-discovered` message within milliseconds.
89
+
90
+ 2. **Connection Initiation**: The peer with the lexicographically larger peer ID should initiate the WebRTC connection automatically.
91
+
92
+ 3. **Retry Mechanism**: If a connection fails or gets stuck, the system will:
93
+ - Clean up stale connection attempts after 5 seconds
94
+ - Allow re-announcements to trigger new connection attempts
95
+ - Retry up to 3 times (6 times for isolated peers)
96
+ - Use shorter retry delays (200ms for isolated peers, 500ms normally)
97
+
98
+ 4. **Multi-Hub Networks**: In networks with multiple hubs:
99
+ - Peer announcements propagate to all hubs
100
+ - Peers connected to different hubs can discover each other
101
+ - Hub-to-hub relay ensures full network visibility
102
+
103
+ 5. **Connection State Management**: The system now properly handles:
104
+ - Stuck connections (>10 seconds in "connecting" state)
105
+ - Failed connection attempts
106
+ - Duplicate connection prevention
107
+ - Re-announcements of existing peers
108
+
109
+ ## Files Modified
110
+
111
+ 1. `src/SignalingHandler.js` - Improved peer announcement handling
112
+ 2. `src/PeerDiscovery.js` - Better connection attempt tracking and cleanup
113
+ 3. `src/ConnectionManager.js` - Enhanced retry logic and stuck connection handling
114
+ 4. `server/index.js` - Fixed hub peer forwarding and relay logic
115
+
116
+ ## Migration Notes
117
+
118
+ These fixes are **backward compatible** and don't require any API changes. Existing applications using PeerPigeon will automatically benefit from the improvements.
119
+
120
+ ## Debugging
121
+
122
+ To enable debug logging for troubleshooting connection issues:
123
+
124
+ ```javascript
125
+ import { DebugLogger } from 'peerpigeon';
126
+
127
+ // Enable specific modules
128
+ DebugLogger.enable('PeerDiscovery');
129
+ DebugLogger.enable('ConnectionManager');
130
+ DebugLogger.enable('SignalingHandler');
131
+
132
+ // Or enable all
133
+ DebugLogger.enableAll();
134
+ ```
135
+
136
+ ## Related Documentation
137
+
138
+ - [HUB_SYSTEM.md](./HUB_SYSTEM.md) - Hub architecture and multi-hub networking
139
+ - [NETWORK_NAMESPACES.md](./NETWORK_NAMESPACES.md) - Network isolation
140
+ - [LOCAL_TESTING.md](./LOCAL_TESTING.md) - Testing peer connections locally