Files
hyperframes/packages/gcp-cloud-run/Dockerfile
T
Miguel Ángel 9981d9afb7 fix(capture): never silently render a webgpu composition blank (#4091)
* fix(capture): never silently render a webgpu composition blank

A composition declaring data-requires-webgpu only got the Chrome WebGPU
flag when hardware GPU auto-detection succeeded. On a software-GPU host
it launched without the flag and rendered blank with no error.

compositionRequiresWebGpu (static declaration check) and
assertWebGpuAdapterAvailable (live per-page adapter probe) now live once
in packages/engine's browserManager, the shared choke point every launch
site already goes through. All six launch sites (frame capture, the four
CLI diagnostic commands, the studio thumbnail server, and the render
pipeline's capture-options builder) route through those two functions;
the old CLI-only static-heuristic guard is deleted, not kept alongside
the new one. A software host that cannot obtain any WebGPU adapter now
fails loudly naming the requirement instead of producing a blank frame.

* fix(capture): thread requiresWebGpu through the distributed chunk-render path

The distributed renderChunk() path built its CaptureOptions without
requiresWebGpu, so it fell through to frameCapture's own fetch-based
detection, whose failure path silently treats "requires webgpu" as
"doesn't" if that fetch ever fails. Every other launch site (frame
capture, all four CLI diagnostic commands, the studio thumbnail server,
and the in-process render pipeline) already reads the value from HTML
already in memory or on disk instead of relying on that fallback.

Reads the compiled composition's index.html the same way probeStage
already does and derives requiresWebGpu from it before building
CaptureOptions. Adds a regression test that pins the exact path
renderChunk() reads at render time, since the composition doesn't
actually exercise WebGPU so an end-to-end render can't distinguish the
two cases on this host.

* test(producer): observe the real CaptureOptions renderChunk() builds

The previous regression test called plan() and compositionRequiresWebGpu()
directly, bypassing renderChunk() entirely, so it could not detect a
regression to the wiring it was meant to protect (confirmed: it stayed
green with the fix reverted).

Exports the existing createCaptureSession dependency seam so a test can
substitute a spy that delegates to the real implementation while
capturing the CaptureOptions object renderChunk() actually constructs.
Verified non-vacuous by reverting the fix and confirming the test fails.

* fix(gcp-cloud-run): resolve puppeteer-core from a real file in the webgpu probe

The image build's WebGPU adapter probe imported puppeteer-core from an
inline `bun -e` eval string. The eval's synthetic /app/[eval] location
can't resolve the workspace-hoisted dependency, so every build of this
stage failed closed with "Cannot find package 'puppeteer-core'" before
the probe itself ever ran.

Moves the probe into a real script file next to probe-beginframe.ts,
which already imports puppeteer-core dynamically the same way and
resolves fine from its real workspace location. Verified locally against
a cached chrome-headless-shell binary.

* fix(engine): bound the webgpu adapter probe so a stuck driver can't hang the caller

requestAdapter() has no native timeout. A broken software GPU driver
that never settles it would hang assertWebGpuAdapterAvailable
indefinitely, including inside the GCP image build's probe RUN step,
producing an opaque build timeout instead of a clean probe failure.

Races the in-page request against a bounded timeout so a stuck adapter
reads as unavailable and fails the same way a genuinely absent one does.

* test(cli): mock the engine's webgpu exports in the browser-fallback test

* test(producer): run the typegpu adapter fixture only on hosts with a hardware WebGPU adapter

The fixture declares data-requires-webgpu, so a software-only host now refuses it
instead of silently rendering the shader blank. The old golden had no shader in it.
Tag it webgpu, skip that tag in the CI image and the test scripts, and re-record the
golden from a Metal render with the shader visible.

* fix(engine): bound the composition fetch that decides the webgpu flag

createCaptureSession fetched the served page with no timeout before launching the
browser, so a hung server stalled a render forever and hung a fake-timer test. Give it a
five second limit, and let that test say it has no WebGPU requirement the way the
producer does.

* fix(capture): refuse a software fallback WebGPU adapter instead of rendering on it

swiftshader reports a WebGPU adapter but cannot render canvas WebGPU, so a
data-requires-webgpu composition on a software-only host crashed on its first frame.
Refuse fallback adapters with the same clear WebGPU-unavailable error. The GCP image
probe now serves its page over http (file:// hides navigator.gpu) and reports a
software-only host instead of failing the image build.

* fix(engine): parse the composition root tag without a backtracking regex

* fix(engine): keep quoted attribute values whole when reading the composition root tag
2026-09-18 18:06:23 -04:00

164 lines
7.8 KiB
Docker

# HyperFrames distributed render — Cloud Run image.
#
# One container image, three roles (plan / renderChunk / assemble). Cloud
# Workflows POSTs a JSON body with an `Action` field; `dist/server.js`
# dispatches to the matching `@hyperframes/producer/distributed` primitive.
#
# Build context is the REPOSITORY ROOT (not this package dir) because the
# package depends on the `@hyperframes/producer` workspace and renders with
# the same chrome-headless-shell + fonts + ffmpeg the production renderer
# uses. The example smoke script and `hyperframes cloudrun deploy` both
# build with the repo root as context:
#
# docker build -f packages/gcp-cloud-run/Dockerfile -t <image> .
#
# NOTE: this Dockerfile only builds from a full hyperframes monorepo checkout
# — it COPYs sibling workspace packages (core/engine/producer). It is NOT
# buildable from the published npm tarball alone; install the repo (or use
# `hyperframes cloudrun deploy`, which builds from your checkout via Cloud
# Build) to produce the image.
#
# Unlike the AWS Lambda adapter there is no ZIP-size ceiling and no runtime
# Chrome decompression step — the binary lives in the image at a fixed path.
FROM node:22-bookworm-slim AS beginframe-contract
# ── System dependencies (identical set to the producer's render image) ───────
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates \
curl \
unzip \
ffmpeg \
libgbm1 \
libnss3 \
libatk-bridge2.0-0 \
libdrm2 \
libxcomposite1 \
libxdamage1 \
libxrandr2 \
libcups2 \
libasound2 \
libpangocairo-1.0-0 \
libxshmfence1 \
libgtk-3-0 \
fonts-liberation \
fonts-noto-color-emoji \
fonts-noto-cjk \
fonts-noto-core \
fonts-noto-extra \
fonts-noto-ui-core \
fonts-freefont-ttf \
fonts-dejavu-core \
fontconfig \
&& rm -rf /var/lib/apt/lists/* \
&& apt-get clean \
&& fc-cache -fv
# ── chrome-headless-shell (deterministic BeginFrame capture) ─────────────────
# Pinned deliberately. The build-stage contract probe below launches this
# exact executable and requires a renderer-ready warm-up plus a PNG-returning
# HeadlessExperimental.beginFrame before the image can build.
RUN npx --yes @puppeteer/browsers install chrome-headless-shell@148.0.7778.167 \
--path /opt/puppeteer \
&& CHS="$(find /opt/puppeteer/chrome-headless-shell -name chrome-headless-shell -type f | head -n1)" \
&& mkdir -p /opt/chrome \
&& ln -s "$CHS" /opt/chrome/chrome-headless-shell \
&& /opt/chrome/chrome-headless-shell --version
# The chromium.ts resolver reads this first; pointing the engine straight at
# the symlinked binary avoids the runtime cache scan.
ENV HYPERFRAMES_CHROME_PATH=/opt/chrome/chrome-headless-shell
ENV PRODUCER_HEADLESS_SHELL_PATH=/opt/chrome/chrome-headless-shell
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV CONTAINER=true
WORKDIR /app
# Install bun (the repo's package manager / build driver). Pin the version:
# the container runs `bun dist/server.js` and relies on bun's ESM `require`
# interop to load the producer bundle, so a future bun release changing that
# behaviour shouldn't silently break the next image rebuild. Bump deliberately.
RUN curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.9"
ENV PATH="/root/.bun/bin:$PATH"
# Install workspace dependencies. Copy manifests first for layer caching.
COPY package.json bun.lock ./
COPY packages/core/package.json packages/core/package.json
COPY packages/engine/package.json packages/engine/package.json
COPY packages/player/package.json packages/player/package.json
COPY packages/producer/package.json packages/producer/package.json
COPY packages/cli/package.json packages/cli/package.json
COPY packages/studio/package.json packages/studio/package.json
COPY packages/shader-transitions/package.json packages/shader-transitions/package.json
COPY packages/aws-lambda/package.json packages/aws-lambda/package.json
COPY packages/gcp-cloud-run/package.json packages/gcp-cloud-run/package.json
COPY packages/lint/package.json packages/lint/package.json
COPY packages/parsers/package.json packages/parsers/package.json
COPY packages/sdk/package.json packages/sdk/package.json
COPY packages/sdk-playground/package.json packages/sdk-playground/package.json
COPY packages/studio-server/package.json packages/studio-server/package.json
COPY scripts/package-subpaths.mjs scripts/package-subpaths.mjs
RUN bun install --frozen-lockfile
# Fail the image build closed if the packaged executable cannot perform the
# same BeginFrame operation the distributed renderer relies on. Generate the
# argument list with the production engine helper so a launcher-flag regression
# invalidates this layer and fails the contract instead of testing a duplicate
# hard-coded profile.
COPY packages/engine/ packages/engine/
COPY packages/aws-lambda/scripts/probe-beginframe.ts packages/aws-lambda/scripts/probe-beginframe.ts
RUN bun -e 'import { buildChromeArgs } from "./packages/engine/src/services/browserManager.ts"; await Bun.write("/tmp/hf-gcp-chrome-args.json", JSON.stringify(buildChromeArgs({ width: 800, height: 600, captureMode: "beginframe", platform: "linux" }, { browserGpuMode: "software" })))' \
&& bun packages/aws-lambda/scripts/probe-beginframe.ts \
--executable-path /opt/chrome/chrome-headless-shell \
--launch-args-json /tmp/hf-gcp-chrome-args.json
# Reports whether this exact pinned binary gets a hardware WebGPU adapter. A software-only
# host reports "no usable adapter" without failing the build; its WebGPU compositions refuse
# to render at run time. A real script file, not an inline `bun -e` eval: the eval's
# synthetic `/app/[eval]` path can't resolve the workspace-hoisted `puppeteer-core`.
COPY packages/aws-lambda/scripts/probe-webgpu-adapter.ts packages/aws-lambda/scripts/probe-webgpu-adapter.ts
RUN bun packages/aws-lambda/scripts/probe-webgpu-adapter.ts \
--executable-path /opt/chrome/chrome-headless-shell
# CI targets `beginframe-contract` directly, so pin/probe changes do not need
# the full monorepo build merely to verify browser capability. The deployable
# image continues from the already-proven binary and installed workspaces.
FROM beginframe-contract AS runtime
# Copy source for the packages the render path needs.
COPY packages/core/ packages/core/
COPY packages/engine/ packages/engine/
COPY packages/producer/ packages/producer/
COPY packages/gcp-cloud-run/ packages/gcp-cloud-run/
COPY packages/lint/ packages/lint/
COPY packages/parsers/ packages/parsers/
COPY packages/sdk/ packages/sdk/
COPY packages/sdk-playground/ packages/sdk-playground/
COPY packages/studio-server/ packages/studio-server/
# Build workspace dependencies before the producer bundle. The published
# workspace packages are not prebuilt in a fresh clone, so producer's esbuild
# resolution otherwise fails on parsers/core compiler entrypoints. Generate
# embedded font data so glyph layout matches production.
RUN bun run --cwd packages/parsers build \
&& bun run --cwd packages/lint build \
&& bun run --cwd packages/studio-server build \
&& bun run --cwd packages/core build \
&& bun run --cwd packages/core build:hyperframes-runtime:modular \
&& bun run --cwd packages/sdk build \
&& bun run --cwd packages/sdk-playground build \
&& bun run --cwd packages/engine build \
&& (cd packages/producer && bunx tsx scripts/generate-font-data.ts) \
&& bun run --cwd packages/producer build \
&& bun run --cwd packages/gcp-cloud-run build
# Cloud Run injects PORT (default 8080). The server reads it.
ENV PORT=8080
EXPOSE 8080
WORKDIR /app/packages/gcp-cloud-run
# Run under bun, not node. The repo is bun-native and `@hyperframes/producer`'s
# bundled `distributed.js` relies on a `require` being available at runtime
# (its esbuild interop shim); bun provides one in ESM, bare `node` does not.
CMD ["bun", "dist/server.js"]