@hyperframes/aws-lambda 0.6.20

package/dist/sdk/index.js

@@ -0,0 +1,578 @@
+// src/sdk/deploySite.ts
+import { mkdtempSync, readdirSync as readdirSync2, readFileSync, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join as join2, relative } from "node:path";
+import { HeadObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { PLAN_PROJECT_DIR_SKIP_SEGMENTS } from "@hyperframes/producer/distributed";
+
+// src/s3Transport.ts
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
+import * as tar from "tar";
+function parseS3Uri(uri) {
+  if (!uri.startsWith("s3://")) {
+    throw new Error(`[s3Transport] expected s3:// URI, got: ${JSON.stringify(uri)}`);
+  }
+  const rest = uri.slice("s3://".length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) {
+    throw new Error(`[s3Transport] missing key in s3 URI: ${JSON.stringify(uri)}`);
+  }
+  const bucket = rest.slice(0, slash);
+  const key = rest.slice(slash + 1);
+  if (!bucket || !key) {
+    throw new Error(`[s3Transport] empty bucket or key in s3 URI: ${JSON.stringify(uri)}`);
+  }
+  return { bucket, key };
+}
+function formatS3Uri(loc) {
+  return `s3://${loc.bucket}/${loc.key}`;
+}
+async function uploadFileToS3(client, localPath, uri, contentType) {
+  if (!existsSync(localPath)) {
+    throw new Error(`[s3Transport] upload source missing: ${localPath}`);
+  }
+  const { bucket, key } = parseS3Uri(uri);
+  const size = statSync(localPath).size;
+  await client.send(
+    new PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      Body: createReadStream(localPath),
+      ContentType: contentType,
+      ContentLength: size
+    })
+  );
+}
+async function tarDirectory(sourceDir, destTarball) {
+  if (!existsSync(sourceDir) || !statSync(sourceDir).isDirectory()) {
+    throw new Error(`[s3Transport] tar source must be an existing directory: ${sourceDir}`);
+  }
+  mkdirSync(dirname(destTarball), { recursive: true });
+  await tar.create({ gzip: true, file: destTarball, cwd: sourceDir }, ["."]);
+}
+
+// src/sdk/deploySite.ts
+async function deploySite(opts) {
+  if (!statSync2(opts.projectDir).isDirectory()) {
+    throw new Error(`[deploySite] projectDir is not a directory: ${opts.projectDir}`);
+  }
+  const siteId = opts.siteId ?? hashProjectDir(opts.projectDir);
+  const key = `sites/${siteId}/project.tar.gz`;
+  const projectS3Uri = formatS3Uri({ bucket: opts.bucketName, key });
+  const s3 = opts.s3 ?? new S3Client({ region: opts.region });
+  const existing = await headObject(s3, opts.bucketName, key);
+  if (existing) {
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectS3Uri,
+      bytes: existing.bytes,
+      uploadedAt: existing.lastModified,
+      uploaded: false
+    };
+  }
+  const workdir = mkdtempSync(join2(tmpdir(), "hf-deploy-site-"));
+  try {
+    const tarball = join2(workdir, "project.tar.gz");
+    await tarDirectory(opts.projectDir, tarball);
+    const size = statSync2(tarball).size;
+    await uploadFileToS3(s3, tarball, projectS3Uri, "application/gzip");
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectS3Uri,
+      bytes: size,
+      uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      uploaded: true
+    };
+  } finally {
+    rmSync2(workdir, { recursive: true, force: true });
+  }
+}
+function hashProjectDir(projectDir) {
+  const hash = createHash("sha256");
+  const files = [];
+  function walk(dir, isRoot) {
+    for (const entry of readdirSync2(dir, { withFileTypes: true }).sort(
+      (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+    )) {
+      if (isRoot && PLAN_PROJECT_DIR_SKIP_SEGMENTS.has(entry.name)) continue;
+      const full = join2(dir, entry.name);
+      if (entry.isDirectory()) walk(full, false);
+      else if (entry.isFile()) files.push(full);
+    }
+  }
+  walk(projectDir, true);
+  for (const file of files) {
+    const rel = relative(projectDir, file).replaceAll("\\", "/");
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(readFileSync(file));
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+async function headObject(s3, bucket, key) {
+  try {
+    const res = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+    return {
+      bytes: typeof res.ContentLength === "number" ? res.ContentLength : 0,
+      lastModified: res.LastModified instanceof Date ? res.LastModified.toISOString() : (/* @__PURE__ */ new Date()).toISOString()
+    };
+  } catch (err) {
+    const status = err.$metadata?.httpStatusCode;
+    if (status === 404) return null;
+    const name = err.name;
+    if (name === "NotFound" || name === "NoSuchKey") return null;
+    throw err;
+  }
+}
+
+// src/sdk/renderToLambda.ts
+import { randomUUID } from "node:crypto";
+import { SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
+
+// src/formatExtension.ts
+function formatExtension(format) {
+  switch (format) {
+    case "mp4":
+      return ".mp4";
+    case "mov":
+      return ".mov";
+    case "png-sequence":
+      return "";
+    default: {
+      const _exhaustive = format;
+      throw new Error(`[formatExtension] unsupported format: ${_exhaustive}`);
+    }
+  }
+}
+
+// src/sdk/validateConfig.ts
+var InvalidConfigError = class extends Error {
+  name = "InvalidConfigError";
+  /** Dotted JSON-pointer-ish path to the offending field, e.g. `config.fps`. */
+  field;
+  constructor(field, message) {
+    super(`[validateConfig] ${field}: ${message}`);
+    this.field = field;
+  }
+};
+var ALLOWED_FPS = [24, 30, 60];
+var ALLOWED_FORMATS = ["mp4", "mov", "png-sequence"];
+var ALLOWED_CODECS = ["h264", "h265"];
+var ALLOWED_QUALITIES = ["draft", "standard", "high"];
+var ALLOWED_RUNTIME_CAPS = ["lambda", "temporal", "cloud-run-job", "k8s-job", "none"];
+var ALLOWED_HDR_MODES = ["auto", "force-sdr"];
+var MAX_DIMENSION = 7680;
+var MIN_DIMENSION = 16;
+var MAX_CHUNK_SIZE = 3600;
+var MAX_PARALLEL_CHUNKS_CEILING = 256;
+function validateDistributedRenderConfig(config) {
+  if (config === null || typeof config !== "object") {
+    throw new InvalidConfigError("config", "must be an object");
+  }
+  if (!ALLOWED_FPS.includes(config.fps)) {
+    throw new InvalidConfigError(
+      "config.fps",
+      `must be one of ${ALLOWED_FPS.join(", ")}; got ${String(config.fps)}`
+    );
+  }
+  validateIntDimension("config.width", config.width);
+  validateIntDimension("config.height", config.height);
+  if (!ALLOWED_FORMATS.includes(config.format)) {
+    throw new InvalidConfigError(
+      "config.format",
+      `must be one of ${ALLOWED_FORMATS.join(", ")}; got ${String(config.format)}`
+    );
+  }
+  if (config.codec !== void 0) {
+    if (config.format !== "mp4") {
+      throw new InvalidConfigError(
+        "config.codec",
+        `is only valid with format="mp4"; got format=${String(config.format)}`
+      );
+    }
+    if (!ALLOWED_CODECS.includes(config.codec)) {
+      throw new InvalidConfigError(
+        "config.codec",
+        `must be one of ${ALLOWED_CODECS.join(", ")}; got ${String(config.codec)}`
+      );
+    }
+  }
+  if (config.quality !== void 0 && !ALLOWED_QUALITIES.includes(config.quality)) {
+    throw new InvalidConfigError(
+      "config.quality",
+      `must be one of ${ALLOWED_QUALITIES.join(", ")}; got ${String(config.quality)}`
+    );
+  }
+  if (config.crf !== void 0 && config.bitrate !== void 0) {
+    throw new InvalidConfigError("config.crf", "is mutually exclusive with config.bitrate");
+  }
+  if (config.crf !== void 0 && (!Number.isInteger(config.crf) || config.crf < 0 || config.crf > 51)) {
+    throw new InvalidConfigError("config.crf", `must be an integer in [0, 51]; got ${config.crf}`);
+  }
+  if (config.bitrate !== void 0 && !/^\d+(\.\d+)?[kKmM]?$/.test(config.bitrate)) {
+    throw new InvalidConfigError(
+      "config.bitrate",
+      `must look like "10M" or "5000k"; got ${JSON.stringify(config.bitrate)}`
+    );
+  }
+  if (config.chunkSize !== void 0) {
+    if (!Number.isInteger(config.chunkSize) || config.chunkSize < 1) {
+      throw new InvalidConfigError(
+        "config.chunkSize",
+        `must be a positive integer; got ${config.chunkSize}`
+      );
+    }
+    if (config.chunkSize > MAX_CHUNK_SIZE) {
+      throw new InvalidConfigError(
+        "config.chunkSize",
+        // Lambda 15-min cap leaves no useful headroom past ~3600 frames
+        // at 4 fps capture-equivalent throughput; rejecting up front
+        // avoids a 14-minute Plan-state retry storm.
+        `must be \u2264 ${MAX_CHUNK_SIZE} (Lambda 15-min cap); got ${config.chunkSize}`
+      );
+    }
+  }
+  if (config.maxParallelChunks !== void 0) {
+    if (!Number.isInteger(config.maxParallelChunks) || config.maxParallelChunks < 1) {
+      throw new InvalidConfigError(
+        "config.maxParallelChunks",
+        `must be a positive integer; got ${config.maxParallelChunks}`
+      );
+    }
+    if (config.maxParallelChunks > MAX_PARALLEL_CHUNKS_CEILING) {
+      throw new InvalidConfigError(
+        "config.maxParallelChunks",
+        `must be \u2264 ${MAX_PARALLEL_CHUNKS_CEILING}; got ${config.maxParallelChunks}`
+      );
+    }
+  }
+  if (config.runtimeCap !== void 0 && !ALLOWED_RUNTIME_CAPS.includes(config.runtimeCap)) {
+    throw new InvalidConfigError(
+      "config.runtimeCap",
+      `must be one of ${ALLOWED_RUNTIME_CAPS.join(", ")}; got ${String(config.runtimeCap)}`
+    );
+  }
+  if (config.hdrMode !== void 0 && !ALLOWED_HDR_MODES.includes(config.hdrMode)) {
+    throw new InvalidConfigError(
+      "config.hdrMode",
+      `distributed mode supports only ${ALLOWED_HDR_MODES.join(", ")}; got ${String(config.hdrMode)}`
+    );
+  }
+  return config;
+}
+function validateIntDimension(field, value) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new InvalidConfigError(field, `must be an integer; got ${String(value)}`);
+  }
+  if (value < MIN_DIMENSION || value > MAX_DIMENSION) {
+    throw new InvalidConfigError(
+      field,
+      `must be in [${MIN_DIMENSION}, ${MAX_DIMENSION}]; got ${value}`
+    );
+  }
+  if (value % 2 !== 0) {
+    throw new InvalidConfigError(field, `must be even (yuv420p constraint); got ${value}`);
+  }
+}
+
+// src/sdk/renderToLambda.ts
+async function renderToLambda(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 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 deploySite({
+    projectDir: opts.projectDir,
+    bucketName: opts.bucketName,
+    region: opts.region,
+    s3: opts.s3
+  });
+  const input = {
+    ProjectS3Uri: site.projectS3Uri,
+    PlanOutputS3Prefix: planOutputS3Prefix,
+    OutputS3Uri: outputS3Uri,
+    Config: opts.config
+  };
+  const sfn = opts.sfn ?? new SFNClient({ region: opts.region });
+  const startedAt = (/* @__PURE__ */ 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
+  };
+}
+
+// src/sdk/getRenderProgress.ts
+import {
+  DescribeExecutionCommand,
+  GetExecutionHistoryCommand,
+  SFNClient as SFNClient2
+} from "@aws-sdk/client-sfn";
+
+// src/sdk/costAccounting.ts
+var LAMBDA_USD_PER_GB_SECOND = 166667e-10;
+var SFN_USD_PER_TRANSITION = 25e-6;
+function computeRenderCost(lambdaInvocations, stateTransitions) {
+  let lambdaUsd = 0;
+  let anyEstimated = false;
+  for (const inv of lambdaInvocations) {
+    const gbSeconds = inv.memorySizeMb / 1024 * (inv.billedDurationMs / 1e3);
+    lambdaUsd += gbSeconds * LAMBDA_USD_PER_GB_SECOND;
+    if (inv.estimated) anyEstimated = true;
+  }
+  const stepFunctionsUsd = stateTransitions * SFN_USD_PER_TRANSITION;
+  const accruedSoFarUsd = roundUsd(lambdaUsd + stepFunctionsUsd);
+  return {
+    accruedSoFarUsd,
+    displayCost: formatUsd(accruedSoFarUsd),
+    breakdown: {
+      lambdaUsd: roundUsd(lambdaUsd),
+      stepFunctionsUsd: roundUsd(stepFunctionsUsd),
+      s3Estimate: "not-included",
+      estimated: anyEstimated
+    }
+  };
+}
+function roundUsd(usd) {
+  return Math.round(usd * 1e4) / 1e4;
+}
+function formatUsd(usd) {
+  return `$${usd.toFixed(4)}`;
+}
+
+// src/sdk/getRenderProgress.ts
+var DEFAULT_MEMORY_MB = 10240;
+async function getRenderProgress(opts) {
+  if (!opts.executionArn) {
+    throw new Error("[getRenderProgress] executionArn is required");
+  }
+  const sfn = opts.sfn ?? new SFNClient2({ 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";
+  const startedAt = describe.startDate?.toISOString() ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  const endedAt = describe.stopDate?.toISOString() ?? null;
+  const history = await loadFullHistory(sfn, opts.executionArn);
+  const summary = summarizeHistory(history, memoryMb);
+  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),
+    startedAt,
+    endedAt
+  };
+}
+async function loadFullHistory(sfn, executionArn) {
+  const events = [];
+  let nextToken;
+  for (let page = 0; page < 50; page++) {
+    const res = await sfn.send(
+      new GetExecutionHistoryCommand({
+        executionArn,
+        maxResults: 1e3,
+        nextToken,
+        reverseOrder: false
+      })
+    );
+    if (res.events) events.push(...res.events);
+    nextToken = res.nextToken;
+    if (!nextToken) break;
+  }
+  return events;
+}
+function summarizeHistory(events, memoryMb) {
+  let framesRendered = 0;
+  let totalFrames = null;
+  let lambdasInvoked = 0;
+  let assembleComplete = false;
+  let outputFile = null;
+  let stateTransitions = 0;
+  const errors = [];
+  const lambdaInvocations = [];
+  let currentLambdaState = 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":
+        stateTransitions++;
+        currentLambdaState = ev.stateEnteredEventDetails?.name ?? currentLambdaState;
+        break;
+      case "LambdaFunctionScheduled":
+        lambdasInvoked++;
+        break;
+      case "LambdaFunctionSucceeded": {
+        const payload = parseJson(ev.lambdaFunctionSucceededEventDetails?.output);
+        const billedDurationMs = inferBilledMs(payload);
+        lambdaInvocations.push({
+          billedDurationMs,
+          memorySizeMb: memoryMb,
+          estimated: billedDurationMs === 0
+        });
+        if (payload && typeof payload === "object") {
+          const obj = payload;
+          if (typeof obj.TotalFrames === "number") totalFrames = obj.TotalFrames;
+          if (typeof obj.FramesEncoded === "number") {
+            if (currentLambdaState === "RenderChunk") {
+              framesRendered += obj.FramesEncoded;
+            }
+          }
+        }
+        break;
+      }
+      case "TaskStateExited":
+      case "MapStateExited":
+        if (ev.stateExitedEventDetails?.name === "Assemble") {
+          assembleComplete = true;
+          const exitPayload = parseJson(ev.stateExitedEventDetails?.output);
+          if (exitPayload && typeof exitPayload === "object") {
+            const obj = exitPayload;
+            const out = obj.Output;
+            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 "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) {
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+function inferBilledMs(payload) {
+  if (!payload || typeof payload !== "object") return 0;
+  const obj = payload;
+  if (typeof obj.DurationMs === "number") return obj.DurationMs;
+  return 0;
+}
+function computeOverallProgress({
+  status,
+  totalFrames,
+  framesRendered,
+  assembleComplete
+}) {
+  if (status === "SUCCEEDED") return 1;
+  if (assembleComplete) return 1;
+  if (totalFrames === null) return 0;
+  const chunkProgress = Math.min(1, framesRendered / totalFrames);
+  return 0.1 + 0.8 * chunkProgress;
+}
+function isTerminalFailure(status) {
+  return status === "FAILED" || status === "TIMED_OUT" || status === "ABORTED";
+}
+export {
+  InvalidConfigError,
+  computeRenderCost,
+  deploySite,
+  getRenderProgress,
+  renderToLambda,
+  validateDistributedRenderConfig
+};
+//# sourceMappingURL=index.js.map