Skip to content

Write HTML. Render video. Built for agents.

6.7 KB
Raw Blame
export type CaptureFailureKind =
  | "cancelled"
  | "transient_browser"
  | "protocol_timeout"
  | "memory_exhaustion"
  | "verification"
  | "authoring"
  | "io";

export interface CaptureWorkerDiagnostic {
  workerId: number;
  framesCaptured: number;
  startFrame: number;
  endFrame: number;
  lines: readonly string[];
}

export class CaptureFailure extends Error {
  readonly kind: CaptureFailureKind;
  readonly cause: unknown;
  readonly workerDiagnostics: readonly CaptureWorkerDiagnostic[];

  constructor(input: {
    kind: CaptureFailureKind;
    message: string;
    cause?: unknown;
    workerDiagnostics?: readonly CaptureWorkerDiagnostic[];
  }) {
    super(input.message);
    this.name = "CaptureFailure";
    this.kind = input.kind;
    this.cause = input.cause;
    this.workerDiagnostics = Object.freeze(
      (input.workerDiagnostics ?? []).map((diagnostic) =>
        Object.freeze({ ...diagnostic, lines: Object.freeze([...diagnostic.lines]) }),
      ),
    );
    if (input.cause instanceof Error && input.cause.stack) this.stack = input.cause.stack;
  }
}

const TRANSIENT_BROWSER_ERROR_PATTERNS = [
  /Navigating frame was detached/i,
  /Target closed/i,
  /Session closed/i,
  /browser has disconnected/i,
  /Page crashed/i,
  /Execution context was destroyed/i,
  /Cannot find context with specified id/i,
  /Failed to launch the browser process/i,
  /Navigation timeout of \d+ ms exceeded/i,
  /ECONNREFUSED/i,
  /net::ERR_NETWORK_CHANGED/i,
  /Composition has zero duration[\s\S]*Runtime ready: false/,
  // CDP can refuse a capture call outright with this exact wording; timed-out
  // variants of the same call hit PROTOCOL_TIMEOUT_PATTERNS, checked first.
  // Anchored to this literal reason (not just the CDP method) so an unrelated,
  // genuinely deterministic Page.captureScreenshot error isn't swept in too.
  /Protocol error \(Page\.captureScreenshot\): Unable to capture screenshot/i,
];

const PROTOCOL_TIMEOUT_PATTERNS = [
  /Network\.enable timed out/i,
  /Runtime\.callFunctionOn timed out/i,
  /Runtime\.evaluate timed out/i,
  /Page\.captureScreenshot timed out/i,
  /HeadlessExperimental\.beginFrame timed out/i,
  /drawElement worker encode timed out \(frame \d+\)/i,
  /Protocol error[\s\S]*tim(?:ed|e) out/i,
  /Waiting failed:\s*\d+\s*ms exceeded/i,
  /Waiting failed[\s\S]*timeout/i,
  /timeout exceeded/i,
];

const MEMORY_EXHAUSTION_ERROR_PATTERNS = [
  /Set maximum size exceeded/i,
  /Map maximum size exceeded/i,
  /Invalid (?:array|string) length/i,
  /Array buffer allocation failed/i,
  /Cannot create a string longer than/i,
  /Reached heap limit/i,
  /JavaScript heap out of memory/i,
];

// Bun/JSC reports oversized allocations as the bare string "Out of memory".
// Match only the complete message, or the complete worker segment produced by
// parallel capture, so unrelated WebGL diagnostics are not misclassified.
const BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE = /^out of memory\.?$/i;
const BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE = /\bworker \d+: out of memory\.?(?:;|$)/i;

const VERIFICATION_ERROR_PATTERNS = [
  /DrawElementVerificationError/i,
  /drawElement self-verify/i,
  /verification (?:failed|mismatch)/i,
  /blank drawElement frame/i,
];

