Allow OS to assign port automatically (#750)

* Allow OS to assign port automatically

* PR feedback

* formating

* Add port 0 usage documentation to README

Author: 2xic

packages/pglite-socket/README.md

@@ -58,7 +58,7 @@ Creates a TCP server that allows PostgreSQL clients to connect to a PGlite datab
 #### Options
 
 - `db: PGlite` - The PGlite database instance
-- `port?: number` - The port to listen on (default: 5432)
+- `port?: number` - The port to listen on (default: 5432). Use port 0 to let the OS assign an available port
 - `host?: string` - The host to bind to (default: 127.0.0.1)
 - `path?: string` - Unix socket path to bind to (takes precedence over host:port)
 - `inspect?: boolean` - Print the incoming and outgoing data to the console (default: false)
@@ -156,7 +156,7 @@ pglite-server --help
 ### CLI Options
 
 - `-d, --db=PATH` - Database path (default: memory://)
-- `-p, --port=PORT` - Port to listen on (default: 5432)
+- `-p, --port=PORT` - Port to listen on (default: 5432). Use 0 to let the OS assign an available port
 - `-h, --host=HOST` - Host to bind to (default: 127.0.0.1)
 - `-u, --path=UNIX` - Unix socket to bind to (takes precedence over host:port)
 - `-v, --debug=LEVEL` - Debug level 0-5 (default: 0)

packages/pglite-socket/src/index.ts

@@ -371,7 +371,12 @@ export class PGLiteSocketServer extends EventTarget {
     if (options.path) {
       this.path = options.path
     } else {
-      this.port = options.port || 5432
+      if (typeof options.port === 'number') {
+        // Keep port undefined on port 0, will be set by the OS when we start the server.
+        this.port = options.port ?? options.port
+      } else {
+        this.port = 5432
+      }
       this.host = options.host || '127.0.0.1'
     }
     this.inspect = options.inspect ?? false
@@ -429,7 +434,15 @@ export class PGLiteSocketServer extends EventTarget {
           resolve()
         })
       } else {
-        this.server.listen(this.port, this.host, () => {
+        const server = this.server
+        server.listen(this.port, this.host, () => {
+          const address = server.address()
+          // We are not using pipes, so return type should be AddressInfo
+          if (address === null || typeof address !== 'object') {
+            throw Error('Expected address info')
+          }
+          // Assign the new port number
+          this.port = address.port
           this.log(`start: server listening on ${this.getServerConn()}`)
           this.dispatchEvent(
             new CustomEvent('listening', {

packages/pglite-socket/tests/index.test.ts

@@ -476,6 +476,37 @@ testSocket(async (connOptions) => {
         // Queue should be emptied
         expect((server as any).connectionQueue).toHaveLength(0)
       })
+
+      it('should start server with OS-assigned port when port is 0', async () => {
+        server = new PGLiteSocketServer({
+          db,
+          host: connOptions.host,
+          port: 0, // Let OS assign port
+        })
+
+        await server.start()
+        const assignedPort = (server as any).port
+        expect(assignedPort).toBeGreaterThan(1024)
+
+        // Try to connect to confirm server is running
+        const client = createConnection({
+          port: assignedPort,
+          host: connOptions.host,
+        })
+
+        await new Promise<void>((resolve, reject) => {
+          client.on('error', () => {
+            reject(new Error('Connection should have failed'))
+          })
+          client.on('connect', () => {
+            client.end()
+            resolve()
+          })
+          setTimeout(resolve, 100)
+        })
+
+        await server.stop()
+      })
     })
   })
 })