hyperframes/examples/gcp-cloud-run

Google Cloud Run example

End-to-end deployment and parity testing for @hyperframes/gcp-cloud-run, the Cloud Run + Cloud Workflows adapter for HyperFrames distributed rendering.

Layout

scripts/smoke.sh        Owner-isolated real-GCP deploy, render, validation, cleanup
sample-events/          Default-v2 and explicit-v2 request examples

The Terraform module and Cloud Workflows definition live in packages/gcp-cloud-run/terraform/.

Plan transport

Plan v2 is the only supported plan transport. The workflow uses PlanV2ManifestGcsUri and PlanV2ArtifactGcsPrefix and validates the plan response before starting chunk fan-out. Deploy the workflow only with a Cloud Run image whose handler implements the matching v2 request/response contract.

For an existing installation, pause new renders and drain active workflow executions. Redeploy the Cloud Run image and workflow from the same package version before upgrading the application SDK. The new SDK sends explicit v2; older workflows may lack the Plan v2-only contract. Keep the application on its previous package version until the infrastructure redeploy completes.

Prerequisites

• gcloud authenticated to a project with billing enabled
• terraform (>= 1.5), ffmpeg, ffprobe, jq, tar, and sha256sum
• the required project APIs already enabled, plus permission to run Cloud Build and manage Cloud Run, Workflows, GCS, IAM service accounts, Monitoring, and Artifact Registry resources

Run the smoke

Plan v2 is the normal smoke path:

./scripts/smoke.sh \
  --project YOUR_GCP_PROJECT \
  --region us-central1

Run one or more chunk sizes:

./scripts/smoke.sh \
  --project YOUR_GCP_PROJECT \
  --region us-central1 \
  --chunk-sizes 30,15,10 \
  --owner plan-v2-smoke

Each render is PSNR-compared with the checked-in in-process fixture baseline. The encoded MP4 hash and byte count are recorded as additional evidence.

Isolation and cleanup

Every invocation hashes the owner, project, region, and a fresh invocation nonce into a unique resource prefix such as hf-smoke-a1b2c3d4e5. Reusing an owner label does not reuse old Terraform state or cloud resources. This prefix stays within GCP service account naming limits. The smoke:

• never uses the static hyperframes prefix
• copies the Terraform module into an owner-scoped work directory and uses an isolated Terraform data directory and state file
• scopes GCS keys, render outputs, the image package/tag, and the default Artifact Registry repository to that owner
• deletes only an image it built
• deletes the Artifact Registry repository only when that invocation created it
• refuses to enable project APIs, because APIs are shared project state
• stages the bounded Cloud Build source archive in an owner-scoped bucket, writes build logs to Cloud Logging, and deletes the staging bucket

Cleanup is on by default. It empties and destroys the owner-scoped bucket and stack, deletes owned image/repository/build-staging resources, then verifies the Cloud Run service, workflow, buckets, both service accounts, image, and any test-created repository are absent. Cleanup fails on API or authentication errors rather than interpreting them as successful deletion. GCP retains the Cloud Build execution record and Cloud Logging audit entries as project-level operational history; the smoke test does not attempt to erase audit records.

--keep-stack deliberately retains the stack, image, and repository and prints the exact isolated state directory and Terraform cleanup commands. Never use it for unattended CI.

Evidence lands under:

scripts/gcp-smoke-artifacts/<owner-hash>/
  results.json
  renders/
  terraform/
  terraform-data/

Use --image to test a caller-owned existing image. That image is never deleted. --skip-build requires --image; new invocations never inherit an old invocation's state or image implicitly.

Test the handler locally

The sample events mirror the request bodies sent by Cloud Workflows:

# Default v2 (PlanProtocol omitted)
curl -sX POST localhost:8080/ \
  -H 'content-type: application/json' \
  --data @sample-events/plan.json | jq .

# Explicit v2 for callers that always stamp the protocol
curl -sX POST localhost:8080/ \
  -H 'content-type: application/json' \
  --data @sample-events/plan-v2.json | jq .

Replace PROJECT, locator placeholders, and plan hashes with values returned by the preceding plan action. A complete action sequence is plan → renderChunk(s) → assemble.