@gigamusic/checkout 4.8.1 → 4.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigamusic/checkout",
-  "version": "4.8.1",
+  "version": "4.9.1",
   "description": "Next.js route-handler factories for Stripe Checkout, Stripe webhooks, and presigned-URL downloads. Stripe is hard-wired; all secrets enter as factory args.",
   "license": "MIT",
   "repository": {
@@ -31,9 +31,9 @@
     "archiver": "^7.0.1",
     "stripe": "^22.0.0",
     "@gigamusic/core": "4.2.0",
-    "@gigamusic/storage": "3.0.0",
-    "@gigamusic/db": "4.8.0",
-    "@gigamusic/email": "4.2.0"
+    "@gigamusic/db": "4.9.0",
+    "@gigamusic/email": "4.2.0",
+    "@gigamusic/storage": "3.0.0"
   },
   "peerDependencies": {
     "next": ">=15"

package/src/checkout.ts

@@ -2,6 +2,7 @@ import type { NextRequest } from "next/server";
 import Stripe from "stripe";
 import type { ReleaseWithTracks, TrackWithFiles } from "@gigamusic/db";
 import type { CheckoutCartItem, CheckoutDeps } from "./types.js";
+import { chunkMetadataValue } from "./metadata-chunks.js";
 
 /**
  * Stripe rejects card charges below 50 cents (USD). A pay-what-you-want
@@ -182,7 +183,7 @@ export function createCheckoutHandler(
           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,
@@ -395,14 +396,18 @@ export function createCheckoutHandler(
       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,

package/src/fulfill.ts

@@ -8,6 +8,7 @@ import {
 } from "@gigamusic/db";
 import { renderPurchaseConfirmation } from "@gigamusic/email";
 import type { FulfillSessionDeps, PurchaseConfirmationDeps } from "./types.js";
+import { readChunkedMetadataValue } from "./metadata-chunks.js";
 
 export type FulfillSessionResult =
   /** This call wrote the order row. The caller owns sending the confirmation email. */
@@ -89,12 +90,14 @@ export async function fulfillCheckoutSession(
     return { status: "already-recorded", order: existing };
   }
 
-  const releaseIds = safeJsonIdList(session.metadata?.release_ids);
-  const trackIds = safeJsonIdList(session.metadata?.track_ids);
+  const releaseIds = safeJsonIdList(
+    readChunkedMetadataValue(session.metadata, "release_ids"),
+  );
+  const trackIds = safeJsonIdList(readChunkedMetadataValue(session.metadata, "track_ids"));
   // Per-line amounts the customer actually paid, keyed `r<id>` / `t<id>`,
   // stamped by `createCheckoutHandler`. Absent on pre-upgrade sessions and on
   // catalog purchases — those fall back to the catalog price below.
-  const chargedAmounts = safeAmountMap(session.metadata?.amounts);
+  const chargedAmounts = safeAmountMap(readChunkedMetadataValue(session.metadata, "amounts"));
 
   if (releaseIds.length === 0 && trackIds.length === 0) {
     return { status: "skipped", reason: "no-items" };

package/src/metadata-chunks.ts

@@ -0,0 +1,45 @@
+/**
+ * Stripe caps every metadata value at 500 characters (and a session at 50
+ * keys). The cart's JSON id lists and per-line `amounts` map are unbounded —
+ * a 50-track cart already pushes `amounts` past the cap and Stripe refuses to
+ * create the session — so long values are spread across numbered
+ * continuation keys and stitched back together at fulfillment.
+ */
+const STRIPE_METADATA_VALUE_LIMIT = 500;
+
+/**
+ * Spread `value` over `key`, `key_1`, `key_2`, … so no single value exceeds
+ * Stripe's limit. Values that already fit land under the bare `key` alone,
+ * so short carts produce exactly the metadata they always have.
+ */
+export function chunkMetadataValue(key: string, value: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  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;
+}
+
+/**
+ * Inverse of `chunkMetadataValue`: read `key` and every consecutive
+ * `key_<n>` continuation. Returns `undefined` when the bare key is absent, so
+ * callers treat pre-upgrade sessions exactly as before.
+ */
+export function readChunkedMetadataValue(
+  metadata: Record<string, string> | null | undefined,
+  key: string,
+): string | undefined {
+  const head = metadata?.[key];
+  if (head === undefined || head === null) return undefined;
+  let value = head;
+  for (let i = 1; ; i++) {
+    const part = metadata?.[`${key}_${i}`];
+    if (part === undefined || part === null) break;
+    value += part;
+  }
+  return value;
+}

package/src/types.ts

@@ -212,6 +212,33 @@ export 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

package/src/zip-length.ts

@@ -0,0 +1,128 @@
+/**
+ * Byte-exact size prediction for the archives `createDownloadZipStreamHandler`
+ * produces, so that route can send a real `Content-Length`.
+ *
+ * Why this matters: without `Content-Length` the response is chunked, and a
+ * function that dies mid-body (timeout, OOM) looks *complete* to the browser.
+ * The customer ends up with a file full of valid MP3 bytes and no
+ * End-of-Central-Directory record — macOS Archive Utility calls that
+ * "Error 79 – Inappropriate file type or format". Declaring the length up
+ * front turns that silent corruption into a download the browser itself flags
+ * as failed.
+ *
+ * The numbers below are not guesses about the zip spec in general; they are
+ * the exact byte counts `compress-commons@6`'s `ZipArchiveOutputStream` emits
+ * for the specific shape of archive this handler builds — every entry `store`d
+ * (no DEFLATE) and appended from a *stream*, which is what forces a data
+ * descriptor after each entry's payload. A buffer-sourced entry has a
+ * different layout (real sizes in the local header, no data descriptor), which
+ * is one reason the stream handler abandons its `Content-Length` the moment it
+ * has to substitute a `_FAILED_*.txt` placeholder.
+ */
+
+/** signature + version + flags + method + mtime + crc + csize + size + name len + extra len */
+const LOCAL_FILE_HEADER_BYTES = 30;
+/** LFH fields + version made by + comment len + disk + attrs + LFH offset */
+const CENTRAL_FILE_HEADER_BYTES = 46;
+/** signature + crc + csize + size, all 32-bit. */
+const DATA_DESCRIPTOR_BYTES = 16;
+/** Same, with 64-bit sizes — used once an entry itself crosses 4 GiB. */
+const ZIP64_DATA_DESCRIPTOR_BYTES = 24;
+/** header id + payload len + size + csize + LFH offset (three 64-bit fields). */
+const ZIP64_EXTRA_FIELD_BYTES = 28;
+/** signature + disks + counts + CD size + CD offset + comment len, comment empty. */
+const END_OF_CENTRAL_DIRECTORY_BYTES = 22;
+/** The zip64 EOCD record plus its locator, written as a pair or not at all. */
+const ZIP64_END_OF_CENTRAL_DIRECTORY_BYTES = 56 + 20;
+
+/** Largest value a 32-bit zip field can hold; anything above forces zip64 encoding. */
+const ZIP64_MAGIC = 0xffffffff;
+/** Largest entry count the classic 16-bit EOCD record can express. */
+const ZIP64_MAGIC_SHORT = 0xffff;
+
+/** One entry as it will be appended: the in-archive path and the payload's exact byte count. */
+export interface PredictedZipEntry {
+  name: string;
+  size: number;
+}
+
+/**
+ * Reject any entry name whose bytes archiver would rewrite.
+ *
+ * `archiver` runs every entry name through `sanitizePath` (collapse separator
+ * runs, `\` → `/`, drop a `scheme:` prefix, drop leading `/` and `../`) before
+ * writing it, and the name's byte length lands in three separate headers. If
+ * our prediction is computed from a name archiver then shortens, the declared
+ * `Content-Length` is wrong — which is worse than sending none at all. Rather
+ * than reimplementing that normalisation and hoping the two stay in step, we
+ * only predict for names that are already fixed points of it.
+ */
+export function isPredictableZipEntryName(name: string): boolean {
+  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);
+}
+
+/**
+ * Exact byte length of the stored, stream-appended zip built from `entries`,
+ * or `null` when the layout can't be pinned down — an unusable entry name, a
+ * non-integer size, or a total large enough to lose precision as a JS number.
+ * Callers must treat `null` as "omit the header and fall back to chunked".
+ *
+ * Both zip64 escalations are modelled, because either one silently changes the
+ * byte count: an individual entry past 4 GiB widens its data descriptor and
+ * gains a central-directory extra field, and an archive whose central
+ * directory starts (or ends up) past 4 GiB — or that holds more than 65535
+ * entries — gains a zip64 EOCD record and locator ahead of the classic EOCD.
+ */
+export function predictStoredZipLength(entries: PredictedZipEntry[]): number | null {
+  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;
+    // The entry's own local-header offset, captured before this entry moves it.
+    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;
+}
+
+/**
+ * Byte cost of the zip64 EOCD record + locator pair, exported so the test
+ * suite can assert it against a real `forceZip64` archive — the one zip64
+ * branch that can be exercised without a multi-gigabyte fixture.
+ */
+export const ZIP64_TRAILER_BYTES = ZIP64_END_OF_CENTRAL_DIRECTORY_BYTES;