@instantdb/platform 1.0.64 → 1.0.65

package/.turbo/turbo-build.log

@@ -1,17 +1,17 @@
 
-> @instantdb/platform@1.0.64 build /home/runner/work/instant/instant/client/packages/platform
+> @instantdb/platform@1.0.65 build /home/runner/work/instant/instant/client/packages/platform
 > rm -rf dist; npm run build:tshy && npm run build:standalone && npm run check-exports
 
 npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 npm warn Unknown user config "always-auth". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 
-> @instantdb/platform@1.0.64 build:tshy
+> @instantdb/platform@1.0.65 build:tshy
 > tshy
 
 npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 npm warn Unknown user config "always-auth". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 
-> @instantdb/platform@1.0.64 build:standalone
+> @instantdb/platform@1.0.65 build:standalone
 > vite build
 
 vite v5.4.14 building for production...
@@ -19,17 +19,17 @@ transforming...
 ✓ 88 modules transformed.
 rendering chunks...
 computing gzip size...
-dist/standalone/index.umd.cjs  370.53 kB │ gzip: 102.56 kB
-dist/standalone/index.js  496.65 kB │ gzip: 119.99 kB
-✓ built in 1.71s
+dist/standalone/index.umd.cjs  372.28 kB │ gzip: 103.21 kB
+dist/standalone/index.js  499.57 kB │ gzip: 120.82 kB
+✓ built in 3.63s
 npm warn Unknown env config "verify-deps-before-run". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 npm warn Unknown user config "always-auth". This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.
 
-> @instantdb/platform@1.0.64 check-exports
+> @instantdb/platform@1.0.65 check-exports
 > attw --pack .
 
 
-@instantdb/platform v1.0.64
+@instantdb/platform v1.0.65
 
 Build tools:
 - @arethetypeswrong/cli@^0.18.5

package/__tests__/src/backupDownload.test.ts

@@ -168,6 +168,223 @@ describe('downloadBackupArchive', () => {
     await expect(promise).rejects.toMatchObject({ name: 'AbortError' });
   });
 
