@gigamusic/checkout 4.8.1 → 4.9.1

package/README.md

@@ -66,6 +66,30 @@ export const GET = createDownloadZipStreamHandler({
 Failures are also logged individually plus an `n/total entries failed` summary
 line per request, so they're greppable without wiring anything up.
 
+### Truncated archives
+
+The server-side stream sends a real `Content-Length` whenever it can work out
+every entry's exact size — from `track_files.fileSize`, falling back to a
+ranged-GET probe for the nullable rows and for cover art. That matters because
+a chunked zip response that dies mid-body (function timeout, OOM) is saved by
+the browser as a *complete* file: valid audio bytes with no
+End-of-Central-Directory record, which macOS Archive Utility reports as
+"Error 79 – Inappropriate file type or format". With a length declared, the
+browser flags the download as failed instead.
+
+A declared length is a promise, so once it is out a failed entry can no longer
+become a `_FAILED_*.txt` placeholder — the transfer is torn down and reported
+instead. If your catalog's recorded sizes have drifted from what's in storage,
+`zipStreamContentLength: false` restores the old chunked behaviour while you
+repair the rows.
+
+Downloads whose consumer stops accepting bytes are treated as abandoned after
+`zipStreamIdleTimeoutMs` (default 30s) and released, and a second concurrent
+stream for the same token supersedes the first — a customer retrying a stuck
+download shouldn't leave the old one running until the function times out.
+Every request ends with a `[zip-stream] completed …` line carrying the entry
+count, bytes sent, bytes promised and duration.
+
 ## Bundles — discounted subsets of the catalog
 
 `catalogPurchase` is all-or-nothing. For a curated pack ("the remix EPs", "2024

package/dist/index.d.ts

@@ -201,6 +201,33 @@ interface DownloadDeps {
      * download that is otherwise still producing bytes.
      */
     onZipEntryFailure?: (failure: ZipEntryFailure) => void;
+    /**
+     * How long `createDownloadZipStreamHandler` lets the customer's connection
+     * go without accepting a byte before it treats the download as abandoned,
+     * tears the archive down and stops paying for R2 egress. Defaults to 30s.
+     *
+     * This exists because `req.signal` cannot be relied on to fire when a
+     * customer closes a bulk download on Vercel — abandoned streams were
+     * observed running the function's full `maxDuration` and stacking up on one
+     * instance until it ran out of memory. Raise it only if you serve customers
+     * slow enough to spend that long on a single 256 KB window; lower it to
+     * reclaim capacity faster.
+     */
+    zipStreamIdleTimeoutMs?: number;
+    /**
+     * Set `false` to make `createDownloadZipStreamHandler` stream without a
+     * `Content-Length`, as it did before the header was introduced.
+     *
+     * The header is what lets a browser notice that a zip arrived truncated
+     * instead of filing a corrupt archive as a finished download, so leaving it
+     * on is strongly preferred. The escape hatch is here for one scenario: the
+     * declared length is computed from `track_files.fileSize`, so a catalog
+     * whose recorded sizes have drifted from the objects in storage would fail
+     * every bulk download rather than silently shipping a mismatched body.
+     * Turning this off restores the old behaviour without a package downgrade
+     * while the rows are repaired. Defaults to `true`.
+     */
+    zipStreamContentLength?: boolean;
     /**
      * Optional artist-name prefix prepended to zip filenames — both the SW
      * manifest and the server-side stream output use it. Example: passing
@@ -412,7 +439,8 @@ interface RouteContext {
  * whole archive. Because that turns a broken purchase into an
  * apparently-successful download, every failure is reported through
  * `deps.onZipEntryFailure` and summarised in a single log line at the end of
- * the request.
+ * the request. The one exception is a failure that lands *after* a
+ * `Content-Length` has been promised — see below.
  *
  * Unlike the manifest path, this handler presigns each file *inside* the loop,
  * immediately before fetching it, so signature expiry can't bite. Its own
@@ -421,6 +449,44 @@ interface RouteContext {
  * (Vercel: 300s by default, up to 800s on Fluid compute). Multi-gigabyte
  * bundles need that raised in the consuming route — `export const maxDuration`
  * — or they'll be cut off mid-stream.
+ *
+ * ## Surviving a stream that dies mid-body
+ *
+ * A function that hits its timeout or its memory ceiling after the response
+ * headers are already out produces a *silent* truncation: the customer's
+ * browser sees a connection close on a chunked response and marks the download
+ * complete. The file is megabytes of perfectly good MP3 with no
+ * End-of-Central-Directory record, which macOS Archive Utility reports as the
+ * famously unhelpful "Error 79 – Inappropriate file type or format". Four
+ * things here exist to keep that from happening again:
+ *
+ *  1. **`Content-Length`.** Entries are stored uncompressed, so the archive's
+ *     byte count is predictable from the entry sizes (`predictStoredZipLength`).
+ *     Sizes come from `track_files.fileSize`, with a ranged-GET probe covering
+ *     the rows where it's null and the cover art that has no row at all. If
+ *     any size stays unknown, the header is omitted rather than guessed — a
+ *     wrong `Content-Length` is worse than none. Once the header is out, a
+ *     failed entry can no longer be papered over with a placeholder (the byte
+ *     count would no longer match), so the transfer is torn down instead: the
+ *     browser reports a failed download, which is the honest outcome.
+ *  2. **Demand-driven output, on small buffers.** The response body pulls from
+ *     archiver only when the customer's connection has drained what came
+ *     before, so a slow client throttles the R2 fetch rather than filling the
+ *     heap — and archiver's 1 MiB default high-water mark, which it silently
+ *     applies to four separate stream buffers, is cut to 64 KiB (see
+ *     `ARCHIVER_HIGH_WATER_MARK_BYTES`).
+ *  3. **An idle watchdog.** `req.signal` is the documented disconnect signal
+ *     but doesn't reliably fire on Vercel, so an abandoned download is instead
+ *     detected by the consumer going quiet (`zipStreamIdleTimeoutMs`, 30s by
+ *     default) and torn down within seconds rather than burning the full
+ *     `maxDuration` of egress and memory.
+ *  4. **One stream per token.** A customer retrying a stuck download would
+ *     otherwise stack zombie archives on a single instance; a second request
+ *     supersedes the first (see `activeStreams`).
+ *
+ * Every request ends with a one-line summary — outcome, entries, bytes sent
+ * versus bytes promised, duration — so a future truncation shows up in the
+ * logs instead of only in a customer's inbox.
  */
 declare function createDownloadZipStreamHandler(deps: DownloadDeps): (req: NextRequest, ctx: RouteContext) => Promise<Response>;
 

package/dist/index.js

@@ -7,6 +7,33 @@ import { Readable, Transform } from 'stream';
 import { finished } from 'stream/promises';
 import archiver from 'archiver';
 
+// src/checkout.ts
+
+// src/metadata-chunks.ts
+var STRIPE_METADATA_VALUE_LIMIT = 500;
+function chunkMetadataValue(key, value) {
+  const out = {};
+  for (let i = 0, offset = 0; offset < value.length || i === 0; i++) {
+    out[i === 0 ? key : `${key}_${i}`] = value.slice(
+      offset,
+      offset + STRIPE_METADATA_VALUE_LIMIT
+    );
+    offset += STRIPE_METADATA_VALUE_LIMIT;
+  }
+  return out;
+}
+function readChunkedMetadataValue(metadata, key) {
+  const head = metadata?.[key];
+  if (head === void 0 || head === null) return void 0;
+  let value = head;
+  for (let i = 1; ; i++) {
+    const part = metadata?.[`${key}_${i}`];
+    if (part === void 0 || part === null) break;
+    value += part;
+  }
+  return value;
+}
+
 // src/checkout.ts
 var STRIPE_MIN_CHARGE_CENTS = 50;
 var MANAGED_PAYMENTS_DISABLED = { enabled: false };
@@ -91,7 +118,7 @@ function createCheckoutHandler(deps) {
           metadata: {
             site,
             catalog_purchase: "true",
-            release_ids: JSON.stringify(releases.map((r) => r.id)),
+            ...chunkMetadataValue("release_ids", JSON.stringify(releases.map((r) => r.id))),
             track_ids: "[]"
           },
           managed_payments: MANAGED_PAYMENTS_DISABLED,
@@ -226,14 +253,16 @@ function createCheckoutHandler(deps) {
       const session = await stripe.checkout.sessions.create({
         mode: "payment",
         line_items: lineItems,
+        // Each value is spread across continuation keys past Stripe's 500-char
+        // cap; `fulfillCheckoutSession` reassembles them.
         metadata: {
           site,
-          release_ids: JSON.stringify(resolvedReleaseIds),
-          track_ids: JSON.stringify(resolvedTrackIds),
-          amounts: JSON.stringify(chargedAmounts),
+          ...chunkMetadataValue("release_ids", JSON.stringify(resolvedReleaseIds)),
+          ...chunkMetadataValue("track_ids", JSON.stringify(resolvedTrackIds)),
+          ...chunkMetadataValue("amounts", JSON.stringify(chargedAmounts)),
           // Ignored by fulfillment — bundles decompose into per-release order
           // items — but invaluable when supporting "what did I actually buy?".
-          ...bundleIds.length > 0 ? { bundle_ids: JSON.stringify(bundleIds) } : {}
+          ...bundleIds.length > 0 ? chunkMetadataValue("bundle_ids", JSON.stringify(bundleIds)) : {}
         },
         managed_payments: MANAGED_PAYMENTS_DISABLED,
         success_url: successUrl,
@@ -273,9 +302,11 @@ async function fulfillCheckoutSession(session, deps) {
   if (existing) {
     return { status: "already-recorded", order: existing };
   }
-  const releaseIds = safeJsonIdList(session.metadata?.release_ids);
-  const trackIds = safeJsonIdList(session.metadata?.track_ids);
-  const chargedAmounts = safeAmountMap(session.metadata?.amounts);
+  const releaseIds = safeJsonIdList(
+    readChunkedMetadataValue(session.metadata, "release_ids")
+  );
+  const trackIds = safeJsonIdList(readChunkedMetadataValue(session.metadata, "track_ids"));
+  const chargedAmounts = safeAmountMap(readChunkedMetadataValue(session.metadata, "amounts"));
   if (releaseIds.length === 0 && trackIds.length === 0) {
     return { status: "skipped", reason: "no-items" };
   }
@@ -515,6 +546,9 @@ async function handleCoverArt(deps, token, releaseIdRaw) {
 }
 
 // src/zip.ts
+function knownByteSize(fileSize) {
+  return typeof fileSize === "number" && Number.isSafeInteger(fileSize) && fileSize > 0 ? fileSize : void 0;
+}
 var ZIP_MANIFEST_EXPIRES_IN_SECONDS = 12 * 60 * 60;
 function applyZipNamePrefix(prefix, base) {
   const trimmed = prefix?.trim();
@@ -602,7 +636,8 @@ function resolveTrackList(order, trackIdsParam, format, audioContentType, fmt, z
       fileName: zipEntryPath(ctx.release?.name ?? null, file.fileName),
       storageKey: file.storageKey,
       contentType: audioContentType,
-      source: { kind: "track", trackId: id, format }
+      source: { kind: "track", trackId: id, format },
+      byteSize: knownByteSize(file.fileSize)
     });
   }
   if (files.length === 0) {
@@ -634,7 +669,8 @@ function resolveSingleRelease(order, releaseId, format, audioContentType, fmt, z
       fileName: zipEntryPath(null, file.fileName),
       storageKey: file.storageKey,
       contentType: audioContentType,
-      source: { kind: "track", trackId: track.id, format }
+      source: { kind: "track", trackId: track.id, format },
+      byteSize: knownByteSize(file.fileSize)
     };
   }).filter((f) => f !== null);
   if (files.length > 0 && release.coverImageUrl) {
@@ -667,7 +703,8 @@ function resolveWholeOrder(order, format, audioContentType, fmt, zipNamePrefix)
           fileName: zipEntryPath(release.name, file.fileName),
           storageKey: file.storageKey,
           contentType: audioContentType,
-          source: { kind: "track", trackId: track.id, format }
+          source: { kind: "track", trackId: track.id, format },
+          byteSize: knownByteSize(file.fileSize)
         });
       }
       if (entries.length > 0 && release.coverImageUrl) {
@@ -690,7 +727,8 @@ function resolveWholeOrder(order, format, audioContentType, fmt, zipNamePrefix)
         fileName: zipEntryPath(release?.name ?? null, file.fileName),
         storageKey: file.storageKey,
         contentType: audioContentType,
-        source: { kind: "track", trackId: track.id, format }
+        source: { kind: "track", trackId: track.id, format },
+        byteSize: knownByteSize(file.fileSize)
       });
     }
   }
@@ -795,9 +833,58 @@ function sourceUrl(downloadUrl, source) {
   }
   return url.toString();
 }
+
+// src/zip-length.ts
+var LOCAL_FILE_HEADER_BYTES = 30;
+var CENTRAL_FILE_HEADER_BYTES = 46;
+var DATA_DESCRIPTOR_BYTES = 16;
+var ZIP64_DATA_DESCRIPTOR_BYTES = 24;
+var ZIP64_EXTRA_FIELD_BYTES = 28;
+var END_OF_CENTRAL_DIRECTORY_BYTES = 22;
+var ZIP64_END_OF_CENTRAL_DIRECTORY_BYTES = 56 + 20;
+var ZIP64_MAGIC = 4294967295;
+var ZIP64_MAGIC_SHORT = 65535;
+function isPredictableZipEntryName(name) {
+  if (name.length === 0) return false;
+  if (name.includes("\\")) return false;
+  if (name.includes("//")) return false;
+  if (name.startsWith("/")) return false;
+  if (name.startsWith("../")) return false;
+  if (name.endsWith("/")) return false;
+  return !/^\w+:/.test(name);
+}
+function predictStoredZipLength(entries) {
+  if (entries.length === 0) return null;
+  let localBytes = 0;
+  let centralBytes = 0;
+  for (const entry of entries) {
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0) return null;
+    if (!isPredictableZipEntryName(entry.name)) return null;
+    const nameBytes = Buffer.byteLength(entry.name, "utf8");
+    const entryIsZip64 = entry.size > ZIP64_MAGIC;
+    const localHeaderOffset = localBytes;
+    localBytes += LOCAL_FILE_HEADER_BYTES + nameBytes + entry.size + (entryIsZip64 ? ZIP64_DATA_DESCRIPTOR_BYTES : DATA_DESCRIPTOR_BYTES);
+    centralBytes += CENTRAL_FILE_HEADER_BYTES + nameBytes + (entryIsZip64 || localHeaderOffset > ZIP64_MAGIC ? ZIP64_EXTRA_FIELD_BYTES : 0);
+  }
+  const archiveIsZip64 = entries.length > ZIP64_MAGIC_SHORT || localBytes > ZIP64_MAGIC || centralBytes > ZIP64_MAGIC;
+  const total = localBytes + centralBytes + (archiveIsZip64 ? ZIP64_END_OF_CENTRAL_DIRECTORY_BYTES : 0) + END_OF_CENTRAL_DIRECTORY_BYTES;
+  return Number.isSafeInteger(total) ? total : null;
+}
+
+// src/zip-stream.ts
+var DEFAULT_IDLE_TIMEOUT_MS = 3e4;
+var OUTPUT_HIGH_WATER_MARK_BYTES = 256 * 1024;
+var ARCHIVER_HIGH_WATER_MARK_BYTES = 64 * 1024;
+var SIZE_PROBE_TIMEOUT_MS = 8e3;
+var SIZE_PROBE_CONCURRENCY = 6;
+var MAX_SIZE_PROBES = 32;
+var activeStreams = /* @__PURE__ */ new Map();
 function createDownloadZipStreamHandler(deps) {
   const { queries, storage } = deps;
+  const idleTimeoutMs = deps.zipStreamIdleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+  const contentLengthEnabled = deps.zipStreamContentLength !== false;
   return async (req, ctx) => {
+    const requestStartedAt = Date.now();
     const { token } = await ctx.params;
     const url = new URL(req.url);
     const resolution = await resolveZipBundle({
@@ -811,11 +898,46 @@ function createDownloadZipStreamHandler(deps) {
     if (!resolution.ok) {
       return Response.json({ error: resolution.error }, { status: resolution.status });
     }
-    const archive = archiver("zip", { store: true });
+    const archive = archiver("zip", {
+      store: true,
+      highWaterMark: ARCHIVER_HIGH_WATER_MARK_BYTES
+    });
     archive.on("error", (err) => {
       console.error("[zip-stream] archiver error:", err);
     });
-    req.signal.addEventListener("abort", () => archive.abort());
+    const fetches = new AbortController();
+    let abandonedFor = null;
+    let currentSource = null;
+    let finalized = false;
+    const abandon = (reason) => {
+      if (abandonedFor) return;
+      abandonedFor = reason;
+      const err = new Error(`zip stream abandoned: ${reason}`);
+      fetches.abort(err);
+      currentSource?.destroy(err);
+      if (!finalized) archive.abort();
+      archive.destroy(err);
+    };
+    const previous = activeStreams.get(token);
+    if (previous) {
+      console.warn(
+        `[zip-stream] superseding an in-flight stream for token ${token} (started ${Date.now() - previous.startedAt}ms ago)`
+      );
+      previous.supersede();
+    }
+    const registration = {
+      startedAt: requestStartedAt,
+      supersede: () => abandon("superseded")
+    };
+    activeStreams.set(token, registration);
+    const deregister = () => {
+      if (activeStreams.get(token) === registration) activeStreams.delete(token);
+    };
+    req.signal.addEventListener("abort", () => abandon("client-disconnect"));
+    const entrySizes = contentLengthEnabled ? await resolveEntrySizes(storage, resolution.files, fetches.signal) : null;
+    const contentLength = entrySizes ? predictStoredZipLength(
+      resolution.files.map((file, i) => ({ name: file.fileName, size: entrySizes[i] }))
+    ) : null;
     const failures = [];
     const reportFailure = (failure) => {
       failures.push(failure);
@@ -825,16 +947,61 @@ function createDownloadZipStreamHandler(deps) {
         console.warn("[zip-stream] onZipEntryFailure threw:", err);
       }
     };
+    let sentBytes = () => 0;
+    let summarised = false;
+    const summarise = (outcome) => {
+      if (summarised) return;
+      summarised = true;
+      deregister();
+      const sent = sentBytes();
+      const line = `[zip-stream] ${outcome} token=${token} entries=${resolution.files.length} failed=${failures.length} bytesSent=${sent} contentLength=${contentLength ?? "none"} durationMs=${Date.now() - requestStartedAt}`;
+      if (outcome !== "completed" || failures.length > 0 || contentLength !== null && sent !== contentLength) {
+        console.error(line);
+      } else {
+        console.log(line);
+      }
+    };
+    const output = createMeteredOutput(archive, {
+      idleTimeoutMs,
+      onIdle: () => {
+        console.error(
+          `[zip-stream] no progress for ${idleTimeoutMs}ms on token ${token}; treating the download as abandoned and releasing the storage stream`
+        );
+        abandon("consumer-idle");
+        summarise("abandoned:consumer-idle");
+      },
+      onCancel: () => {
+        abandon("response-cancelled");
+        summarise("abandoned:response-cancelled");
+      },
+      onClose: () => summarise(abandonedFor ? `abandoned:${abandonedFor}` : "completed"),
+      onError: () => summarise(abandonedFor ? `abandoned:${abandonedFor}` : "errored")
+    });
+    sentBytes = output.bytesSent;
     (async () => {
-      for (const file of resolution.files) {
-        if (req.signal.aborted) return;
+      for (const [index, file] of resolution.files.entries()) {
+        if (abandonedFor) return;
         const baseName = file.fileName.split("/").pop() || file.fileName;
+        const expectedSize = contentLength === null ? void 0 : entrySizes?.[index];
+        const failFatally = (detail, bytesReceived) => {
+          console.error(
+            `[zip-stream] entry ${file.fileName} failed after Content-Length was committed (storageKey=${file.storageKey}, bytesReceived=${bytesReceived}, expected=${expectedSize}): ${detail} \u2014 aborting the response so the browser reports a failed download instead of a corrupt archive`
+          );
+          reportFailure({
+            token,
+            fileName: file.fileName,
+            storageKey: file.storageKey,
+            reason: detail,
+            bytesReceived
+          });
+          abandon("entry-failed-after-content-length");
+        };
         try {
           const url2 = await storage.getPresignedDownloadUrl(file.storageKey, {
             filename: baseName,
             contentType: file.contentType
           });
-          const res = await fetch(url2, { signal: req.signal });
+          const res = await fetch(url2, { signal: fetches.signal });
           if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
           const body = Readable.fromWeb(
             res.body
@@ -846,14 +1013,19 @@ function createDownloadZipStreamHandler(deps) {
               cb(null, chunk);
             }
           });
+          currentSource = counter;
           body.on("error", (err) => counter.destroy(err));
           body.pipe(counter);
           archive.append(counter, { name: file.fileName });
           try {
             await finished(counter);
           } catch (err) {
-            if (req.signal.aborted) return;
+            if (abandonedFor) return;
             const detail = err instanceof Error ? err.message : String(err);
+            if (expectedSize !== void 0) {
+              failFatally(detail, bytesReceived);
+              return;
+            }
             console.error(
               `[zip-stream] body stream error for ${file.fileName} (storageKey=${file.storageKey}, bytesReceived=${bytesReceived}): ${detail}`
             );
@@ -877,10 +1049,22 @@ Try downloading the track individually from your order page.
                 appendErr
               );
             }
+            continue;
+          }
+          if (expectedSize !== void 0 && bytesReceived !== expectedSize) {
+            failFatally(
+              `storage object is ${bytesReceived} bytes but the catalog says ${expectedSize}`,
+              bytesReceived
+            );
+            return;
           }
         } catch (err) {
-          if (req.signal.aborted) return;
+          if (abandonedFor) return;
           const detail = err instanceof Error ? err.message : String(err);
+          if (expectedSize !== void 0) {
+            failFatally(detail, 0);
+            return;
+          }
           console.warn(`[zip-stream] fetch failed for ${file.fileName}:`, detail);
           reportFailure({
             token,
@@ -895,26 +1079,179 @@ Try downloading the track individually from your order page.
 `,
             { name: `_FAILED_${baseName}.txt` }
           );
+        } finally {
+          currentSource = null;
         }
       }
+      if (abandonedFor) return;
       if (failures.length > 0) {
         console.error(
           `[zip-stream] ${failures.length}/${resolution.files.length} entries failed for token ${token}: ${failures.map((f) => f.fileName).join(", ")}`
         );
       }
+      finalized = true;
       await archive.finalize();
     })().catch((err) => {
       console.error("[zip-stream] pipeline error:", err);
-      archive.abort();
+      abandon("pipeline-error");
     });
-    return new Response(Readable.toWeb(archive), {
-      headers: {
-        "Content-Type": "application/zip",
-        "Content-Disposition": `attachment; filename="${resolution.zipName.replace(/"/g, "")}"`,
-        "Cache-Control": "no-store"
+    const headers = {
+      "Content-Type": "application/zip",
+      "Content-Disposition": `attachment; filename="${resolution.zipName.replace(/"/g, "")}"`,
+      "Cache-Control": "no-store"
+    };
+    if (contentLength !== null) headers["Content-Length"] = String(contentLength);
+    return new Response(output.body, { headers });
+  };
+}
+function createMeteredOutput(source, hooks) {
+  let bytesSent = 0;
+  let lastHandoffAt = Date.now();
+  let awaitingConsumer = false;
+  let watchdog;
+  const stopWatchdog = () => {
+    if (watchdog !== void 0) {
+      clearInterval(watchdog);
+      watchdog = void 0;
+    }
+  };
+  const waitForSource = () => new Promise((resolve, reject) => {
+    const cleanup = () => {
+      source.off("readable", onReadable);
+      source.off("end", onEnd);
+      source.off("close", onEnd);
+      source.off("error", onError);
+    };
+    const onReadable = () => {
+      cleanup();
+      resolve();
+    };
+    const onEnd = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    };
+    source.on("readable", onReadable);
+    source.on("end", onEnd);
+    source.on("close", onEnd);
+    source.on("error", onError);
+  });
+  const body = new ReadableStream(
+    {
+      async pull(controller) {
+        awaitingConsumer = false;
+        try {
+          for (; ; ) {
+            const chunk = source.read();
+            if (chunk !== null && chunk.length > 0) {
+              bytesSent += chunk.length;
+              lastHandoffAt = Date.now();
+              awaitingConsumer = true;
+              controller.enqueue(chunk);
+              return;
+            }
+            if (source.errored) throw source.errored;
+            if (source.readableEnded) {
+              stopWatchdog();
+              controller.close();
+              hooks.onClose();
+              return;
+            }
+            if (source.destroyed) {
+              throw new Error("zip stream ended before the archive was finalized");
+            }
+            await waitForSource();
+          }
+        } catch (err) {
+          stopWatchdog();
+          hooks.onError();
+          throw err;
+        }
+      },
+      cancel() {
+        stopWatchdog();
+        hooks.onCancel();
+      }
+    },
+    // Byte-counted so the cap is a real memory bound rather than a chunk
+    // count: at most this much archive output is ever queued ahead of the
+    // customer's connection.
+    new ByteLengthQueuingStrategy({ highWaterMark: OUTPUT_HIGH_WATER_MARK_BYTES })
+  );
+  watchdog = setInterval(
+    () => {
+      if (!awaitingConsumer) return;
+      if (Date.now() - lastHandoffAt < hooks.idleTimeoutMs) return;
+      stopWatchdog();
+      hooks.onIdle();
+    },
+    Math.max(100, Math.floor(hooks.idleTimeoutMs / 4))
+  );
+  watchdog.unref?.();
+  return { body, bytesSent: () => bytesSent };
+}
+async function resolveEntrySizes(storage, files, signal) {
+  const sizes = files.map((file) => file.byteSize);
+  const pending = sizes.flatMap((size, i) => size === void 0 ? [i] : []);
+  if (pending.length === 0) return sizes;
+  if (pending.length > MAX_SIZE_PROBES) {
+    console.warn(
+      `[zip-stream] ${pending.length} entries have no recorded size; streaming without a Content-Length rather than probing them all`
+    );
+    return null;
+  }
+  let cursor = 0;
+  let failed = false;
+  const workers = Array.from(
+    { length: Math.min(SIZE_PROBE_CONCURRENCY, pending.length) },
+    async () => {
+      while (!failed) {
+        const next = pending[cursor++];
+        if (next === void 0) return;
+        const size = await probeObjectSize(storage, files[next], signal);
+        if (size === null) {
+          failed = true;
+          return;
+        }
+        sizes[next] = size;
       }
+    }
+  );
+  await Promise.all(workers);
+  return failed ? null : sizes;
+}
+async function probeObjectSize(storage, file, signal) {
+  let res;
+  try {
+    const url = await storage.getPresignedDownloadUrl(file.storageKey, {
+      filename: file.fileName.split("/").pop() || file.fileName,
+      contentType: file.contentType
     });
-  };
+    res = await fetch(url, {
+      headers: { Range: "bytes=0-0" },
+      signal: AbortSignal.any([signal, AbortSignal.timeout(SIZE_PROBE_TIMEOUT_MS)])
+    });
+  } catch (err) {
+    console.warn(`[zip-stream] size probe failed for ${file.fileName}:`, err);
+    return null;
+  }
+  try {
+    const header = res.status === 206 ? /\/(\d+)$/.exec(res.headers.get("content-range")?.trim() ?? "")?.[1] : res.ok ? res.headers.get("content-length") : null;
+    const size = header === null || header === void 0 ? NaN : Number(header);
+    if (!Number.isSafeInteger(size) || size <= 0) {
+      console.warn(
+        `[zip-stream] size probe for ${file.fileName} returned HTTP ${res.status} without a usable length`
+      );
+      return null;
+    }
+    return size;
+  } finally {
+    await res.body?.cancel().catch(() => {
+    });
+  }
 }
 
 // src/sw-zip-fallback.ts