Skip to content

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

5.9 KB
Raw Blame
import { existsSync, readFileSync, realpathSync } from "node:fs";
import { createRequire } from "node:module";
import path from "node:path";
import { pathToFileURL } from "node:url";
import { RenderError } from "../errors.js";
import { rendererLogger } from "../logger.js";
import {
	describeAdapter,
	type GpuAdapter,
	gpuStatus,
	verifyAdapter,
} from "../worker/gpu.js";
import { workerHealth } from "../worker/health.js";
import { setEngineEntry } from "./engine-alias.js";

/** The parts of a project's `framefields` module the worker uses. */
export interface EngineModule {
	HeadlessMediaRenderer: {
		new (): EngineRenderer;
		initialize(): Promise<void>;
	};
	Composition?: abstract new (...args: never[]) => unknown;
	Media?: abstract new (...args: never[]) => unknown;
	FontManager?: { clear(): void };
	/** Present in framefields versions built for long-lived workers. */
	resetRenderCaches?: () => void;
	/** The adapter the engine renders on (newer framefields versions). */
	describeGpu?: () => Promise<GpuAdapter>;
	/** Split renders (framefields with `renderVideo({ frames })`). */
	planChunks?: (options: Record<string, unknown>) => unknown;
	stitchChunks?: (options: {
		chunks: readonly string[];
		audio?: string;
		outputPath: string;
		signal?: AbortSignal;
	}) => Promise<{ filePath: string; frames: number; durationSec: number }>;
}

export interface EngineRenderer {
	renderLut(vm: never, frame?: number): Promise<string | Buffer>;
	/** Present with `planChunks`: frame costs across the timeline. */
	probeRender?(
		vm: never,
		options: {
			samples?: number;
			signal?: AbortSignal;
			onSample?: (done: number, total: number) => void;
		},
	): Promise<{
		totalFrames: number;
		fps: number;
		durationMs: number;
		samples: { frame: number; ms: number }[];
	}>;
}

export interface BoundEngine {
	version: string;
	/** Real path of the framefields package directory. */
	dir: string;
	entryUrl: string;
	/** Workspace slot the engine was loaded from (kept by the janitor). */
	workspace: string;
	mod: EngineModule;
	/** Engine supports `signal`/`onProgress` and the per-job cache reset. */
	workerHooks: boolean;
}

let bound: BoundEngine | undefined;
/** Workspaces whose node_modules this process has loaded modules from. */
const loadedDeps = new Set<string>();

export function markDepsLoaded(workspace: string): void {
	loadedDeps.add(workspace);
}

/**
 * Dependencies stay cached by path for the life of the process, so a new
 * install in a workspace this process already loaded from can't take effect
 * without a restart.
 */
export function depsLoadedFrom(workspace: string): boolean {
	return loadedDeps.has(workspace);
}

export function boundEngine(): BoundEngine | undefined {
	return bound;
}

/** Finds the framefields the project installed, as seen from its workdir. */
export function locateEngine(workdir: string): {
	version: string;
	dir: string;
	entryUrl: string;
} {
	let entry: string;
	try {
		entry = createRequire(path.join(workdir, "package.json")).resolve(
			"framefields",
		);
	} catch {
		throw new RenderError(
			"ENGINE_NOT_FOUND",
			"The project does not have framefields installed.",
			{
				phase: "install",
				hint: 'Add "framefields" to the package.json dependencies (and commit the lockfile).',
			},
		);
	}
	for (let dir = path.dirname(entry); ; dir = path.dirname(dir)) {
		const file = path.join(dir, "package.json");
		if (existsSync(file)) {
			const pkg = JSON.parse(readFileSync(file, "utf8")) as {
				name?: string;
				version?: string;
			};
			if (pkg.name === "framefields" && pkg.version) {
				return {
					version: pkg.version,
					dir: realpathSync(dir),
					entryUrl: pathToFileURL(realpathSync(entry)).href,
				};
			}
		}
		if (path.dirname(dir) === dir) {
			throw new RenderError(
				"ENGINE_NOT_FOUND",
				"Found framefields but not its package.json.",
				{ phase: "install" },
			);
		}
	}
}

/**
 * Returns the engine for this job (PLAN.md §7). The first job binds the
 * worker to its project's framefields version: loaded once, GPU initialised
 * once. Later jobs needing the same version share it, even from other repos.
 * A different version can't share the process (one GPU stack per process):
 * the job fails with retryable ENGINE_SWITCH and the worker recycles, so the
 * retry lands on a fresh worker.
 */
export async function bindEngine(
	workdir: string,
	workspace: string,
): Promise<BoundEngine> {
	const found = locateEngine(workdir);
	if (bound) {
		if (bound.version === found.version) return bound;
		workerHealth.requestRecycle(
			`engine switch ${bound.version} → ${found.version}`,
		);
		throw new RenderError(
			"ENGINE_SWITCH",
			`This worker runs framefields ${bound.version}; the project needs ${found.version}.`,
			{
				phase: "render",
				hint: "Retry: the worker restarts and loads the project's version.",
			},
		);
	}

	setEngineEntry(found.entryUrl);
	const mod = (await import(/* @vite-ignore */ found.entryUrl)) as EngineModule;
	if (typeof mod.HeadlessMediaRenderer?.initialize !== "function") {
		throw new RenderError(
			"ENGINE_NOT_FOUND",
			`framefields ${found.version} has no HeadlessMediaRenderer.`,
			{
				phase: "render",
			},
		);
	}
	try {
		await mod.HeadlessMediaRenderer.initialize();
	} catch (err) {
		workerHealth.requestRecycle("GPU initialisation failed");
		throw new RenderError(
			"GPU_UNAVAILABLE",
			err instanceof Error ? err.message : String(err),
			{
				phase: "render",
				cause: err,
			},
		);
	}
	// A GPU machine must not end up rendering on the CPU driver (gpu.ts).
	verifyAdapter(await describeAdapter(mod).catch(() => undefined));
	bound = {
		...found,
		workspace,
		mod,
		workerHooks: typeof mod.resetRenderCaches === "function",
	};
	rendererLogger.info(
		{
			version: found.version,
			workerHooks: bound.workerHooks,
			gpu: gpuStatus(),
		},
		"Bound framefields engine and initialised the GPU",
	);
	return bound;
}

/** Test hook: forget the bound engine. */
export function _resetEngineBinding(): void {
	bound = undefined;
	loadedDeps.clear();
}