@classytic/arc-testkit 0.5.0 → 0.7.0

package/dist/mongo.mjs

@@ -1,5 +1,286 @@
-import { cpus, freemem, totalmem } from "node:os";
-//#region src/mongo.ts
+import { t as registerProcessCleanup } from "./process-cleanup-1iBIS_o_.mjs";
+import { rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { cpus, freemem, tmpdir, totalmem } from "node:os";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises";
+// src/mongo-tmp.ts
+/** Prefix mongodb-memory-server gives its data dirs (and that ours use). */
+const MONGO_MEM_DIR_PREFIX = "mongo-mem-";
+/** Replica-set keyfile dirs: no lock file to prove them dead, so never swept. */
+const KEYFILE_DIR_PREFIX = "mongo-mem-keyfile-";
+const HOUR_MS = 36e5;
+const DEFAULT_MAX_AGE_HOURS = 6;
+/** The dedicated base dir from `TEST_MONGO_TMPDIR`, resolved, or undefined. */
+function mongoMemoryTmpBase() {
+	const raw = process.env.TEST_MONGO_TMPDIR?.trim();
+	return raw ? resolve(raw) : void 0;
+}
+/** Minimum age (ms) of a dir the sweep may remove; `null` when the sweep is off. */
+function staleMongoMemoryAgeMs() {
+	const raw = process.env.TEST_MONGO_SWEEP_HOURS?.trim().toLowerCase();
+	if (raw === "0" || raw === "off" || raw === "false") return null;
+	const hours = Number(raw);
+	return raw && Number.isFinite(hours) && hours > 0 ? hours * HOUR_MS : DEFAULT_MAX_AGE_HOURS * HOUR_MS;
+}
+/** Whether a process with this pid exists. EPERM means it exists but is not ours. */
+function isPidAlive(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err.code === "EPERM";
+	}
+}
+/** The pid in a data dir's `mongod.lock`. mongod empties it on a clean shutdown. */
+async function lockPid(dir) {
+	try {
+		const pid = Number.parseInt((await readFile(join(dir, "mongod.lock"), "utf8")).trim(), 10);
+		return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Newest mtime of the dir and its direct entries. The dir's own mtime changes
+* only when an entry is added or removed; a live mongod's activity shows in its
+* files (WiredTiger.wt, sizeStorer.wt, the journal), so those count too.
+*/
+async function newestMtimeMs(dir) {
+	let newest = (await stat(dir)).mtimeMs;
+	let names = [];
+	try {
+		names = await readdir(dir);
+	} catch {}
+	for (const name of names) try {
+		const { mtimeMs } = await stat(join(dir, name));
+		if (mtimeMs > newest) newest = mtimeMs;
+	} catch {}
+	return newest;
+}
+function defaultSweepDirs() {
+	const base = mongoMemoryTmpBase();
+	return base ? [tmpdir(), base] : [tmpdir()];
+}
+/**
+* Remove abandoned `mongo-mem-*` data dirs.
+*
+* A dir is removed only when BOTH hold: its `mongod.lock` names no live process
+* (or is empty or missing), and nothing in it changed for `maxAgeMs`. Keyfile
+* dirs and anything without the prefix are never touched. Errors are collected,
+* never thrown: a sweep must not fail a test run.
+*/
+async function sweepStaleMongoMemoryDirs(options = {}) {
+	const result = {
+		removed: [],
+		kept: [],
+		failed: []
+	};
+	const maxAgeMs = options.maxAgeMs === void 0 ? staleMongoMemoryAgeMs() : options.maxAgeMs;
+	if (maxAgeMs === null) return result;
+	const now = options.now ?? Date.now();
+	const alive = options.isAlive ?? isPidAlive;
+	const bases = new Set((options.dirs ?? defaultSweepDirs()).map((d) => resolve(d)));
+	for (const base of bases) {
+		let entries;
+		try {
+			entries = await readdir(base, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			if (!entry.name.startsWith("mongo-mem-")) continue;
+			if (entry.name.startsWith(KEYFILE_DIR_PREFIX)) continue;
+			const path = join(base, entry.name);
+			try {
+				const pid = await lockPid(path);
+				if (pid !== void 0 && alive(pid)) {
+					result.kept.push({
+						path,
+						reason: "live-process"
+					});
+					continue;
+				}
+				if (now - await newestMtimeMs(path) < maxAgeMs) {
+					result.kept.push({
+						path,
+						reason: "recent"
+					});
+					continue;
+				}
+				await rm(path, {
+					recursive: true,
+					force: true,
+					maxRetries: 2,
+					retryDelay: 100
+				});
+				result.removed.push(path);
+			} catch (err) {
+				result.failed.push({
+					path,
+					error: err.message
+				});
+			}
+		}
+	}
+	return result;
+}
+let processSweep;
+/**
+* Run the sweep at most once per process, in the background. Started before a
+* process boots its first server; never awaited there, because a first sweep
+* after a long leak can have gigabytes to delete. Logs one line when it removed
+* anything, so a machine that keeps leaking is noticed.
+*/
+function sweepStaleMongoMemoryDirsOnce(label = "arc-testkit") {
+	processSweep ??= sweepStaleMongoMemoryDirs().then((r) => {
+		if (r.removed.length > 0) console.warn(`[${label}] removed ${r.removed.length} abandoned mongo-mem-* temp dir(s) left by killed or crashed test runs`);
+		return r;
+	}, () => ({
+		removed: [],
+		kept: [],
+		failed: []
+	}));
+	return processSweep;
+}
+async function newDataDir(base) {
+	await mkdir(base, { recursive: true });
+	return mkdtemp(join(base, MONGO_MEM_DIR_PREFIX));
+}
+/**
+* Point every member at a fresh dir under `base`, unless the caller set its own
+* `dbPath` / `instanceOpts` (then the caller owns that location).
+*/
+async function withDedicatedDataDirs(kind, opts, base, owned) {
+	if (kind === "standalone") {
+		const instance = opts.instance ?? {};
+		if (instance.dbPath !== void 0) return opts;
+		const dbPath = await newDataDir(base);
+		owned.push(dbPath);
+		return {
+			...opts,
+			instance: {
+				...instance,
+				dbPath
+			}
+		};
+	}
+	const existing = opts.instanceOpts;
+	if (existing && existing.length > 0) return opts;
+	const count = Number(opts.replSet?.count ?? 1);
+	const instanceOpts = [];
+	for (let i = 0; i < Math.max(1, count); i += 1) {
+		const dbPath = await newDataDir(base);
+		owned.push(dbPath);
+		instanceOpts.push({ dbPath });
+	}
+	return {
+		...opts,
+		instanceOpts
+	};
+}
+function instancesOf(server) {
+	const members = server.servers;
+	return Array.isArray(members) ? members : [server];
+}
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+/** Synchronous sleep, for the `exit` path where no timer fires. */
+function sleepSync(ms) {
+	Atomics.wait(sleepCell, 0, 0, ms);
+}
+/**
+* Remove a dir synchronously, retrying for up to `timeoutMs`. A killed mongod
+* is reported gone before Windows releases its file handles, so the first
+* attempts can fail with EPERM / EBUSY.
+*/
+function removeDirSync(dir, timeoutMs = 0) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) try {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		return;
+	} catch {
+		if (Date.now() >= deadline) return;
+		sleepSync(50);
+	}
+}
+/** Block until none of `pids` is alive, at most `timeoutMs`. */
+function waitForExitSync(pids, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (pids.some(isPidAlive) && Date.now() < deadline) sleepSync(25);
+}
+/**
+* Create and start a `MongoMemoryServer` (`standalone`) or `MongoMemoryReplSet`
+* (`replset`) with the cleanup guarantees described at the top of this file.
+*
+* `Ctor` is the class itself, so a caller that loads mongodb-memory-server its
+* own way (by resolved path, through an alias) keeps doing so.
+*/
+async function launchMongoMemory(Ctor, kind, createOptions = {}) {
+	const base = mongoMemoryTmpBase();
+	const ownedDirs = [];
+	const opts = base ? await withDedicatedDataDirs(kind, createOptions, base, ownedDirs) : createOptions;
+	const cleanup = {
+		doCleanup: true,
+		force: ownedDirs.length > 0
+	};
+	const server = new Ctor(opts);
+	try {
+		await server.start();
+	} catch (err) {
+		await server.stop(cleanup).catch(() => void 0);
+		for (const dir of ownedDirs) removeDirSync(dir, 2e3);
+		throw err;
+	}
+	let stopped = false;
+	return {
+		server,
+		ownedDirs,
+		async stop() {
+			if (stopped) return;
+			stopped = true;
+			if (await server.stop(cleanup) !== false) for (const dir of ownedDirs) removeDirSync(dir);
+		},
+		stopSync() {
+			if (stopped) return;
+			stopped = true;
+			const dirs = new Set(ownedDirs);
+			const pids = [];
+			for (const member of instancesOf(server)) {
+				const info = member.instanceInfo;
+				const pid = info?.instance?.mongodProcess?.pid;
+				if (pid) {
+					pids.push(pid);
+					try {
+						process.kill(pid, "SIGKILL");
+					} catch {}
+				}
+				if (info?.tmpDir) dirs.add(info.tmpDir);
+			}
+			waitForExitSync(pids, 5e3);
+			for (const dir of dirs) removeDirSync(dir, 5e3);
+		}
+	};
+}
+/**
+* Stop a launched server when the process ends without its teardown: Ctrl-C /
+* SIGTERM stop it properly, then re-raise so the exit code stays truthful; an
+* `exit` (including an uncaught exception) kills mongod and removes the dir
+* synchronously. Returns an untrack function for the orderly path.
+*
+* Uses the package's ONE shared process hook, so tracking many servers adds no
+* listeners beyond one per event.
+*/
+function stopOnProcessExit(handle) {
+	return registerProcessCleanup({
+		stop: () => handle.stop(),
+		stopSync: () => handle.stopSync()
+	});
+}
+// src/mongo.ts
 /**
 * `@classytic/arc-testkit/mongo` — the Mongo adapter for the driver-agnostic pool.
 *
@@ -138,16 +419,22 @@ function mongoServerProvider(options = {}) {
 			* half-the-machine cache default exactly where nobody is watching.
 			*/
 			const create = opts?.createOptions;
-			const server = kind === "transactional" ? await mms.MongoMemoryReplSet.create(create ?? { replSet: {
+			sweepStaleMongoMemoryDirsOnce();
+			/**
+			* Started through `launchMongoMemory`, not `create()`: it always stops
+			* with cleanup, cleans up a failed start (mongodb-memory-server keeps
+			* that dir "for investigation"), honours `TEST_MONGO_TMPDIR`, and gives
+			* the pool a synchronous `stopSync` for its process `exit` handler.
+			*/
+			const launched = kind === "transactional" ? await launchMongoMemory(mms.MongoMemoryReplSet, "replset", create ?? { replSet: {
 				count: 1,
 				storageEngine: "wiredTiger",
 				args
-			} }) : await mms.MongoMemoryServer.create(create ?? { instance: { args } });
+			} }) : await launchMongoMemory(mms.MongoMemoryServer, "standalone", create ?? { instance: { args } });
 			return {
-				uri: server.getUri(),
-				stop: async () => {
-					await server.stop();
-				}
+				uri: launched.server.getUri(),
+				stop: () => launched.stop(),
+				stopSync: () => launched.stopSync()
 			};
 		},
 		/**
@@ -225,5 +512,4 @@ function mongoServerProvider(options = {}) {
 		}
 	};
 }
-//#endregion
-export { awaitIndexBuilds, cacheSizeGB, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, withDbName };
+export { MONGO_MEM_DIR_PREFIX, awaitIndexBuilds, cacheSizeGB, isPidAlive, launchMongoMemory, mongoMemoryTmpBase, mongoServerProvider, mongodMemoryArgs, safePoolSize, safeWorkerCount, staleMongoMemoryAgeMs, stopOnProcessExit, sweepStaleMongoMemoryDirs, withDbName };

package/dist/pool.d.mts

@@ -1,12 +1,17 @@
 import { TestDatabase, TestDatabaseFactory } from "@classytic/arc/testing";
-//#region src/pool.d.ts
 /** Which server shape a suite needs. */
