@hoardodile/host 0.0.0

package/src/hoard/version.ts

@@ -0,0 +1,216 @@
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs"
+import { join, resolve } from "node:path"
+import { conflict, notFound } from "../errors.ts"
+
+/**
+ * Persisted version-state file (under `<root>/local/`, not `versions/`,
+ * because `versions/` is reserved for version folders only).
+ */
+const STATE_FILENAME = "version-state.json"
+
+/**
+ * On-disk shape of the version state.
+ *
+ * - `active` — the version the user is currently viewing. When `active`
+ *   equals the current (max) version the server runs in normal R/W mode;
+ *   when `active < current` the server runs READ-ONLY against a cloned
+ *   snapshot of the active version's DB.
+ */
+type VersionState = {
+	readonly active: number
+}
+
+/** Root layout helper: the versions root directory `<root>/versions`. */
+function versionsRoot(root: string): string {
+	return resolve(root, "versions")
+}
+
+/** State file lives under `<root>/local/version-state.json`. */
+function stateFile(root: string): string {
+	return resolve(root, "local", STATE_FILENAME)
+}
+
+/**
+ * Enumerate version directories under `<root>/versions/`. Names that are
+ * not pure positive integers are ignored. Result is sorted ascending.
+ */
+export function listVersions(root: string): readonly number[] {
+	const dir = versionsRoot(root)
+	if (!existsSync(dir)) return []
+	const names = readdirSync(dir, { withFileTypes: true })
+		.filter((e) => e.isDirectory())
+		.map((e) => e.name)
+	const nums: number[] = []
+	for (const n of names) {
+		if (!/^[1-9][0-9]*$/.test(n)) continue
+		nums.push(Number.parseInt(n, 10))
+	}
+	nums.sort((a, b) => a - b)
+	return nums
+}
+
+/**
+ * Current (maximum) version on disk. Returns `0` when no version exists
+ * yet (caller is expected to bootstrap version 1 in that case).
+ */
+export function currentVersion(root: string): number {
+	const all = listVersions(root)
+	return all.length === 0 ? 0 : (all[all.length - 1] ?? 0)
+}
+
+/**
+ * Read the persisted active version. Falls back to current when the
+ * state file is missing or malformed, or when the recorded value points
+ * at a version that no longer exists.
+ */
+export function readActiveVersion(root: string): number {
+	const cur = currentVersion(root)
+	const file = stateFile(root)
+	if (!existsSync(file)) return cur
+	try {
+		const parsed = JSON.parse(
+			readFileSync(file, "utf8"),
+		) as Partial<VersionState>
+		const active = typeof parsed.active === "number" ? parsed.active : cur
+		const all = listVersions(root)
+		if (all.includes(active)) return active
+		return cur
+	} catch {
+		return cur
+	}
+}
+
+/**
+ * Persist the active version. Caller must ensure `version` exists on
+ * disk (use {@link listVersions}).
+ *
+ * @throws DomainError `version.not_found` when `version` is not a known
+ *   version directory.
+ */
+export function writeActiveVersion(root: string, version: number): void {
+	const all = listVersions(root)
+	if (!all.includes(version)) {
+		throw notFound("version.not_found", `version ${version} does not exist`, {
+			version,
+		})
+	}
+	const file = stateFile(root)
+	mkdirSync(resolve(root, "local"), { recursive: true })
+	const payload: VersionState = { active: version }
+	writeFileSync(file, JSON.stringify(payload), "utf8")
+}
+
+/**
+ * Bootstrap version 1 if the versions root has no version directories yet.
+ * Idempotent; a no-op when any version already exists.
+ */
+export function ensureBootstrapVersion(root: string): number {
+	const cur = currentVersion(root)
+	if (cur > 0) return cur
+	const v1 = resolve(versionsRoot(root), "1")
+	mkdirSync(v1, { recursive: true })
+	return 1
+}
+
+export type CreateNextVersionResult = {
+	readonly previous: number
+	readonly created: number
+}
+
+/**
+ * Snapshot the current version into a freshly-numbered next version.
+ *
+ * Process:
+ * 1. Compute `next = currentVersion + 1`.
+ * 2. Refuse to proceed when `versions/<prev>/app.sqlite` already exists.
+ * 3. Create `<root>/versions/<next>/` and copy installed plugins from
+ *    `versions/<prev>/plugins` (resource binaries stay at their
+ *    `fileVersion`; plugins have no equivalent pointer).
+ * 4. Vacuum-snapshot the live DB into `<root>/versions/<prev>/app.sqlite`.
+ *    (Caller passes a `vacuumInto` function; we don't take a DB handle
+ *    here to keep this module database-agnostic.)
+ * 5. On any failure after step 3, remove `versions/<next>` so
+ *    {@link currentVersion} does not jump to an empty directory.
+ *
+ * @throws DomainError `version.bootstrap_required` when no version exists
+ *   yet (caller must bootstrap first).
+ * @throws DomainError `version.already_exists` when the previous
+ *   version's DB snapshot already exists.
+ */
+export function createNextVersion(
+	root: string,
+	vacuumInto: (destination: string) => void,
+): CreateNextVersionResult {
+	const prev = currentVersion(root)
+	if (prev === 0) {
+		throw conflict(
+			"version.bootstrap_required",
+			"no current version to snapshot from",
+		)
+	}
+	const next = prev + 1
+	const prevDir = resolve(versionsRoot(root), String(prev))
+	const nextDir = resolve(versionsRoot(root), String(next))
+	// Archive the current live DB under the PREVIOUS version directory so
+	// that `versions/<prev>/app.sqlite` becomes the immutable snapshot.
+	// The live database stays at `<root>/app.sqlite`; only this archived
+	// copy lands in `versions/`.
+	const dest = resolve(prevDir, "app.sqlite")
+	if (existsSync(dest)) {
+		throw conflict(
+			"version.already_exists",
+			`app.sqlite already exists for version ${next}`,
+			{ version: next },
+		)
+	}
+	mkdirSync(nextDir, { recursive: true })
+	try {
+		copyVersionPlugins(prevDir, nextDir)
+		vacuumInto(dest)
+	} catch (err) {
+		rmSync(nextDir, { recursive: true, force: true })
+		throw err
+	}
+	return { previous: prev, created: next }
+}
+
+/**
+ * Copy installed plugin directories from one version folder into the
+ * next. Only subdirectories that look like plugins (contain
+ * `manifest.json`) are copied; dot-directories such as leftover
+ * staging folders are skipped.
+ */
+function copyVersionPlugins(prevDir: string, nextDir: string): void {
+	const src = join(prevDir, "plugins")
+	if (!existsSync(src)) return
+	const entries = readdirSync(src, { withFileTypes: true })
+	for (const entry of entries) {
+		if (!entry.isDirectory()) continue
+		if (entry.name.startsWith(".")) continue
+		const from = join(src, entry.name)
+		if (!existsSync(join(from, "manifest.json"))) continue
+		cpSync(from, join(nextDir, "plugins", entry.name), { recursive: true })
+	}
+}
+
+/**
+ * Path to the DB file for version `v`: `<root>/versions/<v>/app.sqlite`.
+ */
+export function versionedDbFile(root: string, v: number): string {
+	return resolve(versionsRoot(root), String(v), "app.sqlite")
+}
+
+/**
+ * Path to the per-version archive directory `<root>/versions/<v>`.
+ */
+export function versionedPath(root: string, v: number): string {
+	return resolve(versionsRoot(root), String(v))
+}

