hyperframes/packages/gcp-cloud-run/README.md

@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 dispatches plan / renderChunk / assemble on the request body's Action field, bridging GCS ↔ the container's filesystem around each OSS primitive. This is what the bundled Dockerfile runs.
• Client-side SDK (./sdk) — renderToCloudRun, getRenderProgress, deploySite, validateDistributedRenderConfig, and computeRenderCost. 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 either a legacy v1 planDir tarball or a v2 manifest plus content-addressed artifacts.
• RenderChunk runs in a parallel for loop 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 selection

Plan v2 is recommended for new integrations. renderToCloudRun still interprets an omitted planProtocol as "v1" for backwards compatibility, so new callers should select v2 explicitly:

await renderToCloudRun({
  // ...project, bucket, workflow, service, and config...
  planProtocol: "v2",
});

V2 uses separate manifest and content-addressed artifact locators throughout the workflow. Unknown protocols and integrity failures fail closed; a render never mixes v1 and v2 artifacts.

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.

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. getRenderProgress reports coarse running progress 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.