pgserve 2.3.0 → 2.4.0

package/src/postgres.js

@@ -548,6 +548,15 @@ export class PostgresManager extends EventEmitter {
     this.binaries = null;
     this.creatingDatabases = new Map(); // Track in-progress creations
     this.socketDir = null; // Unix socket directory for faster local connections
+    // pgserve singleton (v2.4): callers that own the socket directory (e.g.
+    // `pgserve postmaster` invoked under pm2 or a systemd-user unit) pass an
+    // explicit, externally-managed path so libpq peers connecting via
+    // `psql -h $XDG_RUNTIME_DIR/pgserve` reach a stable, well-known socket.
+    // When unset we fall back to the legacy per-pid `os.tmpdir()` path so
+    // foreground / daemon / cluster modes keep working unchanged.
+    this.explicitSocketDir = typeof options.socketDir === 'string' && options.socketDir.length > 0
+      ? options.socketDir
+      : null;
     this.adminPool = null; // Connection pool for database admin operations
     this.useRam = options.useRam || false; // Use /dev/shm for true RAM storage (Linux only)
     this.isTrueRam = false; // Tracks if we're actually using RAM storage
@@ -634,9 +643,24 @@ export class PostgresManager extends EventEmitter {
 
     // Create Unix socket directory (Linux/macOS only, Windows uses TCP)
     if (os.platform() !== 'win32') {
-      this.socketDir = path.join(os.tmpdir(), `pgserve-sock-${process.pid}-${Date.now()}`);
-      if (!fs.existsSync(this.socketDir)) {
-        fs.mkdirSync(this.socketDir, { recursive: true, mode: 0o700 });
+      if (this.explicitSocketDir) {
+        // pgserve singleton (v2.4): operator-supplied socket dir is created
+        // and chmoded by the install path (`pgserve install`); we only
+        // refuse to start when it doesn't exist so the operator's intent
+        // surfaces cleanly instead of postgres bailing on bind() with a
+        // cryptic libpq error.
+        if (!fs.existsSync(this.explicitSocketDir)) {
+          throw new Error(
+            `pgserve: socketDir does not exist: ${this.explicitSocketDir}. `
+            + `Run \`pgserve install\` to create it (or pass --socket-dir <existing-dir>).`,
+          );
+        }
+        this.socketDir = this.explicitSocketDir;
+      } else {
+        this.socketDir = path.join(os.tmpdir(), `pgserve-sock-${process.pid}-${Date.now()}`);
+        if (!fs.existsSync(this.socketDir)) {
+          fs.mkdirSync(this.socketDir, { recursive: true, mode: 0o700 });
+        }
       }
     }
 
@@ -894,6 +918,33 @@ export class PostgresManager extends EventEmitter {
         ...gucArgs,
       ];
 
+      // pgserve singleton (v2.4): the bun-side audit-log writer is gone.
+      // Audit moves to postgres-native logging — `pgaudit` if the .so is
+      // bundled with the embedded postgres distribution, `log_statement`
+      // as a portable fallback otherwise. The wish ships the contract;
+      // shipping the pgaudit binary is a separate cohort task. Either way
+      // pm2 captures stderr to `<configDir>/logs/autopg-server-error.log`
+      // and `logrotate.d/pgserve` rotates it.
+      const pgauditPath = path.join(this.binaries.libDir, '..', 'lib', 'postgresql', 'pgaudit.so');
+      if (fs.existsSync(pgauditPath)) {
+        pgArgs.push('-c', 'shared_preload_libraries=pgaudit');
+        pgArgs.push('-c', 'pgaudit.log=all');
+        pgArgs.push('-c', 'pgaudit.log_catalog=off');
+        appliedGucs.shared_preload_libraries = 'pgaudit';
+        appliedGucs['pgaudit.log'] = 'all';
+      } else {
+        // Fallback: postgres-native log_statement='all' captures every
+        // query without the pgaudit-specific class taxonomy. Operators
+        // get an audit trail today; the cohort can swap to pgaudit later
+        // by dropping the .so into the embedded-postgres bundle.
+        pgArgs.push('-c', 'log_statement=all');
+        appliedGucs.log_statement = 'all';
+        this.logger?.warn(
+          { pgauditPath },
+          'pgaudit.so not found in embedded postgres lib dir; falling back to log_statement=all for audit',
+        );
+      }
+
       // Enable Unix socket for faster local connections (Linux/macOS)
       // Windows falls back to TCP only
       if (this.socketDir) {
@@ -1574,8 +1625,16 @@ export class PostgresManager extends EventEmitter {
         }
       }
 
-      // Clean up socket directory
-      if (this.socketDir) {
+      // Clean up socket directory.
+      // pgserve singleton (v2.4): when the caller supplied an explicit
+      // socket dir (operator-owned canonical path under
+      // `$XDG_RUNTIME_DIR/pgserve` or `/tmp/pgserve`), the install path
+      // owns the directory's lifecycle — postgres unlinks its own
+      // `.s.PGSQL.<port>` + `.lock` files on graceful shutdown, and
+      // tearing the directory down here would race with operator tooling
+      // (pm2 restarts, doctor --fix, etc.). Only sweep the legacy
+      // per-pid `os.tmpdir()/pgserve-sock-*` form we generated ourselves.
+      if (this.socketDir && !this.explicitSocketDir) {
         try {
           fs.rmSync(this.socketDir, { recursive: true, force: true });
           this.logger.debug({ socketDir: this.socketDir }, 'Cleaned up socket directory');

package/src/admin-client.js

@@ -1,223 +0,0 @@
-/**
- * Admin DB client — small Bun.SQL wrapper exposing the `{query, end}`
- * surface that `src/control-db.js` expects.
- *
- * The daemon and the `pgserve daemon issue-token / revoke-token` CLI
- * subcommands both need a privileged connection to the underlying
- * Postgres instance owned by `PostgresManager`. The pg npm module is
- * a devDependency only (it backs the test harness); rather than promote
- * it to runtime we wrap Bun.SQL — which is shipped with the runtime —
- * in the parameterised-query interface control-db.js documents.
- *
- * Connection target:
- *   - Local Unix socket when `socketDir` is provided (the daemon's
- *     hot path) — drops the bytes onto the kernel-local socket.
- *   - TCP fallback when `socketDir` is null (e.g. CI hosts without
- *     the embedded socket directory present).
- *
- * The CLI side reads the daemon's discovery file at
- * `${controlSocketDir}/admin.json` to learn `{socketDir, port}`.
- */
-
-import { SQL } from 'bun';
-import fs from 'fs';
-import path from 'path';
-
-/**
- * @param {object} args
- * @param {string|null} [args.socketDir] — accepted for parity with the
- *   embedded-postgres callers but unused; Bun.SQL's startup auth path
- *   does not currently traverse `pg_hba.conf` Unix-socket trust rules
- *   against `embedded-postgres`, so we always go TCP for admin work.
- *   Keeping the parameter avoids a churning call-site signature.
- * @param {string} [args.host='127.0.0.1']
- * @param {number} args.port
- * @param {string} [args.database='postgres']
- * @param {string} [args.user='postgres']
- * @param {string} [args.password='postgres']
- * @param {number} [args.max=2]
- * @param {number} [args.idleTimeout=300]
- * @param {number} [args.queryTimeoutMs=0]
- * @returns {Promise<{supportsQueryOptions: boolean, query: (text: string, params?: any[], opts?: {timeoutMs?: number}) => Promise<{rows: any[], rowCount: number}>, end: () => Promise<void>, sql: any}>}
- */
-export async function createAdminClient({
-  socketDir: _socketDir = null,
-  host = '127.0.0.1',
-  port,
-  database = 'postgres',
-  user = 'postgres',
-  password = 'postgres',
-  max = 2,
-  idleTimeout = 300,
-  queryTimeoutMs = 0,
-} = {}) {
-  if (typeof port !== 'number') throw new Error('createAdminClient: port required');
-  const options = {
-    hostname: host,
-    port,
-    database,
-    username: user,
-    password,
-    max,
-    idleTimeout,
-  };
-  let sql = new SQL(options);
-  // Light probe so a misconfigured daemon fails loudly here rather than at
-  // first query.
-  await sql`SELECT 1`;
-
-  async function reopen() {
-    const closing = sql;
-    sql = new SQL(options);
-    void closing.close().catch(() => { /* swallow */ });
-    await sql`SELECT 1`;
-  }
-
-  return {
-    supportsQueryOptions: true,
-    get sql() {
-      return sql;
-    },
-    async query(text, params = [], opts = {}) {
-      // control-db.js is written for the pg npm module's contract, which
-      // requires JSON-stringified payloads bound to JSONB parameters.
-      // Bun.SQL goes the other way: it stringifies JS objects when they
-      // hit JSONB columns, but a JS string headed for `::jsonb` is sent
-      // as a JSON string literal (i.e. `"\"..."\"` rather than the array
-      // it represents). Bridge the impedance mismatch here so the same
-      // call sites work against either driver.
-      const adapted = params.map(coerceJsonbParam);
-      const timeoutMs = opts.timeoutMs ?? queryTimeoutMs;
-      try {
-        return await runQueryWithTimeout(sql, text, adapted, timeoutMs);
-      } catch (err) {
-        if (!isRetriableAdminQueryError(err)) throw err;
-        await reopen();
-        return await runQueryWithTimeout(sql, text, adapted, timeoutMs);
-      }
-    },
-    async end() {
-      try { await sql.close(); } catch { /* swallow */ }
-    },
-  };
-}
-
-async function runQueryWithTimeout(sql, text, params, queryTimeoutMs) {
-  const query = runQuery(sql, text, params);
-  return withTimeout(query, queryTimeoutMs);
-}
-
-async function runQuery(sql, text, params) {
-  const rows = await sql.unsafe(text, params);
-  // Bun returns an Array of plain objects with `count` set on it; turn
-  // JSONB columns back into JS values so control-db.js's parseTokens
-  // sees the array-of-objects shape it would receive from pg.
-  const out = Array.from(rows).map(decodeJsonColumns);
-  return { rows: out, rowCount: rows.count ?? rows.length ?? 0 };
-}
-
-function withTimeout(promise, timeoutMs) {
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return promise;
-  let timer;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => {
-      const err = new Error(`admin query timed out after ${timeoutMs}ms`);
-      err.code = 'EADMINQUERYTIMEOUT';
-      reject(err);
-    }, timeoutMs);
-    timer.unref?.();
-  });
-  promise.catch(() => { /* handled by the race winner */ });
-  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
-
-function isRetriableAdminQueryError(err) {
-  const code = err?.code;
-  if (['EADMINQUERYTIMEOUT', 'ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'ConnectionClosed'].includes(code)) return true;
-  const message = err?.message || String(err);
-  return /connection (?:closed|terminated|reset)|socket closed|timeout|CONNECTION_ENDED|CONNECTION_DESTROYED/i.test(message);
-}
-
-/**
- * Strings shaped like a JSON array or object are unwrapped so Bun.SQL's
- * automatic JSONB serialiser sees the JS value (not a quoted JSON string).
- * Anything else is passed through untouched. This mirrors what node-pg
- * does implicitly when the column type is JSONB.
- */
-function coerceJsonbParam(p) {
-  if (typeof p !== 'string') return p;
-  const trimmed = p.trim();
-  if (trimmed.length === 0) return p;
-  const first = trimmed[0];
-  if (first !== '[' && first !== '{') return p;
-  try {
-    return JSON.parse(p);
-  } catch {
-    return p;
-  }
-}
-
-/**
- * Bun.SQL returns JSONB values as the JSON text rather than parsed JS.
- * Re-parse the obvious cases so callers expecting node-pg's auto-decoded
- * shape get arrays/objects.
- */
-function decodeJsonColumns(row) {
-  const out = {};
-  for (const key of Object.keys(row)) {
-    const v = row[key];
-    if (typeof v === 'string' && (v.startsWith('[') || v.startsWith('{'))) {
-      try { out[key] = JSON.parse(v); } catch { out[key] = v; }
-    } else {
-      out[key] = v;
-    }
-  }
-  return out;
-}
-
-/**
- * Daemon-side: write a small JSON file that issue-token / revoke-token
- * subcommands read to find the admin socket.
- *
- * @param {object} args
- * @param {string} args.controlSocketDir
- * @param {string|null} args.socketDir — PG socket directory (nullable on Windows)
- * @param {number} args.port
- * @returns {string} the absolute path to the discovery file
- */
-export function writeAdminDiscovery({ controlSocketDir, socketDir, port }) {
-  const file = path.join(controlSocketDir, 'admin.json');
-  const payload = {
-    socketDir,
-    port,
-    host: socketDir ? null : '127.0.0.1',
-    pid: process.pid,
-    written_at: new Date().toISOString(),
-  };
-  fs.writeFileSync(file, JSON.stringify(payload), { mode: 0o600 });
-  return file;
-}
-
-/**
- * CLI-side: read the daemon's discovery file.
- *
- * @param {string} controlSocketDir
- * @returns {{socketDir: string|null, port: number, host: string|null}}
- */
-export function readAdminDiscovery(controlSocketDir) {
-  const file = path.join(controlSocketDir, 'admin.json');
-  const raw = fs.readFileSync(file, 'utf8');
-  return JSON.parse(raw);
-}
-
-/**
- * CLI-side: best-effort cleanup at daemon shutdown.
- *
- * @param {string} controlSocketDir
- */
-export function removeAdminDiscovery(controlSocketDir) {
-  const file = path.join(controlSocketDir, 'admin.json');
-  try { fs.unlinkSync(file); } catch (e) {
-    if (e.code !== 'ENOENT') throw e;
-  }
-}

package/src/audit.js

@@ -1,168 +0,0 @@
-/**
- * pgserve audit log — JSONL writer with in-process rotation + syslog tier.
- *
- * Tier 1 (default): `~/.pgserve/audit.log`, rotated 50 MB × 5 files.
- * Tier 2 (opt-in):  local syslog via `logger -t pgserve-audit`, one spawn per event.
- * Tier 3 (HTTP webhook): deferred to v2.1.
- *
- * Configuration source-of-truth is the active package.json's
- * `pgserve.audit.target` field; the daemon (Group 3) resolves it per peer
- * and threads the value through `audit(event, fields, { target })`.
- *
- * The event names defined for v2.0 (one row per audit() call):
- *   db_created
- *   db_reaped_ttl
- *   db_reaped_liveness
- *   db_persist_honored
- *   connection_routed
- *   connection_denied_fingerprint_mismatch
- *   enforcement_kill_switch_used
- *   tcp_token_issued
- *   tcp_token_used
- *   tcp_token_denied
- */
-
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import { spawn } from 'child_process';
-
-export const AUDIT_EVENTS = Object.freeze({
-  DB_CREATED: 'db_created',
-  DB_REAPED_TTL: 'db_reaped_ttl',
-  DB_REAPED_LIVENESS: 'db_reaped_liveness',
-  DB_PERSIST_HONORED: 'db_persist_honored',
-  CONNECTION_ROUTED: 'connection_routed',
-  CONNECTION_DENIED_FINGERPRINT_MISMATCH: 'connection_denied_fingerprint_mismatch',
-  ENFORCEMENT_KILL_SWITCH_USED: 'enforcement_kill_switch_used',
-  TCP_TOKEN_ISSUED: 'tcp_token_issued',
-  TCP_TOKEN_USED: 'tcp_token_used',
-  TCP_TOKEN_DENIED: 'tcp_token_denied',
-});
-
-const VALID_EVENTS = new Set(Object.values(AUDIT_EVENTS));
-
-const ROTATE_THRESHOLD_BYTES = 50 * 1024 * 1024; // 50 MB
-const ROTATE_KEEP = 5;
-
-let DEFAULT_LOG_DIR = path.join(os.homedir(), '.pgserve');
-let DEFAULT_LOG_PATH = path.join(DEFAULT_LOG_DIR, 'audit.log');
-let DEFAULT_TARGET = process.env.PGSERVE_AUDIT_TARGET || 'file';
-
-/**
- * Override the default log path. Used by tests and by the daemon if it
- * needs to redirect audit output (e.g. when XDG_DATA_HOME is set).
- *
- * @param {{logFile?: string, target?: 'file'|'syslog'}} cfg
- */
-export function configureAudit(cfg = {}) {
-  if (cfg.logFile) {
-    DEFAULT_LOG_PATH = cfg.logFile;
-    DEFAULT_LOG_DIR = path.dirname(cfg.logFile);
-  }
-  if (cfg.target) {
-    DEFAULT_TARGET = cfg.target;
-  }
-}
-
-/**
- * Read pgserve.audit.target from a package.json (returns 'file' if absent).
- * Group 3 calls this per-peer once it has resolved the peer's package.json.
- *
- * @param {string} packageJsonPath
- * @returns {'file'|'syslog'}
- */
-export function readAuditTarget(packageJsonPath) {
-  try {
-    const raw = fs.readFileSync(packageJsonPath, 'utf8');
-    const pkg = JSON.parse(raw);
-    const target = pkg?.pgserve?.audit?.target;
-    if (target === 'syslog') return 'syslog';
-    return 'file';
-  } catch {
-    return 'file';
-  }
-}
-
-/**
- * Write one audit event.
- *
- * @param {string} event — one of AUDIT_EVENTS values
- * @param {Record<string, unknown>} [fields] — event-specific payload
- * @param {object} [opts]
- * @param {'file'|'syslog'} [opts.target]
- * @param {string} [opts.logFile]
- */
-export function audit(event, fields = {}, opts = {}) {
-  if (!VALID_EVENTS.has(event)) {
-    throw new Error(`audit: unknown event "${event}". Allowed: ${[...VALID_EVENTS].join(', ')}`);
-  }
-  const record = {
-    ts: new Date().toISOString(),
-    event,
-    ...fields,
-  };
-  const line = JSON.stringify(record);
-  const target = opts.target || DEFAULT_TARGET;
-
-  if (target === 'syslog') {
-    writeSyslog(line);
-    return;
-  }
-  writeFile(line, opts.logFile || DEFAULT_LOG_PATH);
-}
-
-function writeFile(line, logFile) {
-  const dir = path.dirname(logFile);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  }
-  rotateIfNeeded(logFile, Buffer.byteLength(line, 'utf8') + 1 /* newline */);
-  fs.appendFileSync(logFile, line + '\n', { mode: 0o600 });
-}
-
-function rotateIfNeeded(logFile, incomingBytes) {
-  let size = 0;
-  try {
-    size = fs.statSync(logFile).size;
-  } catch {
-    return; // file does not exist yet
-  }
-  if (size + incomingBytes <= ROTATE_THRESHOLD_BYTES) return;
-
-  // Cascade .N → .(N+1), drop the eldest.
-  const oldest = `${logFile}.${ROTATE_KEEP}`;
-  if (fs.existsSync(oldest)) {
-    fs.unlinkSync(oldest);
-  }
-  for (let i = ROTATE_KEEP - 1; i >= 1; i--) {
-    const src = `${logFile}.${i}`;
-    const dst = `${logFile}.${i + 1}`;
-    if (fs.existsSync(src)) fs.renameSync(src, dst);
-  }
-  fs.renameSync(logFile, `${logFile}.1`);
-}
-
-function writeSyslog(line) {
-  // logger -t <tag> is POSIX-standard; spawn detached, do not block.
-  // Stderr/stdout discarded — audit must never throw at call sites.
-  try {
-    const child = spawn('logger', ['-t', 'pgserve-audit', line], {
-      stdio: 'ignore',
-      detached: false,
-    });
-    child.on('error', () => { /* logger missing — swallow */ });
-  } catch {
-    // ENOENT / EACCES — swallow; audit must never break the daemon.
-  }
-}
-
-/**
- * Internal: expose rotation constants so tests can drive coverage cleanly
- * without depending on actual 50 MB writes.
- */
-export const _internals = Object.freeze({
-  ROTATE_THRESHOLD_BYTES,
-  ROTATE_KEEP,
-  rotateIfNeeded,
-});