Skip to content

Write HTML. Render video. Built for agents.

18.8 KB
Raw Blame
/**
 * `getRenderProgress` — read-only progress + cost snapshot for a single
 * render started by {@link renderToLambda}.
 *
 * Pulls one `DescribeExecution` + one `GetExecutionHistory` per call. While
 * the chunk Distributed Map runs, one `DescribeMapRun` adds its item counts;
 * once it exits, chunk frames and cost come from the Map's output. Failed
 * chunks' histories are read only when the counts show a failure.
 *
 * Progress math:
 *   - 0  before Plan completes (no frame count is known yet)
 *   - 0.1 once Plan completes (we know `totalFrames`)
 *   - 0.1 + 0.8 × framesEncoded / totalFrames during chunk render
 *   - 1.0 after Assemble completes
 *
 * Frame counts come from the parsed Lambda result payloads on each
 * `TaskSucceeded` event — Plan reports `TotalFrames`, RenderChunk reports
 * `FramesEncoded`. The shape mirrors what the handler produces in
 * `events.ts`, so the parser doesn't need to know anything beyond
 * "JSON.parse this string and grab two fields."
 */

import {
  DescribeExecutionCommand,
  DescribeMapRunCommand,
  GetExecutionHistoryCommand,
  type HistoryEvent,
  ListExecutionsCommand,
  SFNClient,
  type SFNClientConfig,
} from "@aws-sdk/client-sfn";
import {
  type BilledLambdaInvocation,
  computeRenderCost,
  type LambdaArchitecture,
  type RenderCost,
} from "./costAccounting.js";

/** Options for {@link getRenderProgress}. */
export interface GetRenderProgressOptions {
  /** Execution ARN from a {@link renderToLambda} call. */
  executionArn: string;
  /**
   * Default memory size in MB to assume for Lambda invocations when the
   * history event payload doesn't carry it explicitly. Matches the
   * `LambdaMemoryMb` parameter the stack was deployed with.
   */
  defaultMemorySizeMb?: number;
  /** Architecture of the stack's video function, which runs the plan and the chunks: `arm64` when it has one. */
  videoArchitecture?: LambdaArchitecture;
  region?: string;
  /** Test injection seam. */
  sfn?: SFNClient;
}

/** Render-status discriminant; mirrors Step Functions execution states. */
export type RenderStatus =
  | "RUNNING"
  | "SUCCEEDED"
  | "FAILED"
  | "TIMED_OUT"
  | "ABORTED"
  | "PENDING_REDRIVE";

export interface RenderError {
  /** State name where the failure surfaced (`Plan`, `RenderChunk`, `Assemble`, or `<unknown>`). */
  state: string;
  /** Error class / type as Step Functions reports it. */
  error: string;
  /** Cause string Step Functions surfaces (often a stringified JSON payload from the handler). */
  cause: string;
}

/** Snapshot of a single render's progress + cost + errors at one point in time. */
export interface RenderProgress {
  status: RenderStatus;
  /** `[0, 1]`; see module doc for the math. */
  overallProgress: number;
  framesRendered: number;
  /** `null` until Plan completes. */
  totalFrames: number | null;
  /** Total Lambda invocations scheduled so far (both optimized + raw task integrations). */
  lambdasInvoked: number;
  costs: RenderCost;
  /** Final output object if Assemble succeeded; `null` otherwise. */
  outputFile: { s3Uri: string; bytes: number | null } | null;
  errors: RenderError[];
  /** `true` once the execution has terminated in a non-`SUCCEEDED` state. */
  fatalErrorEncountered: boolean;
  /** Problems reading progress that leave the render itself untouched, such as a missing IAM permission. */
  warnings: string[];
  startedAt: string;
  endedAt: string | null;
}

const DEFAULT_MEMORY_MB = 10240;

/** Rides out `ThrottlingException` with the SDK's backoff instead of throwing after the default 3 tries. */
export function createProgressSfnClient(config: SFNClientConfig = {}): SFNClient {
  return new SFNClient({ maxAttempts: 8, ...config });
}

