peerpigeon 1.0.2 → 1.0.4

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 CHANGED
@@ -8,6 +8,11 @@
8
8
 
9
9
  PeerPigeon is a production-ready library for building decentralized applications with true mesh networking, encrypted distributed storage, and selective media streaming. It handles peer discovery, connection management, and message routing automatically.
10
10
 
11
+ > **⚠️ IMPORTANT: Local Testing Requirement**
12
+ > When testing on `localhost`, WebRTC connections require **media permissions** (microphone/camera) due to browser security.
13
+ > **Solution**: Click the "Media" tab in the browser example and grant permissions, or see [docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md) for details.
14
+ > This is **NOT required** for production HTTPS deployments.
15
+
11
16
  ## ✨ Key Features
12
17
 
13
18
  - **🕸️ True Mesh Networking** - Gossip protocol + XOR distance routing (Kademlia-inspired)
@@ -49,16 +54,28 @@ mesh.on('messageReceived', ({ from, content }) => {
49
54
  ### Run Signaling Server
50
55
 
51
56
  ```bash
52
- # Option 1: Use npm script
53
- npm start
57
+ # Start both hub and HTTP server for testing
58
+ npm run dev
54
59
 
55
- # Option 2: Custom port
56
- PORT=8080 npm start
60
+ # Or run them separately:
61
+ npm run dev:hub # Just the signaling hub
62
+ npm run dev:http # Just the HTTP server
57
63
 
58
- # Option 3: Run as a hub (multi-server mesh)
59
- npm run hub
64
+ # Custom port
65
+ PORT=8080 npm run hub
60
66
  ```
61
67
 
68
+ ### Local Testing
69
+
70
+ For localhost testing, you need to grant media permissions:
71
+
72
+ 1. Open browser example: `http://localhost:8080/`
73
+ 2. Go to **Media** tab
74
+ 3. Click **Start Media** button
75
+ 4. Allow microphone/camera access
76
+
77
+ See [docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md) for full details.
78
+
62
79
  ## 📚 Examples
63
80
 
64
81
  ### Distributed Storage
@@ -6503,13 +6503,18 @@ ${b64.match(/.{1,64}/g).join("\n")}
6503
6503
  for (const [peerId, peerConnection] of this.peers) {
6504
6504
  if (peerConnection.connection?.signalingState === "have-local-offer") {
6505
6505
  const connectionAge = Date.now() - peerConnection.connectionStartTime;
6506
- if (connectionAge > 2e3) {
6506
+ if (connectionAge > 1e4) {
6507
6507
  stuckConnections.push(peerId);
6508
6508
  }
6509
6509
  }
6510
6510
  }
6511
6511
  if (stuckConnections.length > 0) {
6512
6512
  this.debug.log(`\u{1F6A8} STUCK MONITOR: Found ${stuckConnections.length} stuck connections - forcing recovery`);
6513
+ if (typeof window !== "undefined" && window.location?.hostname === "localhost") {
6514
+ console.warn("\u26A0\uFE0F LOCAL TESTING: WebRTC connections on localhost require media permissions!");
6515
+ console.warn(' Go to the Media tab and click "Start Media" to grant permissions.');
6516
+ console.warn(" See docs/LOCAL_TESTING.md for details.");
6517
+ }
6513
6518
  for (const peerId of stuckConnections) {
6514
6519
  this.forceConnectionRecovery(peerId).catch((error) => {
6515
6520
  this.debug.error(`Failed to recover stuck connection for ${peerId}:`, error);
@@ -6926,9 +6931,15 @@ ${b64.match(/.{1,64}/g).join("\n")}
6926
6931
  }
6927
6932
  const peerConnection = this.connectionManager.getPeer(fromPeerId);
6928
6933
  this.debug.log(`\u{1F504} ANSWER RECEIVE DEBUG: Found peer connection: ${!!peerConnection}`);
6934
+ const allPeerIds = Array.from(this.connectionManager.peers.keys());
6935
+ this.debug.log(`\u{1F504} ANSWER RECEIVE DEBUG: All current peers (${allPeerIds.length}): ${allPeerIds.map((p) => p.substring(0, 8)).join(", ")}`);
6929
6936
  if (peerConnection) {
6930
6937
  this.debug.log(`\u{1F504} ANSWER RECEIVE DEBUG: Peer connection state: ${peerConnection.connection?.signalingState}`);
6931
6938
  this.debug.log(`\u{1F504} ANSWER RECEIVE DEBUG: Is initiator: ${peerConnection.isInitiator}`);
6939
+ this.debug.log(`\u{1F504} ANSWER RECEIVE DEBUG: Connection age: ${Date.now() - peerConnection.connectionStartTime}ms`);
6940
+ } else {
6941
+ this.debug.error(`\u{1F504} ANSWER RECEIVE DEBUG: NO PEER CONNECTION - Was expecting peer ${fromPeerId.substring(0, 8)}...`);
6942
+ this.debug.error(`\u{1F504} ANSWER RECEIVE DEBUG: This means the peer connection was cleaned up or never created!`);
6932
6943
  }
6933
6944
  if (peerConnection) {
6934
6945
  try {
@@ -6946,7 +6957,8 @@ ${b64.match(/.{1,64}/g).join("\n")}
6946
6957
  }
6947
6958
  }
6948
6959
  } else {
6949
- this.debug.log("\u274C ANSWER RECEIVE DEBUG: No peer connection found for answer from", fromPeerId);
6960
+ this.debug.error("\u274C ANSWER RECEIVE DEBUG: No peer connection found for answer from", fromPeerId);
6961
+ this.debug.error("\u274C ANSWER RECEIVE DEBUG: Peer connection may have been cleaned up prematurely - check connection timeout/cleanup logic");
6950
6962
  }
6951
6963
  }
6952
6964
  handleConnectionRejected(data, fromPeerId) {
@@ -11120,6 +11132,27 @@ ${b64.match(/.{1,64}/g).join("\n")}
11120
11132
  } catch (error) {
11121
11133
  this.debug.warn("PigeonRTC initialization failed:", error.message);
11122
11134
  }
11135
+ if (environmentDetector.isBrowser) {
11136
+ try {
11137
+ const isLocalhost = window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1" || window.location.hostname === "";
11138
+ if (isLocalhost && navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
11139
+ this.debug.log("\u{1F3A4} Requesting media permissions for localhost WebRTC...");
11140
+ const stream = await navigator.mediaDevices.getUserMedia({
11141
+ audio: true,
11142
+ video: false
11143
+ }).catch((err) => {
11144
+ this.debug.warn("Media permission denied - connections may fail on localhost:", err.message);
11145
+ return null;
11146
+ });
11147
+ if (stream) {
11148
+ stream.getTracks().forEach((track) => track.stop());
11149
+ this.debug.log("\u2705 Media permissions granted - localhost connections will work");
11150
+ }
11151
+ }
11152
+ } catch (error) {
11153
+ this.debug.warn("Could not request media permissions:", error.message);
11154
+ }
11155
+ }
11123
11156
  if (this.providedPeerId) {
11124
11157
  if (_PeerPigeonMesh.validatePeerId(this.providedPeerId)) {
11125
11158
  this.peerId = this.providedPeerId;