Skip to content

Write HTML. Render video. Built for agents.

20.5 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Server } from "node:http";
import {
  inProcessAnswer,
  serveStaticProjectHtml,
  type StaticProjectServer,
} from "./staticProjectServer.js";
import { injectMediaCodecMapIntoHtml } from "@hyperframes/studio-server/media-proxy-preview";

// `serveStaticProjectHtml` reaches these two studio-server helpers via a
// absolute module regardless of which file's relative specifier reaches it).
//
// The error class lives inside this `vi.hoisted` block (not a plain top-level
// `class`) because `vi.mock` factories run during static-import resolution —
// before any of this file's own top-level statements execute — so a `class`
// declared below would still be in its temporal dead zone.
const mocks = vi.hoisted(() => {
  class FakeProxyTranscodeError extends Error {
    readonly exitCode: number | null;
    readonly stderrTail: string;
    constructor(message: string, exitCode: number | null = null, stderrTail = "") {
      super(message);
      this.name = "ProxyTranscodeError";
      this.exitCode = exitCode;
      this.stderrTail = stderrTail;
    }
  }
  class FakeProxyCapacityError extends FakeProxyTranscodeError {
    constructor(message = "media proxy queue is full") {
      super(message);
      this.name = "ProxyCapacityError";
    }
  }
  return {
    resolveProxy: vi.fn<
      (
        projectDir: string,
        absoluteSourcePath: string,
        variant?: string,
        box?: unknown,
        options?: { signal?: AbortSignal },
      ) => Promise<string>
    >(
      // Benign default so `injectMediaCodecMap`'s fire-and-forget pre-warm
      // (called for every hostile map entry) always gets a promise to
      // `.catch()`, even in tests that don't care about the proxy path.
      async () => "/unused-prewarm-proxy-path",
    ),
    scanProjectMediaCodecMap: vi.fn<
      (
        ...args: unknown[]
      ) => Promise<
        Record<
          string,
          { codecName: string; browserHostile: boolean; representativeMime: string | null }
        >
      >
    >(async () => ({})),
    probeAssetCodec: vi.fn(async () => ({
      codecName: "hevc",
      hasAlpha: false,
      browserHostile: true,
      representativeMime: null,
    })),
    decideMediaProxyEligibility: vi.fn<
      () => { eligible: true } | { eligible: false; reason: "browser_safe_codec" }
    >(() => ({ eligible: true })),
    ProxyTranscodeError: FakeProxyTranscodeError,
    ProxyCapacityError: FakeProxyCapacityError,
  };
});
const FakeProxyTranscodeError = mocks.ProxyTranscodeError;

vi.mock("@hyperframes/studio-server/proxy-transcoder", () => ({
  resolveProxy: mocks.resolveProxy,
  ProxyTranscodeError: mocks.ProxyTranscodeError,
  ProxyCapacityError: mocks.ProxyCapacityError,
}));

vi.mock("@hyperframes/studio-server/media-codec-map", () => ({
  probeAssetCodec: mocks.probeAssetCodec,
  decideMediaProxyEligibility: mocks.decideMediaProxyEligibility,
  isProxyVariant: (value: string) => value === "h264" || value === "vp8",
  isProxyVariantRequest: (value: string) => value === "auto" || value === "h264" || value === "vp8",
  recordProxyRequest: () => {},
  proxyVariantFor: (facts: { hasAlpha?: boolean }) => (facts.hasAlpha ? "vp8" : "h264"),
  resolveProxyVariantRequest: (request: "auto" | "h264" | "vp8", facts: { hasAlpha?: boolean }) => {
    const expected = facts.hasAlpha ? "vp8" : "h264";
    return request === "auto" || request === expected ? expected : null;
  },
  PROXY_VARIANT_CONFIG: {
    h264: { extension: ".mp4", contentType: "video/mp4" },
    vp8: { extension: ".webm", contentType: "video/webm" },
  },
}));

// The shared injection helper ships as a self-contained dist bundle (its copy
// of scanProjectMediaCodecMap is inlined), so it must be mocked wholesale —
// mocking the media-codec-map subpath can't reach inside it. The fake mirrors
// the real contract (scan → inject tag) via this file's scan mock so the
// injection assertions stay meaningful. Mirrors commands/play.test.ts.
vi.mock("@hyperframes/studio-server/media-proxy-preview", () => ({
  injectMediaCodecMapIntoHtml: vi.fn(
    async (html: string, projectDir: string, htmlSources: unknown[]) => {
      const map = await mocks.scanProjectMediaCodecMap(projectDir, htmlSources);
      const tag = `<script data-hf-media-codec-map>window.__HF_MEDIA_CODEC_MAP__=${JSON.stringify(map)};</script>`;
      return html.includes("</head>")
        ? html.replace("</head>", `${tag}\n</head>`)
        : `${tag}\n${html}`;
    },
  ),
}));

