pgserve 0.1.1

package/src/protocol.js

@@ -0,0 +1,216 @@
+/**
+ * PostgreSQL Wire Protocol Parser (Performance Optimized)
+ *
+ * Extracts database name from PostgreSQL startup message
+ * https://www.postgresql.org/docs/current/protocol-message-formats.html
+ *
+ * Optimizations:
+ * - Fast path for database extraction (skip full parsing if possible)
+ * - Minimize string allocations
+ * - Use Buffer.indexOf for faster null-byte search
+ */
+
+const PROTOCOL_VERSION_3 = 196608;
+const SSL_REQUEST_CODE = 80877103; // PostgreSQL SSL negotiation request
+const DATABASE_KEY = Buffer.from('database\0');
+
+/**
+ * Parse PostgreSQL startup message to extract connection parameters
+ * OPTIMIZED: Fast path for database extraction
+ *
+ * @param {Buffer} data - Raw startup message data
+ * @param {boolean} [fastPath=true] - Use fast path (only extract database)
+ * @returns {Object} Parsed parameters (user, database, application_name, etc.)
+ */
+export function parseStartupMessage(data, fastPath = true) {
+  const length = data.readInt32BE(0);
+  const version = data.readInt32BE(4);
+
+  // Verify protocol version (3.0 = 196608)
+  if (version !== PROTOCOL_VERSION_3) {
+    throw new Error(`Unsupported protocol version: ${version}`);
+  }
+
+  // Fast path: only extract database name (most common case)
+  if (fastPath) {
+    const dbName = extractDatabaseFast(data, 8, length);
+    if (dbName) {
+      return { database: dbName };
+    }
+    // Fallback to full parse if fast path failed
+  }
+
+  // Full parse (slower but complete)
+  const params = {};
+  let offset = 8;
+
+  while (offset < length - 1) {
+    // Find next null byte (key end)
+    const keyEnd = data.indexOf(0, offset);
+    if (keyEnd === -1 || keyEnd >= length) break;
+
+    // Extract key (avoid toString for common keys)
+    const key = data.toString('utf8', offset, keyEnd);
+    offset = keyEnd + 1;
+
+    // Find next null byte (value end)
+    const valueEnd = data.indexOf(0, offset);
+    if (valueEnd === -1 || valueEnd >= length) break;
+
+    // Extract value
+    const value = data.toString('utf8', offset, valueEnd);
+    offset = valueEnd + 1;
+
+    params[key] = value;
+  }
+
+  return params;
+}
+
+/**
+ * Fast path: Extract database name without parsing all parameters
+ * PERFORMANCE: ~3x faster than full parse
+ *
+ * @param {Buffer} data - Startup message buffer
+ * @param {number} offset - Start offset (after header)
+ * @param {number} length - Total message length
+ * @returns {string|null} Database name or null
+ */
+function extractDatabaseFast(data, offset, length) {
+  // Search for "database\0" key
+  while (offset < length - 1) {
+    // Find next null byte
+    const nullPos = data.indexOf(0, offset);
+    if (nullPos === -1 || nullPos >= length) break;
+
+    const keyLength = nullPos - offset;
+
+    // Check if this is the "database" key (compare bytes directly)
+    if (keyLength === 8 && data[offset] === 0x64 /* 'd' */) {
+      // Quick byte comparison for "database"
+      if (
+        data[offset + 1] === 0x61 && // 'a'
+        data[offset + 2] === 0x74 && // 't'
+        data[offset + 3] === 0x61 && // 'a'
+        data[offset + 4] === 0x62 && // 'b'
+        data[offset + 5] === 0x61 && // 'a'
+        data[offset + 6] === 0x73 && // 's'
+        data[offset + 7] === 0x65 // 'e'
+      ) {
+        // Found "database" key, extract value
+        offset = nullPos + 1;
+        const valueEnd = data.indexOf(0, offset);
+        if (valueEnd === -1 || valueEnd >= length) return null;
+
+        return data.toString('utf8', offset, valueEnd);
+      }
+    }
+
+    // Skip to next key-value pair
+    offset = nullPos + 1;
+    const valueEnd = data.indexOf(0, offset);
+    if (valueEnd === -1) break;
+    offset = valueEnd + 1;
+  }
+
+  return null;
+}
+
+/**
+ * Extract database name from startup message
+ *
+ * @param {Buffer} data - Raw startup message data
+ * @returns {string} Database name (defaults to 'postgres')
+ */
+export function extractDatabaseName(data) {
+  try {
+    const params = parseStartupMessage(data);
+    return params.database || 'postgres';
+  } catch (error) {
+    console.warn('Failed to parse startup message:', error.message);
+    return 'postgres'; // Fallback to default
+  }
+}
+
+/**
+ * Read startup message from socket and buffer it
+ *
+ * @param {net.Socket} socket - TCP socket
+ * @returns {Promise<{message: Buffer, allData: Buffer}>} Startup message and all buffered data
+ */
+export async function readStartupMessage(socket) {
+  return new Promise((resolve, reject) => {
+    let buffer = Buffer.alloc(0);
+    let expectedLength = null;
+    let resolved = false;
+
+    const onData = (chunk) => {
+      if (resolved) return;
+
+      buffer = Buffer.concat([buffer, chunk]);
+
+      // Read expected length from first 4 bytes
+      if (expectedLength === null && buffer.length >= 4) {
+        expectedLength = buffer.readInt32BE(0);
+      }
+
+      // Check if we have full message
+      if (expectedLength !== null && buffer.length >= expectedLength) {
+        resolved = true;
+        socket.removeListener('data', onData);
+        socket.removeListener('error', onError);
+
+        const message = buffer.slice(0, expectedLength);
+        resolve({ message, allData: buffer });
+      }
+    };
+
+    const onError = (error) => {
+      if (resolved) return;
+      resolved = true;
+      socket.removeListener('data', onData);
+      socket.removeListener('error', onError);
+      reject(error);
+    };
+
+    socket.on('data', onData);
+    socket.on('error', onError);
+
+    // Timeout after 5 seconds
+    setTimeout(() => {
+      if (resolved) return;
+      resolved = true;
+      socket.removeListener('data', onData);
+      socket.removeListener('error', onError);
+      reject(new Error('Timeout reading startup message'));
+    }, 5000);
+  });
+}
+
+/**
+ * Extract database name from socket connection (with SSL negotiation support)
+ *
+ * @param {net.Socket} socket - TCP socket
+ * @returns {Promise<{dbName: string, buffered: Buffer}>} Database name and buffered data
+ */
+export async function extractDatabaseNameFromSocket(socket) {
+  let { message, allData } = await readStartupMessage(socket);
+
+  // Check if this is an SSL request
+  if (message.length >= 8) {
+    const version = message.readInt32BE(4);
+
+    if (version === SSL_REQUEST_CODE) {
+      // Respond with 'N' (no SSL support)
+      socket.write(Buffer.from('N'));
+
+      // Read the actual startup message
+      const result = await readStartupMessage(socket);
+      message = result.message;
+      allData = result.allData;
+    }
+  }
+
+  const dbName = extractDatabaseName(message);
+  return { dbName, buffered: allData };
+}

