@gigamusic/checkout 4.7.0 → 4.8.0

package/src/filenames.ts

@@ -0,0 +1,23 @@
+/**
+ * Filename helpers shared by the single-file download route and the zip
+ * routes. They live here rather than in either module because `download.ts`
+ * now serves cover art (and so needs `coverArtFilename`) while `zip.ts` needs
+ * `cleanDownloadFilename` — importing across the two directly would be a cycle.
+ */
+
+/** Trim stray leading/trailing whitespace from a download filename while keeping its extension intact. */
+export function cleanDownloadFilename(name: string): string {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return name.trim();
+  return `${name.slice(0, dot).trim()}${name.slice(dot).trim()}`;
+}
+
+/** Strip path separators so a release/track name can't spawn unintended zip subfolders. */
+export function sanitizeSegment(name: string): string {
+  return name.replace(/[/\\]+/g, "-").trim();
+}
+
+/** Zip filename for a release's cover art. */
+export function coverArtFilename(releaseName: string): string {
+  return `${sanitizeSegment(releaseName)} - COVER ART.jpg`;
+}

package/src/index.ts

@@ -16,4 +16,5 @@ export type {
   PurchaseConfirmationDeps,
   ResolvedBundle,
   WebhookDeps,
+  ZipEntryFailure,
 } from "./types.js";

package/src/types.ts

@@ -168,9 +168,50 @@ export interface WebhookDeps extends FulfillSessionDeps, PurchaseConfirmationDep
   webhookSecret: string;
 }
 
