pgserve 0.1.1

package/src/detector.js

@@ -0,0 +1,105 @@
+import net from 'net';
+
+/**
+ * Check if PostgreSQL connection URL is valid and reachable
+ */
+export async function canConnectToPostgres(connectionUrl, timeout = 5000) {
+  if (!connectionUrl || !connectionUrl.startsWith('postgresql://')) {
+    return false;
+  }
+
+  try {
+    // Parse URL to extract host and port
+    const url = new URL(connectionUrl);
+    const host = url.hostname;
+    const port = parseInt(url.port || '5432', 10);
+
+    return await checkTcpConnection(host, port, timeout);
+  } catch (error) {
+    console.warn('Invalid PostgreSQL URL:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Check if TCP connection can be established
+ */
+function checkTcpConnection(host, port, timeout) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+
+    const cleanup = () => {
+      socket.destroy();
+    };
+
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve(false);
+    }, timeout);
+
+    socket.once('connect', () => {
+      clearTimeout(timer);
+      cleanup();
+      resolve(true);
+    });
+
+    socket.once('error', () => {
+      clearTimeout(timer);
+      cleanup();
+      resolve(false);
+    });
+
+    socket.connect(port, host);
+  });
+}
+
+/**
+ * Auto-detect database URL
+ *
+ * Priority:
+ * 1. External PostgreSQL (if reachable)
+ * 2. Embedded PGlite server (start if needed)
+ */
+export async function autoDetect({
+  externalUrl,
+  embeddedDataDir,
+  embeddedPort = null,
+  timeout = 5000
+}) {
+  // Try external PostgreSQL first
+  if (externalUrl && externalUrl.startsWith('postgresql://')) {
+    console.log('🔍 Checking external PostgreSQL connection...');
+
+    if (await canConnectToPostgres(externalUrl, timeout)) {
+      console.log('✅ Using external PostgreSQL');
+      return {
+        type: 'external',
+        url: externalUrl,
+        embedded: false
+      };
+    }
+
+    console.warn('⚠️  External PostgreSQL unreachable, falling back to embedded');
+  }
+
+  // Start embedded server
+  console.log('🚀 Starting embedded PGlite server...');
+
+  const { getOrStart } = await import('./index.js');
+
+  const instance = await getOrStart({
+    dataDir: embeddedDataDir,
+    port: embeddedPort,
+    autoPort: true
+  });
+
+  console.log(`✅ Using embedded PGlite on port ${instance.port}`);
+
+  return {
+    type: 'embedded',
+    url: instance.connectionUrl,
+    embedded: true,
+    port: instance.port,
+    dataDir: instance.dataDir
+  };
+}

package/src/index.js

