@hoardodile/host 0.0.0

package/src/probe-cache.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "vitest"
+import { createProbeCache } from "./probe-cache.ts"
+
+describe("probe cache", () => {
+	test("a miss computes once and hits afterwards", async () => {
+		const cache = createProbeCache()
+		let calls = 0
+		const compute = async () => {
+			calls++
+			return { width: 1 }
+		}
+		await expect(cache.getOrCompute("a", compute)).resolves.toEqual({
+			width: 1,
+		})
+		await expect(cache.getOrCompute("a", compute)).resolves.toEqual({
+			width: 1,
+		})
+		expect(calls).toBe(1)
+	})
+
+	test("concurrent misses for the same key single-flight", async () => {
+		const cache = createProbeCache()
+		let calls = 0
+		const compute = async () => {
+			calls++
+			await new Promise((resolve) => setTimeout(resolve, 10))
+			return true
+		}
+		const [a, b] = await Promise.all([
+			cache.getOrCompute("k", compute),
+			cache.getOrCompute("k", compute),
+		])
+		expect(a).toBe(true)
+		expect(b).toBe(true)
+		expect(calls).toBe(1)
+	})
+
+	test("undefined results are cached too", async () => {
+		const cache = createProbeCache()
+		let calls = 0
+		const compute = async () => {
+			calls++
+			return undefined
+		}
+		await expect(cache.getOrCompute("x", compute)).resolves.toBeUndefined()
+		await expect(cache.getOrCompute("x", compute)).resolves.toBeUndefined()
+		expect(calls).toBe(1)
+	})
+
+	test("rejections are not cached — the next caller retries", async () => {
+		const cache = createProbeCache()
+		let calls = 0
+		const failing = async (): Promise<{ width: number }> => {
+			calls++
+			throw new Error("transient")
+		}
+		await expect(cache.getOrCompute("x", failing)).rejects.toThrow("transient")
+		// Let the rejection cleanup land.
+		await new Promise((resolve) => setTimeout(resolve, 0))
+		await expect(
+			cache.getOrCompute("x", async () => ({ width: 2 })),
+		).resolves.toEqual({ width: 2 })
+		expect(calls).toBe(1)
+	})
+
+	test("evicts the least recently used entry beyond the bound", async () => {
+		const cache = createProbeCache(2)
+		const compute = async () => true
+		await cache.getOrCompute("a", compute)
+		await cache.getOrCompute("b", compute)
+		// Touch "a" so "b" becomes the eviction candidate.
+		await cache.getOrCompute("a", compute)
+		await cache.getOrCompute("c", compute)
+
+		let aCalls = 0
+		await cache.getOrCompute("a", async () => {
+			aCalls++
+			return true
+		})
+		expect(aCalls).toBe(0) // "a" survived as recently used
+
+		let bCalls = 0
+		await cache.getOrCompute("b", async () => {
+			bCalls++
+			return true
+		})
+		expect(bCalls).toBe(1) // "b" was evicted and recomputed
+	})
+})

package/src/probe-cache.ts