let server: StaticProjectServer | undefined;
let dir: string | undefined;

afterEach(async () => {
  await server?.close();
  server = undefined;
  if (dir) rmSync(dir, { recursive: true, force: true });
  dir = undefined;
  mocks.resolveProxy.mockReset();
  mocks.resolveProxy.mockResolvedValue("/unused-prewarm-proxy-path");
  mocks.scanProjectMediaCodecMap.mockReset();
  mocks.scanProjectMediaCodecMap.mockResolvedValue({});
  mocks.probeAssetCodec.mockClear();
  mocks.decideMediaProxyEligibility.mockClear();
  mocks.decideMediaProxyEligibility.mockReturnValue({ eligible: true });
});

async function serveWith(bytes: Buffer): Promise<{ url: string }> {
  dir = mkdtempSync(join(tmpdir(), "hf-static-"));
  writeFileSync(join(dir, "tone.wav"), bytes);
  server = await serveStaticProjectHtml(dir, "<html></html>");
  return { url: server.url };
}

describe("serveStaticProjectHtml range support", () => {
  it("answers a Range request with 206 + the requested byte slice", async () => {
    // Chromium needs byte-range seekability or WAV `.duration` reports Infinity,
    // which makes `hyperframes validate` falsely warn it cannot read the duration.
    const body = Buffer.from("0123456789", "utf-8");
    const { url } = await serveWith(body);

    const res = await fetch(`${url}tone.wav`, { headers: { Range: "bytes=2-5" } });
    expect(res.status).toBe(206);
    expect(res.headers.get("accept-ranges")).toBe("bytes");
    expect(res.headers.get("content-range")).toBe(`bytes 2-5/${body.length}`);
    expect(await res.text()).toBe("2345");
  });

  it("advertises Accept-Ranges even on a full 200 response", async () => {
    const { url } = await serveWith(Buffer.from("abcdef", "utf-8"));
    const res = await fetch(`${url}tone.wav`);
    expect(res.status).toBe(200);
    expect(res.headers.get("accept-ranges")).toBe("bytes");
    expect(await res.text()).toBe("abcdef");
  });

  it.each([undefined, "invalid", "items=0-1"])(
    "serves an empty asset with Range %j and keeps serving the project",
    async (range) => {
      const { url } = await serveWith(Buffer.alloc(0));
      const res = await fetch(`${url}tone.wav`, {
        headers: range === undefined ? {} : { Range: range },
        signal: AbortSignal.timeout(1500),
      });
      expect(res.status).toBe(200);
      expect(res.headers.get("content-length")).toBe("0");
      expect(res.headers.get("accept-ranges")).toBe("bytes");
      expect(res.headers.get("content-range")).toBeNull();
      expect(await res.text()).toBe("");
      const project = await fetch(url);
      expect(project.status).toBe(200);
      expect(await project.text()).toContain("<html></html>");
    },
  );

  it.each(["bytes=0-", "bytes=0-0", "bytes=-1"])(
    "rejects the unsatisfiable range %s on an empty asset",
    async (range) => {
      const { url } = await serveWith(Buffer.alloc(0));
      const res = await fetch(`${url}tone.wav`, { headers: { Range: range } });
      expect(res.status).toBe(416);
      expect(res.headers.get("content-range")).toBe("bytes */0");
      expect(await res.text()).toBe("");
    },
  );

  it("streams a small slice out of a large file without buffering the whole thing", async () => {
    // 8MB file, ask for 4 bytes deep inside it. The handler must createReadStream
    // the [start,end] window only, not readFileSync the whole 8MB and slice.
    const size = 8 * 1024 * 1024;
    const big = Buffer.alloc(size, 0x61); // 'a' everywhere...
    big.write("WXYZ", 5_000_000); // ...except a 4-byte marker
    const { url } = await serveWith(big);

    const res = await fetch(`${url}tone.wav`, { headers: { Range: "bytes=5000000-5000003" } });
    expect(res.status).toBe(206);
    expect(res.headers.get("content-range")).toBe(`bytes 5000000-5000003/${size}`);
    expect(res.headers.get("content-length")).toBe("4");
    expect(await res.text()).toBe("WXYZ");
  });

  it("returns 416 for an unsatisfiable range", async () => {
    const body = Buffer.from("abc", "utf-8");
    const { url } = await serveWith(body);
    const res = await fetch(`${url}tone.wav`, { headers: { Range: "bytes=99-200" } });
    expect(res.status).toBe(416);
    expect(res.headers.get("content-range")).toBe(`bytes */${body.length}`);
  });
});

