@decentnetwork/peer 0.1.0 → 0.1.2

package/dist/peer.d.ts

@@ -41,5 +41,36 @@ export declare class Peer {
     onFriendConnection(cb: (ev: FriendConnectionEvent) => void): void;
     onFriendInfo(cb: (ev: FriendInfoEvent) => void): void;
     friends(): FriendRecord[];
+    /**
+     * Read-only snapshot of the live net_crypto session state for a
+     * friend, or null if no session has been established yet. Lets
+     * callers see whether a peer is reachable via direct UDP, only via
+     * TCP relay, or not at all — the answer is the difference between
+     * ~80ms RTT (UDP) and ~500ms+ RTT (relay) in practice, so the
+     * caller (e.g. `agentnet diag`) can show an operator where their
+     * latency is coming from. Returns:
+     *
+     *   established  — handshake complete on this side
+     *   udpRemote    — direct UDP endpoint we've seen the peer at,
+     *                  if any; null means UDP holepunch hasn't
+     *                  succeeded (yet) so traffic falls back to TCP
+     *                  relay
+     *   hasTcpRoute  — true when a TCP relay has reported a route to
+     *                  the peer
+     *   transport    — convenience derived field: which path the next
+     *                  outbound packet will actually use
+     *   lastPingRecvMs — for staleness; if older than ~32s the session
+     *                    is on its way to timeout
+     */
+    sessionStatus(pubkey: string): {
+        established: boolean;
+        udpRemote: {
+            host: string;
+            port: number;
+        } | null;
+        hasTcpRoute: boolean;
+        transport: "udp" | "tcp-relay" | "both" | "none";
+        lastPingRecvMs: number | null;
+    } | null;
     waitForFriendRequest(timeoutMs?: number): Promise<FriendRequest>;
 }

package/dist/peer.js

@@ -747,6 +747,52 @@ export class Peer {
     friends() {
         return [...this.#friends.values()];
     }
+    /**
+     * Read-only snapshot of the live net_crypto session state for a
+     * friend, or null if no session has been established yet. Lets
+     * callers see whether a peer is reachable via direct UDP, only via
+     * TCP relay, or not at all — the answer is the difference between
+     * ~80ms RTT (UDP) and ~500ms+ RTT (relay) in practice, so the
+     * caller (e.g. `agentnet diag`) can show an operator where their
+     * latency is coming from. Returns:
+     *
+     *   established  — handshake complete on this side
+     *   udpRemote    — direct UDP endpoint we've seen the peer at,
+     *                  if any; null means UDP holepunch hasn't
+     *                  succeeded (yet) so traffic falls back to TCP
+     *                  relay
+     *   hasTcpRoute  — true when a TCP relay has reported a route to
+     *                  the peer
+     *   transport    — convenience derived field: which path the next
+     *                  outbound packet will actually use
+     *   lastPingRecvMs — for staleness; if older than ~32s the session
+     *                    is on its way to timeout
+     */
+    sessionStatus(pubkey) {
+        const s = this.#friendSessions.get(pubkey);
+        if (!s)
+            return null;
+        // session.remote can be a synthetic `tcp:<dhtpk>:0` placeholder
+        // when the TCP relay path reports an endpoint with no real UDP
+        // address; treat those as no-UDP for reporting.
+        const realUdp = s.remote && !s.remote.host?.startsWith("tcp:") && s.remote.port !== 0
+            ? { host: s.remote.host, port: s.remote.port }
+            : null;
+        const transport = realUdp
+            ? s.hasTcpRoute
+                ? "both"
+                : "udp"
+            : s.hasTcpRoute
+                ? "tcp-relay"
+                : "none";
+        return {
+            established: s.established === true,
+            udpRemote: realUdp,
+            hasTcpRoute: s.hasTcpRoute === true,
+            transport,
+            lastPingRecvMs: s.lastPingRecvMs ?? null,
+        };
+    }
     waitForFriendRequest(timeoutMs = 30000) {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
@@ -1984,6 +2030,79 @@ export class Peer {
                 if (session.remote && friend.status !== "online") {
                     this.#setFriendOnline(friendId, session.remote.host, session.remote.port);
                 }
+                // Phase 1.2: keep retrying UDP holepunch even after the session
+                // is already "established" via TCP relay. The toxcore-derived
+                // logic above stops trying once anybody is reachable, which is
+                // correct for messaging (text gets through) but disastrous for
+                // IP-packet forwarding (latency stays at ~500-1500ms via the
+                // relay detour instead of dropping to ~80ms once UDP works).
+                //
+                // We detect "on TCP-relay only" as: session.hasTcpRoute is set
+                // AND session.remote is either null or the synthetic
+                // {host: "tcp:<dhtpk>", port: 0} placeholder. In that state we
+                // re-send our DHT-PK so the peer (re-)learns our UDP endpoint,
+                // re-discover their endpoint via DHT, and trigger a fresh
+                // #initiateSession that will send a UDP cookie request. If UDP
+                // succeeds, #handleCryptoHandshake overwrites session.remote
+                // with the real endpoint and #sendMessengerPacket picks UDP
+                // over TCP from then on. Throttled to UDP_RETRY_INTERVAL_MS so
+                // the loop's 250ms tick doesn't flood DHT lookups.
+                const realUdpRemote = session.remote &&
+                    !session.remote.host?.startsWith("tcp:") &&
+                    session.remote.port !== 0;
+                if (!realUdpRemote && session.hasTcpRoute) {
+                    const UDP_RETRY_INTERVAL_MS = 15_000;
+                    const lastTry = session.lastUdpRetryMs ?? 0;
+                    if (now - lastTry > UDP_RETRY_INTERVAL_MS) {
+                        session.lastUdpRetryMs = now;
+                        // Recompute friend's real public key for the DHT-PK push.
+                        // Same fallback chain as the cooldown branch below.
+                        let friendRealPk = session.friendRealPublicKey;
+                        if (!friendRealPk && friend.address) {
+                            try {
+                                friendRealPk = parseCarrierAddress(friend.address).publicKey;
+                            }
+                            catch {
+                                // Fall through to the userid form.
+                            }
+                        }
+                        if (!friendRealPk && friend.pubkey) {
+                            try {
+                                friendRealPk = base58ToBytes(friend.pubkey);
+                            }
+                            catch {
+                                // Ignore malformed.
+                            }
+                        }
+                        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}`);
+                            });
+                            // 2. Try to discover the peer's UDP endpoint and kick a fresh
+                            //    cookie request via UDP. If it lands, session.remote
+                            //    becomes a real UDP endpoint and the next outbound
+                            //    packet goes direct.
+                            const dhtPk = session.friendDhtPublicKey;
+                            if (dhtPk) {
+                                void this.#discoverAndCacheFriendEndpoint(friendId, dhtPk)
+                                    .then((found) => {
+                                    if (found) {
+                                        return this.#initiateSession(friendId).catch(() => undefined);
+                                    }
+                                })
+                                    .catch(() => undefined);
+                            }
+                            else if (friend.remoteHost && friend.remotePort) {
+                                // We already have a real UDP endpoint cached — just
+                                // retry the cookie request to it.
+                                void this.#initiateSession(friendId).catch(() => undefined);
+                            }
+                            this.#debugLog(`UDP retry attempt for ${friendId} (currently on TCP relay)`);
+                        }
+                    }
+                }
                 continue;
             }
             // No active session: tell the friend our DHT public key so they can

package/package.json

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