@@ -0,0 +1,65 @@
+/**
+ * Process-wide LRU cache for host-side probe results (image/video/audio
+ * metadata and animation flags). Source archives are immutable per
+ * fileVersion, so entries never need explicit invalidation — the cache
+ * scope carries the version and the LRU bound handles eviction.
+ */
+
+/** Process-wide bound (entries) for the host-side probe result cache. */
+export const PLUGIN_PROBE_CACHE_MAX_ENTRIES = 512
+
+/** Cacheable probe result; `undefined` marks a probe that found nothing. */
+type ProbeValue = object | boolean | undefined
+
+export type PluginProbeCache = {
+	/**
+	 * Return the cached result for `key`, computing and storing it on a
+	 * miss. Concurrent callers for the same key share one computation.
+	 */
+	readonly getOrCompute: <T extends ProbeValue>(
+		key: string,
+		compute: () => Promise<T>,
+	) => Promise<T>
+}
+
+/**
+ * Create the probe LRU cache. Keys are caller-composed (probe kind +
+ * version + path); concurrent misses single-flight through one shared
+ * computation; failures are evicted so the next caller retries.
+ */
+export function createProbeCache(
+	maxEntries = PLUGIN_PROBE_CACHE_MAX_ENTRIES,
+): PluginProbeCache {
+	// Promise-valued cells: a miss is stored before it settles, so
+	// concurrent probes for the same key single-flight through one
+	// computation.
+	const cells = new Map<string, Promise<ProbeValue>>()
+
+	return {
+		getOrCompute<T extends ProbeValue>(
+			key: string,
+			compute: () => Promise<T>,
+		): Promise<T> {
+			const existing = cells.get(key)
+			if (existing !== undefined) {
+				// Refresh LRU position.
+				cells.delete(key)
+				cells.set(key, existing)
+				// Type-erased store: each key is namespaced by probe kind, so
+				// the stored promise always resolves to the caller's T.
+				return existing as Promise<T>
+			}
+			const promise = compute()
+			cells.set(key, promise)
+			promise.catch(() => {
+				// Failures are not cached — the next caller retries.
+				if (cells.get(key) === promise) cells.delete(key)
+			})
+			if (cells.size > maxEntries) {
+				const oldest = cells.keys().next().value
+				if (oldest !== undefined) cells.delete(oldest)
+			}
+			return promise
+		},
+	}
+}

package/src/render/ffmpeg.ts

@@ -0,0 +1,78 @@
+/**
+ * Resolve the absolute paths to `ffmpeg` / `ffprobe` for this host.
+ *
+ * Precedence:
+ *   1. Explicit env vars (`FFMPEG_PATH`, `FFPROBE_PATH`).
+ *   2. `ffmpeg-static` and `@derhuerst/ffprobe-static` via lazy
+ *      `createRequire`, so they stay out of the host tarball. Dev
+ *      resolves them from this package's `node_modules`; `pnpm start`
+ *      and the desktop sidecar resolve them from the server
+ *      `dist/node_modules` copy.
+ *   3. A bare command name (`ffmpeg` / `ffprobe`), which lets operators
+ *      who have the binaries on PATH still run the server directly.
+ */
+import { createRequire } from "node:module"
+
+const requireCjs = createRequire(import.meta.url)
+
+export type FfmpegPaths = {
+	readonly ffmpeg: string
+	readonly ffprobe: string
+}
+
+type ResolveDeps = {
+	readonly env?: NodeJS.ProcessEnv
+	/** Override for tests so they never hit the real module. */
+	readonly loadStatic?: () => string | undefined
+	/** Override for tests so they never hit the real module. */
+	readonly loadStaticFfprobe?: () => string | undefined
+}
+
+export function resolveFfmpegPaths(deps: ResolveDeps = {}): FfmpegPaths {
+	const env = deps.env ?? process.env
+	const ffmpegEnv = env.FFMPEG_PATH
+	const ffprobeEnv = env.FFPROBE_PATH
+	const staticFfmpeg =
+		ffmpegEnv === undefined || ffmpegEnv.length === 0
+			? (deps.loadStatic ?? loadInstallerFfmpeg)()
+			: undefined
+	const ffmpeg =
+		ffmpegEnv !== undefined && ffmpegEnv.length > 0
+			? ffmpegEnv
+			: (staticFfmpeg ?? "ffmpeg")
+	const staticFfprobe =
+		ffprobeEnv === undefined || ffprobeEnv.length === 0
+			? (deps.loadStaticFfprobe ?? loadInstallerFfprobe)()
+			: undefined
+	const ffprobe =
+		ffprobeEnv !== undefined && ffprobeEnv.length > 0
+			? ffprobeEnv
+			: (staticFfprobe ?? "ffprobe")
+	return { ffmpeg, ffprobe }
+}
+
+function loadInstallerFfmpeg(): string | undefined {
+	return loadInstallerPath("ffmpeg-static")
+}
+
+function loadInstallerFfprobe(): string | undefined {
+	return loadInstallerPath("@derhuerst/ffprobe-static")
+}
+
+function loadInstallerPath(moduleName: string): string | undefined {
+	try {
+		const mod: unknown = requireCjs(moduleName)
+		if (typeof mod === "string" && mod.length > 0) return mod
+		if (
+			mod !== null &&
+			typeof mod === "object" &&
+			"path" in mod &&
+			typeof (mod as { path: unknown }).path === "string"
+		) {
+			return (mod as { path: string }).path
+		}
+		return undefined
+	} catch {
+		return undefined
+	}
+}

