@hyperframes/gcp-cloud-run 0.6.79

package/dist/index.js

@@ -0,0 +1,855 @@
+// src/server.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, mkdtempSync, readFileSync, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { serve } from "@hono/node-server";
+import { Storage } from "@google-cloud/storage";
+import { Hono } from "hono";
+import {
+  assemble,
+  plan,
+  renderChunk
+} from "@hyperframes/producer/distributed";
+
+// src/chromium.ts
+import { existsSync } from "node:fs";
+var ChromeBinaryUnavailableError = class extends Error {
+  // Read indirectly via the error envelope / Error.prototype.toString.
+  // fallow-ignore-next-line unused-class-member
+  name = "ChromeBinaryUnavailableError";
+  resolvedPath;
+  constructor(resolvedPath, hint) {
+    super(`[chromium] Chrome binary unavailable: ${hint}`);
+    this.resolvedPath = resolvedPath;
+  }
+};
+var FALLBACK_CHROME_PATHS = [
+  "/opt/chrome/chrome-headless-shell",
+  "/usr/bin/chrome-headless-shell",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser"
+];
+function resolveChromeExecutablePath() {
+  const fromEngineOverride = process.env.PRODUCER_HEADLESS_SHELL_PATH?.trim();
+  if (fromEngineOverride) {
+    if (!existsSync(fromEngineOverride)) {
+      throw new ChromeBinaryUnavailableError(
+        fromEngineOverride,
+        `PRODUCER_HEADLESS_SHELL_PATH=${JSON.stringify(fromEngineOverride)} does not exist on disk.`
+      );
+    }
+    return fromEngineOverride;
+  }
+  const fromImage = process.env.HYPERFRAMES_CHROME_PATH?.trim();
+  if (fromImage) {
+    if (!existsSync(fromImage)) {
+      throw new ChromeBinaryUnavailableError(
+        fromImage,
+        `HYPERFRAMES_CHROME_PATH=${JSON.stringify(fromImage)} does not exist on disk.`
+      );
+    }
+    return fromImage;
+  }
+  for (const candidate of FALLBACK_CHROME_PATHS) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new ChromeBinaryUnavailableError(
+    null,
+    `no Chrome binary found. Set HYPERFRAMES_CHROME_PATH (the Dockerfile does this) or PRODUCER_HEADLESS_SHELL_PATH to the absolute path of a chrome-headless-shell binary. Searched: ${FALLBACK_CHROME_PATHS.join(", ")}.`
+  );
+}
+
+// src/formatExtension.ts
+var FORMAT_EXTENSIONS = {
+  mp4: ".mp4",
+  mov: ".mov",
+  webm: ".webm",
+  "png-sequence": ""
+};
+function formatExtension(format) {
+  return FORMAT_EXTENSIONS[format];
+}
+
+// src/gcsTransport.ts
+import { createWriteStream, existsSync as existsSync2, mkdirSync, rmSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import * as tar from "tar";
+function parseGcsUri(uri) {
+  if (!uri.startsWith("gs://")) {
+    throw new Error(`[gcsTransport] expected gs:// URI, got: ${JSON.stringify(uri)}`);
+  }
+  const rest = uri.slice("gs://".length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) {
+    throw new Error(`[gcsTransport] missing key in gs URI: ${JSON.stringify(uri)}`);
+  }
+  const bucket = rest.slice(0, slash);
+  const key = rest.slice(slash + 1);
+  if (!bucket || !key) {
+    throw new Error(`[gcsTransport] empty bucket or key in gs URI: ${JSON.stringify(uri)}`);
+  }
+  return { bucket, key };
+}
+function formatGcsUri(loc) {
+  return `gs://${loc.bucket}/${loc.key}`;
+}
+async function downloadGcsObjectToFile(storage, uri, destPath) {
+  const { bucket, key } = parseGcsUri(uri);
+  mkdirSync(dirname(destPath), { recursive: true });
+  const file = storage.bucket(bucket).file(key);
+  await pipeline(file.createReadStream(), createWriteStream(destPath));
+}
+async function uploadFileToGcs(storage, localPath, uri, contentType) {
+  if (!existsSync2(localPath)) {
+    throw new Error(`[gcsTransport] upload source missing: ${localPath}`);
+  }
+  const { bucket, key } = parseGcsUri(uri);
+  await storage.bucket(bucket).upload(localPath, {
+    destination: key,
+    // `resumable: false` (simple upload) is faster for the small-to-medium
+    // objects this adapter moves and avoids the extra round-trip a resumable
+    // session start costs; GCS recommends resumable only past ~8 MB but our
+    // chunks are reliably above that, so let the client pick by default.
+    contentType
+  });
+}
+async function tarDirectory(sourceDir, destTarball) {
+  if (!existsSync2(sourceDir) || !statSync(sourceDir).isDirectory()) {
+    throw new Error(`[gcsTransport] tar source must be an existing directory: ${sourceDir}`);
+  }
+  mkdirSync(dirname(destTarball), { recursive: true });
+  await tar.create({ gzip: true, file: destTarball, cwd: sourceDir }, ["."]);
+}
+async function untarDirectory(tarballPath, destDir) {
+  if (!existsSync2(tarballPath)) {
+    throw new Error(`[gcsTransport] tarball missing: ${tarballPath}`);
+  }
+  if (existsSync2(destDir)) {
+    rmSync(destDir, { recursive: true, force: true });
+  }
+  mkdirSync(destDir, { recursive: true });
+  await tar.extract({ file: tarballPath, cwd: destDir });
+}
+
+// src/server.ts
+var cachedStorage = null;
+function getStorage() {
+  if (cachedStorage) return cachedStorage;
+  cachedStorage = new Storage();
+  return cachedStorage;
+}
+async function dispatch(event, deps) {
+  const unwrapped = unwrapEvent(event);
+  validateEventGcsUris(unwrapped);
+  logEvent({ event: "handler_start", action: unwrapped.Action, input: summarizeEvent(unwrapped) });
+  try {
+    switch (unwrapped.Action) {
+      case "plan":
+        return await handlePlan(unwrapped, deps);
+      case "renderChunk":
+        return await handleRenderChunk(unwrapped, deps);
+      case "assemble":
+        return await handleAssemble(unwrapped, deps);
+      default: {
+        const _exhaustive = unwrapped;
+        throw new Error(
+          `[handler] unknown Action: ${JSON.stringify(
+            _exhaustive.Action
+          )}. Expected one of "plan", "renderChunk", "assemble".`
+        );
+      }
+    }
+  } catch (err) {
+    logEvent({
+      event: "handler_error",
+      action: unwrapped.Action,
+      message: err instanceof Error ? err.message : String(err),
+      name: err instanceof Error ? err.name : void 0
+    });
+    throw err;
+  }
+}
+var MAX_ENVELOPE_DEPTH = 4;
+function unwrapEvent(event) {
+  let cursor = event;
+  for (let i = 0; i < MAX_ENVELOPE_DEPTH; i++) {
+    if (cursor && typeof cursor === "object") {
+      const obj = cursor;
+      if (typeof obj.Action === "string" && isCloudRunAction(obj.Action)) {
+        return cursor;
+      }
+      if ("Payload" in obj) {
+        cursor = obj.Payload;
+        continue;
+      }
+      if ("Input" in obj) {
+        cursor = obj.Input;
+        continue;
+      }
+    }
+    break;
+  }
+  throw new Error(
+    `[handler] body has no recognised Action; unwrapped ${MAX_ENVELOPE_DEPTH} levels of Payload/Input without finding one.`
+  );
+}
+function isCloudRunAction(value) {
+  return value === "plan" || value === "renderChunk" || value === "assemble";
+}
+function logEvent(payload) {
+  console.log(JSON.stringify(payload));
+}
+function summarizeEvent(event) {
+  switch (event.Action) {
+    case "plan":
+      return {
+        projectGcsUri: event.ProjectGcsUri,
+        planOutputGcsPrefix: event.PlanOutputGcsPrefix,
+        format: event.Config.format,
+        fps: event.Config.fps
+      };
+    case "renderChunk":
+      return {
+        planGcsUri: event.PlanGcsUri,
+        chunkIndex: event.ChunkIndex,
+        format: event.Format
+      };
+    case "assemble":
+      return {
+        planGcsUri: event.PlanGcsUri,
+        chunkCount: event.ChunkGcsUris.length,
+        hasAudio: event.AudioGcsUri !== null,
+        outputGcsUri: event.OutputGcsUri,
+        format: event.Format
+      };
+  }
+}
+function primeChrome(deps) {
+  if (deps?.skipChromeResolution) return;
+  if (process.env.PRODUCER_HEADLESS_SHELL_PATH) return;
+  process.env.PRODUCER_HEADLESS_SHELL_PATH = resolveChromeExecutablePath();
+}
+async function handlePlan(event, deps) {
+  const started = Date.now();
+  const storage = deps?.storage ?? getStorage();
+  const primitive = deps?.primitives?.plan ?? plan;
+  primeChrome(deps);
+  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-cr-plan-"));
+  const projectArchive = join(work, "project.tar.gz");
+  const projectDir = join(work, "project");
+  const planDir = join(work, "plan");
+  try {
+    await downloadGcsObjectToFile(storage, event.ProjectGcsUri, projectArchive);
+    await untarDirectory(projectArchive, projectDir);
+    const config = {
+      ...event.Config
+    };
+    const result = await primitive(projectDir, config, planDir);
+    const planTar = join(work, "plan.tar.gz");
+    await tarDirectory(planDir, planTar);
+    const planTarUri = `${trimTrailingSlash(event.PlanOutputGcsPrefix)}/plan.tar.gz`;
+    const audioPath = join(planDir, "audio.aac");
+    const hasAudio = existsSync3(audioPath) && statSync2(audioPath).size > 0;
+    await uploadFileToGcs(storage, planTar, planTarUri, "application/gzip");
+    return {
+      Action: "plan",
+      PlanGcsUri: planTarUri,
+      PlanHash: result.planHash,
+      ChunkCount: result.chunkCount,
+      TotalFrames: result.totalFrames,
+      Fps: result.fps,
+      Width: result.width,
+      Height: result.height,
+      Format: result.format,
+      HasAudio: hasAudio,
+      AudioGcsUri: null,
+      FfmpegVersion: result.ffmpegVersion,
+      ProducerVersion: result.producerVersion,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function handleRenderChunk(event, deps) {
+  const started = Date.now();
+  const storage = deps?.storage ?? getStorage();
+  const primitive = deps?.primitives?.renderChunk ?? renderChunk;
+  primeChrome(deps);
+  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-cr-chunk-"));
+  const planTar = join(work, "plan.tar.gz");
+  const planDir = join(work, "plan");
+  try {
+    await downloadGcsObjectToFile(storage, event.PlanGcsUri, planTar);
+    await untarDirectory(planTar, planDir);
+    verifyPlanHash(planDir, event.PlanHash);
+    const chunkOutputBase = join(
+      work,
+      event.Format === "png-sequence" ? `chunk-${pad(event.ChunkIndex)}` : `chunk-${pad(event.ChunkIndex)}${formatExtension(event.Format)}`
+    );
+    const result = await primitive(planDir, event.ChunkIndex, chunkOutputBase);
+    const chunkUri = await uploadChunkOutput(
+      storage,
+      result,
+      event.ChunkOutputGcsPrefix,
+      event.ChunkIndex
+    );
+    return {
+      Action: "renderChunk",
+      ChunkGcsUri: chunkUri,
+      ChunkIndex: event.ChunkIndex,
+      Sha256: result.sha256,
+      FramesEncoded: result.framesEncoded,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function uploadChunkOutput(storage, result, prefix, chunkIndex) {
+  const trimmed = trimTrailingSlash(prefix);
+  if (result.outputKind === "file") {
+    const ext = extname(result.outputPath);
+    const uri2 = `${trimmed}/chunks/${pad(chunkIndex)}${ext}`;
+    await uploadFileToGcs(storage, result.outputPath, uri2);
+    return uri2;
+  }
+  const tarball = `${result.outputPath}.tar.gz`;
+  await tarDirectory(result.outputPath, tarball);
+  const uri = `${trimmed}/chunks/${pad(chunkIndex)}.tar.gz`;
+  await uploadFileToGcs(storage, tarball, uri, "application/gzip");
+  return uri;
+}
+async function handleAssemble(event, deps) {
+  const started = Date.now();
+  const storage = deps?.storage ?? getStorage();
+  const primitive = deps?.primitives?.assemble ?? assemble;
+  const work = mkdtempSync(join(deps?.tmpRoot ?? tmpdir(), "hf-cr-assemble-"));
+  const planTar = join(work, "plan.tar.gz");
+  const planDir = join(work, "plan");
+  try {
+    await downloadGcsObjectToFile(storage, event.PlanGcsUri, planTar);
+    await untarDirectory(planTar, planDir);
+    const chunkPaths = await downloadChunkObjects(storage, event.ChunkGcsUris, work, event.Format);
+    let audioPath = null;
+    const planAudio = join(planDir, "audio.aac");
+    if (existsSync3(planAudio) && statSync2(planAudio).size > 0) {
+      audioPath = planAudio;
+    } else if (event.AudioGcsUri) {
+      audioPath = planAudio;
+      await downloadGcsObjectToFile(storage, event.AudioGcsUri, audioPath);
+    }
+    const finalOutput = event.Format === "png-sequence" ? join(work, "output-frames") : join(work, `output${formatExtension(event.Format)}`);
+    const result = await primitive(planDir, chunkPaths, audioPath, finalOutput, {
+      cfr: event.Cfr === true
+    });
+    if (event.Format === "png-sequence") {
+      const tarball = `${finalOutput}.tar.gz`;
+      await tarDirectory(finalOutput, tarball);
+      await uploadFileToGcs(storage, tarball, event.OutputGcsUri, "application/gzip");
+    } else {
+      await uploadFileToGcs(storage, finalOutput, event.OutputGcsUri);
+    }
+    return {
+      Action: "assemble",
+      OutputGcsUri: event.OutputGcsUri,
+      FramesEncoded: result.framesEncoded,
+      FileSize: result.fileSize,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function downloadChunkObjects(storage, uris, workDir, format) {
+  const chunksDir = join(workDir, "chunks");
+  mkdirSync2(chunksDir, { recursive: true });
+  const local = new Array(uris.length);
+  await Promise.all(
+    uris.map(async (uri, i) => {
+      if (!uri) {
+        throw new Error(`[handler] chunk URI at index ${i} is empty`);
+      }
+      const { key } = parseGcsUri(uri);
+      const localPath = join(chunksDir, basename(key));
+      await downloadGcsObjectToFile(storage, uri, localPath);
+      if (format === "png-sequence") {
+        const dirPath = join(chunksDir, `frames-${pad(i)}`);
+        await untarDirectory(localPath, dirPath);
+        local[i] = dirPath;
+      } else {
+        local[i] = localPath;
+      }
+    })
+  );
+  return local;
+}
+function getEventGcsUris(event) {
+  switch (event.Action) {
+    case "plan":
+      return [event.ProjectGcsUri, event.PlanOutputGcsPrefix];
+    case "renderChunk":
+      return [event.PlanGcsUri, event.ChunkOutputGcsPrefix];
+    case "assemble":
+      return [
+        event.PlanGcsUri,
+        ...event.ChunkGcsUris,
+        event.OutputGcsUri,
+        event.AudioGcsUri
+      ].filter((u) => u != null);
+  }
+}
+var warnedAllowlistDisabled = false;
+function validateEventGcsUris(event) {
+  const allowedBucket = process.env.HYPERFRAMES_RENDER_BUCKET?.trim();
+  if (allowedBucket === "*") return;
+  if (!allowedBucket) {
+    if (!warnedAllowlistDisabled) {
+      warnedAllowlistDisabled = true;
+      logEvent({
+        event: "bucket_allowlist_disabled",
+        level: "WARNING",
+        message: 'HYPERFRAMES_RENDER_BUCKET is unset \u2014 the GCS bucket-allowlist guard is DISABLED. Set it to the render bucket name to enforce, or to "*" to opt out intentionally.'
+      });
+    }
+    return;
+  }
+  for (const uri of getEventGcsUris(event)) {
+    const { bucket } = parseGcsUri(uri);
+    if (bucket !== allowedBucket) {
+      const err = new Error(
+        `[handler] GCS_URI_NOT_ALLOWED: URI ${JSON.stringify(uri)} targets bucket "${bucket}" but only "${allowedBucket}" is permitted`
+      );
+      err.name = "GCS_URI_NOT_ALLOWED";
+      throw err;
+    }
+  }
+}
+function pad(n) {
+  return n.toString().padStart(4, "0");
+}
+function trimTrailingSlash(prefix) {
+  return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
+function cleanupDir(dir) {
+  try {
+    rmSync2(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+function verifyPlanHash(planDir, expected) {
+  const planJsonPath = join(planDir, "plan.json");
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(planJsonPath, "utf-8"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const error = new Error(`PLAN_HASH_MISMATCH: failed to read ${planJsonPath}: ${msg}`);
+    error.name = "PLAN_HASH_MISMATCH";
+    throw error;
+  }
+  const actual = parsed.planHash;
+  if (typeof actual !== "string" || actual !== expected) {
+    const error = new Error(
+      `PLAN_HASH_MISMATCH: event PlanHash=${expected} did not match plan.json planHash=${String(actual)}`
+    );
+    error.name = "PLAN_HASH_MISMATCH";
+    throw error;
+  }
+}
+var NON_RETRYABLE_ERROR_NAMES = /* @__PURE__ */ new Set([
+  // Handler-boundary guards.
+  "GCS_URI_NOT_ALLOWED",
+  "PLAN_HASH_MISMATCH",
+  // Producer error class names (`.name`) + their string code aliases — the
+  // class sets `.name` to the class name but wraps a `code`; cover both so a
+  // raw-code throw is caught too. Mirrors the AWS state machine's
+  // non-retryable list.
+  "FormatNotSupportedInDistributedError",
+  "PlanTooLargeError",
+  "RenderChunkValidationError",
+  "FFMPEG_VERSION_MISMATCH",
+  "FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED",
+  "PLAN_TOO_LARGE",
+  "BROWSER_GPU_NOT_SOFTWARE",
+  "FONT_FETCH_FAILED",
+  "ChromeBinaryUnavailableError"
+]);
+function createApp(deps) {
+  const app = new Hono();
+  app.get("/healthz", (c) => c.json({ status: "ok" }));
+  app.post("/", async (c) => {
+    let body;
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: "BAD_REQUEST", message: "request body must be JSON" }, 400);
+    }
+    try {
+      const result = await dispatch(body, deps);
+      return c.json(result, 200);
+    } catch (err) {
+      const name = err instanceof Error ? err.name : void 0;
+      const message = err instanceof Error ? err.message : String(err);
+      const status = name && NON_RETRYABLE_ERROR_NAMES.has(name) ? 400 : 500;
+      return c.json({ error: name ?? "RenderError", message }, status);
+    }
+  });
+  return app;
+}
+function startServer() {
+  const port = Number(process.env.PORT ?? 8080);
+  const app = createApp();
+  serve({ fetch: app.fetch, port }, (info) => {
+    logEvent({ event: "server_listening", port: info.port });
+  });
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  startServer();
+}
+
+// src/sdk/deploySite.ts
+import { mkdtempSync as mkdtempSync2, rmSync as rmSync3, statSync as statSync3 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join2 } from "node:path";
+import { Storage as Storage2 } from "@google-cloud/storage";
+import { hashProjectDir } from "@hyperframes/producer/distributed";
+async function deploySite(opts) {
+  if (!statSync3(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 projectGcsUri = formatGcsUri({ bucket: opts.bucketName, key });
+  const storage = opts.storage ?? new Storage2();
+  const file = storage.bucket(opts.bucketName).file(key);
+  const existing = await headObject(file);
+  if (existing) {
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectGcsUri,
+      bytes: existing.bytes,
+      uploadedAt: existing.lastModified,
+      uploaded: false
+    };
+  }
+  const workdir = mkdtempSync2(join2(tmpdir2(), "hf-deploy-site-"));
+  try {
+    const tarball = join2(workdir, "project.tar.gz");
+    await tarDirectory(opts.projectDir, tarball);
+    const size = statSync3(tarball).size;
+    await uploadFileToGcs(storage, tarball, projectGcsUri, "application/gzip");
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectGcsUri,
+      bytes: size,
+      uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      uploaded: true
+    };
+  } finally {
+    rmSync3(workdir, { recursive: true, force: true });
+  }
+}
+async function headObject(file) {
+  const [exists] = await file.exists();
+  if (!exists) return null;
+  const [meta] = await file.getMetadata();
+  const sizeRaw = meta.size;
+  const bytes = typeof sizeRaw === "string" ? Number(sizeRaw) : typeof sizeRaw === "number" ? sizeRaw : 0;
+  return {
+    bytes: Number.isFinite(bytes) ? bytes : 0,
+    lastModified: meta.updated ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+
+// src/sdk/renderToCloudRun.ts
+import { randomUUID } from "node:crypto";
+
+// src/sdk/validateConfig.ts
+import { InvalidConfigError } from "@hyperframes/producer/distributed";
+import {
+  InvalidConfigError as InvalidConfigError2,
+  validateDistributedRenderConfig,
+  validateVariablesPayload
+} from "@hyperframes/producer/distributed";
+var MAX_WORKFLOWS_INPUT_BYTES = 512 * 1024;
+var LARGE_VARIABLES_DOCS_URL = "https://hyperframes.heygen.com/deploy/templates-on-lambda#working-with-large-variables";
+function validateWorkflowsInputSize(input) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(input);
+  } catch (err) {
+    throw new InvalidConfigError(
+      "config",
+      `Cloud Workflows execution argument is not JSON-serializable: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (serialized === void 0) {
+    throw new InvalidConfigError(
+      "config",
+      "Cloud Workflows execution argument is not JSON-serializable (JSON.stringify returned undefined). Check that all fields, including config.variables, are plain JSON values."
+    );
+  }
+  const byteLength = Buffer.byteLength(serialized, "utf8");
+  if (byteLength > MAX_WORKFLOWS_INPUT_BYTES) {
+    throw new InvalidConfigError(
+      "config",
+      `Cloud Workflows execution argument is ${byteLength} bytes, which exceeds the ${MAX_WORKFLOWS_INPUT_BYTES}-byte (512 KiB) limit. Variables are for typed data (strings, numbers, structured records); media assets (images, audio, video) should be passed as URL references the composition resolves at render time, not inlined as base64. See ${LARGE_VARIABLES_DOCS_URL} for the URL-your-assets convention.`
+    );
+  }
+}
+
+// src/sdk/renderToCloudRun.ts
+async function renderToCloudRun(opts) {
+  validateDistributedRenderConfig(opts.config);
+  if (!opts.bucketName) throw new Error("[renderToCloudRun] bucketName is required");
+  if (!opts.projectId) throw new Error("[renderToCloudRun] projectId is required");
+  if (!opts.location) throw new Error("[renderToCloudRun] location is required");
+  if (!opts.workflowId) throw new Error("[renderToCloudRun] workflowId is required");
+  if (!opts.serviceUrl) throw new Error("[renderToCloudRun] serviceUrl is required");
+  if (!opts.siteHandle && !opts.projectDir) {
+    throw new Error("[renderToCloudRun] either siteHandle or projectDir must be supplied");
+  }
+  const renderId = opts.renderId ?? `hf-render-${randomUUID()}`;
+  if (!/^[A-Za-z0-9._-]+$/.test(renderId) || renderId.includes("..")) {
+    throw new Error(
+      `[renderToCloudRun] renderId must match [A-Za-z0-9._-]+ and not contain "..": ${JSON.stringify(renderId)}`
+    );
+  }
+  const ext = formatExtension(opts.config.format);
+  const outputKey = opts.outputKey ?? `renders/${renderId}/output${ext}`;
+  const planOutputGcsPrefix = formatGcsUri({
+    bucket: opts.bucketName,
+    key: `renders/${renderId}/`
+  });
+  const outputGcsUri = formatGcsUri({ bucket: opts.bucketName, key: outputKey });
+  const site = opts.siteHandle ?? await deploySite({
+    projectDir: opts.projectDir,
+    bucketName: opts.bucketName,
+    storage: opts.storage
+  });
+  const argument = {
+    RenderId: renderId,
+    ProjectGcsUri: site.projectGcsUri,
+    PlanOutputGcsPrefix: planOutputGcsPrefix,
+    OutputGcsUri: outputGcsUri,
+    ServiceUrl: opts.serviceUrl,
+    Config: opts.config
+  };
+  validateWorkflowsInputSize(argument);
+  const executions = opts.executions ?? await defaultExecutionsClient();
+  const parent = executions.workflowPath(opts.projectId, opts.location, opts.workflowId);
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const [execution] = await executions.createExecution({
+    parent,
+    execution: { argument: JSON.stringify(argument) }
+  });
+  if (!execution.name) {
+    throw new Error("[renderToCloudRun] CreateExecution returned no execution name");
+  }
+  return {
+    renderId,
+    executionName: execution.name,
+    bucketName: opts.bucketName,
+    workflowId: opts.workflowId,
+    outputGcsUri,
+    projectGcsUri: site.projectGcsUri,
+    startedAt
+  };
+}
+async function defaultExecutionsClient() {
+  const mod = await import("@google-cloud/workflows");
+  const client = new mod.ExecutionsClient();
+  return client;
+}
+
+// src/sdk/costAccounting.ts
+var CLOUD_RUN_USD_PER_VCPU_SECOND = 24e-6;
+var CLOUD_RUN_USD_PER_GIB_SECOND = 25e-7;
+var CLOUD_RUN_USD_PER_REQUEST = 4e-7;
+var WORKFLOWS_USD_PER_STEP = 1e-5;
+function computeRenderCost(invocations, workflowSteps) {
+  let cloudRunUsd = 0;
+  let anyEstimated = false;
+  for (const inv of invocations) {
+    const seconds = inv.durationMs / 1e3;
+    cloudRunUsd += seconds * inv.vcpu * CLOUD_RUN_USD_PER_VCPU_SECOND;
+    cloudRunUsd += seconds * inv.memoryGib * CLOUD_RUN_USD_PER_GIB_SECOND;
+    cloudRunUsd += CLOUD_RUN_USD_PER_REQUEST;
+    if (inv.estimated) anyEstimated = true;
+  }
+  const workflowsUsd = workflowSteps * WORKFLOWS_USD_PER_STEP;
+  const accruedSoFarUsd = roundUsd(cloudRunUsd + workflowsUsd);
+  return {
+    accruedSoFarUsd,
+    displayCost: formatUsd(accruedSoFarUsd),
+    breakdown: {
+      cloudRunUsd: roundUsd(cloudRunUsd),
+      workflowsUsd: roundUsd(workflowsUsd),
+      gcsEstimate: "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_VCPU = 4;
+var DEFAULT_MEMORY_GIB = 16;
+async function getRenderProgress(opts) {
+  if (!opts.executionName) {
+    throw new Error("[getRenderProgress] executionName is required");
+  }
+  const executions = opts.executions ?? await defaultExecutionsClient2();
+  const vcpu = opts.vcpu ?? DEFAULT_VCPU;
+  const memoryGib = opts.memoryGib ?? DEFAULT_MEMORY_GIB;
+  const [execution] = await executions.getExecution({ name: opts.executionName });
+  const status = mapState(execution.state);
+  const startedAt = toIso(execution.startTime) ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  const endedAt = toIso(execution.endTime);
+  const errors = [];
+  if (execution.error) {
+    errors.push({
+      state: execution.error.context ?? "<execution>",
+      error: extractErrorName(execution.error.payload) ?? "ExecutionError",
+      cause: execution.error.payload ?? ""
+    });
+  }
+  if (status !== "succeeded") {
+    return {
+      status,
+      overallProgress: 0,
+      framesRendered: 0,
+      totalFrames: null,
+      invocationsObserved: 0,
+      costs: computeRenderCost([], 0),
+      outputFile: null,
+      errors,
+      fatalErrorEncountered: status === "failed" || status === "cancelled",
+      startedAt,
+      endedAt
+    };
+  }
+  const acc = parseAccumulated(execution.result);
+  const chunks = acc.Chunks?.filter((c) => c != null) ?? [];
+  const framesRendered = chunks.reduce((sum, c) => sum + (c.FramesEncoded ?? 0), 0);
+  const totalFrames = typeof acc.Plan?.TotalFrames === "number" ? acc.Plan.TotalFrames : null;
+  const invocations = [];
+  const pushInv = (durationMs) => {
+    invocations.push({
+      durationMs: typeof durationMs === "number" ? durationMs : 0,
+      vcpu,
+      memoryGib,
+      estimated: typeof durationMs !== "number"
+    });
+  };
+  if (acc.Plan) pushInv(acc.Plan.DurationMs);
+  for (const c of chunks) pushInv(c.DurationMs);
+  if (acc.Assemble) pushInv(acc.Assemble.DurationMs);
+  const workflowSteps = invocations.length + 4;
+  const costs = computeRenderCost(invocations, workflowSteps);
+  const outputGcsUri = acc.Assemble?.OutputGcsUri;
+  const outputFile = outputGcsUri ? {
+    gcsUri: outputGcsUri,
+    bytes: typeof acc.Assemble?.FileSize === "number" ? acc.Assemble.FileSize : null
+  } : null;
+  return {
+    status,
+    overallProgress: 1,
+    framesRendered,
+    totalFrames,
+    invocationsObserved: invocations.length,
+    costs,
+    outputFile,
+    errors,
+    fatalErrorEncountered: false,
+    startedAt,
+    endedAt
+  };
+}
+function mapState(state) {
+  switch (state) {
+    case "ACTIVE":
+    case "QUEUED":
+      return "running";
+    case "SUCCEEDED":
+      return "succeeded";
+    case "FAILED":
+    case "UNAVAILABLE":
+      return "failed";
+    case "CANCELLED":
+      return "cancelled";
+    default:
+      return "unknown";
+  }
+}
+function parseAccumulated(result) {
+  if (!result) return {};
+  try {
+    const parsed = JSON.parse(result);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+  }
+  return {};
+}
+function extractErrorName(payload) {
+  if (!payload) return void 0;
+  try {
+    const outer = JSON.parse(payload);
+    if (typeof outer.error === "string") return outer.error;
+    if (typeof outer.body === "string") {
+      const inner = JSON.parse(outer.body);
+      if (typeof inner.error === "string") return inner.error;
+    } else if (outer.body && typeof outer.body === "object") {
+      const inner = outer.body;
+      if (typeof inner.error === "string") return inner.error;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function toIso(ts) {
+  if (ts == null) return null;
+  if (typeof ts === "string") return ts;
+  const seconds = ts.seconds == null ? null : Number(ts.seconds);
+  if (seconds == null || !Number.isFinite(seconds)) return null;
+  const ms = seconds * 1e3 + (ts.nanos ?? 0) / 1e6;
+  return new Date(ms).toISOString();
+}
+async function defaultExecutionsClient2() {
+  const mod = await import("@google-cloud/workflows");
+  const client = new mod.ExecutionsClient();
+  return client;
+}
+export {
+  ChromeBinaryUnavailableError,
+  InvalidConfigError2 as InvalidConfigError,
+  computeRenderCost,
+  createApp,
+  deploySite,
+  dispatch,
+  downloadGcsObjectToFile,
+  formatGcsUri,
+  getRenderProgress,
+  parseGcsUri,
+  renderToCloudRun,
+  resolveChromeExecutablePath,
+  startServer,
+  tarDirectory,
+  untarDirectory,
+  unwrapEvent,
+  uploadFileToGcs,
+  validateDistributedRenderConfig
+};
+//# sourceMappingURL=index.js.map