gerbeur/api/remote/bandcamp-streams.ts

/**
 * Resolves a Bandcamp page to its streamable tracks, at play time.
 *
 * Bandcamp's signed stream URLs expire 24h after the page fetch, so they can
 * never be baked into `rich_content` at dump-creation time the way `embedUrl`
 * is. This service is the play-time counterpart: the frontend asks for a page,
 * gets a whole tracklist back, and plays the mp3s directly from bcbits.
 *
 * @module
 */

import { APIErrorCode } from "../../shared/api.ts";
import { APIException } from "../lib/api-exception.ts";
import { fetchWithTimeout, isValidHttpUrl, readTextCapped } from "./fetch.ts";
import { BANDCAMP_HOST_RE, parseTralbum } from "./bandcamp-tralbum.ts";
import type { Tralbum } from "../../shared/player.ts";

/**
 * How long a resolved page is cached: comfortably inside the 24h signature
 * life, so a cache hit is never a URL that is about to expire mid-listen.
 */
const TTL_MS = 12 * 60 * 60 * 1000;
/** The most pages cached; the oldest write goes first. */
const MAX_ENTRIES = 200;

/** Resolved pages, by {@link cacheKey}. */
const cache = new Map<string, Tralbum>();

/**
 * Returns the cache key of `url`: a page is the same page regardless of query,
 * fragment or case.
 */
function cacheKey(url: string): string {
  try {
    const u = new URL(url);
    return `${u.protocol}//${u.hostname.toLowerCase()}${
      u.pathname.replace(/\/+$/, "")
    }`;
  } catch {
    return url;
  }
}

function readCache(key: string): Tralbum | null {
  const hit = cache.get(key);
  if (!hit) return null;
  if (Date.now() - hit.resolvedAt > TTL_MS) {
    cache.delete(key);
    return null;
  }
  return hit;
}

function writeCache(key: string, value: Tralbum): void {
  // Map preserves insertion order, so the first key is the oldest write.
  if (cache.size >= MAX_ENTRIES) {
    const oldest = cache.keys().next().value;
    if (oldest !== undefined) cache.delete(oldest);
  }
  cache.set(key, value);
}

/**
 * Fetches a Bandcamp page and returns its tracklist, cached.
 *
 * `force` bypasses the cache — used by the client's re-resolve path, so a
 * cached entry whose URLs have started 403ing can't keep being handed back.
 *
 * @throws {APIException} 400 when `pageUrl` isn't a public bandcamp.com URL,
 * 502 when Bandcamp can't be reached or doesn't answer with a page, 404 when
 * the page has nothing streamable.
 */
export async function resolveBandcamp(
  pageUrl: string,
  { force = false }: { force?: boolean } = {},
): Promise<Tralbum> {
  if (!isValidHttpUrl(pageUrl)) {
    throw new APIException(
      APIErrorCode.VALIDATION_ERROR,
      400,
      "Invalid URL",
    );
  }

  let hostname: string;
  try {
    hostname = new URL(pageUrl).hostname;
  } catch {
    throw new APIException(APIErrorCode.VALIDATION_ERROR, 400, "Invalid URL");
  }
  if (!BANDCAMP_HOST_RE.test(hostname)) {
    throw new APIException(
      APIErrorCode.VALIDATION_ERROR,
      400,
      "Not a Bandcamp URL",
    );
  }

  const key = cacheKey(pageUrl);
  if (!force) {
    const hit = readCache(key);
    if (hit) return hit;
  }

  let res: Response;
  try {
    res = await fetchWithTimeout(pageUrl, 8000);
  } catch {
    throw new APIException(
      APIErrorCode.SERVER_ERROR,
      502,
      "Could not reach Bandcamp",
    );
  }
  // Every path out of here that doesn't read the body has to release it, or the
  // connection stays open until GC. This endpoint is unauthenticated: a caller
  // hammering random /track/<slug> URLs would otherwise leak one body a request.
  if (!res.ok) {
    await res.body?.cancel();
    throw new APIException(
      APIErrorCode.SERVER_ERROR,
      502,
      `Bandcamp returned ${res.status}`,
    );
  }
  if (!(res.headers.get("content-type") ?? "").startsWith("text/html")) {
    await res.body?.cancel();
    throw new APIException(
      APIErrorCode.SERVER_ERROR,
      502,
      "Bandcamp did not return a page",
    );
  }

  const parsed = parseTralbum(await readTextCapped(res), pageUrl);
  if (!parsed) {
    // Covers "no data-tralbum", "hasAudio: false" and preorder-only releases
    // with nothing streamable — all cases where the client falls back to the
    // iframe embed rather than showing an error.
    throw new APIException(
      APIErrorCode.NOT_FOUND,
      404,
      "No streamable tracks on this page",
    );
  }

  writeCache(key, parsed);
  return parsed;
}