+  test('fetches later entries while an earlier one is still being written', async () => {
+    const files = [
+      { name: 'config.json', size: 1 },
+      { name: 'entities/a.jsonl', size: 1 },
+      { name: 'entities/b.jsonl', size: 1 },
+    ];
+    const started: string[] = [];
+    let resolveAllStarted!: () => void;
+    const allStarted = new Promise<void>((r) => {
+      resolveAllStarted = r;
+    });
+
+    const manager = {
+      listFiles: async () => files,
+      getFileUrl,
+      // A fetch records that it started and, once every entry's fetch has
+      // begun, releases the writer below.
+      streamStorageFiles: async function* () {},
+    } as any;
+    const trackingFetch = async (url: string) => {
+      started.push(url);
+      if (started.length === files.length) resolveAllStarted();
+      return bodyOf(`body:${url}`);
+    };
+
+    // The first entry's write can't finish until every fetch has started. A
+    // strictly sequential downloader would deadlock — the second file's fetch
+    // would wait on the first file's write, which waits on all fetches — so
+    // this test only completes because later fetches run ahead of the writer.
+    let firstAdd = true;
+    const createWriter = async (sink: WritableStream<Uint8Array>) => {
+      const w = sink.getWriter();
+      return {
+        add: async (_name: string, input: ReadableStream<Uint8Array>) => {
+          if (firstAdd) {
+            firstAdd = false;
+            await allStarted;
+          }
+          for await (const _chunk of input) {
+            // drain
+          }
+          await w.write(new Uint8Array([0]));
+        },
+        close: () => w.close(),
+      };
+    };
+
+    await downloadBackupArchive({
+      manager,
+      backup,
+      fetchBody: trackingFetch,
+      sink: nullSink(),
+      createWriter,
+    });
+
+    expect(started).toEqual([
+      'config.json',
+      'entities/a.jsonl',
+      'entities/b.jsonl',
+    ]);
+  });
+
+  test('retries a transient failure opening an entry body', async () => {
+    const names: string[] = [];
+    const manager = {
+      listFiles,
+      getFileUrl,
+      streamStorageFiles: async function* () {
+        yield { locationId: 'loc-1', path: 'a.png', url: 'loc-1-url' };
+      },
+    } as any;
+
+    // The storage blob's first open fails once, then succeeds.
+    let storageAttempts = 0;
+    const flakyFetch = async (url: string) => {
+      if (url === 'loc-1-url') {
+        storageAttempts++;
+        if (storageAttempts === 1) throw new Error('ECONNRESET');
+      }
+      return bodyOf(`body:${url}`);
+    };
+
+    const result = await downloadBackupArchive({
+      manager,
+      backup,
+      fetchBody: flakyFetch,
+      sink: nullSink(),
+      createWriter: makeWriter(names),
+      retry: { attempts: 3, delayMs: 0 },
+    });
+
+    expect(storageAttempts).toBe(2);
+    expect(names).toEqual([
+      'config.json',
+      'entities/todos.jsonl',
+      'files/loc-1',
+    ]);
+    expect(result.files).toBe(1);
+  });
+
+  test('retries a body that connects but errors on its first read', async () => {
+    const names: string[] = [];
+    const manager = {
+      listFiles,
+      getFileUrl,
+      streamStorageFiles: async function* () {
+        yield { locationId: 'loc-1', path: 'a.png', url: 'loc-1-url' };
+      },
+    } as any;
+
+    // fetchBody resolves (connection established) but the body errors on its
+    // first read the first time — the shape of a reset idle connection.
+    let storageAttempts = 0;
+    const flakyFetch = async (url: string) => {
+      if (url === 'loc-1-url') {
+        storageAttempts++;
+        if (storageAttempts === 1) {
+          return new ReadableStream<Uint8Array>({
+            pull(controller) {
+              controller.error(new Error('ECONNRESET'));
+            },
+          });
+        }
+      }
+      return bodyOf(`body:${url}`);
+    };
+
+    const result = await downloadBackupArchive({
+      manager,
+      backup,
+      fetchBody: flakyFetch,
+      sink: nullSink(),
+      createWriter: makeWriter(names),
+      retry: { attempts: 3, delayMs: 0 },
+    });
+
+    expect(storageAttempts).toBe(2);
+    expect(names).toEqual([
+      'config.json',
+      'entities/todos.jsonl',
+      'files/loc-1',
+    ]);
+    expect(result.files).toBe(1);
+  });
+
+  test('does not retry once the body has yielded a chunk', async () => {
+    const manager = {
+      listFiles,
+      getFileUrl,
+      streamStorageFiles: async function* () {
+        yield { locationId: 'loc-1', path: 'a.png', url: 'loc-1-url' };
+      },
+    } as any;
+
+    // The body delivers one chunk on the first read, then errors on the next —
+    // a mid-stream failure. Once bytes are flowing the entry can't be
+    // restarted, so this must not retry.
+    let storageAttempts = 0;
+    const fetchBody = async (url: string) => {
+      if (url === 'loc-1-url') {
+        storageAttempts++;
+        let phase = 0;
+        return new ReadableStream<Uint8Array>({
+          pull(controller) {
+            if (phase++ === 0) {
+              controller.enqueue(new TextEncoder().encode('partial'));
+            } else {
+              controller.error(new Error('mid-stream reset'));
+            }
+          },
+        });
+      }
+      return bodyOf(`body:${url}`);
+    };
+
+    await expect(
+      downloadBackupArchive({
+        manager,
+        backup,
+        fetchBody,
+        sink: nullSink(),
+        createWriter: makeWriter([]),
+        retry: { attempts: 3, delayMs: 0 },
+      }),
+    ).rejects.toThrow();
+    expect(storageAttempts).toBe(1);
+  });
+
+  test('gives up after exhausting retries and names the failing entry', async () => {
+    const manager = {
+      listFiles,
+      getFileUrl,
+      streamStorageFiles: async function* () {
+        yield { locationId: 'loc-9', path: null, url: 'bad-url' };
+      },
+    } as any;
+
+    let attempts = 0;
+    await expect(
+      downloadBackupArchive({
+        manager,
+        backup,
+        fetchBody: async (url: string) => {
+          if (url === 'bad-url') {
+            attempts++;
+            throw new Error('HTTP 500');
+          }
+          return bodyOf('x');
+        },
+        sink: nullSink(),
+        createWriter: makeWriter([]),
+        retry: { attempts: 3, delayMs: 0 },
+      }),
+    ).rejects.toThrow('Couldn\'t download storage file "loc-9" (HTTP 500).');
+    expect(attempts).toBe(3);
+  });
+
   test('names a pathless storage file by locationId when its download fails', async () => {
     const manager = {
       listFiles,
@@ -187,6 +404,7 @@ describe('downloadBackupArchive', () => {
         },
         sink: nullSink(),
         createWriter: makeWriter([]),
+        retry: { attempts: 1 },
       }),
     ).rejects.toThrow('Couldn\'t download storage file "loc-9" (HTTP 500).');
   });