package/src/render/index.ts

@@ -0,0 +1,34 @@
+/**
+ * The thumbnail/preview render pipeline: sharp for images, ffmpeg for
+ * video frames and embedded audio artwork. It lives in the host — next
+ * to the probes it shares a sharp instance with — so every consumer
+ * renders identically: the server's thumb service in production, and
+ * `hoardodile plugin dev` when it serves preview variants and seek
+ * frames to the workbench.
+ *
+ * sharp is a required peer here (unlike probing, rendering cannot
+ * degrade); ffmpeg/ffprobe binaries are resolved lazily by `ffmpeg.ts`.
+ */
+
+export type { FfmpegPaths } from "./ffmpeg.ts"
+export { resolveFfmpegPaths } from "./ffmpeg.ts"
+export type {
+	ImageThumbInput,
+	ImageThumbRenderResult,
+	RenderResult,
+	VideoFrameSource,
+} from "./pipeline.ts"
+export {
+	ANIMATED_AREA_DIVISOR,
+	AVIF_EFFORT,
+	AVIF_QUALITY,
+	cleanOrphanedTempFiles,
+	fitInsideArea,
+	PREVIEW_AVIF_QUALITY,
+	PREVIEW_WEBP_QUALITY,
+	renderAudioCoverArt,
+	renderImageThumbOnce,
+	renderImageWithArea,
+	renderVideoFrame,
+	WEBP_QUALITY,
+} from "./pipeline.ts"

package/src/render/pipeline.test.ts

