Skip to content

Code-first video & image, rendered natively on WebGPU.

5.1 KB
Raw Blame
/**
 * Stable error codes for render jobs (PLAN.md §10). `retryable` tells RunPod
 * or the caller whether running the same job again can succeed.
 */

export type JobPhase =
	| "boot"
	| "validate"
	| "resolve"
	| "fetch"
	| "lfs"
	| "assets"
	| "install"
	| "load"
	| "render"
	| "verify"
	| "upload"
	| "any";

interface CodeInfo {
	phase: JobPhase;
	retryable: boolean;
}

const CODES = {
	CONFIG_INVALID: { phase: "boot", retryable: false },
	GPU_UNAVAILABLE: { phase: "boot", retryable: false },
	TOOL_MISSING: { phase: "boot", retryable: false },

	JOB_INVALID: { phase: "validate", retryable: false },
	REPO_NOT_ALLOWED: { phase: "validate", retryable: false },
	BUCKET_NOT_ALLOWED: { phase: "validate", retryable: false },
	PATH_ESCAPE: { phase: "validate", retryable: false },
	BUSY: { phase: "validate", retryable: true },

	GIT_AUTH_FAILED: { phase: "resolve", retryable: false },
	REPO_NOT_FOUND: { phase: "resolve", retryable: false },
	REF_NOT_FOUND: { phase: "resolve", retryable: false },
	REF_AMBIGUOUS: { phase: "resolve", retryable: false },
	COMMIT_MISMATCH: { phase: "resolve", retryable: false },
	GIT_TLS_FAILED: { phase: "resolve", retryable: false },

	GIT_NETWORK: { phase: "fetch", retryable: true },
	GIT_CACHE_CORRUPT: { phase: "fetch", retryable: true },

	LFS_AUTH_FAILED: { phase: "lfs", retryable: false },
	LFS_QUOTA_EXCEEDED: { phase: "lfs", retryable: false },
	LFS_UNAVAILABLE: { phase: "lfs", retryable: false },
	LFS_OBJECT_MISSING: { phase: "lfs", retryable: false },
	LFS_POINTER_UNRESOLVED: { phase: "lfs", retryable: false },
	UNSUPPORTED_GIT_FILTER: { phase: "lfs", retryable: false },

	ASSET_MANIFEST_INVALID: { phase: "assets", retryable: false },
	ASSET_PRIVATE: { phase: "assets", retryable: false },
	ASSET_NOT_UPLOADED: { phase: "assets", retryable: false },
	ASSET_FORBIDDEN: { phase: "assets", retryable: false },
	ASSET_DOWNLOAD_FAILED: { phase: "assets", retryable: true },
	ASSET_HASH_MISMATCH: { phase: "assets", retryable: false },

	DISK_FULL: { phase: "any", retryable: true },

	LOCKFILE_MISSING: { phase: "install", retryable: false },
	INSTALL_FAILED: { phase: "install", retryable: false },
	INSTALL_TIMEOUT: { phase: "install", retryable: true },
	ENGINE_NOT_FOUND: { phase: "install", retryable: false },
	ENGINE_SWITCH: { phase: "render", retryable: true },
	ENGINE_UNSUPPORTED: { phase: "render", retryable: false },

	ENTRY_NOT_FOUND: { phase: "load", retryable: false },
	ENTRY_COMPILE_FAILED: { phase: "load", retryable: false },
	EXPORT_NOT_FOUND: { phase: "load", retryable: false },
	EXPORT_INVALID: { phase: "load", retryable: false },
	EXPORT_SIDE_EFFECT: { phase: "load", retryable: false },
	COMPOSITION_BUILD_FAILED: { phase: "load", retryable: false },

	ASSET_NOT_FOUND: { phase: "render", retryable: false },
	RENDER_FAILED: { phase: "render", retryable: false },
	RENDER_STALLED: { phase: "render", retryable: true },
	RENDER_TIMEOUT: { phase: "render", retryable: false },
	RENDER_OOM: { phase: "render", retryable: true },
	GPU_DEVICE_LOST: { phase: "render", retryable: true },
	RENDER_CRASHED: { phase: "render", retryable: true },

	OUTPUT_MISSING: { phase: "verify", retryable: false },
	OUTPUT_INVALID: { phase: "verify", retryable: false },
	OUTPUT_TOO_LARGE: { phase: "verify", retryable: false },
	QA_FAILED: { phase: "verify", retryable: false },

	UPLOAD_FAILED: { phase: "upload", retryable: true },
	UPLOAD_URL_EXPIRED: { phase: "upload", retryable: false },
	UPLOAD_AUTH_FAILED: { phase: "upload", retryable: false },

	CANCELLED: { phase: "any", retryable: false },
	SHUTDOWN: { phase: "any", retryable: true },
	INTERNAL: { phase: "any", retryable: false },
} as const satisfies Record<string, CodeInfo>;

export type ErrorCode = keyof typeof CODES;

export interface RenderErrorJSON {
	code: ErrorCode;
	message: string;
	phase: JobPhase;
	retryable: boolean;
	hint?: string;
	details?: Record<string, unknown>;
}

export class RenderError extends Error {
	readonly code: ErrorCode;
	readonly phase: JobPhase;
	readonly retryable: boolean;
	readonly hint?: string;
	readonly details?: Record<string, unknown>;

	constructor(
		code: ErrorCode,
		message: string,
		options: {
			phase?: JobPhase;
			hint?: string;
			details?: Record<string, unknown>;
			cause?: unknown;
		} = {},
	) {
		super(message, { cause: options.cause });
		this.name = "RenderError";
		this.code = code;
		this.phase = options.phase ?? CODES[code].phase;
		this.retryable = CODES[code].retryable;
		this.hint = options.hint;
		this.details = options.details;
	}

	toJSON(): RenderErrorJSON {
		return {
			code: this.code,
			message: this.message,
			phase: this.phase,
			retryable: this.retryable,
			...(this.hint && { hint: this.hint }),
			...(this.details && { details: this.details }),
		};
	}
}

/** Wraps anything thrown into a RenderError, keeping RenderErrors as they are. */
export function toRenderError(err: unknown, phase: JobPhase): RenderError {
	if (err instanceof RenderError) return err;
	const message = err instanceof Error ? err.message : String(err);
	if (/ENOSPC/.test(message)) {
		return new RenderError("DISK_FULL", message, { phase, cause: err });
	}
	return new RenderError("INTERNAL", message, { phase, cause: err });
}