@decentnetwork/peer 0.1.128 → 0.1.130

package/README.md

@@ -95,3 +95,47 @@ is your identity — back it up.
 ## License
 
 GPL-3.0-or-later. Same as upstream toxcore.
+
+## Tuning peer discovery
+
+Discovery is the loop that finds a friend's current UDP endpoint when there is
+no live session. It costs real CPU — every onion request is three X25519
+scalar multiplications, one per layer — so the defaults are a compromise, and
+a node with unusual friend counts or hardware may want to move them.
+
+All are environment variables read at startup.
+
+| Axis | Variable | Default | What it controls |
+|---|---|---|---|
+| **Interval** | `DECENT_DHT_PK_ANNOUNCE_COOLDOWN_MS` | `25000` | Minimum gap between lookups for the same friend |
+| **Backoff cap** | `DECENT_ONION_LOOKUP_MAX_BACKOFF_MS` | `120000` | Ceiling once a friend keeps failing to resolve |
+| **Breadth** | `DECENT_FRIEND_ROUTE_MAX_ATTEMPTS` | `24` | Nodes queried per sweep |
+| **Depth** | `DECENT_ONION_DATA_ATTEMPTS` | `5` | Retries per onion data packet |
+| Self-announce interval | `DECENT_SELF_ANNOUNCE_INTERVAL_MS` | `20000` | How often we re-announce ourselves |
+| Self-announce breadth | `DECENT_SELF_ANNOUNCE_TARGETS` | `16` | Nodes we announce to |
+
+### Which knob to turn
+
+**Turn the interval, not the breadth.** Cost is breadth x frequency, so both
+reduce CPU — but they fail differently. Narrowing breadth was tried and
+reverted: iOS peers appear in short windows and are only caught by a wide
+sweep, so a narrow one loses them outright rather than finding them late.
+Lengthening the interval degrades gracefully — the worst case is simply
+`ONION_LOOKUP_MAX_BACKOFF_MS`, the longest you can go without noticing a peer
+that came back.
+
+Read the backoff cap as exactly that: **the worst-case time to notice a friend
+returning.** Raising it to save CPU is a direct trade against how quickly the
+node reacts.
+
+### Symptoms and responses
+
+- **High steady CPU with offline friends.** Expected: each unreachable friend
+  is swept on its own schedule, so cost scales with how many friends are *not*
+  there. Raise `DECENT_ONION_LOOKUP_MAX_BACKOFF_MS`. Measured on a 2-core box
+  with ~5 unreachable friends, a flat 25s interval held the daemon at ~22% of
+  a core purely on lookups.
+- **A peer is online but never seen.** Lower the interval, or raise breadth if
+  it was lowered. Do not lower breadth further.
+- **Small or battery-powered device.** Raise the interval and the backoff cap
+  together; leave breadth alone.

package/dist/compat/tcp-relay-pool.d.ts

