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.
- package/dist/peerpigeon-browser.js +361 -30
- package/dist/peerpigeon-browser.js.map +3 -3
- package/docs/BROADCAST_STREAMING.md +388 -0
- package/docs/PEER_DISCOVERY_FIXES.md +140 -0
- package/examples/broadcast-stream-demo.html +539 -0
- package/package.json +1 -1
- package/server/index.js +238 -38
- package/src/ConnectionManager.js +38 -8
- package/src/GossipManager.js +22 -0
- package/src/PeerConnection.js +12 -7
- package/src/PeerDiscovery.js +33 -18
- package/src/PeerPigeonMesh.js +333 -0
- package/src/SignalingHandler.js +18 -5
|
@@ -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
|