@decentnetwork/peer 0.1.122 → 0.1.124

package/dist/peer.d.ts

@@ -307,4 +307,27 @@ export declare class Peer {
         name: string;
         description: string;
     };
+    /**
+     * Tell a friend our public UDP endpoint over the (already-working,
+     * possibly tcp-relay) messenger channel, so they can hole-punch to us.
+     * This is the out-of-band substitute for the broken DHT/onion-announce
+     * endpoint discovery. Both peers do this symmetrically; on receipt each
+     * feeds the other's endpoint into endpointCandidates and punches.
+     */
+    /**
+     * Lazily allocate our node-level TURN relay on its own dedicated UDP
+     * socket. Returns our public relay address (on the TURN server) which we
+     * advertise to peers so they can reach us via the relay even when direct
+     * UDP can't be punched. Relayed data is injected into #onDatagram tagged
+     * `viaRelay` so it updates the relay freshness, not the direct endpoint.
+     */
+    /**
+     * Test-only seam for scripts/turn-socket-leak-selftest.mjs: drive one TURN
+     * allocation attempt directly instead of waiting out the 120s-per-friend
+     * relay keepalive that reaches this path in production. Not public API.
+     */
+    __testForceTurnAllocation(): Promise<{
+        host: string;
+        port: number;
+    } | undefined>;
 }

package/dist/peer.js

@@ -23,14 +23,35 @@ import { UdpTransport } from "./transport/udp.js";
 import { bytesToHex, concatBytes, randomBytes } from "./utils/bytes.js";
 import { buildBindingRequest, decodeStun, decodeXorMappedAddress, findAttr, STUN_ATTR_XOR_MAPPED_ADDRESS, STUN_BINDING_SUCCESS } from "./stun.js";
 import { TurnClient } from "./turn.js";
-import { createSocket as createDgramSocket } from "dgram";
+import { createBoundUdp4Socket, closeDgramSocket } from "./transport/dgram-lifecycle.js";
 // Dedicated TURN relay servers — fixed public relays used as a stable
 // fallback path when direct UDP hole-punch fails or flaps (symmetric NAT,
 // NAT remaps, lossy direct path). A relay endpoint never NAT-flaps, so the
 // path stays put even when the peers' NATs churn. Static long-term creds.
-const TURN_RELAY_SERVERS = [
-    { host: "tokyo.fi.chat", port: 3478, username: "allcom", password: "allcompass" }
-];
+// DECENT_TURN_SERVERS overrides the list ("host:port,host:port"). Used by the
+// socket-leak selftest to point allocation at an unroutable address so every
+// attempt fails deterministically; also lets ops repoint TURN without a build.
+const TURN_RELAY_SERVERS = (() => {
+    const raw = process.env.DECENT_TURN_SERVERS?.trim();
+    if (!raw) {
+        return [{ host: "tokyo.fi.chat", port: 3478, username: "allcom", password: "allcompass" }];
+    }
+    return raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => {
+        const idx = entry.lastIndexOf(":");
+        const host = idx === -1 ? entry : entry.slice(0, idx);
+        const port = idx === -1 ? 3478 : Number.parseInt(entry.slice(idx + 1), 10);
+        return {
+            host,
+            port: Number.isFinite(port) && port > 0 ? port : 3478,
+            username: "allcom",
+            password: "allcompass"
+        };
+    });
+})();
 const ANNOUNCE_WAIT_TIMEOUT_MS = readEnvInt("DECENT_ANNOUNCE_WAIT_TIMEOUT_MS", 4000);
 // 24 (was 12): with distance-ordered walking a lookup needs headroom to
 // recurse past a first wave of dead close-in-XOR-space entries.