/** Pull a current progress snapshot for one render. */
export async function getRenderProgress(opts: GetRenderProgressOptions): Promise<RenderProgress> {
  if (!opts.executionArn) {
    throw new Error("[getRenderProgress] executionArn is required");
  }
  const sfn = opts.sfn ?? createProgressSfnClient({ region: opts.region });
  const memoryMb = opts.defaultMemorySizeMb ?? DEFAULT_MEMORY_MB;

  const describe = await sfn.send(
    new DescribeExecutionCommand({ executionArn: opts.executionArn }),
  );
  const status = (describe.status ?? "RUNNING") as RenderStatus;
  const startedAt = describe.startDate?.toISOString() ?? new Date(0).toISOString();
  const endedAt = describe.stopDate?.toISOString() ?? null;

  const history = await loadFullHistory(sfn, opts.executionArn);
  const summary = summarizeHistory(history, memoryMb, opts.videoArchitecture);
  const mapRun = findChunkMapRun(history);
  const warnings: string[] = [];
  if (mapRun?.exited) addChunkResults(summary, mapRun.output, memoryMb, opts.videoArchitecture);
  else if (mapRun) {
    await addRunningMapRun(sfn, mapRun.arn, summary, memoryMb).catch((err: unknown) => {
      if ((err as { name?: unknown } | null)?.name !== "AccessDeniedException") throw err;
      warnings.push(MAP_RUN_ACCESS_DENIED);
    });
  }

  const costs = computeRenderCost(summary.lambdaInvocations, summary.stateTransitions);
  const overallProgress = computeOverallProgress({
    status,
    totalFrames: summary.totalFrames,
    framesRendered: summary.framesRendered,
    assembleComplete: summary.assembleComplete,
  });

  return {
    status,
    overallProgress,
    framesRendered: summary.framesRendered,
    totalFrames: summary.totalFrames,
    lambdasInvoked: summary.lambdasInvoked,
    costs,
    outputFile: summary.outputFile,
    errors: summary.errors,
    fatalErrorEncountered: isTerminalFailure(status),
    warnings,
    startedAt,
    endedAt,
  };
}

async function loadFullHistory(sfn: SFNClient, executionArn: string): Promise<HistoryEvent[]> {
  const events: HistoryEvent[] = [];
  let nextToken: string | undefined;
  for (let page = 0; page < 50; page++) {
    const res = await sfn.send(
      new GetExecutionHistoryCommand({
        executionArn,
        maxResults: 1000,
        nextToken,
        reverseOrder: false,
      }),
    );
    if (res.events) events.push(...res.events);
    nextToken = res.nextToken;
    if (!nextToken) break;
  }
  return events;
}

const FAILED_CHUNK_HISTORIES_READ = 5;

const MAP_RUN_ACCESS_DENIED =
  "Chunk progress is hidden until the chunks finish: this caller lacks states:DescribeMapRun. " +
  "Re-apply the policy from `hyperframes lambda policies user`.";

interface ChunkMapRun {
  arn: string;
  exited: boolean;
  output: string | undefined;
}

/** The chunk Distributed Map's run; `null` for an inline Map, whose chunk events are in the parent history. */
function findChunkMapRun(events: HistoryEvent[]): ChunkMapRun | null {
  let run: ChunkMapRun | null = null;
  for (const ev of events) {
    const arn = ev.mapRunStartedEventDetails?.mapRunArn;
    if (arn) run = { arn, exited: false, output: undefined };
    const exit = ev.stateExitedEventDetails;
    if (run && ev.type === "MapStateExited" && isRenderChunksMapState(exit?.name)) {
      run = { ...run, exited: true, output: exit?.output };
    }
  }
  return run;
}

/** Exact chunk frames and cost from the chunk results the Map's output carries. */
function addChunkResults(
  summary: HistorySummary,
  mapOutput: string | undefined,
  memoryMb: number,
  architecture: LambdaArchitecture | undefined,
) {
  const chunks = (parseJson(mapOutput) as { Chunks?: unknown } | null)?.Chunks;
  for (const chunk of Array.isArray(chunks) ? chunks : []) {
    summary.lambdasInvoked++;
    summary.stateTransitions++;
    summary.lambdaInvocations.push(billedInvocation(chunk, memoryMb, architecture));
    applyPayloadFrameCounts(chunk, "RenderChunk", (delta) => {
      summary.framesRendered += delta;
    });
  }
}

