pgserve 1.1.3-rc.7 → 1.1.3

package/.claude/context/windows-debug.md

@@ -0,0 +1,119 @@
+# Windows Debug Context
+
+## RESOLVED (2025-12-12)
+
+The Windows router binding issue has been fixed. See "Solution Applied" below.
+
+---
+
+## Original Issue
+PostgreSQL starts successfully on port 9432, but the router/proxy on port 8432 was NOT listening.
+Clients could not connect because 8432 wasn't bound.
+
+## Root Causes Found
+
+### 1. `reusePort: true` - Linux-only feature (PRIMARY CAUSE)
+**Location:** `src/cluster.js:75`
+
+The cluster mode uses `Bun.listen({ reusePort: true })` which maps to `SO_REUSEPORT`.
+This socket option is Linux-only and **silently fails on Windows**.
+
+### 2. Auto-enabled cluster mode on multi-core Windows systems
+**Location:** `bin/pglite-server.js:106`
+
+Windows systems with multiple CPU cores automatically entered cluster mode,
+triggering the `reusePort` failure.
+
+### 3. TCP port opens before PostgreSQL ready for protocol handshakes
+**Location:** `src/postgres.js:803-821`
+
+PostgreSQL was marked "ready" when TCP port opened, but it wasn't actually
+ready for protocol-level handshakes. Admin pool connection timed out.
+
+---
+
+## Solution Applied
+
+### Fix 1: Disable cluster mode on Windows
+**File:** `bin/pglite-server.js:98-108`
+```javascript
+const isWindows = os.platform() === 'win32';
+cluster: cpuCount > 1 && !isWindows,
+```
+
+### Fix 2: Add platform check to reusePort
+**File:** `src/cluster.js:72-76`
+```javascript
+const isWindows = os.platform() === 'win32';
+this.server = Bun.listen({
+  reusePort: !isWindows,  // SO_REUSEPORT only works on Linux/macOS
+  ...
+});
+```
+
+### Fix 3: Add port binding verification
+**File:** `src/cluster.js:99-102`
+```javascript
+if (!this.server || !this.server.port) {
+  throw new Error(`Failed to bind to port ${this.port} - reusePort may not be supported`);
+}
+```
+
+### Fix 4: Add Windows readiness delay
+**File:** `src/postgres.js:813-817`
+```javascript
+if (isWindows) {
+  await Bun.sleep(2000); // 2 second delay for Windows
+}
+```
+
+### Fix 5: Increase admin pool retry for Windows
+**File:** `src/postgres.js:598-599`
+```javascript
+const maxRetries = isWindows ? 10 : 5;
+const baseDelay = isWindows ? 2000 : 1000;
+```
+
+---
+
+## Verification
+
+After applying fixes, server runs correctly on Windows:
+- Router: `127.0.0.1:7432` ✅
+- PostgreSQL: `127.0.0.1:8432` ✅
+- Database auto-provisioning: ✅
+- Query execution: ✅
+
+```
+Server started successfully!
+
+  Endpoint:    postgresql://127.0.0.1:7432/<database>
+  Mode:        In-memory (ephemeral)
+  PostgreSQL:  Port 8432 (internal)
+  Auto-create: Enabled
+```
+
+---
+
+## Test Commands (Run from Windows)
+```cmd
+# Build binary
+bun build --compile bin/pglite-server.js --outfile dist/pgserve-windows-x64.exe
+
+# Start server
+dist\pgserve-windows-x64.exe
+
+# Check ports are listening (should see BOTH)
+netstat -an | findstr "LISTEN" | findstr "8432 9432"
+
+# Test connection
+psql postgresql://localhost:8432/testdb
+```
+
+---
+
+## Related Files
+- `bin/pglite-server.js` - Entry point, cluster mode decision
+- `src/cluster.js` - Cluster mode with reusePort
+- `src/router.js` - Single-process mode (works on Windows)
+- `src/postgres.js` - PostgreSQL startup and admin pool

package/.github/workflows/build-all-platforms.yml

