@decentnetwork/peer 0.1.128 → 0.1.129

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/package.json

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