@milaboratories/pl-middle-layer 1.67.6 → 1.68.0

package/dist/middle_layer/tree_snapshot_store.cjs

@@ -0,0 +1,283 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_build_stamp = require("./build_stamp.cjs");
+let node_path = require("node:path");
+node_path = require_runtime.__toESM(node_path, 1);
+let _milaboratories_ts_helpers = require("@milaboratories/ts-helpers");
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = require_runtime.__toESM(node_fs_promises, 1);
+let _milaboratories_pl_client = require("@milaboratories/pl-client");
+let _milaboratories_pl_tree = require("@milaboratories/pl-tree");
+let node_crypto = require("node:crypto");
+//#region src/middle_layer/tree_snapshot_store.ts
+function initialStat() {
+	return {
+		reads: 0,
+		hits: 0,
+		restores: 0,
+		misses: {
+			absent: 0,
+			unreadable: 0,
+			"session-rotated": 0,
+			"not-a-snapshot": 0,
+			"unknown-schema": 0,
+			truncated: 0,
+			checksum: 0,
+			malformed: 0
+		},
+		writes: 0,
+		writeFailures: 0,
+		bytesWritten: 0,
+		discarded: 0,
+		evicted: 0,
+		evictedForSize: 0,
+		bytesEvicted: 0,
+		millisReading: 0,
+		millisWriting: 0
+	};
+}
+const FILE_PREFIX = "tree.";
+const FILE_SUFFIX = ".plts";
+/** Keeps a filename to characters every filesystem we target accepts. */
+function safe(part) {
+	return part.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+/** Names this class writes: a finished snapshot, or the staging file of a write killed before
+*  its rename. The directory is caller-supplied and only defaults to one of ours, so nothing
+*  failing this is ever deleted, by the purge or by the startup eviction. */
+function isOurFile(name) {
+	if (!name.startsWith(FILE_PREFIX)) return false;
+	return name.endsWith(FILE_SUFFIX) || name.includes(`${FILE_SUFFIX}.tmp.`);
+}
+/**
+* Snapshots of project tree mirrors on the local filesystem.
+*
+* A snapshot is addressed by backend instance, authenticated user, root resource, build stamp
+* and snapshot schema version. Everything except the root goes into the *scope*, which is
+* fixed for the lifetime of a client; the root distinguishes one project from another, so
+* there is one file per project per user per backend, rewritten in place.
+*
+* The session is deliberately not part of the key. It is witnessed inside the file and
+* compared on read: a snapshot from an ended session is a miss, but the file is kept, because
+* its bodies remain valid indefinitely and only its signatures have died. Deleting it would
+* destroy the evidence a future signature refresh would repair.
+*/
+var TreeSnapshotStore = class TreeSnapshotStore {
+	ops;
+	scope;
+	stat = initialStat();
+	constructor(ops, scope) {
+		this.ops = ops;
+		this.scope = scope;
+	}
+	/**
+	* Builds a store for the given client, or returns undefined when nothing should be
+	* persisted for it.
+	*
+	* Returns undefined for an impersonated client: reading and writing under `asUser` would
+	* leave another user's mirror at rest under the admin's identity, usable only if the admin
+	* returned to that exact root. One condition removes both the hygiene question and the
+	* orphan one.
+	*/
+	static create(pl, ops) {
+		if (!ops.enabled) {
+			ops.logger.info("tree snapshots are disabled by configuration");
+			return;
+		}
+		if (pl.conf.asUser !== void 0) {
+			ops.logger.info("tree snapshots are disabled while the client is opened as another user");
+			return;
+		}
+		const identity = (0, node_crypto.createHash)("sha256").update([
+			pl.conf.hostAndPort,
+			pl.serverInfo.instanceId ?? "",
+			pl.authUser ?? ""
+		].join("\0")).digest("hex").slice(0, 16);
+		return new TreeSnapshotStore(ops, `${_milaboratories_pl_tree.PERSISTED_TREE_SCHEMA_VERSION}.${safe(require_build_stamp.ML_BUILD_STAMP)}.${identity}`);
+	}
+	/**
+	* Removes this class's files from the snapshot directory. Run when snapshots are switched
+	* off, so a user who turns the kill switch off because the disk is full or unwritable
+	* actually gets the space back, rather than leaving up to the size ceiling stranded there
+	* indefinitely.
+	*
+	* Deliberately keyed on the setting rather than on "there is no store": a store is also
+	* absent for an impersonated client, and deleting there would destroy the operator's own
+	* snapshots from their ordinary sessions. Never throws.
+	*/
+	static async purge(dir, logger) {
+		try {
+			for (const name of await node_fs_promises.default.readdir(dir)) {
+				if (!isOurFile(name)) continue;
+				await node_fs_promises.default.rm(node_path.default.join(dir, name), { force: true }).catch(() => {});
+			}
+			await node_fs_promises.default.rmdir(dir).catch(() => {});
+		} catch (e) {
+			if (e?.code === "ENOENT") return;
+			logger.warn(`failed to clear the tree snapshot directory: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+	getStats() {
+		return this.stat;
+	}
+	fileFor(root) {
+		const { globalId } = (0, _milaboratories_pl_client.parseSignedResourceId)(root);
+		return node_path.default.join(this.ops.dir, `${FILE_PREFIX}${this.scope}.${globalId}${FILE_SUFFIX}`);
+	}
+	/**
+	* Reads the snapshot for a project root, or reports why there is nothing to restore.
+	*
+	* `root` is the id as resolved in the current session. Its signature is what the stored
+	* witness is compared against, so a rotated session is detected without inflating the
+	* payload, and no separate session lookup is needed anywhere.
+	*/
+	async read(root) {
+		const started = Date.now();
+		this.stat.reads++;
+		try {
+			const file = this.fileFor(root);
+			let bytes;
+			try {
+				bytes = await node_fs_promises.default.readFile(file);
+			} catch (e) {
+				const absent = e?.code === "ENOENT";
+				if (!absent) this.ops.logger.warn(`tree snapshot exists but could not be read: ${e instanceof Error ? e.message : String(e)}`);
+				return this.miss(absent ? "absent" : "unreadable");
+			}
+			const header = (0, _milaboratories_pl_tree.readPersistedTreeHeader)(bytes);
+			if (!header.ok) return this.miss(header.reason);
+			const { signature } = (0, _milaboratories_pl_client.parseSignedResourceId)(root);
+			if (!Buffer.from(header.value.witness).equals(Buffer.from(signature))) return this.miss("session-rotated");
+			const decoded = await (0, _milaboratories_pl_tree.decodePersistedTree)(bytes);
+			if (!decoded.ok) return this.miss(decoded.reason);
+			const now = /* @__PURE__ */ new Date();
+			await node_fs_promises.default.utimes(file, now, now).catch(() => {});
+			this.stat.hits++;
+			return {
+				ok: true,
+				tree: decoded.value
+			};
+		} finally {
+			this.stat.millisReading += Date.now() - started;
+		}
+	}
+	miss(miss) {
+		this.stat.misses[miss]++;
+		return {
+			ok: false,
+			miss
+		};
+	}
+	/** Recorded by the caller once it knows the tree accepted the snapshot. The store cannot
+	*  tell on its own: it hands over bytes, and whether they become a tree is the tree's call. */
+	noteRestored() {
+		this.stat.restores++;
+	}
+	/**
+	* Writes a snapshot, replacing any previous one for the same project.
+	*
+	* Never throws and never rejects: a write is an optimisation, and a full disk or a
+	* permissions problem must not fail the operation that triggered it. Staged and renamed
+	* into place, so a process killed mid-write leaves the previous snapshot rather than a torn
+	* one.
+	*/
+	async write(root, snapshot, ops = {}) {
+		const started = Date.now();
+		try {
+			const bytes = await (0, _milaboratories_pl_tree.encodePersistedTree)(snapshot, { compress: ops.compress });
+			await (0, _milaboratories_ts_helpers.ensureDirExists)(this.ops.dir);
+			const file = this.fileFor(root);
+			await (0, _milaboratories_ts_helpers.createPathAtomically)(this.ops.logger, file, async (tempPath) => {
+				await node_fs_promises.default.writeFile(tempPath, bytes, { flag: "wx" });
+			});
+			this.stat.writes++;
+			this.stat.bytesWritten += bytes.length;
+			return true;
+		} catch (e) {
+			this.stat.writeFailures++;
+			this.ops.logger.warn(`failed to write tree snapshot: ${e instanceof Error ? e.message : String(e)}`);
+			return false;
+		} finally {
+			this.stat.millisWriting += Date.now() - started;
+		}
+	}
+	/** Deletes the snapshot for a project. Used by the fail-safe, when a restored tree turns
+	*  out not to match what the backend will serve. Never throws. */
+	async discard(root) {
+		try {
+			await node_fs_promises.default.rm(this.fileFor(root), { force: true });
+			this.stat.discarded++;
+		} catch (e) {
+			this.ops.logger.warn(`failed to discard tree snapshot: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+	/**
+	* Startup housekeeping. Drops every snapshot outside the current scope (another build,
+	* backend, user or schema version), then trims what is left to the size ceiling, least
+	* recently written first.
+	*
+	* Modification time stands in for recency of use: an open project is rewritten
+	* periodically, so the file's age tracks how recently the project was worked on. Read times
+	* would be a truer signal but atime is unreliable across platforms and mount options.
+	*
+	* Runs at startup only, so the ceiling bounds what a session starts with rather than capping
+	* it throughout: a long session opening many projects can exceed it until the next launch.
+	*
+	* Never throws: an unusable cache directory should cost the cache, not the startup.
+	*/
+	async evict() {
+		try {
+			await (0, _milaboratories_ts_helpers.ensureDirExists)(this.ops.dir);
+			const names = await node_fs_promises.default.readdir(this.ops.dir);
+			const current = [];
+			for (const name of names) {
+				const file = node_path.default.join(this.ops.dir, name);
+				const inScope = name.startsWith(`${FILE_PREFIX}${this.scope}.`) && name.endsWith(FILE_SUFFIX);
+				if (!inScope && !isOurFile(name)) continue;
+				let size = 0;
+				let mtimeMs = 0;
+				try {
+					const stat = await node_fs_promises.default.stat(file);
+					if (!stat.isFile()) continue;
+					size = stat.size;
+					mtimeMs = stat.mtimeMs;
+				} catch {
+					continue;
+				}
+				if (inScope) {
+					current.push({
+						file,
+						size,
+						mtimeMs
+					});
+					continue;
+				}
+				await this.remove(file, size, false);
+			}
+			const ceiling = this.ops.maxSizeBytes;
+			let total = current.reduce((sum, e) => sum + e.size, 0);
+			if (total <= ceiling) return;
+			current.sort((a, b) => a.mtimeMs - b.mtimeMs);
+			for (const entry of current) {
+				if (total <= ceiling) break;
+				if (await this.remove(entry.file, entry.size, true)) total -= entry.size;
+			}
+		} catch (e) {
+			this.ops.logger.warn(`tree snapshot eviction failed: ${e instanceof Error ? e.message : String(e)}`);
+		}
+	}
+	async remove(file, size, forSize) {
+		try {
+			await node_fs_promises.default.rm(file, { force: true });
+			this.stat.evicted++;
+			this.stat.bytesEvicted += size;
+			if (forSize) this.stat.evictedForSize++;
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+//#endregion
+exports.TreeSnapshotStore = TreeSnapshotStore;
+
+//# sourceMappingURL=tree_snapshot_store.cjs.map

package/dist/middle_layer/tree_snapshot_store.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_snapshot_store.cjs","names":["PERSISTED_TREE_SCHEMA_VERSION","ML_BUILD_STAMP","fsp","path"],"sources":["../../src/middle_layer/tree_snapshot_store.ts"],"sourcesContent":["import type { PersistedTree, PersistedTreeReadFailure } from \"@milaboratories/pl-tree\";\nimport {\n  decodePersistedTree,\n  encodePersistedTree,\n  PERSISTED_TREE_SCHEMA_VERSION,\n  readPersistedTreeHeader,\n} from \"@milaboratories/pl-tree\";\nimport type { PlClient, SignedResourceId } from \"@milaboratories/pl-client\";\nimport { parseSignedResourceId } from \"@milaboratories/pl-client\";\nimport type { MiLogger } from \"@milaboratories/ts-helpers\";\nimport { createPathAtomically, ensureDirExists } from \"@milaboratories/ts-helpers\";\nimport { createHash } from \"node:crypto\";\nimport fsp from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { ML_BUILD_STAMP } from \"./build_stamp\";\n\n/** Why a read did not produce a tree to restore from. Counted rather than inferred, because\n *  \"no snapshot\" and \"a snapshot we refused\" are very different things when a warm reopen\n *  fails to be warm and someone has to work out why. */\nexport type TreeSnapshotMiss =\n  /** No file for this key: a first open, or the key moved (new build, new backend, new user). */\n  | \"absent\"\n  /** A file is there but could not be opened at all: permissions, a bad mount, an I/O error.\n   *  Distinct from `absent` because a first open and a broken cache directory need different\n   *  answers from whoever reads the counters. */\n  | \"unreadable\"\n  /** File exists, but its signatures belong to a session that has ended. Kept, not deleted. */\n  | \"session-rotated\"\n  /** File exists and could not be read. Carries the codec's reason. */\n  | PersistedTreeReadFailure;\n\nexport type TreeSnapshotStat = {\n  reads: number;\n  /** Snapshots read successfully. A hit is not yet a warm open: the tree can still refuse to\n   *  apply it, which is what {@link restores} counts. */\n  hits: number;\n  /** Snapshots actually applied as a tree's initial state. This is the number that says a\n   *  reopen was warm. */\n  restores: number;\n  /** Miss counts by reason. */\n  misses: Record<TreeSnapshotMiss, number>;\n  writes: number;\n  writeFailures: number;\n  bytesWritten: number;\n  /** Snapshots deleted by the fail-safe after a restored tree failed its first refresh. */\n  discarded: number;\n  /** Files removed at startup, and how many of those were dropped for being over the ceiling\n   *  rather than for belonging to another build, backend or user. */\n  evicted: number;\n  evictedForSize: number;\n  bytesEvicted: number;\n  millisReading: number;\n  millisWriting: number;\n};\n\nfunction initialStat(): TreeSnapshotStat {\n  return {\n    reads: 0,\n    hits: 0,\n    restores: 0,\n    misses: {\n      absent: 0,\n      unreadable: 0,\n      \"session-rotated\": 0,\n      \"not-a-snapshot\": 0,\n      \"unknown-schema\": 0,\n      truncated: 0,\n      checksum: 0,\n      malformed: 0,\n    },\n    writes: 0,\n    writeFailures: 0,\n    bytesWritten: 0,\n    discarded: 0,\n    evicted: 0,\n    evictedForSize: 0,\n    bytesEvicted: 0,\n    millisReading: 0,\n    millisWriting: 0,\n  };\n}\n\nexport type TreeSnapshotStoreOps = {\n  /** Directory holding the snapshots. One file per project. */\n  readonly dir: string;\n  /** Total bytes the directory may occupy after startup eviction. */\n  readonly maxSizeBytes: number;\n  readonly logger: MiLogger;\n};\n\nconst FILE_PREFIX = \"tree.\";\nconst FILE_SUFFIX = \".plts\";\n\n/** Keeps a filename to characters every filesystem we target accepts. */\nfunction safe(part: string): string {\n  return part.replace(/[^A-Za-z0-9_-]/g, \"_\");\n}\n\n/** Names this class writes: a finished snapshot, or the staging file of a write killed before\n *  its rename. The directory is caller-supplied and only defaults to one of ours, so nothing\n *  failing this is ever deleted, by the purge or by the startup eviction. */\nfunction isOurFile(name: string): boolean {\n  if (!name.startsWith(FILE_PREFIX)) return false;\n  return name.endsWith(FILE_SUFFIX) || name.includes(`${FILE_SUFFIX}.tmp.`);\n}\n\n/**\n * Snapshots of project tree mirrors on the local filesystem.\n *\n * A snapshot is addressed by backend instance, authenticated user, root resource, build stamp\n * and snapshot schema version. Everything except the root goes into the *scope*, which is\n * fixed for the lifetime of a client; the root distinguishes one project from another, so\n * there is one file per project per user per backend, rewritten in place.\n *\n * The session is deliberately not part of the key. It is witnessed inside the file and\n * compared on read: a snapshot from an ended session is a miss, but the file is kept, because\n * its bodies remain valid indefinitely and only its signatures have died. Deleting it would\n * destroy the evidence a future signature refresh would repair.\n */\nexport class TreeSnapshotStore {\n  private readonly stat = initialStat();\n\n  private constructor(\n    private readonly ops: TreeSnapshotStoreOps,\n    /** Identifies backend, user, build and schema. Same for every project in this session. */\n    private readonly scope: string,\n  ) {}\n\n  /**\n   * Builds a store for the given client, or returns undefined when nothing should be\n   * persisted for it.\n   *\n   * Returns undefined for an impersonated client: reading and writing under `asUser` would\n   * leave another user's mirror at rest under the admin's identity, usable only if the admin\n   * returned to that exact root. One condition removes both the hygiene question and the\n   * orphan one.\n   */\n  public static create(\n    pl: PlClient,\n    ops: TreeSnapshotStoreOps & { readonly enabled: boolean },\n  ): TreeSnapshotStore | undefined {\n    if (!ops.enabled) {\n      ops.logger.info(\"tree snapshots are disabled by configuration\");\n      return undefined;\n    }\n    if (pl.conf.asUser !== undefined) {\n      ops.logger.info(\"tree snapshots are disabled while the client is opened as another user\");\n      return undefined;\n    }\n\n    // The backend *instance*, not merely its address: instanceId rotates whenever the backend\n    // resets its database, which is exactly the case where the same address starts serving a\n    // different state under reused global ids. Without it, a reset at a fixed address (a local\n    // backend, whose working directory does not move) would be a key hit, and the only thing\n    // left to catch it would be the witness, which is empty on both sides on a backend that\n    // predates resource signatures.\n    //\n    // Hashed rather than spelled out: a login can be an email and an address can carry\n    // characters a filename cannot. The hash only has to be stable and to differ when any part\n    // differs, both of which it does. The NUL separator keeps the parts unambiguous.\n    const identity = createHash(\"sha256\")\n      .update([pl.conf.hostAndPort, pl.serverInfo.instanceId ?? \"\", pl.authUser ?? \"\"].join(\"\\0\"))\n      .digest(\"hex\")\n      .slice(0, 16);\n\n    const scope = `${PERSISTED_TREE_SCHEMA_VERSION}.${safe(ML_BUILD_STAMP)}.${identity}`;\n    return new TreeSnapshotStore(ops, scope);\n  }\n\n  /**\n   * Removes this class's files from the snapshot directory. Run when snapshots are switched\n   * off, so a user who turns the kill switch off because the disk is full or unwritable\n   * actually gets the space back, rather than leaving up to the size ceiling stranded there\n   * indefinitely.\n   *\n   * Deliberately keyed on the setting rather than on \"there is no store\": a store is also\n   * absent for an impersonated client, and deleting there would destroy the operator's own\n   * snapshots from their ordinary sessions. Never throws.\n   */\n  public static async purge(dir: string, logger: MiLogger): Promise<void> {\n    try {\n      // Deliberately NOT a recursive delete of `dir`. The path is caller-supplied and only\n      // defaults to a directory of ours, so removing it wholesale would let a misconfigured\n      // `treeSnapshotPath` take an unrelated directory with it, at the exact moment the user\n      // reached for a switch labelled \"my disk is troublesome\". Only files this class writes\n      // are removed, then the directory itself if that emptied it.\n      for (const name of await fsp.readdir(dir)) {\n        if (!isOurFile(name)) continue;\n        await fsp.rm(path.join(dir, name), { force: true }).catch(() => {});\n      }\n      await fsp.rmdir(dir).catch(() => {\n        // Still holds something that is not ours; leaving it is the point.\n      });\n    } catch (e: unknown) {\n      if ((e as NodeJS.ErrnoException | null)?.code === \"ENOENT\") return;\n      logger.warn(\n        `failed to clear the tree snapshot directory: ${e instanceof Error ? e.message : String(e)}`,\n      );\n    }\n  }\n\n  public getStats(): Readonly<TreeSnapshotStat> {\n    return this.stat;\n  }\n\n  private fileFor(root: SignedResourceId): string {\n    // The root's global id, not the signed form: the signature changes every session while\n    // the file must not.\n    const { globalId } = parseSignedResourceId(root);\n    return path.join(this.ops.dir, `${FILE_PREFIX}${this.scope}.${globalId}${FILE_SUFFIX}`);\n  }\n\n  /**\n   * Reads the snapshot for a project root, or reports why there is nothing to restore.\n   *\n   * `root` is the id as resolved in the current session. Its signature is what the stored\n   * witness is compared against, so a rotated session is detected without inflating the\n   * payload, and no separate session lookup is needed anywhere.\n   */\n  public async read(\n    root: SignedResourceId,\n  ): Promise<{ ok: true; tree: PersistedTree } | { ok: false; miss: TreeSnapshotMiss }> {\n    const started = Date.now();\n    this.stat.reads++;\n    try {\n      const file = this.fileFor(root);\n      let bytes: Buffer;\n      try {\n        bytes = await fsp.readFile(file);\n      } catch (e: unknown) {\n        // A missing file and an unreadable one both mean a cold open, but they are different\n        // problems: one is an ordinary first open, the other is a cache directory that needs\n        // attention, and the counters are the only place that difference is visible.\n        const absent = (e as NodeJS.ErrnoException | null)?.code === \"ENOENT\";\n        if (!absent)\n          this.ops.logger.warn(\n            `tree snapshot exists but could not be read: ${e instanceof Error ? e.message : String(e)}`,\n          );\n        return this.miss(absent ? \"absent\" : \"unreadable\");\n      }\n\n      const header = readPersistedTreeHeader(bytes);\n      if (!header.ok) return this.miss(header.reason);\n\n      // On a backend predating resource signatures both sides are empty and always match,\n      // which is right: without signatures the ids are not session-bound in the first place.\n      const { signature } = parseSignedResourceId(root);\n      if (!Buffer.from(header.value.witness).equals(Buffer.from(signature)))\n        // Kept, not deleted. See the class comment.\n        return this.miss(\"session-rotated\");\n\n      const decoded = await decodePersistedTree(bytes);\n      if (!decoded.ok) return this.miss(decoded.reason);\n\n      // Touched on a hit so the modification time tracks last *use*, which is what the size\n      // trim is supposed to order by. Without this, a project reopened every day but never\n      // changed is never rewritten, and so ages out ahead of one touched once and abandoned.\n      const now = new Date();\n      await fsp.utimes(file, now, now).catch(() => {\n        // Ordering the trim is not worth failing a hit over.\n      });\n\n      this.stat.hits++;\n      return { ok: true, tree: decoded.value };\n    } finally {\n      this.stat.millisReading += Date.now() - started;\n    }\n  }\n\n  private miss(miss: TreeSnapshotMiss): { ok: false; miss: TreeSnapshotMiss } {\n    this.stat.misses[miss]++;\n    return { ok: false, miss };\n  }\n\n  /** Recorded by the caller once it knows the tree accepted the snapshot. The store cannot\n   *  tell on its own: it hands over bytes, and whether they become a tree is the tree's call. */\n  public noteRestored(): void {\n    this.stat.restores++;\n  }\n\n  /**\n   * Writes a snapshot, replacing any previous one for the same project.\n   *\n   * Never throws and never rejects: a write is an optimisation, and a full disk or a\n   * permissions problem must not fail the operation that triggered it. Staged and renamed\n   * into place, so a process killed mid-write leaves the previous snapshot rather than a torn\n   * one.\n   */\n  public async write(\n    root: SignedResourceId,\n    snapshot: PersistedTree,\n    ops: { compress?: boolean } = {},\n  ): Promise<boolean> {\n    const started = Date.now();\n    try {\n      const bytes = await encodePersistedTree(snapshot, { compress: ops.compress });\n      await ensureDirExists(this.ops.dir);\n\n      const file = this.fileFor(root);\n      await createPathAtomically(this.ops.logger, file, async (tempPath) => {\n        // \"wx\" so a colliding temp name fails instead of overwriting another writer's file.\n        await fsp.writeFile(tempPath, bytes, { flag: \"wx\" });\n      });\n\n      this.stat.writes++;\n      this.stat.bytesWritten += bytes.length;\n      return true;\n    } catch (e: unknown) {\n      this.stat.writeFailures++;\n      this.ops.logger.warn(\n        `failed to write tree snapshot: ${e instanceof Error ? e.message : String(e)}`,\n      );\n      return false;\n    } finally {\n      this.stat.millisWriting += Date.now() - started;\n    }\n  }\n\n  /** Deletes the snapshot for a project. Used by the fail-safe, when a restored tree turns\n   *  out not to match what the backend will serve. Never throws. */\n  public async discard(root: SignedResourceId): Promise<void> {\n    try {\n      await fsp.rm(this.fileFor(root), { force: true });\n      this.stat.discarded++;\n    } catch (e: unknown) {\n      this.ops.logger.warn(\n        `failed to discard tree snapshot: ${e instanceof Error ? e.message : String(e)}`,\n      );\n    }\n  }\n\n  /**\n   * Startup housekeeping. Drops every snapshot outside the current scope (another build,\n   * backend, user or schema version), then trims what is left to the size ceiling, least\n   * recently written first.\n   *\n   * Modification time stands in for recency of use: an open project is rewritten\n   * periodically, so the file's age tracks how recently the project was worked on. Read times\n   * would be a truer signal but atime is unreliable across platforms and mount options.\n   *\n   * Runs at startup only, so the ceiling bounds what a session starts with rather than capping\n   * it throughout: a long session opening many projects can exceed it until the next launch.\n   *\n   * Never throws: an unusable cache directory should cost the cache, not the startup.\n   */\n  public async evict(): Promise<void> {\n    try {\n      await ensureDirExists(this.ops.dir);\n      const names = await fsp.readdir(this.ops.dir);\n\n      const current: { file: string; size: number; mtimeMs: number }[] = [];\n\n      for (const name of names) {\n        const file = path.join(this.ops.dir, name);\n\n        // Anything of ours not addressed to the current scope goes: another build, backend,\n        // user or schema version, and also the staging files of a write that was killed\n        // before its rename, which end in `.tmp.<hex>` rather than the suffix.\n        const inScope =\n          name.startsWith(`${FILE_PREFIX}${this.scope}.`) && name.endsWith(FILE_SUFFIX);\n\n        // Out of scope is not the same as ours to delete: a `treeSnapshotPath` pointed at an\n        // existing or shared directory would otherwise have every file in it removed at\n        // startup. Same rule as `purge`, for the same reason.\n        if (!inScope && !isOurFile(name)) continue;\n\n        let size = 0;\n        let mtimeMs = 0;\n        try {\n          const stat = await fsp.stat(file);\n          if (!stat.isFile()) continue;\n          size = stat.size;\n          mtimeMs = stat.mtimeMs;\n        } catch {\n          continue; // vanished under us, or unreadable: nothing to account for\n        }\n\n        if (inScope) {\n          current.push({ file, size, mtimeMs });\n          continue;\n        }\n\n        await this.remove(file, size, false);\n      }\n\n      const ceiling = this.ops.maxSizeBytes;\n      let total = current.reduce((sum, e) => sum + e.size, 0);\n      if (total <= ceiling) return;\n\n      // Oldest first, so the projects a user is actually working on are the ones that survive.\n      current.sort((a, b) => a.mtimeMs - b.mtimeMs);\n      for (const entry of current) {\n        if (total <= ceiling) break;\n        // Only a file that actually went stops counting against the ceiling. Subtracting\n        // regardless would let one undeletable file end the trim early and leave the directory\n        // over its limit.\n        if (await this.remove(entry.file, entry.size, true)) total -= entry.size;\n      }\n    } catch (e: unknown) {\n      this.ops.logger.warn(\n        `tree snapshot eviction failed: ${e instanceof Error ? e.message : String(e)}`,\n      );\n    }\n  }\n\n  private async remove(file: string, size: number, forSize: boolean): Promise<boolean> {\n    try {\n      await fsp.rm(file, { force: true });\n      this.stat.evicted++;\n      this.stat.bytesEvicted += size;\n      if (forSize) this.stat.evictedForSize++;\n      return true;\n    } catch {\n      // A file we cannot delete is not worth failing startup over; it will be reconsidered\n      // on the next one.\n      return false;\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/middle_layer/tree_snapshot_store.d.ts

@@ -0,0 +1,143 @@
+import { MiLogger } from "@milaboratories/ts-helpers";
+import { PlClient, SignedResourceId } from "@milaboratories/pl-client";
+import { PersistedTree, PersistedTreeReadFailure } from "@milaboratories/pl-tree";
+//#region src/middle_layer/tree_snapshot_store.d.ts
+/** Why a read did not produce a tree to restore from. Counted rather than inferred, because
+ *  "no snapshot" and "a snapshot we refused" are very different things when a warm reopen
+ *  fails to be warm and someone has to work out why. */
+export type TreeSnapshotMiss =
+/** No file for this key: a first open, or the key moved (new build, new backend, new user). */
+"absent" |
+/** A file is there but could not be opened at all: permissions, a bad mount, an I/O error.
+ *  Distinct from `absent` because a first open and a broken cache directory need different
+ *  answers from whoever reads the counters. */
+"unreadable" |
+/** File exists, but its signatures belong to a session that has ended. Kept, not deleted. */
+"session-rotated" |
+/** File exists and could not be read. Carries the codec's reason. */
+PersistedTreeReadFailure;
+export type TreeSnapshotStat = {
+  reads: number;
+  /** Snapshots read successfully. A hit is not yet a warm open: the tree can still refuse to
+   *  apply it, which is what {@link restores} counts. */
+  hits: number;
+  /** Snapshots actually applied as a tree's initial state. This is the number that says a
+   *  reopen was warm. */
+  restores: number;
+  /** Miss counts by reason. */
+  misses: Record<TreeSnapshotMiss, number>;
+  writes: number;
+  writeFailures: number;
+  bytesWritten: number;
+  /** Snapshots deleted by the fail-safe after a restored tree failed its first refresh. */
+  discarded: number;
+  /** Files removed at startup, and how many of those were dropped for being over the ceiling
+   *  rather than for belonging to another build, backend or user. */
+  evicted: number;
+  evictedForSize: number;
+  bytesEvicted: number;
+  millisReading: number;
+  millisWriting: number;
+};
+export type TreeSnapshotStoreOps = {
+  /** Directory holding the snapshots. One file per project. */
+  readonly dir: string;
+  /** Total bytes the directory may occupy after startup eviction. */
+  readonly maxSizeBytes: number;
+  readonly logger: MiLogger;
+};
+/**
+ * Snapshots of project tree mirrors on the local filesystem.
+ *
+ * A snapshot is addressed by backend instance, authenticated user, root resource, build stamp
+ * and snapshot schema version. Everything except the root goes into the *scope*, which is
+ * fixed for the lifetime of a client; the root distinguishes one project from another, so
+ * there is one file per project per user per backend, rewritten in place.
+ *
+ * The session is deliberately not part of the key. It is witnessed inside the file and
+ * compared on read: a snapshot from an ended session is a miss, but the file is kept, because
+ * its bodies remain valid indefinitely and only its signatures have died. Deleting it would
+ * destroy the evidence a future signature refresh would repair.
+ */
+export declare class TreeSnapshotStore {
+  private readonly ops;
+  /** Identifies backend, user, build and schema. Same for every project in this session. */
+  private readonly scope;
+  private readonly stat;
+  private constructor();
+  /**
+   * Builds a store for the given client, or returns undefined when nothing should be
+   * persisted for it.
+   *
+   * Returns undefined for an impersonated client: reading and writing under `asUser` would
+   * leave another user's mirror at rest under the admin's identity, usable only if the admin
+   * returned to that exact root. One condition removes both the hygiene question and the
+   * orphan one.
+   */
+  static create(pl: PlClient, ops: TreeSnapshotStoreOps & {
+    readonly enabled: boolean;
+  }): TreeSnapshotStore | undefined;
+  /**
+   * Removes this class's files from the snapshot directory. Run when snapshots are switched
+   * off, so a user who turns the kill switch off because the disk is full or unwritable
+   * actually gets the space back, rather than leaving up to the size ceiling stranded there
+   * indefinitely.
+   *
+   * Deliberately keyed on the setting rather than on "there is no store": a store is also
+   * absent for an impersonated client, and deleting there would destroy the operator's own
+   * snapshots from their ordinary sessions. Never throws.
+   */
+  static purge(dir: string, logger: MiLogger): Promise<void>;
+  getStats(): Readonly<TreeSnapshotStat>;
+  private fileFor;
+  /**
+   * Reads the snapshot for a project root, or reports why there is nothing to restore.
+   *
+   * `root` is the id as resolved in the current session. Its signature is what the stored
+   * witness is compared against, so a rotated session is detected without inflating the
+   * payload, and no separate session lookup is needed anywhere.
+   */
+  read(root: SignedResourceId): Promise<{
+    ok: true;
+    tree: PersistedTree;
+  } | {
+    ok: false;
+    miss: TreeSnapshotMiss;
+  }>;
+  private miss;
+  /** Recorded by the caller once it knows the tree accepted the snapshot. The store cannot
+   *  tell on its own: it hands over bytes, and whether they become a tree is the tree's call. */
+  noteRestored(): void;
+  /**
+   * Writes a snapshot, replacing any previous one for the same project.
+   *
+   * Never throws and never rejects: a write is an optimisation, and a full disk or a
+   * permissions problem must not fail the operation that triggered it. Staged and renamed
+   * into place, so a process killed mid-write leaves the previous snapshot rather than a torn
+   * one.
+   */
+  write(root: SignedResourceId, snapshot: PersistedTree, ops?: {
+    compress?: boolean;
+  }): Promise<boolean>;
+  /** Deletes the snapshot for a project. Used by the fail-safe, when a restored tree turns
+   *  out not to match what the backend will serve. Never throws. */
+  discard(root: SignedResourceId): Promise<void>;
+  /**
+   * Startup housekeeping. Drops every snapshot outside the current scope (another build,
+   * backend, user or schema version), then trims what is left to the size ceiling, least
+   * recently written first.
+   *
+   * Modification time stands in for recency of use: an open project is rewritten
+   * periodically, so the file's age tracks how recently the project was worked on. Read times
+   * would be a truer signal but atime is unreliable across platforms and mount options.
+   *
+   * Runs at startup only, so the ceiling bounds what a session starts with rather than capping
+   * it throughout: a long session opening many projects can exceed it until the next launch.
+   *
+   * Never throws: an unusable cache directory should cost the cache, not the startup.
+   */
+  evict(): Promise<void>;
+  private remove;
+}
+//#endregion
+//# sourceMappingURL=tree_snapshot_store.d.ts.map

package/dist/middle_layer/tree_snapshot_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_snapshot_store.d.ts","names":[],"sources":["../../src/middle_layer/tree_snapshot_store.ts"],"mappings":";;;;;;;YAmBY;;;;;;;;;;AAUR;YAEQ;EACV;;;EAGA;;;EAGA;;EAEA,QAAQ,OAAO;EACf;EACA;EACA;;EAEA;;;EAGA;EACA;EACA;EACA;EACA;;YA8BU;;WAED;;WAEA;WACA,QAAQ;;;;;;;;;;;;;;;qBAgCN;mBAIQ;;mBAEA;mBALF;UAEV;;;;;;;;;;SAeO,OACZ,IAAI,UACJ,KAAK;aAAkC;MACtC;;;;;;;;;;;SAuCiB,MAAM,aAAa,QAAQ,WAAW;EAsBnD,YAAY,SAAS;UAIpB;;;;;;;;EAcK,KACX,MAAM,mBACL;IAAU;IAAU,MAAM;;IAAoB;IAAW,MAAM;;UAgD1D;;;EAOD;;;;;;;;;EAYM,MACX,MAAM,kBACN,UAAU,eACV;IAAO;MACN;;;EA4BU,QAAQ,MAAM,mBAAmB;;;;;;;;;;;;;;;EAyBjC,SAAS;UA4DR"}