Files
hyperframes/packages/aws-lambda/src/sdk/renderToLambda.test.ts
T
James Russo 7f48a6894c feat!: remove Plan v1 distributed transport (#6970)
* feat!: remove Plan v1 distributed transport

BREAKING CHANGE: Cloud adapters accept only Plan v2; producer v1 exports are removed.

* ci: authorize Plan v1 cleanup deletions

* docs: avoid citing generated smoke result file

* fix(gcp): reject unsupported plan protocols in workflow

* ci: preserve gcp package size reduction

* fix: reject stale Plan v1 SDK options

* chore: remove retired Plan parity scripts
2026-11-02 04:13:57 +00:00

431 lines
15 KiB
TypeScript

import { afterEach, beforeEach, describe, expect, it } from "bun:test";
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { SFNClient } from "@aws-sdk/client-sfn";
import type { SerializableDistributedRenderConfig } from "../events.js";
import { SITE_MANIFEST_INVALID } from "../siteManifest.js";
import { asS3Client, FakeS3 } from "./__fixtures__/fakeS3.js";
import { deploySite, type SiteHandle, siteHandleFromId } from "./deploySite.js";
import { renderToLambda } from "./renderToLambda.js";
import { InvalidConfigError } from "./validateConfig.js";
interface CapturedStart {
stateMachineArn: string;
name: string;
input: unknown;
}
const CURRENT_DEFINITION = JSON.stringify({
States: { PlanV2: { Retry: [{ ErrorEquals: [SITE_MANIFEST_INVALID], MaxAttempts: 0 }] } },
});
class FakeSFN {
starts: CapturedStart[] = [];
describes = 0;
definition = CURRENT_DEFINITION;
async send(command: unknown): Promise<unknown> {
const cmdName = (command as { constructor: { name: string } }).constructor.name;
if (cmdName === "DescribeStateMachineCommand") {
this.describes++;
return { definition: this.definition };
}
if (cmdName === "StartExecutionCommand") {
const input = (command as { input: { stateMachineArn: string; name: string; input: string } })
.input;
this.starts.push({
stateMachineArn: input.stateMachineArn,
name: input.name,
input: JSON.parse(input.input),
});
return {
executionArn: `arn:aws:states:us-east-1:1234:execution:hf:${input.name}`,
startDate: new Date(),
};
}
throw new Error(`FakeSFN: unexpected command ${cmdName}`);
}
}
function asSFNClient(fake: { send(command: unknown): Promise<unknown> }): SFNClient {
return fake as unknown as SFNClient;
}
const baseConfig: SerializableDistributedRenderConfig = {
fps: 30,
width: 1280,
height: 720,
format: "mp4",
};
let projectDir: string;
beforeEach(() => {
projectDir = mkdtempSync(join(tmpdir(), "hf-render-test-"));
writeFileSync(join(projectDir, "index.html"), "<html></html>");
});
afterEach(() => {
rmSync(projectDir, { recursive: true, force: true });
});
describe("renderToLambda", () => {
it("rejects a stale v1 SDK option before any AWS work", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const staleOptions = {
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
planProtocol: "v1",
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
};
await expect(renderToLambda(staleOptions)).rejects.toMatchObject({
name: "PLAN_PROTOCOL_UNSUPPORTED",
});
expect(sfn.describes).toBe(0);
expect(sfn.starts).toHaveLength(0);
expect(s3.ops).toHaveLength(0);
});
it("returns a handle and starts a state-machine execution with the right input", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const handle = await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
executionName: "smoke-1",
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
expect(handle.renderId).toBe("smoke-1");
expect(handle.executionArn).toContain("smoke-1");
expect(handle.bucketName).toBe("test-bucket");
expect(handle.outputS3Uri).toBe("s3://test-bucket/renders/smoke-1/output.mp4");
expect(handle.projectS3Uri).toMatch(/^s3:\/\/test-bucket\/sites\/[0-9a-f]{16}\/files\.json$/);
expect(Object.keys(handle)).toEqual([
"renderId",
"executionArn",
"bucketName",
"stateMachineArn",
"outputS3Uri",
"projectS3Uri",
"startedAt",
]);
expect(sfn.starts).toHaveLength(1);
const start = sfn.starts[0]!;
expect(start.name).toBe("smoke-1");
expect(start.stateMachineArn).toBe("arn:aws:states:us-east-1:1234:stateMachine:hf");
expect(start.input).toEqual({
ProjectS3Uri: handle.projectS3Uri,
PlanOutputS3Prefix: "s3://test-bucket/renders/smoke-1/",
OutputS3Uri: "s3://test-bucket/renders/smoke-1/output.mp4",
Config: baseConfig,
PlanProtocol: "v2",
});
});
it("derives the file extension from config.format", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const handle = await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: { ...baseConfig, format: "mov" },
executionName: "smoke-mov",
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
expect(handle.outputS3Uri).toBe("s3://test-bucket/renders/smoke-mov/output.mov");
});
it("reuses a supplied siteHandle (no deploy)", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const prebuilt: SiteHandle = {
siteId: "prebaked",
bucketName: "test-bucket",
projectS3Uri: "s3://test-bucket/sites/prebaked/project.tar.gz",
bytes: 4096,
uploadedAt: "2026-05-16T00:00:00Z",
uploaded: true,
};
const handle = await renderToLambda({
siteHandle: prebuilt,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
executionName: "smoke-reuse",
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
expect(handle.projectS3Uri).toBe(prebuilt.projectS3Uri);
// No HEAD/PUT means s3.existing stayed empty.
expect(s3.existing.size).toBe(0);
});
it("refuses a stack deployed before files.json sites before uploading or starting", async () => {
const sfn = new FakeSFN();
sfn.definition = JSON.stringify({ States: { PlanV2: { Retry: [] } } });
const s3 = new FakeS3();
await expect(
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
}),
).rejects.toMatchObject({
name: "STACK_TOO_OLD",
message: expect.stringContaining("hyperframes lambda deploy"),
});
expect(s3.ops).toHaveLength(0);
expect(sfn.starts).toHaveLength(0);
});
describe("with a site id from before files.json", () => {
const renderSite = (s3: FakeS3, sfn: FakeSFN, siteId: string) =>
renderToLambda({
siteHandle: siteHandleFromId("test-bucket", siteId),
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
it("renders its project.tar.gz", async () => {
const s3 = new FakeS3();
const sfn = new FakeSFN();
s3.existing.add("test-bucket/sites/oldsite/project.tar.gz");
const handle = await renderSite(s3, sfn, "oldsite");
expect(handle.projectS3Uri).toBe("s3://test-bucket/sites/oldsite/project.tar.gz");
expect(sfn.starts[0]?.input).toMatchObject({ ProjectS3Uri: handle.projectS3Uri });
});
it("names both keys and the fix when neither exists, before starting", async () => {
const s3 = new FakeS3();
const sfn = new FakeSFN();
await expect(renderSite(s3, sfn, "gone")).rejects.toMatchObject({
name: "SITE_NOT_FOUND",
message: expect.stringMatching(
/sites\/gone\/files\.json.*sites\/gone\/project\.tar\.gz.*sites create/,
),
});
expect(sfn.starts).toHaveLength(0);
});
});
describe("with a site whose files expired from the content store", () => {
async function deployThenExpire(s3: FakeS3): Promise<{ site: SiteHandle; expiredKey: string }> {
const site = await deploySite({ projectDir, bucketName: "test-bucket", s3: asS3Client(s3) });
const expiredKey = [...s3.existing].find((id) => id.includes("/cas/sha256/"))!;
s3.existing.delete(expiredKey);
s3.ops.length = 0;
return { site, expiredKey };
}
const renderWith = (s3: FakeS3, sfn: FakeSFN, site: SiteHandle, dir?: string) =>
renderToLambda({
siteHandle: site,
projectDir: dir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
it("re-uploads the expired file from the project dir, then renders", async () => {
const s3 = new FakeS3();
const sfn = new FakeSFN();
const { site, expiredKey } = await deployThenExpire(s3);
await renderWith(s3, sfn, site, projectDir);
expect(
s3.ops.filter((op) => op.kind === "put").map((op) => `${op.bucket}/${op.key}`),
).toEqual([expiredKey]);
expect(sfn.starts).toHaveLength(1);
});
it("refuses when the project dir's copy differs or is gone, uploading nothing", async () => {
const s3 = new FakeS3();
const sfn = new FakeSFN();
const { site } = await deployThenExpire(s3);
writeFileSync(join(projectDir, "index.html"), "<html>edited</html>");
await expect(renderWith(s3, sfn, site, projectDir)).rejects.toMatchObject({
name: "SITE_FILES_MISSING",
});
rmSync(join(projectDir, "index.html"));
await expect(renderWith(s3, sfn, site, projectDir)).rejects.toMatchObject({
name: "SITE_FILES_MISSING",
});
expect(s3.ops.filter((op) => op.kind === "put")).toHaveLength(0);
expect(sfn.starts).toHaveLength(0);
});
it("without a project dir, refuses with the missing-file count before starting", async () => {
const s3 = new FakeS3();
const sfn = new FakeSFN();
const { site } = await deployThenExpire(s3);
await expect(renderWith(s3, sfn, site)).rejects.toMatchObject({
name: "SITE_FILES_MISSING",
message: expect.stringContaining("1 of 1 files"),
});
expect(sfn.starts).toHaveLength(0);
});
});
it("rejects invalid configs synchronously before any AWS call", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
try {
await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: { ...baseConfig, fps: 50 as never },
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
throw new Error("expected throw");
} catch (err) {
expect(err).toBeInstanceOf(InvalidConfigError);
}
expect(sfn.starts).toHaveLength(0);
});
it("requires either siteHandle or projectDir", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
await expect(
renderToLambda({
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
}),
).rejects.toThrow(/either siteHandle or projectDir/);
});
it("auto-generates an executionName when omitted", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const handle = await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
expect(handle.renderId).toMatch(/^hf-render-[0-9a-f-]{36}$/);
});
it("threads variables through the Step Functions execution input", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const variables = { title: "Hello Alice", accent: "#ff0000" };
await renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: { ...baseConfig, variables },
executionName: "smoke-variables",
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
});
expect(sfn.starts).toHaveLength(1);
const start = sfn.starts[0]!;
// The execution input carries the variables under Config.variables —
// the Step Functions state machine forwards `Config` verbatim into the
// PlanEvent's `Config` field, where the handler spreads it into the
// producer's DistributedRenderConfig.
const input = start.input as { Config: { variables?: Record<string, unknown> } };
expect(input.Config.variables).toEqual(variables);
});
it("rejects a config whose variables blob would push the execution input over 256 KiB", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
const huge = "x".repeat(260 * 1024);
await expect(
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: { ...baseConfig, variables: { blob: huge } },
executionName: "smoke-too-big",
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
}),
).rejects.toThrow(/256.*KiB|templates-on-lambda/);
// The reject must happen BEFORE StartExecution — uncaught oversize input
// surfaces as States.DataLimitExceeded 50ms in, far from this call site.
expect(sfn.starts).toHaveLength(0);
});
it("rejects a config whose variables contain non-JSON-safe values", async () => {
const sfn = new FakeSFN();
const s3 = new FakeS3();
await expect(
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: {
...baseConfig,
// BigInt would throw at JSON.stringify time; catch it at the validator
// boundary with a typed error instead.
variables: { count: 9_007_199_254_740_993n } as unknown as Record<string, unknown>,
},
executionName: "smoke-bigint",
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
}),
).rejects.toThrow(InvalidConfigError);
expect(sfn.starts).toHaveLength(0);
});
it("has a troubleshooting entry for every error it raises before starting", () => {
const docs = readFileSync(
new URL("../../../../docs/deploy/aws-lambda.mdx", import.meta.url),
"utf8",
);
for (const name of ["STACK_TOO_OLD", "SITE_FILES_MISSING", "SITE_NOT_FOUND"]) {
expect({ name, documented: new RegExp(`^### .*\`${name}\``, "m").test(docs) }).toEqual({
name,
documented: true,
});
}
});
it("propagates a missing executionArn as an error", async () => {
const sfn = {
async send(_cmd: unknown): Promise<unknown> {
return { executionArn: undefined, definition: CURRENT_DEFINITION };
},
};
const s3 = new FakeS3();
await expect(
renderToLambda({
projectDir,
bucketName: "test-bucket",
stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
config: baseConfig,
sfn: asSFNClient(sfn),
s3: asS3Client(s3),
}),
).rejects.toThrow(/no executionArn/);
});
});