@decentnetwork/peer 0.1.71 → 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;
@@ -42,15 +45,34 @@ export const FILEKIND = { DATA: 0, AVATAR: 1 };
 //    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 = 96; // ~131 KB start — ramps to the cap fast on a clean path
-const CWND_MIN_CHUNKS = 24; // ~33 KB floor — still enough to keep a thin path busy
-const CWND_GROW_CHUNKS = 48; // additive increase per ack-progress event
+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 = 2400; // cap the RTT-adaptive stall patience (high-RTT relay paths)
+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;
@@ -119,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) {
@@ -142,13 +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);
@@ -234,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);
     }
@@ -309,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);
@@ -316,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) {
@@ -328,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
@@ -371,10 +473,42 @@ export class FileTransferManager {
         if (ackedOffset > st.acked) {
             // 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.cwnd = Math.min(WINDOW_CHUNKS, st.cwnd + CWND_GROW_CHUNKS);
+            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 });
@@ -414,11 +548,13 @@ export class FileTransferManager {
                 }
                 if (st.acked >= st.size)
                     return;
-                // RTT-adaptive patience: after consecutive stalls, wait longer before
-                // deciding the path stalled — so a high-RTT relay hop doesn't trigger a
-                // spurious go-back-N re-blast before an ACK could even have returned
-                // (that spurious re-blast is exactly what collapses a thin path).
-                const patience = Math.min(WATCHDOG_MAX_MS, WATCHDOG_MS << Math.min(st.stalls, 4));
+                // 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;
@@ -461,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.71",
+  "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",