ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-10-30 17:27:09 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
fcd93ce1843556be4b95e0e133929c319e549609
hyperframes/examples/aws-lambda/template.yaml
T
Miguel Ángel 992df8b203 perf(cloud): move project bytes once through shared content storage (#5772) 
* perf(producer): distributed chunks download only the videos they show

A project video under compiled/ that chunks extract their own frames from
now goes only to the chunks that show it, like video-sources/ files. A
chunk skips the readiness wait for a deferred video it does not show, so
it no longer logs media_load_failed for a file it was never given.

* fix(producer): cloud site uploads pack the files their id hashes, symlinks included

* perf(aws-lambda): chunks read only the byte ranges of a video they need

A chunk that extracts its own frames from a deferred project video now
reads it from S3 by byte range through a short-lived pre-signed URL,
instead of downloading and hashing the whole object first. S3 attests the
object's stored SHA-256 before the URL is signed; every other artifact is
still downloaded and verified as before.

* perf(aws-lambda): upload project files once to a shared content-addressed area

* chore(producer): keep planV2 comment share at the base level

* fix(engine): verify the TLS certificate of https video inputs and never surface their signed query

* fix(aws-lambda): renders re-upload a site's expired files instead of failing

* perf(aws-lambda): the plan step probes project videos in place instead of downloading them

* fix(engine): https video reads reconnect and time out, and redaction covers wrapped causes

Signed-URL reads now pass -rw_timeout, -reconnect and -reconnect_delay_max (both Lambda builds accept them) and ffmpeg also -reconnect_on_network_error, so a transient S3 error or a stalled read fails fast or recovers instead of waiting out the process timeout. Query redaction now descends into error.cause.

* fix(aws-lambda): share entry bundles and ratchet package budget

* fix(aws-lambda): site ids uploaded before files.json still render

A site id from an earlier sites create has only sites/<id>/project.tar.gz.
renderToLambda now falls back to that tarball, which the plan step still
reads, and when neither key exists it fails before starting with both keys
named and the fix (run sites create again).

* fix(aws-lambda): renders fail before upload on a stack too old to read sites

A stack deployed before files.json sites untars the site file in its plan
step and fails after four retries. renderToLambda now reads the state
machine definition first and stops with STACK_TOO_OLD and the redeploy
command when the plan task does not list SITE_MANIFEST_INVALID, which new
SAM and CDK stacks now treat as terminal. The README's upgrade section
drops the planProtocol v1 fallback, which hits the same failure.

* docs(aws-lambda): document shared content storage and the upgrade path

The deploy guide still described the tarball HeadObject short-circuit. It
now covers the cas/sha256/ store and its 30-day lifecycle rule, the
STACK_TOO_OLD, SITE_FILES_MISSING and SITE_NOT_FOUND errors, that old site
ids keep working, and that every project uploads once more after the
upgrade. A test keeps a troubleshooting entry for each pre-submit error.

* fix(producer): chunks log each video they read by URL, without its query

A chunk reading a video straight from the bucket left no trace in its log.
It now logs one line per remote source with the path and the URL minus its
query string, so signatures never reach the log.

* fix(engine): ffmpeg errors never keep part of a signed URL's query

A process's stderr tail was trimmed before its URLs were redacted, so a
cut inside a signed URL left a query fragment the URL pattern no longer
matched, and the fragment reached the error. The stderr tail is now
redacted before every trim, and the redactor also strips a signing
parameter cut off from its URL.

* fix(aws-lambda): comments name the site manifest instead of a file path

* fix(engine): stderr redaction survives chunk splits, and every ffmpeg spawn uses it

The stderr tail was redacted on each chunk and then cut, so once a cut
severed a long URL's scheme, the rest of its signature in the next chunk
matched neither pattern. The tail is now kept raw with 2x slack and
redacted only when the text is produced, then cut to size. The unused
producer audioExtractor (its own spawn, unredacted stderr) is deleted and
the parity harness's PCM decode goes through ManagedChildProcess; a test
fails on any ffmpeg/ffprobe spawn in engine, producer or aws-lambda that
does not.

* chore(producer): record the audioExtractor deletion as intended

* fix(engine): drop a signature fragment the stderr tail cut from its URL

The raw tail is kept at twice the cap, but that cut can itself land inside a
signature, and when redaction shrinks the rest below the cap the fragment
survived. After a cut, the severed token is dropped before redaction.

* refactor(engine): name the severed-token drop instead of commenting it

* test(engine): a cut-off URL leaves nothing behind; aws-lambda size budget to measured

* fix(producer): chunk URL-read tests use main's frame list; producer size budget to measured

* chore(producer): size budget at the measured size, no headroom

* chore(producer): size budget back to measured x1.05, the check's own rule
2026-10-19 19:23:51 +00:00

783 lines
32 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
AWSTemplateFormatVersion: "2010-09-09"
Transform: AWS::Serverless-2016-10-31
Description: >-
HyperFrames distributed rendering — Step Functions standard workflow with
one Lambda function handling Plan, RenderChunk (fan-out via Map state),
and Assemble. One S3 bucket, alarms for runaway concurrency, Lambda
errors, and Step Functions execution failures.
Built from the handler ZIP at packages/aws-lambda/dist/handler.zip.
See:
- packages/aws-lambda/README.md (handler architecture)
- examples/aws-lambda/README.md (this directory's deploy guide)
Parameters:
ProjectName:
Type: String
Default: hyperframes
Description: Name prefix applied to all created resources.
LambdaMemoryMb:
Type: Number
Default: 10240
AllowedValues: [2048, 3072, 4096, 5120, 6144, 7168, 8192, 9216, 10240]
Description: >-
Lambda memory in MB. Render workloads are CPU-bound; bumping memory
proportionally bumps the CPU share Lambda gives the function. 10 GB
(the max) is recommended for 1080p renders.
LambdaTimeoutSec:
Type: Number
Default: 900
MinValue: 60
MaxValue: 900
Description: >-
Per-invocation Lambda timeout. Render chunks at the default
chunkSize=240 frames complete in seconds; 15 minutes is the Lambda
hard ceiling and the default here to absorb cold-start variance.
ReservedConcurrency:
Type: Number
Default: -1
Description: >-
Lambda reserved concurrency cap. Set to a positive integer to bound
simultaneous chunk renders (e.g. 50 to limit cost). -1 means
unreserved: each render runs up to 90% of the account's unreserved
concurrency.
ChromeSource:
Type: String
Default: sparticuz
AllowedValues: [sparticuz, chrome-headless-shell]
Description: >-
Which Chrome runtime the bundled ZIP was built with. Must match the
`--source=` flag passed to `build-zip.ts`. The handler reads this
via the HYPERFRAMES_LAMBDA_CHROME_SOURCE env var at boot.
ChunkInvocationAlarmThreshold:
Type: Number
Default: 1000
Description: >-
CloudWatch alarm threshold for total RenderChunk invocations per
hour. The runaway-Map state pathology would fan out far more
chunks than expected; an alarm at 10× the typical workload
protects against billing surprises.
Conditions:
HasReservedConcurrency: !Not [!Equals [!Ref ReservedConcurrency, -1]]
Globals:
Function:
Runtime: nodejs22.x
MemorySize: !Ref LambdaMemoryMb
Timeout: !Ref LambdaTimeoutSec
# x86_64 is required for @sparticuz/chromium — its prebuilt
# Chromium ships x86_64-only. Adopters who switch to a custom
# ARM-built chrome-headless-shell can change this to `arm64`, but
# the default ZIP build will fail to launch on Graviton.
Architectures: [x86_64]
# Lambda function-level X-Ray tracing. The state machine already
# has Tracing.Enabled: true; without this, X-Ray traces would
# terminate at the Step Functions → Lambda boundary instead of
# following into per-function spans.
Tracing: Active
# Cost-allocation tags. Setting these at the Globals level applies
# to every AWS::Serverless::Function in the template — there's
# only one today, but the contract is portable to multi-function
# variants. Bucket + state-machine carry the same tags resource-
# locally because Globals only covers functions.
Tags:
Project: !Ref ProjectName
HyperFramesComponent: lambda-renderer
Environment:
Variables:
NODE_OPTIONS: "--enable-source-maps"
HYPERFRAMES_LAMBDA_CHROME_SOURCE: !Ref ChromeSource
Resources:
# ── S3 bucket for plan tarballs, chunk outputs, and final renders ───────
RenderBucket:
Type: AWS::S3::Bucket
DeletionPolicy: Retain
UpdateReplacePolicy: Retain
Properties:
# BucketName omitted — CloudFormation generates a unique name like
# "<stack-name>-renderbucket-<random>". S3 bucket names are capped at
# 63 chars; a static !Sub expression including ProjectName +
# AWS::AccountId + AWS::Region trips that limit when ProjectName
# carries a timestamp (e.g. the smoke script's per-run stack name).
PublicAccessBlockConfiguration:
BlockPublicAcls: true
BlockPublicPolicy: true
IgnorePublicAcls: true
RestrictPublicBuckets: true
VersioningConfiguration:
# `Suspended` keeps storage costs flat — versions are not
# retained on overwrites. Tradeoff: if an adopter writes their
# final rendered mp4 to this bucket and a re-render overwrites
# the same key, the prior version is gone. Adopters who treat
# the final mp4 as user-keepable should set this to `Enabled`
# (intermediates under `renders/` still expire via the
# lifecycle rule below regardless).
Status: Suspended
LifecycleConfiguration:
Rules:
- Id: ExpireIntermediates
Status: Enabled
Prefix: renders/
# Plan tarballs and chunk outputs are intermediate artifacts.
# Users keep the final mp4 (different key prefix); the rest
# can age out after a week to keep storage costs flat.
ExpirationInDays: 7
- Id: ExpireSharedContent
Status: Enabled
Prefix: cas/sha256/
# Project files and plan artifacts by SHA-256, shared across renders.
ExpirationInDays: 30
Tags:
- Key: Project
Value: !Ref ProjectName
- Key: HyperFramesComponent
Value: lambda-renderer
# ── Single Lambda function handling all three roles ──────────────────────
RenderFunction:
Type: AWS::Serverless::Function
Properties:
FunctionName: !Sub "${ProjectName}-render"
Description: >-
HyperFrames distributed render handler. Dispatches on event.Action.
Handler: handler.handler
# Local path is resolved by `sam build` + `sam deploy --resolve-s3`
# (or `--s3-bucket`); the resulting CodeUri rewrites to s3://.
CodeUri: ../../packages/aws-lambda/dist/handler.zip
PackageType: Zip
ReservedConcurrentExecutions: !If
- HasReservedConcurrency
- !Ref ReservedConcurrency
- !Ref AWS::NoValue
EphemeralStorage:
Size: 10240
Environment:
Variables:
# Lambda's Node 22 runtime sets these by default; explicit for
# clarity + so users can override during local SAM invoke.
TMPDIR: /tmp
HYPERFRAMES_RENDER_BUCKET: !Ref RenderBucket
HYPERFRAMES_LAMBDA_RESERVED_CONCURRENCY: !Ref ReservedConcurrency
Policies:
- S3CrudPolicy:
BucketName: !Ref RenderBucket
- Statement:
- Effect: Allow
Action: s3:AbortMultipartUpload
Resource: !Sub "arn:${AWS::Partition}:s3:::${RenderBucket}/*"
# Plan sizes an unreserved render to the account's concurrency.
- Statement:
- Effect: Allow
Action: lambda:GetAccountSettings
Resource: "*"
# CloudWatch Logs perms are covered by SAM's default
# AWSLambdaBasicExecutionRole — explicit `CloudWatchLogsFullAccess`
# would be overscope (`logs:*` on `*`, including DeleteLogGroup +
# CreateExportTask). Reference templates shouldn't leak overbroad
# IAM into adopters' accounts.
# ── CloudWatch log group for the state machine ──────────────────────────
# SAM doesn't auto-create one when `LoggingConfiguration` is set, so we
# define it explicitly — that way the IAM grant on the state-machine
# role has a destination to write to.
RenderStateMachineLogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: !Sub "/aws/states/${ProjectName}-render"
RetentionInDays: 30
# ── Step Functions state machine: Plan → Map(N) RenderChunk → Assemble ──
RenderStateMachine:
Type: AWS::Serverless::StateMachine
Properties:
Name: !Sub "${ProjectName}-render"
Type: STANDARD
Tracing:
Enabled: true
Logging:
# Without this, the `WriteCloudwatchLogs` grant on the state
# machine role would be unused — operators would see zero
# execution history outside the Step Functions console.
# `Level: ERROR` keeps log volume low; bump to `ALL` for
# heavy debugging.
Level: ERROR
IncludeExecutionData: false
Destinations:
- CloudWatchLogsLogGroup:
LogGroupArn: !GetAtt RenderStateMachineLogGroup.Arn
Definition:
Comment: >-
HyperFrames distributed render orchestration: Plan → Map(N)
RenderChunk → Assemble.
# Defensive 1-hour ceiling on the whole choreography. The
# individual states already have retries + per-task timeouts;
# this catches pathological runaways (Plan-retry storm,
# stuck-state-machine bugs) at the top before per-task budgets
# compound into a multi-hour execution. The longest legitimate
# render observed in PR 880's eval was ~3 minutes.
TimeoutSeconds: 3600
StartAt: SelectPlanProtocol
States:
SelectPlanProtocol:
Type: Choice
Choices:
- Variable: $.PlanProtocol
StringEquals: v2
Next: PlanV2
- Variable: $.PlanProtocol
StringEquals: v1
Next: Plan
- Variable: $.PlanProtocol
IsPresent: true
Next: UnsupportedPlanProtocol
Default: PlanV2
UnsupportedPlanProtocol:
Type: Fail
Error: PLAN_PROTOCOL_UNSUPPORTED
Cause: PlanProtocol must be "v1", "v2", or absent (defaults to v2).
Plan:
Type: Task
Resource: arn:aws:states:::lambda:invoke
Parameters:
FunctionName: !GetAtt RenderFunction.Arn
Payload:
Action: plan
PlanProtocol: v1
ProjectS3Uri.$: "$.ProjectS3Uri"
PlanOutputS3Prefix.$: "$.PlanOutputS3Prefix"
Config.$: "$.Config"
ResultSelector:
PlanProtocol: v1
PlanS3Uri.$: "$.Payload.PlanS3Uri"
PlanHash.$: "$.Payload.PlanHash"
ChunkCount.$: "$.Payload.ChunkCount"
MaxChunkConcurrency.$: "$.Payload.MaxChunkConcurrency"
Format.$: "$.Payload.Format"
HasAudio.$: "$.Payload.HasAudio"
AudioS3Uri.$: "$.Payload.AudioS3Uri"
ResultPath: $.Plan
Retry:
- ErrorEquals:
# These error names are thrown by the producer's plan
# stage when retrying can never help — version skew,
# determinism violations, GPU misconfiguration, font
# fetch failures, plan-size cap, unsupported format.
# Fail fast rather than burning ~120s of retry budget.
- FFMPEG_VERSION_MISMATCH
- PLAN_HASH_MISMATCH
- BROWSER_GPU_NOT_SOFTWARE
- FONT_FETCH_FAILED
- PLAN_TOO_LARGE
- PlanTooLargeError
- PLAN_PROTOCOL_UNSUPPORTED
- PlanProtocolUnsupportedError
- VIDEO_SOURCE_UNRENDERABLE
- INVALID_VIDEO_METADATA
- NOT_MEDIA_PAYLOAD
- NotMediaPayloadError
- PLAN_ARTIFACT_DIGEST_MISMATCH
- FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
- CHUNK_EXCEEDS_WORKER_TIMEOUT
- SITE_MANIFEST_INVALID
MaxAttempts: 0
# Another render on the same function can still take the reserved slots; wait minutes.
- ErrorEquals: [Lambda.TooManyRequestsException]
IntervalSeconds: 5
MaxAttempts: 10
BackoffRate: 2
MaxDelaySeconds: 60
JitterStrategy: FULL
- ErrorEquals: [States.ALL]
IntervalSeconds: 2
MaxAttempts: 4
BackoffRate: 2
MaxDelaySeconds: 60
Next: BuildChunkList
PlanV2:
Type: Task
Resource: arn:aws:states:::lambda:invoke
Parameters:
FunctionName: !GetAtt RenderFunction.Arn
Payload:
Action: plan
PlanProtocol: v2
ProjectS3Uri.$: "$.ProjectS3Uri"
PlanOutputS3Prefix.$: "$.PlanOutputS3Prefix"
Config.$: "$.Config"
ResultSelector:
PlanProtocol: v2
PlanV2ManifestS3Uri.$: "$.Payload.PlanV2ManifestS3Uri"
PlanV2ArtifactS3Prefix.$: "$.Payload.PlanV2ArtifactS3Prefix"
PlanHash.$: "$.Payload.PlanHash"
ChunkCount.$: "$.Payload.ChunkCount"
MaxChunkConcurrency.$: "$.Payload.MaxChunkConcurrency"
Format.$: "$.Payload.Format"
HasAudio.$: "$.Payload.HasAudio"
ResultPath: $.Plan
Retry:
- ErrorEquals:
- FFMPEG_VERSION_MISMATCH
- PLAN_HASH_MISMATCH
- S3_URI_NOT_ALLOWED
- BROWSER_GPU_NOT_SOFTWARE
- FONT_FETCH_FAILED
- PLAN_TOO_LARGE
- PlanTooLargeError
- PLAN_PROTOCOL_UNSUPPORTED
- PlanProtocolUnsupportedError
- PLAN_V2_INTEGRITY_UNRECOVERABLE
- VIDEO_SOURCE_UNRENDERABLE
- INVALID_VIDEO_METADATA
- NOT_MEDIA_PAYLOAD
- NotMediaPayloadError
- PlanV2IntegrityError
- PLAN_ARTIFACT_DIGEST_MISMATCH
- FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
- CHUNK_EXCEEDS_WORKER_TIMEOUT
- ChromeBinaryUnavailableError
- SITE_MANIFEST_INVALID
MaxAttempts: 0
- ErrorEquals: [Lambda.TooManyRequestsException]
IntervalSeconds: 5
MaxAttempts: 10
BackoffRate: 2
MaxDelaySeconds: 60
JitterStrategy: FULL
- ErrorEquals: [States.ALL]
IntervalSeconds: 2
MaxAttempts: 4
BackoffRate: 2
MaxDelaySeconds: 60
Next: BuildChunkList
BuildChunkList:
# Translate ChunkCount into an array `[0, 1, ..., N-1]` so the
# Map state below has something to iterate. Range is the
# idiomatic Step Functions intrinsic for this; no Lambda call
# required.
Type: Pass
Parameters:
ChunkIndexes.$: "States.ArrayRange(0, States.MathAdd($.Plan.ChunkCount, -1), 1)"
ResultPath: $.Iterator
Next: AssertChunkCount
AssertChunkCount:
# Defensive gate: `resolveChunkPlan` guarantees ChunkCount ≥ 1,
# but if some future regression let a zero-chunk plan through,
# `RenderChunks` (Map state) would iterate zero times and
# `Assemble` would receive an empty `ChunkS3Uris` array — silently
# producing an empty output. Fail fast instead.
Type: Choice
Choices:
- Variable: $.Plan.ChunkCount
NumericGreaterThan: 0
Next: SelectWorkerProtocol
Default: PlanProducedZeroChunks
PlanProducedZeroChunks:
Type: Fail
Error: PLAN_TOO_LARGE
Cause: Plan returned ChunkCount=0 — non-retryable producer-side invariant violation.
SelectWorkerProtocol:
Type: Choice
Choices:
- Variable: $.Plan.PlanProtocol
StringEquals: v2
Next: RenderChunksV2
Default: RenderChunks
RenderChunks:
Type: Map
Label: RenderChunks
ItemsPath: $.Iterator.ChunkIndexes
ItemSelector:
ChunkIndex.$: "$$.Map.Item.Value"
PlanS3Uri.$: "$.Plan.PlanS3Uri"
PlanHash.$: "$.Plan.PlanHash"
ChunkOutputS3Prefix.$: "$.PlanOutputS3Prefix"
Format.$: "$.Plan.Format"
# Chunks past the plan's concurrency queue here instead of being throttled by Lambda.
MaxConcurrencyPath: $.Plan.MaxChunkConcurrency
ResultPath: $.Chunks
ItemProcessor:
ProcessorConfig:
# Inline Map runs at most 40 iterations at once. STANDARD children
# because EXPRESS ones stop at 5 minutes and a chunk may run 15.
Mode: DISTRIBUTED
ExecutionType: STANDARD
StartAt: RenderChunk
States:
RenderChunk:
Type: Task
Resource: arn:aws:states:::lambda:invoke
Parameters:
FunctionName: !GetAtt RenderFunction.Arn
Payload:
Action: renderChunk
PlanProtocol: v1
ChunkIndex.$: "$.ChunkIndex"
PlanS3Uri.$: "$.PlanS3Uri"
PlanHash.$: "$.PlanHash"
ChunkOutputS3Prefix.$: "$.ChunkOutputS3Prefix"
Format.$: "$.Format"
ResultSelector:
ChunkS3Uri.$: "$.Payload.ChunkS3Uri"
ChunkIndex.$: "$.Payload.ChunkIndex"
Sha256.$: "$.Payload.Sha256"
FramesEncoded.$: "$.Payload.FramesEncoded"
DurationMs.$: "$.Payload.DurationMs"
Retry:
- ErrorEquals:
- FFMPEG_VERSION_MISMATCH
- PLAN_HASH_MISMATCH
- BROWSER_GPU_NOT_SOFTWARE
- PLAN_TOO_LARGE
- PlanTooLargeError
- PLAN_PROTOCOL_UNSUPPORTED
- PlanProtocolUnsupportedError
- INVALID_VIDEO_METADATA
- PLAN_ARTIFACT_DIGEST_MISMATCH
MaxAttempts: 0
- ErrorEquals: [Lambda.TooManyRequestsException]
IntervalSeconds: 5
MaxAttempts: 10
BackoffRate: 2
MaxDelaySeconds: 60
JitterStrategy: FULL
- ErrorEquals: [States.ALL]
IntervalSeconds: 2
MaxAttempts: 4
BackoffRate: 2
MaxDelaySeconds: 60
End: true
Next: Assemble
Assemble:
Type: Task
Resource: arn:aws:states:::lambda:invoke
Parameters:
FunctionName: !GetAtt RenderFunction.Arn
Payload:
Action: assemble
PlanProtocol: v1
PlanS3Uri.$: "$.Plan.PlanS3Uri"
ChunkS3Uris.$: "$.Chunks[*].ChunkS3Uri"
AudioS3Uri.$: "$.Plan.AudioS3Uri"
OutputS3Uri.$: "$.OutputS3Uri"
Format.$: "$.Plan.Format"
ResultSelector:
OutputS3Uri.$: "$.Payload.OutputS3Uri"
FramesEncoded.$: "$.Payload.FramesEncoded"
FileSize.$: "$.Payload.FileSize"
ResultPath: $.Output
Retry:
- ErrorEquals:
# Same non-retryable error names as the Plan state's
# gate — these surface at assemble time too because
# ffmpeg-driven concat picks up version drift and we
# re-verify plan hash + format at assemble. Skip the
# retry storm; fail fast.
- FFMPEG_VERSION_MISMATCH
- PLAN_HASH_MISMATCH
- FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
- PLAN_TOO_LARGE
- PlanTooLargeError
- PLAN_PROTOCOL_UNSUPPORTED
- PlanProtocolUnsupportedError
- PLAN_ARTIFACT_DIGEST_MISMATCH
MaxAttempts: 0
- ErrorEquals: [Lambda.TooManyRequestsException]
IntervalSeconds: 5
MaxAttempts: 10
BackoffRate: 2
MaxDelaySeconds: 60
JitterStrategy: FULL
- ErrorEquals: [States.ALL]
IntervalSeconds: 2
MaxAttempts: 4
BackoffRate: 2
MaxDelaySeconds: 60
End: true
RenderChunksV2:
Type: Map
Label: RenderChunksV2
ItemsPath: $.Iterator.ChunkIndexes
ItemSelector:
ChunkIndex.$: "$$.Map.Item.Value"
PlanV2ManifestS3Uri.$: "$.Plan.PlanV2ManifestS3Uri"
PlanV2ArtifactS3Prefix.$: "$.Plan.PlanV2ArtifactS3Prefix"
PlanHash.$: "$.Plan.PlanHash"
ChunkOutputS3Prefix.$: "$.PlanOutputS3Prefix"
Format.$: "$.Plan.Format"
# Chunks past the plan's concurrency queue here instead of being throttled by Lambda.
MaxConcurrencyPath: $.Plan.MaxChunkConcurrency
ResultPath: $.Chunks
ItemProcessor:
ProcessorConfig:
Mode: DISTRIBUTED
ExecutionType: STANDARD
StartAt: RenderChunkV2
States:
RenderChunkV2:
Type: Task
Resource: arn:aws:states:::lambda:invoke
Parameters:
FunctionName: !GetAtt RenderFunction.Arn
Payload:
Action: renderChunk
PlanProtocol: v2
ChunkIndex.$: "$.ChunkIndex"
PlanV2ManifestS3Uri.$: "$.PlanV2ManifestS3Uri"
PlanV2ArtifactS3Prefix.$: "$.PlanV2ArtifactS3Prefix"
PlanHash.$: "$.PlanHash"
ChunkOutputS3Prefix.$: "$.ChunkOutputS3Prefix"
Format.$: "$.Format"
ResultSelector:
ChunkS3Uri.$: "$.Payload.ChunkS3Uri"
ChunkIndex.$: "$.Payload.ChunkIndex"
Sha256.$: "$.Payload.Sha256"
FramesEncoded.$: "$.Payload.FramesEncoded"
DurationMs.$: "$.Payload.DurationMs"
Retry:
- ErrorEquals:
- FFMPEG_VERSION_MISMATCH
- PLAN_HASH_MISMATCH
- S3_URI_NOT_ALLOWED
- BROWSER_GPU_NOT_SOFTWARE
- PLAN_TOO_LARGE
- PlanTooLargeError
- PLAN_PROTOCOL_UNSUPPORTED
- PlanProtocolUnsupportedError
- PLAN_V2_INTEGRITY_UNRECOVERABLE
- INVALID_VIDEO_METADATA
- PlanV2IntegrityError
- PLAN_ARTIFACT_DIGEST_MISMATCH
- ChromeBinaryUnavailableError
MaxAttempts: 0
- ErrorEquals: [Lambda.TooManyRequestsException]
IntervalSeconds: 5
MaxAttempts: 10
BackoffRate: 2
MaxDelaySeconds: 60
JitterStrategy: FULL
- ErrorEquals: [States.ALL]
IntervalSeconds: 2
MaxAttempts: 4
BackoffRate: 2
MaxDelaySeconds: 60
End: true
Next: AssembleV2
AssembleV2:
Type: Task
Resource: arn:aws:states:::lambda:invoke
Parameters:
FunctionName: !GetAtt RenderFunction.Arn
Payload:
Action: assemble
PlanProtocol: v2
PlanV2ManifestS3Uri.$: "$.Plan.PlanV2ManifestS3Uri"
PlanV2ArtifactS3Prefix.$: "$.Plan.PlanV2ArtifactS3Prefix"
PlanHash.$: "$.Plan.PlanHash"
ChunkS3Uris.$: "$.Chunks[*].ChunkS3Uri"
AudioS3Uri: null
OutputS3Uri.$: "$.OutputS3Uri"
Format.$: "$.Plan.Format"
ResultSelector:
OutputS3Uri.$: "$.Payload.OutputS3Uri"
FramesEncoded.$: "$.Payload.FramesEncoded"
FileSize.$: "$.Payload.FileSize"
ResultPath: $.Output
Retry:
- ErrorEquals:
- FFMPEG_VERSION_MISMATCH
- PLAN_HASH_MISMATCH
- S3_URI_NOT_ALLOWED
- FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED
- PLAN_TOO_LARGE
- PlanTooLargeError
- PLAN_PROTOCOL_UNSUPPORTED
- PlanProtocolUnsupportedError
- PLAN_V2_INTEGRITY_UNRECOVERABLE
- PlanV2IntegrityError
- PLAN_ARTIFACT_DIGEST_MISMATCH
- ChromeBinaryUnavailableError
MaxAttempts: 0
- ErrorEquals: [Lambda.TooManyRequestsException]
IntervalSeconds: 5
MaxAttempts: 10
BackoffRate: 2
MaxDelaySeconds: 60
JitterStrategy: FULL
- ErrorEquals: [States.ALL]
IntervalSeconds: 2
MaxAttempts: 4
BackoffRate: 2
MaxDelaySeconds: 60
End: true
Role: !GetAtt RenderStateMachineRole.Arn
RenderStateMachineRole:
Type: AWS::IAM::Role
Properties:
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal:
Service: states.amazonaws.com
Action: sts:AssumeRole
Policies:
- PolicyName: InvokeRenderFunction
PolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Action: lambda:InvokeFunction
Resource: !GetAtt RenderFunction.Arn
# A Distributed Map runs each chunk as a child execution of this state machine.
# ARNs built by name: !Ref RenderStateMachine here would be a dependency cycle.
- PolicyName: RunDistributedMapChildren
PolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Action: states:StartExecution
Resource: !Sub "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:stateMachine:${ProjectName}-render"
- Effect: Allow
Action:
- states:DescribeExecution
- states:StopExecution
Resource: !Sub "arn:${AWS::Partition}:states:${AWS::Region}:${AWS::AccountId}:execution:${ProjectName}-render:*"
- PolicyName: WriteCloudwatchLogs
PolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Action:
- logs:CreateLogDelivery
- logs:GetLogDelivery
- logs:UpdateLogDelivery
- logs:DeleteLogDelivery
- logs:ListLogDeliveries
- logs:PutResourcePolicy
- logs:DescribeResourcePolicies
- logs:DescribeLogGroups
Resource: "*"
- PolicyName: XRayTracing
PolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Action:
- xray:PutTraceSegments
- xray:PutTelemetryRecords
Resource: "*"
# ── CloudWatch alarm: runaway chunk invocations ─────────────────────────
RenderChunkInvocationAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmName: !Sub "${ProjectName}-runaway-chunk-invocations"
AlarmDescription: >-
Fires if RenderChunk Lambda invocations exceed the configured
threshold in a 1-hour window. The Map state's MaxConcurrency cap
protects against simultaneous fan-out, but a runaway state
machine that triggers many sequential renders would still rack
up cost; this alarm catches that pattern.
Namespace: AWS/Lambda
MetricName: Invocations
Dimensions:
- Name: FunctionName
Value: !Ref RenderFunction
Statistic: Sum
Period: 3600
EvaluationPeriods: 1
Threshold: !Ref ChunkInvocationAlarmThreshold
ComparisonOperator: GreaterThanThreshold
TreatMissingData: notBreaching
# ── CloudWatch alarm: Lambda function errors ────────────────────────────
# Fires on any non-zero error rate. The invocation alarm above catches
# *too many calls*; this catches *calls that failed*. Without it,
# silent per-chunk failures (a non-retryable error inside the
# producer) would only surface by reading Step Functions execution
# history.
RenderFunctionErrorsAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmName: !Sub "${ProjectName}-render-function-errors"
AlarmDescription: >-
Fires if the render Lambda reports any errors in a 5-minute
window. Set EvaluationPeriods=1 so a single failure pages.
Namespace: AWS/Lambda
MetricName: Errors
Dimensions:
- Name: FunctionName
Value: !Ref RenderFunction
Statistic: Sum
Period: 300
EvaluationPeriods: 1
Threshold: 1
ComparisonOperator: GreaterThanOrEqualToThreshold
TreatMissingData: notBreaching
# ── CloudWatch alarm: Step Functions execution failures ─────────────────
# Fires when a state-machine execution reaches a terminal failure
# state (typed non-retryable, retry-exhausted, or top-level timeout).
# Complementary to the Lambda Errors alarm: SFN failures include
# Choice-state Fail branches (PlanProducedZeroChunks) that bypass
# Lambda entirely, plus retry-exhaustion of transient errors that
# individual Lambda invocations counted as successful "retries".
RenderStateMachineFailedAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
AlarmName: !Sub "${ProjectName}-render-state-machine-failed"
AlarmDescription: >-
Fires when the render state machine reports a failed
execution. Catches retry-exhaustion + typed non-retryable +
TimeoutSeconds cases that the Lambda Errors metric misses.
Namespace: AWS/States
MetricName: ExecutionsFailed
Dimensions:
- Name: StateMachineArn
Value: !Ref RenderStateMachine
Statistic: Sum
Period: 300
EvaluationPeriods: 1
Threshold: 1
ComparisonOperator: GreaterThanOrEqualToThreshold
TreatMissingData: notBreaching
Outputs:
RenderBucketName:
Description: S3 bucket for plan tarballs, chunk outputs, and final renders.
Value: !Ref RenderBucket
Export:
Name: !Sub "${AWS::StackName}-RenderBucket"
RenderFunctionArn:
Description: ARN of the Lambda function. Pass to `aws lambda invoke` for local testing.
Value: !GetAtt RenderFunction.Arn
Export:
Name: !Sub "${AWS::StackName}-RenderFunctionArn"
RenderStateMachineArn:
Description: ARN of the Step Functions state machine. Pass to `aws stepfunctions start-execution`.
Value: !Ref RenderStateMachine
Export:
Name: !Sub "${AWS::StackName}-RenderStateMachineArn"
Reference in New Issue View Git Blame Copy Permalink