@decentnetwork/peer 0.1.4 → 0.1.6

package/dist/peer.d.ts

@@ -13,6 +13,31 @@ export declare class Peer {
     joinNetwork(): Promise<BootstrapResult>;
     lookup(pubkey: string): Promise<LookupResult>;
     announceSelf(timeoutMs?: number): Promise<NetworkNode[]>;
+    /**
+     * Aggregate DHT health snapshot — surfaces the layers that have to
+     * work for UDP holepunch / route discovery to succeed.
+     *   bootstrapsConfigured  – nodes the SDK is allowed to talk to
+     *   knownNodesCount       – nodes discovered or persisted in our DHT view
+     *   lastSelfAnnounceMs    – last time we ran a self-announce sweep
+     *   selfAnnounceStoredOn  – how many nodes acknowledged STORING our
+     *                            announce last time. **If 0, our outbound
+     *                            DHT is broken** — peers can't find us,
+     *                            #discoverFriendRoutes returns nothing,
+     *                            UDP holepunch is impossible. Most common
+     *                            failure mode when sessions stay on
+     *                            tcp-relay forever.
+     *   udpLocalPort          – the OS-assigned UDP port (null = no socket)
+     *   tcpRelayConnected     – fallback relay path; if >0, sessions get
+     *                            through even when DHT is dead.
+     */
+    dhtHealth(): {
+        bootstrapsConfigured: number;
+        knownNodesCount: number;
+        lastSelfAnnounceMs: number;
+        selfAnnounceStoredOn: number;
+        udpLocalPort: number | null;
+        tcpRelayConnected: number;
+    };
     addKnownNodes(nodes: NetworkNode[]): void;
     knownNodes(): NetworkNode[];
     sendFriendRequest(pubkey: string, hello?: string): Promise<void>;

package/dist/peer.js

@@ -434,6 +434,33 @@ export class Peer {
     async announceSelf(timeoutMs = 15000) {
         return this.#runSelfAnnounce(true, Date.now() + timeoutMs);
     }
+    /**
+     * Aggregate DHT health snapshot — surfaces the layers that have to
+     * work for UDP holepunch / route discovery to succeed.
+     *   bootstrapsConfigured  – nodes the SDK is allowed to talk to
+     *   knownNodesCount       – nodes discovered or persisted in our DHT view
+     *   lastSelfAnnounceMs    – last time we ran a self-announce sweep
+     *   selfAnnounceStoredOn  – how many nodes acknowledged STORING our
+     *                            announce last time. **If 0, our outbound
+     *                            DHT is broken** — peers can't find us,
+     *                            #discoverFriendRoutes returns nothing,
+     *                            UDP holepunch is impossible. Most common
+     *                            failure mode when sessions stay on
+     *                            tcp-relay forever.
+     *   udpLocalPort          – the OS-assigned UDP port (null = no socket)
+     *   tcpRelayConnected     – fallback relay path; if >0, sessions get
+     *                            through even when DHT is dead.
+     */
+    dhtHealth() {
+        return {
+            bootstrapsConfigured: this.#opts.bootstrapNodes.length,
+            knownNodesCount: this.#knownNodes.length,
+            lastSelfAnnounceMs: this.#lastSelfAnnounceMs,
+            selfAnnounceStoredOn: this.#lastSelfAnnounceStoredCount,
+            udpLocalPort: this.#udp?.localPort() ?? null,
+            tcpRelayConnected: this.#tcpRelays?.connectedRelays(99).length ?? 0,
+        };
+    }
     addKnownNodes(nodes) {
         this.#knownNodes = dedupeNodes([...nodes, ...this.#knownNodes]);
     }
@@ -2788,10 +2815,73 @@ export class Peer {
         // residential ISPs where self-announce doesn't propagate).
         // Mirrors toxcore's send_dht_pk_packet which calls
         // tcp_copy_connected_relays to fill extras.
-        let extras = new Uint8Array(0);
+        // Also pack OUR OWN UDP endpoint(s) as extras (family 0x02 =
+        // UDP_FAMILY_IPV4). Without this, peers receiving our DHT-PK push
+        // learn our TCP relays but have NO IDEA where to send UDP cookie
+        // requests — so they never even try UDP holepunch and every
+        // session stays on tcp-relay (~500ms+ RTT) instead of the
+        // ~80ms UDP path. Observed in the wild: even same-LAN peers
+        // (snoopy and mac-dev on the same /24) stuck on tcp-relay
+        // forever because neither side ever announces a UDP endpoint
+        // to the other.
+        //
+        // For peers behind NAT, the LAN address we advertise is
+        // reachable by same-LAN peers and harmless for WAN peers
+        // (they fall through to tcp-relay as before). For peers with
+        // a public IP (e.g. a Vultr VPS), the LAN address IS the
+        // reachable one; same-format works. STUN-style reflexive
+        // discovery is the next layer but isn't required to fix the
+        // LAN case immediately.
+        const packed = [];
+        const ourUdpPort = this.#udp?.localPort();
+        if (ourUdpPort && ourUdpPort > 0) {
+            const ourDhtPk = this.#keyPair?.publicKey;
+            if (ourDhtPk && ourDhtPk.length === 32) {
+                // Enumerate non-loopback IPv4 addresses on this host.
+                // We use os.networkInterfaces() rather than guessing — this
+                // covers a multi-homed peer with several reachable IPs.
+                try {
+                    const ifaces = (await import("os")).networkInterfaces();
+                    const seenIps = new Set();
+                    for (const iface of Object.values(ifaces)) {
+                        if (!iface)
+                            continue;
+                        for (const addr of iface) {
+                            if (addr.family !== "IPv4")
+                                continue;
+                            if (addr.internal)
+                                continue;
+                            if (addr.address === "0.0.0.0")
+                                continue;
+                            if (seenIps.has(addr.address))
+                                continue;
+                            seenIps.add(addr.address);
+                            const parts = addr.address
+                                .split(".")
+                                .map((p) => Number.parseInt(p, 10));
+                            if (parts.length !== 4 || parts.some((n) => !(n >= 0 && n <= 255)))
+                                continue;
+                            const entry = new Uint8Array(1 + 4 + 2 + 32);
+                            entry[0] = 0x02; // UDP_FAMILY_IPV4
+                            entry[1] = parts[0];
+                            entry[2] = parts[1];
+                            entry[3] = parts[2];
+                            entry[4] = parts[3];
+                            entry[5] = (ourUdpPort >> 8) & 0xff;
+                            entry[6] = ourUdpPort & 0xff;
+                            entry.set(ourDhtPk, 7);
+                            packed.push(entry);
+                        }
+                    }
+                }
+                catch {
+                    // os import or interface enumeration failed; skip UDP extras
+                    // and let TCP relay carry the session as before.
+                }
+            }
+        }
         if (this.#tcpRelays) {
             const relays = this.#tcpRelays.connectedRelays(3); // MAX_SHARED_RELAYS
-            const packed = [];
             for (const r of relays) {
                 // Only IPv4 TCP entries supported here; matches what we parse.
                 // Format per packed-nodes spec: family(1) + ipv4(4) + port(2 BE) + pk(32)
@@ -2809,10 +2899,8 @@ export class Peer {
                 entry.set(r.serverPublicKey, 7);
                 packed.push(entry);
             }
-            if (packed.length > 0) {
-                extras = concatBytes(packed);
-            }
         }
+        const extras = packed.length > 0 ? concatBytes(packed) : new Uint8Array(0);
         const innerPayload = concatBytes([
             noReplayBytes,
             this.#keyPair.publicKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",