const AUTHORING_ERROR_PATTERNS = [
  /Composition has zero duration[\s\S]*Runtime ready: true/i,
  /data-duration/i,
  /No root \[data-composition-id\]/i,
  /failed to parse/i,
  /unparseable/i,
];

function messageOf(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

function matchesAny(message: string, patterns: readonly RegExp[]): boolean {
  return patterns.some((pattern) => pattern.test(message));
}

const IO_OPERATION_TOKENS = ["read", "write", "rename", "copy", "open", "file", "directory"];

function hasIoOperationFailure(message: string): boolean {
  const normalized = message.toLowerCase();
  return normalized.split(/[\r\n]/).some((line) =>
    IO_OPERATION_TOKENS.some((operation) => {
      const operationIndex = line.indexOf(operation);
      if (operationIndex < 0) return false;
      const failureStart = operationIndex + operation.length;
      return line.indexOf("failed", failureStart) >= 0 || line.indexOf("error", failureStart) >= 0;
    }),
  );
}

/**
 * A write to a pipe whose reader has gone: EPIPE on darwin/linux, EOF on
 * win32 (libuv reports a closed named pipe as UV_EOF), ECONNRESET on a
 * socket. All three mean the streaming encoder died under us, which is an io
 * fact about the host, not an authoring defect in the composition.
 */
const BROKEN_PIPE_MESSAGE = /\bwrite (?:EPIPE|EOF|ECONNRESET)\b/;

function ioError(error: unknown, message: string): boolean {
  const code = error instanceof Error ? (error as NodeJS.ErrnoException).code : undefined;
  return (
    Boolean(
      code &&
      /^(?:EACCES|ECONNRESET|EEXIST|EIO|EMFILE|ENFILE|ENOENT|ENOSPC|EOF|EPERM|EPIPE|EROFS)$/.test(
        code,
      ),
    ) ||
    BROKEN_PIPE_MESSAGE.test(message) ||
    hasIoOperationFailure(message)
  );
}

export function classifyCaptureFailure(
  error: unknown,
  options: {
    signal?: AbortSignal;
    workerDiagnostics?: readonly CaptureWorkerDiagnostic[];
  } = {},
): CaptureFailure {
  if (error instanceof CaptureFailure && !options.workerDiagnostics && !options.signal?.aborted) {
    return error;
  }
  const message = messageOf(error);
  let kind: CaptureFailureKind;
  if (options.signal?.aborted || /(?:render|capture)?_?cancelled|AbortError/i.test(message)) {
    kind = "cancelled";
  } else if (
    BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE.test(message.trim()) ||
    BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE.test(message) ||
    matchesAny(message, MEMORY_EXHAUSTION_ERROR_PATTERNS)
  ) {
    kind = "memory_exhaustion";
  } else if (matchesAny(message, VERIFICATION_ERROR_PATTERNS)) {
    kind = "verification";
  } else if (matchesAny(message, PROTOCOL_TIMEOUT_PATTERNS)) {
    kind = "protocol_timeout";
  } else if (matchesAny(message, TRANSIENT_BROWSER_ERROR_PATTERNS)) {
    kind = "transient_browser";
  } else if (matchesAny(message, AUTHORING_ERROR_PATTERNS)) {
    kind = "authoring";
  } else {
    kind = ioError(error, message) ? "io" : "authoring";
  }
  return new CaptureFailure({
    kind,
    message,
    cause: error,
    workerDiagnostics:
      options.workerDiagnostics ??
      (error instanceof CaptureFailure ? error.workerDiagnostics : undefined),
  });
}

export function isTransientBrowserError(error: unknown): boolean {
  return classifyCaptureFailure(error).kind === "transient_browser";
}

export function isMemoryExhaustionError(error: unknown): boolean {
  return classifyCaptureFailure(error).kind === "memory_exhaustion";
}

export function isFatalCaptureFailure(failure: CaptureFailure): boolean {
  return !["cancelled", "transient_browser", "protocol_timeout"].includes(failure.kind);
}