pgserve 2.3.0 → 2.5.0

package/src/lib/runtime-json.js

@@ -0,0 +1,181 @@
+/**
+ * `<socketDir>/runtime.json` — runtime discovery file owned by the
+ * `autopg serve` postmaster wrapper (cutover wish G19).
+ *
+ * Schema:
+ *   {
+ *     socketDir:     "<absolute path>",
+ *     port:          <integer>,    // postgres TCP port
+ *     pid:           <integer>,    // postmaster pid
+ *     autopgPid:     <integer>,    // `autopg serve` wrapper pid
+ *     schemaVersion: 1
+ *   }
+ *
+ * Cohort contract — there is **no `supervisor` field**. The supervisor
+ * (pm2 / systemd-user / launchd / external) is recorded once at install
+ * time in `~/.autopg/admin.json`. Mixing the two creates a synchronization
+ * problem (which file is authoritative when the postmaster restarts under
+ * a new pid?). `writeRuntimeJson()` rejects records carrying a `supervisor`
+ * key so the contract can't drift via a future copy-paste.
+ *
+ * Lifecycle:
+ *   - `writeRuntimeJson()` after the postmaster greets healthy.
+ *   - `clearRuntimeJson()` on graceful shutdown (SIGTERM / SIGINT).
+ *   - On crash the file is left in place. Consumers detect a stale record
+ *     via `process.kill(record.autopgPid, 0)` (no-signal probe).
+ *
+ * Atomic semantics: write to `<file>.tmp.<pid>`, then `fs.renameSync()`.
+ * Mode 0644 so unprivileged peers can `cat <socketDir>/runtime.json`
+ * without sudo — the file carries no secrets, only public discovery info.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export const RUNTIME_FILE_NAME = 'runtime.json';
+export const RUNTIME_FILE_MODE = 0o644;
+export const RUNTIME_SCHEMA_VERSION = 1;
+
+export function getRuntimeFilePath(socketDir) {
+  if (typeof socketDir !== 'string' || socketDir.length === 0) {
+    throw new TypeError('runtime-json: socketDir must be a non-empty string');
+  }
+  return path.join(socketDir, RUNTIME_FILE_NAME);
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function validateRecord(record) {
+  if (!isPlainObject(record)) {
+    throw new TypeError('runtime-json: record must be an object');
+  }
+  if (typeof record.socketDir !== 'string' || record.socketDir.length === 0) {
+    throw new TypeError('runtime-json: socketDir must be a non-empty string');
+  }
+  if (!Number.isInteger(record.port) || record.port < 1 || record.port > 65535) {
+    throw new TypeError(`runtime-json: port must be an integer in [1, 65535]; got ${record.port}`);
+  }
+  if (!Number.isInteger(record.pid) || record.pid < 1) {
+    throw new TypeError(`runtime-json: pid must be a positive integer; got ${record.pid}`);
+  }
+  if (!Number.isInteger(record.autopgPid) || record.autopgPid < 1) {
+    throw new TypeError(`runtime-json: autopgPid must be a positive integer; got ${record.autopgPid}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(record, 'supervisor')) {
+    throw new TypeError(
+      'runtime-json: refusing to write `supervisor` into runtime.json — that field '
+      + 'lives only in `~/.autopg/admin.json` (cohort contract).',
+    );
+  }
+}
+
+/**
+ * Read `<socketDir>/runtime.json`. Returns the parsed object on success,
+ * `null` when the file is missing or unreadable. Never throws — callers
+ * treat "missing" and "broken" identically and fall back to admin.json.
+ */
+export function readRuntimeJson(socketDir) {
+  let file;
+  try {
+    file = getRuntimeFilePath(socketDir);
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomic write of the runtime discovery record. Validates shape, refuses
+ * a `supervisor` key (the cohort contract — that field belongs in
+ * admin.json), ensures the parent directory exists, and stamps
+ * `schemaVersion: 1` if the caller didn't.
+ */
+export function writeRuntimeJson(input = {}) {
+  if (!isPlainObject(input)) {
+    throw new TypeError('runtime-json: writeRuntimeJson expects an object argument');
+  }
+  // Reject `supervisor` from the input directly — destructuring would
+  // silently drop it and that's a contract failure we want to surface.
+  if (Object.prototype.hasOwnProperty.call(input, 'supervisor')) {
+    throw new TypeError(
+      'runtime-json: refusing to write `supervisor` into runtime.json — that field '
+      + 'lives only in `~/.autopg/admin.json` (cohort contract).',
+    );
+  }
+  const { socketDir, port, pid, autopgPid, schemaVersion = RUNTIME_SCHEMA_VERSION } = input;
+  const record = { socketDir, port, pid, autopgPid, schemaVersion };
+  validateRecord(record);
+
+  if (!fs.existsSync(socketDir)) {
+    fs.mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+  }
+
+  const file = getRuntimeFilePath(socketDir);
+  const tmp = `${file}.tmp.${process.pid}`;
+  const json = `${JSON.stringify(record, null, 2)}\n`;
+  fs.writeFileSync(tmp, json, { mode: RUNTIME_FILE_MODE });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, RUNTIME_FILE_MODE);
+  return record;
+}
+
+/**
+ * Best-effort delete of `<socketDir>/runtime.json`. Used during graceful
+ * shutdown so consumers immediately observe "no live postmaster" instead
+ * of seeing a stale-pid record they have to probe with `process.kill()`.
+ *
+ * Returns `true` when the file was removed, `false` when it was already
+ * gone or removal failed. Never throws — graceful shutdown must not
+ * regress because of a permission glitch on the runtime file.
+ */
+export function clearRuntimeJson(socketDir) {
+  let file;
+  try {
+    file = getRuntimeFilePath(socketDir);
+  } catch {
+    return false;
+  }
+  try {
+    fs.unlinkSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true when the runtime record points at a process that's alive
+ * on this host. `process.kill(pid, 0)` is a no-signal probe — it raises
+ * ESRCH when the pid is gone and EPERM when we can't signal a foreign
+ * uid (still alive, just not ours). Treat EPERM as "alive" so cross-uid
+ * supervisors (e.g. an operator probing a system-installed pgserve)
+ * don't false-negative.
+ */
+export function isLiveRuntime(record) {
+  if (!isPlainObject(record)) return false;
+  // process.kill(pid, 0) accepts a process group sentinel for pid <= 0
+  // (pid 0 = caller's group, pid -1 = every signalable process). Neither
+  // is a meaningful "live postmaster" answer, so reject anything below 1
+  // before we touch the syscall.
+  const pid = record.autopgPid;
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}

package/src/lib/socket-dir.js

@@ -0,0 +1,69 @@
+/**
+ * Canonical pgserve socket-dir resolver.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 1.
+ *
+ * Postgres backend listens on a Unix socket inside this directory plus TCP
+ * 5432. The directory is also where `pgserve` records its `.s.PGSQL.<port>`
+ * socket file so off-the-shelf libpq clients connecting via
+ * `psql -h <socketDir>` (no `-p`) succeed against the systemd / freedesktop
+ * convention path. CI runners and minimal containers without
+ * `$XDG_RUNTIME_DIR` get `/tmp/pgserve` as the documented fallback.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+export const SOCKET_DIR_NAME = 'pgserve';
+export const SOCKET_DIR_MODE = 0o700;
+
+/**
+ * Resolve the canonical socket directory.
+ *
+ * Preferred: `$XDG_RUNTIME_DIR/pgserve` (systemd / freedesktop convention).
+ * Fallback: `/tmp/pgserve` (CI runners and minimal containers without XDG).
+ *
+ * Pure function — does not touch the filesystem. Use `ensureSocketDir()`
+ * to create the directory with the correct permissions.
+ */
+export function resolveSocketDir() {
+  const xdg = process.env.XDG_RUNTIME_DIR;
+  const base = xdg && xdg.length > 0 ? xdg : '/tmp';
+  return path.join(base, SOCKET_DIR_NAME);
+}
+
+/**
+ * Ensure the socket directory exists with mode 0700 and is writable.
+ *
+ * Returns the resolved path. Throws if the directory exists but is not a
+ * directory, or if creation fails for any reason other than EEXIST.
+ *
+ * The mode is enforced via fs.chmodSync after creation — `mkdirSync(mode)`
+ * is honored only when the directory does not already exist.
+ */
+export function ensureSocketDir(dir = resolveSocketDir()) {
+  fs.mkdirSync(dir, { recursive: true, mode: SOCKET_DIR_MODE });
+  fs.chmodSync(dir, SOCKET_DIR_MODE);
+
+  const stat = fs.statSync(dir);
+  if (!stat.isDirectory()) {
+    throw new Error(
+      `pgserve: socket dir path exists but is not a directory: ${dir}`,
+    );
+  }
+
+  // Validate writability by touching a sentinel file. Avoids surfacing the
+  // real-world failure ("postgres can't bind socket") at the postmaster
+  // boot step where the diagnostic is much harder to trace.
+  const probe = path.join(dir, `.writable-${process.pid}-${Date.now()}`);
+  try {
+    fs.writeFileSync(probe, '');
+    fs.unlinkSync(probe);
+  } catch (err) {
+    throw new Error(
+      `pgserve: socket dir not writable (${dir}): ${err.message}`,
+    );
+  }
+
+  return dir;
+}

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/upgrade/index.js

@@ -20,11 +20,16 @@ import * as plpgsqlResolve from './steps/plpgsql-resolve.js';
 import * as envRefresh from './steps/env-refresh.js';
 import * as consumerSignal from './steps/consumer-signal.js';
 import * as healthValidate from './steps/health-validate.js';
+import * as cosignMetaMigration from './steps/cosign-meta-migration.js';
 
 export const STEPS = [
   { name: 'port-reconcile', impl: portReconcile },
   { name: 'binary-cache-flush', impl: binaryCacheFlush },
   { name: 'plpgsql-resolve', impl: plpgsqlResolve },
+  // pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+  // Adds the additive `verified_*` columns to `pgserve_meta`. Runs after
+  // plpgsql-resolve so the extension is available; idempotent per-DB.
+  { name: 'cosign-meta-migration', impl: cosignMetaMigration },
   { name: 'env-refresh', impl: envRefresh },
   { name: 'consumer-signal', impl: consumerSignal },
   { name: 'health-validate', impl: healthValidate },

package/src/upgrade/steps/cosign-meta-migration.js

@@ -0,0 +1,123 @@
+/**
+ * Step — pgserve_meta cosign columns (additive).
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 4.
+ *
+ * Adds `verified_at`, `verified_identity`, `verified_tier` to every
+ * `pgserve_meta` table the upgrade step finds. The schema delta is
+ * additive (Decision P4) — pre-cosign rows continue to work, columns are
+ * NULL until Group 3's `pgserve provision` writes them.
+ *
+ * Runs idempotently: `ADD COLUMN IF NOT EXISTS` plus a guarded DO-block
+ * for the CHECK constraint. Re-running on an already-migrated host is a
+ * no-op. If `pgserve_meta` does not exist (fresh install before G3 has
+ * provisioned anything) the step is a SKIP.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+import { getMigrationStatements } from '../../cosign/schema.js';
+
+export const name = 'cosign-meta-migration';
+const CANONICAL_PORT = 5432;
+const SYSTEM_DBS = new Set(['template0', 'template1']);
+
+// PR #79 fix: previous implementation used execSync with a template string +
+// JSON.stringify(sql). The migration SQL contains `DO $$ ... $$` blocks; bash
+// expands `$$` to its PID, corrupting the SQL before psql sees it. Switch to
+// spawnSync (shell:false) with the SQL fed through stdin — no shell parsing,
+// no expansion, no injection surface.
+function pgQuery({ db, sql, captureStdout = false, port = CANONICAL_PORT }) {
+  const env = { ...process.env, PGPASSWORD: process.env.PGPASSWORD || 'postgres' };
+  const result = spawnSync(
+    'psql',
+    ['-h', '127.0.0.1', '-p', String(port), '-U', 'postgres', '-d', db, '-At', '-f', '-'],
+    { env, input: sql, stdio: ['pipe', 'pipe', 'pipe'] }
+  );
+  if (result.status !== 0) {
+    const stderr = (result.stderr || Buffer.from('')).toString();
+    const err = new Error(`psql exited ${result.status}: ${stderr.trim()}`);
+    err.status = result.status;
+    err.stderr = stderr;
+    throw err;
+  }
+  const stdout = (result.stdout || Buffer.from('')).toString();
+  return captureStdout ? stdout.trim() : stdout;
+}
+
+function listUserDbs() {
+  const out = pgQuery({
+    db: 'postgres',
+    sql: "SELECT datname FROM pg_database WHERE NOT datistemplate ORDER BY datname",
+    captureStdout: true,
+  });
+  return out ? out.split('\n').filter(Boolean).filter((d) => !SYSTEM_DBS.has(d)) : [];
+}
+
+function pgserveMetaExists(db) {
+  const out = pgQuery({
+    db,
+    sql: "SELECT to_regclass('public.pgserve_meta') IS NOT NULL",
+    captureStdout: true,
+  });
+  return out === 't' || out === 'true';
+}
+
+export async function plan() {
+  let dbs;
+  try {
+    dbs = listUserDbs();
+  } catch (err) {
+    return `cannot enumerate DBs: ${err.message}`;
+  }
+  if (dbs.length === 0) return 'no user DBs — skip';
+  const targets = [];
+  for (const db of dbs) {
+    try {
+      if (pgserveMetaExists(db)) targets.push(db);
+    } catch {
+      // Skip silently — DB might be unreachable, listed but not connectable.
+    }
+  }
+  if (targets.length === 0) return 'no DB hosts pgserve_meta yet — skip';
+  return `would apply additive cosign columns to pgserve_meta in: ${targets.join(', ')}`;
+}
+
+export async function execute({ log, warn }) {
+  let dbs;
+  try {
+    dbs = listUserDbs();
+  } catch (err) {
+    return { status: 'FAIL', detail: `cannot enumerate DBs: ${err.message}` };
+  }
+  if (dbs.length === 0) return { status: 'SKIP', detail: 'no user DBs to migrate' };
+
+  const statements = getMigrationStatements();
+  let migrated = 0;
+  let skipped = 0;
+  for (const db of dbs) {
+    let exists;
+    try {
+      exists = pgserveMetaExists(db);
+    } catch (err) {
+      warn(`[cosign-meta-migration] ${db}: cannot probe pgserve_meta — ${err.message}`);
+      skipped++;
+      continue;
+    }
+    if (!exists) {
+      skipped++;
+      continue;
+    }
+    try {
+      for (const sql of statements) {
+        pgQuery({ db, sql });
+      }
+      log(`[cosign-meta-migration] ${db}: applied ${statements.length} idempotent statement(s)`);
+      migrated++;
+    } catch (err) {
+      warn(`[cosign-meta-migration] ${db}: failed — ${err.message}`);
+      skipped++;
+    }
+  }
+  return { status: 'OK', detail: `migrated ${migrated} DB(s), skipped ${skipped}` };
+}