mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* 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>
128 lines
5.5 KiB
Plaintext
128 lines
5.5 KiB
Plaintext
---
|
|
title: "@hyperframes/gcp-cloud-run"
|
|
description: "Google Cloud Run and Workflows adapter for distributed HyperFrames rendering."
|
|
---
|
|
|
|
The GCP Cloud Run package runs HyperFrames' distributed render primitives on Google Cloud. It ships a Cloud Run HTTP service, a Node client SDK, and a Terraform module for provisioning the bucket, service, workflow, and service accounts.
|
|
|
|
```bash
|
|
npm install @hyperframes/gcp-cloud-run
|
|
```
|
|
|
|
## When to Use
|
|
|
|
**Use `@hyperframes/gcp-cloud-run` when you need to:**
|
|
- Render large compositions on Google Cloud infrastructure
|
|
- Orchestrate `plan`, `renderChunk`, and `assemble` through Cloud Workflows
|
|
- Store project archives, chunk outputs, and final videos in GCS
|
|
- Deploy the renderer as a Cloud Run service with a pinned Chrome runtime
|
|
- Drive renders from CI, a backend service, or custom internal tooling
|
|
|
|
**Use a different package if you want to:**
|
|
- Render locally or inside a single Node process - use the [CLI](/packages/cli) or [producer](/packages/producer)
|
|
- Run the same distributed model on AWS - use [aws-lambda](/packages/aws-lambda)
|
|
- Build or edit composition HTML - use [studio](/packages/studio), [sdk](/packages/sdk), or [core](/packages/core)
|
|
|
|
<Tip>
|
|
Cloud Run uses a container image, so it avoids Lambda ZIP-size pressure and can install the same pinned `chrome-headless-shell` runtime used by the standard renderer.
|
|
</Tip>
|
|
|
|
## Package Exports
|
|
|
|
| Import | Description |
|
|
|--------|-------------|
|
|
| `@hyperframes/gcp-cloud-run` | Server handler, event types, GCS transport, and client SDK exports |
|
|
| `@hyperframes/gcp-cloud-run/server` | Cloud Run HTTP service entry point |
|
|
| `@hyperframes/gcp-cloud-run/sdk` | Lightweight Node SDK for deploying sites, starting renders, polling progress, and estimating cost |
|
|
|
|
The published package also includes `terraform/` and a `Dockerfile` for deployment.
|
|
|
|
## Architecture
|
|
|
|
Cloud Workflows invokes one Cloud Run service with different `Action` values:
|
|
|
|
<Steps>
|
|
<Step title="Plan">
|
|
Downloads the project archive from GCS, runs the producer planner, and uploads the plan directory.
|
|
</Step>
|
|
<Step title="Render chunks">
|
|
Cloud Workflows runs parallel `renderChunk` calls against the Cloud Run service. Each request renders one chunk and uploads it to GCS.
|
|
</Step>
|
|
<Step title="Assemble">
|
|
Downloads all chunks and audio assets, assembles the deliverable, and uploads the final file.
|
|
</Step>
|
|
</Steps>
|
|
|
|
The service is intentionally close to the AWS Lambda adapter: thin cloud transport around the same `@hyperframes/producer/distributed` primitives.
|
|
|
|
## Deploying
|
|
|
|
Build and push the container, then apply the Terraform module:
|
|
|
|
```bash
|
|
gcloud builds submit . \
|
|
--tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
|
|
|
|
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 the bucket name, service URL, workflow name, and region needed by 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
|
|
|
|
```typescript
|
|
import { getRenderProgress, renderToCloudRun } 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",
|
|
projectId: "my-project",
|
|
location: "us-central1",
|
|
workflowId: "hyperframes-render",
|
|
serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
|
|
});
|
|
|
|
let progress = await getRenderProgress({ executionName: handle.executionName });
|
|
while (progress.status === "running") {
|
|
await new Promise((resolve) => setTimeout(resolve, 5000));
|
|
progress = await getRenderProgress({ executionName: handle.executionName });
|
|
}
|
|
|
|
console.log(progress.status, progress.outputFile, progress.costs.displayCost);
|
|
```
|
|
|
|
Plan v2 is the only supported distributed plan transport. Workers fetch
|
|
manifest-selected content-addressed artifacts, and the SDK sends explicit v2
|
|
without requiring a protocol option.
|
|
|
|
<Warning>
|
|
For an existing installation, pause new renders and drain active workflow
|
|
executions. Redeploy the Cloud Run image and Cloud Workflows definition from
|
|
the same package version before upgrading the application SDK. Older
|
|
workflows may lack the Plan v2-only request and locator contract.
|
|
</Warning>
|
|
|
|
Pass `projectDir` for one-shot uploads, or call `deploySite()` separately and reuse the returned site handle across many renders.
|
|
|
|
## Related topics
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="GCP Cloud Run Deployment" icon="cloud" href="/deploy/gcp-cloud-run">
|
|
End-to-end deployment details and smoke-test notes.
|
|
</Card>
|
|
<Card title="@hyperframes/producer" icon="video" href="/packages/producer">
|
|
The distributed primitives that the Cloud Run service executes.
|
|
</Card>
|
|
</CardGroup>
|