@effectstream/db 0.200.5 → 0.300.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/db",
-  "version": "0.200.5",
+  "version": "0.300.0",
   "license": "(MIT OR Apache-2.0)",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -21,11 +21,11 @@
     "./version": "./migrations/system-version.ts"
   },
   "dependencies": {
-    "@effectstream/coroutine": "0.200.5",
-    "@effectstream/log": "0.200.5",
-    "@effectstream/runtime": "0.200.5",
-    "@effectstream/sync": "0.200.5",
-    "@effectstream/utils": "0.200.5",
+    "@effectstream/coroutine": "0.300.0",
+    "@effectstream/log": "0.300.0",
+    "@effectstream/runtime": "0.300.0",
+    "@effectstream/sync": "0.300.0",
+    "@effectstream/utils": "0.300.0",
     "@electric-sql/pglite": "^0.3.14",
     "@pgtyped/runtime": "2.4.2",
     "@pgtyped/parser": "2.4.2",

package/src/snapshot-handler.ts

@@ -7,7 +7,7 @@ import {
   statMtime,
 } from "@effectstream/utils/fs";
 import { spawnOutput } from "@effectstream/utils/runtime-spawn";
-import { sleep, until, type Operation } from "effection";
+import { ensure, sleep, until, type Operation } from "effection";
 
 /** `process.env` works under Node, Bun, and Deno (via node: compat). */
 declare const process: { env: Record<string, string | undefined> };
@@ -67,10 +67,15 @@ function resolveSnapshotConfig(config?: SnapshotConfig): ResolvedSnapshotConfig
  * Creates a database snapshot using `pg_dump` in custom format (`-F c`).
  * Must be called AFTER releasing the DB mutex (pg_dump opens its own connection).
  *
+ * @param signal - optional; aborting it kills the `pg_dump` child. Pass one
+ *   whenever the caller's own lifetime is bounded (see {@link runSnapshotLoop}),
+ *   otherwise a cancelled caller leaves a full dump running unsupervised.
+ *
  * @see docs/home/1000-effectstream-engine/1003-database-snapshots.md
  */
 export async function createSnapshot(
   config?: SnapshotConfig,
+  signal?: AbortSignal,
 ): Promise<void> {
   // pg_dump queries pg_catalog directly; PGlite's catalog may not match the
   // locally-installed pg_dump version, so skip snapshots under PGlite.
@@ -106,6 +111,7 @@ export async function createSnapshot(
     env: { ...ambientEnv, PGPASSWORD: ENV.DB_PW ?? "" },
     stdout: "inherit",
     stderr: "inherit",
+    signal,
   });
   if (!result.success) {
     throw new Error(`[Snapshot] pg_dump failed with exit code ${result.code}`);
@@ -126,15 +132,38 @@ export function* runSnapshotLoop(
   const resolved = resolveSnapshotConfig(snapshotConfig);
   const intervalMs = resolved.intervalSeconds * 1000;
   console.log(`[Snapshot] Loop started (interval ${intervalMs / 1000}s, path ${resolved.path}, cwd ${cwd()})`);
+
+  // A dump is a child process holding its own database connection. `until`
+  // only abandons the promise on cancellation, so without this the loop can be
+  // torn down while `pg_dump` keeps running — the runtime would report a clean
+  // shutdown with a live child still writing.
+  let abortInFlight: (() => void) | undefined;
+  let inFlightExit: Promise<void> | undefined;
+  yield* ensure(function* () {
+    abortInFlight?.();
+    if (inFlightExit) yield* until(inFlightExit);
+  });
+
   while (true) {
     yield* sleep(intervalMs);
     console.log(`[Snapshot] Firing`);
+    const controller = new AbortController();
+    const dump = createSnapshot(resolved, controller.signal);
+    abortInFlight = () => controller.abort();
+    // Settles when the child is gone, however it ended; the rejection is
+    // observed here so abandoning `dump` cannot become an unhandled rejection.
+    inFlightExit = dump.then(() => {}, () => {});
     try {
-      yield* until(createSnapshot(resolved));
+      yield* until(dump);
       console.log(`[Snapshot] Done; sleeping ${intervalMs / 1000}s`);
     } catch (e) {
       console.error("[Snapshot] Failed:", e);
     }
+    // Deliberately not in a `finally`: on cancellation the generator's finally
+    // blocks run BEFORE the `ensure` above, which would clear the handle the
+    // ensure needs to kill the child.
+    abortInFlight = undefined;
+    inFlightExit = undefined;
   }
 }
 

package/test/snapshot-lifecycle.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Reproduction for the snapshot child-process boundary (spec 00031: G6).
+ *
+ * `createSnapshot` shells out to `pg_dump` through `spawnOutput`, which is
+ * awaited with effection's `until`. `until` abandons the promise on
+ * cancellation but nothing kills the process behind it, so halting the runtime
+ * leaves a full database dump running unsupervised.
+ *
+ * A stub `pg_dump` (first on PATH) stands in for the real one so the test needs
+ * no PostgreSQL installation and can observe the child's PID directly.
+ */
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { run, type Task } from "effection";
+import { runSnapshotLoop } from "../src/snapshot-handler.ts";
+
+const ENV_KEYS = ["PATH", "PGLITE", "SNAPSHOT_TEST_PIDFILE"] as const;
+
+let saved: Record<string, string | undefined>;
+let workDir: string;
+let pidFile: string;
+let task: Task<unknown> | undefined;
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitUntil(
+  check: () => boolean,
+  ms: number,
+  label: string,
+): Promise<void> {
+  const end = Date.now() + ms;
+  while (!check()) {
+    if (Date.now() >= end) throw new Error(`${label} not met within ${ms}ms`);
+    await sleep(10);
+  }
+}
+
+function childPid(): number | undefined {
+  if (!existsSync(pidFile)) return undefined;
+  const raw = readFileSync(pidFile, "utf8").trim();
+  const pid = Number(raw);
+  return Number.isFinite(pid) && pid > 0 ? pid : undefined;
+}
+
+beforeEach(() => {
+  saved = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]]));
+  workDir = mkdtempSync(join(tmpdir(), "es-00031-snapshot-"));
+  pidFile = join(workDir, "pg_dump.pid");
+
+  // A stand-in `pg_dump` that announces its PID and then runs long enough for
+  // the test to halt the loop while it is still working.
+  const stub = join(workDir, "pg_dump");
+  writeFileSync(
+    stub,
+    `#!/bin/sh\necho $$ > "${pidFile}"\nexec sleep 30\n`,
+    "utf8",
+  );
+  chmodSync(stub, 0o755);
+
+  process.env.PATH = `${workDir}:${process.env.PATH ?? ""}`;
+  // `createSnapshot` short-circuits under PGLite (pg_dump cannot read its
+  // catalog), so the scenario under test is the server-backed one.
+  process.env.PGLITE = "false";
+});
+
+afterEach(async () => {
+  if (task) {
+    await Promise.race([task.halt().catch(() => {}), sleep(2_000)]);
+    task = undefined;
+  }
+  const pid = childPid();
+  if (pid !== undefined && alive(pid)) {
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch { /* already gone */ }
+  }
+  rmSync(workDir, { recursive: true, force: true });
+  for (const key of ENV_KEYS) {
+    const value = saved[key];
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+test("G6: halting the snapshot loop kills the in-flight pg_dump child", async () => {
+  task = run(() =>
+    runSnapshotLoop({
+      intervalSeconds: 0.05,
+      path: join(workDir, "snapshots"),
+    })
+  );
+  void Promise.resolve(task).catch(() => {});
+
+  await waitUntil(() => childPid() !== undefined, 10_000, "pg_dump started");
+  const pid = childPid()!;
+  expect(alive(pid)).toBe(true);
+
+  await task.halt();
+  task = undefined;
+  await sleep(500);
+
+  // The runtime claimed it had shut down while a database dump was still
+  // running with an open connection.
+  expect(alive(pid)).toBe(false);
+}, 30_000);