// Open Map Run: frames estimated from the succeeded share; chunk Lambda cost waits for the Map's exit.
async function addRunningMapRun(
  sfn: SFNClient,
  mapRunArn: string,
  summary: HistorySummary,
  memoryMb: number,
): Promise<void> {
  const res = await sfn.send(new DescribeMapRunCommand({ mapRunArn }));
  const { total = 0, pending = 0, succeeded = 0, failed = 0 } = res.itemCounts ?? {};
  summary.lambdasInvoked += total - pending;
  summary.stateTransitions += total - pending;
  if (summary.totalFrames !== null && total > 0) {
    summary.framesRendered += Math.floor((summary.totalFrames * succeeded) / total);
  }
  if (failed > 0) summary.errors.push(...(await failedChunkErrors(sfn, mapRunArn, memoryMb)));
}

async function failedChunkErrors(
  sfn: SFNClient,
  mapRunArn: string,
  memoryMb: number,
): Promise<RenderError[]> {
  const failed = await sfn.send(
    new ListExecutionsCommand({
      mapRunArn,
      statusFilter: "FAILED",
      maxResults: FAILED_CHUNK_HISTORIES_READ,
    }),
  );
  const errors: RenderError[] = [];
  for (const child of failed.executions ?? []) {
    if (!child.executionArn) continue;
    const childHistory = await loadFullHistory(sfn, child.executionArn);
    errors.push(...summarizeHistory(childHistory, memoryMb).errors);
  }
  return errors;
}

interface HistorySummary {
  lambdaInvocations: BilledLambdaInvocation[];
  stateTransitions: number;
  framesRendered: number;
  totalFrames: number | null;
  lambdasInvoked: number;
  assembleComplete: boolean;
  outputFile: { s3Uri: string; bytes: number | null } | null;
  errors: RenderError[];
}

/**
 * One pass over the history events that pulls every number {@link getRenderProgress}
 * needs. State transitions = the count of events that advance the state
 * machine (entering/exiting states + map iteration completions). Lambda
 * invocations = `LambdaFunctionScheduled` count. Frame totals come from
 * the success-payload of each Lambda invocation.
 */
