@hoardodile/host 0.0.0

package/src/probe/image.ts

@@ -0,0 +1,336 @@
+import { extname } from "node:path"
+import type { Readable } from "node:stream"
+import { IMAGE_EXTS } from "@hoardodile/sdk-types/media-exts"
+import { PROBE_HEADER_BYTES } from "../archive/index.ts"
+
+import type { ImageInfo } from "../types.ts"
+
+/**
+ * Max zip entry size read into memory for thumb synthesis. Larger
+ * entries are materialized to disk before sharp/ffmpeg runs.
+ */
+export const THUMB_BUFFER_MAX_BYTES = 32 * 1024 * 1024
+
+/**
+ * Image probing via sharp. sharp is loaded lazily and declared as an
+ * optional peer dependency: the host package stays free of native
+ * binaries, and consumers that never probe images (the browser-side mock,
+ * dependency-light CI installs) never pull it in. When sharp is missing,
+ * probe calls fail loudly instead of degrading silently.
+ */
+type SharpModule = typeof import("sharp")
+
+let sharpPromise: Promise<SharpModule> | undefined
+
+export function loadSharp(): Promise<SharpModule> {
+	sharpPromise ??= import("sharp").catch((err: unknown) => {
+		sharpPromise = undefined
+		throw new Error(
+			`sharp is not installed — add "sharp" to your dependencies to enable image probing: ${err instanceof Error ? err.message : String(err)}`,
+		)
+	})
+	return sharpPromise
+}
+
+export type ImageSourceProbe = {
+	readonly width: number
+	readonly height: number
+	readonly animated: boolean
+}
+
+const ANIMATED_EXT_HINTS = new Set([".gif", ".webp", ".avif"])
+
+export { PROBE_HEADER_BYTES } from "../archive/index.ts"
+
+/** True when `ext` names a format that can carry animation. */
+export function isAnimatedCandidateExt(ext: string): boolean {
+	return ANIMATED_EXT_HINTS.has(ext)
+}
+
+export type ImageMetadataInput =
+	| string
+	| Buffer
+	| Readable
+	| {
+			readonly openStream: () => Promise<Readable>
+			/**
+			 * Optional byte-range read into the underlying source (e.g. a
+			 * zip entry slice). When present, metadata probes read
+			 * {@link PROBE_HEADER_BYTES} from the start instead of
+			 * streaming the whole entry — libvips reads the ENTIRE file
+			 * for metadata from a non-seekable stream, but only the header
+			 * from a buffer.
+			 */
+			readonly readRange?: (start: number, end: number) => Promise<Buffer>
+	  }
+
+/**
+ * Narrow a Node stream into sharp's readable input without assertion.
+ * Async because the sharp module itself is loaded lazily.
+ *
+ * sharp's constructor rejects `sharp(stream, opts)` — for stream input
+ * the input options must be passed AS the first argument (a plain object
+ * of input parameters like `pages`/`animated`) and the readable piped
+ * into the resulting Duplex.
+ */
+export async function sharpFromReadable(
+	stream: Readable,
+	options?: import("sharp").SharpOptions,
+): Promise<import("sharp").Sharp> {
+	if (typeof stream.read !== "function") {
+		throw new Error("expected a readable stream")
+	}
+	const { default: sharp } = await loadSharp()
+	const descriptor =
+		options === undefined || Object.keys(options).length === 0
+			? undefined
+			: ({ ...options } as unknown as import("sharp").SharpInput)
+	const instance = descriptor === undefined ? sharp() : sharp(descriptor)
+	stream.pipe(instance)
+	return instance
+}
+
+function isReadable(input: unknown): input is Readable {
+	return (
+		typeof input === "object" &&
+		input !== null &&
+		typeof (input as Readable).pipe === "function" &&
+		!("openStream" in input)
+	)
+}
+
+function isReopenableImageStream(
+	input: ImageMetadataInput,
+): input is { readonly openStream: () => Promise<Readable> } {
+	return (
+		typeof input === "object" &&
+		input !== null &&
+		!Buffer.isBuffer(input) &&
+		"openStream" in input &&
+		typeof (input as { openStream: unknown }).openStream === "function"
+	)
+}
+
+/**
+ * Sharp options for image thumb/probe reads. Enables sequential read for
+ * large JPEGs on disk so libvips can shrink-on-load during resize.
+ */
+export function sharpImageInputOpts(
+	input: string | Buffer,
+	ext: string,
+	pages: number,
+	animated?: boolean,
+): import("sharp").SharpOptions {
+	const opts: import("sharp").SharpOptions = { pages }
+	if (animated === true) opts.animated = true
+	if (
+		typeof input === "string" &&
+		(ext === ".jpg" || ext === ".jpeg" || ext === ".jfif")
+	) {
+		opts.sequentialRead = true
+	}
+	return opts
+}
+
+/**
+ * True when a shallow `{ pages: 1 }` metadata read is not enough to
+ * decide animation and the full multi-page scan is required.
+ */
+export function needsFullAnimationScan(
+	meta: Pick<
+		import("sharp").Metadata,
+		"width" | "height" | "pages" | "pageHeight"
+	>,
+	ext: string,
+): boolean {
+	if (ext === ".gif") return true
+	if (ANIMATED_EXT_HINTS.has(ext) && (meta.pages ?? 1) > 1) return true
+	if (
+		meta.pageHeight !== undefined &&
+		meta.height !== undefined &&
+		meta.pageHeight !== meta.height
+	) {
+		return true
+	}
+	return false
+}
+
+/**
+ * Buffer a probe stream with a hard byte cap. Only used for formats whose
+ * animation scan needs the whole stream (GIF): probing only needs
+ * metadata, so an entry bigger than the cap is treated as unprobed rather
+ * than buffered whole into host memory.
+ */
+async function bufferCapped(
+	input: Readable,
+	maxBytes: number,
+): Promise<Buffer> {
+	const chunks: Uint8Array[] = []
+	let total = 0
+	for await (const chunk of input) {
+		const bytes: Uint8Array =
+			typeof chunk === "string" ? Buffer.from(chunk) : chunk
+		total += bytes.byteLength
+		if (total > maxBytes) {
+			input.destroy()
+			throw new Error(`probe input exceeds the ${maxBytes}-byte cap`)
+		}
+		chunks.push(bytes)
+	}
+	return Buffer.concat(chunks)
+}
+
+/**
+ * Read image metadata with layered animation detection: static sources
+ * stop after a single-page read; animated containers escalate to
+ * `{ pages: -1 }` only when the shallow probe signals multi-frame input.
+ */
+export async function readImageMetadata(
+	input: ImageMetadataInput,
+	ext: string,
+): Promise<{
+	readonly meta: import("sharp").Metadata
+	readonly animated: boolean
+}> {
+	if (isReopenableImageStream(input)) {
+		// Header-slice fast path: probe a small leading window as a buffer
+		// (header-only libvips read) instead of streaming the whole entry
+		// (full-file read). Only definitive static results are accepted —
+		// animation candidates escalate inside the slice read, and a
+		// truncated buffer cannot complete a full scan, so those fall
+		// through to the stream path where frame counts stay correct. GIF
+		// is skipped outright (its frame count lives at the end).
+		if (input.readRange !== undefined && ext !== ".gif") {
+			const head = await input.readRange(0, PROBE_HEADER_BYTES)
+			if (head.length > 0) {
+				try {
+					const { default: sharp } = await loadSharp()
+					const shallowMeta = await sharp(
+						head,
+						sharpImageInputOpts(head, ext, 1),
+					).metadata()
+					if (!needsFullAnimationScan(shallowMeta, ext)) {
+						return { meta: shallowMeta, animated: false }
+					}
+				} catch {
+					// Truncated header unreadable — fall through to the
+					// stream path.
+				}
+			}
+		}
+		const stream = await input.openStream()
+		const shallow = await sharpFromReadable(stream, { pages: 1 })
+		const shallowMeta = await shallow.metadata()
+		if (!needsFullAnimationScan(shallowMeta, ext)) {
+			return { meta: shallowMeta, animated: false }
+		}
+		const fullStream = await input.openStream()
+		const fullMeta = await sharpFromReadable(fullStream, {
+			pages: -1,
+			animated: true,
+		}).then((s) => s.metadata())
+		return { meta: fullMeta, animated: (fullMeta.pages ?? 1) > 1 }
+	}
+	if (isReadable(input)) {
+		// GIF frame counts are not stored in the container header, so the
+		// full animation scan needs the whole stream — buffer cap-guarded
+		// and reuse the buffer path.
+		if (ext === ".gif") {
+			const data = await bufferCapped(input, THUMB_BUFFER_MAX_BYTES)
+			return readImageMetadata(data, ext)
+		}
+		// Static formats: hand the stream straight to sharp so the probe
+		// reads only the header bytes. (Buffering the whole entry first —
+		// the previous behavior, capped at THUMB_BUFFER_MAX_BYTES — turned
+		// every stream probe into a full read and made entries beyond the
+		// cap unprobeable.)
+		try {
+			const shallow = await sharpFromReadable(input, { pages: 1 })
+			const shallowMeta = await shallow.metadata()
+			if (!needsFullAnimationScan(shallowMeta, ext)) {
+				return { meta: shallowMeta, animated: false }
+			}
+			// Animated candidates (webp/avif/tiff) report their total page
+			// count from the container header, so the shallow read is
+			// conclusive — and the stream cannot be rewound for a full
+			// scan anyway.
+			return {
+				meta: shallowMeta,
+				animated: (shallowMeta.pages ?? 1) > 1,
+			}
+		} finally {
+			input.destroy()
+		}
+	}
+	const { default: sharp } = await loadSharp()
+	const shallow = sharp(input, sharpImageInputOpts(input, ext, 1))
+	const shallowMeta = await shallow.metadata()
+	if (!needsFullAnimationScan(shallowMeta, ext)) {
+		return { meta: shallowMeta, animated: false }
+	}
+	const fullMeta = await sharp(
+		input,
+		sharpImageInputOpts(input, ext, -1, true),
+	).metadata()
+	return { meta: fullMeta, animated: (fullMeta.pages ?? 1) > 1 }
+}
+
+/**
+ * Probe an image path or buffer and return pixel dimensions plus whether
+ * the source is animated. Probe failures return `undefined`.
+ */
+export async function probeImageSource(
+	input: ImageMetadataInput,
+	extHint?: string,
+): Promise<ImageSourceProbe | undefined> {
+	const ext =
+		extHint ?? (typeof input === "string" ? extname(input).toLowerCase() : "")
+	if (ext.length > 0 && !IMAGE_EXTS.has(ext)) return undefined
+	try {
+		const { meta, animated } = await readImageMetadata(input, ext)
+		const h = meta.pageHeight ?? meta.height
+		if (meta.width === undefined || h === undefined) return undefined
+		return { width: meta.width, height: h, animated }
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Probe an image source and return its pixel dimensions. Probe failures
+ * return `undefined` so callers can treat "not yet probed" and "probe
+ * failed" the same way.
+ */
+export async function probeImage(
+	source: ImageMetadataInput,
+): Promise<ImageInfo | undefined> {
+	const probe = await probeImageSource(source)
+	if (probe === undefined) return undefined
+	return { width: probe.width, height: probe.height }
+}
+
+/**
+ * True when the image has more than one frame (animated GIF / WebP / APNG /
+ * AVIF). Uses layered detection so static JPEG/PNG avoid a full-frame scan.
+ * Errors are coerced to `false`.
+ */
+export async function probeAnimatedImage(
+	source: ImageMetadataInput,
+): Promise<boolean> {
+	if (
+		typeof source === "string" &&
+		!IMAGE_EXTS.has(extname(source).toLowerCase())
+	) {
+		return false
+	}
+	try {
+		const probe = await probeImageSource(source)
+		return probe?.animated ?? false
+	} catch (err) {
+		const label = typeof source === "string" ? source : "stream"
+		console.warn(
+			`[probeAnimatedImage] sharp failed on ${label}: ${err instanceof Error ? err.message : String(err)}`,
+		)
+		return false
+	}
+}

package/src/probe/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Probe implementations for the {@link ResourceAPI} builder. Consumed by
+ * the server's plugin wiring and the CLI's bench — the same probing code
+ * on both sides keeps "test path = production path". sharp and ffprobe
+ * are optional peers loaded lazily; see `image.ts` / `video.ts` /
+ * `audio.ts`.
+ */
+
+import { probeAvMedia } from "./av.ts"
+import { probeImageSource } from "./image.ts"
+
+export {
+	audioInfoFromPayload,
+	extToAudioInputFormat,
+	parseFfprobeAudioJson,
+	probeAudio,
+} from "./audio.ts"
+export type { AvProbeOptions } from "./av.ts"
+export { avResultFromPayload, probeAvMedia } from "./av.ts"
+export { resolveFfprobePath } from "./ffprobe.ts"
+export type { ImageMetadataInput, ImageSourceProbe } from "./image.ts"
+export {
+	isAnimatedCandidateExt,
+	loadSharp,
+	needsFullAnimationScan,
+	PROBE_HEADER_BYTES,
+	probeAnimatedImage,
+	probeImage,
+	probeImageSource,
+	readImageMetadata,
+	sharpFromReadable,
+	sharpImageInputOpts,
+	THUMB_BUFFER_MAX_BYTES,
+} from "./image.ts"
+export { SNIFF_HEADER_BYTES, sniffBytes } from "./sniff.ts"
+export type { ProbedVideoMeta } from "./video.ts"
+export {
+	extToFfmpegInputFormat,
+	parseFfprobeJson,
+	probeVideo,
+	probeVideoMeta,
+} from "./video.ts"
+
+/**
+ * The host's real probe implementations, shaped for
+ * `createPluginResourceAPI({ view, ...mediaProbes })`. Every consumer
+ * (server import path, trash fallback, CLI) spreads this same object,
+ * so "what you test is what runs in production" holds by construction
+ * instead of by three copies of the same wiring.
+ */
+export const mediaProbes = {
+	probeImage: probeImageSource,
+	probeAv: probeAvMedia,
+} as const

package/src/probe/sniff.test.ts

@@ -0,0 +1,72 @@
+import sharp from "sharp"
+import { describe, expect, test } from "vitest"
+import { sniffBytes } from "./sniff.ts"
+
+/**
+ * Sniffing is the layer that decides which probe backend a file reaches,
+ * so these cases pin the two branches that matter: a real signature
+ * wins over a lying name, and a signature-less format still gets named.
+ */
+
+async function pngBytes(): Promise<Buffer> {
+	return sharp({
+		create: {
+			width: 4,
+			height: 4,
+			channels: 3,
+			background: { r: 0, g: 0, b: 0 },
+		},
+	})
+		.png()
+		.toBuffer()
+}
+
+describe("sniffBytes", () => {
+	test("magic bytes win over the extension", async () => {
+		await expect(sniffBytes(await pngBytes(), "photo.jpg")).resolves.toEqual({
+			mime: "image/png",
+			ext: ".png",
+			kind: "image",
+			source: "magic",
+		})
+	})
+
+	test("identifies a file with no extension at all", async () => {
+		await expect(sniffBytes(await pngBytes(), "001")).resolves.toEqual({
+			mime: "image/png",
+			ext: ".png",
+			kind: "image",
+			source: "magic",
+		})
+	})
+
+	test("falls back to the extension for signature-less formats", async () => {
+		const text = new TextEncoder().encode("just words, no signature")
+		await expect(sniffBytes(text, "notes.txt")).resolves.toEqual({
+			mime: "text/plain",
+			ext: ".txt",
+			kind: "other",
+			source: "extension",
+		})
+	})
+
+	test("resolves to undefined when neither bytes nor name say anything", async () => {
+		const noise = Uint8Array.from([0x11, 0x22, 0x33, 0x44])
+		await expect(sniffBytes(noise, "blob.bin")).resolves.toBeUndefined()
+	})
+
+	test("an empty head still answers from the name", async () => {
+		await expect(sniffBytes(new Uint8Array(), "clip.mp4")).resolves.toEqual({
+			mime: "video/mp4",
+			ext: ".mp4",
+			kind: "video",
+			source: "extension",
+		})
+	})
+
+	test("container MIME types map to the family they usually carry", async () => {
+		const ogg = new TextEncoder().encode("OggS\0\0\0\0\0\0\0\0\0\0\0\0\0\0")
+		const sniffed = await sniffBytes(ogg, "track.ogg")
+		expect(sniffed?.kind).toBe("audio")
+	})
+})

package/src/probe/sniff.ts

@@ -0,0 +1,67 @@
+import { fileTypeFromName } from "@hoardodile/sdk-types"
+import { mimeToKind } from "@hoardodile/sdk-types/media-exts"
+
+import type { FileType } from "../types.ts"
+
+/**
+ * Content sniffing: what a file's bytes say it is, with the filename as
+ * the fallback rather than the verdict.
+ *
+ * The layering mirrors what the ecosystem settled on (freedesktop's
+ * shared-mime-info, Apache Tika, WHATWG mimesniff): magic-byte matching
+ * decides for binary formats, and the extension only answers for
+ * formats that carry no signature at all — text, subtitles, CSV. That
+ * split is why a `.jpg` holding WebP bytes probes as WebP, while a
+ * `.txt` still resolves to `text/plain`.
+ */
+
+/**
+ * Header window handed to the magic matcher. `file-type` documents 4100
+ * bytes as the sample size that makes its detection deterministic; the
+ * host reads exactly that much and no more, so sniffing an entry costs
+ * one small ranged read.
+ */
+export const SNIFF_HEADER_BYTES = 4100
+
+type FileTypeModule = typeof import("file-type")
+
+let fileTypePromise: Promise<FileTypeModule> | undefined
+
+/**
+ * Load the magic-byte matcher lazily. Sniffing is opt-in per host (the
+ * directory backend never sniffs), so an unused host pays nothing for
+ * the module graph.
+ */
+function loadFileType(): Promise<FileTypeModule> {
+	fileTypePromise ??= import("file-type")
+	return fileTypePromise
+}
+
+/**
+ * Identify a file from a leading byte window plus its name. `head`
+ * should hold the first {@link SNIFF_HEADER_BYTES} bytes; a shorter
+ * slice still works for formats whose signature fits inside it.
+ */
+export async function sniffBytes(
+	head: Uint8Array,
+	path: string,
+): Promise<FileType | undefined> {
+	if (head.byteLength > 0) {
+		try {
+			const { fileTypeFromBuffer } = await loadFileType()
+			const detected = await fileTypeFromBuffer(head)
+			if (detected !== undefined) {
+				return {
+					mime: detected.mime,
+					ext: `.${detected.ext}`,
+					kind: mimeToKind(detected.mime),
+					source: "magic",
+				}
+			}
+		} catch {
+			// A malformed or truncated header is not an error condition —
+			// fall through to the filename, same as a signature-less file.
+		}
+	}
+	return fileTypeFromName(path)
+}

package/src/probe/video.test.ts

@@ -0,0 +1,41 @@
+import { PassThrough, Readable } from "node:stream"
+import { afterEach, describe, expect, test, vi } from "vitest"
+import { probeVideoMeta } from "./video.ts"
+
+vi.mock("execa", () => ({
+	execa: vi.fn(),
+}))
+
+describe("probeVideoMeta", () => {
+	afterEach(() => {
+		vi.clearAllMocks()
+	})
+
+	test("ffprobe receives pipe:0 for stream sources", async () => {
+		const { execa } = await import("execa")
+		const payload = JSON.stringify({
+			streams: [{ codec_type: "video", width: 640, height: 360 }],
+			format: { duration: "1.5" },
+		})
+		vi.mocked(execa).mockReturnValue(
+			Object.assign(
+				Promise.resolve({
+					stdout: payload,
+					stderr: "",
+					exitCode: 0,
+				}),
+				{ stdin: new PassThrough() },
+			) as never,
+		)
+
+		const stream = Readable.from(Buffer.from("fake-video"))
+		const meta = await probeVideoMeta(stream, "/bin/ffprobe", "mp4")
+		const args = vi.mocked(execa).mock.calls[0]?.[1] as string[]
+		expect(args).toContain("pipe:0")
+		expect(args).toContain("-f")
+		expect(args).toContain("mp4")
+		expect(meta.width).toBe(640)
+		expect(meta.height).toBe(360)
+		expect(meta.durationMs).toBe(1500)
+	})
+})

package/src/probe/video.ts

@@ -0,0 +1,116 @@
+import type { Readable } from "node:stream"
+import type { VideoInfo } from "../types.ts"
+import {
+	type FfprobePayload,
+	ffprobeDurationMs,
+	getFfprobePath,
+	parseFfprobePayload,
+	runFfprobeJson,
+} from "./ffprobe.ts"
+
+/**
+ * ffmpeg `-f` container name for piped zip entry bytes (no filename hint).
+ */
+const FFMPEG_INPUT_FORMAT: Readonly<Record<string, string>> = {
+	".mp4": "mp4",
+	".m4v": "mp4",
+	".webm": "webm",
+	".mov": "mov",
+	".mkv": "matroska",
+	".avi": "avi",
+}
+
+/** Resolve an extension to its ffmpeg `-f` container name, or `undefined` for unknown extensions. */
+export function extToFfmpegInputFormat(ext: string): string | undefined {
+	return FFMPEG_INPUT_FORMAT[ext.toLowerCase()]
+}
+
+/**
+ * Video probing via ffprobe (see `ffprobe.ts` for path resolution and the
+ * process plumbing).
+ */
+
+/**
+ * Source-media metadata derived by ffprobe - pixel dimensions of the first
+ * video stream and the playable duration in milliseconds. Any field can be
+ * absent when ffprobe declines to report it (corrupt header, missing
+ * container metadata). Callers persist whichever fields are populated.
+ */
+export type ProbedVideoMeta = {
+	readonly width?: number
+	readonly height?: number
+	readonly durationMs?: number
+}
+
+/**
+ * Run `ffprobe` against `source` and extract width, height and duration.
+ *
+ * @throws `Error` with stderr when ffprobe exits non-zero or emits no JSON.
+ */
+export async function probeVideoMeta(
+	source: string | Readable,
+	ffprobePath: string,
+	inputFormat?: string,
+): Promise<ProbedVideoMeta> {
+	return videoMetaFromPayload(
+		await runFfprobeJson(source, ffprobePath, inputFormat),
+	)
+}
+
+/**
+ * Pure parser; broken out so callers and tests can hit it without spawning
+ * ffprobe. Returns only the fields that survive type narrowing - partial
+ * payloads are normal for malformed media and we prefer surfacing what we
+ * have over rejecting the whole probe.
+ */
+export function parseFfprobeJson(json: string): ProbedVideoMeta {
+	return videoMetaFromPayload(parseFfprobePayload(json))
+}
+
+export function videoMetaFromPayload(payload: FfprobePayload): ProbedVideoMeta {
+	const result: { width?: number; height?: number; durationMs?: number } = {}
+	const videoStream = payload.streams?.find((s) => s.codec_type === "video")
+	if (videoStream !== undefined) {
+		if (typeof videoStream.width === "number" && videoStream.width > 0) {
+			result.width = Math.round(videoStream.width)
+		}
+		if (typeof videoStream.height === "number" && videoStream.height > 0) {
+			result.height = Math.round(videoStream.height)
+		}
+	}
+	const durationMs = ffprobeDurationMs(payload.format)
+	if (durationMs !== undefined) result.durationMs = durationMs
+	return result
+}
+
+/**
+ * Probe a video stream or path with ffprobe and return its pixel
+ * dimensions and duration. Probe failures return `undefined` so callers
+ * can treat "not yet probed" and "probe failed" the same way.
+ */
+export async function probeVideo(
+	source: string | Readable,
+	extHint?: string,
+): Promise<VideoInfo | undefined> {
+	try {
+		const inputFormat =
+			typeof source === "string" || extHint === undefined
+				? undefined
+				: extToFfmpegInputFormat(extHint)
+		const probed = await probeVideoMeta(source, getFfprobePath(), inputFormat)
+		if (
+			probed.width === undefined &&
+			probed.height === undefined &&
+			probed.durationMs === undefined
+		) {
+			return undefined
+		}
+		return {
+			width: probed.width,
+			height: probed.height,
+			durationMs: probed.durationMs,
+		}
+	} catch {
+		return undefined
+	}
+}