@hoardodile/host 0.0.0

package/src/nested-view.ts

@@ -0,0 +1,239 @@
+import { createReadStream } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+import type { Readable } from "node:stream"
+import { buffer } from "node:stream/consumers"
+import {
+	type ExtractedEntry,
+	readExistingManifest,
+} from "./archive/extract-archive.ts"
+import type { NestedCdCache, NestedResolver } from "./archive/index.ts"
+import { createNestedResolver, splitVirtualPath } from "./archive/index.ts"
+import { readFileRange } from "./archive/zip-entries.ts"
+import type { ResourceContainer } from "./container.ts"
+
+/**
+ * Wrap a {@link ResourceContainer} so every read operation understands
+ * virtual paths (`outer!inner`, see `./archive`). The plugin API,
+ * the server artifact view and the CLI directory container all funnel
+ * entry reads through this wrapper, so nested-container support lands
+ * everywhere (hooks, cover pipeline, thumbnails, the HTTP file route)
+ * without each consumer knowing about containers.
+ *
+ * A virtual path resolves in two steps:
+ *   1. nested zip addressing — the resolver reads the outer entry's
+ *      central directory and streams the *decompressed* inner bytes;
+ *   2. materialized cache addressing — when `extractCacheDir` is wired
+ *      and the outer archive was extracted by the plugin API (its
+ *      manifest exists in `<extractCacheDir>/<outer>/`), the inner file
+ *      is served straight from disk. This is how non-zip containers
+ *      (rar/7z/tar — not expressible as random-access sources) get
+ *      `outer!inner` addressing after extraction, and it is strictly
+ *      better than streaming: entries are seekable.
+ *
+ * Literal entries pass through untouched; virtual entries are only
+ * addressable by name, never enumerated.
+ *
+ * `scope` prefixes nested-cache keys when the cache is shared across
+ * containers (see {@link createNestedResolver}); `resolveSeekablePath`
+ * forwards the base container's capability for literal entries and the
+ * extracted file path for materialized ones.
+ */
+export function createNestedAwareContainer(
+	base: ResourceContainer,
+	nestedCdCache?: NestedCdCache,
+	scope?: string,
+	extractCacheDir?: string,
+): ResourceContainer {
+	const resolver = createNestedResolver(
+		{
+			sizeOf: (rel) => base.resolveByteRange(rel).then((r) => r?.size),
+			readSlice: (rel, start, end) => base.readEntrySlice(rel, start, end),
+		},
+		{ cdCache: nestedCdCache, scope },
+	)
+
+	// Manifest reads are memoized per (cacheDir, outer): archives are
+	// immutable per version, so a parsed manifest never needs invalidation.
+	const manifestMemo = new Map<
+		string,
+		Promise<readonly ExtractedEntry[] | undefined>
+	>()
+
+	function readManifest(
+		outer: string,
+	): Promise<readonly ExtractedEntry[] | undefined> {
+		const key = `${extractCacheDir}:${outer}`
+		const pending = manifestMemo.get(key)
+		if (pending !== undefined) return pending
+		const work = readExistingManifest(
+			join(extractCacheDir!, outer, "index.json"),
+			outer,
+		).catch(() => undefined)
+		manifestMemo.set(key, work)
+		return work
+	}
+
+	type MaterializedEntry = {
+		readonly kind: "materialized"
+		readonly absPath: string
+		readonly sizeBytes: number
+	}
+
+	/**
+	 * Resolve `outer!inner` against the extraction cache: the inner path
+	 * must appear in the outer's manifest (the manifest paths were
+	 * sanitized at extraction time, so this is a whitelist — no
+	 * traversal can reach outside the cache dir).
+	 */
+	async function resolveMaterialized(
+		rel: string,
+	): Promise<MaterializedEntry | undefined> {
+		if (extractCacheDir === undefined) return undefined
+		const parts = splitVirtualPath(rel)
+		if (parts === undefined) return undefined
+		const { outer, inner } = parts
+		const manifest = await readManifest(outer)
+		const entry = manifest?.find((e) => e.path === inner)
+		if (entry === undefined) return undefined
+		return {
+			kind: "materialized",
+			absPath: join(extractCacheDir, outer, inner),
+			sizeBytes: entry.sizeBytes,
+		}
+	}
+
+	async function resolve(rel: string) {
+		const nested = await resolver.resolve(rel)
+		if (nested.kind === "container") return nested
+		const materialized = await resolveMaterialized(rel)
+		return materialized ?? nested
+	}
+
+	async function readEntrySlice(
+		rel: string,
+		start: number,
+		end: number,
+	): Promise<Buffer> {
+		const resolved = await resolve(rel)
+		if (resolved.kind === "literal") {
+			return base.readEntrySlice(rel, start, end)
+		}
+		if (resolved.kind === "materialized") {
+			// readEntrySlice's `end` is exclusive; readFileRange's is
+			// inclusive.
+			return readFileRange(resolved.absPath, start, end - 1)
+		}
+		// Slice the decompressed bytes: consume the stream only up to
+		// `end` so head reads (sniff/probe windows) stay bounded.
+		return readVirtualSlice(() => resolved.openStream(), start, end)
+	}
+
+	async function openEntryStream(rel: string): Promise<{
+		readonly stream: Readable
+		readonly size: number
+		readonly mtimeMs?: number
+		readonly path?: string
+	}> {
+		const resolved = await resolve(rel)
+		if (resolved.kind === "literal") {
+			return base.openEntryStream(rel)
+		}
+		if (resolved.kind === "materialized") {
+			return {
+				stream: createReadStream(resolved.absPath),
+				size: resolved.sizeBytes,
+				path: resolved.absPath,
+			}
+		}
+		return { stream: resolved.openStream(), size: resolved.entry.sizeBytes }
+	}
+
+	async function readEntry(rel: string): Promise<Buffer> {
+		const resolved = await resolve(rel)
+		if (resolved.kind === "literal") {
+			return base.readEntry(rel)
+		}
+		if (resolved.kind === "materialized") {
+			return readFile(resolved.absPath)
+		}
+		return buffer(resolved.openStream())
+	}
+
+	async function resolveByteRange(
+		rel: string,
+	): Promise<{ readonly size: number } | undefined> {
+		const resolved = await resolve(rel)
+		if (resolved.kind === "literal") {
+			return base.resolveByteRange(rel)
+		}
+		if (resolved.kind === "materialized") {
+			return { size: resolved.sizeBytes }
+		}
+		return { size: resolved.entry.sizeBytes }
+	}
+
+	async function resolveSeekablePath(rel: string): Promise<string | undefined> {
+		const resolved = await resolve(rel)
+		if (resolved.kind === "literal") {
+			return base.resolveSeekablePath?.(rel)
+		}
+		if (resolved.kind === "materialized") {
+			// Extracted files are real on-disk entries — libvips/ffmpeg
+			// can mmap/open them directly instead of streaming.
+			return resolved.absPath
+		}
+		return undefined
+	}
+
+	return {
+		listEntries: base.listEntries,
+		readEntry,
+		readEntrySlice,
+		openEntryStream,
+		resolveByteRange,
+		resolveSeekablePath,
+	}
+}
+
+/**
+ * Read `[start, end)` of an entry stream without buffering more than
+ * `end` bytes. STORED and DEFLATE entries alike stream through this
+ * path, so a truncated header slice never inflates the whole entry.
+ */
+async function readVirtualSlice(
+	openStream: () => Readable,
+	start: number,
+	end: number,
+): Promise<Buffer> {
+	if (end <= start) return Buffer.alloc(0)
+	const chunks: Buffer[] = []
+	let collected = 0
+	await new Promise<void>((resolveDone, rejectDone) => {
+		const stream = openStream()
+		stream.on("data", (chunk: Buffer | string) => {
+			const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk
+			const need = end - collected
+			if (need <= 0) {
+				stream.destroy()
+				resolveDone()
+				return
+			}
+			const take = bytes.subarray(0, Math.min(need, bytes.length))
+			chunks.push(take)
+			collected += take.length
+			if (collected >= end) {
+				stream.destroy()
+				resolveDone()
+			}
+		})
+		stream.on("end", () => resolveDone())
+		stream.on("error", (err) => rejectDone(err))
+	})
+	const full = Buffer.concat(chunks, collected)
+	const sliceStart = Math.min(start, full.length)
+	return full.subarray(sliceStart)
+}
+
+/** Resolver instance type re-export for callers that build their own views. */
+export type { NestedResolver }

