Files
hyperframes/packages/aws-lambda/src/sdk/renderToLambda.ts
T
James RussoandClaude Opus 5.5 39347da9de fix(cli): leave files from outside the project out of Lambda and Cloud Run site uploads (#8060)
* fix(cli): leave files from outside the project out of Lambda and Cloud Run site uploads

A site upload for `lambda` or `cloudrun` followed every symlink in the project and
shipped what it pointed at, wherever that was on the machine. `publish` and `cloud
render` already ask first. Site uploads now leave a file or folder linked in from
outside the project out and name each one; `--include-outside-files` (or
`includeOutsideFiles` in the SDK's deploySite, renderToLambda and renderToCloudRun)
uploads them. publishProjectArchive called without a prepared archive now leaves
outside files out too, since nothing approved them.

— Rames

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(producer): drop the new option comments the comment ratchet refuses

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 09:25:25 +00:00

190 lines
7.3 KiB
TypeScript

/**
* `renderToLambda` — start a distributed render against an already-deployed
* SAM/CDK stack and return a handle the caller can poll with
* {@link getRenderProgress}.
*
* The function does *not* wait for the render to finish. Step Functions
* standard workflows can run for hours; blocking the caller's process on
* the SFN execution is the wrong default. The returned `RenderHandle`
* carries everything the progress / cost / download paths need.
*
* Wire order:
* 1. Validate config (typed throw before any AWS call).
* 2. `deploySite` if no `siteHandle` was provided.
* 3. `StartExecution` against the state machine with the same input
* shape `examples/aws-lambda/scripts/smoke.sh` builds.
* 4. Return handle. The S3 `outputKey` is deterministic from the
* execution name so the caller can predict the final object URL.
*/
import { randomUUID } from "node:crypto";
import { DescribeStateMachineCommand, SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
import { S3Client } from "@aws-sdk/client-s3";
import type { SerializableDistributedRenderConfig } from "../events.js";
import { formatExtension } from "../formatExtension.js";
import { formatS3Uri } from "../s3Transport.js";
import { SITE_MANIFEST_INVALID } from "../siteManifest.js";
import { parseStateMachineArn, pinBucketOwner } from "./bucketOwner.js";
import { deploySite, ensureSiteStored, type SiteHandle } from "./deploySite.js";
import {
validateDistributedRenderConfig,
validateStepFunctionsInputSize,
} from "./validateConfig.js";
/** Options for {@link renderToLambda}. */
export interface RenderToLambdaOptions {
/** Local project directory. Required without `siteHandle`; with one, re-uploads expired files. */
projectDir?: string;
/** Re-use an existing `deploySite` upload (skips tar+S3 PUT). */
siteHandle?: SiteHandle;
onNotice?: (message: string) => void;
includeOutsideFiles?: boolean;
/** Validated `SerializableDistributedRenderConfig` (no logger / abortSignal). */
config: SerializableDistributedRenderConfig;
/** S3 bucket from the SAM stack output (`RenderBucketName`). */
bucketName: string;
/** State machine ARN from the SAM stack output (`RenderStateMachineArn`). */
stateMachineArn: string;
/** AWS region; defaults to the SDK default chain. */
region?: string;
/**
* Final output S3 key. Defaults to `renders/<executionName>/output.<ext>`
* where `<ext>` is derived from `config.format`.
*/
outputKey?: string;
/**
* Step Functions execution name. Defaults to `hf-render-<uuid>`.
* Used as `renderId` everywhere downstream (history queries, cost
* accounting, predictable S3 key prefix).
*/
executionName?: string;
/** Test injection seam — production callers leave unset. */
sfn?: SFNClient;
/** Test injection seam — propagated to `deploySite` when applicable. */
s3?: S3Client;
}
/** Stable identifier + every URL/ARN the caller needs to follow the render. */
export interface RenderHandle {
/** Same as the Step Functions execution name. */
renderId: string;
/** Full execution ARN; pass to {@link getRenderProgress}. */
executionArn: string;
bucketName: string;
stateMachineArn: string;
outputS3Uri: string;
projectS3Uri: string;
startedAt: string;
}
function rejectUnsupportedLegacyPlanProtocol(opts: object): void {
const planProtocol = Reflect.get(opts, "planProtocol");
if (planProtocol === undefined || planProtocol === "v2") return;
const error = new Error(
`[renderToLambda] planProtocol is no longer configurable; expected "v2" or absent, got ${JSON.stringify(planProtocol)}`,
);
error.name = "PLAN_PROTOCOL_UNSUPPORTED";
throw error;
}
// fallow-ignore-next-line complexity
export async function renderToLambda(opts: RenderToLambdaOptions): Promise<RenderHandle> {
rejectUnsupportedLegacyPlanProtocol(opts);
validateDistributedRenderConfig(opts.config);
if (!opts.bucketName) {
throw new Error("[renderToLambda] bucketName is required");
}
if (!opts.stateMachineArn) {
throw new Error("[renderToLambda] stateMachineArn is required");
}
if (!opts.siteHandle && !opts.projectDir) {
throw new Error("[renderToLambda] either siteHandle or projectDir must be supplied");
}
const { account } = parseStateMachineArn(opts.stateMachineArn);
const sfn = opts.sfn ?? new SFNClient({ region: opts.region });
await assertStackReadsSites({ stateMachineArn: opts.stateMachineArn, sfn });
const s3 = pinBucketOwner(opts.s3 ?? new S3Client({ region: opts.region }), account);
const executionName = opts.executionName ?? `hf-render-${randomUUID()}`;
const ext = formatExtension(opts.config.format);
const outputKey = opts.outputKey ?? `renders/${executionName}/output${ext}`;
const planOutputS3Prefix = formatS3Uri({
bucket: opts.bucketName,
key: `renders/${executionName}/`,
});
const outputS3Uri = formatS3Uri({ bucket: opts.bucketName, key: outputKey });
const site = opts.siteHandle
? await ensureSiteStored(opts.siteHandle, s3, opts.projectDir)
: await deploySite({
projectDir: opts.projectDir as string,
bucketName: opts.bucketName,
region: opts.region,
onNotice: opts.onNotice,
includeOutsideFiles: opts.includeOutsideFiles,
s3,
});
const input = {
ProjectS3Uri: site.projectS3Uri,
PlanOutputS3Prefix: planOutputS3Prefix,
OutputS3Uri: outputS3Uri,
Config: opts.config,
PlanProtocol: "v2",
};
// Reject oversize input client-side. Step Functions Standard caps the
// execution input at 256 KiB; without this check, the input bloat
// (typically from `config.variables` containing inlined media) surfaces
// as `States.DataLimitExceeded` 50 ms into the execution, far from the
// caller's stack frame. Measured AFTER `deploySite` so the synthesised
// `ProjectS3Uri` is counted (a few hundred bytes either way, but the
// check should be against the actual wire payload).
validateStepFunctionsInputSize(input);
const startedAt = new Date().toISOString();
const response = await sfn.send(
new StartExecutionCommand({
stateMachineArn: opts.stateMachineArn,
name: executionName,
input: JSON.stringify(input),
}),
);
if (!response.executionArn) {
throw new Error("[renderToLambda] StartExecution returned no executionArn");
}
return {
renderId: executionName,
executionArn: response.executionArn,
bucketName: opts.bucketName,
stateMachineArn: opts.stateMachineArn,
outputS3Uri,
projectS3Uri: site.projectS3Uri,
startedAt,
};
}
/** An older stack's plan step would try to untar a site manifest and fail after retries. */
export async function assertStackReadsSites(opts: {
stateMachineArn: string;
region?: string;
sfn?: SFNClient;
}): Promise<void> {
const sfn = opts.sfn ?? new SFNClient({ region: opts.region });
const { stateMachineArn } = opts;
const { definition } = await sfn.send(new DescribeStateMachineCommand({ stateMachineArn }));
if (definition?.includes(`"${SITE_MANIFEST_INVALID}"`)) return;
const error = new Error(
`[renderToLambda] STACK_TOO_OLD: ${stateMachineArn} was deployed by an earlier ` +
"@hyperframes/aws-lambda that cannot read this version's sites. Redeploy the stack first " +
"(`hyperframes lambda deploy`, or the SAM template / CDK construct from this version).",
);
error.name = "STACK_TOO_OLD";
throw error;
}