package/src/hoard/versioned-folder-ops.ts

@@ -0,0 +1,152 @@
+import { mkdir, readdir, rename, rm, writeFile } from "node:fs/promises"
+import { extname, join } from "node:path"
+import type { StoragePaths } from "./paths.ts"
+import { writeVersioned } from "./write-versioned.ts"
+
+export type VersionedFolderOps = {
+	/** Ensure the current-version entity folder exists. */
+	ensureFolder(id: string): Promise<void>
+	/** Remove the current-version entity folder. Swallows missing-path errors. */
+	removeFolder(id: string): Promise<void>
+	/**
+	 * When an entity's files live only under frozen past archives, hard
+	 * delete cannot remove those folders; drop a `.deleted` placeholder in
+	 * the current-version folder instead.
+	 */
+	markDeleted(id: string): Promise<string>
+	/**
+	 * Move the current-version entity folder into `local/trash/` with a
+	 * unique directory name. No-op when the source path is missing (same as
+	 * a removed folder). Returns the destination path (whether or not a move
+	 * occurred).
+	 */
+	moveFolderToTrash(id: string): Promise<string>
+}
+
+/**
+ * The four lifecycle operations shared by the resource and character
+ * file-system layers. They differ only in which versioned folder they
+ * target and how the trash / placeholder names are derived.
+ *
+ * `moveFolderToTrash` treats `EPERM`/`EBUSY`/`UNKNOWN` as transient Windows
+ * locks (a file inside the folder is still open) and leaves the source in
+ * place; a boot-time orphan sweep reclaims it later.
+ *
+ * `readOnly` is a live `{ current: boolean }` ref (the server's runtime
+ * read-only flag), so a version switch mid-request re-reads it.
+ */
+export function buildVersionedFolderOps(
+	paths: StoragePaths,
+	readOnly: { readonly current: boolean },
+	kind: "resource" | "character",
+): VersionedFolderOps {
+	const folderOf =
+		(id: string) =>
+		(current: StoragePaths["latest"]): string =>
+			kind === "resource" ? current.resource(id) : current.character(id)
+	const trashPrefix = kind === "resource" ? "resources-" : "characters-"
+	const deletedKind = kind === "resource" ? "resources" : "characters"
+
+	async function ensureFolder(id: string): Promise<void> {
+		await writeVersioned(paths, readOnly.current, (current) =>
+			mkdir(folderOf(id)(current), { recursive: true }),
+		)
+	}
+
+	async function removeFolder(id: string): Promise<void> {
+		await writeVersioned(paths, readOnly.current, (current) =>
+			rm(folderOf(id)(current), {
+				recursive: true,
+				force: true,
+			}).catch(() => {}),
+		)
+	}
+
+	async function markDeleted(id: string): Promise<string> {
+		return writeVersioned(paths, readOnly.current, async (current) => {
+			const folder = folderOf(id)(current)
+			await mkdir(folder, { recursive: true })
+			const marker = current.deletedMarker(deletedKind, id)
+			// Empty file: the placeholder's existence is the whole signal.
+			await writeFile(marker, "")
+			return marker
+		})
+	}
+
+	async function moveFolderToTrash(id: string): Promise<string> {
+		// write-local-only: trash directory is under local/, not versions/.
+		await mkdir(paths.local.trash(), { recursive: true })
+		return writeVersioned(paths, readOnly.current, async (current) => {
+			const src = folderOf(id)(current)
+			const dest = join(
+				paths.local.trash(),
+				`${trashPrefix}${id}-${Date.now()}`,
+			)
+			try {
+				await rename(src, dest)
+			} catch (err) {
+				const code = (err as NodeJS.ErrnoException).code
+				if (code === "ENOENT") {
+					// Already gone; return dest as a conventional indicator.
+					return dest
+				}
+				// Windows may throw EPERM/EBUSY/UNKNOWN when a file inside src is
+				// still open (thumb pipeline, HTTP stream, zip handle, ...). Don't
+				// let a transient lock block the hard-delete; an orphan sweep at
+				// boot will reclaim the leftover folder later.
+				if (code === "EPERM" || code === "EBUSY" || code === "UNKNOWN") {
+					return src
+				}
+				throw err
+			}
+			return dest
+		})
+	}
+
+	return {
+		ensureFolder,
+		removeFolder,
+		markDeleted,
+		moveFolderToTrash,
+	}
+}
+
+/**
+ * Move every file in `sourceFolder` whose name matches `match` into
+ * `destFolder` under a timestamped archive name (`<prefix><stamp><ext>`, or
+ * `<prefix><stamp>_<i><ext>` when several files match). Moves to the local
+ * (non-synced) directory so replaced files are preserved without polluting
+ * the versions sync scope. Creates `destFolder` on demand; silently ignores
+ * ENOENT on source files and a missing source folder.
+ */
+export async function archiveStaleFiles(args: {
+	readonly sourceFolder: string
+	readonly destFolder: string
+	readonly match: (name: string) => boolean
+	readonly archivePrefix: string
+}): Promise<void> {
+	const { sourceFolder, destFolder, match, archivePrefix } = args
+	const entries = await readdir(sourceFolder).catch(() => [])
+	const stale = entries.filter(match)
+	if (stale.length === 0) return
+	await mkdir(destFolder, { recursive: true })
+	const stamp = Date.now()
+	await Promise.all(
+		stale.map(async (name, i) => {
+			const ext = extname(name)
+			const archiveName =
+				stale.length === 1
+					? `${archivePrefix}${stamp}${ext}`
+					: `${archivePrefix}${stamp}_${i}${ext}`
+			try {
+				await rename(join(sourceFolder, name), join(destFolder, archiveName))
+			} catch (err) {
+				if (!isEnoentError(err)) throw err
+			}
+		}),
+	)
+}
+
+function isEnoentError(err: unknown): boolean {
+	return err instanceof Error && "code" in err && err.code === "ENOENT"
+}

