pgserve 1.1.10 → 2.0.0

package/src/gc.js

@@ -0,0 +1,351 @@
+/**
+ * pgserve GC — 3-layer lifecycle sweep (Group 5).
+ *
+ * Decides which user databases to reap based on:
+ *   1. `persist=true` — exempt from GC, audited as `db_persist_honored`.
+ *   2. Liveness — if `liveness_pid` points at a running process, slide
+ *      `last_connection_at` forward to "now" (the peer is alive, the row is
+ *      a heartbeat) and never reap.
+ *   3. TTL — peer is gone AND `now - last_connection_at > ttlMs` (default
+ *      24h) → `DROP DATABASE`, delete the meta row, audit reap event.
+ *
+ * Audit reap event is `db_reaped_liveness` when the row had a non-null
+ * liveness_pid that is now dead, otherwise `db_reaped_ttl` (the row never
+ * registered a liveness_pid — pure idle expiry).
+ *
+ * `installSweepTriggers(daemon, …)` wires the three call sites:
+ *   - boot: a single sweep right after the daemon is listening, with a
+ *     summary log line so operators see GC activity at startup.
+ *   - hourly `setInterval` (configurable via `intervalMs`).
+ *   - on-connect sampling: subscribe to the daemon's `'accept'` event and
+ *     fire `gcSweep` async at rate 1/N where `N = max(1, dbCount/10)`. The
+ *     listener never awaits the sweep, so accept latency is unaffected.
+ */
+
+import { audit, AUDIT_EVENTS } from './audit.js';
+import { forEachReapable, deleteMetaRow, touchLastConnection } from './control-db.js';
+
+const TTL_MS_DEFAULT = 24 * 60 * 60 * 1000;
+const HOURLY_MS = 60 * 60 * 1000;
+
+/**
+ * Default liveness probe — POSIX `kill(pid, 0)` returns 0 if the process is
+ * alive, throws ESRCH if gone, EPERM if owned by another user (still alive).
+ *
+ * @param {number|null|undefined} pid
+ * @returns {boolean}
+ */
+function defaultIsProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * @typedef {object} GcSweepOptions
+ * @property {{query: Function}} adminClient — pgserve admin DB connection
+ * @property {{adminPool: any, createdDatabases?: Set<string>}} [pgManager] —
+ *   optional; used to evict from the in-process createdDatabases cache after
+ *   a successful DROP. Tests can omit; gcSweep always falls back to the
+ *   adminClient's `query()` for the actual DROP.
+ * @property {number|Date} [now]
+ * @property {number} [ttlMs] — defaults to 24h
+ * @property {boolean} [dryRun] — when true, never DROP / DELETE / audit reap
+ * @property {(pid: number|null|undefined) => boolean} [isProcessAlive]
+ * @property {{warn?: Function, info?: Function, error?: Function, debug?: Function}} [logger]
+ */
+
+/**
+ * @typedef {object} GcSweepResult
+ * @property {number} examined
+ * @property {number} reaped
+ * @property {number} kept
+ * @property {number} persistSkipped
+ * @property {number} aliveSkipped
+ * @property {string[]} reapedNames
+ */
+
+/**
+ * Run one GC sweep. Returns counts so callers can log a summary or assert
+ * in tests.
+ *
+ * @param {GcSweepOptions} opts
+ * @returns {Promise<GcSweepResult>}
+ */
+export async function gcSweep({
+  adminClient,
+  pgManager = null,
+  now = new Date(),
+  ttlMs = TTL_MS_DEFAULT,
+  dryRun = false,
+  isProcessAlive = defaultIsProcessAlive,
+  logger,
+} = {}) {
+  if (!adminClient) throw new Error('gcSweep: adminClient required');
+
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(nowMs)) throw new Error('gcSweep: now must be Date or numeric ms');
+
+  const result = {
+    examined: 0,
+    reaped: 0,
+    kept: 0,
+    persistSkipped: 0,
+    aliveSkipped: 0,
+    reapedNames: [],
+  };
+
+  // Snapshot so we don't iterate while we DELETE — pg's async iterator
+  // protocols vary across drivers, but materialising 240 rows is cheap and
+  // sidesteps any cursor-vs-DELETE quirks.
+  const candidates = [];
+  for await (const row of forEachReapable(adminClient)) {
+    candidates.push(row);
+  }
+
+  for (const row of candidates) {
+    result.examined += 1;
+
+    // Persist=true rows never appear from forEachReapable (the query filters
+    // them out), but if the schema changes that contract we still defend
+    // here — and emit the audit event the wish promises.
+    if (row.persist) {
+      result.persistSkipped += 1;
+      result.kept += 1;
+      if (!dryRun) {
+        audit(AUDIT_EVENTS.DB_PERSIST_HONORED, {
+          database: row.databaseName,
+          fingerprint: row.fingerprint,
+        });
+      }
+      continue;
+    }
+
+    const livenessPid = row.livenessPid;
+    const hadLivenessPid = Number.isInteger(livenessPid) && livenessPid > 0;
+    const alive = hadLivenessPid && isProcessAlive(livenessPid);
+
+    if (alive) {
+      result.aliveSkipped += 1;
+      result.kept += 1;
+      if (!dryRun) {
+        // Slide the window: an alive process means the row is effectively
+        // current, even if the pgserve_meta last_connection_at value lags.
+        try {
+          await touchLastConnection(adminClient, {
+            databaseName: row.databaseName,
+            livenessPid,
+          });
+        } catch (err) {
+          logger?.warn?.(
+            { err: err?.message || String(err), database: row.databaseName },
+            'gcSweep: touchLastConnection failed for live row (non-fatal)',
+          );
+        }
+      }
+      continue;
+    }
+
+    const lastMs = row.lastConnectionAt instanceof Date
+      ? row.lastConnectionAt.getTime()
+      : Number(row.lastConnectionAt);
+    const ageMs = Number.isFinite(lastMs) ? nowMs - lastMs : Infinity;
+
+    if (ageMs <= ttlMs) {
+      result.kept += 1;
+      continue;
+    }
+
+    if (dryRun) {
+      result.reaped += 1;
+      result.reapedNames.push(row.databaseName);
+      continue;
+    }
+
+    try {
+      await dropDatabaseSafely(adminClient, row.databaseName, logger);
+      pgManager?.createdDatabases?.delete(row.databaseName);
+      await deleteMetaRow(adminClient, row.databaseName);
+      const reapEvent = hadLivenessPid
+        ? AUDIT_EVENTS.DB_REAPED_LIVENESS
+        : AUDIT_EVENTS.DB_REAPED_TTL;
+      audit(reapEvent, {
+        database: row.databaseName,
+        fingerprint: row.fingerprint,
+        last_connection_at: row.lastConnectionAt instanceof Date
+          ? row.lastConnectionAt.toISOString()
+          : row.lastConnectionAt,
+        liveness_pid: livenessPid ?? null,
+        age_ms: Number.isFinite(ageMs) ? ageMs : null,
+      });
+      result.reaped += 1;
+      result.reapedNames.push(row.databaseName);
+    } catch (err) {
+      logger?.error?.(
+        { err: err?.message || String(err), database: row.databaseName },
+        'gcSweep: failed to reap database',
+      );
+    }
+  }
+
+  return result;
+}
+
+async function dropDatabaseSafely(adminClient, databaseName, logger) {
+  const escaped = `"${databaseName.replace(/"/g, '""')}"`;
+  // Terminate any lingering backends so DROP DATABASE doesn't refuse with
+  // 55006 (object_in_use). The peer's pgserve daemon socket is already gone
+  // (liveness dead) but Postgres can hold idle backends a while longer.
+  try {
+    await adminClient.query(
+      `SELECT pg_terminate_backend(pid)
+       FROM pg_stat_activity
+       WHERE datname = $1 AND pid <> pg_backend_pid()`,
+      [databaseName],
+    );
+  } catch (err) {
+    logger?.debug?.(
+      { err: err?.message || String(err), database: databaseName },
+      'gcSweep: pg_terminate_backend failed (non-fatal)',
+    );
+  }
+  await adminClient.query(`DROP DATABASE IF EXISTS ${escaped}`);
+}
+
+/**
+ * Wire the three sweep call sites onto a running daemon.
+ *
+ * Returns a `{stop()}` handle so tests (and `daemon.stop()`) can detach.
+ *
+ * @param {object} daemon — PgserveDaemon instance
+ * @param {object} [opts]
+ * @param {{query: Function}} [opts.adminClient] — defaults to daemon._adminClient
+ * @param {number} [opts.intervalMs] — hourly default; pass 0 to disable
+ * @param {number} [opts.ttlMs]
+ * @param {(pid: number) => boolean} [opts.isProcessAlive]
+ * @param {() => Promise<number>|number} [opts.getDbCount] — defaults to a
+ *   COUNT(*) query against pgserve_meta
+ * @param {boolean} [opts.bootSweep=true]
+ * @returns {{stop: () => Promise<void>, sweep: () => Promise<GcSweepResult>}}
+ */
+export function installSweepTriggers(daemon, opts = {}) {
+  const adminClient = opts.adminClient || daemon._adminClient;
+  if (!adminClient) {
+    throw new Error('installSweepTriggers: daemon has no admin client');
+  }
+  const intervalMs = opts.intervalMs == null ? HOURLY_MS : opts.intervalMs;
+  const ttlMs = opts.ttlMs == null ? TTL_MS_DEFAULT : opts.ttlMs;
+  const logger = daemon.logger;
+  const pgManager = daemon.pgManager;
+  const isProcessAlive = opts.isProcessAlive || defaultIsProcessAlive;
+  const getDbCount = opts.getDbCount || (async () => {
+    try {
+      const r = await adminClient.query('SELECT count(*)::int AS n FROM pgserve_meta');
+      return r.rows?.[0]?.n ?? 0;
+    } catch {
+      return 0;
+    }
+  });
+
+  let stopped = false;
+  let inflight = false;
+  let lastDbCount = 0;
+
+  const runSweep = async () => {
+    if (stopped) return null;
+    if (inflight) return null;
+    inflight = true;
+    try {
+      const res = await gcSweep({
+        adminClient,
+        pgManager,
+        now: new Date(),
+        ttlMs,
+        isProcessAlive,
+        logger,
+      });
+      lastDbCount = Math.max(0, lastDbCount - res.reaped);
+      return res;
+    } catch (err) {
+      logger?.error?.(
+        { err: err?.message || String(err) },
+        'gcSweep failed',
+      );
+      return null;
+    } finally {
+      inflight = false;
+    }
+  };
+
+  let timer = null;
+  if (intervalMs > 0) {
+    timer = setInterval(() => {
+      void runSweep();
+    }, intervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  const acceptListener = () => {
+    // Sample 1/N where N = max(1, ceil(dbCount/10)). Always async and
+    // detached so accept latency isn't blocked.
+    const n = Math.max(1, Math.ceil(lastDbCount / 10));
+    if (n === 1 || Math.random() * n < 1) {
+      setImmediate(() => {
+        if (stopped) return;
+        // Refresh count opportunistically before each sweep so on-connect
+        // sampling tracks the live row count without polling.
+        Promise.resolve(getDbCount())
+          .then((c) => { lastDbCount = Number(c) || 0; })
+          .then(runSweep)
+          .catch(() => { /* swallowed by runSweep */ });
+      });
+    }
+  };
+  daemon.on?.('accept', acceptListener);
+
+  const handle = {
+    sweep: runSweep,
+    async stop() {
+      stopped = true;
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      daemon.off?.('accept', acceptListener);
+    },
+  };
+
+  if (opts.bootSweep !== false) {
+    // Boot sweep + count refresh + summary log. Detached so we don't block
+    // start() — the daemon is already listening at this point.
+    setImmediate(async () => {
+      try {
+        lastDbCount = Number(await getDbCount()) || 0;
+        const res = await runSweep();
+        if (res) {
+          logger?.info?.(
+            {
+              examined: res.examined,
+              reaped: res.reaped,
+              kept: res.kept,
+              persist_skipped: res.persistSkipped,
+              alive_skipped: res.aliveSkipped,
+            },
+            'pgserve GC: boot sweep complete',
+          );
+        }
+      } catch (err) {
+        logger?.warn?.(
+          { err: err?.message || String(err) },
+          'pgserve GC: boot sweep failed',
+        );
+      }
+    });
+  }
+
+  return handle;
+}

package/src/index.js

@@ -13,6 +13,17 @@ export { RestoreManager } from './restore.js';
 export { Dashboard } from './dashboard.js';
 export { StatsCollector } from './stats-collector.js';
 export { StatsDashboard } from './stats-dashboard.js';
+export {
+  PgserveDaemon,
+  startDaemon,
+  stopDaemon,
+  resolveControlSocketDir,
+  resolveControlSocketPath,
+  resolvePidLockPath,
+  resolveLibpqCompatPath,
+  acquirePidLock,
+  isProcessAlive,
+} from './daemon.js';
 
 // Default export
 export { startMultiTenantServer as default } from './router.js';

package/src/postgres.js

@@ -444,8 +444,20 @@ export class PostgresManager {
 
   /**
    * Start the embedded PostgreSQL instance
+   *
+   * Re-entry guard: if a previous start() left `this.process` or stale state
+   * behind, refuse silently rather than leaking another socketDir/databaseDir.
+   * Callers must call stop() first if they want to restart.
    */
   async start() {
+    if (this.process) {
+      this.logger?.warn(
+        { pid: this.process.pid, socketDir: this.socketDir },
+        'PostgresManager.start() called while already started — returning existing instance'
+      );
+      return this;
+    }
+
     // Get binary paths (may extract bundled binaries on first run)
     this.binaries = await getBinaryPaths();
 
@@ -773,12 +785,33 @@ export class PostgresManager {
       readStream(this.process.stdout);
 
       // Handle process exit
+      //
+      // When the postgres subprocess exits (normal stop OR crash), we must
+      // null `this.process` AND `this.socketDir`/`this.databaseDir` so that
+      // subsequent `getSocketPath()` calls do not return a path to a directory
+      // that no longer exists. This is the issue #24 root cause: the router
+      // was receiving stale socketPaths pointing to cleaned-up tmp dirs.
+      //
+      // NOTE: we do NOT null socketDir here if `stop()` is in flight, because
+      // stop() already handles cleanup+null. We only need to self-heal when
+      // the exit is unexpected (external kill, crash, OOM).
       this.process.exited.then((code) => {
         processExited = true;
         if (!started) {
           reject(new Error(`PostgreSQL exited with code ${code} before starting: ${startupOutput}`));
         }
         this.process = null;
+        // On unexpected exit (not via stop()), reset cached paths so that
+        // getSocketPath() returns null and callers can fall back to TCP
+        // or force a fresh start().
+        if (!this._stopping) {
+          this.socketDir = null;
+          this.databaseDir = null;
+          this.logger?.warn(
+            { code },
+            'PostgreSQL subprocess exited unexpectedly — socketDir/databaseDir reset'
+          );
+        }
       });
 
       // Method 1: TCP connection polling (preferred, works on Linux/macOS)
@@ -1294,8 +1327,19 @@ export class PostgresManager {
 
   /**
    * Stop the PostgreSQL instance
+   *
+   * Cleanup order matters: we null `this.socketDir`/`this.databaseDir` AFTER
+   * the rmSync so any concurrent `getSocketPath()` call either sees the old
+   * path (while it still exists) or null (after cleanup) — never a path
+   * pointing to a deleted directory.
+   *
+   * The `_stopping` flag tells the process.exited handler to NOT redundantly
+   * null the paths (avoids a race where start() called immediately after
+   * stop() sees nulls that stop() was about to set anyway).
    */
   async stop() {
+    this._stopping = true;
+
     // Close admin pool first (Bun.sql)
     if (this.adminPool) {
       await this.adminPool.close();
@@ -1340,6 +1384,16 @@ export class PostgresManager {
         }
       }
     }
+
+    // Reset cached paths UNCONDITIONALLY after cleanup so getSocketPath()
+    // returns null for anyone still holding a reference to this instance.
+    // This is the core fix for issue #24.
+    this.socketDir = null;
+    if (!this.persistent) {
+      this.databaseDir = null;
+    }
+    this.createdDatabases.clear();
+    this._stopping = false;
   }
 
   /**

package/src/protocol.js

@@ -133,6 +133,137 @@ export function extractDatabaseName(data) {
   }
 }
 
+/**
+ * Extract `application_name` from a startup message buffer. Returns null when
+ * absent or when the buffer is malformed (callers fall back to no-auth).
+ *
+ * @param {Buffer} data
+ * @returns {string|null}
+ */
+export function extractApplicationName(data) {
+  try {
+    const params = parseStartupMessage(data, /* fastPath */ false);
+    return typeof params.application_name === 'string' ? params.application_name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return a new startup-message buffer with the `database` parameter replaced
+ * by `newDbName`. All other parameters (and their order) are preserved by
+ * default; pass `dropParams: ['application_name', ...]` to strip noisy
+ * fields the daemon would rather not forward to PG verbatim. The 4-byte
+ * length prefix at the start of the buffer is recomputed.
+ *
+ * Group 6 uses this on TCP-authenticated connections so a peer that presents
+ * a token for fingerprint X is forced into fingerprint X's database, even
+ * if the libpq client requested a different one.
+ *
+ * @param {Buffer} data — original startup message
+ * @param {string} newDbName
+ * @param {{dropParams?: string[]}} [opts]
+ * @returns {Buffer}
+ */
+export function rewriteDatabaseName(data, newDbName, opts = {}) {
+  if (!Buffer.isBuffer(data)) throw new Error('rewriteDatabaseName: buffer required');
+  if (typeof newDbName !== 'string' || newDbName.length === 0) {
+    throw new Error('rewriteDatabaseName: non-empty newDbName required');
+  }
+  const length = data.readInt32BE(0);
+  const version = data.readInt32BE(4);
+  const drop = new Set(opts.dropParams || []);
+
+  // Walk parameters; build a list of (key, value) pairs replacing 'database'.
+  const pairs = [];
+  let offset = 8;
+  let sawDatabase = false;
+  while (offset < length - 1) {
+    const keyEnd = data.indexOf(0, offset);
+    if (keyEnd === -1 || keyEnd >= length) break;
+    const key = data.toString('utf8', offset, keyEnd);
+    offset = keyEnd + 1;
+    const valueEnd = data.indexOf(0, offset);
+    if (valueEnd === -1 || valueEnd >= length) break;
+    const value = data.toString('utf8', offset, valueEnd);
+    offset = valueEnd + 1;
+    if (drop.has(key)) continue;
+    if (key === 'database') {
+      pairs.push(['database', newDbName]);
+      sawDatabase = true;
+    } else {
+      pairs.push([key, value]);
+    }
+  }
+  if (!sawDatabase) pairs.push(['database', newDbName]);
+
+  // Compute new buffer size: 4 (length) + 4 (version) + sum(key+1 + value+1) + 1 (terminator).
+  let bodyLen = 0;
+  for (const [k, v] of pairs) {
+    bodyLen += Buffer.byteLength(k, 'utf8') + 1 + Buffer.byteLength(v, 'utf8') + 1;
+  }
+  const total = 4 + 4 + bodyLen + 1;
+  const out = Buffer.alloc(total);
+  out.writeInt32BE(total, 0);
+  out.writeInt32BE(version, 4);
+  let cur = 8;
+  for (const [k, v] of pairs) {
+    cur += out.write(k, cur, 'utf8');
+    out[cur++] = 0;
+    cur += out.write(v, cur, 'utf8');
+    out[cur++] = 0;
+  }
+  out[cur++] = 0; // final terminator
+  return out;
+}
+
+/**
+ * Build a PostgreSQL ErrorResponse (`'E'`) frame.
+ *
+ * Used by the daemon to reject cross-fingerprint connection attempts
+ * with SQLSTATE `28P01 invalid_authorization_specification` before the
+ * peer's startup message ever reaches the underlying PG instance.
+ *
+ * Frame layout (PG protocol v3):
+ *   'E' (1 byte) | length (4 bytes, includes itself) | <fields...> | '\0'
+ *
+ * Each field: type-byte | utf8 string | '\0'
+ * Required fields per PG docs: 'S' (Severity), 'C' (SQLSTATE), 'M' (Message).
+ * 'V' (localized severity, server >= 9.6) is included for parity with the
+ * frames real Postgres emits — psql / pg drivers parse both transparently.
+ *
+ * @param {{severity?: string, sqlstate: string, message: string}} args
+ * @returns {Buffer}
+ */
+export function buildErrorResponse({ severity = 'FATAL', sqlstate, message }) {
+  if (typeof sqlstate !== 'string' || sqlstate.length !== 5) {
+    throw new TypeError('buildErrorResponse: sqlstate must be a 5-character string');
+  }
+  if (typeof message !== 'string' || message.length === 0) {
+    throw new TypeError('buildErrorResponse: message must be a non-empty string');
+  }
+  const field = (typeChar, value) => {
+    const valBytes = Buffer.byteLength(value, 'utf8');
+    const buf = Buffer.alloc(1 + valBytes + 1);
+    buf.writeUInt8(typeChar.charCodeAt(0), 0);
+    buf.write(value, 1, 'utf8');
+    buf.writeUInt8(0, 1 + valBytes);
+    return buf;
+  };
+  const body = Buffer.concat([
+    field('S', severity),
+    field('V', severity),
+    field('C', sqlstate),
+    field('M', message),
+    Buffer.from([0]),
+  ]);
+  const frameLength = 4 + body.length;
+  const header = Buffer.alloc(5);
+  header.writeUInt8(0x45, 0); // 'E'
+  header.writeUInt32BE(frameLength, 1);
+  return Buffer.concat([header, body]);
+}
+
 // Pre-allocated buffer pool for startup message parsing (avoids allocation per connection)
 const STARTUP_BUFFER_SIZE = 8192; // Max startup message is typically < 1KB
 const bufferPool = [];