* fix(gcp-cloud-run): render pages cannot reach the service's own dispatch endpoint The Cloud Run image now sets PRODUCER_RESTRICT_PAGE_NETWORK=true, so a rendered page reaches only its own project server and public addresses, not loopback ports or the metadata server. The dispatch endpoint also refuses any POST that carries an Origin header: browsers send one on every POST and Cloud Workflows never does. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(engine): the default frame cache folder is private to the user who renders The default extraction cache sits in the shared temp folder. It is now created with mode 0700, an existing one owned by the same user is closed to others (its entries stay, so cache hits carry over), and one that is a link or belongs to another user is not used: that render runs without the cache and prints a warning. The animated GIF cache under the same folder follows the same rule. A folder set with HYPERFRAMES_EXTRACT_CACHE_DIR is left as it is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(gcp-cloud-run): a Terraform variable turns the page network restriction off restrict_page_network (default true) sets PRODUCER_RESTRICT_PAGE_NETWORK on the service. The package README and docs say what the restriction refuses and how to turn it off for trusted compositions that need private hosts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(engine): restore an unset TMPDIR as unset after the cache-root tests Assigning undefined to process.env stores the string "undefined", so on a runner with no TMPDIR every later test made its temp folder under ./undefined. * test(engine): the frame-extractor link test also restores an unset TMPDIR as unset * chore(engine): raise the packed size budget to 500000 --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
7.0 KiB
@hyperframes/gcp-cloud-run
Google Cloud Run + Cloud Workflows adapter for HyperFrames distributed
rendering. The OSS render primitives (plan → renderChunk × N →
assemble) are pure functions over local file paths; this package is the
deployment, orchestration, and storage glue that runs them on Google Cloud —
the GCP counterpart to @hyperframes/aws-lambda.
Two surfaces, one package:
- Server-side handler (
./server) — a Cloud Run HTTP service that dispatchesplan/renderChunk/assembleon the request body'sActionfield, bridging GCS ↔ the container's filesystem around each OSS primitive. This is what the bundledDockerfileruns. - Client-side SDK (
./sdk) —renderToCloudRun,getRenderProgress,deploySite,validateDistributedRenderConfig, andcomputeRenderCost. Call these from a Node process (CI, CLI, app backend) to drive a deployed stack without writing GCS / Workflows boilerplate.
The package is not a dependency of @hyperframes/producer; install it
separately.
Architecture
GCS bucket ←→ Cloud Run service (plan / renderChunk / assemble)
▲
│ OIDC-authenticated http.post, one per step
│
Cloud Workflows (Plan → parallel RenderChunk → Assemble)
- Plan downloads the project tarball and publishes a Plan v2 manifest plus content-addressed artifacts.
- RenderChunk runs in a parallel
forloop in the workflow, fanned out up to the plan's chunk count. Each invocation renders one chunk and uploads it. - Assemble downloads every chunk + audio, stitches the final deliverable, and uploads it.
Every step is a POST to the same Cloud Run URL with a different Action.
The workflow accumulates each step's small result body and returns
{ Plan, Chunks, Assemble } so getRenderProgress can read frame totals and
per-step durations on success.
Plan transport
Plan v2 is the only supported distributed plan transport.
renderToCloudRun sends PlanProtocol: "v2" without requiring a protocol
option:
await renderToCloudRun({
// ...project, bucket, workflow, service, and config...
});
V2 uses separate manifest and content-addressed artifact locators throughout the workflow. Unknown protocols and integrity failures fail closed.
Upgrade order
Redeploy the Cloud Run image and Cloud Workflows definition from the same new
package version before upgrading an application that calls
renderToCloudRun. Pause new renders and drain active workflow executions
during the infrastructure update. Older workflows may lack the Plan v2-only
request and locator contract. If infrastructure cannot be redeployed first,
keep the application on its previous package version until the workflow
redeploy is complete.
Chrome runtime
Unlike the Lambda adapter — which fights a 250 MB ZIP ceiling and
decompresses @sparticuz/chromium into /tmp at runtime — Cloud Run runs a
container image. The Dockerfile installs the same pinned
chrome-headless-shell build and font set the production renderer uses, at a
fixed path, and exports HYPERFRAMES_CHROME_PATH. CDP-level BeginFrame
support is a binary/runtime capability, so the image build launches that
exact executable and requires an enable + warm-up + PNG-returning
HeadlessExperimental.beginFrame probe to pass. The end-to-end smoke also
requires every chunk to report effective CaptureMode: "beginframe", which
catches runtime fallback separately from build-time packaging. There is no
runtime decompression step and no packaging ceiling.
Deploying
The terraform/ module provisions everything: the GCS render bucket, the
Cloud Run service, the Cloud Workflows definition, two least-privilege
service accounts (the service reads/writes the bucket; the workflow invokes
the service), and a runaway-request alert.
# 1. Build + push the image (Cloud Build or local docker).
gcloud builds submit . \
--tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
# 2. Apply the module.
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform init
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
-var project_id=PROJECT \
-var region=us-central1 \
-var image=REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
Terraform outputs render_bucket_name, service_url, workflow_name, and
region — pass them straight into the SDK.
Page network restriction
The service sets PRODUCER_RESTRICT_PAGE_NETWORK=true, so a rendered page reaches only its own project files and public internet addresses. Loopback, private, link-local and IPv6 addresses are refused for anything the page loads. An asset on a VPC-only host or behind private DNS is missing from the video. ffmpeg's https inputs may open only https, so an https source that redirects to http, or encrypted HLS, does not load.
Keep it on when you render compositions you did not write. To turn it off, apply the module with -var restrict_page_network=false, or set TF_VAR_restrict_page_network=false before hyperframes cloudrun deploy.
Using the SDK
import { renderToCloudRun, getRenderProgress } from "@hyperframes/gcp-cloud-run/sdk";
const handle = await renderToCloudRun({
projectDir: "./my-composition",
config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
bucketName: "hyperframes-render-my-project", // from terraform output
projectId: "my-project",
location: "us-central1",
workflowId: "hyperframes-render",
serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
});
// Poll until done.
let progress = await getRenderProgress({ executionName: handle.executionName });
while (progress.status === "running") {
await new Promise((r) => setTimeout(r, 5000));
progress = await getRenderProgress({ executionName: handle.executionName });
}
console.log(progress.status, progress.outputFile, progress.costs.displayCost);
deploySite is called implicitly when you pass projectDir; call it
yourself to pre-upload once and reuse the siteHandle across many renders
(e.g. personalised template batches).
Running tests
bun test # unit tests over an in-memory GCS double — no network
bun run typecheck
The live end-to-end smoke (build image → terraform apply → render a fixture
through the workflow → PSNR-compare → destroy) lives at
examples/gcp-cloud-run/scripts/smoke.sh and needs a GCP project with
billing enabled.
What's still ahead
- Mid-flight per-chunk progress.
getRenderProgressreports coarserunningprogress and exact numbers on success. Reading the Cloud Workflows step-entries API would give per-chunk progress while the render is in flight; tracked as a follow-up. - Cloud Run Jobs / Firebase Functions variants. This first version targets Cloud Run services + Workflows (the closest analog to Lambda + Step Functions). The same handler runs unchanged under Cloud Run Jobs; only the orchestration trigger differs.