describe("serveStaticProjectHtml asset roots", () => {
  const extraDirs: string[] = [];
  const mk = (): string => {
    const d = mkdtempSync(join(tmpdir(), "hf-static-root-"));
    extraDirs.push(d);
    return d;
  };
  afterEach(() => {
    for (const d of extraDirs.splice(0)) rmSync(d, { recursive: true, force: true });
  });

  it("serves files from an extra asset root when the project dir lacks them", async () => {
    // extra root (e.g. localized-assets temp dir) resolves same-origin
    const projectDir = mk();
    const assetDir = mk();
    mkdirSync(join(assetDir, "_remote_media"), { recursive: true });
    writeFileSync(join(assetDir, "_remote_media", "img.jpg"), "PIXELS");
    server = await serveStaticProjectHtml(projectDir, "<html></html>", undefined, [assetDir]);

    const res = await fetch(`${server.url}_remote_media/img.jpg`);
    expect(res.status).toBe(200);
    expect(await res.text()).toBe("PIXELS");
  });

  it("labels the page and its scripts UTF-8 so text without a meta charset is not misread", async () => {
    const projectDir = mk();
    writeFileSync(join(projectDir, "scene.js"), 'document.title = "太阳系";');
    server = await serveStaticProjectHtml(projectDir, "<h1>太阳系科普动画</h1>");

    const page = await fetch(server.url);
    const script = await fetch(`${server.url}scene.js`);
    expect(page.headers.get("content-type")).toBe("text/html; charset=utf-8");
    expect(script.headers.get("content-type")).toBe("text/javascript; charset=utf-8");
  });

  it("prefers the project dir over an asset root for the same path", async () => {
    const projectDir = mk();
    const assetDir = mk();
    writeFileSync(join(projectDir, "a.txt"), "PROJECT");
    writeFileSync(join(assetDir, "a.txt"), "ASSET");
    server = await serveStaticProjectHtml(projectDir, "<html></html>", undefined, [assetDir]);

    const res = await fetch(`${server.url}a.txt`);
    expect(await res.text()).toBe("PROJECT");
  });

  it("serves a file whose name has a bare percent sign", async () => {
    const projectDir = mk();
    writeFileSync(join(projectDir, "100%.png"), "PERCENT");
    writeFileSync(join(projectDir, "50% off.png"), "SALE");
    server = await serveStaticProjectHtml(projectDir, "<html></html>", undefined, []);

    const bare = await fetch(`${server.url}100%.png`);
    expect(bare.status).toBe(200);
    expect(await bare.text()).toBe("PERCENT");
    expect(await (await fetch(`${server.url}50%%20off.png`)).text()).toBe("SALE");
  });

  it("404s a path present in no root", async () => {
    const projectDir = mk();
    server = await serveStaticProjectHtml(projectDir, "<html></html>", undefined, [mk()]);
    const res = await fetch(`${server.url}nope.txt`);
    expect(res.status).toBe(404);
  });
});

