@hoardodile/host 0.0.0

package/src/archive/7z.test.ts

@@ -0,0 +1,222 @@
+import { execFileSync } from "node:child_process"
+import {
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { describe, expect, it } from "vitest"
+import {
+	extractSevenZipInto,
+	listSevenZipEntries,
+	resolveSevenZipPath,
+} from "./7z.ts"
+import {
+	createArchiveExtractor,
+	type ExtractArchiveDeps,
+} from "./extract-archive.ts"
+import type { OuterEntrySource } from "./nested-entry.ts"
+
+const bin = resolveSevenZipPath()
+const sevenZipAvailable = bin !== undefined
+
+function makeSevenZip(
+	dir: string,
+	files: Record<string, string>,
+	opts: string[] = [],
+) {
+	const payload = join(dir, "payload")
+	mkdirSync(payload, { recursive: true })
+	for (const [name, content] of Object.entries(files)) {
+		const filePath = join(payload, name)
+		mkdirSync(dirname(filePath), { recursive: true })
+		writeFileSync(filePath, content)
+	}
+	const archivePath = join(dir, "fixture.7z")
+	execFileSync(bin!, ["a", "-t7z", ...opts, archivePath, "."], {
+		cwd: payload,
+		stdio: "ignore",
+	})
+	return archivePath
+}
+
+function entrySource(archivePath: string): OuterEntrySource {
+	const bytes = readFileSync(archivePath)
+	return {
+		sizeOf: async () => bytes.length,
+		readSlice: async (_rel, start, end) => bytes.subarray(start, end),
+	}
+}
+
+function makeExtractor(
+	archivePath: string,
+	overrides: Partial<ExtractArchiveDeps> = {},
+) {
+	const root = mkdtempSync(join(tmpdir(), "7z-extract-"))
+	return {
+		root,
+		extractor: createArchiveExtractor({
+			outer: entrySource(archivePath),
+			cacheDir: join(root, "cache"),
+			maxBytes: 10 * 1024 * 1024,
+			maxEntries: 100,
+			...overrides,
+		}),
+		cleanup: () => rmSync(root, { recursive: true, force: true }),
+	}
+}
+
+describe.skipIf(!sevenZipAvailable)("7z binary capabilities", () => {
+	it("supports RAR5 extraction", () => {
+		// The shipped binary must include the full codecs (7za.exe does
+		// not — the package now ships 7z.exe+7z.dll on Windows and 7zz
+		// on POSIX, both with RAR support).
+		const info = execFileSync(bin!, ["i"], { encoding: "utf8" })
+		expect(info).toMatch(/\bRar5\b/)
+	})
+})
+
+describe.skipIf(!sevenZipAvailable)("7z listing", () => {
+	it("parses entries from a real .7z archive", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "7z-list-"))
+		try {
+			const archivePath = makeSevenZip(dir, {
+				"a/b.txt": "hello",
+				"c.bin": "x".repeat(4096),
+			})
+			const entries = await listSevenZipEntries(archivePath)
+			const files = entries.filter((e) => !e.folder)
+			expect(files.map((e) => e.name).sort()).toEqual(["a/b.txt", "c.bin"])
+			expect(files.find((e) => e.name === "c.bin")?.sizeBytes).toBe(4096)
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+})
+
+describe.skipIf(!sevenZipAvailable)("7z rar fixture", () => {
+	const FIXTURE = join(
+		import.meta.dirname,
+		"../../testdata/rar5-multiple-files.rar",
+	)
+
+	it("lists the vendored rar5 sample", async () => {
+		const entries = await listSevenZipEntries(FIXTURE)
+		const files = entries.filter((e) => !e.folder)
+		expect(files.map((e) => e.name).sort()).toEqual([
+			"test1.bin",
+			"test2.bin",
+			"test3.bin",
+			"test4.bin",
+		])
+		for (const entry of files) expect(entry.sizeBytes).toBe(4096)
+	})
+
+	it("extracts the vendored rar5 sample", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "7z-rar-x-"))
+		try {
+			await extractSevenZipInto(FIXTURE, join(dir, "out"))
+			expect(readFileSync(join(dir, "out", "test1.bin")).length).toBe(4096)
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+})
+
+describe.skipIf(!sevenZipAvailable)("7z extraction", () => {
+	it("extracts an archive into a directory", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "7z-x-"))
+		try {
+			const archivePath = makeSevenZip(dir, { "a/b.txt": "hello" })
+			const out = join(dir, "out")
+			await extractSevenZipInto(archivePath, out)
+			expect(readFileSync(join(out, "a", "b.txt"), "utf8")).toBe("hello")
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+})
+
+describe.skipIf(!sevenZipAvailable)("extractArchive 7z dispatch", () => {
+	it("materializes a .7z container with an idempotent manifest", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "7z-api-"))
+		try {
+			const archivePath = makeSevenZip(dir, { "img.txt": "payload" })
+			const { extractor, root, cleanup } = makeExtractor(archivePath)
+			try {
+				const first = await extractor.extract("fixture.7z")
+				expect(first.entries.map((e) => e.path)).toEqual(["img.txt"])
+				expect(
+					readFileSync(join(root, "cache", "fixture.7z", "img.txt"), "utf8"),
+				).toBe("payload")
+				// second run reuses the manifest without re-extracting
+				const second = await extractor.extract("fixture.7z")
+				expect(second.entries).toEqual(first.entries)
+			} finally {
+				cleanup()
+			}
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+
+	it("rejects archives over the byte budget", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "7z-budget-"))
+		try {
+			const archivePath = makeSevenZip(dir, { "big.bin": "y".repeat(2048) })
+			const { extractor, cleanup } = makeExtractor(archivePath, {
+				maxBytes: 1024,
+			})
+			try {
+				await expect(extractor.extract("fixture.7z")).rejects.toThrow(
+					/exceeding the limit/,
+				)
+			} finally {
+				cleanup()
+			}
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+
+	it("rejects password-protected archives", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "7z-enc-"))
+		try {
+			const archivePath = makeSevenZip(dir, { "secret.txt": "top" }, [
+				"-psecret",
+			])
+			const { extractor, cleanup } = makeExtractor(archivePath)
+			try {
+				await expect(extractor.extract("fixture.7z")).rejects.toThrow(
+					/password-protected/,
+				)
+			} finally {
+				cleanup()
+			}
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+
+	it("lists 7z archives but does not address them as nested containers", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "7z-nested-"))
+		try {
+			const archivePath = makeSevenZip(dir, { "inner.txt": "x" })
+			const { extractor, cleanup } = makeExtractor(archivePath)
+			try {
+				// The extractor's list answers for any 7-Zip-able format
+				// (metadata-only); only the *resolver* (virtual
+				// `outer!inner` addressing) stays zip-only.
+				const listing = await extractor.list("fixture.7z")
+				expect(listing?.map((e) => e.name)).toEqual(["inner.txt"])
+			} finally {
+				cleanup()
+			}
+		} finally {
+			rmSync(dir, { recursive: true, force: true })
+		}
+	})
+})

