mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
James Russo
1d636f603c
## What Refactor distributed planning around one shared local execution-plan builder: - `buildLocalExecutionPlan()` now owns compile/probe/extract/audio/freeze. - Legacy `plan()` remains a deprecated v1 transport wrapper. - Plan v2 calls the shared builder directly and publishes through the existing manifest/CAS contract. - Add neutral `createPlanV2FromExecutionPlan()`, `publishPlanV2FromExecutionPlan()`, `getPlanV2ExecutionPlanHash()`, and `PLAN_PROTOCOL_V1` names. - Retain deprecated v1-named exports and wire aliases. - Recommend explicit Plan v2 opt-in for new producer, Lambda, and Cloud Run integrations. ## Why Plan v2 previously looked like it invoked a v1 planner even though v1 and v2 share the same frozen local execution representation. This removes that migration-era coupling while preserving the public minor-version compatibility contract. ## How The shared builder returns neutral internal execution-plan fields. The v1 wrapper maps those fields back to the existing `PlanResult`; the v2 publisher consumes them directly. Compatibility is intentional and covered by exact shape tests: - omitted `planProtocol` still serializes/selects `"v1"`; - v1 layouts, descriptor-less decoding, event unions, workflow branches, and exports remain; - the v1 descriptor JSON is byte-identical and `CURRENT_PLAN_PROTOCOL` is an identity-preserving alias; - v2 manifest bytes, key order, hash framing, and `sourcePlanV1Hash` wire key remain unchanged; - no enumerable neutral hash field was added to manifests or returned result objects; - v1/v2 result objects, cloud event payloads, and SDK handle key sets remain unchanged. ## Test plan - Focused Plan v1/v2/protocol/export/size compatibility: 141 passed - `@hyperframes/core`: 1,419 passed - `@hyperframes/producer` unit lane: 990 passed - `@hyperframes/aws-lambda`: 140 passed - `@hyperframes/gcp-cloud-run`: 101 passed - Producer, Lambda, and Cloud Run typechecks - Repository-wide lint, format check, workspace/package-subpath checks - Full workspace build - `git diff --check` - [x] Unit tests added/updated - [ ] Manual testing performed - [x] Documentation updated (if applicable)
213 lines
9.6 KiB
Markdown
213 lines
9.6 KiB
Markdown
# @hyperframes/aws-lambda
|
||
|
||
AWS Lambda adapter for HyperFrames distributed rendering. Ships three
|
||
things together:
|
||
|
||
1. The **Lambda handler** that wraps the OSS `plan` / `renderChunk` /
|
||
`assemble` primitives behind a single dispatch boundary Step Functions
|
||
can drive (`src/handler.ts`).
|
||
2. A **client-side SDK** — `renderToLambda`, `getRenderProgress`,
|
||
`deploySite`, plus `validateDistributedRenderConfig` and
|
||
`computeRenderCost` (`src/sdk/`).
|
||
3. An **`aws-cdk-lib` L2 construct** (`HyperframesRenderStack`) that
|
||
provisions the same topology as `examples/aws-lambda/template.yaml`
|
||
inside an adopter's own CDK app (`src/cdk/`).
|
||
|
||
The handler ZIP and the SAM template still drive a maintainer-run real-AWS
|
||
smoke flow; the SDK + CDK are the supported public surface for adopters.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ Step Functions state machine │
|
||
│ Plan → Map(N) RenderChunk → Assemble │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
│ dispatches by event.Action
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ One Lambda function (this package's `dist/handler.zip`) │
|
||
│ handler.mjs │
|
||
│ ├─ Action="plan" → @hyperframes/producer/distributed │
|
||
│ ├─ Action="renderChunk" → @hyperframes/producer/distributed │
|
||
│ └─ Action="assemble" → @hyperframes/producer/distributed │
|
||
│ bin/ffmpeg — ffmpeg-static │
|
||
│ node_modules/@sparticuz/chromium/ — Lambda-optimised Chromium │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
│ pure functions over local paths
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ S3 bucket — v1 plan tar or v2 manifest/blobs + chunks + output │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
The handler downloads inputs from S3 into `/tmp`, calls the OSS primitive,
|
||
uploads outputs back to S3, and returns a small JSON result that fits
|
||
inside Step Functions' history budget (under 200 bytes per chunk).
|
||
|
||
### Plan transport selection
|
||
|
||
Plan v2 is recommended for new integrations. `renderToLambda` still defaults
|
||
an omitted `planProtocol` to the existing monolithic v1 transport for
|
||
backwards compatibility, so select v2 explicitly:
|
||
|
||
```ts
|
||
await renderToLambda({
|
||
// ...bucket, state machine, project, and config...
|
||
planProtocol: "v2",
|
||
});
|
||
```
|
||
|
||
V2 never overloads `PlanS3Uri`. The planner returns
|
||
`PlanV2ManifestS3Uri` and `PlanV2ArtifactS3Prefix`; chunk workers fetch
|
||
only manifest-selected chunk artifacts, while the assembler fetches its
|
||
own metadata and audio subset. Blobs are immutable SHA-256-addressed
|
||
objects, verified on upload and download, and the manifest is published
|
||
last. Unknown protocols and digest mismatches are terminal Step Functions
|
||
errors. Omit the selector—or use `"v1"`—to retain the prior wire contract.
|
||
|
||
## Chrome runtime
|
||
|
||
The package supports two Chromium sources:
|
||
|
||
| Source | Default | Size | When to pick it |
|
||
| ------------------------------- | ------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
|
||
| `@sparticuz/chromium` | yes | ~70 MiB compressed | Lambda. Decompresses into `/tmp` at runtime; the rest of the ecosystem already uses it for headless-Chrome-in-Lambda. |
|
||
| Bundled `chrome-headless-shell` | no | ~140 MiB | Fallback. Used if `@sparticuz/chromium` ever drops `HeadlessExperimental.beginFrame` support. |
|
||
|
||
Pick the source at build time:
|
||
|
||
```bash
|
||
bun run --cwd packages/aws-lambda build:zip
|
||
bun run --cwd packages/aws-lambda build:zip -- --source=chrome-headless-shell
|
||
```
|
||
|
||
The handler reads `HYPERFRAMES_LAMBDA_CHROME_SOURCE` at boot. The build
|
||
script sets that env var via Lambda function configuration in
|
||
`examples/aws-lambda/template.yaml`.
|
||
|
||
## BeginFrame regression guard
|
||
|
||
HyperFrames' renderer drives Chrome via the CDP
|
||
`HeadlessExperimental.beginFrame` command — same path the K8s deploy uses.
|
||
The Lambda adapter assumes that `@sparticuz/chromium`'s
|
||
chrome-headless-shell build honours BeginFrame. To prove it (and re-prove
|
||
it on every release), the package ships a Docker probe:
|
||
|
||
```bash
|
||
# Build the Lambda-like container and run the probe.
|
||
bun run --cwd packages/aws-lambda probe:beginframe:docker
|
||
```
|
||
|
||
The probe boots `@sparticuz/chromium` inside
|
||
`public.ecr.aws/lambda/nodejs:22` and asserts CDP `beginFrame` with
|
||
`screenshot: true` returns a PNG buffer. Exit code 0 = green; non-zero =
|
||
fall back to bundling chrome-headless-shell directly via `--source=chrome-headless-shell`.
|
||
|
||
## Building the ZIP
|
||
|
||
```bash
|
||
bun install # at the monorepo root
|
||
bun run --cwd packages/aws-lambda build:zip # → packages/aws-lambda/dist/handler.zip
|
||
bun run --cwd packages/aws-lambda verify:zip-size # CI gate
|
||
```
|
||
|
||
The build script bundles `src/handler.ts` via esbuild, stages
|
||
`@sparticuz/chromium` and `puppeteer-core` under `node_modules/`, copies
|
||
ffmpeg-static into `bin/`, and zips the result. The unzipped layout is
|
||
designed to extract cleanly into Lambda's `/var/task/`.
|
||
|
||
`verify:zip-size` enforces:
|
||
|
||
- Unzipped ≤ 248 MiB (in-house budget; Lambda hard ceiling is 250 MiB unzipped — AWS docs label this "250 MB" but use binary mebibytes)
|
||
- Zipped ≤ 150 MiB (in-house budget; Lambda has no hard zipped cap for S3-deployed functions)
|
||
|
||
CI fails the PR if either is exceeded.
|
||
|
||
## Running tests
|
||
|
||
```bash
|
||
bun run --cwd packages/aws-lambda test # unit tests (no Chrome)
|
||
bun run --cwd packages/aws-lambda probe:beginframe # local probe (Linux only)
|
||
```
|
||
|
||
## Using the SDK
|
||
|
||
After deploying the stack (via the SAM template, CDK construct below, or
|
||
your own CFN of choice), drive renders from Node:
|
||
|
||
```ts
|
||
import { deploySite, getRenderProgress, renderToLambda } from "@hyperframes/aws-lambda";
|
||
|
||
// One-time upload per project version.
|
||
const site = await deploySite({
|
||
projectDir: "./my-composition",
|
||
bucketName: "hyperframes-render-bucket",
|
||
});
|
||
|
||
// Start a render. Returns immediately — does NOT poll.
|
||
const handle = await renderToLambda({
|
||
siteHandle: site,
|
||
bucketName: site.bucketName,
|
||
stateMachineArn: "arn:aws:states:us-east-1:123:stateMachine:hyperframes-render",
|
||
config: {
|
||
fps: 30,
|
||
width: 1920,
|
||
height: 1080,
|
||
format: "mp4",
|
||
chunkSize: 240,
|
||
maxParallelChunks: 16,
|
||
runtimeCap: "lambda",
|
||
},
|
||
});
|
||
|
||
// Poll progress + cost on your own cadence.
|
||
const progress = await getRenderProgress({ executionArn: handle.executionArn });
|
||
console.log(progress.overallProgress, progress.costs.displayCost);
|
||
if (progress.status === "SUCCEEDED" && progress.outputFile) {
|
||
console.log("Render landed at", progress.outputFile.s3Uri);
|
||
}
|
||
```
|
||
|
||
`renderToLambda` validates the config client-side via
|
||
`validateDistributedRenderConfig` and throws a typed `InvalidConfigError`
|
||
before the Step Functions execution starts, so shape errors surface
|
||
synchronously instead of as opaque `ExecutionFailed` results.
|
||
|
||
`getRenderProgress` reports an approximate per-render cost
|
||
(`accruedSoFarUsd` plus a formatted `displayCost`) derived from Lambda
|
||
billed-duration × memory × the us-east-1 on-demand rate plus the Step
|
||
Functions transition price. The math is documented in
|
||
`src/sdk/costAccounting.ts`; numbers are best-effort and exclude S3
|
||
transfer.
|
||
|
||
## Using the CDK construct
|
||
|
||
```ts
|
||
import { App, Stack } from "aws-cdk-lib";
|
||
import { HyperframesRenderStack } from "@hyperframes/aws-lambda/cdk";
|
||
|
||
const app = new App();
|
||
const stack = new Stack(app, "MyApp");
|
||
const render = new HyperframesRenderStack(stack, "Render", {
|
||
// optional: reservedConcurrency: 8,
|
||
// optional: lambdaMemoryMb: 10240,
|
||
// optional: chromeSource: "sparticuz",
|
||
});
|
||
|
||
// Re-export so an adopter app can wire dashboards / SNS topics.
|
||
new CfnOutput(stack, "RenderBucketName", { value: render.bucket.bucketName });
|
||
new CfnOutput(stack, "StateMachineArn", { value: render.stateMachine.stateMachineArn });
|
||
```
|
||
|
||
`aws-cdk-lib` and `constructs` are **optional peer dependencies**: SDK-only
|
||
consumers don't pull them at runtime. The construct itself imports from
|
||
`@hyperframes/aws-lambda/cdk`.
|
||
|
||
## What's still ahead
|
||
|
||
- `hyperframes lambda` CLI (deploy / sites create / render / progress / destroy) — PR 6.5.
|
||
- IAM bootstrap subcommand (`policies role | user | validate`) — PR 6.9.
|
||
- Lambda-local regression harness (`--mode=lambda-local`) — PR 6.6.
|
||
- Adopter-facing migration guide — PR 6.8.
|