Skip to content

Write HTML. Render video. Built for agents.

6.8 KB
Raw Blame
/**
 * `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 { LambdaPlanProtocol, SerializableDistributedRenderConfig } from "../events.js";
import { formatExtension } from "../formatExtension.js";
import { formatS3Uri } from "../s3Transport.js";
import { SITE_MANIFEST_INVALID } from "../siteManifest.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;
  /** Validated `SerializableDistributedRenderConfig` (no logger / abortSignal). */
  config: SerializableDistributedRenderConfig;
  /**
   * Distributed plan transport. Defaults to `"v2"`. Select `"v1"`
   * explicitly only for deprecated compatibility with the monolithic plan.
   */
  planProtocol?: LambdaPlanProtocol;
  /** 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;
}

// fallow-ignore-next-line complexity
export async function renderToLambda(opts: RenderToLambdaOptions): Promise<RenderHandle> {
  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 sfn = opts.sfn ?? new SFNClient({ region: opts.region });
  await assertStackReadsSites({ stateMachineArn: opts.stateMachineArn, sfn });

  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,
        opts.s3 ?? new S3Client({ region: opts.region }),
        opts.projectDir,
      )
    : await deploySite({
        projectDir: opts.projectDir as string,
        bucketName: opts.bucketName,
        region: opts.region,
        s3: opts.s3,
      });

  const input = {
    ProjectS3Uri: site.projectS3Uri,
    PlanOutputS3Prefix: planOutputS3Prefix,
    OutputS3Uri: outputS3Uri,
    Config: opts.config,
    PlanProtocol: opts.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;
}