@freqhole/reliquary 0.0.0

package/dist/transfer/snatch.js

@@ -0,0 +1,289 @@
+// p2p blob download: snatch a blob from a peer, either into memory or
+// straight to a user-chosen disk location.
+//
+// per-peer retry loop tries three strategies in order against each peer:
+// bulk verified download with progress, chunk-streamed verified download,
+// and an unverified base64 proxy fallback. a strategy is skipped when its
+// node method is missing, and falls through to the next when it FAILS
+// against that peer - a peer whose backend only accepts an app-level rpc
+// alpn makes the verified strategies fail even though the local node has
+// the methods, and only the proxy fallback can reach it. a cancelled
+// error (see `cancellation.ts`) always rethrows immediately - it is never
+// treated as "this strategy/peer failed, try the next one".
+import { log } from "../utils/log.js";
+import { hashBlake3 } from "../worker/index.js";
+import { isCancelledError } from "./cancellation.js";
+const TAG = "transfer.snatch";
+const DEFAULT_TIMEOUT_MS = 10 * 60_000;
+/** how long to wait for trailing chunk-callback messages to arrive after
+ *  the download rpc's own promise has already resolved (see
+ *  `waitForBytesReceived` below). */
+const TAIL_CHUNK_WAIT_DEADLINE_MS = 30_000;
+const TAIL_CHUNK_POLL_INTERVAL_MS = 25;
+function withTimeout(promise, ms) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error("peer download timed out")), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new DOMException("snatch cancelled", "AbortError");
+}
+function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/** a worker-hosted node's chunk callback fires as its own fire-and-forget
+ *  message, on a separate channel from the download rpc's return value -
+ *  the rpc promise can resolve while the last few chunk messages are
+ *  still in flight. wait until every byte has actually landed before
+ *  treating the transfer as complete (this exact race lost the tail of a
+ *  large transfer once; the wait is load-bearing, not defensive fluff). */
+async function waitForBytesReceived(getReceived, total) {
+    const deadline = Date.now() + TAIL_CHUNK_WAIT_DEADLINE_MS;
+    while (getReceived() < total && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, TAIL_CHUNK_POLL_INTERVAL_MS));
+    }
+    if (getReceived() < total) {
+        throw new Error(`chunk stream incomplete: received ${getReceived()} of ${total} bytes`);
+    }
+}
+function parseFlatProxyResponse(body) {
+    const parsed = JSON.parse(body);
+    if (typeof parsed.data !== "string")
+        return null;
+    return { data: parsed.data, mime: parsed.mime };
+}
+async function base64ProxyFallback(node, peerAddr, info, options, timeoutMs) {
+    if (!node.proxy_request || !options.proxyPath)
+        return null;
+    const path = options.proxyPath(info.id ?? info.blake3);
+    const resp = await withTimeout(node.proxy_request(peerAddr, "GET", path, null), timeoutMs);
+    if (resp.status !== 200)
+        return null;
+    const parse = options.parseProxyResponse ?? parseFlatProxyResponse;
+    const parsed = parse(resp.body);
+    if (!parsed)
+        return null;
+    const bytes = base64ToBytes(parsed.data);
+    options.onProgress?.(1);
+    // strategies 1/2 get cryptographic verification for free - the
+    // transport checks every chunk against the requested hash's bao tree
+    // during the download itself. this fallback is a plain base64 json
+    // response with zero transfer-level integrity checking, so verify
+    // explicitly: a corrupted or malicious response must be rejected, not
+    // silently accepted and persisted under the wrong hash.
+    const actualHash = await hashBlake3(bytes);
+    if (actualHash !== info.blake3) {
+        throw new Error(`snatch hash mismatch: expected blake3 ${info.blake3.slice(0, 16)}... but downloaded bytes hash to ${actualHash.slice(0, 16)}... (proxy fallback is not cryptographically verified in transit)`);
+    }
+    return { bytes, blake3: info.blake3, mime: parsed.mime ?? info.mime };
+}
+async function snatchFromPeer(node, peerAddr, info, options, timeoutMs) {
+    let lastError;
+    // strategy 1: bulk verified download.
+    if (node.download_verified_with_ensure_progress) {
+        try {
+            const bytes = await withTimeout(node.download_verified_with_ensure_progress(peerAddr, info.blake3, info.size, options.onProgress ?? (() => { }), options.downloadId), timeoutMs);
+            return { bytes, blake3: info.blake3, mime: info.mime };
+        }
+        catch (err) {
+            // a deliberate pause must not fall through to the other strategies
+            if (isCancelledError(err))
+                throw err;
+            lastError = err;
+            log.debug(TAG, `strategy 1 (bulk verified) failed against ${peerAddr.slice(0, 16)}...:`, err);
+        }
+    }
+    // strategy 2: chunk-streamed verified download, accumulated in memory.
+    if (node.download_verified_streaming_with_ensure) {
+        try {
+            const chunks = [];
+            let bytesReceived = 0;
+            const onChunk = (chunk, offset) => {
+                bytesReceived += chunk.length;
+                chunks.push({ offset, data: chunk });
+            };
+            const total = await withTimeout(node.download_verified_streaming_with_ensure(peerAddr, info.blake3, info.size, onChunk, options.onProgress ?? (() => { }), options.downloadId), timeoutMs);
+            await waitForBytesReceived(() => bytesReceived, total);
+            const buffer = new Uint8Array(total);
+            for (const { offset, data } of chunks)
+                buffer.set(data, offset);
+            return { bytes: buffer, blake3: info.blake3, mime: info.mime };
+        }
+        catch (err) {
+            if (isCancelledError(err))
+                throw err;
+            lastError = err;
+            log.debug(TAG, `strategy 2 (streamed verified) failed against ${peerAddr.slice(0, 16)}...:`, err);
+        }
+    }
+    // strategy 3: unverified base64 proxy fallback. its own failures
+    // (non-200, bad envelope, hash mismatch) count as this peer failing.
+    const proxyAttempted = !!(node.proxy_request && options.proxyPath);
+    const fallback = await base64ProxyFallback(node, peerAddr, info, options, timeoutMs);
+    if (fallback)
+        return fallback;
+    if (proxyAttempted && !lastError) {
+        lastError = new Error("proxy fallback returned no blob");
+    }
+    throw lastError ?? new Error("peer has no supported download strategy");
+}
+/**
+ * download a blob's bytes from the first peer (in `peerNodeIds` order)
+ * that can serve it. a peer failure (offline, transport error, hash
+ * mismatch) tries the next peer; a cancelled error (see `cancellation.ts`)
+ * rethrows immediately with no next-peer retry.
+ */
+export async function snatchBlob(node, peerNodeIds, info, options = {}) {
+    if (peerNodeIds.length === 0) {
+        throw new Error("no peers available for snatch");
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let lastError;
+    for (const peerAddr of peerNodeIds) {
+        throwIfAborted(options.signal);
+        try {
+            const result = await snatchFromPeer(node, peerAddr, info, options, timeoutMs);
+            if (result.bytes.length === 0) {
+                throw new Error("snatch returned 0 bytes - refusing empty payload");
+            }
+            return result;
+        }
+        catch (err) {
+            if (isCancelledError(err))
+                throw err;
+            lastError = err;
+            log.warn(TAG, `snatch from peer ${peerAddr.slice(0, 16)}... failed:`, err);
+        }
+    }
+    throw lastError ?? new Error("snatch failed: all peers exhausted");
+}
+async function streamToWritable(node, peerAddr, info, writable, options, timeoutMs) {
+    // the File System Access API requires ordered, awaited writes; the
+    // transport's chunk callback fires synchronously and must not await, so
+    // writes are chained here and drained once the transfer settles.
+    let writeChain = Promise.resolve();
+    let writeError = null;
+    let bytesReceived = 0;
+    const onChunk = (chunk, offset) => {
+        bytesReceived += chunk.length;
+        if (writeError)
+            return; // stop queueing after the first failure
+        writeChain = writeChain.then(async () => {
+            if (writeError)
+                return;
+            try {
+                await writable.write({ type: "write", position: offset, data: chunk });
+            }
+            catch (err) {
+                writeError = err;
+            }
+        });
+    };
+    const total = await withTimeout(node.download_verified_streaming_with_ensure(peerAddr, info.blake3, info.size, onChunk, options.onProgress ?? (() => { }), options.downloadId), timeoutMs);
+    await waitForBytesReceived(() => bytesReceived, total);
+    await writeChain;
+    if (writeError)
+        throw writeError;
+    return total;
+}
+/**
+ * download a blob straight to a user-chosen disk location, writing each
+ * verified chunk to `writable` at its explicit offset as it streams in
+ * (no full payload ever held in memory). falls back to a fully-buffered
+ * `snatchBlob` + single write when the node has no streaming strategy.
+ *
+ * on a mid-stream peer failure, `writable` is truncated back to zero
+ * before the next peer is tried, so a retry never appends onto partial
+ * data. on a cancelled error, `writable` is left exactly as it is (no
+ * truncate, no close) so a resumed snatch can rewrite the same offsets;
+ * the caller owns pausing/closing/discarding it in that case.
+ */
+export async function snatchBlobToDisk(node, peerNodeIds, info, writable, options = {}) {
+    if (peerNodeIds.length === 0) {
+        throw new Error("no peers available for snatch");
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const canStream = typeof node.download_verified_streaming_with_ensure === "function";
+    let lastError;
+    for (const peerAddr of peerNodeIds) {
+        throwIfAborted(options.signal);
+        if (canStream) {
+            try {
+                const size = await streamToWritable(node, peerAddr, info, writable, options, timeoutMs);
+                if (size === 0) {
+                    throw new Error("snatch returned 0 bytes - refusing empty payload");
+                }
+                await writable.close();
+                return { size, blake3: info.blake3, mime: info.mime };
+            }
+            catch (err) {
+                if (isCancelledError(err))
+                    throw err;
+                lastError = err;
+                log.warn(TAG, `streamed snatch-to-disk from peer ${peerAddr.slice(0, 16)}... failed:`, err);
+                await writable.truncate(0);
+                continue;
+            }
+        }
+        let result;
+        try {
+            result = await snatchFromPeer(node, peerAddr, info, options, timeoutMs);
+            if (result.bytes.length === 0) {
+                throw new Error("snatch returned 0 bytes - refusing empty payload");
+            }
+        }
+        catch (err) {
+            if (isCancelledError(err))
+                throw err;
+            lastError = err;
+            log.warn(TAG, `buffered snatch-to-disk from peer ${peerAddr.slice(0, 16)}... failed:`, err);
+            continue;
+        }
+        throwIfAborted(options.signal);
+        // write phase: a failure here is a real disk-write error, not a peer
+        // problem, so it is surfaced directly - never retried against another
+        // peer. `.slice()` copies into a fresh, exactly-sized buffer (not the
+        // transport's possibly-oversized/shared backing buffer).
+        await writable.write(result.bytes.slice());
+        await writable.close();
+        return { size: result.bytes.length, blake3: result.blake3, mime: result.mime };
+    }
+    throw lastError ?? new Error("snatch failed: all peers exhausted");
+}
+/**
+ * pause an in-flight snatch registered under `downloadId`. the transfer
+ * stops at the next chunk boundary and its promise rejects with a
+ * cancelled error (see `isCancelledError`). the partial stays pinned in
+ * the transport's store - resume by calling `snatchBlob`/
+ * `snatchBlobToDisk` again with the same `downloadId`/blake3 (only
+ * missing ranges transfer). returns false when `node` has no
+ * `download_cancel` or the download already settled.
+ */
+export async function pauseSnatchDownload(node, downloadId) {
+    if (!node.download_cancel)
+        return false;
+    return (await node.download_cancel(downloadId)) === true;
+}
+/**
+ * discard a paused partial: releases the gc pin a paused download left
+ * behind so the transport can reclaim it. call when the user cancels for
+ * good rather than pausing to resume later. best-effort - failures are
+ * logged, not thrown.
+ */
+export async function discardPausedDownload(node, blake3Hash) {
+    if (!node.unprotect_blob)
+        return;
+    try {
+        await node.unprotect_blob(blake3Hash);
+    }
+    catch (err) {
+        log.debug(TAG, "discardPausedDownload failed (non-fatal):", err);
+    }
+}

package/dist/transfer/snatch.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snatch.test.d.ts.map

package/dist/transfer/snatch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snatch.test.d.ts","sourceRoot":"","sources":["../../src/transfer/snatch.test.ts"],"names":[],"mappings":""}

package/dist/transfer/snatch.test.js

@@ -0,0 +1,337 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+vi.mock("../worker/index.js", () => ({
+    hashBlake3: vi.fn(async (bytes) => `hash-of-${bytes.length}-bytes`),
+}));
+import { hashBlake3 } from "../worker/index.js";
+import { discardPausedDownload, pauseSnatchDownload, snatchBlob, snatchBlobToDisk, } from "./snatch.js";
+afterEach(() => {
+    vi.clearAllMocks();
+});
+const BLAKE3 = "abc123";
+const SIZE = 12;
+function bytes(n) {
+    const arr = new Uint8Array(n);
+    for (let i = 0; i < n; i++)
+        arr[i] = i % 256;
+    return arr;
+}
+describe("snatchBlob", () => {
+    it("returns bytes from strategy 1 (bulk verified download)", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(async (_peer, _hash, _size, onProgress) => {
+                onProgress(1);
+                return bytes(SIZE);
+            }),
+        };
+        const result = await snatchBlob(node, ["peer-a"], { blake3: BLAKE3, size: SIZE });
+        expect(result.bytes.length).toBe(SIZE);
+        expect(result.blake3).toBe(BLAKE3);
+        expect(node.download_verified_with_ensure_progress).toHaveBeenCalledWith("peer-a", BLAKE3, SIZE, expect.any(Function), undefined);
+    });
+    it("falls through to the next peer when one fails", async () => {
+        let calls = 0;
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(async (peer) => {
+                calls++;
+                if (peer === "peer-a")
+                    throw new Error("offline");
+                return bytes(SIZE);
+            }),
+        };
+        const result = await snatchBlob(node, ["peer-a", "peer-b"], { blake3: BLAKE3, size: SIZE });
+        expect(calls).toBe(2);
+        expect(result.bytes.length).toBe(SIZE);
+    });
+    it("rethrows a cancelled error immediately without trying the next peer", async () => {
+        let calls = 0;
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(async () => {
+                calls++;
+                throw new DOMException("aborted", "AbortError");
+            }),
+        };
+        await expect(snatchBlob(node, ["peer-a", "peer-b"], { blake3: BLAKE3, size: SIZE })).rejects.toMatchObject({ name: "AbortError" });
+        expect(calls).toBe(1);
+    });
+    it("throws immediately when the signal is already aborted", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(),
+        };
+        const controller = new AbortController();
+        controller.abort();
+        await expect(snatchBlob(node, ["peer-a"], { blake3: BLAKE3, size: SIZE }, { signal: controller.signal })).rejects.toMatchObject({ name: "AbortError" });
+        expect(node.download_verified_with_ensure_progress).not.toHaveBeenCalled();
+    });
+    it("assembles out-of-order chunks via strategy 2 (streaming) at their explicit offsets", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_streaming_with_ensure: vi.fn(async (_peer, _hash, _size, onChunk, onProgress) => {
+                // deliver out of order to prove offsets (not push order) win.
+                onChunk(new Uint8Array([40, 41, 42, 43]), 8);
+                onChunk(new Uint8Array([0, 1, 2, 3]), 0);
+                onChunk(new Uint8Array([10, 11, 12, 13]), 4);
+                onProgress(1);
+                return 12;
+            }),
+        };
+        const result = await snatchBlob(node, ["peer-a"], { blake3: BLAKE3, size: 12 });
+        expect(Array.from(result.bytes)).toEqual([0, 1, 2, 3, 10, 11, 12, 13, 40, 41, 42, 43]);
+    });
+    it("rejects when the streamed byte count never reaches the declared total", async () => {
+        vi.useFakeTimers();
+        try {
+            const node = {
+                node_id: () => "me",
+                download_verified_streaming_with_ensure: vi.fn(async (_peer, _hash, _size, onChunk) => {
+                    onChunk(new Uint8Array([1, 2, 3]), 0);
+                    return 12; // declares 12 total but only 3 bytes ever arrive
+                }),
+            };
+            const promise = snatchBlob(node, ["peer-a"], { blake3: BLAKE3, size: 12 });
+            const assertion = expect(promise).rejects.toThrow(/chunk stream incomplete/);
+            await vi.advanceTimersByTimeAsync(30_000);
+            await assertion;
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it("rejects an empty payload", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(async () => new Uint8Array(0)),
+        };
+        await expect(snatchBlob(node, ["peer-a"], { blake3: BLAKE3, size: 0 })).rejects.toThrow(/0 bytes/);
+    });
+    it("uses the base64 proxy fallback when no verified strategy is available, verifying the hash", async () => {
+        const payload = bytes(4);
+        const b64 = Buffer.from(payload).toString("base64");
+        const node = {
+            node_id: () => "me",
+            proxy_request: vi.fn(async () => ({
+                status: 200,
+                body: JSON.stringify({ data: b64, mime: "image/png" }),
+            })),
+        };
+        const expectedHash = `hash-of-${payload.length}-bytes`;
+        const result = await snatchBlob(node, ["peer-a"], {
+            blake3: expectedHash,
+            size: payload.length,
+            id: "some-app-id",
+        }, {
+            proxyPath: (id) => `/api/blobs/${id}/data`,
+        });
+        expect(node.proxy_request).toHaveBeenCalledWith("peer-a", "GET", "/api/blobs/some-app-id/data", null);
+        expect(Array.from(result.bytes)).toEqual(Array.from(payload));
+        expect(result.mime).toBe("image/png");
+        expect(hashBlake3).toHaveBeenCalled();
+    });
+    it("rejects a proxy-fallback response whose bytes don't match the expected blake3", async () => {
+        const payload = bytes(4);
+        const b64 = Buffer.from(payload).toString("base64");
+        const node = {
+            node_id: () => "me",
+            proxy_request: vi.fn(async () => ({
+                status: 200,
+                body: JSON.stringify({ data: b64 }),
+            })),
+        };
+        await expect(snatchBlob(node, ["peer-a"], { blake3: "not-the-real-hash", size: payload.length }, { proxyPath: (id) => `/api/blobs/${id}/data` })).rejects.toThrow(/hash mismatch/);
+    });
+    it("falls through to the next strategy on the same peer when a verified strategy fails", async () => {
+        // a peer whose backend only accepts an app-level rpc alpn makes the
+        // verified strategies fail even though the local node has the methods -
+        // the proxy fallback must still be attempted against that same peer.
+        const payload = bytes(4);
+        const b64 = Buffer.from(payload).toString("base64");
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(async () => {
+                throw new Error("peer rejected iroh-blobs alpn");
+            }),
+            download_verified_streaming_with_ensure: vi.fn(async () => {
+                throw new Error("peer rejected iroh-blobs alpn");
+            }),
+            proxy_request: vi.fn(async () => ({
+                status: 200,
+                body: JSON.stringify({ data: b64, mime: "image/png" }),
+            })),
+        };
+        const result = await snatchBlob(node, ["peer-a"], { blake3: `hash-of-${payload.length}-bytes`, size: payload.length }, { proxyPath: (id) => `/api/blobs/${id}/data` });
+        expect(node.download_verified_with_ensure_progress).toHaveBeenCalledTimes(1);
+        expect(node.download_verified_streaming_with_ensure).toHaveBeenCalledTimes(1);
+        expect(node.proxy_request).toHaveBeenCalledTimes(1);
+        expect(Array.from(result.bytes)).toEqual(Array.from(payload));
+    });
+    it("does not fall through to another strategy on a cancelled error", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(async () => {
+                throw new Error("download cancelled");
+            }),
+            download_verified_streaming_with_ensure: vi.fn(),
+            proxy_request: vi.fn(),
+        };
+        await expect(snatchBlob(node, ["peer-a", "peer-b"], { blake3: BLAKE3, size: SIZE }, { proxyPath: (id) => `/api/blobs/${id}/data` })).rejects.toThrow(/download cancelled/);
+        expect(node.download_verified_streaming_with_ensure).not.toHaveBeenCalled();
+        expect(node.proxy_request).not.toHaveBeenCalled();
+    });
+    it("parses a nested proxy envelope via parseProxyResponse", async () => {
+        const payload = bytes(4);
+        const b64 = Buffer.from(payload).toString("base64");
+        const node = {
+            node_id: () => "me",
+            proxy_request: vi.fn(async () => ({
+                status: 200,
+                body: JSON.stringify({ success: true, data: { data: b64, mime: "audio/wav" } }),
+            })),
+        };
+        const result = await snatchBlob(node, ["peer-a"], { blake3: `hash-of-${payload.length}-bytes`, size: payload.length }, {
+            proxyPath: (id) => `/api/blobs/${id}/data`,
+            parseProxyResponse: (body) => {
+                const parsed = JSON.parse(body);
+                if (!parsed.success || typeof parsed.data?.data !== "string")
+                    return null;
+                return { data: parsed.data.data, mime: parsed.data.mime };
+            },
+        });
+        expect(Array.from(result.bytes)).toEqual(Array.from(payload));
+        expect(result.mime).toBe("audio/wav");
+    });
+    it("throws when there are no peers to try", async () => {
+        const node = { node_id: () => "me" };
+        await expect(snatchBlob(node, [], { blake3: BLAKE3, size: SIZE })).rejects.toThrow(/no peers/);
+    });
+});
+class FakeWritable {
+    chunks = new Map();
+    closed = false;
+    truncated = [];
+    async write(input) {
+        if (input instanceof Uint8Array) {
+            this.chunks.set(0, input);
+            return;
+        }
+        this.chunks.set(input.position, input.data);
+    }
+    async truncate(size) {
+        this.truncated.push(size);
+        this.chunks.clear();
+    }
+    async close() {
+        this.closed = true;
+    }
+    assembled(total) {
+        const buf = new Uint8Array(total);
+        for (const [offset, data] of this.chunks)
+            buf.set(data, offset);
+        return buf;
+    }
+}
+describe("snatchBlobToDisk", () => {
+    it("streams verified chunks straight to the writable and closes it", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_streaming_with_ensure: vi.fn(async (_peer, _hash, _size, onChunk, onProgress) => {
+                onChunk(new Uint8Array([1, 2, 3, 4]), 0);
+                onChunk(new Uint8Array([5, 6, 7, 8]), 4);
+                onProgress(1);
+                return 8;
+            }),
+        };
+        const writable = new FakeWritable();
+        const result = await snatchBlobToDisk(node, ["peer-a"], { blake3: BLAKE3, size: 8 }, writable);
+        expect(result.size).toBe(8);
+        expect(Array.from(writable.assembled(8))).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+        expect(writable.closed).toBe(true);
+        expect(writable.truncated).toEqual([]);
+    });
+    it("truncates and retries the next peer on a mid-stream failure", async () => {
+        let attempt = 0;
+        const node = {
+            node_id: () => "me",
+            download_verified_streaming_with_ensure: vi.fn(async (peer, _h, _s, onChunk) => {
+                attempt++;
+                if (peer === "peer-a") {
+                    onChunk(new Uint8Array([9, 9]), 0);
+                    throw new Error("connection reset");
+                }
+                onChunk(new Uint8Array([1, 2, 3, 4]), 0);
+                return 4;
+            }),
+        };
+        const writable = new FakeWritable();
+        const result = await snatchBlobToDisk(node, ["peer-a", "peer-b"], { blake3: BLAKE3, size: 4 }, writable);
+        expect(attempt).toBe(2);
+        expect(writable.truncated).toEqual([0]);
+        expect(Array.from(writable.assembled(4))).toEqual([1, 2, 3, 4]);
+        expect(writable.closed).toBe(true);
+    });
+    it("leaves the writable open (no truncate, no close) on a cancelled download", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_streaming_with_ensure: vi.fn(async () => {
+                throw new Error("download cancelled");
+            }),
+        };
+        const writable = new FakeWritable();
+        await expect(snatchBlobToDisk(node, ["peer-a"], { blake3: BLAKE3, size: 4 }, writable)).rejects.toThrow(/download cancelled/);
+        expect(writable.truncated).toEqual([]);
+        expect(writable.closed).toBe(false);
+    });
+    it("falls back to a buffered download + single write when streaming is unavailable", async () => {
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: vi.fn(async () => bytes(6)),
+        };
+        const writable = new FakeWritable();
+        const result = await snatchBlobToDisk(node, ["peer-a"], { blake3: BLAKE3, size: 6 }, writable);
+        expect(result.size).toBe(6);
+        expect(writable.closed).toBe(true);
+    });
+    it("surfaces a buffered-path disk-write failure directly instead of retrying another peer", async () => {
+        const download = vi.fn(async () => bytes(6));
+        const node = {
+            node_id: () => "me",
+            download_verified_with_ensure_progress: download,
+        };
+        const writable = new FakeWritable();
+        writable.write = async () => {
+            throw new Error("disk full");
+        };
+        await expect(snatchBlobToDisk(node, ["peer-a", "peer-b"], { blake3: BLAKE3, size: 6 }, writable)).rejects.toThrow(/disk full/);
+        expect(download).toHaveBeenCalledTimes(1);
+    });
+});
+describe("pauseSnatchDownload / discardPausedDownload", () => {
+    it("pauses via download_cancel and reports whether a download was actually flagged", async () => {
+        const node = {
+            node_id: () => "me",
+            download_cancel: vi.fn(async () => true),
+        };
+        await expect(pauseSnatchDownload(node, "dl-1")).resolves.toBe(true);
+        expect(node.download_cancel).toHaveBeenCalledWith("dl-1");
+    });
+    it("returns false when the node has no download_cancel", async () => {
+        const node = { node_id: () => "me" };
+        await expect(pauseSnatchDownload(node, "dl-1")).resolves.toBe(false);
+    });
+    it("discards a paused download via unprotect_blob, swallowing errors", async () => {
+        const node = {
+            node_id: () => "me",
+            unprotect_blob: vi.fn(async () => {
+                throw new Error("boom");
+            }),
+        };
+        await expect(discardPausedDownload(node, BLAKE3)).resolves.toBeUndefined();
+        expect(node.unprotect_blob).toHaveBeenCalledWith(BLAKE3);
+    });
+    it("is a no-op when the node has no unprotect_blob", async () => {
+        const node = { node_id: () => "me" };
+        await expect(discardPausedDownload(node, BLAKE3)).resolves.toBeUndefined();
+    });
+});