@@ -0,0 +1,177 @@
+/**
+ * pgserve - PostgreSQL embedded server using PGlite
+ *
+ * Multi-tenant PostgreSQL router using PGlite
+ * Single port, auto-provisioning, perfect for multi-user apps and AI agents
+ */
+
+// Multi-tenant mode (NEW - recommended)
+export { MultiTenantRouter, startMultiTenantServer } from './router.js';
+export { InstancePool } from './pool.js';
+
+// Legacy single-instance mode (backwards compatible)
+import { startServer as _startServer, stopServer as _stopServer } from './server.js';
+import { allocatePort, getPortRangeInfo } from './ports.js';
+import {
+  findInstanceByDataDir,
+  findInstanceByPort,
+  listInstances,
+  cleanupStaleInstances
+} from './registry.js';
+import { autoDetect as _autoDetect } from './detector.js';
+
+/**
+ * Start a new PGlite server instance
+ *
+ * @param {Object} options
+ * @param {string} options.dataDir - Data directory for the database
+ * @param {number} [options.port] - Specific port (optional, auto-allocated if not provided)
+ * @param {boolean} [options.autoPort=true] - Auto-allocate port if specified port is unavailable
+ * @param {string} [options.logLevel='info'] - Log level (error, warn, info, debug)
+ * @returns {Promise<Object>} Server instance
+ */
+export async function startServer({ dataDir, port, autoPort = true, logLevel = 'info' }) {
+  // Allocate port (checks for existing instance, reuses if running)
+  const allocatedPort = await allocatePort(dataDir, port);
+
+  if (port && allocatedPort !== port && !autoPort) {
+    throw new Error(
+      `Port ${port} unavailable and autoPort is disabled. ` +
+        `Use autoPort: true or choose a different port.`
+    );
+  }
+
+  return _startServer({ dataDir, port: allocatedPort, logLevel });
+}
+
+/**
+ * Stop a running server instance
+ *
+ * @param {Object} options
+ * @param {string} [options.dataDir] - Data directory of the instance to stop
+ * @param {number} [options.port] - Port of the instance to stop
+ */
+export async function stopServer({ dataDir, port }) {
+  return _stopServer({ dataDir, port });
+}
+
+/**
+ * Get an existing instance or start a new one
+ *
+ * This is the recommended way to start a server, as it prevents
+ * duplicate instances for the same data directory.
+ *
+ * @param {Object} options
+ * @param {string} options.dataDir - Data directory for the database
+ * @param {number} [options.port] - Preferred port (auto-allocated if unavailable)
+ * @param {boolean} [options.autoPort=true] - Auto-allocate port
+ * @param {string} [options.logLevel='info'] - Log level
+ * @returns {Promise<Object>} Server instance (existing or new)
+ */
+export async function getOrStart({ dataDir, port, autoPort = true, logLevel = 'info' }) {
+  // Check if instance already running
+  const existing = findInstanceByDataDir(dataDir);
+
+  if (existing) {
+    // Verify process is still alive
+    try {
+      process.kill(existing.pid, 0);
+      console.log(`✅ Using existing instance on port ${existing.port}`);
+
+      return {
+        port: existing.port,
+        dataDir,
+        pid: existing.pid,
+        connectionUrl: `postgresql://localhost:${existing.port}`,
+        existing: true
+      };
+    } catch {
+      // Process dead, cleanup and start new
+      console.log('🔄 Stale instance found, starting fresh...');
+    }
+  }
+
+  // Start new instance
+  return startServer({ dataDir, port, autoPort, logLevel });
+}
+
+/**
+ * Auto-detect database configuration
+ *
+ * Tries external PostgreSQL first, falls back to embedded PGlite
+ *
+ * @param {Object} options
+ * @param {string} [options.externalUrl] - External PostgreSQL URL to try first
+ * @param {string} options.embeddedDataDir - Data directory for embedded fallback
+ * @param {number} [options.embeddedPort] - Preferred port for embedded server
+ * @param {number} [options.timeout=5000] - Timeout for external connection test
+ * @returns {Promise<Object>} Database configuration
+ */
+export async function autoDetect({
+  externalUrl,
+  embeddedDataDir,
+  embeddedPort,
+  timeout = 5000
+}) {
+  return _autoDetect({ externalUrl, embeddedDataDir, embeddedPort, timeout });
+}
+
+/**
+ * List all running instances
+ *
+ * @returns {Array<Object>} Array of instance info
+ */
+export function list() {
+  return listInstances();
+}
+
+/**
+ * Find instance by data directory
+ *
+ * @param {string} dataDir - Data directory path
+ * @returns {Object|null} Instance info or null
+ */
+export function findByDataDir(dataDir) {
+  return findInstanceByDataDir(dataDir);
+}
+
+/**
+ * Find instance by port
+ *
+ * @param {number} port - Port number
+ * @returns {Object|null} Instance info or null
+ */
+export function findByPort(port) {
+  return findInstanceByPort(port);
+}
+
+/**
+ * Get port range information
+ *
+ * @returns {Object} Port range stats
+ */
+export function portInfo() {
+  return getPortRangeInfo();
+}
+
+/**
+ * Cleanup stale instances (dead processes)
+ *
+ * @returns {number} Number of instances cleaned up
+ */
+export function cleanup() {
+  return cleanupStaleInstances();
+}
+
+// Export all functions
+export default {
+  startServer,
+  stopServer,
+  getOrStart,
+  autoDetect,
+  list,
+  findByDataDir,
+  findByPort,
+  portInfo,
+  cleanup
+};