@@ -88,6 +109,15 @@ const FRIEND_PING_INTERVAL_MS = readEnvInt("DECENT_FRIEND_PING_INTERVAL_MS", 400
 // middle of toxcore's reactive range — fast enough to keep responsiveness,
 // slow enough not to burn CPU on idle peers. Tunable via env.
 const FRIEND_CONNECTION_LOOP_MS = readEnvInt("DECENT_FRIEND_CONNECTION_LOOP_MS", 250);
+/** Minimum gap between onion DHT-PK announces to the SAME friend.
+ *
+ *  One announce fans out to several nodes and costs three X25519 scalar mults
+ *  per node (one per onion layer), so this budget is the difference between an
+ *  idle node and a busy core. Two call sites in #doFriendConnections need it —
+ *  they previously each spelled the interval out, drifted apart (25s vs the
+ *  enclosing 3s re-punch cadence), and the cheap one silently set the pace for
+ *  the expensive one. Shared here so they cannot diverge again. */
+const DHT_PK_ANNOUNCE_COOLDOWN_MS = readEnvInt("DECENT_DHT_PK_ANNOUNCE_COOLDOWN_MS", 25_000);
 const FRIEND_TIMEOUT_MS = readEnvInt("DECENT_FRIEND_TIMEOUT_MS", 32000);
 // A session whose keys we've PROVEN (decrypted ≥1 real packet from the peer) is
 // NOT torn down at FRIEND_TIMEOUT_MS. A transient all-transport blackout — e.g.
@@ -358,6 +388,14 @@ export class Peer {
     // session entry exists yet so the connection loop does not flood DHT-PK
     // requests when route discovery keeps failing.
     #dhtPkSendCooldown = new Map();
+    /** Last ONION-routed endpoint lookup per friend. Separate from
+     *  #dhtPkSendCooldown: they are two different expensive operations for the
+     *  same friend, and sharing one timestamp would let whichever ran first
+     *  suppress the other for a full budget. */
+    #onionLookupCooldown = new Map();
+    /** Consecutive failed endpoint lookups per (friend,target) — drives how wide
+     *  the next fan-out goes. Cleared on success. */
+    #onionLookupMisses = new Map();
     // Per-friend cooldown for re-asserting the TCP-relay route toward an
     // unconnected friend (the "accepted friend that never connects" wedge —
     // requestRoute only fired once at startup and was never retried).
@@ -736,13 +774,8 @@ export class Peer {
         this.#udp.off("datagram", this.#onDatagram);
         await this.#udp.stop();
         // Release the TURN allocation + its dedicated socket.
-        try {
-            this.#turnClient?.close();
-            this.#turnSocket?.close();
-        }
-        catch {
-            // best-effort
-        }
+        this.#turnClient?.close();
+        await closeDgramSocket(this.#turnSocket);
         this.#turnClient = undefined;
         this.#turnSocket = undefined;
         this.#ourRelayAddr = undefined;
@@ -3044,12 +3077,53 @@ export class Peer {
             return false;
         }
         const targetId = carrierIdFromPublicKey(searchPublicKey);
+        // Per-(friend, target) budget, enforced HERE rather than at the call sites.
+        //
+        // One run of this fans out to up to 24 nodes and each onion request costs
+        // three X25519 scalar mults (one per layer) — up to ~72 per call, tens of
+        // ms of pure CPU. There are four call sites and gating them one at a time
+        // just moves the cost to whichever one was missed: after gating only the
+        // re-punch path, this function was STILL the top crypto entry on
+        // smtp.gfax.cn. A choke point inside the function is the only version that
+        // cannot be bypassed by a call site added later.
+        //
+        // Keyed by target, not just friend, so the dhtPk lookup and the
+        // onion-routed fallback for the same friend keep independent budgets —
+        // throttling repeats of the SAME search, never the first try of a
+        // different one.
+        const budgetKey = `${friendId}:${targetId}`;
+        const lastLookup = this.#onionLookupCooldown.get(budgetKey) ?? 0;
+        const sinceLast = Date.now() - lastLookup;
+        if (sinceLast < DHT_PK_ANNOUNCE_COOLDOWN_MS) {
+            this.#debugLog(`endpoint lookup for ${friendId} skipped: ${Math.round(sinceLast / 1000)}s since last ` +
+                `(budget ${DHT_PK_ANNOUNCE_COOLDOWN_MS / 1000}s)`);
+            return false;
+        }
+        this.#onionLookupCooldown.set(budgetKey, Date.now());
+        // Adaptive fan-out. Each node in this queue costs TWO announce round trips
+        // (ping id, then the real query) and every onion request is three X25519
+        // scalar mults — so a full 24-node sweep is ~144 scalar mults, and the loop
+        // only exits early on SUCCESS. In steady state the lookups that repeat are
+        // exactly the ones that keep failing, so the old fixed width paid the
+        // maximum price precisely when it was least likely to pay off: measured
+        // ~10-23 announce sends/sec on smtp.gfax.cn, ~28% of a core.
+        //
+        // First attempt keeps the full width — that is the one most likely to find
+        // the peer, and discovery reliability is not what we are trading away.
+        // Repeats narrow to a probe, and every 8th attempt goes wide again so a
+        // peer that only just came back is still found without waiting for a
+        // restart. Widening beats a permanently narrow sweep: the failure we must
+        // not introduce is "never discovers", not "discovers a bit later".
+        const misses = this.#onionLookupMisses.get(budgetKey) ?? 0;
+        const fullWidth = Math.max(8, Math.min(24, MAX_FRIEND_ROUTE_ATTEMPTS));
+        const width = misses === 0 || misses % 8 === 0 ? fullWidth : 4;
         const queue = dedupeNodes(this.#knownNodes.length > 0 ? this.#knownNodes : this.#opts.bootstrapNodes)
             .filter((n) => !this.#isNodeBlacklisted(`${n.host}:${n.port}`))
             .sort((a, b) => this.#nodeScore(`${b.host}:${b.port}`) - this.#nodeScore(`${a.host}:${a.port}`))
-            .slice(0, Math.max(8, Math.min(24, MAX_FRIEND_ROUTE_ATTEMPTS)));
+            .slice(0, width);
         const directKnown = queue.find((node) => node.pk === targetId);
         if (directKnown) {
+            this.#onionLookupMisses.delete(budgetKey);
             this.#cacheFriendRemote(friendId, directKnown.host, directKnown.port);
             this.#debugLog(`friend endpoint matched known node for ${friendId} at ${directKnown.host}:${directKnown.port}`);
             return true;
@@ -3106,11 +3180,15 @@ export class Peer {
             }
             const exact = discovered.find((n) => n.pk === targetId);
             if (exact) {
+                this.#onionLookupMisses.delete(budgetKey);
                 this.#cacheFriendRemote(friendId, exact.host, exact.port);
                 this.#debugLog(`friend endpoint discovered for ${friendId} at ${exact.host}:${exact.port}`);
                 return true;
             }
         }
+        // Nothing found: remember, so the next sweep for this target probes
+        // narrowly instead of paying the full 24-node price again.
+        this.#onionLookupMisses.set(budgetKey, misses + 1);
         return false;
     }
     async #announceSelfBestEffort(force = false, deadlineMs = Number.POSITIVE_INFINITY) {
@@ -3531,9 +3609,29 @@ export class Peer {
                         if (friendRealPk && friendRealPk.length === 32) {
                             // 1. Re-announce our DHT-PK so peer learns *our* UDP endpoint
                             //    even if their own DHT lookup against us was stale.
-                            void this.#sendOnionDhtPk(friendRealPk).catch((error) => {
-                                this.#debugLog(`UDP retry: dhtpk_send for ${friendId} failed: ${error.message}`);
-                            });
+                            //
+                            //    This shares #dhtPkSendCooldown with the periodic branch
+                            //    below ON PURPOSE. The two operations in this `if` have very
+                            //    different costs and must not share the 3s cadence: the
+                            //    endpoint offer above is one UDP packet, while an onion
+                            //    DHT-PK announce fans out to several nodes and does THREE
+                            //    X25519 scalar mults per node (one per onion layer). At 3s
+                            //    per friend that dominated the CPU of any node with a few
+                            //    idle relay friends — measured on smtp.gfax.cn: 82% of wall
+                            //    clock inside nacl, 83% of it under createOnionRequest0,
+                            //    against 2% on a node with none. Note the trigger is NOT a
+                            //    broken friend: udpConfirmed needs UDP traffic within 4s, so
+                            //    a perfectly healthy but idle relay friend qualifies forever.
+                            //
+                            //    Keep the offer at 3s (cheap, and it is what actually
+                            //    re-punches); let the expensive announce keep its 25s budget.
+                            const lastAnnounce = this.#dhtPkSendCooldown.get(friendId) ?? 0;
+                            if (now - lastAnnounce > DHT_PK_ANNOUNCE_COOLDOWN_MS) {
+                                this.#dhtPkSendCooldown.set(friendId, now);
+                                void this.#sendOnionDhtPk(friendRealPk).catch((error) => {
+                                    this.#debugLog(`UDP retry: dhtpk_send for ${friendId} failed: ${error.message}`);
+                                });
+                            }
                             // 2. Try to discover the peer's UDP endpoint and kick a
                             //    fresh cookie request via UDP. discoverAndCacheFriend
                             //    Endpoint accepts EITHER the DHT-PK (preferred —
@@ -3544,6 +3642,19 @@ export class Peer {
                             //    session.friendDhtPublicKey is null. Falling back
                             //    to friendRealPk keeps the retry from being a no-op
                             //    in exactly the case it was designed to fix.
+                            //    COST NOTE: those two lookups are not the same price. With a
+                            //    dhtPk it is a direct DHT query. Without one it is an
+                            //    ONION-routed lookup — several nodes, three X25519 scalar
+                            //    mults each — and the fallback fires precisely on
+                            //    relay-only sessions, which are the long-lived ones. At the
+                            //    3s re-punch cadence that made it the single biggest CPU
+                            //    consumer on a node with idle relay friends (measured on
+                            //    smtp.gfax.cn: 31% of all crypto time entered here). So the
+                            //    cheap direct lookup keeps the 3s cadence and only the onion
+                            //    fallback is charged against the announce budget.
+                            //    The per-(friend, target) budget now lives INSIDE
+                            //    #discoverAndCacheFriendEndpoint, so this call site stays
+                            //    simple and every other caller is covered by the same gate.
                             const dhtPk = session.friendDhtPublicKey;
                             const searchKey = dhtPk ?? friendRealPk;
                             if (searchKey && searchKey.length === 32) {
@@ -3577,8 +3688,7 @@ export class Peer {
             // bootstrap nodes). Per-friend cooldown via #dhtPkSendCooldown so we
             // don't flood onion data requests every 5s loop tick.
             const lastDhtPkSent = this.#dhtPkSendCooldown.get(friendId) ?? 0;
-            const dhtPkInterval = 25_000;
-            if (now - lastDhtPkSent > dhtPkInterval) {
+            if (now - lastDhtPkSent > DHT_PK_ANNOUNCE_COOLDOWN_MS) {
                 let friendRealPk = session?.friendRealPublicKey;
                 if (!friendRealPk && friend.address) {
                     try {
@@ -4765,6 +4875,14 @@ export class Peer {
      * UDP can't be punched. Relayed data is injected into #onDatagram tagged
      * `viaRelay` so it updates the relay freshness, not the direct endpoint.
      */
+    /**
+     * Test-only seam for scripts/turn-socket-leak-selftest.mjs: drive one TURN
+     * allocation attempt directly instead of waiting out the 120s-per-friend
+     * relay keepalive that reaches this path in production. Not public API.
+     */
+    async __testForceTurnAllocation() {
+        return this.#ensureTurnRelay().catch(() => undefined);
+    }
     async #ensureTurnRelay() {
         if (this.#ourRelayAddr)
             return this.#ourRelayAddr;
@@ -4772,15 +4890,10 @@ export class Peer {
             return this.#turnAllocating;
         this.#turnAllocating = (async () => {
             for (const srv of TURN_RELAY_SERVERS) {
+                let sock;
+                let client;
                 try {
-                    const sock = createDgramSocket("udp4");
-                    await new Promise((resolve, reject) => {
-                        sock.once("error", reject);
-                        sock.bind(0, () => {
-                            sock.off("error", reject);
-                            resolve();
-                        });
-                    });
+                    sock = await createBoundUdp4Socket();
                     // CRITICAL: a persistent 'error' listener. A TURN send to an
                     // unresolvable host (DNS NXDOMAIN — e.g. tokyo.fi.chat on a box whose
                     // resolver doesn't know it) emits an 'error' on this dgram socket;
@@ -4789,7 +4902,7 @@ export class Peer {
                     // "getaddrinfo ENOTFOUND tokyo.fi.chat", which churned every session).
                     // Swallow it — the relay simply won't allocate/relay over this server.
                     sock.on("error", (e) => this.#debugLog(`turn socket error (${srv.host}): ${e.message}`));
-                    const client = new TurnClient({
+                    client = new TurnClient({
                         sock,
                         creds: { host: srv.host, port: srv.port, realm: "", username: srv.username, password: srv.password }
                     });
@@ -4805,12 +4918,16 @@ export class Peer {
                     });
                     this.#turnSocket = sock;
                     this.#turnClient = client;
+                    sock = undefined;
+                    client = undefined;
                     this.#ourRelayAddr = { host: alloc.relayedAddress.address, port: alloc.relayedAddress.port };
                     this.#debugLog(`turn relay allocated on ${srv.host}: ${this.#ourRelayAddr.host}:${this.#ourRelayAddr.port}`);
                     return this.#ourRelayAddr;
                 }
                 catch (error) {
                     this.#debugLog(`turn relay allocate failed on ${srv.host}: ${error.message}`);
+                    client?.close();
+                    await closeDgramSocket(sock);
                 }
             }
             return undefined;

package/dist/transport/dgram-lifecycle.d.ts

@@ -0,0 +1,14 @@
+import { type Socket as DgramSocket } from "dgram";
+export type DgramSocketFactory = () => DgramSocket;
+export declare function createBoundUdp4Socket(createSocket?: DgramSocketFactory): Promise<DgramSocket>;
+/**
+ * Close a dgram socket and wait for the fd to actually be released.
+ *
+ * Never rejects and never hangs: `close()` throws ERR_SOCKET_DGRAM_NOT_RUNNING
+ * on an already-closed socket, and a socket caught mid-teardown may never run
+ * the close callback at all. Both must settle, because callers await this on
+ * the TURN failure path — a hang there would leave `#turnAllocating` pending
+ * forever and wedge every later caller awaiting that same promise, and would
+ * also block `Peer.stop()`.
+ */
+export declare function closeDgramSocket(sock: DgramSocket | undefined, timeoutMs?: number): Promise<void>;

package/dist/transport/dgram-lifecycle.js

@@ -0,0 +1,64 @@
+import { createSocket as createDgramSocket } from "dgram";
+export async function createBoundUdp4Socket(createSocket = () => createDgramSocket("udp4")) {
+    const sock = createSocket();
+    try {
+        await new Promise((resolve, reject) => {
+            const cleanup = () => {
+                sock.off("error", onError);
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            sock.once("error", onError);
+            sock.bind(0, () => {
+                cleanup();
+                resolve();
+            });
+        });
+        return sock;
+    }
+    catch (error) {
+        await closeDgramSocket(sock);
+        throw error;
+    }
+}
+/**
+ * Close a dgram socket and wait for the fd to actually be released.
+ *
+ * Never rejects and never hangs: `close()` throws ERR_SOCKET_DGRAM_NOT_RUNNING
+ * on an already-closed socket, and a socket caught mid-teardown may never run
+ * the close callback at all. Both must settle, because callers await this on
+ * the TURN failure path — a hang there would leave `#turnAllocating` pending
+ * forever and wedge every later caller awaiting that same promise, and would
+ * also block `Peer.stop()`.
+ */
+export async function closeDgramSocket(sock, timeoutMs = 2000) {
+    if (!sock)
+        return;
+    await new Promise((resolve) => {
+        let done = false;
+        let timer;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            sock.off("close", finish);
+            resolve();
+        };
+        // Belt and braces: the callback, the 'close' event, or the timer —
+        // whichever comes first releases the caller.
+        timer = setTimeout(finish, timeoutMs);
+        // Don't keep the event loop alive just to observe a close.
+        timer.unref?.();
+        try {
+            sock.once("close", finish);
+            sock.close(finish);
+        }
+        catch {
+            finish();
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.122",
+  "version": "0.1.124",
   "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",