@decentnetwork/peer 0.1.154 → 0.1.156

package/dist/peer.js

@@ -89,6 +89,21 @@ const NODE_BLACKLIST_MAX_TTL_MS = readEnvInt("DECENT_NODE_BLACKLIST_MAX_TTL_MS",
 const FRIEND_ANNOUNCE_ATTEMPTS = readEnvInt("DECENT_FRIEND_ANNOUNCE_ATTEMPTS", 1);
 const JOIN_ANNOUNCE_TIMEOUT_MS = readEnvInt("DECENT_JOIN_ANNOUNCE_TIMEOUT_MS", 12000);
 const SELF_ANNOUNCE_INTERVAL_MS = readEnvInt("DECENT_SELF_ANNOUNCE_INTERVAL_MS", 20000);
+// Slack on top of a run's own deadline before the watchdog abandons it. The
+// abandoned run is left to finish or hang on its own; what matters is that the
+// NEXT tick is allowed to start.
+const SELF_ANNOUNCE_WATCHDOG_MARGIN_MS = readEnvInt("DECENT_SELF_ANNOUNCE_WATCHDOG_MARGIN_MS", 15000);
+// Longest a self-announce pause may hold before it releases itself. The only
+// caller wraps a single friend-request send, which has its own 8s announce
+// deadline plus route discovery; 60s is well clear of a slow-but-working send
+// and well short of "the peer is now invisible".
+const SELF_ANNOUNCE_PAUSE_MAX_MS = readEnvInt("DECENT_SELF_ANNOUNCE_PAUSE_MAX_MS", 60_000);
+const FAULT_REQUEST_HANG = process.env.DECENT_FAULT_REQUEST_HANG === "1";
+// How long a stored announce entry stays useful to someone looking us up.
+// toxcore expires announce entries on roughly this timescale, so a node that
+// acknowledged a store longer ago than this can no longer be counted on.
+const ANNOUNCE_ENTRY_TTL_MS = readEnvInt("DECENT_ANNOUNCE_ENTRY_TTL_MS", 300_000);
+const FAULT_ANNOUNCE_HANG_RUN = readEnvInt("DECENT_FAULT_ANNOUNCE_HANG", 0);
 // Classic-DHT maintenance cadence. Every tick we get_nodes toward our own key
 // (so neighbours store our address and native peers can find our UDP endpoint)
 // and toward each not-yet-UDP friend's key (so we find theirs and punch).
@@ -475,6 +490,11 @@ export class Peer {
     // 25s forever for stale persisted entries.
     #dhtPkConsecutiveFailures = new Map();
     #lastSelfAnnounceStoredCount = -1;
+    // nodeId -> when that node last acknowledged STORING our announce. What
+    // callers actually want to know is "can anyone look me up right now", and
+    // that is a property of live storage across rounds, not of the round in
+    // flight. Counted against ANNOUNCE_ENTRY_TTL_MS on read.
+    #selfAnnounceStoredAt = new Map();
     // Diagnostics for the TCP-relay onion path (announce/discovery over TCP).
     // Surfaced in dhtHealth so `agentnet diag` shows whether it's active without
     // needing verbose logs: sent = onion requests handed to relays, recv = onion
@@ -536,6 +556,13 @@ export class Peer {
     #profileRetryTimers = new Map();
     #greetingSentTo = new Set();
     #selfAnnouncePromise;
+    #selfAnnounceRunCount = 0;
+    // Bumped when the watchdog abandons a run. The abandoned run is still alive
+    // and would otherwise keep writing #announceRouteUsed underneath the round
+    // that replaced it — and step2 rejects a ping_id whose route changed, so
+    // that interference would cost stores. It cannot be killed, but it can be
+    // told to stop at its next wave boundary.
+    #selfAnnounceEpoch = 0;
     #selfAnnouncePauseDepth = 0;
     #started = false;
     constructor(opts) {
@@ -1080,6 +1107,13 @@ export class Peer {
         }
         const resumeSelfAnnounce = this.#pauseSelfAnnounce();
         try {
+            // Fault injection, off unless DECENT_FAULT_REQUEST_HANG=1. Hangs inside
+            // the paused region — the shape that killed self-announce in the
+            // browser — so the pause expiry can be tested rather than argued for.
+            if (FAULT_REQUEST_HANG) {
+                this.#debugLog("FAULT: hanging inside the self-announce pause forever");
+                await new Promise(() => { });
+            }
             if (this.#selfAnnouncePromise) {
                 await this.#selfAnnouncePromise.catch(() => { });
             }
@@ -3633,6 +3667,17 @@ export class Peer {
             return [];
         }
         this.#lastSelfAnnounceMs = now;
+        // Fault injection, off unless DECENT_FAULT_ANNOUNCE_HANG names a run
+        // index. Reproduces the browser wedge — a run that never settles — so the
+        // watchdog in #runSelfAnnounce can be tested for real instead of only
+        // reasoned about. Same spirit as DECENT_ANNOUNCE_DEBUG: costs one integer
+        // compare when unset.
+        const myEpoch = this.#selfAnnounceEpoch;
+        this.#selfAnnounceRunCount += 1;
+        if (FAULT_ANNOUNCE_HANG_RUN > 0 && this.#selfAnnounceRunCount === FAULT_ANNOUNCE_HANG_RUN) {
+            this.#debugLog(`FAULT: hanging self-announce run #${this.#selfAnnounceRunCount} forever`);
+            await new Promise(() => { });
+        }
         const storedNodes = [];
         // An onion announce only STORES on the nodes whose key is closest to OURS,
         // and toxcore reaches them by following the "here are closer nodes" lists
@@ -3671,15 +3716,27 @@ export class Peer {
             queue.sort((x, y) => xorCloser(selfPk, x.nodePk, y.nodePk));
         };
         enqueueNodes(this.#knownNodes.length > 0 ? this.#knownNodes : this.#opts.bootstrapNodes);
-        // Reset counter at start so dhtHealth can distinguish "never ran" (-1)
-        // from "ran but stored on 0 nodes" (0).
-        this.#lastSelfAnnounceStoredCount = 0;
+        // No reset here. Zeroing at the START of every round is why dhtHealth
+        // read 0 for the first seconds of each round, and why a round cut short by
+        // the deadline published 0 even though ten nodes were still holding our
+        // announce from 10s earlier. Measured before this change: a healthy peer
+        // reported 0 / 10 / 0 / 0 / 10 across a 135s poll. Anyone sampling at the
+        // wrong moment — a user reading the UI, or me reading it and reporting it
+        // as a finding — concluded the peer was unfindable when it was not.
+        // "Never ran" is still distinguishable: #lastSelfAnnounceStoredCount
+        // stays -1 until the first round records something.
+        if (this.#lastSelfAnnounceStoredCount < 0)
+            this.#lastSelfAnnounceStoredCount = 0;
         const STORE_TARGET = 4;
         let waves = 0;
         while (queue.length > 0 && storedNodes.length < STORE_TARGET && waves < 16) {
             if (Date.now() >= deadlineMs) {
                 this.#debugLog("self announce stopped at deadline");
-                this.#lastSelfAnnounceStoredCount = storedNodes.length;
+                this.#publishSelfAnnounceStoredCount();
+                return storedNodes;
+            }
+            if (this.#selfAnnounceEpoch !== myEpoch) {
+                this.#debugLog("self announce abandoned by watchdog — stopping at wave boundary");
                 return storedNodes;
             }
             waves += 1;
@@ -3784,9 +3841,17 @@ export class Peer {
                 if (final.isStored === 2) {
                     storedNodes.push(c.node);
                     this.#debugLog(`self announce STORED on ${c.node.host}:${c.node.port} (total ${storedNodes.length})`);
-                    // Keep dhtHealth.selfAnnounceStoredOn live within the loop,
-                    // not just at the end, so we see growth in real time.
-                    this.#lastSelfAnnounceStoredCount = storedNodes.length;
+                    // Publish the running count only once it EXCEEDS the last completed
+                    // round's. Each round starts from an empty storedNodes, so writing it
+                    // through unconditionally made dhtHealth read 0 for the first second
+                    // or so of every round — and anyone who polled in that window saw
+                    // "stored on 0 nodes" and concluded the peer was unfindable. That
+                    // reading is what made the Air look permanently broken, and I
+                    // reported it as a finding once before checking whether it settled.
+                    // Measured on this Mac: the same peer alternates 0 / 9 / 10 / 0
+                    // across a two-minute poll while every round stores on ten nodes.
+                    this.#selfAnnounceStoredAt.set(`${c.node.host}:${c.node.port}`, Date.now());
+                    this.#publishSelfAnnounceStoredCount();
                 }
                 const discovered = parsePackedNodes(final.nodes);
                 if (discovered.length > 0) {
@@ -3797,12 +3862,22 @@ export class Peer {
                 }
             }
         }
-        // Track the most recent acknowledged-storage count so dhtHealth()
-        // can surface "DHT discovery layer alive but our announce isn't
-        // landing on any node" vs the normal case.
-        this.#lastSelfAnnounceStoredCount = storedNodes.length;
+        // Track live acknowledged storage so dhtHealth() can still surface "DHT
+        // discovery layer alive but our announce isn't landing anywhere" — that
+        // now shows up as the count DECAYING to 0 as entries age out, instead of
+        // flickering to 0 once per round.
+        this.#publishSelfAnnounceStoredCount();
         return storedNodes;
     }
+    /** Count nodes whose acknowledged store is still within its TTL. */
+    #publishSelfAnnounceStoredCount() {
+        const cutoff = Date.now() - ANNOUNCE_ENTRY_TTL_MS;
+        for (const [id, at] of this.#selfAnnounceStoredAt) {
+            if (at < cutoff)
+                this.#selfAnnounceStoredAt.delete(id);
+        }
+        this.#lastSelfAnnounceStoredCount = this.#selfAnnounceStoredAt.size;
+    }
     #ensureSelfAnnounceLoop() {
         if (this.#selfAnnounceTimer || SELF_ANNOUNCE_INTERVAL_MS <= 0) {
             return;
@@ -7285,22 +7360,89 @@ export class Peer {
         const recentBonus = Date.now() - h.lastOkMs < 60_000 ? 2 : 0;
         return (h.ok * 2) - h.fail + recentBonus;
     }
+    /**
+     * Pause the self-announce loop, with an expiry.
+     *
+     * The pause is released in a `finally`, which is correct right up until the
+     * guarded body never finishes. sendFriendRequest awaits a relay send inside
+     * that body, and in a browser a backgrounded tab can leave that socket
+     * neither open nor errored — so the `finally` never runs, the depth stays at
+     * 1, and self-announce is dead forever.
+     *
+     * This latch sits BEFORE the watchdog in #ensureSelfAnnounceLoop: the tick
+     * returns on pause depth without ever calling #runSelfAnnounce, so bounding
+     * the run was not enough on its own. Measured on app.beagle.chat after the
+     * watchdog shipped: announce age still climbing past 700s while the page's
+     * other timers ran normally.
+     *
+     * A pause is a short-lived thing — a few seconds around one send. One that
+     * outlives this window is a bug somewhere upstream, and the loop matters
+     * more than the pause does.
+     */
     #pauseSelfAnnounce() {
         this.#selfAnnouncePauseDepth += 1;
-        return () => {
+        let released = false;
+        const release = (viaTimeout) => {
+            if (released)
+                return;
+            released = true;
+            clearTimeout(expiry);
             this.#selfAnnouncePauseDepth = Math.max(0, this.#selfAnnouncePauseDepth - 1);
+            if (viaTimeout) {
+                this.#debugLog(`self-announce pause expired after ${Math.round(SELF_ANNOUNCE_PAUSE_MAX_MS / 1000)}s — ` +
+                    `releasing it; whoever took it never gave it back`);
+            }
         };
+        const expiry = setTimeout(() => release(true), SELF_ANNOUNCE_PAUSE_MAX_MS);
+        expiry.unref?.();
+        return () => release(false);
     }
     async #runSelfAnnounce(force, deadlineMs) {
         if (this.#selfAnnouncePromise) {
             await this.#selfAnnouncePromise.catch(() => { });
         }
-        this.#selfAnnouncePromise = this.#announceSelfBestEffort(force, deadlineMs);
+        // Hard deadline around the WHOLE run, not just the per-node waiter.
+        //
+        // #ensureSelfAnnounceLoop skips a tick while #selfAnnouncePromise is set,
+        // so one run that never settles kills self-announce FOREVER — silently,
+        // and with dhtHealth still reporting the last good numbers. Measured on
+        // app.beagle.chat 2026-08-31: lastSelfAnnounceMs frozen 1731s, stored
+        // stuck at 11, nobody able to look us up. lastSelfAnnounceMs is stamped
+        // on ENTRY, so a frozen value proves the function was never re-entered —
+        // the loop was latched, not failing.
+        //
+        // The hang is in the transport: #sendAnnounceAndWait awaits
+        // #sendThroughOnionPath BEFORE it awaits the timeout-guarded waiter, and
+        // in a browser that send goes over a relay WebSocket. A backgrounded tab
+        // can leave that socket neither open nor errored, so the await never
+        // settles and Promise.allSettled underneath waits forever. Native peers
+        // send over UDP and never hit it, which is why this was browser-only.
+        //
+        // Timing out the specific await would fix today's hang; this fixes the
+        // class. A self-healing loop must not depend on every transport path
+        // being timeout-correct to stay alive.
+        const budgetMs = Math.max(0, deadlineMs - Date.now()) + SELF_ANNOUNCE_WATCHDOG_MARGIN_MS;
+        let watchdog;
+        const guarded = Promise.race([
+            this.#announceSelfBestEffort(force, deadlineMs),
+            new Promise((resolve) => {
+                watchdog = setTimeout(() => {
+                    this.#debugLog(`self announce watchdog fired after ${Math.round(budgetMs / 1000)}s — ` +
+                        `abandoning the run so the loop can retry`);
+                    this.#selfAnnounceEpoch += 1;
+                    resolve([]);
+                }, budgetMs);
+                watchdog.unref?.();
+            }),
+        ]);
+        this.#selfAnnouncePromise = guarded;
         try {
-            const result = await this.#selfAnnouncePromise;
+            const result = await guarded;
             return result ?? [];
         }
         finally {
+            if (watchdog)
+                clearTimeout(watchdog);
             this.#selfAnnouncePromise = undefined;
         }
     }

package/package.json

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