@decentnetwork/peer 0.1.70 → 0.1.72

package/dist/compat/filetransfer.d.ts

@@ -44,6 +44,9 @@ export declare class FileTransferManager {
     private readonly send;
     private readonly emit;
     constructor(send: FtSend, emit: FtEmit);
+    /** Enable resumable receives: partials are persisted under `dir` and matched
+     *  on re-offer by content-hash fileId. Unset = in-memory only (no resume). */
+    setResumeDir(dir: string): void;
     sendFile(friendId: string, data: Uint8Array, opts: {
         name: string;
         kind?: number;

package/dist/compat/filetransfer.js

@@ -20,6 +20,9 @@
 // implicit position); both ends here are the JS SDK. A native-interop mode
 // (Phase 2) can negotiate the plain format via the send-request.
 import { concatBytes, randomBytes } from "../utils/bytes.js";
+import { createHash } from "node:crypto";
+import { existsSync, statSync, readFileSync, appendFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 export const PACKET_ID_FILE_SENDREQUEST = 80;
 export const PACKET_ID_FILE_CONTROL = 81;
 export const PACKET_ID_FILE_DATA = 82;
@@ -30,19 +33,46 @@ export const MAX_CONCURRENT_FILE_PIPES = 256;
 export const MAX_FILE_DATA_SIZE = 1367;
 export const FILECONTROL = { ACCEPT: 0, PAUSE: 1, KILL: 2, SEEK: 3, ACK: 4 };
 export const FILEKIND = { DATA: 0, AVATAR: 1 };
-// Reliability tuning. We use a FIXED in-flight window (not TCP-style AIMD): a
-// file transfer over a private direct path should treat packet loss as RANDOM
-// (lossy Wi-Fi / long-haul jitter), NOT as congestion — backing the window off
-// on every random drop collapsed throughput to a crawl (minutes for a big
-// file). Instead, keep the window large and just retransmit the gaps fast. The
-// 4 MB UDP socket buffer absorbs the burst; the receiver buffers by offset, so
-// reordering is free.
-const WINDOW_CHUNKS = 768; // ~1 MB in flight — fills a 200ms-RTT path at ~5 MB/s
-const WATCHDOG_MS = 150; // resend from the ack point if no progress this long
+// Reliability tuning. We RAMP an in-flight window (AIMD-lite) rather than pin it:
+//  - RANDOM single-packet loss (dup-ack with a gap) is NOT congestion — fast-
+//    retransmit the hole and DON'T shrink the window, so lossy-but-fat paths
+//    (Wi-Fi / long-haul jitter) keep full throughput (the original intent).
+//  - A SUSTAINED stall (no ack progress for ~RTT) IS congestion — halve the
+//    window so we stop flooding the path. This is what keeps the *session* alive
+//    during a big transfer over a thin/relayed hop: without it, a fixed 1 MB
+//    window blasted go-back-N saturates the path, starves the net_crypto
+//    keepalive, and the whole session (ping included) times out. On a good path
+//    the window ramps back to WINDOW_CHUNKS within a few RTTs → same speed.
+// The 4 MB UDP socket buffer absorbs bursts; the receiver buffers by offset.
+const WINDOW_CHUNKS = 768; // ~1 MB — the window CAP (fills a 200ms-RTT path at ~5 MB/s)
+const CWND_INIT_CHUNKS = 16; // ~22 KB start — small so the opening burst can't bloat a thin path
+const CWND_MIN_CHUNKS = 8; // ~11 KB floor — keeps a slow/flaky path's buffer shallow
+// Congestion control (TCP Vegas — DELAY-based). Loss/AIMD control fails on a
+// slow peer with a deep buffer (a user's laptop): ~1 MB in flight piles up as
+// 12-23 s of queue latency with NO loss, so it never backs off, and the stalls
+// trigger go-back-N resends that balloon the queue further. Vegas instead reads
+// how many chunks are QUEUED from the RTT inflation — cwnd × (1 − minRtt/RTT) —
+// and steers the window to keep that between ALPHA and BETA. When the queue is
+// below ALPHA there's spare capacity → grow (no self-limiting, unlike a
+// rate-based cap); above BETA the queue is too deep → shrink. It converges to
+// "pipe full + a couple chunks queued" on ANY path: a fast link gets a big
+// window, a thin flaky one a small window and a shallow queue, automatically.
+// Target the ABSOLUTE queue delay (rtt − minRtt), not a packet count: bound the
+// latency the transfer ADDS to the path to ≈ MAX_QUEUE_MS on ANY path. A fast
+// link keeps a big window (it drains quickly, so a big window adds little
+// delay); a thin flaky one keeps a small window (a big window there would add
+// seconds). Growing whenever the added delay is low means no self-limiting.
+const MAX_QUEUE_MS = 150; // ceiling on added latency → when exceeded, drain
+const QUEUE_LOW_MS = 60; // below this there's spare capacity → grow
+const VEGAS_GROW = 1.3; // window ×this per RTT when under-filled
+const VEGAS_SHRINK = 0.85; // window ×this per RTT when the queue is too deep
+const WATCHDOG_MS = 150; // stall poll cadence / base no-progress patience
+const WATCHDOG_MAX_MS = 8000; // cap the RTT-adaptive stall patience (must exceed a slow path's RTT so acks aren't mistaken for a stall)
 const FAST_RT_MIN_MS = 40; // min gap between fast-retransmits of the same hole (≈1 RTT)
 const ACK_THROTTLE_MS = 15; // coalesce receiver acks (fast enough to drive fast-retransmit)
 const REACK_MS = 200; // receiver keep-alive re-ack cadence
 const SEND_GIVEUP_MS = 60000; // abandon a send after this long with no ack progress (peer gone)
+const PERSIST_INTERVAL_BYTES = 1024 * 1024; // flush the resume file at most once per this much progress
 function u32be(n) {
     const b = new Uint8Array(4);
     b[0] = (n >>> 24) & 0xff;
@@ -111,10 +141,27 @@ export class FileTransferManager {
     emit;
     #sending = new Map();
     #receiving = new Map();
+    // When set, incoming transfers persist their contiguous prefix here so a
+    // dropped/restarted transfer resumes instead of restarting (断点续传).
+    #resumeDir;
     constructor(send, emit) {
         this.send = send;
         this.emit = emit;
     }
+    /** Enable resumable receives: partials are persisted under `dir` and matched
+     *  on re-offer by content-hash fileId. Unset = in-memory only (no resume). */
+    setResumeDir(dir) {
+        try {
+            mkdirSync(dir, { recursive: true });
+            this.#resumeDir = dir;
+        }
+        catch {
+            this.#resumeDir = undefined;
+        }
+    }
+    #partPath(fileId) {
+        return this.#resumeDir ? join(this.#resumeDir, hex(fileId) + ".part") : undefined;
+    }
     #map(m, friendId) {
         let inner = m.get(friendId);
         if (!inner) {
@@ -134,12 +181,20 @@ export class FileTransferManager {
         const fileNumber = this.#freeNumber(friendId);
         if (fileNumber < 0)
             return null;
-        const fileId = randomBytes(FILE_ID_LENGTH);
+        // Content-addressed fileId (sha256): re-sending the SAME file after a
+        // restart or a dropped peer yields the SAME id, so the receiver can match
+        // it against its persisted partial and resume from where it left off — the
+        // key to 断点续传 (resumable transfer). Falls back to random for empty data.
+        const fileId = data.length > 0
+            ? new Uint8Array(createHash("sha256").update(data).digest()).slice(0, FILE_ID_LENGTH)
+            : randomBytes(FILE_ID_LENGTH);
         const req = encodeFileSendRequest(fileNumber, opts.kind ?? FILEKIND.DATA, BigInt(data.length), fileId, opts.name);
         const st = {
             fileNumber, fileId, name: opts.name, data, size: data.length,
             acked: 0, nextSend: 0, pumping: false, started: false, req, startMs: nowMs(),
             lastProgressAcked: 0, lastAckAdvanceMs: nowMs(), lastResendMs: 0,
+            cwnd: CWND_INIT_CHUNKS, stalls: 0,
+            minRttMs: Infinity, srttMs: 0, probeOffset: -1, probeSentMs: 0,
         };
         this.#map(this.#sending, friendId).set(fileNumber, st);
         void this.send(friendId, PACKET_ID_FILE_SENDREQUEST, req).catch(() => undefined);
@@ -225,10 +280,42 @@ export class FileTransferManager {
         const st = {
             fileNumber: r.fileNumber, fileId: r.fileId, name: r.filename, size,
             buf: new Uint8Array(size), got: new Uint8Array(chunkCount(size)),
-            contiguous: 0, maxByte: 0, done: false, ackDirty: false,
+            contiguous: 0, maxByte: 0, persisted: 0, partPath: this.#partPath(r.fileId), done: false, ackDirty: false,
         };
+        // 断点续传: if we persisted a contiguous prefix of this exact file (matched
+        // by content-hash fileId) before a drop/restart, load it and resume — our
+        // ack will tell the sender to skip past what we already have.
+        if (st.partPath && existsSync(st.partPath)) {
+            try {
+                const have = Math.min(statSync(st.partPath).size, size);
+                // Only the whole-chunk prefix is trustworthy; drop any tail into a
+                // partial last chunk. contiguous must sit on a chunk boundary unless
+                // it's the final byte.
+                const chunks = Math.floor(have / MAX_FILE_DATA_SIZE);
+                const usable = Math.min(chunks * MAX_FILE_DATA_SIZE, size);
+                if (usable > 0) {
+                    const partial = readFileSync(st.partPath);
+                    st.buf.set(partial.subarray(0, usable), 0);
+                    for (let i = 0; i < chunks; i++)
+                        st.got[i] = 1;
+                    st.contiguous = usable;
+                    st.maxByte = usable;
+                    st.persisted = usable;
+                    // Truncate the file to exactly the whole-chunk prefix, so subsequent
+                    // appends continue from `usable` (a leftover partial last chunk would
+                    // otherwise desync the append offset from st.persisted).
+                    if (have > usable)
+                        writeFileSync(st.partPath, st.buf.subarray(0, usable));
+                }
+            }
+            catch { /* corrupt/unreadable partial → start fresh */ }
+        }
         this.#map(this.#receiving, friendId).set(r.fileNumber, st);
         this.emit("file-offer", { friendId, fileNumber: r.fileNumber, fileId: hex(r.fileId), name: r.filename, size, kind: r.fileType });
+        if (st.contiguous >= size) {
+            this.#finishRecv(friendId, st);
+            return;
+        }
         if (size === 0)
             this.#finishRecv(friendId, st);
     }
@@ -300,6 +387,7 @@ export class FileTransferManager {
                 i++;
             st.contiguous = Math.min(i * MAX_FILE_DATA_SIZE, st.size);
             this.emit("file-progress", { friendId, fileId: hex(st.fileId), received: st.contiguous, total: st.size });
+            this.#persistPartial(st);
         }
         if (st.contiguous >= st.size) {
             this.#finishRecv(friendId, st);
@@ -307,6 +395,22 @@ export class FileTransferManager {
         }
         this.#scheduleAck(friendId, st);
     }
+    // Flush the newly-contiguous bytes to the resume file, throttled so we do at
+    // most one append per PERSIST_INTERVAL_BYTES of progress (not per chunk).
+    #persistPartial(st, force = false) {
+        if (!st.partPath)
+            return;
+        const pending = st.contiguous - st.persisted;
+        if (pending <= 0)
+            return;
+        if (!force && pending < PERSIST_INTERVAL_BYTES)
+            return;
+        try {
+            appendFileSync(st.partPath, st.buf.subarray(st.persisted, st.contiguous));
+            st.persisted = st.contiguous;
+        }
+        catch { /* disk issue → keep going in memory; resume just won't cover this gap */ }
+    }
     #finishRecv(friendId, st) {
         st.done = true;
         if (st.ackTimer) {
@@ -319,6 +423,13 @@ export class FileTransferManager {
         }
         this.#sendAck(friendId, st); // final ack so the sender completes
         const data = st.buf;
+        // Transfer complete → the resume file is no longer needed.
+        if (st.partPath) {
+            try {
+                unlinkSync(st.partPath);
+            }
+            catch { /* already gone */ }
+        }
         this.emit("file-complete", { friendId, fileId: hex(st.fileId), name: st.name, size: st.size, data });
         // Keep a lightweight done-marker (st.contiguous == size) so a LOST final
         // ack can be recovered: any further FILE_DATA for this slot re-acks. Free
@@ -360,9 +471,44 @@ export class FileTransferManager {
         const ackedOffset = readU32be(data, 0);
         const maxRecv = data.length >= 8 ? readU32be(data, 4) : ackedOffset;
         if (ackedOffset > st.acked) {
-            // Progress.
+            // Progress. The path is delivering → additively re-open the window (up to
+            // the cap) and clear the stall streak (patience shrinks back to the base).
+            const nowT = nowMs();
             st.acked = Math.min(ackedOffset, st.size);
-            st.lastAckAdvanceMs = nowMs();
+            st.lastAckAdvanceMs = nowT;
+            st.stalls = 0;
+            // Resume: if the receiver's ack jumps ahead of where we've sent (it had a
+            // persisted partial), skip the send cursor past the bytes it already has
+            // instead of re-transmitting them.
+            if (st.nextSend < st.acked)
+                st.nextSend = st.acked;
+            // Vegas: adjust the window ONCE PER RTT, when the timed frontier byte's ack
+            // returns (per-ack would fire several times before a slow path's probe
+            // reported, overshooting). Estimate chunks queued from RTT inflation and
+            // steer to keep it in [ALPHA, BETA].
+            if (st.probeOffset >= 0 && st.acked >= st.probeOffset) {
+                const rtt = nowT - st.probeSentMs;
+                st.probeOffset = -1;
+                // Reject glitch samples: a batched/late ack can make a probe byte look
+                // acked far sooner than it was really delivered, producing an RTT far
+                // below the smoothed value — which would corrupt minRtt and wreck the
+                // queue estimate. Only trust a sample within a sane band of srtt.
+                const glitch = st.srttMs > 0 && rtt < st.srttMs * 0.4;
+                if (!glitch && rtt > 0) {
+                    st.srttMs = st.srttMs === 0 ? rtt : 0.85 * st.srttMs + 0.15 * rtt;
+                    if (rtt < st.minRttMs)
+                        st.minRttMs = rtt;
+                    // Added latency this transfer is putting on the path = how deep the
+                    // queue is. Steer the window to keep it under MAX_QUEUE_MS.
+                    const queueDelayMs = st.minRttMs !== Infinity ? rtt - st.minRttMs : 0;
+                    if (queueDelayMs < QUEUE_LOW_MS) {
+                        st.cwnd = Math.min(WINDOW_CHUNKS, Math.ceil(st.cwnd * VEGAS_GROW)); // spare capacity → grow
+                    }
+                    else if (queueDelayMs > MAX_QUEUE_MS) {
+                        st.cwnd = Math.max(CWND_MIN_CHUNKS, Math.floor(st.cwnd * VEGAS_SHRINK)); // queue too deep → drain
+                    } // else hold: pipe full, queue shallow
+                }
+            }
             if (st.acked - st.lastProgressAcked >= 256 * 1024 || st.acked >= st.size) {
                 st.lastProgressAcked = st.acked;
                 this.emit("file-progress", { friendId, fileId: hex(st.fileId), received: st.acked, total: st.size, sending: true });
@@ -402,7 +548,14 @@ export class FileTransferManager {
                 }
                 if (st.acked >= st.size)
                     return;
-                if (nowMs() - st.lastAckAdvanceMs < WATCHDOG_MS) {
+                // RTT-adaptive patience: NEVER declare a stall before ~3 RTTs have
+                // passed, or a high-RTT path (acks legitimately arrive every 800ms+)
+                // false-stalls every 150ms, collapsing the window to the floor and
+                // go-back-N-re-blasting — exactly what pinned a thin path at the minimum.
+                // Take the max of the exponential backoff and 3× the smoothed RTT.
+                const rttFloor = st.srttMs > 0 ? st.srttMs * 3 : WATCHDOG_MS;
+                const patience = Math.min(WATCHDOG_MAX_MS, Math.max(WATCHDOG_MS << Math.min(st.stalls, 4), rttFloor));
+                if (nowMs() - st.lastAckAdvanceMs < patience) {
                     stalledSinceMs = nowMs();
                     return;
                 }
@@ -411,6 +564,12 @@ export class FileTransferManager {
                     this.emit("file-cancel", { friendId, fileId: hex(st.fileId), sending: true, reason: "timeout" });
                     return;
                 }
+                // Sustained stall = congestion/path signal → multiplicatively cut the
+                // window so we STOP flooding. This frees the path for the net_crypto
+                // keepalive + acks, keeping the session (and ping) alive; the transfer
+                // then self-clocks back up as acks resume.
+                st.stalls++;
+                st.cwnd = Math.max(CWND_MIN_CHUNKS, Math.floor(st.cwnd / 2));
                 st.lastAckAdvanceMs = nowMs();
                 st.lastResendMs = nowMs();
                 if (st.nextSend > st.acked)
@@ -425,7 +584,7 @@ export class FileTransferManager {
         st.pumping = true;
         try {
             while (this.#map(this.#sending, friendId).has(st.fileNumber) && st.acked < st.size) {
-                const windowEnd = Math.min(st.acked + WINDOW_CHUNKS * MAX_FILE_DATA_SIZE, st.size);
+                const windowEnd = Math.min(st.acked + st.cwnd * MAX_FILE_DATA_SIZE, st.size);
                 if (st.nextSend >= windowEnd)
                     break; // window full / all sent — wait for acks
                 const off = st.nextSend;
@@ -438,6 +597,12 @@ export class FileTransferManager {
                 }
                 if (st.nextSend === off)
                     st.nextSend = end; // unless a rewind moved it
+                // Arm one RTT probe per round-trip: time this fresh frontier byte until
+                // its ack lands, so #onAck can read the path's current queue delay.
+                if (st.probeOffset < 0 && end > st.acked) {
+                    st.probeOffset = end;
+                    st.probeSentMs = nowMs();
+                }
             }
         }
         finally {

package/dist/peer.js

@@ -312,6 +312,10 @@ export class Peer {
         };
         this.#knownNodes = [...opts.bootstrapNodes];
         this.#friendStoreFile = opts.friendStoreFile ?? `${opts.keyFile}.friends.json`;
+        // Enable resumable (断点续传) receives when the app gives us a directory to
+        // persist partials in.
+        if (opts.fileResumeDir)
+            this.#fileTransfer.setResumeDir(opts.fileResumeDir);
     }
     static async create(opts) {
         if (opts.compatibilityMode && opts.compatibilityMode !== "legacy") {

package/dist/types/peer.d.ts

@@ -44,6 +44,13 @@ export type PeerOptions = {
      * optimisation only applies to packet 64 and custom-id data is duplicated.
      */
     bulkDataPacketId?: number;
+    /**
+     * Directory for persisting partially-received files so a dropped or
+     * restarted transfer resumes instead of restarting (断点续传). Unset =
+     * in-memory only (no resume). The fileId is content-addressed (sha256), so a
+     * re-send of the same file matches its persisted partial automatically.
+     */
+    fileResumeDir?: string;
     /**
      * Display name this peer advertises to friends (Carrier nickname, packet 48 +
      * the userinfo profile). Without it every node reports the build default

package/package.json

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