-type ServerKind = "standalone" | "transactional";
+export type ServerKind = "standalone" | "transactional";
 /** A running server the pool may hand out namespaces on. */
-interface TestServerHandle {
+export interface TestServerHandle {
   /** Base connection string, WITHOUT a namespace selected. */
   readonly uri: string;
   stop(): Promise<void>;
+  /**
+   * Optional: best-effort SYNCHRONOUS stop, for a process `exit` handler where
+   * no async work completes. Without it an `exit` only starts `stop()`, the
+   * process ends before it finishes, and the server's data dir is left behind.
+   */
+  stopSync?(): void;
 }
 /**
  * What a driver must supply. Two methods, deliberately.
@@ -15,7 +20,7 @@ interface TestServerHandle {
  * is the same in every driver, so putting it here would duplicate it per driver
  * — which is precisely the failure this module exists to end.
  */
-interface TestServerProvider<TConn> {
+export interface TestServerProvider<TConn> {
   /** Human name, used only in diagnostics. */
   readonly name: string;
   /**
@@ -67,7 +72,7 @@ interface TestServerProvider<TConn> {
    */
   afterBoot?(): Promise<void>;
 }
-interface TestDatabasePoolOptions {
+export interface TestDatabasePoolOptions {
   /**
    * Env-var prefix for the cross-worker handshake. Two runs with different
    * prefixes (a spine run and a host run) can share a machine without either
@@ -145,7 +150,7 @@ interface TestDatabasePoolOptions {
   /** Escape hatch: force per-suite private servers (the unpooled behaviour). */
   readonly disabled?: boolean;
 }
-interface TestDatabasePool<TConn> {
+export interface TestDatabasePool<TConn> {
   /** Hand to `bootModuleApp({ database })`. */
   readonly factory: TestDatabaseFactory<TConn>;
   /** Wrap a boot function so it defaults to the pool. */
@@ -178,13 +183,11 @@ interface TestDatabasePool<TConn> {
     live: number;
   };
 }
-declare function createTestDatabasePool<TConn>(provider: TestServerProvider<TConn>, options?: TestDatabasePoolOptions): TestDatabasePool<TConn>;
+export declare function createTestDatabasePool<TConn>(provider: TestServerProvider<TConn>, options?: TestDatabasePoolOptions): TestDatabasePool<TConn>;
 /**
  * Publish a started server so other worker PROCESSES reuse it.
  *
  * Only a process that owns servers calls this — typically an eager
  * `globalSetup` in a run that prefers boot-cost-up-front over laziness.
  */
-declare function publishPoolServers(servers: Partial<Record<ServerKind, readonly string[]>>, envPrefix?: string): void;
-//#endregion
-export { ServerKind, TestDatabasePool, TestDatabasePoolOptions, TestServerHandle, TestServerProvider, createTestDatabasePool, publishPoolServers };
+export declare function publishPoolServers(servers: Partial<Record<ServerKind, readonly string[]>>, envPrefix?: string): void;

package/dist/pool.mjs

@@ -1,8 +1,9 @@
-import { randomBytes } from "node:crypto";
+import { n as unregisterProcessCleanup, t as registerProcessCleanup } from "./process-cleanup-1iBIS_o_.mjs";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
 import { join } from "node:path";
-//#region src/pool.ts
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+// src/pool.ts
 /**
 * `@classytic/arc-testkit/pool` — a POOLED `TestDatabaseFactory`, driver-agnostic.
 *
@@ -207,35 +208,37 @@ function createTestDatabasePool(provider, options = {}) {
 	* started on a machine with less memory than the one before.
 	*
 	* `exit` handlers must be SYNCHRONOUS, so the async `stop()` is not awaited
-	* there; it is a best-effort kill on the way out. The signal handlers get to
-	* await properly, which is the path that actually matters for Ctrl-C.
+	* there; a handle with `stopSync()` (the Mongo adapter's) is killed and its
+	* data dir removed synchronously, any other gets a best-effort `stop()`.
+	* The signal handlers get to await properly, which is the path that actually
+	* matters for Ctrl-C.
+	*/
+	const processCleanup = {
+		stop: () => stopAll(),
+		stopSync: () => {
+			const handles = [...started.values(), ...privateHandles];
+			started.clear();
+			starting.clear();
+			privateHandles.clear();
+			for (const handle of handles) if (handle.stopSync) handle.stopSync();
+			else handle.stop();
+		}
+	};
+	/**
+	* Registered with the package's ONE shared process hook rather than adding
+	* listeners per pool: a suite that builds many pools would otherwise pass
+	* Node's listener limit (`MaxListenersExceededWarning`). Unregistered by
+	* `stopAll()`, re-registered on the next server this pool owns.
 	*/
-	let exitHooked = false;
 	function hookProcessExit() {
-		if (exitHooked) return;
-		exitHooked = true;
-		const onSignal = (signal) => {
-			stopAll().finally(() => {
-				process.removeListener(signal, onSignal);
-				process.kill(process.pid, signal);
-			});
-		};
-		for (const signal of [
-			"SIGINT",
-			"SIGTERM",
-			"SIGHUP",
-			"SIGBREAK"
-		]) process.once(signal, onSignal);
-		process.once("exit", () => {
-			for (const handle of started.values()) handle.stop();
-			for (const handle of privateHandles) handle.stop();
-		});
+		registerProcessCleanup(processCleanup);
 	}
 	async function stopAll() {
 		const handles = [...started.values(), ...privateHandles];
 		started.clear();
 		starting.clear();
 		privateHandles.clear();
+		unregisterProcessCleanup(processCleanup);
 		await Promise.all(handles.map((h) => h.stop().catch(() => void 0)));
 	}
 	const factory = async (opts) => {
@@ -406,5 +409,4 @@ function publishPoolServers(servers, envPrefix = "ARC_TESTKIT") {
 	}
 	writeFileSync(file, JSON.stringify(servers));
 }
-//#endregion
 export { createTestDatabasePool, publishPoolServers };

package/dist/process-cleanup-1iBIS_o_.mjs

@@ -0,0 +1,66 @@
+// src/process-cleanup.ts
+/** Signals that end a test run; SIGBREAK is Windows Ctrl-Break. */
+const CLEANUP_SIGNALS = [
+	"SIGINT",
+	"SIGTERM",
+	"SIGHUP",
+	"SIGBREAK"
+];
+const STATE_KEY = Symbol.for("@classytic/arc-testkit/process-cleanup");
+function state() {
+	const g = globalThis;
+	const existing = g[STATE_KEY];
+	if (existing) return existing;
+	const entries = /* @__PURE__ */ new Set();
+	const created = {
+		entries,
+		hooked: false,
+		onSignal: (signal) => {
+			const all = [...entries];
+			entries.clear();
+			unhook(created);
+			Promise.all(all.map((e) => e.stop().catch(() => void 0))).finally(() => {
+				process.kill(process.pid, signal);
+			});
+		},
+		onExit: () => {
+			const all = [...entries];
+			entries.clear();
+			unhook(created);
+			for (const e of all) try {
+				e.stopSync();
+			} catch {}
+		}
+	};
+	g[STATE_KEY] = created;
+	return created;
+}
+function hook(s) {
+	if (s.hooked) return;
+	s.hooked = true;
+	for (const signal of CLEANUP_SIGNALS) process.on(signal, s.onSignal);
+	process.on("exit", s.onExit);
+}
+function unhook(s) {
+	if (!s.hooked) return;
+	s.hooked = false;
+	for (const signal of CLEANUP_SIGNALS) process.removeListener(signal, s.onSignal);
+	process.removeListener("exit", s.onExit);
+}
+/**
+* Stop `entry` if the process ends before it is unregistered. Registering the
+* same entry twice is a no-op. Returns the unregister function for the
+* orderly path; once nothing is registered the process listeners are removed.
+*/
+function registerProcessCleanup(entry) {
+	const s = state();
+	s.entries.add(entry);
+	hook(s);
+	return () => unregisterProcessCleanup(entry);
+}
+function unregisterProcessCleanup(entry) {
+	const s = state();
+	s.entries.delete(entry);
+	if (s.entries.size === 0) unhook(s);
+}
+export { unregisterProcessCleanup as n, registerProcessCleanup as t };