package/src/registry.js

@@ -0,0 +1,134 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const REGISTRY_DIR = path.join(os.homedir(), '.pglite-server');
+const REGISTRY_FILE = path.join(REGISTRY_DIR, 'registry.json');
+
+/**
+ * Ensure registry directory exists
+ */
+function ensureRegistryDir() {
+  if (!fs.existsSync(REGISTRY_DIR)) {
+    fs.mkdirSync(REGISTRY_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Load registry from disk
+ */
+export function loadRegistry() {
+  ensureRegistryDir();
+
+  if (!fs.existsSync(REGISTRY_FILE)) {
+    return { instances: {} };
+  }
+
+  try {
+    const data = fs.readFileSync(REGISTRY_FILE, 'utf-8');
+    return JSON.parse(data);
+  } catch (error) {
+    console.warn('Failed to load registry, creating new:', error.message);
+    return { instances: {} };
+  }
+}
+
+/**
+ * Save registry to disk
+ */
+export function saveRegistry(registry) {
+  ensureRegistryDir();
+  fs.writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2), 'utf-8');
+}
+
+/**
+ * Register a new instance
+ */
+export function registerInstance(dataDir, port, pid) {
+  const registry = loadRegistry();
+
+  registry.instances[dataDir] = {
+    port,
+    pid,
+    started: new Date().toISOString(),
+    version: '17.5' // PGlite version
+  };
+
+  saveRegistry(registry);
+}
+
+/**
+ * Unregister an instance
+ */
+export function unregisterInstance(dataDir) {
+  const registry = loadRegistry();
+  delete registry.instances[dataDir];
+  saveRegistry(registry);
+}
+
+/**
+ * Find instance by data directory
+ */
+export function findInstanceByDataDir(dataDir) {
+  const registry = loadRegistry();
+  return registry.instances[dataDir] || null;
+}
+
+/**
+ * Find instance by port
+ */
+export function findInstanceByPort(port) {
+  const registry = loadRegistry();
+
+  for (const [dataDir, instance] of Object.entries(registry.instances)) {
+    if (instance.port === port) {
+      return { dataDir, ...instance };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * List all instances
+ */
+export function listInstances() {
+  const registry = loadRegistry();
+  return Object.entries(registry.instances).map(([dataDir, instance]) => ({
+    dataDir,
+    ...instance
+  }));
+}
+
+/**
+ * Check if process is running
+ */
+export function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Cleanup stale instances (process not running)
+ */
+export function cleanupStaleInstances() {
+  const registry = loadRegistry();
+  let cleaned = 0;
+
+  for (const [dataDir, instance] of Object.entries(registry.instances)) {
+    if (!isProcessRunning(instance.pid)) {
+      delete registry.instances[dataDir];
+      cleaned++;
+    }
+  }
+
+  if (cleaned > 0) {
+    saveRegistry(registry);
+  }
+
+  return cleaned;
+}

package/src/router.js

@@ -0,0 +1,289 @@
+/**
+ * Multi-Tenant Router (Performance Optimized)
+ *
+ * Single TCP server that routes connections to different PGlite instances
+ * based on database name from PostgreSQL connection string
+ *
+ * Performance Optimizations:
+ * - Pino logger (5x faster than console.log)
+ * - TCP socket optimizations (nodelay, keepalive)
+ * - Minimal event emitter overhead
+ * - Optimized connection tracking
+ */
+
+import net from 'net';
+import { PGLiteSocketHandler } from '@electric-sql/pglite-socket';
+import { InstancePool } from './pool.js';
+import { extractDatabaseNameFromSocket } from './protocol.js';
+import { EventEmitter } from 'events';
+import pino from 'pino';
+
+/**
+ * Multi-Tenant Router Server
+ */
+export class MultiTenantRouter extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.port = options.port || 8432;
+    this.host = options.host || '127.0.0.1';
+    this.baseDir = options.baseDir || './data';
+    this.memoryMode = options.memoryMode || false;
+    this.maxInstances = options.maxInstances || 100;
+    this.autoProvision = options.autoProvision !== false;
+    this.inspect = options.inspect || false;
+
+    // Pino logger (ultra-fast structured logging)
+    const logLevel = options.logLevel || 'info';
+    this.logger = options.logger || pino({
+      level: logLevel,
+      transport: logLevel === 'debug' ? {
+        target: 'pino-pretty',
+        options: { colorize: true }
+      } : undefined
+    });
+
+    // Instance pool
+    this.pool = new InstancePool({
+      baseDir: this.baseDir,
+      memoryMode: this.memoryMode,
+      maxInstances: this.maxInstances,
+      autoProvision: this.autoProvision,
+      logger: this.logger.child({ component: 'pool' })
+    });
+
+    // TCP server
+    this.server = null;
+    this.connections = new Set();
+
+    // Performance: Reduce event listener overhead
+    this.setMaxListeners(this.maxInstances + 10);
+
+    // Forward pool events (optimized logging)
+    this.pool.on('instance-created', (dbName) => {
+      this.logger.info({ dbName }, 'Database created');
+      this.emit('database-created', dbName);
+    });
+
+    this.pool.on('instance-locked', (dbName) => {
+      this.logger.debug({ dbName }, 'Database locked');
+    });
+
+    this.pool.on('instance-unlocked', (dbName) => {
+      this.logger.debug({ dbName }, 'Database unlocked');
+    });
+  }
+
+  /**
+   * Optimize TCP socket for PostgreSQL wire protocol
+   * @param {net.Socket} socket - TCP socket to optimize
+   */
+  optimizeSocket(socket) {
+    // Disable Nagle's algorithm for lower latency
+    socket.setNoDelay(true);
+
+    // Enable TCP keepalive (detect dead connections)
+    socket.setKeepAlive(true, 60000); // 60s initial delay
+
+    // Increase socket buffer sizes for better throughput
+    // Note: These are hints to OS, actual values may differ
+    try {
+      socket.setRecvBufferSize && socket.setRecvBufferSize(128 * 1024); // 128KB
+      socket.setSendBufferSize && socket.setSendBufferSize(128 * 1024); // 128KB
+    } catch (err) {
+      // Ignore if not supported
+      this.logger.debug({ err }, 'Could not set socket buffer sizes');
+    }
+
+    // Prevent socket timeout during long-running queries
+    socket.setTimeout(0);
+  }
+
+  /**
+   * Start multi-tenant router
+   */
+  async start() {
+    return new Promise((resolve, reject) => {
+      // Create TCP server with optimizations
+      this.server = net.createServer({
+        // Performance: Allow half-open sockets (faster cleanup)
+        allowHalfOpen: false,
+        // Performance: Pause on connect (manual resume after setup)
+        pauseOnConnect: true
+      }, async (socket) => {
+        await this.handleConnection(socket);
+      });
+
+      // Set max connections (system limit)
+      this.server.maxConnections = this.maxInstances * 2;
+
+      // Error handling
+      this.server.on('error', (error) => {
+        this.logger.error({ err: error }, 'Server error');
+        this.emit('error', error);
+      });
+
+      // Start listening
+      this.server.listen(this.port, this.host, () => {
+        this.logger.info({
+          host: this.host,
+          port: this.port,
+          baseDir: this.memoryMode ? '(in-memory)' : this.baseDir,
+          memoryMode: this.memoryMode,
+          autoProvision: this.autoProvision,
+          maxInstances: this.maxInstances
+        }, 'Multi-tenant router started');
+
+        this.emit('listening');
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Handle incoming connection (Performance Optimized)
+   */
+  async handleConnection(socket) {
+    const connId = `${socket.remoteAddress}:${socket.remotePort}`;
+    const startTime = Date.now();
+
+    // Optimize socket BEFORE any I/O
+    this.optimizeSocket(socket);
+
+    // Track connection
+    this.connections.add(socket);
+
+    // Resume socket (was paused on connect)
+    socket.resume();
+
+    let dbName = null;
+    let handler = null;
+
+    try {
+      // Extract database name from PostgreSQL handshake
+      this.logger.debug({ connId }, 'Reading startup message');
+      const { dbName: extractedDbName, buffered } = await extractDatabaseNameFromSocket(socket);
+      dbName = extractedDbName;
+
+      this.logger.info({ dbName, connId }, 'Connection request');
+
+      // Get or create PGlite instance (with locking)
+      const instance = await this.pool.acquire(dbName, socket);
+
+      const routingTime = Date.now() - startTime;
+      this.logger.info({
+        dbName,
+        connId,
+        dataDir: instance.dataDir,
+        routingTimeMs: routingTime
+      }, 'Routed to database');
+
+      // Push buffered data back to socket for handler to read
+      socket.unshift(buffered);
+
+      // Create handler for this connection
+      handler = new PGLiteSocketHandler({
+        db: instance.db,
+        closeOnDetach: true,
+        inspect: this.inspect
+      });
+
+      // Attach socket to handler
+      await handler.attach(socket);
+
+      this.logger.debug({ dbName, connId }, 'Socket attached');
+
+      // Handle socket close (cleanup)
+      const cleanup = () => {
+        this.logger.debug({ dbName, connId }, 'Connection closed');
+        if (handler) {
+          handler.detach();
+        }
+        this.connections.delete(socket);
+        // Note: Don't call socket.removeAllListeners() here as it removes
+        // the pool's unlock handlers before they can fire, causing stuck locks
+      };
+
+      socket.once('close', cleanup);
+      socket.once('error', (error) => {
+        this.logger.warn({ dbName, connId, err: error }, 'Socket error');
+        cleanup();
+      });
+
+      this.emit('connection', { dbName, socket, connId });
+    } catch (error) {
+      this.logger.error({ dbName, connId, err: error }, 'Connection error');
+
+      // Cleanup
+      if (handler) {
+        try {
+          handler.detach();
+        } catch (detachErr) {
+          this.logger.debug({ err: detachErr }, 'Error detaching handler');
+        }
+      }
+
+      socket.destroy(); // Force close on error
+      this.connections.delete(socket);
+      this.emit('connection-error', { error, dbName, connId });
+    }
+  }
+
+  /**
+   * Stop router (graceful shutdown)
+   */
+  async stop() {
+    this.logger.info('Stopping multi-tenant router');
+
+    // Close all connections gracefully
+    const activeConns = this.connections.size;
+    for (const socket of this.connections) {
+      socket.end(); // Graceful close (vs destroy())
+    }
+    this.connections.clear();
+
+    // Close TCP server
+    if (this.server) {
+      await new Promise((resolve) => {
+        this.server.close(resolve);
+      });
+    }
+
+    // Close all PGlite instances
+    await this.pool.closeAll();
+
+    this.logger.info({
+      activeConnections: activeConns,
+      closedInstances: this.pool.instances.size
+    }, 'Router stopped');
+
+    this.emit('stopped');
+  }
+
+  /**
+   * Get router stats
+   */
+  getStats() {
+    return {
+      port: this.port,
+      host: this.host,
+      activeConnections: this.connections.size,
+      pool: this.pool.getStats()
+    };
+  }
+
+  /**
+   * List all databases
+   */
+  listDatabases() {
+    return this.pool.list();
+  }
+}
+
+/**
+ * Start multi-tenant router (convenience function)
+ */
+export async function startMultiTenantServer(options = {}) {
+  const router = new MultiTenantRouter(options);
+  await router.start();
+  return router;
+}