@@ -70,21 +70,34 @@ jobs:
       - name: Install dependencies
         run: bun install
 
-      # Windows: native build with custom icon
-      - name: Build for Windows (with icon)
+      # Windows: native build with icon and proper metadata
+      - name: Build for Windows (with branding)
         if: matrix.platform == 'windows-x64'
         run: |
-          mkdir -p dist
-          bun build --compile --windows-icon=assets/icon.ico bin/pglite-server.js --outfile dist/${{ matrix.output }}
-          ls -lh dist/
-        shell: bash
+          New-Item -ItemType Directory -Force -Path dist | Out-Null
+          $RAW_VERSION = node -p "require('./package.json').version"
+          # Convert 1.1.3-rc.10 to 1.1.3.10 (Windows requires X.Y.Z.W format)
+          $WIN_VERSION = $RAW_VERSION -replace '-rc\.', '.'
+          Write-Host "Raw version: $RAW_VERSION -> Windows version: $WIN_VERSION"
+          bun build --compile `
+            --define BUILD_VERSION="'$RAW_VERSION'" `
+            --windows-icon=assets/icon.ico `
+            --windows-title="pgserve" `
+            --windows-publisher="Namastex Labs" `
+            --windows-description="Embedded PostgreSQL Server - Zero config, auto-provision, unlimited connections" `
+            --windows-version="$WIN_VERSION" `
+            --windows-copyright="Copyright (c) 2025 Namastex Labs" `
+            bin/pglite-server.js --outfile dist/${{ matrix.output }}
+          Get-ChildItem dist/
+        shell: pwsh
 
       # Linux/macOS: native build
       - name: Build for ${{ matrix.platform }}
         if: matrix.platform != 'windows-x64'
         run: |
           mkdir -p dist
-          bun build --compile bin/pglite-server.js --outfile dist/${{ matrix.output }}
+          VERSION=$(node -p "require('./package.json').version")
+          bun build --compile --define BUILD_VERSION="'$VERSION'" bin/pglite-server.js --outfile dist/${{ matrix.output }}
           ls -lh dist/
 
       - name: Upload artifact

package/bin/pglite-server.js