function summarizeHistory(
  events: HistoryEvent[],
  memoryMb: number,
  videoArchitecture?: LambdaArchitecture,
): HistorySummary {
  let framesRendered = 0;
  let totalFrames: number | null = null;
  let lambdasInvoked = 0;
  let assembleComplete = false;
  let outputFile: HistorySummary["outputFile"] = null;
  let stateTransitions = 0;
  const errors: RenderError[] = [];
  const lambdaInvocations: BilledLambdaInvocation[] = [];

  // Track the state name we most recently entered, so we can:
  //   - attach the enclosing state to LambdaFunctionFailed errors, and
  //   - identify when the Assemble state finished (StateExited.Assemble)
  //     without relying on the inner Lambda payload's `Action` field.
  let currentLambdaState: string | null = null;

  for (const ev of events) {
    switch (ev.type) {
      case "TaskStateEntered":
      case "MapStateEntered":
      case "PassStateEntered":
      case "ChoiceStateEntered":
      case "SucceedStateEntered":
      case "FailStateEntered":
      case "WaitStateEntered":
      case "ParallelStateEntered":
        // Step Functions Standard Workflows bill per *state entry*, not per
        // history event. Lambda invocations produce ~5-7 history events
        // each (Scheduled / Started / Succeeded / TaskStateExited / …);
        // counting every event as a transition over-reports cost by 3-5×.
        stateTransitions++;
        currentLambdaState = ev.stateEnteredEventDetails?.name ?? currentLambdaState;
        break;
      // Optimized `lambda:invoke` task emits Task* events; raw
      // `lambda:invokeFunction.sync` emits LambdaFunction*. Handle both.
      case "TaskScheduled":
        if (ev.taskScheduledEventDetails?.resourceType === "lambda") {
          lambdasInvoked++;
        }
        break;
      case "LambdaFunctionScheduled":
        lambdasInvoked++;
        break;
      case "TaskSucceeded": {
        if (ev.taskSucceededEventDetails?.resourceType !== "lambda") break;
        const wrapped = parseJson(ev.taskSucceededEventDetails?.output);
        const payload = unwrapLambdaPayload(wrapped);
        lambdaInvocations.push(
          billedInvocation(
            payload,
            memoryMb,
            stateArchitecture(currentLambdaState, videoArchitecture),
          ),
        );
        applyPayloadFrameCounts(payload, currentLambdaState, (delta) => {
          framesRendered += delta;
        });
        if (payload && typeof payload === "object") {
          const obj = payload as Record<string, unknown>;
          if (typeof obj.TotalFrames === "number") totalFrames = obj.TotalFrames;
        }
        break;
      }
      case "LambdaFunctionSucceeded": {
        const payload = parseJson(ev.lambdaFunctionSucceededEventDetails?.output);
        lambdaInvocations.push(
          billedInvocation(
            payload,
            memoryMb,
            stateArchitecture(currentLambdaState, videoArchitecture),
          ),
        );
        applyPayloadFrameCounts(payload, currentLambdaState, (delta) => {
          framesRendered += delta;
        });
        if (payload && typeof payload === "object") {
          const obj = payload as Record<string, unknown>;
          if (typeof obj.TotalFrames === "number") totalFrames = obj.TotalFrames;
        }
        break;
      }
      case "TaskStateExited":
      case "MapStateExited":
        // Mark the assemble step complete on its state-exit, independent
        // of the inner Lambda payload shape. The Assemble state's
        // ResultSelector pulls FileSize + OutputS3Uri from the Lambda
        // result, so we re-extract them here from the state exit's
        // own output rather than relying on the Lambda payload.
        if (isAssembleState(ev.stateExitedEventDetails?.name)) {
          assembleComplete = true;
          const exitPayload = parseJson(ev.stateExitedEventDetails?.output);
          if (exitPayload && typeof exitPayload === "object") {
            const obj = exitPayload as Record<string, unknown>;
            const out = obj.Output as Record<string, unknown> | undefined;
            const outputS3Uri = typeof out?.OutputS3Uri === "string" ? out.OutputS3Uri : null;
            const bytes = typeof out?.FileSize === "number" ? out.FileSize : null;
            outputFile = outputS3Uri ? { s3Uri: outputS3Uri, bytes } : outputFile;
          }
        }
        break;
      case "TaskFailed":
        if (ev.taskFailedEventDetails?.resourceType !== "lambda") break;
        errors.push({
          state: currentLambdaState ?? "<unknown>",
          error: ev.taskFailedEventDetails?.error ?? "UNKNOWN",
          cause: ev.taskFailedEventDetails?.cause ?? "",
        });
        break;
      case "LambdaFunctionFailed":
        errors.push({
          state: currentLambdaState ?? "<unknown>",
          error: ev.lambdaFunctionFailedEventDetails?.error ?? "UNKNOWN",
          cause: ev.lambdaFunctionFailedEventDetails?.cause ?? "",
        });
        break;
      case "ExecutionFailed":
        errors.push({
          state: "<execution>",
          error: ev.executionFailedEventDetails?.error ?? "UNKNOWN",
          cause: ev.executionFailedEventDetails?.cause ?? "",
        });
        break;
      case "ExecutionAborted":
        errors.push({
          state: "<execution>",
          error: ev.executionAbortedEventDetails?.error ?? "ABORTED",
          cause: ev.executionAbortedEventDetails?.cause ?? "",
        });
        break;
      case "ExecutionTimedOut":
        errors.push({
          state: "<execution>",
          error: "TIMEOUT",
          cause: ev.executionTimedOutEventDetails?.cause ?? "",
        });
        break;
      default:
        break;
    }
  }

  return {
    lambdaInvocations,
    stateTransitions,
    framesRendered,
    totalFrames,
    lambdasInvoked,
    assembleComplete,
    outputFile,
    errors,
  };
}