package/src/probe/audio.test.ts

@@ -0,0 +1,135 @@
+// @vitest-environment node
+
+import { describe, expect, test } from "vitest"
+import { extToAudioInputFormat, parseFfprobeAudioJson } from "./audio.ts"
+
+function payload(value: unknown): string {
+	return JSON.stringify(value)
+}
+
+describe("parseFfprobeAudioJson", () => {
+	test("reads stream parameters, duration and bit rate", () => {
+		const info = parseFfprobeAudioJson(
+			payload({
+				streams: [
+					{
+						codec_type: "audio",
+						codec_name: "flac",
+						sample_rate: "44100",
+						channels: 2,
+					},
+				],
+				format: { duration: "183.456", bit_rate: "938211" },
+			}),
+		)
+		expect(info).toEqual({
+			codec: "flac",
+			sampleRate: 44100,
+			channels: 2,
+			durationMs: 183456,
+			bitRate: 938211,
+		})
+	})
+
+	test("surfaces embedded artwork with its dimensions", () => {
+		const info = parseFfprobeAudioJson(
+			payload({
+				streams: [
+					{ codec_type: "audio", codec_name: "mp3" },
+					{
+						codec_type: "video",
+						codec_name: "mjpeg",
+						width: 600,
+						height: 600,
+						disposition: { attached_pic: 1 },
+					},
+				],
+				format: {},
+			}),
+		)
+		expect(info?.coverArt).toEqual({ width: 600, height: 600 })
+	})
+
+	test("a real video stream is not artwork", () => {
+		const info = parseFfprobeAudioJson(
+			payload({
+				streams: [
+					{ codec_type: "audio", codec_name: "aac" },
+					{
+						codec_type: "video",
+						codec_name: "h264",
+						width: 1920,
+						height: 1080,
+						disposition: { attached_pic: 0 },
+					},
+				],
+				format: {},
+			}),
+		)
+		expect(info?.coverArt).toBeUndefined()
+	})
+
+	test("returns undefined without an audio stream", () => {
+		const info = parseFfprobeAudioJson(
+			payload({
+				streams: [{ codec_type: "video", codec_name: "h264" }],
+				format: { duration: "10.0" },
+			}),
+		)
+		expect(info).toBeUndefined()
+	})
+
+	test("omits fields the container does not report", () => {
+		const info = parseFfprobeAudioJson(
+			payload({ streams: [{ codec_type: "audio" }], format: {} }),
+		)
+		expect(info).toEqual({})
+	})
+
+	test("reads tags case-insensitively, container first", () => {
+		const info = parseFfprobeAudioJson(
+			payload({
+				streams: [
+					{
+						codec_type: "audio",
+						tags: { TITLE: "stream title", ALBUM: "stream album" },
+					},
+				],
+				format: { tags: { Title: "format title", ARTIST: "someone" } },
+			}),
+		)
+		expect(info?.tags).toEqual({
+			title: "format title",
+			artist: "someone",
+			album: "stream album",
+		})
+	})
+
+	test("falls back to album_artist and drops empty tag values", () => {
+		const info = parseFfprobeAudioJson(
+			payload({
+				streams: [{ codec_type: "audio" }],
+				format: { tags: { album_artist: "band", title: "" } },
+			}),
+		)
+		expect(info?.tags).toEqual({ artist: "band" })
+	})
+
+	test("rejects a negative duration instead of persisting it", () => {
+		const info = parseFfprobeAudioJson(
+			payload({
+				streams: [{ codec_type: "audio" }],
+				format: { duration: "-1.0" },
+			}),
+		)
+		expect(info?.durationMs).toBeUndefined()
+	})
+})
+
+describe("extToAudioInputFormat", () => {
+	test("maps opus onto the ogg demuxer and m4a onto mp4", () => {
+		expect(extToAudioInputFormat(".opus")).toBe("ogg")
+		expect(extToAudioInputFormat(".M4A")).toBe("mp4")
+		expect(extToAudioInputFormat(".mp4")).toBeUndefined()
+	})
+})