package/src/pool.js

@@ -0,0 +1,320 @@
+/**
+ * PGlite Instance Pool (Performance Optimized)
+ *
+ * Manages multiple PGlite instances (one per database)
+ * Handles lazy initialization, connection locking, and cleanup
+ *
+ * Performance Optimizations:
+ * - Fast Map-based lookups (O(1) access)
+ * - Minimal memory overhead per instance
+ * - Pino structured logging
+ * - Proper event listener cleanup
+ */
+
+import { PGlite } from '@electric-sql/pglite';
+import path from 'path';
+import fs from 'fs';
+import { EventEmitter } from 'events';
+
+/**
+ * Wrapper for PGlite instance with connection management
+ */
+class ManagedInstance extends EventEmitter {
+  constructor(dbName, dataDir, logger, memoryMode = false) {
+    super();
+    this.dbName = dbName;
+    this.dataDir = dataDir;
+    this.memoryMode = memoryMode;
+    this.logger = logger; // Pino logger
+    this.db = null;
+    this.locked = false;
+    this.activeSocket = null;
+    this.lockTimer = null; // Safety timeout for locks
+    this.queue = [];
+    this.createdAt = Date.now();
+    this.lastAccess = Date.now();
+
+    // Performance: Limit max listeners
+    this.setMaxListeners(10);
+  }
+
+  /**
+   * Initialize PGlite instance (lazy)
+   */
+  async initialize() {
+    if (this.db) {
+      return this.db;
+    }
+
+    const initStart = Date.now();
+
+    if (this.memoryMode) {
+      // Use in-memory database (unique per instance)
+      this.logger.debug({ dbName: this.dbName, mode: 'memory' }, 'Initializing in-memory PGlite instance');
+      this.db = new PGlite();
+    } else {
+      // Ensure directory exists for file-based storage
+      if (!fs.existsSync(this.dataDir)) {
+        fs.mkdirSync(this.dataDir, { recursive: true });
+      }
+
+      this.logger.debug({ dbName: this.dbName, dataDir: this.dataDir }, 'Initializing PGlite instance');
+      this.db = new PGlite(this.dataDir);
+    }
+
+    await this.db.waitReady;
+
+    const initTime = Date.now() - initStart;
+    this.logger.info({
+      dbName: this.dbName,
+      dataDir: this.memoryMode ? '(in-memory)' : this.dataDir,
+      memoryMode: this.memoryMode,
+      initTimeMs: initTime
+    }, 'PGlite instance initialized');
+
+    this.emit('initialized', this.dbName);
+    return this.db;
+  }
+
+  /**
+   * Lock instance to a socket
+   * @param {net.Socket} socket - TCP socket to lock to
+   * @param {number} timeout - Safety timeout in ms (default 5 minutes)
+   */
+  lock(socket, timeout = 300000) {
+    if (this.locked) {
+      throw new Error(`Instance ${this.dbName} is already locked`);
+    }
+
+    this.locked = true;
+    this.activeSocket = socket;
+    this.lastAccess = Date.now();
+
+    // Safety net: auto-unlock after timeout (prevents permanent locks)
+    this.lockTimer = setTimeout(() => {
+      this.logger.warn({ dbName: this.dbName }, 'Lock timeout - forcing unlock');
+      this.unlock();
+    }, timeout);
+
+    // Only attach event listeners if socket is provided
+    if (socket) {
+      socket.on('close', () => this.unlock());
+      socket.on('error', () => this.unlock());
+    }
+
+    this.emit('locked', this.dbName, socket);
+  }
+
+  /**
+   * Unlock instance (connection closed)
+   */
+  unlock() {
+    // Clear safety timeout if it exists
+    if (this.lockTimer) {
+      clearTimeout(this.lockTimer);
+      this.lockTimer = null;
+    }
+
+    this.locked = false;
+    this.activeSocket = null;
+    this.lastAccess = Date.now();
+
+    this.emit('unlocked', this.dbName);
+
+    // Resolve one waiting promise (it will lock, then when it unlocks, the next will be resolved)
+    if (this.queue.length > 0) {
+      const { resolve } = this.queue.shift();
+      // Don't lock here - let the acquire() caller handle locking with their socket
+      resolve(this);
+    }
+  }
+
+  /**
+   * Wait for instance to be free
+   */
+  async waitForFree(timeout = 30000) {
+    if (!this.locked) {
+      return this;
+    }
+
+    return new Promise((resolve, reject) => {
+      this.queue.push({ socket: null, resolve, reject });
+
+      const timer = setTimeout(() => {
+        const index = this.queue.findIndex((item) => item.resolve === resolve);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+        }
+        reject(new Error(`Timeout waiting for database ${this.dbName}`));
+      }, timeout);
+
+      // Clear timeout on resolve
+      this.once('unlocked', () => clearTimeout(timer));
+    });
+  }
+
+  /**
+   * Close PGlite instance
+   */
+  async close() {
+    if (this.db) {
+      try {
+        await this.db.close();
+      } catch (error) {
+        // Ignore ExitStatus errors (normal WASM cleanup)
+        if (error.name !== 'ExitStatus') {
+          console.error(`Error closing instance ${this.dbName}:`, error.message);
+        }
+      }
+    }
+
+    this.db = null;
+    this.emit('closed', this.dbName);
+  }
+
+  /**
+   * Get instance stats
+   */
+  getStats() {
+    return {
+      dbName: this.dbName,
+      locked: this.locked,
+      queueLength: this.queue.length,
+      uptime: Date.now() - this.createdAt,
+      lastAccess: Date.now() - this.lastAccess
+    };
+  }
+}
+
+/**
+ * PGlite Instance Pool
+ */
+export class InstancePool extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.baseDir = options.baseDir || './data';
+    this.memoryMode = options.memoryMode || false;
+    this.maxInstances = options.maxInstances || 100;
+    this.autoProvision = options.autoProvision !== false; // Default true
+    this.instances = new Map(); // dbName -> ManagedInstance (O(1) lookups)
+    this.logger = options.logger; // Pino logger
+
+    // Performance: Set max listeners based on max instances
+    this.setMaxListeners(this.maxInstances + 10);
+  }
+
+  /**
+   * Get or create PGlite instance for database (Performance Optimized)
+   */
+  async getOrCreate(dbName) {
+    // Fast path: Check cache first (O(1) lookup)
+    let instance = this.instances.get(dbName);
+
+    if (!instance) {
+      // Check max instances limit
+      if (this.instances.size >= this.maxInstances) {
+        this.logger.error({
+          dbName,
+          currentInstances: this.instances.size,
+          maxInstances: this.maxInstances
+        }, 'Maximum instances limit reached');
+
+        throw new Error(
+          `Maximum instances limit reached (${this.maxInstances}). ` +
+            `Cannot create database: ${dbName}`
+        );
+      }
+
+      if (!this.autoProvision) {
+        this.logger.warn({ dbName }, 'Database does not exist (auto-provision disabled)');
+        throw new Error(`Database ${dbName} does not exist (auto-provision disabled)`);
+      }
+
+      // Create new instance
+      const dataDir = this.memoryMode ? null : path.join(this.baseDir, dbName);
+      instance = new ManagedInstance(
+        dbName,
+        dataDir,
+        this.logger.child({ dbName }), // Child logger with context
+        this.memoryMode
+      );
+
+      // Forward events (use once() where appropriate for performance)
+      instance.on('initialized', (name) => this.emit('instance-created', name));
+      instance.on('locked', (name) => this.emit('instance-locked', name));
+      instance.on('unlocked', (name) => this.emit('instance-unlocked', name));
+      instance.on('closed', (name) => this.emit('instance-closed', name));
+
+      // Add to cache BEFORE initialization (prevents race conditions)
+      this.instances.set(dbName, instance);
+    }
+
+    // Lazy initialize (async, may already be initialized)
+    await instance.initialize();
+
+    return instance;
+  }
+
+  /**
+   * Acquire instance (lock to socket)
+   */
+  async acquire(dbName, socket, timeout = 30000) {
+    const instance = await this.getOrCreate(dbName);
+
+    // If locked, wait for it to be free
+    if (instance.locked) {
+      console.log(`⏳ Database ${dbName} is busy, queuing connection...`);
+      await instance.waitForFree(timeout);
+    }
+
+    // Lock to this socket
+    instance.lock(socket);
+
+    return instance;
+  }
+
+  /**
+   * Get instance (without locking)
+   */
+  get(dbName) {
+    return this.instances.get(dbName);
+  }
+
+  /**
+   * List all instances
+   */
+  list() {
+    return Array.from(this.instances.values()).map((instance) => instance.getStats());
+  }
+
+  /**
+   * Close specific instance
+   */
+  async closeInstance(dbName) {
+    const instance = this.instances.get(dbName);
+    if (instance) {
+      await instance.close();
+      this.instances.delete(dbName);
+    }
+  }
+
+  /**
+   * Close all instances
+   */
+  async closeAll() {
+    const promises = Array.from(this.instances.values()).map((instance) => instance.close());
+    await Promise.all(promises);
+    this.instances.clear();
+  }
+
+  /**
+   * Get pool stats
+   */
+  getStats() {
+    return {
+      totalInstances: this.instances.size,
+      maxInstances: this.maxInstances,
+      instances: this.list()
+    };
+  }
+}

