Skip to content

Commit 17a2a00

Browse files
authored
feat(cloud): default distributed plans to v2 (#3311)
* feat(cloud): default distributed plans to v2 * fix(cloud): address plan v2 review feedback * fix(examples): document explicit v2 samples
1 parent 6b17c24 commit 17a2a00

36 files changed

Lines changed: 403 additions & 143 deletions

‎docs/packages/aws-lambda.mdx‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,6 @@ const site = await deploySite({
7070

7171
const handle = await renderToLambda({
7272
siteHandle: site,
73-
planProtocol: "v2",
7473
bucketName: site.bucketName,
7574
stateMachineArn: "arn:aws:states:us-east-1:123456789012:stateMachine:hyperframes-render",
7675
config: {
@@ -88,10 +87,17 @@ const progress = await getRenderProgress({ executionArn: handle.executionArn });
8887
console.log(progress.status, progress.overallProgress, progress.costs.displayCost);
8988
```
9089

91-
Plan v2 is recommended for new integrations because workers fetch
92-
manifest-selected content-addressed artifacts. For backwards compatibility,
93-
omitting `planProtocol` still selects v1; existing callers do not change
94-
behavior until they opt in.
90+
Plan v2 is the default because workers fetch manifest-selected
91+
content-addressed artifacts. The SDK sends explicit v2 when `planProtocol` is
92+
omitted. Deprecated v1 compatibility remains available by passing
93+
`planProtocol: "v1"`.
94+
95+
<Warning>
96+
For an existing installation, pause new renders and drain active Step
97+
Functions executions. Redeploy the Lambda handler and SAM/CDK state machine
98+
from the same package version before upgrading the application SDK. Older
99+
infrastructure may default omission to v1 or lack v2 support.
100+
</Warning>
95101

96102
`renderToLambda()` validates the distributed render config before starting the Step Functions execution, so invalid dimensions, formats, chunk sizes, or payload sizes fail synchronously.
97103

‎docs/packages/gcp-cloud-run.mdx‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,6 @@ import { getRenderProgress, renderToCloudRun } from "@hyperframes/gcp-cloud-run/
7979

8080
const handle = await renderToCloudRun({
8181
projectDir: "./my-composition",
82-
planProtocol: "v2",
8382
config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
8483
bucketName: "hyperframes-render-my-project",
8584
projectId: "my-project",
@@ -97,10 +96,17 @@ while (progress.status === "running") {
9796
console.log(progress.status, progress.outputFile, progress.costs.displayCost);
9897
```
9998

100-
Plan v2 is recommended for new integrations because workers fetch
101-
manifest-selected content-addressed artifacts. For backwards compatibility,
102-
omitting `planProtocol` still selects v1; existing callers do not change
103-
behavior until they opt in.
99+
Plan v2 is the default because workers fetch manifest-selected
100+
content-addressed artifacts. The SDK sends explicit v2 when `planProtocol` is
101+
omitted. Deprecated v1 compatibility remains available by passing
102+
`planProtocol: "v1"`.
103+
104+
<Warning>
105+
For an existing installation, pause new renders and drain active workflow
106+
executions. Redeploy the Cloud Run image and Cloud Workflows definition from
107+
the same package version before upgrading the application SDK. Older
108+
workflows may default omission to v1 or lack v2 support.
109+
</Warning>
104110

105111
Pass `projectDir` for one-shot uploads, or call `deploySite()` separately and reuse the returned site handle across many renders.
106112

‎examples/aws-lambda/README.md‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,6 @@ aws stepfunctions start-execution \
7575
"ProjectS3Uri": "s3://${RENDER_BUCKET}/projects/my-project.tar.gz",
7676
"PlanOutputS3Prefix": "s3://${RENDER_BUCKET}/renders/$(date +%s)/",
7777
"OutputS3Uri": "s3://${RENDER_BUCKET}/output.mp4",
78-
"PlanProtocol": "v2",
7978
"Config": {
8079
"fps": 30,
8180
"width": 1920,
@@ -92,10 +91,20 @@ EOF
9291

9392
The Step Functions execution kicks off Plan, fans out RenderChunk via
9493
the Map state, and finally Assemble. Final mp4 lands at `OutputS3Uri`.
95-
Plan v2 is recommended for new integrations. `PlanProtocol` may be `"v1"` or
96-
`"v2"`; absent still defaults to v1 for backwards compatibility. V2 uses
97-
separate manifest and content-addressed artifact locators throughout the
98-
workflow and never places a v2 object in `PlanS3Uri`.
94+
Plan v2 is the default when `PlanProtocol` is absent. V2 uses separate
95+
manifest and content-addressed artifact locators throughout the workflow and
96+
never places a v2 object in `PlanS3Uri`. The deprecated v1 transport remains
97+
available by sending `"PlanProtocol": "v1"` explicitly.
98+
99+
### Upgrading an existing stack
100+
101+
Pause new renders and let active Step Functions executions drain before the
102+
upgrade. Redeploy the Lambda handler and this state machine (or the matching
103+
CDK construct) from the same package version before upgrading the application
104+
that calls `renderToLambda`. The new SDK sends explicit v2 by default, while
105+
older infrastructure may default omission to v1 or lack v2 support. Keep
106+
passing `planProtocol: "v1"` until the infrastructure redeploy completes if
107+
you need a staged migration.
99108

100109
## Local invocation
101110

@@ -112,10 +121,13 @@ sam validate
112121
sam local invoke RenderFunction --event sample-events/plan.json
113122
```
114123

115-
The `sample-events/` directory ships small JSON payloads for each of the
116-
three actions. They reference fake S3 URIs — useful for sanity-checking
117-
the handler's dispatch logic; not for full end-to-end testing (real S3
118-
calls require credentials and a project zip to actually exist).
124+
The `sample-events/` directory ships three tiers for each action:
125+
`*.json` demonstrates default v2 with `PlanProtocol` omitted, `*-v1.json`
126+
demonstrates deprecated explicit-v1 compatibility, and `*-v2.json`
127+
demonstrates callers that stamp v2 explicitly. They reference fake S3 URIs —
128+
useful for sanity-checking the handler's dispatch logic; not for full
129+
end-to-end testing (real S3 calls require credentials and a project zip to
130+
actually exist).
119131

120132
## End-to-end smoke + benchmark
121133

@@ -124,7 +136,7 @@ the architecture works on a deployed Lambda — use the local smoke
124136
script:
125137

126138
```bash
127-
# Defaults use the fixture's meta.json minPsnr (30 dB for mp4-h264-sdr).
139+
# Defaults use Plan v2 and the fixture's meta.json minPsnr (30 dB for mp4-h264-sdr).
128140
./scripts/smoke.sh
129141

130142
# Customised:
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"Action": "assemble",
3+
"PlanProtocol": "v1",
4+
"PlanS3Uri": "s3://example-bucket/renders/sample/plan.tar.gz",
5+
"ChunkS3Uris": [
6+
"s3://example-bucket/renders/sample/chunks/0000.mp4",
7+
"s3://example-bucket/renders/sample/chunks/0001.mp4"
8+
],
9+
"AudioS3Uri": null,
10+
"OutputS3Uri": "s3://example-bucket/renders/sample/output.mp4",
11+
"Format": "mp4"
12+
}

‎examples/aws-lambda/sample-events/assemble.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
{
22
"Action": "assemble",
3-
"PlanS3Uri": "s3://example-bucket/renders/sample/plan.tar.gz",
3+
"PlanV2ManifestS3Uri": "s3://example-bucket/renders/sample/v2/manifest.json",
4+
"PlanV2ArtifactS3Prefix": "s3://example-bucket/renders/sample/v2/artifacts/sha256",
5+
"PlanHash": "0000000000000000000000000000000000000000000000000000000000000000",
46
"ChunkS3Uris": [
57
"s3://example-bucket/renders/sample/chunks/0000.mp4",
68
"s3://example-bucket/renders/sample/chunks/0001.mp4",
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"Action": "plan",
3+
"PlanProtocol": "v1",
4+
"ProjectS3Uri": "s3://example-bucket/projects/sample.tar.gz",
5+
"PlanOutputS3Prefix": "s3://example-bucket/renders/sample/",
6+
"Config": {
7+
"fps": 30,
8+
"width": 1920,
9+
"height": 1080,
10+
"format": "mp4",
11+
"chunkSize": 240,
12+
"maxParallelChunks": 8,
13+
"runtimeCap": "lambda"
14+
}
15+
}

‎examples/aws-lambda/sample-events/plan.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"Action": "plan",
3-
"ProjectS3Uri": "s3://example-bucket/projects/sample-composition.tar.gz",
3+
"ProjectS3Uri": "s3://example-bucket/projects/sample.tar.gz",
44
"PlanOutputS3Prefix": "s3://example-bucket/renders/sample/",
55
"Config": {
66
"fps": 30,
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"Action": "renderChunk",
3+
"PlanProtocol": "v1",
4+
"PlanS3Uri": "s3://example-bucket/renders/sample/plan.tar.gz",
5+
"PlanHash": "0000000000000000000000000000000000000000000000000000000000000000",
6+
"ChunkIndex": 0,
7+
"ChunkOutputS3Prefix": "s3://example-bucket/renders/sample/",
8+
"Format": "mp4"
9+
}

‎examples/aws-lambda/sample-events/render-chunk.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"Action": "renderChunk",
3-
"PlanS3Uri": "s3://example-bucket/renders/sample/plan.tar.gz",
3+
"PlanV2ManifestS3Uri": "s3://example-bucket/renders/sample/v2/manifest.json",
4+
"PlanV2ArtifactS3Prefix": "s3://example-bucket/renders/sample/v2/artifacts/sha256",
45
"PlanHash": "0000000000000000000000000000000000000000000000000000000000000000",
56
"ChunkIndex": 0,
67
"ChunkOutputS3Prefix": "s3://example-bucket/renders/sample/",

‎examples/aws-lambda/scripts/smoke.sh‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
# --region <region> (default: $AWS_REGION or us-east-1)
3232
# --profile <name> (default: $AWS_PROFILE, otherwise the AWS
3333
# default profile resolution chain)
34-
# --plan-protocol <v1|v2|both> (default: v1)
34+
# --plan-protocol <v1|v2|both> (default: v2)
3535
# --keep-stack (skip `sam delete` at the end)
3636
# --skip-build (skip the ZIP rebuild; use the existing one)
3737
#
@@ -82,7 +82,7 @@ SMOKE_RUN_ID="${HYPERFRAMES_SMOKE_RUN_ID:-$(hf_new_smoke_run_id)}"
8282
STACK_NAME="${STACK_NAME:-hyperframes-lambda-smoke-${SMOKE_RUN_ID}}"
8383
AWS_REGION="${AWS_REGION:-us-east-1}"
8484
AWS_PROFILE="${AWS_PROFILE:-}"
85-
PLAN_PROTOCOL="${PLAN_PROTOCOL:-v1}"
85+
PLAN_PROTOCOL="${PLAN_PROTOCOL:-v2}"
8686
KEEP_STACK="false"
8787
SKIP_BUILD="false"
8888
REQUIRE_ENCODED_SHA_EQUAL="${REQUIRE_ENCODED_SHA_EQUAL:-false}"
@@ -110,7 +110,7 @@ Flags:
110110
--stack-name <name> SAM stack name (default: hyperframes-lambda-smoke-<unique-run-id>)
111111
--region <region> AWS region (default: $AWS_REGION or us-east-1)
112112
--profile <name> AWS profile (default: $AWS_PROFILE)
113-
--plan-protocol <v1|v2|both> plan transport(s) to compare (default: v1)
113+
--plan-protocol <v1|v2|both> plan transport(s) to compare (default: v2)
114114
--reserved-concurrency <N> Lambda Map MaxConcurrency cap (default: 16)
115115
--keep-stack skip `sam delete` at the end (manual teardown later)
116116
--require-encoded-sha-equal also gate byte-identical encoded MP4 output

0 commit comments

Comments
 (0)