describe("serveStaticProjectHtml transparent media proxies", () => {
  const dirs: string[] = [];
  const mk = (): string => {
    const d = mkdtempSync(join(tmpdir(), "hf-static-proxy-"));
    dirs.push(d);
    return d;
  };
  afterEach(() => {
    for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
  });

  it("injects __HF_MEDIA_CODEC_MAP__ into the served HTML", async () => {
    mocks.scanProjectMediaCodecMap.mockResolvedValue({
      "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null },
    });
    const projectDir = mk();
    server = await serveStaticProjectHtml(projectDir, "<html><head></head><body></body></html>");

    const res = await fetch(server.url);
    const html = await res.text();
    expect(html).toContain("__HF_MEDIA_CODEC_MAP__");
    expect(html).toContain("/clip.mp4");
  });

  it("lets an explicit proxy override win over hyperframes.json", async () => {
    mocks.scanProjectMediaCodecMap.mockResolvedValue({
      "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null },
    });
    const projectDir = mk();
    writeFileSync(
      join(projectDir, "hyperframes.json"),
      JSON.stringify({ media: { autoProxy: false } }),
    );
    server = await serveStaticProjectHtml(
      projectDir,
      "<html><head></head><body></body></html>",
      undefined,
      [],
      true,
    );

    const html = await (await fetch(server.url)).text();
    expect(html).toContain("__HF_MEDIA_CODEC_MAP__");
  });

  it("lets an explicit --no-proxy override suppress config-enabled proxying", async () => {
    mocks.scanProjectMediaCodecMap.mockResolvedValue({
      "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null },
    });
    const projectDir = mk();
    server = await serveStaticProjectHtml(
      projectDir,
      "<html><head></head><body></body></html>",
      undefined,
      [],
      false,
    );

    const html = await (await fetch(server.url)).text();
    expect(html).not.toContain("__HF_MEDIA_CODEC_MAP__");
    expect(mocks.scanProjectMediaCodecMap).not.toHaveBeenCalled();
  });

  it("serves the resolved proxy's bytes for ?hf-proxy=h264 on a hostile video asset", async () => {
    const projectDir = mk();
    writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
    const proxyPath = join(projectDir, "proxy.mp4");
    writeFileSync(proxyPath, "transcoded-h264-bytes");
    mocks.resolveProxy.mockResolvedValue(proxyPath);
    server = await serveStaticProjectHtml(projectDir, "<html></html>");

    const res = await fetch(`${server.url}clip.mp4?hf-proxy=h264`);
    expect(res.status).toBe(200);
    expect(await res.text()).toBe("transcoded-h264-bytes");
    expect(mocks.resolveProxy).toHaveBeenCalledWith(
      projectDir,
      join(projectDir, "clip.mp4"),
      "h264",
      undefined,
      { signal: expect.any(AbortSignal) },
    );
  });

  it.each(["mxf", "mts", "m2ts", "ts", "mkv", "m4v"])(
    "serves a proxy for .%s camera/container media",
    async (extension) => {
      const projectDir = mk();
      const sourcePath = join(projectDir, `clip.${extension}`);
      writeFileSync(sourcePath, "original-hostile-bytes");
      const proxyPath = join(projectDir, "proxy.mp4");
      writeFileSync(proxyPath, "transcoded-h264-bytes");
      mocks.resolveProxy.mockResolvedValue(proxyPath);
      server = await serveStaticProjectHtml(projectDir, "<html></html>");

      const res = await fetch(`${server.url}clip.${extension}?hf-proxy=h264`);
      expect(res.status).toBe(200);
      expect(await res.text()).toBe("transcoded-h264-bytes");
      expect(mocks.resolveProxy).toHaveBeenCalledWith(projectDir, sourcePath, "h264", undefined, {
        signal: expect.any(AbortSignal),
      });
    },
  );

  it("serves an alpha-bearing video through a VP8 WebM proxy", async () => {
    const projectDir = mk();
    writeFileSync(join(projectDir, "clip.mov"), "prores-4444-alpha-bytes");
    mocks.probeAssetCodec.mockResolvedValueOnce({
      codecName: "prores",
      hasAlpha: true,
      browserHostile: true,
      representativeMime: null,
    });
    const proxyPath = join(projectDir, "proxy.webm");
    writeFileSync(proxyPath, "vp8-alpha-proxy");
    mocks.resolveProxy.mockResolvedValueOnce(proxyPath);
    server = await serveStaticProjectHtml(projectDir, "<html></html>");

    const res = await fetch(`${server.url}clip.mov?hf-proxy=auto`);

    expect(res.status).toBe(200);
    expect(res.headers.get("content-type")).toBe("video/webm");
    expect(mocks.probeAssetCodec).toHaveBeenCalledWith(join(projectDir, "clip.mov"));
    expect(mocks.resolveProxy).toHaveBeenCalledWith(
      projectDir,
      join(projectDir, "clip.mov"),
      "vp8",
      undefined,
      { signal: expect.any(AbortSignal) },
    );
  });

  it("answers 502 when the proxy transcode fails", async () => {
    const projectDir = mk();
    writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
    mocks.resolveProxy.mockRejectedValue(
      new FakeProxyTranscodeError("ffmpeg exited with code 1", 1),
    );
    server = await serveStaticProjectHtml(projectDir, "<html></html>");

    const res = await fetch(`${server.url}clip.mp4?hf-proxy=h264`);
    expect(res.status).toBe(502);
  });

  it("answers a retryable 503 when the proxy queue is full", async () => {
    const projectDir = mk();
    writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
    mocks.resolveProxy.mockRejectedValue(new mocks.ProxyCapacityError());
    server = await serveStaticProjectHtml(projectDir, "<html></html>");

    const res = await fetch(`${server.url}clip.mp4?hf-proxy=h264`);
    expect(res.status).toBe(503);
    expect(res.headers.get("retry-after")).toBe("1");
  });

  it("404s ?hf-proxy=h264 for a non-video asset without attempting a transcode", async () => {
    const projectDir = mk();
    writeFileSync(join(projectDir, "image.png"), "not-a-video");
    server = await serveStaticProjectHtml(projectDir, "<html></html>");

    const res = await fetch(`${server.url}image.png?hf-proxy=h264`);
    expect(res.status).toBe(404);
    expect(mocks.resolveProxy).not.toHaveBeenCalled();
  });

  it("stops the copies it started, pre-warmed or asked for, when it closes", async () => {
    mocks.scanProjectMediaCodecMap.mockResolvedValue({
      "/clip.mp4": { codecName: "hevc", browserHostile: true, representativeMime: null },
    });
    const projectDir = mk();
    writeFileSync(join(projectDir, "clip.mp4"), "original-hevc-bytes");
    let asked: AbortSignal | undefined;
    mocks.resolveProxy.mockImplementation(
      (_dir, _path, _variant, _box, options) =>
        new Promise((_resolve, reject) => {
          asked = options?.signal;
          asked?.addEventListener("abort", () => reject(asked?.reason));
        }),
    );
    const closing = await serveStaticProjectHtml(projectDir, "<html><head></head></html>");
    const held = fetch(`${closing.url}clip.mp4?hf-proxy=h264`);
    await vi.waitFor(() => expect(asked).toBeDefined());
    const injected = vi.mocked(injectMediaCodecMapIntoHtml).mock.calls.at(-1) as unknown[];
    const prewarms = injected[5] as AbortSignal | undefined;

    await closing.close();

    expect(prewarms?.aborted).toBe(true);
    expect(asked?.aborted).toBe(true);
    expect((await held).status).toBe(500);
  });
});