@@ -0,0 +1,187 @@
+import { mkdtempSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { PassThrough, Readable } from "node:stream"
+import sharp from "sharp"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { renderImageThumbOnce, renderVideoFrame } from "./pipeline.ts"
+
+vi.mock("node:child_process", () => ({
+	spawn: vi.fn(),
+	execFile: vi.fn(),
+}))
+
+describe("renderImageThumbOnce stream input", () => {
+	afterEach(() => {
+		vi.resetModules()
+		vi.clearAllMocks()
+	})
+
+	test("reopenable stream input renders (piped sharp input)", async () => {
+		// Regression lock for the >32MB stream path: sharp's constructor
+		// rejects `sharp(stream, opts)`, so stream inputs must go through
+		// the piped-descriptor form in sharpFromReadable.
+		const png = await sharp({
+			create: {
+				width: 64,
+				height: 48,
+				channels: 3,
+				background: { r: 12, g: 34, b: 56 },
+			},
+		})
+			.png()
+			.toBuffer()
+
+		const destDir = mkdtempSync(join(tmpdir(), "stream-thumb-"))
+		try {
+			const rendered = await renderImageThumbOnce({
+				input: { openStream: async () => Readable.from(png) },
+				ext: ".png",
+				resolveDest: (fmt) => join(destDir, `cover.${fmt}`),
+				variant: {
+					format: "avif",
+					fit: "inside",
+					maxArea: 10_000,
+					webpQuality: 82,
+					avifQuality: 65,
+				},
+			})
+			expect(rendered.format).toBe("avif")
+			const meta = await sharp(rendered.path).metadata()
+			expect(meta.width).toBe(64)
+			expect(meta.height).toBe(48)
+		} finally {
+			rmSync(destDir, { recursive: true, force: true })
+		}
+	})
+
+	test("fit exact transcodes at source dimensions even under a tiny area cap", async () => {
+		const png = await sharp({
+			create: {
+				width: 64,
+				height: 48,
+				channels: 3,
+				background: { r: 12, g: 34, b: 56 },
+			},
+		})
+			.png()
+			.toBuffer()
+
+		const destDir = mkdtempSync(join(tmpdir(), "exact-thumb-"))
+		try {
+			const rendered = await renderImageThumbOnce({
+				input: png,
+				ext: ".png",
+				resolveDest: (fmt) => join(destDir, `exact.${fmt}`),
+				// A cap this small would shrink the source under `inside`;
+				// `exact` must ignore it entirely.
+				variant: {
+					format: "avif",
+					fit: "exact",
+					maxArea: 100,
+					webpQuality: 82,
+					avifQuality: 65,
+				},
+			})
+			expect(rendered.format).toBe("avif")
+			expect(rendered.displayWidth).toBe(64)
+			expect(rendered.displayHeight).toBe(48)
+			const meta = await sharp(rendered.path).metadata()
+			expect(meta.width).toBe(64)
+			expect(meta.height).toBe(48)
+		} finally {
+			rmSync(destDir, { recursive: true, force: true })
+		}
+	})
+
+	test("fit inside still downscales to the area cap", async () => {
+		const png = await sharp({
+			create: {
+				width: 64,
+				height: 48,
+				channels: 3,
+				background: { r: 12, g: 34, b: 56 },
+			},
+		})
+			.png()
+			.toBuffer()
+
+		const destDir = mkdtempSync(join(tmpdir(), "inside-thumb-"))
+		try {
+			const rendered = await renderImageThumbOnce({
+				input: png,
+				ext: ".png",
+				resolveDest: (fmt) => join(destDir, `inside.${fmt}`),
+				variant: {
+					format: "avif",
+					fit: "inside",
+					maxArea: 100,
+					webpQuality: 82,
+					avifQuality: 65,
+				},
+			})
+			const meta = await sharp(rendered.path).metadata()
+			const area = (meta.width ?? 0) * (meta.height ?? 0)
+			expect(area).toBeLessThan(100)
+			expect(meta.width).toBeLessThan(64)
+		} finally {
+			rmSync(destDir, { recursive: true, force: true })
+		}
+	})
+})
+
+describe("renderVideoFrame", () => {
+	afterEach(() => {
+		vi.resetModules()
+		vi.clearAllMocks()
+	})
+
+	test("ffmpeg receives pipe:0 for stream sources", async () => {
+		const { spawn } = await import("node:child_process")
+		const jpeg = await sharp({
+			create: {
+				width: 8,
+				height: 8,
+				channels: 3,
+				background: { r: 1, g: 2, b: 3 },
+			},
+		})
+			.jpeg()
+			.toBuffer()
+		const fakeChild = {
+			stdin: new PassThrough(),
+			stdout: {
+				on: vi.fn((_event: string, handler: (chunk: Buffer) => void) => {
+					handler(jpeg)
+				}),
+			},
+			stderr: { on: vi.fn() },
+			on: vi.fn((event: string, handler: (code: number) => void) => {
+				if (event === "close") handler(0)
+			}),
+		}
+		vi.mocked(spawn).mockReturnValue(fakeChild as never)
+
+		const destDir = mkdtempSync(join(tmpdir(), "pipe-frame-"))
+		try {
+			const destPath = join(destDir, "frame.avif")
+			const stream = Readable.from(Buffer.from("fake-video"))
+			await renderVideoFrame({
+				source: stream,
+				ext: ".mp4",
+				destPath,
+				ffmpeg: { ffmpeg: "/bin/ffmpeg", ffprobe: "/bin/ffprobe" },
+				maxArea: 10_000,
+				quality: 65,
+			})
+			const args = vi.mocked(spawn).mock.calls[0]?.[1] as string[]
+			expect(args).toContain("pipe:0")
+			expect(args).toContain("-f")
+			expect(args).toContain("mp4")
+			expect(args).not.toContain("-ss")
+			expect(args).not.toContain("fake-video")
+		} finally {
+			rmSync(destDir, { recursive: true, force: true })
+		}
+	})
+})