mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 12:54:29 +00:00
James Russo
34d1f0e1d0
* feat(lambda): add TypeScript SDK and CDK construct
Adds the client-side surface on top of the Phase 6a Lambda handler so
adopters can drive a deployed stack from Node without writing AWS-SDK
boilerplate:
- renderToLambda(opts) starts a Step Functions execution and returns a
handle. Does NOT poll.
- getRenderProgress({ executionArn }) returns a snapshot of progress,
frames rendered, cost (Lambda GB-seconds + SFN transitions), errors,
and the final output object once Assemble completes.
- deploySite({ projectDir, bucketName }) content-addresses the project
tree, tar.gzs it, and uploads to S3 with a HeadObject short-circuit so
re-renders of the same tree skip the tar+PUT.
- validateDistributedRenderConfig throws a typed InvalidConfigError
before StartExecution, so shape errors surface synchronously.
- computeRenderCost is exposed for callers who want to format cost out
of band.
Also ships HyperframesRenderStack, an aws-cdk-lib L2 construct that
emits the same topology as examples/aws-lambda/template.yaml. Lives on
the ./cdk subpath export so SDK-only consumers don't pull aws-cdk-lib
into their runtime graph (declared as an optional peer dependency).
Tests: 24 new unit tests across the SDK plus 9 CDK synth / contract /
snapshot tests. All 83 tests in packages/aws-lambda/src pass.
* refactor(lambda): /simplify pass on the SDK + CDK PR
Pulls shared logic out so the SDK doesn't re-invent things the handler
and the producer already have:
- `formatExtension` extracted to packages/aws-lambda/src/formatExtension.ts.
handler.ts and renderToLambda.ts both used identical 12-line copies of
this switch.
- `PLAN_PROJECT_DIR_SKIP_SEGMENTS` is now exported from
@hyperframes/producer/distributed. deploySite consumes it instead of
its own duplicate SKIP_TOP_LEVEL set; the two lists were trivially
identical and would have drifted silently.
- `FakeS3` + `drainBody` factored out of the two SDK test files into
src/sdk/__fixtures__/fakeS3.ts. Drops ~110 lines of test-file
duplication and gives future SDK tests a one-line FakeS3 import.
- S3 URI building in deploySite and renderToLambda routes through the
existing `formatS3Uri` helper instead of inline `s3://...`
concatenation; matches the convention already in handler.ts.
Net -133 lines across the touched files. All 83 aws-lambda tests still
pass; all 60 producer distributed tests still pass.
* fix(lambda): bump CDK test timeouts for CI cold-start synth
The bun:test default 5s timeout tripped the first CDK snapshot test
in CI when the cold-start `Template.fromStack(stack)` synth took ~5-8s
on the slowest GitHub Actions runner. Locally on a warm shell the
synth measures <1s, so the failure didn't reproduce until PR #909 hit
CI.
Two changes:
- Both CDK test files cache one synth in `beforeAll(..., 30000)` and
reuse the result across every test that uses the default props.
Each individual test now runs in microseconds (pure assertions
against the already-synthed template), so the 5s timeout no longer
applies on the hot path.
- The two contract tests that exercise non-default props
(reservedConcurrency, projectName) still synth fresh per-test; they
get a per-test `it(..., 30000)` timeout.
No behavior changes.
* fix(lambda): address PR review on SDK + CDK construct
Three correctness + ergonomics fixes raised in Vai's review:
- getRenderProgress over-counted SFN transitions by 3-5×. Step
Functions Standard Workflows bill per state-entry, not per
history event. Each Task produces ~5-7 history events
(Scheduled / Started / Succeeded / TaskStateExited / …);
counting `events.length` reported the runaway. Switch to
counting `*StateEntered` events explicitly.
- assembleComplete + outputFile detection was coupled to the
Lambda payload's `Action` field. Move both signals onto the
enclosing state name (`StateExited.name === "Assemble"`), which
is the state-machine identity rather than the Lambda event
contract. framesRendered increment moves to the same boundary
(RenderChunk state).
- SiteHandle now carries `bucketName` directly so README + CLI
callers don't have to re-parse `projectS3Uri.split("/")[2]`.
Test updates: getRenderProgress tests wrap renderChunk/assemble
events in matching StateEntered + StateExited pairs so the new
state-name-driven dispatch is exercised end-to-end. SiteHandle
fixture in renderToLambda.test.ts gets the new bucketName field.
All 83 aws-lambda tests still pass.
79 lines
2.6 KiB
TypeScript
79 lines
2.6 KiB
TypeScript
/**
|
|
* `@hyperframes/aws-lambda` — Lambda adapter for the HyperFrames
|
|
* distributed render pipeline.
|
|
*
|
|
* Two surfaces, one package:
|
|
*
|
|
* - **Server-side handler.** `handler`, the Step Functions event/result
|
|
* types, Chrome resolution, and S3 transport. These power the Lambda
|
|
* function bundled into `dist/handler.zip`.
|
|
* - **Client-side SDK.** `renderToLambda`, `getRenderProgress`,
|
|
* `deploySite`, `validateDistributedRenderConfig`, and `computeRenderCost`.
|
|
* Adopters call these from their Node process (CI scripts, CLIs, CDK
|
|
* pipelines) to drive a deployed stack without writing AWS-SDK
|
|
* boilerplate.
|
|
*
|
|
* The CDK L2 construct lives at the `./cdk` subpath export so SDK-only
|
|
* consumers don't pull `aws-cdk-lib` into their runtime graph:
|
|
*
|
|
* import { HyperframesRenderStack } from "@hyperframes/aws-lambda/cdk";
|
|
*
|
|
* The package is NOT a dependency of `@hyperframes/producer`; consumers
|
|
* install it separately.
|
|
*/
|
|
|
|
export { handler, type HandlerDeps, unwrapEvent } from "./handler.js";
|
|
export {
|
|
type AssembleEvent,
|
|
type AssembleLambdaResult,
|
|
type LambdaAction,
|
|
type LambdaEvent,
|
|
type LambdaResult,
|
|
type PlanEvent,
|
|
type PlanLambdaResult,
|
|
type RenderChunkEvent,
|
|
type RenderChunkLambdaResult,
|
|
type SerializableDistributedRenderConfig,
|
|
} from "./events.js";
|
|
// `_setSparticuzChromiumForTests` is intentionally NOT re-exported from
|
|
// the package barrel — it's a test-only DI seam. Test files import it
|
|
// directly from `./chromium.js`.
|
|
export {
|
|
type ChromeSource,
|
|
resolveChromeArgs,
|
|
resolveChromeExecutablePath,
|
|
resolveChromeSource,
|
|
} from "./chromium.js";
|
|
export {
|
|
downloadS3ObjectToFile,
|
|
formatS3Uri,
|
|
parseS3Uri,
|
|
type S3Location,
|
|
tarDirectory,
|
|
untarDirectory,
|
|
uploadFileToS3,
|
|
} from "./s3Transport.js";
|
|
|
|
// ── Client-side SDK ─────────────────────────────────────────────────────────
|
|
export { deploySite, type DeploySiteOptions, type SiteHandle } from "./sdk/deploySite.js";
|
|
export {
|
|
renderToLambda,
|
|
type RenderHandle,
|
|
type RenderToLambdaOptions,
|
|
} from "./sdk/renderToLambda.js";
|
|
export {
|
|
getRenderProgress,
|
|
type GetRenderProgressOptions,
|
|
type RenderError,
|
|
type RenderProgress,
|
|
type RenderStatus,
|
|
} from "./sdk/getRenderProgress.js";
|
|
export {
|
|
type BilledLambdaInvocation,
|
|
computeRenderCost,
|
|
type RenderCost,
|
|
} from "./sdk/costAccounting.js";
|
|
export { InvalidConfigError, validateDistributedRenderConfig } from "./sdk/validateConfig.js";
|
|
// The CDK construct is exported separately via the `./cdk` subpath so
|
|
// SDK-only consumers don't pay the `aws-cdk-lib` import cost.
|