pgserve 1.2.0 → 2.0.1

package/bin/{pglite-server.js → postgres-server.js}

@@ -12,6 +12,20 @@ import path from 'path';
 import os from 'os';
 import { startMultiTenantServer } from '../src/index.js';
 import { startClusterServer } from '../src/cluster.js';
+import {
+  PgserveDaemon,
+  stopDaemon,
+  resolveControlSocketDir,
+  resolveControlSocketPath,
+} from '../src/daemon.js';
+import { createAdminClient, readAdminDiscovery } from '../src/admin-client.js';
+import {
+  ensureMetaSchema,
+  addAllowedToken,
+  revokeAllowedToken,
+} from '../src/control-db.js';
+import { mintToken } from '../src/tokens.js';
+import { audit, AUDIT_EVENTS } from '../src/audit.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -25,9 +39,252 @@ process.on('uncaughtException', (error) => {
   process.exit(1);
 });
 
-// Parse CLI arguments
+// Parse CLI arguments — `pgserve daemon [stop]` is dispatched before the
+// classic `pgserve [options]` parser so daemon-mode flags do not collide
+// with router flags.
 const args = process.argv.slice(2);
 
+if (args[0] === 'daemon') {
+  await runDaemonSubcommand(args.slice(1));
+}
+
+async function runDaemonSubcommand(daemonArgs) {
+  if (daemonArgs[0] === 'stop') {
+    const result = stopDaemon();
+    if (result.stopped) {
+      console.log(`pgserve daemon stopped (pid ${result.pid})`);
+      process.exit(0);
+    }
+    if (result.reason === 'no-pid-file') {
+      console.error('pgserve daemon: no PID file found — is the daemon running?');
+      process.exit(1);
+    }
+    if (result.reason === 'stale-pid' || result.reason === 'invalid-pid-file') {
+      console.log(`pgserve daemon: cleaned up stale lock (pid ${result.pid ?? '?'})`);
+      process.exit(0);
+    }
+    if (result.reason === 'timeout') {
+      console.error(`pgserve daemon: pid ${result.pid} did not exit within timeout`);
+      process.exit(1);
+    }
+    console.error(`pgserve daemon stop: ${result.reason}${result.error ? ` (${result.error})` : ''}`);
+    process.exit(1);
+  }
+
+  if (daemonArgs[0] === 'issue-token') {
+    await runIssueTokenSubcommand(daemonArgs.slice(1));
+    return;
+  }
+  if (daemonArgs[0] === 'revoke-token') {
+    await runRevokeTokenSubcommand(daemonArgs.slice(1));
+    return;
+  }
+
+  // `pgserve daemon` (long-running)
+  const opts = parseDaemonArgs(daemonArgs);
+  const daemon = new PgserveDaemon(opts);
+  try {
+    await daemon.start();
+  } catch (err) {
+    if (err.code === 'EALREADYRUNNING') {
+      console.error(`pgserve daemon: already running, pid ${err.pid}`);
+      process.exit(1);
+    }
+    console.error('pgserve daemon: failed to start:', err.message);
+    process.exit(1);
+  }
+  const dir = resolveControlSocketDir();
+  console.log(`
+pgserve daemon — singleton mode
+
+  Control socket: ${resolveControlSocketPath(dir)}
+  PID lock:       ${path.join(dir, 'pgserve.pid')}
+  PG socket:      ${daemon.pgManager.getSocketPath() || '(TCP fallback)'}
+
+  Connect:        psql 'host=${dir} dbname=mydb'
+
+  Press Ctrl+C or send SIGTERM to stop.
+`);
+
+  // Daemon installs its own SIGTERM/SIGINT handlers; just wait forever.
+  await new Promise(() => {});
+}
+
+function parseDaemonArgs(daemonArgs) {
+  const opts = {
+    baseDir: null,
+    useRam: false,
+    logLevel: 'info',
+    autoProvision: true,
+    tcpListens: [],
+    enablePgvector: false,
+  };
+  for (let i = 0; i < daemonArgs.length; i++) {
+    const arg = daemonArgs[i];
+    switch (arg) {
+      case '--data':
+      case '-d':
+        opts.baseDir = daemonArgs[++i];
+        break;
+      case '--ram':
+        opts.useRam = true;
+        break;
+      case '--log':
+      case '-l':
+        opts.logLevel = daemonArgs[++i];
+        break;
+      case '--no-provision':
+        opts.autoProvision = false;
+        break;
+      case '--listen':
+        opts.tcpListens.push(daemonArgs[++i]);
+        break;
+      case '--pgvector':
+        opts.enablePgvector = true;
+        break;
+      case '--help':
+        console.log(`
+pgserve daemon — singleton control-socket mode
+
+USAGE:
+  pgserve daemon [options]
+  pgserve daemon stop
+  pgserve daemon issue-token --fingerprint <hex>
+  pgserve daemon revoke-token <id>
+
+OPTIONS:
+  --data <path>   Persistent data directory (default: in-memory)
+  --ram           Use /dev/shm storage (Linux only)
+  --log <level>   Log level: error|warn|info|debug (default: info)
+  --no-provision  Disable auto-provisioning of databases
+  --listen [host:]port  Bind opt-in TCP listener (repeatable)
+  --pgvector      Auto-enable pgvector extension on new databases
+  --help          Show this help
+
+The daemon binds $XDG_RUNTIME_DIR/pgserve/control.sock (fallback /tmp/pgserve/control.sock).
+A second invocation while the first is running exits with "already running".
+
+TCP peers (--listen) MUST authenticate via libpq application_name shaped
+"?fingerprint=<12hex>&token=<bearer>". Issue tokens with
+"pgserve daemon issue-token --fingerprint <hex>". Revoke with
+"pgserve daemon revoke-token <id>".
+`);
+        process.exit(0);
+        // falls through (unreachable)
+      default:
+        if (arg.startsWith('-')) {
+          console.error(`Unknown daemon option: ${arg}`);
+          process.exit(1);
+        }
+    }
+  }
+  return opts;
+}
+
+async function runIssueTokenSubcommand(args) {
+  let fingerprint = null;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--fingerprint') fingerprint = args[++i];
+    else if (arg === '--help') {
+      console.log(`
+pgserve daemon issue-token --fingerprint <12hex>
+
+Issues a fresh bearer token for an existing fingerprint. Prints the token
+to stdout exactly once; only the sha256 hash is persisted. Use the printed
+value in libpq application_name shaped "?fingerprint=<hex>&token=<bearer>".
+`);
+      process.exit(0);
+    } else {
+      console.error(`Unknown option: ${arg}`);
+      process.exit(1);
+    }
+  }
+  if (!fingerprint || !/^[0-9a-f]{12}$/.test(fingerprint)) {
+    console.error('issue-token: --fingerprint <12hex> required');
+    process.exit(1);
+  }
+
+  let admin;
+  try {
+    const dir = resolveControlSocketDir();
+    const disc = readAdminDiscovery(dir);
+    admin = await createAdminClient({ socketDir: disc.socketDir, port: disc.port });
+  } catch (err) {
+    console.error('issue-token: cannot reach running daemon admin socket:', err.message);
+    console.error('Hint: start the daemon first with `pgserve daemon`.');
+    process.exit(1);
+  }
+
+  try {
+    await ensureMetaSchema(admin);
+    const { id, cleartext, hash } = mintToken();
+    const result = await addAllowedToken(admin, {
+      fingerprint,
+      tokenId: id,
+      tokenHash: hash,
+    });
+    audit(AUDIT_EVENTS.TCP_TOKEN_ISSUED, {
+      fingerprint,
+      token_id: id,
+      database: result.databaseName,
+    });
+    console.log('Token issued. Save the bearer value below — it will not be shown again:');
+    console.log('');
+    console.log(`  id:          ${id}`);
+    console.log(`  fingerprint: ${fingerprint}`);
+    console.log(`  database:    ${result.databaseName}`);
+    console.log(`  token:       ${cleartext}`);
+    console.log('');
+    console.log('Use as libpq application_name:');
+    console.log(`  application_name='?fingerprint=${fingerprint}&token=${cleartext}'`);
+    process.exit(0);
+  } catch (err) {
+    if (err.code === 'EUNKNOWNFINGERPRINT') {
+      console.error(`issue-token: fingerprint ${fingerprint} not provisioned yet.`);
+      console.error('Connect once via Unix socket so pgserve creates the database first.');
+      process.exit(2);
+    }
+    console.error('issue-token failed:', err.message);
+    process.exit(1);
+  } finally {
+    try { await admin.end(); } catch { /* swallow */ }
+  }
+}
+
+async function runRevokeTokenSubcommand(args) {
+  if (args.length === 0 || args[0] === '--help') {
+    console.log('Usage: pgserve daemon revoke-token <id>');
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+  const tokenId = args[0];
+
+  let admin;
+  try {
+    const dir = resolveControlSocketDir();
+    const disc = readAdminDiscovery(dir);
+    admin = await createAdminClient({ socketDir: disc.socketDir, port: disc.port });
+  } catch (err) {
+    console.error('revoke-token: cannot reach running daemon admin socket:', err.message);
+    process.exit(1);
+  }
+
+  try {
+    const affected = await revokeAllowedToken(admin, tokenId);
+    if (affected === 0) {
+      console.error(`revoke-token: no token with id ${tokenId} found`);
+      process.exit(2);
+    }
+    console.log(`Token ${tokenId} revoked (affected ${affected} row${affected === 1 ? '' : 's'})`);
+    process.exit(0);
+  } catch (err) {
+    console.error('revoke-token failed:', err.message);
+    process.exit(1);
+  } finally {
+    try { await admin.end(); } catch { /* swallow */ }
+  }
+}
+
 /**
  * Print usage help
  */

package/bun.lock

@@ -8,7 +8,6 @@
         "bun": "^1.3.4",
       },
       "devDependencies": {
-        "@electric-sql/pglite": "^0.2.17",
         "eslint": "^9.39.1",
         "eslint-plugin-unused-imports": "^4.3.0",
         "husky": "^9.1.7",
@@ -25,8 +24,6 @@
     },
   },
   "packages": {
-    "@electric-sql/pglite": ["@electric-sql/pglite@0.2.17", "", {}, "sha512-qEpKRT2oUaWDH6tjRxLHjdzMqRUGYDnGZlKrnL4dJ77JVMcP2Hpo3NYnOSPKdZdeec57B6QPprCUFg0picx5Pw=="],
-
     "@embedded-postgres/darwin-arm64": ["@embedded-postgres/darwin-arm64@18.2.0-beta.16", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wnswaF+uDvGeitqajJ8v8xOG4ttFrzixElwKNe2MIxBXSLWPV3xhi6tBY0Sjw8Lmiu6UG9vNLFZSjHPrIeokBg=="],
 
     "@embedded-postgres/darwin-x64": ["@embedded-postgres/darwin-x64@18.2.0-beta.16", "", { "os": "darwin", "cpu": "x64" }, "sha512-u9WtTPxRuO0uOny5IniXHSDaLmtOujwzDoExIV/jFT0Fu8SzpX7wdoPbsSPBLgyQWdr/nPA77K9QI4r6P1/fKA=="],

package/ecosystem.config.cjs

@@ -2,7 +2,7 @@ module.exports = {
   apps: [
     {
       name: 'pgserve',
-      script: './bin/pglite-server.js',
+      script: './bin/postgres-server.js',
       args: 'router --port 8432',
       cwd: '/home/namastex/dev/pgserve',
       interpreter: 'node',
@@ -13,8 +13,8 @@ module.exports = {
       env: {
         NODE_ENV: 'production'
       },
-      error_file: '/home/namastex/logs/pglite-server-error.log',
-      out_file: '/home/namastex/logs/pglite-server-out.log',
+      error_file: '/home/namastex/logs/postgres-server-error.log',
+      out_file: '/home/namastex/logs/postgres-server-out.log',
       log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
       merge_logs: true,
       time: true

package/eslint.config.js

@@ -17,6 +17,8 @@ export default [
         clearTimeout: 'readonly',
         setInterval: 'readonly',
         clearInterval: 'readonly',
+        setImmediate: 'readonly',
+        clearImmediate: 'readonly',
         URL: 'readonly',
         __dirname: 'readonly',
         // Bun globals

package/knip.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "entry": ["src/index.js", "bin/pglite-server.js", "bin/pgserve-wrapper.cjs"],
+  "entry": ["src/index.js", "bin/postgres-server.js", "bin/pgserve-wrapper.cjs"],
   "project": ["src/**/*.js", "bin/**/*.js", "bin/**/*.cjs"],
   "ignore": ["tests/**", "helpers/**", "scripts/**"],
   "ignoreBinaries": ["scripts/test-npx.sh", "scripts/test-bun-self-heal.sh", "make"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "1.2.0",
+  "version": "2.0.1",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -11,9 +11,9 @@
     "bench": "bun tests/benchmarks/runner.js",
     "test": "bun test tests/**/*.test.js",
     "test:watch": "bun test --watch tests/**/*.test.js",
-    "dev": "bun --watch bin/pglite-server.js",
-    "start": "bun bin/pglite-server.js",
-    "build": "bun build --compile bin/pglite-server.js --outfile dist/pgserve",
+    "dev": "bun --watch bin/postgres-server.js",
+    "start": "bun bin/postgres-server.js",
+    "build": "bun build --compile bin/postgres-server.js --outfile dist/pgserve",
     "build:all": "make build-all",
     "lint": "eslint src/ bin/",
     "lint:fix": "eslint src/ bin/ --fix",
@@ -48,7 +48,6 @@
     "@embedded-postgres/windows-x64": "18.2.0-beta.16"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.2.17",
     "eslint": "^9.39.1",
     "eslint-plugin-unused-imports": "^4.3.0",
     "husky": "^9.1.7",

package/scripts/test-bun-self-heal.sh

@@ -7,7 +7,7 @@
 # pgserve-wrapper.cjs must detect this and self-heal via `node install.js`.
 #
 # This test stages a synthetic broken install tree, runs the wrapper, and
-# asserts that it recovers and spawns pglite-server.
+# asserts that it recovers and spawns postgres-server.
 
 set -e
 
@@ -37,10 +37,10 @@ mkdir -p "$FIXTURE/node_modules/pgserve/bin"
 
 cp "$WRAPPER" "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs"
 
-# Stub pglite-server so we can detect a successful spawn without needing
+# Stub postgres-server so we can detect a successful spawn without needing
 # postgres binaries in the fixture.
-cat > "$FIXTURE/node_modules/pgserve/bin/pglite-server.js" <<'EOF'
-console.log("pglite-server-spawned");
+cat > "$FIXTURE/node_modules/pgserve/bin/postgres-server.js" <<'EOF'
+console.log("postgres-server-spawned");
 process.exit(0);
 EOF
 
@@ -97,13 +97,13 @@ if ! echo "$OUTPUT" | grep -q "bun runtime recovered"; then
   exit 1
 fi
 
-if ! echo "$OUTPUT" | grep -q "pglite-server-spawned"; then
-  echo "✗ pglite-server was not spawned after self-heal"
+if ! echo "$OUTPUT" | grep -q "postgres-server-spawned"; then
+  echo "✗ postgres-server was not spawned after self-heal"
   echo "$OUTPUT"
   exit 1
 fi
 
-echo "✓ self-heal path: wrapper detected, repaired, and spawned pglite-server"
+echo "✓ self-heal path: wrapper detected, repaired, and spawned postgres-server"
 
 echo ""
 echo "=== Testing healthy path is unaffected ==="
@@ -122,13 +122,13 @@ if echo "$OUTPUT" | grep -q "self-heal\|recovered"; then
   exit 1
 fi
 
-if ! echo "$OUTPUT" | grep -q "pglite-server-spawned"; then
-  echo "✗ pglite-server was not spawned on healthy path"
+if ! echo "$OUTPUT" | grep -q "postgres-server-spawned"; then
+  echo "✗ postgres-server was not spawned on healthy path"
   echo "$OUTPUT"
   exit 1
 fi
 
-echo "✓ healthy path: wrapper was silent and spawned pglite-server directly"
+echo "✓ healthy path: wrapper was silent and spawned postgres-server directly"
 
 echo ""
 echo "=== Testing non-postinstall errors surface raw ==="

package/src/admin-client.js

@@ -0,0 +1,171 @@
+/**
+ * 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]
+ * @returns {Promise<{query: (text: string, params?: any[]) => 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,
+} = {}) {
+  if (typeof port !== 'number') throw new Error('createAdminClient: port required');
+  const sql = new SQL({
+    hostname: host,
+    port,
+    database,
+    username: user,
+    password,
+    max,
+    // TODO #38: investigate GC perf for 240-orphan sweep on shared CI runners;
+    // bumped 10s→30s during Felipe deadline 2026-04-29 to unblock pgserve v2.0 ship.
+    idleTimeout: 30,
+  });
+  // Light probe so a misconfigured daemon fails loudly here rather than at
+  // first query.
+  await sql`SELECT 1`;
+  return {
+    sql,
+    async query(text, params = []) {
+      // 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 rows = await sql.unsafe(text, adapted);
+      // 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 };
+    },
+    async end() {
+      try { await sql.close(); } catch { /* swallow */ }
+    },
+  };
+}
+
+/**
+ * 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;
+  }
+}