@decentnetwork/peer 0.1.5 → 0.1.7

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]);
     }
@@ -1969,6 +1996,10 @@ 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;
         return storedNodes;
     }
     #ensureSelfAnnounceLoop() {

package/package.json

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