package/src/archive/7z.ts

@@ -0,0 +1,261 @@
+import { spawn } from "node:child_process"
+import { createRequire } from "node:module"
+import { invalid } from "../errors.ts"
+import { SNIFF_WINDOW_BYTES, sniffContainerFormat } from "./format.ts"
+import { decodeLegacyZipName } from "./name-decode.ts"
+import { readFileRange } from "./zip-entries.ts"
+
+/**
+ * 7-Zip process wrapper for the extra archive formats (.7z/.rar/.xz) and
+ * — since the whole-archive extraction switch — zip/tar/gzip as well.
+ * The binary comes from the optional `@hoardodile/7z-bin` package
+ * (downloaded at install time); when it is absent every function here
+ * rejects with a clear "unavailable" error and callers degrade to
+ * zip-only support via yauzl.
+ *
+ * Only whole-archive operations run through 7-Zip: listing with
+ * `l -slt -ba` (fixed English fields, locale-independent) and full
+ * extraction with `x -y`. Random-access entry streaming stays on the
+ * native zip path, which 7-Zip cannot express.
+ *
+ * Legacy zip names (no UTF-8 flag) are not re-encoded by 7-Zip on every
+ * platform — its POSIX builds pass the raw bytes through — so the host
+ * decodes them as cp437 itself: the listing's `Path` values are decoded
+ * byte-wise for zip archives (see {@link decodeLegacyZipName}), and the
+ * extraction sites rename the on-disk files to match (see
+ * `normalizeExtractedTree` in extract.ts). Listing output is still
+ * forced to UTF-8 (`-sccUTF-8`) so 7-Zip's Windows build emits decoded
+ * names as valid UTF-8 rather than console-codepage bytes.
+ */
+
+const requireCjs = createRequire(import.meta.url)
+
+export const SEVEN_ZIP_PATH_ENV = "7Z_BIN_PATH"
+
+export type SevenZipEntry = {
+	readonly name: string
+	readonly sizeBytes: number
+	readonly folder: boolean
+	readonly encrypted: boolean
+}
+
+/**
+ * Resolve the absolute path of the 7-Zip binary, or `undefined` when the
+ * optional package is not installed (install failed / skipped platform).
+ */
+export function resolveSevenZipPath(): string | undefined {
+	const fromEnv = process.env[SEVEN_ZIP_PATH_ENV]
+	if (fromEnv !== undefined && fromEnv.length > 0) return fromEnv
+	try {
+		const mod: unknown = requireCjs("@hoardodile/7z-bin")
+		if (typeof mod === "string" && mod.length > 0) return mod
+		return undefined
+	} catch {
+		return undefined
+	}
+}
+
+function sevenZipUnavailable(): Error {
+	return invalid(
+		"resource.archive_open_failed",
+		"7-Zip is not installed — install @hoardodile/7z-bin or set 7Z_BIN_PATH to enable archive extraction",
+		{},
+	)
+}
+
+/**
+ * Run 7-Zip with `args`; rejects with a domain error on non-zero exit,
+ * timeout, or spawn failure (missing binary, wrong-arch executable).
+ * stdout is streamed and collected in memory (no maxBuffer ceiling —
+ * `l -slt` on very large archives can exceed a fixed cap); `stderr` is
+ * included in the message so operators can see the native error instead
+ * of a bare exit code.
+ */
+function run7z(
+	bin: string,
+	args: readonly string[],
+	timeoutMs: number,
+): Promise<{ readonly stdout: Buffer }> {
+	return new Promise((resolveDone, rejectDone) => {
+		const child = spawn(bin, [...args], {
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+		})
+		const stdout: Buffer[] = []
+		const stderr: Buffer[] = []
+		let settled = false
+
+		child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk))
+		child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk))
+
+		const fail = (err: Error): void => {
+			if (settled) return
+			settled = true
+			rejectDone(err)
+		}
+		const timer = setTimeout(() => {
+			child.kill()
+			fail(
+				invalid(
+					"resource.archive_open_failed",
+					`7-Zip timed out after ${timeoutMs}ms`,
+					{ timeoutMs },
+				),
+			)
+		}, timeoutMs)
+		timer.unref()
+
+		child.on("error", (err) => {
+			fail(
+				invalid(
+					"resource.archive_open_failed",
+					`could not start 7-Zip: ${err.message}`,
+					{},
+				),
+			)
+		})
+		child.on("close", (code, signal) => {
+			clearTimeout(timer)
+			if (settled) return
+			if (code === 0) {
+				settled = true
+				resolveDone({ stdout: Buffer.concat(stdout) })
+				return
+			}
+			const detail =
+				signal !== null ? `killed by ${signal}` : `exit ${code ?? "?"}`
+			const tail = Buffer.concat(stderr)
+				.toString("utf8")
+				.trim()
+				.split("\n")
+				.at(-1)
+			fail(
+				invalid(
+					"resource.archive_open_failed",
+					`7-Zip ${detail}${tail !== undefined && tail.length > 0 ? `: ${tail}` : ""}`,
+					{ code },
+				),
+			)
+		})
+	})
+}
+
+/** True when `encrypted` field from `-slt` marks an encrypted entry. */
+function isEncryptedField(value: string): boolean {
+	return value === "+"
+}
+
+/** Parse `l -slt -ba` output into per-entry records (blank-line separated). */
+function parseSltListing(
+	stdout: Buffer,
+	legacyNames: boolean,
+): SevenZipEntry[] {
+	const entries: SevenZipEntry[] = []
+	let name: string | undefined
+	let sizeBytes = 0
+	let folder = false
+	let encrypted = false
+	// latin1 round-trips every output byte losslessly, so the raw `Path`
+	// value survives for the cp437 decode below (the UTF-8 pass-through
+	// would replace invalid bytes with U+FFFD first).
+	for (const line of stdout.toString("latin1").split(/\r?\n/)) {
+		if (line.length === 0) {
+			if (name !== undefined) {
+				entries.push({ name, sizeBytes, folder, encrypted })
+				name = undefined
+			}
+			continue
+		}
+		const sep = line.indexOf(" = ")
+		if (sep < 0) continue
+		const key = line.slice(0, sep)
+		if (key === "Path") {
+			// 7za prints backslash separators on Windows; normalize to
+			// the forward-slash convention used across the archive runtime.
+			const raw = Buffer.from(line.slice(sep + 3), "latin1")
+			const decoded = legacyNames
+				? decodeLegacyZipName(raw)
+				: raw.toString("utf8")
+			name = decoded.replace(/\\/g, "/")
+			continue
+		}
+		const value = line.slice(sep + 3)
+		switch (key) {
+			case "Size":
+				sizeBytes = Number.parseInt(value, 10) || 0
+				break
+			case "Attributes":
+				// Directories carry `D` (there is no Folder field in -slt).
+				folder = value.includes("D")
+				break
+			case "Encrypted":
+				encrypted = isEncryptedField(value)
+				break
+		}
+	}
+	if (name !== undefined) {
+		entries.push({ name, sizeBytes, folder, encrypted })
+	}
+	return entries
+}
+
+/**
+ * Per-call options for the 7-Zip wrappers.
+ */
+export type SevenZipRunOptions = {
+	readonly timeoutMs?: number
+}
+
+/**
+ * True when `archivePath`'s magic bytes say zip. Read once per call (a
+ * 4KB window) to decide whether names decode as legacy cp437 (see
+ * {@link decodeLegacyZipName}) — callers never need to know the format.
+ * An unreadable header degrades to "not zip" (no cp437 fallback), which
+ * is the safe direction for every other format.
+ */
+async function isZipArchive(archivePath: string): Promise<boolean> {
+	const head = await readFileRange(
+		archivePath,
+		0,
+		SNIFF_WINDOW_BYTES - 1,
+	).catch(() => undefined)
+	if (head === undefined || head.length === 0) return false
+	return sniffContainerFormat(head) === "zip"
+}
+
+/**
+ * List the entries of `archivePath` (zip/tar/7z/rar/xz/gzip). Rejects
+ * when the archive is encrypted (7-Zip would prompt for a password on a
+ * TTY). Listing output is forced to UTF-8 (`-sccUTF-8`); legacy zip
+ * names decode as cp437 byte-wise (see {@link decodeLegacyZipName}).
+ */
+export async function listSevenZipEntries(
+	archivePath: string,
+	opts: SevenZipRunOptions = {},
+): Promise<SevenZipEntry[]> {
+	const bin = resolveSevenZipPath()
+	if (bin === undefined) throw sevenZipUnavailable()
+	const args = ["l", "-slt", "-ba", "-sccUTF-8"]
+	const legacyNames = await isZipArchive(archivePath)
+	args.push(archivePath)
+	const { stdout } = await run7z(bin, args, opts.timeoutMs ?? 120_000)
+	return parseSltListing(stdout, legacyNames)
+}
+
+/**
+ * Extract `archivePath` in full into `destDir`. Callers must pre-validate
+ * budgets from {@link listSevenZipEntries} — 7-Zip has no byte-level
+ * progress or per-entry abort, so the listing is the enforcement point.
+ * Legacy zip names land on disk as 7-Zip wrote them (raw bytes on POSIX);
+ * callers fix them up afterwards via `normalizeExtractedTree` (extract.ts).
+ */
+export async function extractSevenZipInto(
+	archivePath: string,
+	destDir: string,
+	opts: SevenZipRunOptions = {},
+): Promise<void> {
+	const bin = resolveSevenZipPath()
+	if (bin === undefined) throw sevenZipUnavailable()
+	const args = ["x", archivePath, `-o${destDir}`, "-y", "-bd"]
+	await run7z(bin, args, opts.timeoutMs ?? 10 * 60_000)
+}