package/src/probe/audio.ts

@@ -0,0 +1,140 @@
+import type { Readable } from "node:stream"
+import { AUDIO_FFMPEG_INPUT_FORMAT } from "@hoardodile/sdk-types/media-exts"
+import type { AudioCoverArt, AudioInfo, AudioTags } from "../types.ts"
+import {
+	type FfprobePayload,
+	type FfprobeStream,
+	ffprobeDurationMs,
+	ffprobeInt,
+	getFfprobePath,
+	parseFfprobePayload,
+	runFfprobeJson,
+} from "./ffprobe.ts"
+
+/**
+ * Audio probing via ffprobe (see `ffprobe.ts` for path resolution and the
+ * process plumbing). One probe answers everything the host needs about an
+ * audio file: playable duration, stream parameters, whether the container
+ * carries embedded artwork, and the human-facing tags.
+ */
+
+/** Resolve an extension to its ffmpeg `-f` container name for piped input. */
+export function extToAudioInputFormat(ext: string): string | undefined {
+	return AUDIO_FFMPEG_INPUT_FORMAT[ext.toLowerCase()]
+}
+
+/**
+ * Pure parser; broken out so callers and tests can hit it without
+ * spawning ffprobe. Returns `undefined` when the payload carries no
+ * audio stream at all — a video file probed as audio must not produce a
+ * half-filled result.
+ */
+export function parseFfprobeAudioJson(json: string): AudioInfo | undefined {
+	return audioInfoFromPayload(parseFfprobePayload(json))
+}
+
+export function audioInfoFromPayload(
+	payload: FfprobePayload,
+): AudioInfo | undefined {
+	const streams = payload.streams ?? []
+	const audioStream = streams.find((s) => s.codec_type === "audio")
+	if (audioStream === undefined) return undefined
+
+	const result: {
+		durationMs?: number
+		codec?: string
+		bitRate?: number
+		sampleRate?: number
+		channels?: number
+		coverArt?: AudioCoverArt
+		tags?: AudioTags
+	} = {}
+
+	const durationMs = ffprobeDurationMs(payload.format)
+	if (durationMs !== undefined) result.durationMs = durationMs
+	if (
+		typeof audioStream.codec_name === "string" &&
+		audioStream.codec_name.length > 0
+	) {
+		result.codec = audioStream.codec_name
+	}
+	const bitRate = ffprobeInt(payload.format?.bit_rate)
+	if (bitRate !== undefined) result.bitRate = bitRate
+	const sampleRate = ffprobeInt(audioStream.sample_rate)
+	if (sampleRate !== undefined) result.sampleRate = sampleRate
+	const channels = ffprobeInt(audioStream.channels)
+	if (channels !== undefined) result.channels = channels
+	const picture = streams.find(isAttachedPicture)
+	if (picture !== undefined) {
+		result.coverArt = {
+			width: ffprobeInt(picture.width),
+			height: ffprobeInt(picture.height),
+		}
+	}
+	const tags = readAudioTags(payload)
+	if (tags !== undefined) result.tags = tags
+
+	return result
+}
+
+/**
+ * True for the still image ffmpeg exposes as a video stream: ID3 APIC
+ * frames, FLAC PICTURE blocks and MP4 `covr` atoms all surface this way.
+ */
+function isAttachedPicture(stream: FfprobeStream): boolean {
+	if (stream.codec_type !== "video") return false
+	const disposition = stream.disposition
+	if (typeof disposition !== "object" || disposition === null) return false
+	return (disposition as Record<string, unknown>).attached_pic === 1
+}
+
+/**
+ * Read the well-known tags off the container, falling back to the audio
+ * stream's own tag table (Vorbis comments in Matroska/Ogg land there).
+ * Tag keys vary in case between muxers, so lookups are case-insensitive.
+ */
+function readAudioTags(payload: FfprobePayload): AudioTags | undefined {
+	const tables = [
+		payload.format?.tags,
+		payload.streams?.find((s) => s.codec_type === "audio")?.tags,
+	]
+	const lookup = new Map<string, string>()
+	for (const table of tables) {
+		if (typeof table !== "object" || table === null) continue
+		for (const [key, value] of Object.entries(table)) {
+			if (typeof value !== "string" || value.length === 0) continue
+			const normalized = key.toLowerCase()
+			if (!lookup.has(normalized)) lookup.set(normalized, value)
+		}
+	}
+	const tags: { title?: string; artist?: string; album?: string } = {}
+	const title = lookup.get("title")
+	if (title !== undefined) tags.title = title
+	const artist = lookup.get("artist") ?? lookup.get("album_artist")
+	if (artist !== undefined) tags.artist = artist
+	const album = lookup.get("album")
+	if (album !== undefined) tags.album = album
+	return Object.keys(tags).length === 0 ? undefined : tags
+}
+
+/**
+ * Probe an audio stream or path with ffprobe. Probe failures — a missing
+ * binary, an unreadable container, or a source with no audio stream —
+ * return `undefined` so callers can treat "not yet probed" and "probe
+ * failed" the same way.
+ */
+export async function probeAudio(
+	source: string | Readable,
+	extHint?: string,
+): Promise<AudioInfo | undefined> {
+	try {
+		const inputFormat =
+			typeof source === "string" || extHint === undefined
+				? undefined
+				: extToAudioInputFormat(extHint)
+		const payload = await runFfprobeJson(source, getFfprobePath(), inputFormat)
+		return audioInfoFromPayload(payload)
+	} catch {
+		return undefined
+	}
+}