function parseJson(s: string | undefined): unknown {
  if (!s) return null;
  try {
    return JSON.parse(s);
  } catch {
    return null;
  }
}

/**
 * Optimized `lambda:invoke` wraps the Lambda response as
 * `{ ExecutedVersion, Payload: {…handler payload…}, StatusCode }`. Raw
 * `lambda:invokeFunction.sync` puts the handler payload at the root.
 * Return the inner `Payload` when present so callers read the same fields
 * either way.
 */
function unwrapLambdaPayload(payload: unknown): unknown {
  if (payload && typeof payload === "object" && "Payload" in payload) {
    const inner = (payload as { Payload: unknown }).Payload;
    if (inner && typeof inner === "object") return inner;
  }
  return payload;
}

/**
 * Bump `framesRendered` only inside the `RenderChunk` state. Plan and
 * Assemble also report `FramesEncoded`, so a state-blind add would
 * double-count once Assemble runs.
 */
function applyPayloadFrameCounts(
  payload: unknown,
  currentLambdaState: string | null,
  bump: (delta: number) => void,
): void {
  if (!isRenderChunkState(currentLambdaState)) return;
  if (!payload || typeof payload !== "object") return;
  const obj = payload as Record<string, unknown>;
  if (typeof obj.FramesEncoded === "number") bump(obj.FramesEncoded);
}

function isRenderChunkState(name: string | null | undefined): boolean {
  return name === "RenderChunk" || name === "RenderChunkV2";
}

function isRenderChunksMapState(name: string | null | undefined): boolean {
  return name === "RenderChunks" || name === "RenderChunksV2";
}

function isAssembleState(name: string | null | undefined): boolean {
  return name === "Assemble" || name === "AssembleV2";
}

/**
 * Lambda success payloads from our handler include `DurationMs` — the
 * wall-clock the handler observed. We use it as a best-effort proxy
 * for `BilledDuration` when SFN doesn't expose the latter directly
 * on `LambdaFunctionSucceeded` (the dedicated `BilledDuration` field
 * is in CloudWatch Metrics, not the SFN history payload).
 */
function billedInvocation(
  payload: unknown,
  memoryMb: number,
  architecture: LambdaArchitecture | undefined,
): BilledLambdaInvocation {
  const billedDurationMs = inferBilledMs(payload);
  return {
    billedDurationMs,
    memorySizeMb: memoryMb,
    estimated: billedDurationMs === 0,
    architecture,
  };
}

/** The video function runs the plan and the chunks; audio and assemble run on the render function. */
function stateArchitecture(
  state: string | null,
  videoArchitecture: LambdaArchitecture | undefined,
): LambdaArchitecture | undefined {
  return state === "Plan" || state === "PlanV2" || isRenderChunkState(state)
    ? videoArchitecture
    : undefined;
}

function inferBilledMs(payload: unknown): number {
  if (!payload || typeof payload !== "object") return 0;
  const obj = payload as Record<string, unknown>;
  if (typeof obj.DurationMs === "number") return obj.DurationMs;
  return 0;
}

interface ComputeProgressArgs {
  status: RenderStatus;
  totalFrames: number | null;
  framesRendered: number;
  assembleComplete: boolean;
}

function computeOverallProgress({
  status,
  totalFrames,
  framesRendered,
  assembleComplete,
}: ComputeProgressArgs): number {
  if (status === "SUCCEEDED") return 1;
  if (assembleComplete) return 1;
  if (totalFrames === null) return 0;
  // 10 % Plan + 80 % chunk render + 10 % Assemble.
  const chunkProgress = Math.min(1, framesRendered / totalFrames);
  return 0.1 + 0.8 * chunkProgress;
}

function isTerminalFailure(status: RenderStatus): boolean {
  return status === "FAILED" || status === "TIMED_OUT" || status === "ABORTED";
}