package/src/ports.js

@@ -0,0 +1,114 @@
+import net from 'net';
+import { loadRegistry } from './registry.js';
+
+const PORT_RANGE_START = 12000;
+const PORT_RANGE_END = 12999;
+
+/**
+ * Check if a port is available
+ */
+export function isPortFree(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        resolve(false);
+      } else {
+        resolve(false);
+      }
+    });
+
+    server.once('listening', () => {
+      server.close();
+      resolve(true);
+    });
+
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+/**
+ * Check if port is in registry (even if process is dead)
+ */
+function isPortInRegistry(port) {
+  const registry = loadRegistry();
+
+  for (const instance of Object.values(registry.instances)) {
+    if (instance.port === port) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Allocate a port for a data directory
+ *
+ * Priority:
+ * 1. If instance already running, return its port
+ * 2. Try preferred port (if provided)
+ * 3. Find next available port in range
+ */
+export async function allocatePort(dataDir, preferredPort = null) {
+  const registry = loadRegistry();
+
+  // Check if instance already exists for this dataDir
+  const existing = registry.instances[dataDir];
+  if (existing) {
+    // Verify process is still running
+    try {
+      process.kill(existing.pid, 0);
+      console.log(`Instance already running for ${dataDir} on port ${existing.port}`);
+      return existing.port;
+    } catch {
+      // Process dead, continue allocation
+      console.log(`Stale instance found for ${dataDir}, reallocating port`);
+    }
+  }
+
+  // Try preferred port first
+  if (preferredPort !== null) {
+    if (preferredPort < PORT_RANGE_START || preferredPort > PORT_RANGE_END) {
+      throw new Error(
+        `Preferred port ${preferredPort} outside allowed range ${PORT_RANGE_START}-${PORT_RANGE_END}`
+      );
+    }
+
+    if (await isPortFree(preferredPort) && !isPortInRegistry(preferredPort)) {
+      return preferredPort;
+    }
+
+    console.warn(`Preferred port ${preferredPort} unavailable, auto-allocating...`);
+  }
+
+  // Find next available port
+  for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
+    if ((await isPortFree(port)) && !isPortInRegistry(port)) {
+      return port;
+    }
+  }
+
+  throw new Error(
+    `No available ports in range ${PORT_RANGE_START}-${PORT_RANGE_END}. ` +
+    `Stop unused instances with 'pglite-server stop --all'`
+  );
+}
+
+/**
+ * Get port range info
+ */
+export function getPortRangeInfo() {
+  const registry = loadRegistry();
+  const usedPorts = Object.values(registry.instances).map((i) => i.port);
+
+  return {
+    start: PORT_RANGE_START,
+    end: PORT_RANGE_END,
+    total: PORT_RANGE_END - PORT_RANGE_START + 1,
+    used: usedPorts.length,
+    available: PORT_RANGE_END - PORT_RANGE_START + 1 - usedPorts.length,
+    usedPorts
+  };
+}