@gigamusic/checkout 4.8.0 → 4.9.0

package/src/zip-stream.ts

@@ -4,12 +4,69 @@ import { finished } from "node:stream/promises";
 import type { ReadableStream as NodeReadableStream } from "node:stream/web";
 import archiver from "archiver";
 import type { DownloadDeps, ZipEntryFailure } from "./types.js";
-import { resolveZipBundle } from "./zip.js";
+import { resolveZipBundle, type ZipFile } from "./zip.js";
+import { predictStoredZipLength } from "./zip-length.js";
 
 interface RouteContext {
   params: Promise<{ token: string }>;
 }
 
+/** How long the customer's browser may go without accepting a byte before we call the download abandoned. */
+const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
+/**
+ * Bytes the response may sit on ahead of the consumer. The output is
+ * demand-driven, so this is the whole of our buffering: nothing is pulled out
+ * of archiver — and therefore nothing is pulled out of R2 — until the
+ * customer's connection has taken what we already produced.
+ */
+const OUTPUT_HIGH_WATER_MARK_BYTES = 256 * 1024;
+/**
+ * High-water mark handed to archiver, overriding its 1 MiB default.
+ *
+ * That default is not one buffer: archiver passes its options straight down to
+ * `zip-stream`, so the `Archiver` transform and the `ZipArchiveOutputStream`
+ * beneath it each get 1 MiB on *both* their readable and writable sides — a
+ * measured ~4.6 MB resident per in-flight archive before the response has sent
+ * a byte. That is invisible on a healthy download and lethal on a stalled one:
+ * eight abandoned streams sharing a Fluid instance (which is exactly what the
+ * retry storm in production produced) hold ~37 MB of zip buffers on their own,
+ * on top of an open R2 socket and undici's own buffers each. 64 KiB per stage
+ * costs a few more event-loop turns and nothing measurable in throughput,
+ * since the network is the bottleneck either way.
+ */
+const ARCHIVER_HIGH_WATER_MARK_BYTES = 64 * 1024;
+/** Per-object timeout for the pre-flight size probe; a slow probe must not delay the archive. */
+const SIZE_PROBE_TIMEOUT_MS = 8_000;
+/** Probes run in parallel, but not unboundedly — this is TTFB the customer waits through. */
+const SIZE_PROBE_CONCURRENCY = 6;
+/**
+ * Above this many unsized entries, skip the probe entirely and stream without
+ * a `Content-Length`. A bundle that needs dozens of probes is one whose
+ * catalog rows are broken; the pre-flight cost isn't worth paying on every
+ * retry.
+ */
+const MAX_SIZE_PROBES = 32;
+
+interface ActiveStream {
+  startedAt: number;
+  supersede: () => void;
+}
+
+/**
+ * Zip streams currently in flight, keyed by download token.
+ *
+ * This is per-instance state and therefore *not* a global lock: two requests
+ * that land on different Vercel instances will not see each other. That's
+ * accepted deliberately. The failure this guards against — a customer whose
+ * download appears stuck clicking again, and again — reuses one instance,
+ * because Fluid compute packs concurrent requests for the same function onto
+ * the same instance. Catching the common case is what keeps eight zombie
+ * archives from stacking up and exhausting that instance's memory; a
+ * cross-instance guard would need shared state (Redis, or the DB) and is not
+ * worth the dependency for the remaining tail.
+ */
+const activeStreams = new Map<string, ActiveStream>();
+
 /**
  * Server-side bulk-download fallback. Mirrors `createDownloadZipHandler`'s
  * auth + file-list logic via the shared `resolveZipBundle()`, but streams
@@ -31,7 +88,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
@@ -40,13 +98,54 @@ 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.
  */
 export function createDownloadZipStreamHandler(
   deps: DownloadDeps,
 ): (req: NextRequest, ctx: RouteContext) => Promise<Response> {
   const { queries, storage } = deps;
+  const idleTimeoutMs = deps.zipStreamIdleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+  const contentLengthEnabled = deps.zipStreamContentLength !== false;
 
   return async (req: NextRequest, ctx: RouteContext): Promise<Response> => {
+    const requestStartedAt = Date.now();
     const { token } = await ctx.params;
     const url = new URL(req.url);
 
@@ -64,15 +163,68 @@ export function createDownloadZipStreamHandler(
 
     // `store: true` = no DEFLATE compression. MP3/WAV barely compress, and
     // the SW path serves uncompressed entries — staying consistent means
-    // identical byte counts across the two routes.
-    const archive = archiver("zip", { store: true });
+    // identical byte counts across the two routes. It's also what makes the
+    // archive's final size predictable; see `predictStoredZipLength`.
+    const archive = archiver("zip", {
+      store: true,
+      highWaterMark: ARCHIVER_HIGH_WATER_MARK_BYTES,
+    });
 
     archive.on("error", (err) => {
       console.error("[zip-stream] archiver error:", err);
     });
 
-    // Tear the pipeline down if the client disconnects mid-download.
-    req.signal.addEventListener("abort", () => archive.abort());
+    // Every storage fetch runs on our own signal rather than `req.signal`
+    // directly, so a disconnect, a supersede and the idle watchdog all have
+    // the same power to stop pulling bytes out of R2. `archive.abort()` alone
+    // doesn't: archiver kills its queue but never touches the source stream
+    // it's already draining.
+    const fetches = new AbortController();
+    let abandonedFor: string | null = null;
+    let currentSource: Transform | null = null;
+    let finalized = false;
+
+    /** Stop the whole pipeline — storage fetches, archiver, and the entry loop — recording why. */
+    const abandon = (reason: string) => {
+      if (abandonedFor) return;
+      abandonedFor = reason;
+      const err = new Error(`zip stream abandoned: ${reason}`);
+      fetches.abort(err);
+      currentSource?.destroy(err);
+      // `abort()` stops archiver accepting work; `destroy()` is what actually
+      // tears down the readable side, so a consumer still waiting on `pull`
+      // gets an error rather than a stream that never ends.
+      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: ActiveStream = {
+      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: ZipEntryFailure[] = [];
     /** Record one unusable entry and hand it to the consumer's reporter, never letting that reporter break the stream. */
@@ -85,6 +237,48 @@ export function createDownloadZipStreamHandler(
       }
     };
 
+    let sentBytes = () => 0;
+    let summarised = false;
+    /** One greppable line per request, so a truncated archive is visible in the logs rather than only in a support email. */
+    const summarise = (outcome: string) => {
+      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;
+
     // Serialise storage fetches: only open file N's socket after archiver
     // has fully consumed file N-1. The naive parallel approach (open every
     // socket up front, let archiver drain them in order) leaves the later
@@ -94,15 +288,44 @@ export function createDownloadZipStreamHandler(
     // to the per-file streaming time — and archiver is the serial
     // bottleneck anyway, so end-to-end throughput is unchanged.
     (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;
+        // Only a length that actually went out on the wire binds us: sizes
+        // resolved for an archive whose layout turned out unpredictable are
+        // just unused numbers, and that request keeps the placeholder policy.
+        const expectedSize = contentLength === null ? undefined : entrySizes?.[index];
+        /**
+         * Once a `Content-Length` is out on the wire the archive's byte count
+         * is a promise we can't renegotiate, so a placeholder (which has a
+         * different size) would itself produce the truncated download this
+         * handler exists to prevent. Fail the transfer instead: the browser
+         * flags it, the customer retries, and the operator gets a log line and
+         * an `onZipEntryFailure` call either way.
+         */
+        const failFatally = (detail: string, bytesReceived: number) => {
+          console.error(
+            `[zip-stream] entry ${file.fileName} failed after Content-Length was committed ` +
+              `(storageKey=${file.storageKey}, bytesReceived=${bytesReceived}, ` +
+              `expected=${expectedSize}): ${detail} — 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 url = await storage.getPresignedDownloadUrl(file.storageKey, {
             filename: baseName,
             contentType: file.contentType,
           });
-          const res = await fetch(url, { signal: req.signal });
+          const res = await fetch(url, { signal: fetches.signal });
           if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
           // DOM `ReadableStream` and Node's web `ReadableStream` are
           // runtime-compatible but typed separately — cast at the boundary.
@@ -120,6 +343,7 @@ export function createDownloadZipStreamHandler(
               cb(null, chunk);
             },
           });
+          currentSource = counter;
           // Forward upstream errors onto the counter so the `finished`
           // await rejects and the loop can append a _FAILED_ placeholder.
           body.on("error", (err) => counter.destroy(err));
@@ -131,8 +355,12 @@ export function createDownloadZipStreamHandler(
             // readable side (entry fully written to the zip queue).
             await finished(counter);
           } catch (err) {
-            if (req.signal.aborted) return;
+            if (abandonedFor) return;
             const detail = err instanceof Error ? err.message : String(err);
+            if (expectedSize !== undefined) {
+              failFatally(detail, bytesReceived);
+              return;
+            }
             console.error(
               `[zip-stream] body stream error for ${file.fileName} ` +
                 `(storageKey=${file.storageKey}, bytesReceived=${bytesReceived}): ${detail}`,
@@ -156,10 +384,26 @@ export function createDownloadZipStreamHandler(
                 appendErr,
               );
             }
+            continue;
+          }
+          // The declared length was computed from the catalog (or from a
+          // pre-flight probe); an object that turns out to be a different size
+          // means the promise on the wire is already wrong, so stop rather
+          // than ship a mismatched body.
+          if (expectedSize !== undefined && 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 !== undefined) {
+            failFatally(detail, 0);
+            return;
+          }
           console.warn(`[zip-stream] fetch failed for ${file.fileName}:`, detail);
           reportFailure({
             token,
@@ -173,26 +417,265 @@ export function createDownloadZipStreamHandler(
               `Try downloading the track individually from your order page.\n`,
             { 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");
+    });
+
+    const headers: Record<string, string> = {
+      "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 });
+  };
+}
+
+interface MeteredOutput {
+  body: ReadableStream<Uint8Array>;
+  bytesSent: () => number;
+}
+
+interface MeteredOutputHooks {
+  idleTimeoutMs: number;
+  /** The consumer stopped taking bytes for `idleTimeoutMs` — the download has been abandoned. */
+  onIdle: () => void;
+  /** The platform cancelled the response body (the usual shape of a client disconnect). */
+  onCancel: () => void;
+  onClose: () => void;
+  onError: () => void;
+}
+
+/**
+ * Wrap archiver's output in a strictly demand-driven `ReadableStream`.
+ *
+ * `Readable.toWeb()` — what this replaces — runs the Node stream in flowing
+ * mode and pauses it once the web stream's queue is over its high-water mark.
+ * That works, but it hands the platform's response writer an already-flowing
+ * source and gives us no handle on whether the customer is actually taking
+ * bytes. Pulling instead of pushing gives both: nothing leaves archiver until
+ * the consumer asks, so a slow customer's connection is what paces the R2
+ * fetch, and "the consumer has not asked in a while" becomes an observable
+ * event.
+ *
+ * That second part is what makes an abandoned download detectable at all.
+ * `req.signal` is supposed to fire on disconnect and does so locally, but the
+ * production incident this was written for shows requests running the full
+ * 300-second timeout after the customer had plainly given up — seven retries
+ * from one order in 78 minutes, each of the earlier ones still burning R2
+ * egress and heap. A consumer that has gone quiet for `idleTimeoutMs` is
+ * treated as gone, whatever `req.signal` believes.
+ *
+ * The watchdog only counts time in which *we* are the ones waiting: while a
+ * `pull` is outstanding the archive is the slow side (a large track can take
+ * far longer than the idle timeout to fetch from R2), and that must never be
+ * mistaken for an absent customer.
+ */
+function createMeteredOutput(source: Readable, hooks: MeteredOutputHooks): MeteredOutput {
+  let bytesSent = 0;
+  let lastHandoffAt = Date.now();
+  let awaitingConsumer = false;
+  let watchdog: ReturnType<typeof setInterval> | undefined;
+
+  const stopWatchdog = () => {
+    if (watchdog !== undefined) {
+      clearInterval(watchdog);
+      watchdog = undefined;
+    }
+  };
+
+  /** Resolve as soon as the archive has more bytes, has ended, or has failed. */
+  const waitForSource = () =>
+    new Promise<void>((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: unknown) => {
+        cleanup();
+        reject(err instanceof Error ? err : new Error(String(err)));
+      };
+      source.on("readable", onReadable);
+      source.on("end", onEnd);
+      // A destroy() with no error emits neither `end` nor `error`; without
+      // this the pull would wait forever on a stream that is already gone.
+      source.on("close", onEnd);
+      source.on("error", onError);
     });
 
-    return new Response(Readable.toWeb(archive) as ReadableStream<Uint8Array>, {
-      headers: {
-        "Content-Type": "application/zip",
-        "Content-Disposition": `attachment; filename="${resolution.zipName.replace(/"/g, "")}"`,
-        "Cache-Control": "no-store",
+  const body = new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        awaitingConsumer = false;
+        try {
+          for (;;) {
+            const chunk = source.read() as Buffer | null;
+            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 };
+}
+
+/**
+ * Exact byte length of every entry in the bundle, or `null` if even one is
+ * unknown — the caller must then skip `Content-Length` entirely rather than
+ * declare a number it can't keep.
+ *
+ * `track_files.fileSize` covers audio in the normal case, but the column is
+ * nullable (legacy rows store `0`) and cover art has no row at all, so the
+ * stragglers are measured directly against storage. The probe is a ranged GET
+ * for a single byte rather than a HEAD: presigned URLs are signed per HTTP
+ * method, so a `HEAD` against a GET signature is refused, while `Range` is an
+ * unsigned header and rides along fine. The `Content-Range` response carries
+ * the object's full length.
+ */
+async function resolveEntrySizes(
+  storage: DownloadDeps["storage"],
+  files: ZipFile[],
+  signal: AbortSignal,
+): Promise<number[] | null> {
+  const sizes = files.map((file) => file.byteSize);
+  const pending = sizes.flatMap((size, i) => (size === undefined ? [i] : []));
+  if (pending.length === 0) return sizes as number[];
+  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 === undefined) 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 as number[]);
+}
+
+/** Measure one storage object with a single-byte ranged GET, or `null` if its size can't be established. */
+async function probeObjectSize(
+  storage: DownloadDeps["storage"],
+  file: ZipFile,
+  signal: AbortSignal,
+): Promise<number | null> {
+  let res: Response;
+  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 {
+    // 206: the object's total length is the tail of `bytes 0-0/<total>`.
+    // 200: the range was ignored and `Content-Length` is the whole object.
+    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 === undefined ? 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(() => {});
+  }
 }

package/src/zip.ts

@@ -29,6 +29,21 @@ export interface ZipFile {
   storageKey: string;
   contentType: string;
   source?: ZipFileSource;
+  /**
+   * Exact byte length of the stored object, when the catalog knows it.
+   * `track_files.fileSize` is nullable (and legacy rows carry `0`), and cover
+   * art has no size row at all, so this is absent as often as not —
+   * `createDownloadZipStreamHandler` measures the stragglers itself before
+   * committing to a `Content-Length`.
+   */
+  byteSize?: number;
+}
+
+/** `track_files.fileSize` is nullable and legacy rows store `0`; only a positive integer is a real size. */
+function knownByteSize(fileSize: number | null | undefined): number | undefined {
+  return typeof fileSize === "number" && Number.isSafeInteger(fileSize) && fileSize > 0
+    ? fileSize
+    : undefined;
 }
 
 interface ZipManifest {
@@ -234,6 +249,7 @@ function resolveTrackList(
       storageKey: file.storageKey,
       contentType: audioContentType,
       source: { kind: "track", trackId: id, format },
+      byteSize: knownByteSize(file.fileSize),
     });
   }
   if (files.length === 0) {
@@ -277,6 +293,7 @@ function resolveSingleRelease(
         storageKey: file.storageKey,
         contentType: audioContentType,
         source: { kind: "track", trackId: track.id, format },
+        byteSize: knownByteSize(file.fileSize),
       };
     })
     .filter((f): f is ZipFile => f !== null);
@@ -321,6 +338,7 @@ function resolveWholeOrder(
           storageKey: file.storageKey,
           contentType: audioContentType,
           source: { kind: "track", trackId: track.id, format },
+          byteSize: knownByteSize(file.fileSize),
         });
       }
       if (entries.length > 0 && release.coverImageUrl) {
@@ -344,6 +362,7 @@ function resolveWholeOrder(
         storageKey: file.storageKey,
         contentType: audioContentType,
         source: { kind: "track", trackId: track.id, format },
+        byteSize: knownByteSize(file.fileSize),
       });
     }
   }