mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* 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>
190 lines
7.3 KiB
TypeScript
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;
|
|
}
|