Function handlePlan

packages/aws-lambda/src/handler.ts:228–298

(event: PlanEvent, deps?: HandlerDeps)

// ── Plan ────────────────────────────────────────────────────────────────────

async function handlePlan(event: PlanEvent, deps?: HandlerDeps): Promise<PlanLambdaResult> {
  const started = Date.now();
  const s3 = deps?.s3 ?? getS3Client();
  const primitive = deps?.primitives?.plan ?? plan;

  // The producer's probe stage launches Chromium whenever the composition
  // needs a runtime duration probe or has unresolved sub-compositions, so
  // plan has to resolve Chrome the same way renderChunk does. Without this
  // the probe throws "An `executablePath` or `channel` must be specified
  // for `puppeteer-core`" the moment runProbeStage calls puppeteer.launch.
  if (!deps?.skipChromeResolution && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
    const chromePath = await resolveChromeExecutablePath();
    process.env.PRODUCER_HEADLESS_SHELL_PATH = chromePath;
  }

  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-lambda-plan-"));
  // We use `.tar.gz` (not `.zip`) as the project archive's on-the-wire
  // format because Lambda's Amazon Linux base image ships GNU `tar` but
  // not `unzip` in `/usr/bin`. The smoke script + future CLI both
  // produce tar.gz uploads.
  const projectArchive = join(work, "project.tar.gz");
  const projectDir = join(work, "project");
  const planDir = join(work, "plan");

  try {
    await downloadS3ObjectToFile(s3, event.ProjectS3Uri, projectArchive);
    await untarDirectory(projectArchive, projectDir);

    const config: DistributedRenderConfig = {
      ...event.Config,
    };
    const result: PlanResult = await primitive(projectDir, config, planDir);

    // Upload the planDir as a single tarball. Step Functions cannot pass
    // a directory-shaped artifact between states; we serialize and rely on
    // the consumer (renderChunk / assemble) to untar. Audio is co-located
    // alongside the plan so RenderChunk doesn't have to pull the whole
    // plan tarball when audio isn't relevant to the chunk.
    const planTar = join(work, "plan.tar.gz");
    await tarDirectory(planDir, planTar);
    const planTarUri = `${trimTrailingSlash(event.PlanOutputS3Prefix)}/plan.tar.gz`;
    const audioPath = join(planDir, "audio.aac");
    const hasAudio = existsSync(audioPath) && statSync(audioPath).size > 0;
    const audioUri = hasAudio ? `${trimTrailingSlash(event.PlanOutputS3Prefix)}/audio.aac` : null;
    // Plan and audio are independent S3 PUTs; run them in parallel so
    // the response returns as soon as the slower of the two completes.
    await Promise.all([
      uploadFileToS3(s3, planTar, planTarUri, "application/gzip"),
      hasAudio && audioUri ? uploadFileToS3(s3, audioPath, audioUri, "audio/aac") : null,
    ]);

    return {
      Action: "plan",
      PlanS3Uri: planTarUri,
      PlanHash: result.planHash,
      ChunkCount: result.chunkCount,
      TotalFrames: result.totalFrames,
      Fps: result.fps,