package/src/hoard/write-versioned.test.ts

@@ -0,0 +1,67 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { describe, expect, test } from "vitest"
+import { createStoragePaths } from "./paths.ts"
+import { writeVersioned } from "./write-versioned.ts"
+
+describe("writeVersioned", () => {
+	test("throws DomainError when readOnly is true", async () => {
+		const root = await mkdtemp(join(tmpdir(), "write-versioned-ro-"))
+		try {
+			const paths = createStoragePaths({ root })
+			await expect(
+				writeVersioned(paths, true, async () => "should not run"),
+			).rejects.toMatchObject({
+				code: "CONFLICT",
+				kind: "server.read_only_archive",
+				message:
+					"server is viewing a read-only archive; versioned writes are blocked",
+			})
+		} finally {
+			await rm(root, { recursive: true, force: true })
+		}
+	})
+
+	test("executes command on paths.latest when readOnly is false", async () => {
+		const root = await mkdtemp(join(tmpdir(), "write-versioned-ok-"))
+		try {
+			const paths = createStoragePaths({ root })
+			const result = await writeVersioned(paths, false, async (current) => {
+				const dir = current.resource("res-1")
+				await mkdir(dir, { recursive: true })
+				const file = join(dir, "blob")
+				await writeFile(file, "data")
+				return file
+			})
+			expect(result.startsWith(paths.latest.resource("res-1"))).toBe(true)
+		} finally {
+			await rm(root, { recursive: true, force: true })
+		}
+	})
+
+	test("callback always receives the current version even when viewing an older version", async () => {
+		const root = await mkdtemp(join(tmpdir(), "write-versioned-version-"))
+		try {
+			// Prepare two version directories and pin active to v1 while current is v2.
+			await mkdir(join(root, "versions", "1"), { recursive: true })
+			await mkdir(join(root, "versions", "2"), { recursive: true })
+			const paths = createStoragePaths({
+				root,
+				activeVersion: 1,
+				latestVersion: 2,
+			})
+			expect(paths.active.version).toBe(1)
+			expect(paths.latest.version).toBe(2)
+
+			const receivedVersion = await writeVersioned(
+				paths,
+				false,
+				async (current) => current.version,
+			)
+			expect(receivedVersion).toBe(2)
+		} finally {
+			await rm(root, { recursive: true, force: true })
+		}
+	})
+})