+/**
+ * One entry `createDownloadZipStreamHandler` could not stream into the
+ * archive. The customer still gets a zip — the entry is replaced by a
+ * `_FAILED_<name>.txt` placeholder so one bad object doesn't corrupt the rest
+ * — which is exactly why the failure needs surfacing somewhere the operator
+ * will see it: from the outside, a half-empty archive looks like a successful
+ * download.
+ */
+export interface ZipEntryFailure {
+  /** Download token whose bundle was being streamed — identifies the order. */
+  token: string;
+  /** Path of the entry inside the archive, e.g. `"Album/track.wav"`. */
+  fileName: string;
+  storageKey: string;
+  /** Message from the failed storage fetch or mid-stream error. */
+  reason: string;
+  /** Bytes received before the failure; 0 when the fetch never got going. */
+  bytesReceived: number;
+}
+
 export interface DownloadDeps {
   queries: Queries;
   storage: StorageProvider;
+  /**
+   * Path of the single-file download route (`createDownloadHandler`) that
+   * `createDownloadZipHandler`'s manifest addresses its entries through, with
+   * `{token}` as the placeholder — e.g. `"/downloads/{token}/file"`.
+   *
+   * Defaults to the manifest route's own path minus its last segment, which
+   * resolves to `/download/[token]` under the layout `docs/setup.md`
+   * prescribes. Only set this if you mount the two routes such that the
+   * relationship doesn't hold.
+   */
+  downloadPath?: string;
+  /**
+   * Called by `createDownloadZipStreamHandler` once per entry it fails to
+   * stream, so a broken bulk download can raise an alert instead of silently
+   * shipping a zip full of `_FAILED_*.txt` placeholders. Failures are also
+   * logged, with a per-request summary line carrying the failed/total count.
+   *
+   * Errors thrown here are swallowed — reporting must never take down a
+   * download that is otherwise still producing bytes.
+   */
+  onZipEntryFailure?: (failure: ZipEntryFailure) => void;
   /**
    * 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-stream.ts

@@ -3,7 +3,7 @@ import { Readable, Transform } from "node:stream";
 import { finished } from "node:stream/promises";
 import type { ReadableStream as NodeReadableStream } from "node:stream/web";
 import archiver from "archiver";
-import type { DownloadDeps } from "./types.js";
+import type { DownloadDeps, ZipEntryFailure } from "./types.js";
 import { resolveZipBundle } from "./zip.js";
 
 interface RouteContext {
@@ -28,7 +28,18 @@ interface RouteContext {
  *
  * Per-file failure policy matches the SW: any failed storage fetch becomes
  * a `_FAILED_<name>.txt` placeholder so one bad object doesn't taint the
- * whole archive.
+ * 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.
+ *
+ * Unlike the manifest path, this handler presigns each file *inside* the loop,
+ * immediately before fetching it, so signature expiry can't bite. Its own
+ * ceiling is the platform's function timeout: audio bytes proxy through the
+ * function, so the whole archive has to be produced within `maxDuration`
+ * (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.
  */
 export function createDownloadZipStreamHandler(
   deps: DownloadDeps,
@@ -63,6 +74,17 @@ export function createDownloadZipStreamHandler(
     // Tear the pipeline down if the client disconnects mid-download.
     req.signal.addEventListener("abort", () => archive.abort());
 
+    const failures: ZipEntryFailure[] = [];
+    /** Record one unusable entry and hand it to the consumer's reporter, never letting that reporter break the stream. */
+    const reportFailure = (failure: ZipEntryFailure) => {
+      failures.push(failure);
+      try {
+        deps.onZipEntryFailure?.(failure);
+      } catch (err) {
+        console.warn("[zip-stream] onZipEntryFailure threw:", err);
+      }
+    };
+
     // 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
@@ -115,6 +137,13 @@ export function createDownloadZipStreamHandler(
               `[zip-stream] body stream error for ${file.fileName} ` +
                 `(storageKey=${file.storageKey}, bytesReceived=${bytesReceived}): ${detail}`,
             );
+            reportFailure({
+              token,
+              fileName: file.fileName,
+              storageKey: file.storageKey,
+              reason: detail,
+              bytesReceived,
+            });
             try {
               archive.append(
                 `Streaming "${file.fileName}" from storage failed after ${bytesReceived} bytes: ${detail}.\n` +
@@ -132,6 +161,13 @@ export function createDownloadZipStreamHandler(
           if (req.signal.aborted) return;
           const detail = err instanceof Error ? err.message : String(err);
           console.warn(`[zip-stream] fetch failed for ${file.fileName}:`, detail);
+          reportFailure({
+            token,
+            fileName: file.fileName,
+            storageKey: file.storageKey,
+            reason: detail,
+            bytesReceived: 0,
+          });
           archive.append(
             `Failed to download "${file.fileName}" from storage: ${detail}.\n` +
               `Try downloading the track individually from your order page.\n`,
@@ -139,6 +175,12 @@ export function createDownloadZipStreamHandler(
           );
         }
       }
+      if (failures.length > 0) {
+        console.error(
+          `[zip-stream] ${failures.length}/${resolution.files.length} entries failed ` +
+            `for token ${token}: ${failures.map((f) => f.fileName).join(", ")}`,
+        );
+      }
       await archive.finalize();
     })().catch((err) => {
       console.error("[zip-stream] pipeline error:", err);

package/src/zip.ts

@@ -7,17 +7,28 @@ import type {
 } from "@gigamusic/db";
 import type { StorageProvider } from "@gigamusic/storage";
 import type { DownloadDeps } from "./types.js";
-import { cleanDownloadFilename } from "./download.js";
+import { cleanDownloadFilename, coverArtFilename, sanitizeSegment } from "./filenames.js";
 
 interface RouteContext {
   params: Promise<{ token: string }>;
 }
 
+/**
+ * How a zip entry can be re-addressed through `createDownloadHandler`, so the
+ * manifest can hand the service worker a same-origin URL that mints the R2
+ * signature at fetch time instead of a signature minted up front. Entries
+ * without a source fall back to a presigned URL (see `ZIP_MANIFEST_EXPIRES_IN_SECONDS`).
+ */
+export type ZipFileSource =
+  | { kind: "track"; trackId: number; format: string }
+  | { kind: "cover"; releaseId: number };
+
 /** A file destined for the zip, paired with the storage object it streams from. */
 export interface ZipFile {
   fileName: string;
   storageKey: string;
   contentType: string;
+  source?: ZipFileSource;
 }
 
 interface ZipManifest {
@@ -25,6 +36,26 @@ interface ZipManifest {
   files: { fileName: string; url: string }[];
 }
 
+/**
+ * Expiry for the presigned URLs the manifest falls back to when an entry has
+ * no `source` to re-address it by.
+ *
+ * The storage default is 5 minutes, measured from when the manifest is built —
+ * which is fatally short here. The service worker fetches manifest entries
+ * strictly sequentially (a zip is a sequential format; `client-zip` drains one
+ * body before opening the next), so a multi-gigabyte bundle is still working
+ * through the list long after minute five. Worse, R2's signature-failure
+ * responses carry no CORS headers, so the cross-origin fetch rejects with an
+ * opaque `NetworkError` rather than a readable 403 — and the SW's per-file
+ * catch turns each one into a `_FAILED_*.txt` placeholder, so the customer
+ * gets a plausible-looking zip with most of their music missing.
+ *
+ * 12 hours comfortably outlasts any realistic download. These URLs are
+ * shareable for that window, which is a small leak: the order link that
+ * produced them grants the same files and doesn't expire at all.
+ */
+export const ZIP_MANIFEST_EXPIRES_IN_SECONDS = 12 * 60 * 60;
+
 /**
  * Discriminated result of `resolveZipBundle` — the SW-manifest handler and
  * the server-side streaming handler both call this so they produce
@@ -91,9 +122,21 @@ export async function resolveZipBundle(args: ResolveZipArgs): Promise<ResolveZip
 /**
  * Build the GET handler for the zip-manifest endpoint. Returns the JSON
  * manifest the consumer-shipped service worker (`public/sw-zip.js`)
- * consumes — the SW pipes presigned R2 URLs through
- * `client-zip` and streams the archive straight from R2 to the browser, with
- * the Vercel function never touching audio bytes.
+ * consumes — the SW pipes each URL through `client-zip` and streams the
+ * archive straight from storage to the browser, with the serverless function
+ * never touching audio bytes.
+ *
+ * Manifest URLs point back at `createDownloadHandler` on this same origin
+ * rather than directly at presigned R2 URLs. That route 302s to a *freshly*
+ * signed URL, so the signature is minted at the moment the SW reaches that
+ * entry — however many hours into the archive that is. Signing everything up
+ * front meant every URL in a multi-gigabyte bundle died 5 minutes after the
+ * click; see `ZIP_MANIFEST_EXPIRES_IN_SECONDS`. The redirect adds one cheap
+ * function invocation per file and gives failures a server-side trace they
+ * never had while the SW talked straight to R2.
+ *
+ * The manifest shape (`{ zipName, files: [{ fileName, url }] }`) is unchanged,
+ * so an already-deployed service worker keeps working without modification.
  *
  * Query-param branches:
  *  - `trackIds` set → curated track list, flat layout
@@ -122,7 +165,11 @@ export function createDownloadZipHandler(
 
     const manifest: ZipManifest = {
       zipName: resolution.zipName,
-      files: await presignZipFiles(storage, resolution.files),
+      files: await buildManifestFiles(
+        storage,
+        resolution.files,
+        downloadRouteUrl(url, token, deps.downloadPath),
+      ),
     };
     return Response.json(manifest);
   };
@@ -186,6 +233,7 @@ function resolveTrackList(
       fileName: zipEntryPath(ctx.release?.name ?? null, file.fileName),
       storageKey: file.storageKey,
       contentType: audioContentType,
+      source: { kind: "track", trackId: id, format },
     });
   }
   if (files.length === 0) {
@@ -221,19 +269,20 @@ function resolveSingleRelease(
   }
 
   const files: ZipFile[] = release.tracks
-    .map((track) => {
+    .map((track): ZipFile | null => {
       const file = track.files.find((f) => f.format === format);
       if (!file) return null;
       return {
         fileName: zipEntryPath(null, file.fileName),
         storageKey: file.storageKey,
         contentType: audioContentType,
-      } satisfies ZipFile;
+        source: { kind: "track", trackId: track.id, format },
+      };
     })
     .filter((f): f is ZipFile => f !== null);
 
   if (files.length > 0 && release.coverImageUrl) {
-    files.push(...coverArtEntries(release.name, release.coverImageUrl, "", files));
+    files.push(...coverArtEntries(release, release.coverImageUrl, "", files));
   }
 
   if (files.length === 0) {
@@ -271,12 +320,13 @@ function resolveWholeOrder(
           fileName: zipEntryPath(release.name, file.fileName),
           storageKey: file.storageKey,
           contentType: audioContentType,
+          source: { kind: "track", trackId: track.id, format },
         });
       }
       if (entries.length > 0 && release.coverImageUrl) {
         entries.push(
           ...coverArtEntries(
-            release.name,
+            release,
             release.coverImageUrl,
             `${sanitizeSegment(release.name)}/`,
             entries,
@@ -293,6 +343,7 @@ function resolveWholeOrder(
         fileName: zipEntryPath(release?.name ?? null, file.fileName),
         storageKey: file.storageKey,
         contentType: audioContentType,
+        source: { kind: "track", trackId: track.id, format },
       });
     }
   }
@@ -339,11 +390,6 @@ function trackOwnership(order: OrderWithItems) {
   };
 }
 
-/** Strip path separators so a release/track name can't spawn unintended zip subfolders. */
-export function sanitizeSegment(name: string): string {
-  return name.replace(/[/\\]+/g, "-").trim();
-}
-
 /**
  * Detects extended-mix tracks from their filename. The catalog marks them
  * inconsistently ("Extended", "(Extended)", "[EXTENDED MIX]"), so a loose
@@ -368,51 +414,107 @@ export function zipEntryPath(releaseName: string | null, fileName: string): stri
   return segments.join("/");
 }
 
-/** Zip filename for a release's cover art. */
-export function coverArtFilename(releaseName: string): string {
-  return `${sanitizeSegment(releaseName)} - COVER ART.jpg`;
-}
-
 /**
  * Cover-art zip entries for a release: the artwork alongside the tracks, plus
  * a duplicate inside the `Extended/` subfolder when any track entry uses one.
  * `folder` is the release's `Name/` prefix for multi-release zips, or "" for
  * flat single-release zips.
+ *
+ * Both entries carry the same `cover` source: cover art isn't track-keyed, so
+ * `createDownloadHandler` addresses it by release id instead.
  */
 export function coverArtEntries(
-  releaseName: string,
+  release: Pick<ReleaseWithTracks, "id" | "name">,
   coverImageUrl: string,
   folder: string,
   trackEntries: ZipFile[],
 ): ZipFile[] {
-  const file = coverArtFilename(releaseName);
+  const file = coverArtFilename(release.name);
+  const source: ZipFileSource = { kind: "cover", releaseId: release.id };
   const entries: ZipFile[] = [
-    { fileName: `${folder}${file}`, storageKey: coverImageUrl, contentType: "image/jpeg" },
+    {
+      fileName: `${folder}${file}`,
+      storageKey: coverImageUrl,
+      contentType: "image/jpeg",
+      source,
+    },
   ];
   if (trackEntries.some((e) => e.fileName.split("/").includes("Extended"))) {
     entries.push({
       fileName: `${folder}Extended/${file}`,
       storageKey: coverImageUrl,
       contentType: "image/jpeg",
+      source,
     });
   }
   return entries;
 }
 
-/** Presign every zip entry into the `{ fileName, url }` manifest shape the service worker consumes. */
-async function presignZipFiles(
+export { coverArtFilename, sanitizeSegment };
+
+/**
+ * Locate the single-file download route (`createDownloadHandler`) relative to
+ * the manifest route that's currently serving this request.
+ *
+ * `docs/setup.md` mounts the manifest at `download/[token]/zip`, one segment
+ * below `download/[token]`, so dropping the last path segment finds it. Doing
+ * it this way rather than hardcoding `/download/{token}` keeps working under a
+ * Next `basePath` or any other prefix; `downloadPath` is the escape hatch for
+ * consumers who mount the two routes somewhere else entirely.
+ */
+export function downloadRouteUrl(
+  manifestUrl: URL,
+  token: string,
+  downloadPath: string | undefined,
+): URL {
+  if (downloadPath) {
+    return new URL(downloadPath.replace("{token}", encodeURIComponent(token)), manifestUrl);
+  }
+  const segments = manifestUrl.pathname.replace(/\/+$/, "").split("/");
+  segments.pop();
+  const url = new URL(manifestUrl.toString());
+  url.search = "";
+  url.hash = "";
+  url.pathname = segments.join("/") || "/";
+  return url;
+}
+
+/**
+ * Turn resolved zip entries into the `{ fileName, url }` manifest shape the
+ * service worker consumes. Entries carrying a `source` become same-origin
+ * `downloadUrl` links signed at fetch time; anything else falls back to a
+ * long-lived presigned URL.
+ */
+export async function buildManifestFiles(
   storage: StorageProvider,
   files: ZipFile[],
+  downloadUrl: URL,
 ): Promise<ZipManifest["files"]> {
   return Promise.all(
-    files.map(async (t) => ({
-      fileName: t.fileName,
-      url: await storage.getPresignedDownloadUrl(t.storageKey, {
-        filename: t.fileName.split("/").pop() ?? t.fileName,
-        contentType: t.contentType,
-      }),
+    files.map(async (file) => ({
+      fileName: file.fileName,
+      url: file.source
+        ? sourceUrl(downloadUrl, file.source)
+        : await storage.getPresignedDownloadUrl(file.storageKey, {
+            filename: file.fileName.split("/").pop() ?? file.fileName,
+            contentType: file.contentType,
+            expiresInSeconds: ZIP_MANIFEST_EXPIRES_IN_SECONDS,
+          }),
     })),
   );
 }
 
+/** Address one zip entry through `createDownloadHandler`'s query-param contract. */
+function sourceUrl(downloadUrl: URL, source: ZipFileSource): string {
+  const url = new URL(downloadUrl.toString());
+  if (source.kind === "track") {
+    url.searchParams.set("trackId", String(source.trackId));
+    url.searchParams.set("format", source.format);
+  } else {
+    url.searchParams.set("asset", "cover");
+    url.searchParams.set("releaseId", String(source.releaseId));
+  }
+  return url.toString();
+}
+
 export type { Queries };