@@ -70,12 +70,31 @@ export declare class TcpRelayPool extends EventEmitter {
     /** Diagnostics. */
     connectedCount(): number;
     /**
-     * Send an onion request (createOnionRequest0Tcp packet) through up to `fanout`
-     * connected relays. Each relay forwards it to node B over UDP and routes the
-     * onion response back over TCP (surfaced via the pool's "onionResponse"
-     * event). Returns the number of relays the request was handed to (0 = none
-     * connected). Fanning out across a few relays covers the case where one relay
-     * can't reach node B.
+     * Send an onion request through up to `fanout` connected relays.
+     *
+     * Each relay forwards the packet to node B over UDP and routes the onion
+     * response back over TCP (surfaced via the pool's "onionResponse" event).
+     * Returns how many relays accepted it (0 = none connected).
+     *
+     * **What fanout buys.** The SAME request is handed to several relays, so it
+     * is redundancy, not extra reach: if one relay is unreachable, overloaded, or
+     * simply cannot get to node B, another copy still arrives. The peer sees one
+     * request either way — duplicates are dropped by the onion layer.
+     *
+     * **What it costs.** Linear in every resource this path spends: N relays
+     * means N times the TCP traffic and N times the work at the relay end. It
+     * does NOT multiply local crypto — the onion packet is built once and reused,
+     * so the X25519 cost is paid once regardless of fanout.
+     *
+     * **Choosing a value.** `1` is cheapest and correct on a stable link where
+     * the first relay is reliable; a lost request just waits for the next sweep.
+     * `2` (the default) is the useful middle: it covers a single dead relay,
+     * which is the common failure, at double the traffic on a path that is
+     * already small. Above 3 the added redundancy is mostly wasted — you are
+     * paying for the case where three independent relays fail at once, which in
+     * practice means the network is down, not the relays.
+     *
+     * Override with `DECENT_ONION_RELAY_FANOUT`.
      */
     sendOnionRequest(packet: Uint8Array, fanout?: number): number;
     /**

package/dist/compat/tcp-relay-pool.js

@@ -22,6 +22,14 @@
 import { EventEmitter } from "node:events";
 import { base58ToBytes } from "../utils/base58.js";
 import { TcpRelayClient } from "./tcp-relay.js";
+/** How many connected relays each onion request is duplicated across.
+ *
+ *  Redundancy against a single dead relay, at a linear cost in TCP traffic.
+ *  See {@link TcpRelayPool.sendOnionRequest} for how to choose a value. */
+const ONION_RELAY_FANOUT = (() => {
+    const raw = Number(process.env.DECENT_ONION_RELAY_FANOUT);
+    return Number.isInteger(raw) && raw >= 1 && raw <= 8 ? raw : 2;
+})();
 const KEY_SIZE = 32;
 // Connect to (up to) this many bootstrap nodes as persistent TCP relays. It was
 // 3 — but the pool picks the FIRST N in order, so a peer only met friends whose
@@ -212,14 +220,33 @@ export class TcpRelayPool extends EventEmitter {
         return this.#relays.filter((r) => r.client?.state() === "connected").length;
     }
     /**
-     * Send an onion request (createOnionRequest0Tcp packet) through up to `fanout`
-     * connected relays. Each relay forwards it to node B over UDP and routes the
-     * onion response back over TCP (surfaced via the pool's "onionResponse"
-     * event). Returns the number of relays the request was handed to (0 = none
-     * connected). Fanning out across a few relays covers the case where one relay
-     * can't reach node B.
+     * Send an onion request through up to `fanout` connected relays.
+     *
+     * Each relay forwards the packet to node B over UDP and routes the onion
+     * response back over TCP (surfaced via the pool's "onionResponse" event).
+     * Returns how many relays accepted it (0 = none connected).
+     *
+     * **What fanout buys.** The SAME request is handed to several relays, so it
+     * is redundancy, not extra reach: if one relay is unreachable, overloaded, or
+     * simply cannot get to node B, another copy still arrives. The peer sees one
+     * request either way — duplicates are dropped by the onion layer.
+     *
+     * **What it costs.** Linear in every resource this path spends: N relays
+     * means N times the TCP traffic and N times the work at the relay end. It
+     * does NOT multiply local crypto — the onion packet is built once and reused,
+     * so the X25519 cost is paid once regardless of fanout.
+     *
+     * **Choosing a value.** `1` is cheapest and correct on a stable link where
+     * the first relay is reliable; a lost request just waits for the next sweep.
+     * `2` (the default) is the useful middle: it covers a single dead relay,
+     * which is the common failure, at double the traffic on a path that is
+     * already small. Above 3 the added redundancy is mostly wasted — you are
+     * paying for the case where three independent relays fail at once, which in
+     * practice means the network is down, not the relays.
+     *
+     * Override with `DECENT_ONION_RELAY_FANOUT`.
      */
-    sendOnionRequest(packet, fanout = 2) {
+    sendOnionRequest(packet, fanout = ONION_RELAY_FANOUT) {
         let sent = 0;
         for (const r of this.#relays) {
             if (sent >= fanout)

package/dist/peer.js

@@ -968,7 +968,7 @@ export class Peer {
                 uint32ToLe(friendAddress.nospam),
                 appPayload
             ]);
-            const routes = await this.#discoverFriendRoutes(friendAddress.publicKey);
+            const routes = await this.#discoverFriendRoutes(friendAddress.publicKey, true);
             this.#debugLog(`friend route discovery done routes=${routes.length}`);
             if (routes.length === 0) {
                 // The direct net_crypto send needs a known endpoint for the target; to
@@ -2928,10 +2928,35 @@ export class Peer {
             // Ignore invalid offline payloads.
         }
     }
-    async #discoverFriendRoutes(friendPublicKey) {
+    /**
+     * @param userInitiated skips the budget. Adding a friend must not wait on a
+     *   throttle meant for background upkeep.
+     */
+    async #discoverFriendRoutes(friendPublicKey, userInitiated = false) {
         if (!this.#keyPair) {
             throw new Error("Peer is not started");
         }
+        // Same per-friend budget as #discoverAndCacheFriendEndpoint, enforced HERE
+        // for the same reason: this is the THIRD time today the cost simply moved
+        // to whichever caller was not gated. #sendOnionDhtPk's call sites were
+        // throttled, so the sweep underneath them became the top crypto entry
+        // instead — 17.9% of wall on gfax, climbing (20% -> 27% over ten minutes)
+        // rather than settling, because the DHT-PK path kept a FLAT 25s interval
+        // while the endpoint path had already been given backoff.
+        //
+        // A gate inside the function cannot be bypassed by a call site added later.
+        const routeKey = `routes:${carrierIdFromPublicKey(friendPublicKey)}`;
+        if (!userInitiated) {
+            const misses = this.#onionLookupMisses.get(routeKey) ?? 0;
+            const budget = Math.min(DHT_PK_ANNOUNCE_COOLDOWN_MS * Math.max(1, misses), ONION_LOOKUP_MAX_BACKOFF_MS);
+            const since = Date.now() - (this.#onionLookupCooldown.get(routeKey) ?? 0);
+            if (since < budget) {
+                this.#debugLog(`route discovery for ${routeKey} skipped: ${Math.round(since / 1000)}s ` +
+                    `since last (budget ${Math.round(budget / 1000)}s, misses ${misses})`);
+                return [];
+            }
+            this.#onionLookupCooldown.set(routeKey, Date.now());
+        }
         const searchKey = createEphemeralKeyPair();
         const routes = [];
         const routeSeen = new Set();
@@ -3075,6 +3100,15 @@ export class Peer {
                 }
             }
         }
+        // Miss accounting drives the backoff above. Without it the budget stays at
+        // its 25s floor forever and the gate does nothing for the friends that
+        // actually cost us — the ones that never resolve.
+        if (!userInitiated) {
+            if (routes.length > 0)
+                this.#onionLookupMisses.delete(routeKey);
+            else
+                this.#onionLookupMisses.set(routeKey, (this.#onionLookupMisses.get(routeKey) ?? 0) + 1);
+        }
         return routes;
     }
     async #discoverAndCacheFriendEndpoint(friendId, searchPublicKey) {

package/package.json

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