describe("serveStaticProjectHtml when a sandbox refuses listen()", () => {
  const refuse = (code: string) =>
    vi.spyOn(Server.prototype, "listen").mockImplementation(function (this: Server) {
      process.nextTick(() =>
        this.emit("error", Object.assign(new Error(`listen ${code}`), { code })),
      );
      return this;
    });

  afterEach(() => vi.restoreAllMocks());

  it("answers the project in this process, Range included, with nothing listening", async () => {
    const listen = refuse("EPERM");
    dir = mkdtempSync(join(tmpdir(), "hf-static-"));
    writeFileSync(join(dir, "tone.wav"), Buffer.from("0123456789", "utf-8"));
    server = await serveStaticProjectHtml(dir, "<html><body>composition</body></html>");

    expect(listen).toHaveBeenCalledOnce();
    expect(server.port).toBe(0);
    expect(inProcessAnswer(server.url)).toBe(server.answer);
    const page = await server.answer!({ method: "GET", path: "/", headers: {} });
    expect(page.status).toBe(200);
    expect(page.body.toString()).toContain("composition");
    const slice = await server.answer!({
      method: "GET",
      path: "/tone.wav",
      headers: { range: "bytes=2-5" },
    });
    expect(slice.status).toBe(206);
    expect(slice.headers["content-range"]).toBe("bytes 2-5/10");
    expect(slice.body.toString()).toBe("2345");
    expect(
      (await server.answer!({ method: "GET", path: "/missing.png", headers: {} })).status,
    ).toBe(404);

    const url = server.url;
    await server.close();
    server = undefined;
    expect(inProcessAnswer(url)).toBeUndefined();
  });

  it("still fails on a bind error that is not a refusal", async () => {
    refuse("EADDRINUSE");
    dir = mkdtempSync(join(tmpdir(), "hf-static-"));
    await expect(serveStaticProjectHtml(dir, "<html></html>")).rejects.toMatchObject({
      code: "EADDRINUSE",
    });
  });
});