package/dist/commonjs/backupDownload.d.ts

@@ -54,6 +54,33 @@ export type DownloadBackupArchiveOpts = {
     createWriter: (sink: WritableStream<Uint8Array>, signal: AbortSignal) => Promise<BackupArchiveWriter>;
     signal?: AbortSignal;
     onProgress?: (progress: BackupDownloadProgress) => void;
+    /**
+     * How many entries to fetch ahead of the one currently being written into
+     * the archive.
+     *
+     * Only fetch *initiation* is parallelised, the bodies are still written in
+     * order and consumed one at a time, so an in-flight prefetched body buffers
+     * only to its stream's high-water mark and memory stays bounded. Defaults to
+     * {@link DEFAULT_PREFETCH}.
+     */
+    prefetch?: number;
+    /**
+     * Retry policy for *opening* an entry's body (fetching its presigned URL and
+     * getting a live response). Prefetching keeps body connections open, paused,
+     * while earlier entries write, so a queued connection can be reset before we
+     * read it.
+     * `attempts` is the total number of tries (default {@link DEFAULT_FETCH_ATTEMPTS});
+     * `delayMs` is the base for exponential backoff (default {@link DEFAULT_RETRY_DELAY_MS}).
+     *
+     * This only covers failures before the writer starts consuming the body.
+     * Once bytes have been written into the archive entry there's no way to
+     * restart it without HTTP range/resume support, so a mid-stream failure
+     * still fails the download.
+     */
+    retry?: {
+        attempts?: number;
+        delayMs?: number;
+    };
 };
 /**
  * Downloads a backup into a single archive written to `opts.sink`: entries

package/dist/commonjs/backupDownload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backupDownload.d.ts","sourceRoot":"","sources":["../../src/backupDownload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,cAAc,EACf,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,sBAAsB,GAAG;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,QAAQ,EAAE,MAAM,CAAC;IAIjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAG1B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,EACjC,IAAI,EAAE;QAAE,WAAW,EAAE,IAAI,CAAA;KAAE,GAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,EAAE,SAAS,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,EAAE,CACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IACzC;;;;OAIG;IACH,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC;;;OAGG;IACH,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;CACzD,CAAC;AAQF;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,yBAAyB,GAAG;IAChC,OAAO,EAAE,IAAI,CACX,cAAc,EACd,WAAW,GAAG,YAAY,GAAG,oBAAoB,CAClD,CAAC;CACH,GACA,OAAO,CAAC,oBAAoB,CAAC,CAiQ/B"}
+{"version":3,"file":"backupDownload.d.ts","sourceRoot":"","sources":["../../src/backupDownload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,cAAc,EACf,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,sBAAsB,GAAG;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B,QAAQ,EAAE,MAAM,CAAC;IAIjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAG1B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,EACjC,IAAI,EAAE;QAAE,WAAW,EAAE,IAAI,CAAA;KAAE,GAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,EAAE,SAAS,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,EAAE,CACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IACzC;;;;OAIG;IACH,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC;;;OAGG;IACH,YAAY,EAAE,CACZ,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,MAAM,EAAE,WAAW,KAChB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACxD;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD,CAAC;AAoNF;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,yBAAyB,GAAG;IAChC,OAAO,EAAE,IAAI,CACX,cAAc,EACd,WAAW,GAAG,YAAY,GAAG,oBAAoB,CAClD,CAAC;CACH,GACA,OAAO,CAAC,oBAAoB,CAAC,CAwR/B"}

package/dist/commonjs/backupDownload.js

@@ -1,8 +1,168 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.downloadBackupArchive = downloadBackupArchive;
+const DEFAULT_PREFETCH = 4;
+const DEFAULT_FETCH_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 500;
+const MAX_RETRY_DELAY_MS = 5000;
+// Normalize caller-supplied numeric options so NaN/Infinity/non-integers can't
+// alter retry counts or pipeline bounds — fall back to the default instead.
+const finitePositiveInt = (v, fallback) => v != null && Number.isInteger(v) && v > 0 ? v : fallback;
+const finiteNonNegative = (v, fallback) => v != null && Number.isFinite(v) && v >= 0 ? v : fallback;
 const isAbortError = (e) => e?.name === 'AbortError';
 const errorMessage = (e) => e instanceof Error ? e.message : String(e);
+// A cancellable sleep: resolves after `ms`, or rejects if the signal aborts
+// first so backoff between retries doesn't outlive a cancelled download.
+const delay = (ms, signal) => new Promise((resolve, reject) => {
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+    };
+    const timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort);
+        resolve();
+    }, ms);
+    signal.addEventListener('abort', onAbort, { once: true });
+});
+// Re-emits an already-read first chunk, then streams the rest from `reader`.
+// Past that first chunk read errors propagate to the consumer unchanged — by
+// then bytes are in the archive entry and it can't be restarted.
+function replayFrom(first, reader) {
+    let replayed = false;
+    return new ReadableStream({
+        async pull(controller) {
+            if (!replayed) {
+                replayed = true;
+                if (first.done) {
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(first.value);
+                return;
+            }
+            const { done, value } = await reader.read();
+            if (done)
+                controller.close();
+            else
+                controller.enqueue(value);
+        },
+        async cancel(reason) {
+            await reader.cancel(reason);
+        },
+    });
+}
+/**
+ * Opens a body via `open`, retrying on transient failure with abortable
+ * exponential backoff. `open` is re-invoked from scratch each attempt, so an
+ * entity file re-mints its presigned URL. An abort propagates immediately; any
+ * other final failure is wrapped by `describe` into a user-facing message
+ * naming the entry.
+ *
+ * The first chunk is read inside the retry scope, so a body that connects but
+ * fails on its first read — the shape of a prefetched connection reset while it
+ * sat idle — is re-fetched too, since nothing has been written to the archive
+ * yet. Only failures once bytes are flowing are treated as unrecoverable.
+ */
+async function openWithRetry(open, opts) {
+    let lastError;
+    for (let attempt = 1; attempt <= opts.attempts; attempt++) {
+        opts.signal.throwIfAborted();
+        let reader;
+        try {
+            const body = await open();
+            reader = body.getReader();
+            const first = await reader.read();
+            return replayFrom(first, reader);
+        }
+        catch (e) {
+            // Release the failed connection before retrying (or giving up).
+            if (reader)
+                reader.cancel().catch(() => { });
+            if (isAbortError(e))
+                throw e;
+            lastError = e;
+            if (attempt < opts.attempts) {
+                const backoff = Math.min(opts.delayMs * 2 ** (attempt - 1), MAX_RETRY_DELAY_MS);
+                await delay(backoff, opts.signal);
+            }
+        }
+    }
+    throw new Error(opts.describe(lastError));
+}
+/**
+ * Wraps an ordered stream of entry thunks, keeping up to `lookahead` fetches
+ * in flight while yielding the prepared entries in their original order. A
+ * background producer pulls thunks and starts their fetches as space frees up;
+ * the consumer awaits each in turn. Preserves order and backpressure: at most
+ * `lookahead` bodies are ever in flight, and the producer parks when the
+ * pipeline is full or the source is waiting for more work.
+ */
+async function* prefetchEntries(thunks, lookahead) {
+    const pipeline = [];
+    const state = { done: false, producerError: null, onItem: null, onSpace: null };
+    const wakeItem = () => {
+        const w = state.onItem;
+        state.onItem = null;
+        if (w)
+            w();
+    };
+    const wakeSpace = () => {
+        const w = state.onSpace;
+        state.onSpace = null;
+        if (w)
+            w();
+    };
+    // Never rejects: a failure to produce the next thunk (or start its fetch)
+    // lands in state.producerError for the consumer to throw in order.
+    const producer = (async () => {
+        try {
+            for await (const thunk of thunks) {
+                while (pipeline.length >= lookahead) {
+                    await new Promise((resolve) => {
+                        state.onSpace = resolve;
+                    });
+                }
+                const started = thunk();
+                // The consumer awaits `started` in order; attach a no-op catch so a
+                // fetch that rejects before then isn't reported as unhandled.
+                started.catch(() => { });
+                pipeline.push(started);
+                wakeItem();
+            }
+        }
+        catch (e) {
+            state.producerError = e;
+        }
+        finally {
+            state.done = true;
+            wakeItem();
+        }
+    })();
+    try {
+        while (true) {
+            if (pipeline.length === 0) {
+                if (state.done) {
+                    if (state.producerError)
+                        throw state.producerError;
+                    break;
+                }
+                await new Promise((resolve) => {
+                    state.onItem = resolve;
+                });
+                continue;
+            }
+            const entry = await pipeline.shift();
+            wakeSpace();
+            yield entry;
+        }
+    }
+    finally {
+        // On early exit (abort/error), let the producer unwind — its own signal
+        // teardown resolves the source's waits — without blocking here.
+        wakeSpace();
+        producer.catch(() => { });
+    }
+}
 /**
  * Downloads a backup into a single archive written to `opts.sink`: entries
  * in the canonical restore order (`config.json`, then the
@@ -41,6 +201,8 @@ async function downloadBackupArchive(opts) {
     const bytesTotal = backup.uncompressedSize != null
         ? backup.uncompressedSize + (backup.filesSize ?? 0)
         : null;
+    const retryAttempts = finitePositiveInt(opts.retry?.attempts, DEFAULT_FETCH_ATTEMPTS);
+    const retryDelayMs = finiteNonNegative(opts.retry?.delayMs, DEFAULT_RETRY_DELAY_MS);
     const tick = () => onProgress?.({
         entitiesCompleted,
         entitiesTotal,
@@ -119,7 +281,14 @@ async function downloadBackupArchive(opts) {
             notify();
         }
     })();
-    const entries = (async function* () {
+    // Entry write order is significant for restore: config.json first, then the
+    // entities/*.jsonl shards, then files/<locationId>. In particular ALL entity
+    // files must be written before ANY storage file. listFiles returns the
+    // entity files in write order; this generator yields thunks for them in
+    // order, then drains the storage queue. The thunks are consumed through
+    // prefetchEntries, which starts a bounded number of the fetches ahead of the
+    // encoder while keeping this order and one-at-a-time writing.
+    const thunks = (async function* () {
         const files = await manager.listFiles(backup.id, { signal });
         if (files.length === 0) {
             throw new Error('No files found for this backup.');
@@ -134,30 +303,32 @@ async function downloadBackupArchive(opts) {
         entitiesTotal = files.filter((f) => f.name !== 'config.json').length;
         tick();
         for (const f of files) {
-            currentEntity = f.name;
-            tick();
-            const url = await manager.getFileUrl(backup.id, f.name, { signal });
-            let body;
-            try {
-                body = await fetchBody(url, signal);
-            }
-            catch (e) {
-                if (isAbortError(e))
-                    throw e;
-                throw new Error(`Failed to fetch ${f.name}: ${errorMessage(e)}.`);
-            }
-            yield {
-                name: f.name,
-                input: countBytes(body),
-                onAdded: () => {
-                    if (f.name !== 'config.json')
-                        entitiesCompleted++;
-                    tick();
-                },
+            yield async () => {
+                const body = await openWithRetry(async () => {
+                    const url = await manager.getFileUrl(backup.id, f.name, { signal });
+                    return fetchBody(url, signal);
+                }, {
+                    signal,
+                    attempts: retryAttempts,
+                    delayMs: retryDelayMs,
+                    describe: (e) => `Failed to fetch ${f.name}: ${errorMessage(e)}.`,
+                });
+                return {
+                    name: f.name,
+                    input: countBytes(body),
+                    onWriting: () => {
+                        currentEntity = f.name;
+                        currentFile = '';
+                        tick();
+                    },
+                    onAdded: () => {
+                        if (f.name !== 'config.json')
+                            entitiesCompleted++;
+                        tick();
+                    },
+                };
             };
         }
-        currentEntity = '';
-        tick();
         while (true) {
             if (storageError)
                 throw storageError;
@@ -173,25 +344,28 @@ async function downloadBackupArchive(opts) {
                 queueHead++;
             }
             if (file) {
-                const label = file.path || file.locationId;
-                currentFile = label;
-                tick();
-                let body;
-                try {
-                    body = await fetchBody(file.url, signal);
-                }
-                catch (e) {
-                    if (isAbortError(e))
-                        throw e;
-                    throw new Error(`Couldn't download storage file "${label}" (${errorMessage(e)}).`);
-                }
-                yield {
-                    name: `files/${file.locationId}`,
-                    input: countBytes(body),
-                    onAdded: () => {
-                        filesCompleted++;
-                        tick();
-                    },
+                const storageFile = file;
+                const label = storageFile.path || storageFile.locationId;
+                yield async () => {
+                    const body = await openWithRetry(() => fetchBody(storageFile.url, signal), {
+                        signal,
+                        attempts: retryAttempts,
+                        delayMs: retryDelayMs,
+                        describe: (e) => `Couldn't download storage file "${label}" (${errorMessage(e)}).`,
+                    });
+                    return {
+                        name: `files/${storageFile.locationId}`,
+                        input: countBytes(body),
+                        onWriting: () => {
+                            currentEntity = '';
+                            currentFile = label;
+                            tick();
+                        },
+                        onAdded: () => {
+                            filesCompleted++;
+                            tick();
+                        },
+                    };
                 };
             }
             else if (storageDone) {
@@ -203,11 +377,11 @@ async function downloadBackupArchive(opts) {
                 });
             }
         }
-        currentFile = '';
-        tick();
         if (storageError)
             throw storageError;
     })();
+    const prefetch = finitePositiveInt(opts.prefetch, DEFAULT_PREFETCH);
+    const entries = prefetchEntries(thunks, prefetch);
     const sinkWriter = opts.sink.getWriter();
     try {
         // Sink the archive encoder writes into: it tallies the encoded size for
@@ -230,11 +404,15 @@ async function downloadBackupArchive(opts) {
         });
         const writer = await createWriter(countingSink, signal);
         for await (const entry of entries) {
+            entry.onWriting();
             await writer.add(entry.name, entry.input, {
                 lastModDate: backup.backupAt,
             });
             entry.onAdded();
         }
+        currentEntity = '';
+        currentFile = '';
+        tick();
         // A caller abort that lands after the last entry lets the generator
         // finish cleanly; don't close and return a complete-looking archive.
         signal.throwIfAborted();