peerpigeon 1.0.7 → 1.0.9

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.
@@ -1,140 +0,0 @@
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