package/src/probe/av.ts

@@ -0,0 +1,84 @@
+import type { Readable } from "node:stream"
+import type { ProbeResult } from "@hoardodile/sdk-types"
+
+import { audioInfoFromPayload } from "./audio.ts"
+import {
+	type FfprobePayload,
+	type FfprobeStream,
+	getFfprobePath,
+	runFfprobeJson,
+} from "./ffprobe.ts"
+import { videoMetaFromPayload } from "./video.ts"
+
+/**
+ * The unified audio/video probe behind `ResourceAPI.probe`: one ffprobe
+ * pass answers both "which family is this" and "what are its
+ * parameters", the way ffprobe itself reports media (`format` plus a
+ * `streams` array) instead of asking the caller to guess the family
+ * first.
+ *
+ * Container formats that carry either kind (Ogg, Matroska, ISO-BMFF)
+ * are settled here: the stream layout decides, not the extension and
+ * not the container MIME.
+ */
+
+export type AvProbeOptions = {
+	/** MIME type from content sniffing; carried into the result. */
+	readonly mime: string
+	/**
+	 * ffmpeg `-f` container name. Required for stream sources (a pipe
+	 * has no filename for ffprobe to key off); ignored for paths.
+	 */
+	readonly inputFormat?: string
+}
+
+/**
+ * True for the still image ffmpeg exposes as a video stream: ID3 APIC
+ * frames, FLAC PICTURE blocks and MP4 `covr` atoms all surface this
+ * way, and none of them make the file a video.
+ */
+function isAttachedPicture(stream: FfprobeStream): boolean {
+	const disposition = stream.disposition
+	if (typeof disposition !== "object" || disposition === null) return false
+	return (disposition as Record<string, unknown>).attached_pic === 1
+}
+
+/**
+ * Classify an ffprobe payload into a {@link ProbeResult}. A real video
+ * stream wins; otherwise an audio stream decides; a payload with
+ * neither is a decode failure.
+ */
+export function avResultFromPayload(
+	payload: FfprobePayload,
+	mime: string,
+): ProbeResult {
+	const streams = payload.streams ?? []
+	const hasVideo = streams.some(
+		(stream) => stream.codec_type === "video" && !isAttachedPicture(stream),
+	)
+	if (hasVideo) {
+		return { kind: "video", mime, ...videoMetaFromPayload(payload) }
+	}
+	const audio = audioInfoFromPayload(payload)
+	if (audio !== undefined) return { kind: "audio", mime, ...audio }
+	return { kind: "unknown", reason: "failed" }
+}
+
+/**
+ * Probe an audio/video source with ffprobe. Never rejects: a missing
+ * binary, an unreadable container or a source ffprobe cannot demux all
+ * resolve to `{ kind: "unknown", reason: "failed" }`.
+ */
+export async function probeAvMedia(
+	source: string | Readable,
+	opts: AvProbeOptions,
+): Promise<ProbeResult> {
+	try {
+		const inputFormat =
+			typeof source === "string" ? undefined : opts.inputFormat
+		const payload = await runFfprobeJson(source, getFfprobePath(), inputFormat)
+		return avResultFromPayload(payload, opts.mime)
+	} catch {
+		return { kind: "unknown", reason: "failed" }
+	}
+}