package/src/hoard/write-versioned.ts

@@ -0,0 +1,39 @@
+import { conflict } from "../errors.ts"
+import type { StoragePaths } from "./paths.ts"
+
+/**
+ * Command that performs a write under the **current** (latest, writable)
+ * archive version. Receiving `paths.latest` instead of the whole
+ * {@link StoragePaths} object makes it impossible for callers to accidentally
+ * target `paths.active`, which may point at a frozen past version when the
+ * server is in read-only viewing mode.
+ */
+export type VersionedWriteCommand<T> = (
+	paths: StoragePaths["latest"],
+) => T | Promise<T>
+
+/**
+ * Central gate for every file-system write that lands under `versions/<v>`.
+ *
+ * - Blocks the operation when `readOnly` is true, surfacing a domain conflict
+ *   with code `server.read_only_archive`.
+ * - Forces the command to operate on `paths.latest` (the latest archive
+ *   version) so past frozen versions can never be mutated.
+ *
+ * Local-only writes (thumbs, caches, staging pool, trash) should NOT use this
+ * helper; they live under `local/` and are governed by the route-level
+ * write gate instead.
+ */
+export async function writeVersioned<T>(
+	paths: StoragePaths,
+	readOnly: boolean,
+	cmd: VersionedWriteCommand<T>,
+): Promise<T> {
+	if (readOnly) {
+		throw conflict(
+			"server.read_only_archive",
+			"server is viewing a read-only archive; versioned writes are blocked",
+		)
+	}
+	return await cmd(paths.latest)
+}