@@ -94,7 +94,9 @@ FEATURES:
  */
 function parseArgs() {
   // Auto-enable cluster mode on multi-core systems for best performance
+  // Note: Cluster mode uses SO_REUSEPORT which is not supported on Windows
   const cpuCount = os.cpus().length;
+  const isWindows = os.platform() === 'win32';
 
   const options = {
     port: 8432,
@@ -103,7 +105,7 @@ function parseArgs() {
     useRam: false, // Use /dev/shm for true RAM storage (Linux only)
     logLevel: 'info',
     autoProvision: true,
-    cluster: cpuCount > 1,  // Auto-enable on multi-core (use --no-cluster to disable)
+    cluster: cpuCount > 1 && !isWindows,  // Auto-enable on multi-core (disabled on Windows - no SO_REUSEPORT)
     workers: null, // null = use CPU count
     syncTo: null,  // Sync target PostgreSQL URL
     syncDatabases: null // Database patterns to sync (comma-separated)

package/eslint.config.js

@@ -24,6 +24,8 @@ export default [
         TextDecoder: 'readonly',
         TextEncoder: 'readonly',
         Response: 'readonly',
+        // Build-time constants (injected via --define)
+        BUILD_VERSION: 'readonly',
       },
     },
     rules: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "1.1.3-rc.7",
+  "version": "1.1.3",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",

package/src/cluster.js

@@ -69,10 +69,11 @@ class ClusterRouter extends EventEmitter {
 
     // Create TCP server using Bun.listen() for 2-3x throughput
     const router = this;
+    const isWindows = os.platform() === 'win32';
     this.server = Bun.listen({
       hostname: this.host,
       port: this.port,
-      reusePort: true,  // Enable SO_REUSEPORT for multi-worker port sharing (Linux)
+      reusePort: !isWindows,  // SO_REUSEPORT for multi-worker port sharing (Linux/macOS only)
       socket: {
         data(socket, data) {
           router.handleSocketData(socket, data);
@@ -95,6 +96,11 @@ class ClusterRouter extends EventEmitter {
       }
     });
 
+    // Verify port actually bound (detect silent failures on Windows)
+    if (!this.server || !this.server.port) {
+      throw new Error(`Failed to bind to port ${this.port} - reusePort may not be supported on this platform`);
+    }
+
     this.emit('listening');
   }
 

package/src/dashboard.js

@@ -13,12 +13,18 @@ import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
-// Get package version
+// Get package version - BUILD_VERSION is injected at compile time via --define
+// Falls back to reading package.json for development mode
 let version = '1.0.0';
 try {
-  const __dirname = dirname(fileURLToPath(import.meta.url));
-  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-  version = pkg.version;
+  // Check for build-time injected version first
+  if (typeof BUILD_VERSION !== 'undefined') {
+    version = BUILD_VERSION;
+  } else {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+    version = pkg.version;
+  }
 } catch {
   // Fallback version
 }

package/src/postgres.js

@@ -575,9 +575,11 @@ export class PostgresManager {
    */
   async _initAdminPool() {
     const { SQL } = await import('bun');
+    const isWindows = process.platform === 'win32';
 
     // Bun.sql config - uses TCP connections (Unix sockets not directly supported)
     // This is fine for admin queries (low volume, local connection)
+    // Windows needs longer timeout due to higher network stack latency
     this.adminPool = new SQL({
       hostname: '127.0.0.1',
       port: this.port,
@@ -586,16 +588,38 @@ export class PostgresManager {
       password: this.password,
       max: 5, // Small pool - only for CREATE DATABASE operations
       idleTimeout: 30,
-      connectionTimeout: 5,
+      connectionTimeout: isWindows ? 15 : 5,
     });
 
-    // Verify connection is working with a simple query
-    await this.adminPool`SELECT 1`;
+    // Verify connection with retry logic
+    // TCP port being open doesn't mean PostgreSQL protocol is ready
+    // This handles the race condition on Windows where the port binds
+    // before the server is fully ready to accept protocol handshakes
+    const maxRetries = isWindows ? 10 : 5;  // More retries on Windows
+    const baseDelay = isWindows ? 2000 : 1000; // Longer delay on Windows
 
-    this.logger.debug({
-      host: '127.0.0.1',
-      maxConnections: 5
-    }, 'Admin connection pool initialized (Bun.sql)');
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        await this.adminPool`SELECT 1`;
+        this.logger.debug({
+          host: '127.0.0.1',
+          maxConnections: 5,
+          attempt
+        }, 'Admin connection pool initialized (Bun.sql)');
+        return; // Success
+      } catch (err) {
+        if (attempt === maxRetries) {
+          throw new Error(`Failed to initialize admin pool after ${maxRetries} attempts: ${err.message}`);
+        }
+        this.logger.debug({
+          attempt,
+          maxRetries,
+          error: err.message
+        }, 'Admin pool connection failed, retrying...');
+        // Exponential backoff: 1s, 2s, 3s, 4s
+        await new Promise(resolve => setTimeout(resolve, baseDelay * attempt));
+      }
+    }
   }
 
   /**
@@ -667,8 +691,24 @@ export class PostgresManager {
 
       let started = false;
       let startupOutput = '';
+      let processExited = false;
+      let portBindingSeen = false;
+      const portStr = this.port.toString();
+
+      // Hybrid startup detection:
+      // 1. TCP connection polling (works on Linux/macOS)
+      // 2. Log-based detection (fallback for Windows where Bun.connect may fail)
+      // Whichever succeeds first wins
+
+      const markReady = (method) => {
+        if (!started) {
+          started = true;
+          this.logger.info({ port: this.port, method }, 'PostgreSQL ready');
+          resolve();
+        }
+      };
 
-      // Read stderr in streaming fashion to detect startup
+      // Read stderr - detect port binding in logs (locale-independent: just look for port number)
       const readStream = async (stream) => {
         const reader = stream.getReader();
         const decoder = new TextDecoder();
@@ -680,11 +720,16 @@ export class PostgresManager {
             startupOutput += message;
             this.logger.debug({ pgOutput: message.trim() }, 'PostgreSQL output');
 
-            // Check for ready message
-            if (!started && (message.includes('database system is ready to accept connections') ||
-                message.includes('ready to accept connections'))) {
-              started = true;
-              resolve();
+            // Detect port binding - look for our port number in log output
+            // This is locale-independent (numbers are universal)
+            if (!portBindingSeen && message.includes(portStr)) {
+              portBindingSeen = true;
+              // Give PostgreSQL 500ms after port binding to finish startup
+              setTimeout(() => {
+                if (!started && !processExited) {
+                  markReady('log-port-binding');
+                }
+              }, 500);
             }
           }
         } catch {
@@ -698,16 +743,97 @@ export class PostgresManager {
 
       // Handle process exit
       this.process.exited.then((code) => {
+        processExited = true;
         if (!started) {
           reject(new Error(`PostgreSQL exited with code ${code} before starting: ${startupOutput}`));
         }
         this.process = null;
       });
 
-      // Timeout after 30 seconds
+      // Method 1: TCP connection polling (preferred, works on Linux/macOS)
+      const tryConnect = () => {
+        return new Promise((resolveConn, rejectConn) => {
+          let resolved = false;
+          const timeout = setTimeout(() => {
+            if (!resolved) {
+              resolved = true;
+              rejectConn(new Error('Connection timeout'));
+            }
+          }, 500);
+
+          Bun.connect({
+            hostname: '127.0.0.1',
+            port: this.port,
+            socket: {
+              open(socket) {
+                if (!resolved) {
+                  resolved = true;
+                  clearTimeout(timeout);
+                  socket.end();
+                  resolveConn(true);
+                }
+              },
+              connectError(_socket, error) {
+                if (!resolved) {
+                  resolved = true;
+                  clearTimeout(timeout);
+                  rejectConn(error);
+                }
+              },
+              error(_socket, error) {
+                if (!resolved) {
+                  resolved = true;
+                  clearTimeout(timeout);
+                  rejectConn(error);
+                }
+              },
+              data() {},
+              close() {},
+            },
+          }).catch((err) => {
+            if (!resolved) {
+              resolved = true;
+              clearTimeout(timeout);
+              rejectConn(err);
+            }
+          });
+        });
+      };
+
+      const pollConnection = async () => {
+        const startTime = Date.now();
+        const timeoutMs = 30000;
+        const isWindows = process.platform === 'win32';
+
+        while (Date.now() - startTime < timeoutMs && !started) {
+          if (processExited) return;
+
+          try {
+            await tryConnect();
+            // On Windows, TCP port opens before PostgreSQL is fully ready for protocol handshakes
+            // Add delay to let PostgreSQL complete its startup sequence
+            if (isWindows) {
+              await Bun.sleep(2000); // 2 second delay for Windows
+            }
+            markReady('tcp');
+            return;
+          } catch {
+            await Bun.sleep(200);
+          }
+        }
+      };
+
+      // Start TCP polling (log detection is handled inline above via setTimeout)
+      pollConnection();
+
+      // Overall timeout with helpful error for Windows firewall
       setTimeout(() => {
-        if (!started) {
-          reject(new Error(`PostgreSQL startup timed out after 30s. Output: ${startupOutput}`));
+        if (!started && !processExited) {
+          const isWindows = process.platform === 'win32';
+          const hint = isWindows
+            ? '\n\nOn Windows, this may be caused by Windows Firewall blocking localhost connections.\nTry: netsh advfirewall firewall add rule name="pgserve" dir=in action=allow protocol=TCP localport=' + this.port
+            : '';
+          reject(new Error(`PostgreSQL startup timed out after 30s.${hint}\n\nOutput: ${startupOutput}`));
         }
       }, 30000);
     });