postgrejs 3.13.0 → 3.14.0

package/README.md

@@ -98,6 +98,32 @@ Each adapter hands the compiled SQL straight to this client, with no `pg` left a
 compared query by query against the driver it replaces - and, where the project ships a suite of its own, run
 against that too. So adopting one is a change to how the connection is created and nothing else.
 
+### 🌍 Runs Where You Run
+
+<!-- Same card shape as the adapters above, for the same reason: GitHub strips CSS, and a table
+     is the one layout that survives everywhere the README is read. -->
+<table>
+  <tr>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.postgrejs.com/docs/getting-started/benchmarks"><img src="https://www.postgrejs.com/img/nodejs-logo.svg" alt="Node.js" height="46"></a><br><br>
+      <b><a href="https://www.postgrejs.com/docs/getting-started/benchmarks">Node.js</a></b><br>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.postgrejs.com/docs/getting-started/benchmarks-bun"><img src="https://www.postgrejs.com/img/bun-logo.svg" alt="Bun" height="46"></a><br><br>
+      <b><a href="https://www.postgrejs.com/docs/getting-started/benchmarks-bun">Bun</a></b><br>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.postgrejs.com/docs/guides/cloudflare-workers"><img src="https://www.postgrejs.com/img/cloudflare-logo.svg" alt="Cloudflare Workers" height="46"></a><br><br>
+      <b><a href="https://www.postgrejs.com/docs/guides/cloudflare-workers">Cloudflare Workers</a></b><br>
+    </td>
+  </tr>
+</table>
+
+Node and Bun run **the same test suite** in CI on every push - Node across 20, 22, 24 and 26 against PostgreSQL 12,
+16 and 18, Bun against 18 - so neither is a target that merely ought to work. Workers is not in that matrix yet: it
+was measured by hand against PostgreSQL 18, a plain connection and a TLS one, and what the runtime does and does not
+allow is written down in [doc/CLOUDFLARE-WORKERS.md](doc/CLOUDFLARE-WORKERS.md).
+
 ## Installation
 
 ```bash
@@ -133,6 +159,7 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
 | Packages to install               |           1            |    4 <sup>1</sup>     |        1         |
 | Module system                     |          ESM           |        ESM/CJS        |     ESM/CJS      |
 | Language                          |           TS           |    JS <sup>2</sup>    | JS <sup>3</sup>  |
+| Cloudflare Workers                |    ✅ <sup>28</sup>    |   🟡 <sup>29</sup>    | ✅ <sup>30</sup> |
 | ***Wire protocol***               |                        |                       |                  |
 | Protocol version                  |          3.2           |          3.0          |       3.0        |
 | Simple Query protocol             |           ✅           |          ✅           |        ✅        |
@@ -271,6 +298,25 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
   input parser is what sorts and deduplicates a vector and what defines a query's grammar, so encoding either here
   would make the same text mean one thing written as a literal and another bound as a parameter. They are sent as
   text instead, which is exact.
+- <sup>28</sup> PostgreJS runs on workerd under `nodejs_compat` with nothing installed and no build of its own.
+  Measured end to end: a plain connection against PostgreSQL 18, and a TLS one against a managed PostgreSQL 18 whose
+  certificate comes from Let's Encrypt - the same server refusing the connection outright (`28000 connection is
+  insecure`) when `sslmode` is dropped, which is what makes the encrypted one mean something. TLS opens a socket of
+  the runtime's own and upgrades it with `startTls()`, since `tls.connect({ socket })` is not something workerd can
+  carry out. Three limits are the runtime's, and all three libraries have them: `ca`, `cert` and `rejectUnauthorized`
+  have nowhere to go (workerd's TLS options are `{ expectedServerHostname?: string }`, so a self-signed certificate
+  cannot be trusted and a local server cannot be reached over TLS at all); `sslnegotiation=direct` cannot announce the
+  `postgresql` ALPN protocol, and is refused by name here; and SCRAM channel binding has no server certificate to bind
+  to, so `channelBinding: 'require'` is refused and the default `prefer` authenticates without it. Hyperdrive is the
+  other way in, terminating TLS in Cloudflare's own network - checked here against its binding. See
+  [doc/CLOUDFLARE-WORKERS.md](doc/CLOUDFLARE-WORKERS.md).
+- <sup>29</sup> pg reaches workerd through `pg-cloudflare`, a separate package it carries as an optional dependency
+  and selects at runtime (`lib/stream.js`, on `navigator.userAgent`). That package wraps `cloudflare:sockets` and
+  upgrades with its own `startTls()`, so TLS is available where PostgreJS's is not - at the cost of a second package
+  and of nothing happening at all if it was not installed.
+- <sup>30</sup> postgres.js ships a build for the runtime: a `workerd` condition in `exports` pointing at `cf/`, whose
+  polyfills shim `net`/`tls` onto `cloudflare:sockets` including `startTls({ servername })`. One package, the right
+  code chosen by the resolver, TLS included.
 
 ## Benchmarks
 
@@ -302,6 +348,9 @@ you open an issue please provide version of NodeJS and PostgreSQL server.
 - Bun - the same test suite runs under Bun in CI against PostgreSQL 18 on every push, so Bun is a supported target
   rather than an untested coincidence. (Coverage is collected on the Node matrix only: `c8` instruments V8's
   coverage APIs, which JavaScriptCore doesn't have.)
+- Cloudflare Workers - with `nodejs_compat`, and without TLS: the runtime has no way to trust a server
+  certificate, so a database behind TLS is reached through Hyperdrive instead. See
+  [doc/CLOUDFLARE-WORKERS.md](doc/CLOUDFLARE-WORKERS.md).
 
 ## License
 

package/constants.d.ts

@@ -1,6 +1,6 @@
 import { Protocol } from './protocol/protocol.js';
 import DataFormat = Protocol.DataFormat;
-export declare const version = "3.13.0";
+export declare const version = "3.14.0";
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/constants.js

@@ -2,7 +2,7 @@ import { Protocol } from './protocol/protocol.js';
 var DataFormat = Protocol.DataFormat;
 // @ts-ignore
 Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
-export const version = '3.13.0';
+export const version = '3.14.0';
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {

package/protocol/pg-socket.d.ts

@@ -1,4 +1,3 @@
-import net from 'node:net';
 import tls from 'node:tls';
 import { ConnectionState } from '../constants.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
@@ -20,6 +19,29 @@ export interface SocketError extends Error {
  * is asked for, and a queue that pairs each response with whoever sent
  * the statement that caused it.
  */
+/**
+ * What this client needs a socket to be, whoever provides one.
+ *
+ * `net.Socket`, its TLS upgrade, and `WorkerdSocket` all satisfy it.
+ */
+interface ClientSocket {
+    readonly destroyed: boolean;
+    readonly writable: boolean;
+    write(data: any, cb?: (err?: Error | null) => void): boolean;
+    destroy(err?: Error): any;
+    end(...args: any[]): any;
+    pause(): any;
+    resume(): any;
+    cork(): void;
+    uncork(): void;
+    setNoDelay(enable?: boolean): any;
+    setKeepAlive(enable?: boolean): any;
+    setTimeout(ms: number, cb?: () => void): any;
+    connect(...args: any[]): any;
+    on(event: string, listener: (...args: any[]) => void): any;
+    once(event: string, listener: (...args: any[]) => void): any;
+    removeAllListeners(event?: string): any;
+}
 export declare class PgSocket extends SafeEventEmitter {
     options: ConnectionConfiguration;
     private _state;
@@ -29,6 +51,7 @@ export declare class PgSocket extends SafeEventEmitter {
      * bare. Cleared by _reset().
      */
     private _closeReason?;
+    /** Whichever kind of socket this runtime connects with. */
     private _socket?;
     private _backend;
     private _frontend;
@@ -65,10 +88,10 @@ export declare class PgSocket extends SafeEventEmitter {
      * afterwards. Resolves `onReady` with whichever socket ends up ready to
      * speak the PostgreSQL protocol: the plain one, or its TLS upgrade.
      */
-    protected _negotiateTls(socket: net.Socket, target: {
+    protected _negotiateTls(socket: ClientSocket, target: {
         host: string;
         port?: number;
-    }, onReady: (socket: net.Socket | tls.TLSSocket) => void, onError: (err: Error) => void): void;
+    }, onReady: (socket: ClientSocket) => void, onError: (err: Error) => void): void;
     /**
      * Asks the server to cancel whatever this session is currently running.
      *
@@ -337,3 +360,4 @@ export declare class PgSocket extends SafeEventEmitter {
      */
     protected _sendCopy(data: Buffer | Buffer[], cb?: Callback): boolean;
 }
+export {};

package/protocol/pg-socket.js

@@ -6,6 +6,7 @@ import DoublyLinked from 'doublylinked';
 import promisify from 'putil-promisify';
 import { ConnectionState } from '../constants.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
+import { isWorkerd } from '../util/runtime.js';
 import { Backend } from './backend.js';
 import { signatureHashOfCertificate } from './cert-signature.js';
 import { ConnectionLostError } from './connection-lost-error.js';
@@ -13,13 +14,20 @@ import { DatabaseError } from './database-error.js';
 import { Frontend } from './frontend.js';
 import { Protocol } from './protocol.js';
 import { SASL } from './sasl.js';
+import { WorkerdSocket } from './workerd-socket.js';
 const DEFAULT_PORT_NUMBER = 5432;
 const COMMAND_RESULT_PATTERN = /^([^\d]+)(?: (\d+)(?: (\d+))?)?$/;
 /**
- * The connected socket: the handshake, the authentication, TLS where it
- * is asked for, and a queue that pairs each response with whoever sent
- * the statement that caused it.
+ * Whether a connection is going to ask for TLS at all.
+ *
+ * @param options The connection's own options.
+ * @returns True when any of the three ways of asking is set.
  */
+/* Read in two places that have to agree: which socket to open, and
+   whether to negotiate once it is open. */
+function wantsTls(options) {
+    return (!!options.ssl || !!options.requireSSL || options.sslNegotiation === 'direct');
+}
 export class PgSocket extends SafeEventEmitter {
     options;
     _state = ConnectionState.CLOSED;
@@ -29,6 +37,7 @@ export class PgSocket extends SafeEventEmitter {
      * bare. Cleared by _reset().
      */
     _closeReason;
+    /** Whichever kind of socket this runtime connects with. */
     _socket;
     _backend = new Backend();
     _frontend;
@@ -86,7 +95,17 @@ export class PgSocket extends SafeEventEmitter {
         this._sessionAttrsChecked = false;
         this._state = ConnectionState.CONNECTING;
         const target = this._hosts[this._hostIndex];
-        const socket = (this._socket = new net.Socket());
+        /* Workerd cannot upgrade a `net.Socket`, and the socket that can be
+           upgraded has to be opened as one from the start - `secureTransport:
+           'starttls'` is a connect-time choice, not a later one. So the kind
+           of socket is decided here, by whether TLS is going to be asked for
+           at all. The plain path stays on `node:net`, which works there. */
+        const socket = (this._socket =
+            isWorkerd() &&
+                wantsTls(this.options) &&
+                this.options.sslNegotiation !== 'direct'
+                ? new WorkerdSocket(true)
+                : new net.Socket());
         const errorHandler = (err) => {
             this._state = ConnectionState.CLOSED;
             this._removeListeners();
@@ -133,7 +152,14 @@ export class PgSocket extends SafeEventEmitter {
     _negotiateTls(socket, target, onReady, onError) {
         const options = this.options;
         const startTls = () => {
-            const tlsOptions = { ...options.ssl, socket };
+            /* Only ever reached off workerd - the branch below hands that
+               runtime to its own upgrade - so the socket here is the
+               `net.Socket` `tls.connect()` wants, which the structural type
+               cannot say on its own. */
+            const tlsOptions = {
+                ...options.ssl,
+                socket: socket,
+            };
             if (target.host && net.isIP(target.host) === 0)
                 tlsOptions.servername = target.host;
             if (options.sslNegotiation === 'direct')
@@ -142,11 +168,51 @@ export class PgSocket extends SafeEventEmitter {
             tlsSocket.once('error', onError);
             tlsSocket.once('secureConnect', () => onReady(tlsSocket));
         };
-        const wantsSSL = !!options.ssl ||
-            !!options.requireSSL ||
-            options.sslNegotiation === 'direct';
-        if (!wantsSSL)
+        if (!wantsTls(options))
             return onReady(socket);
+        /* Workerd upgrades through the socket it already has rather than by
+           wrapping it: `tls.connect({ socket })` does nothing it can carry
+           out, and measured, attempting it answers "Network connection
+           lost." after the server has already agreed to TLS. The exchange
+           either side of the upgrade is the same one as below - this branch
+           exists because the call in the middle is a different call.
+    
+           One limit is the runtime's and no client escapes it: workerd's TLS
+           options are `{ expectedServerHostname?: string }` and nothing
+           else, so nothing here can say which certificate to trust, and a
+           server whose certificate does not chain to a public CA cannot be
+           reached over TLS at all - which is every local PostgreSQL with a
+           self-signed certificate. */
+        /* Direct negotiation is TLS from the first byte, and PostgreSQL 17
+           only accepts it when the client announces the `postgresql`
+           protocol over ALPN. Workerd's socket options are
+           `{ secureTransport, allowHalfOpen }` - there is nowhere to say it,
+           and the server answers by closing, which surfaces as an internal
+           error with a reference number. Refused by name instead. */
+        if (isWorkerd() && options.sslNegotiation === 'direct')
+            return onError(new Error('sslNegotiation "direct" is not available on Cloudflare Workers: it needs the ' +
+                '"postgresql" ALPN protocol, which the runtime offers no way to announce. ' +
+                'Leave sslNegotiation unset to negotiate with SSLRequest instead.'));
+        if (socket instanceof WorkerdSocket) {
+            const upgrade = () => {
+                socket.once('error', onError);
+                socket.once('secureConnect', () => onReady(socket));
+                socket.startTls(target.host && net.isIP(target.host) === 0 ? target.host : undefined);
+            };
+            socket.write(this._frontend.getSSLRequestMessage());
+            socket.readOnce((x) => {
+                const command = x?.toString();
+                if (command === 'S')
+                    return upgrade();
+                if (command === 'N') {
+                    if (options.requireSSL)
+                        return onError(new Error('Server does not support SSL connections'));
+                    return onReady(socket);
+                }
+                onError(new Error('Unexpected response from server: ' + command));
+            });
+            return;
+        }
         if (options.sslNegotiation === 'direct') {
             // Straight into the handshake: no SSLRequest, nothing in the clear.
             return startTls();
@@ -825,15 +891,28 @@ export class PgSocket extends SafeEventEmitter {
                 break;
             case Protocol.AuthenticationMessageKind.SASL: {
                 const mode = this.options.channelBinding || 'prefer';
+                /* Encrypted and "can be bound to" are two questions on workerd,
+                   where they are one on Node. Binding mixes a hash of the
+                   server's certificate into the SCRAM proof, and that runtime
+                   hands out no certificate - so a connection can be perfectly
+                   secure there and still have nothing to bind to. Saying "not
+                   using TLS" for it, which is what the one test used to answer,
+                   sends the reader looking in the wrong place. */
+                const secure = this._socket instanceof tls.TLSSocket ||
+                    (this._socket instanceof WorkerdSocket && this._socket.secure);
                 const tlsSocket = mode !== 'disable' && this._socket instanceof tls.TLSSocket
                     ? this._socket
                     : undefined;
                 const offersBinding = !!msg.mechanisms?.includes('SCRAM-SHA-256-PLUS');
                 const useBinding = !!tlsSocket && offersBinding;
                 if (mode === 'require' && !useBinding) {
-                    throw new Error(tlsSocket
-                        ? 'SASL: channelBinding is "require" but the server does not offer SCRAM-SHA-256-PLUS'
-                        : 'SASL: channelBinding is "require" but the connection is not using TLS');
+                    throw new Error(!secure
+                        ? 'SASL: channelBinding is "require" but the connection is not using TLS'
+                        : !tlsSocket
+                            ? 'SASL: channelBinding is "require", but this runtime does not expose the ' +
+                                'server certificate, so there is nothing to bind to. Cloudflare Workers is ' +
+                                'one; use "prefer", which is the default.'
+                            : 'SASL: channelBinding is "require" but the server does not offer SCRAM-SHA-256-PLUS');
                 }
                 if (!useBinding && !msg.mechanisms?.includes('SCRAM-SHA-256')) {
                     throw new Error('SASL: Only mechanisms SCRAM-SHA-256 and SCRAM-SHA-256-PLUS are supported');

package/protocol/smart-buffer.d.ts

@@ -9,11 +9,12 @@ export interface SmartBufferConfig {
     houseKeepMs?: number;
 }
 /**
- * Adds the PostgreSQL wire format's two string encodings on top of
- * flexy-buffer's `FlexyBuffer`: a NUL-terminated C string, and a
- * length-prefixed string where a `null`/`undefined` value is written as a
- * length of -1 with no bytes following.
+ * The most a buffer may ever hold, given how much memory the machine has.
+ *
+ * @param totalMemory Bytes of memory, or 0 when that cannot be known.
+ * @returns Half of it, capped - or the cap alone when it is unknown.
  */
+export declare function maxSizeFor(totalMemory: number): number;
 export declare class SmartBuffer extends FlexyBuffer {
     static DEFAULT_PAGE_SIZE: number;
     static DEFAULT_MAX_SIZE: number;

package/protocol/smart-buffer.js

@@ -6,9 +6,29 @@ import * as os from 'os';
  * length-prefixed string where a `null`/`undefined` value is written as a
  * length of -1 with no bytes following.
  */
+/** The ceiling on `maxSizeFor`, and its answer when there is no machine to measure. */
+const HARD_MAX = 1024 * 1024 * 1024 * 2; // 2 GB
+/**
+ * The most a buffer may ever hold, given how much memory the machine has.
+ *
+ * @param totalMemory Bytes of memory, or 0 when that cannot be known.
+ * @returns Half of it, capped - or the cap alone when it is unknown.
+ */
+/* `os.totalmem()` answers 0 where there is no machine to ask about:
+   measured under Cloudflare's workerd, where `node:os` resolves and
+   returns zeros rather than throwing. Taking the minimum of that was a
+   maximum size of zero, which worked only because flexy-buffer reads a
+   falsy `maxLength` as "use the default" - an accident, and one that
+   would have become a buffer refusing every write the day that default
+   changed. */
+export function maxSizeFor(totalMemory) {
+    return totalMemory > 0
+        ? Math.min(Math.floor(totalMemory / 2), HARD_MAX)
+        : HARD_MAX;
+}
 export class SmartBuffer extends FlexyBuffer {
     static DEFAULT_PAGE_SIZE = 512;
-    static DEFAULT_MAX_SIZE = Math.min(Math.floor(os.totalmem() / 2), 1024 * 1024 * 1024 * 2);
+    static DEFAULT_MAX_SIZE = maxSizeFor(typeof os.totalmem === 'function' ? os.totalmem() : 0);
     constructor(cfg) {
         super({
             pageSize: cfg?.pageSize || SmartBuffer.DEFAULT_PAGE_SIZE,

package/protocol/workerd-socket.d.ts

@@ -0,0 +1,87 @@
+import { SafeEventEmitter } from '../safe-event-emitter.js';
+/** What `cloudflare:sockets` hands back, as much of it as is used here. */
+interface CfSocket {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    closed: Promise<void>;
+    close(): Promise<void>;
+    startTls(options: {
+        expectedServerHostname?: string;
+    }): CfSocket;
+}
+/** The one function `cloudflare:sockets` is reached for. */
+export type CfConnect = (address: string, options?: {
+    secureTransport?: 'off' | 'on' | 'starttls';
+}) => CfSocket;
+/**
+ * A `net.Socket`-shaped view of a Cloudflare socket, for the part of it
+ * this client uses: `connect`, `write`, `destroy`, and `data`/`error`/
+ * `close` events, plus `startTls()`, which is the one thing Node's
+ * `tls.connect({ socket })` cannot do on that runtime.
+ *
+ * Reads are a loop over the stream rather than a `'data'` event the
+ * runtime emits, so the loop is what turns one into the other.
+ */
+export declare class WorkerdSocket extends SafeEventEmitter {
+    private readonly _wantsTls;
+    private readonly _connect;
+    private _cf?;
+    private _writer?;
+    private _reader?;
+    private _upgrading;
+    private _destroyed;
+    private _paused?;
+    private _resume?;
+    constructor(_wantsTls: boolean, _connect?: () => Promise<CfConnect>);
+    /** Whether a TLS upgrade has been asked for and completed. */
+    get secure(): boolean;
+    private _secure;
+    /** Whether `destroy()` has been called. */
+    get destroyed(): boolean;
+    /** Whether writes are still accepted. */
+    get writable(): boolean;
+    cork(): void;
+    uncork(): void;
+    setNoDelay(): this;
+    setKeepAlive(): this;
+    setTimeout(): this;
+    /** Stops reading, so the sender is made to wait. */
+    pause(): this;
+    /** Starts reading again. */
+    resume(): this;
+    /** Closes the connection once anything already written has gone. */
+    end(): this;
+    /**
+     * Opens the connection and emits `connect` once it is writable.
+     *
+     * @param port The port to reach.
+     * @param host The host to reach.
+     */
+    connect(port: number, host: string): void;
+    /**
+     * Reads one chunk and hands it over, without starting the loop.
+     *
+     * @param cb Called with the bytes, or with nothing if the connection
+     * ended first.
+     */
+    readOnce(cb: (data?: Buffer) => void): void;
+    /**
+     * Upgrades the connection in place.
+     *
+     * @param servername The name to check the certificate against.
+     */
+    startTls(servername?: string): void;
+    /**
+     * Writes to the connection.
+     *
+     * @param data The bytes to send.
+     * @param cb Called once they are written, or with the error.
+     * @returns True - the runtime offers no "buffer is full" answer.
+     */
+    write(data: Uint8Array, cb?: (err?: Error | null) => void): boolean;
+    /** Closes the connection; `close` follows once the runtime agrees. */
+    destroy(): this;
+    protected _attach(cf: CfSocket, readLoop: boolean): void;
+    protected _read(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
+}
+export {};

package/protocol/workerd-socket.js

@@ -0,0 +1,245 @@
+import { SafeEventEmitter } from '../safe-event-emitter.js';
+/* Imported where it is called rather than at the top of the file: the
+   specifier does not resolve off workerd, and this module is reachable
+   from a Node build through `pg-socket.ts`. Nothing awaits it unless a
+   connection is actually being made on that runtime. */
+const importCfConnect = async () => (await import(/* webpackIgnore: true */ 'cloudflare:sockets'))
+    .connect;
+/**
+ * A `net.Socket`-shaped view of a Cloudflare socket, for the part of it
+ * this client uses: `connect`, `write`, `destroy`, and `data`/`error`/
+ * `close` events, plus `startTls()`, which is the one thing Node's
+ * `tls.connect({ socket })` cannot do on that runtime.
+ *
+ * Reads are a loop over the stream rather than a `'data'` event the
+ * runtime emits, so the loop is what turns one into the other.
+ */
+/* Written here rather than taken from `pg-cloudflare`, which does the
+   same job for `pg`: the adapter is a hundred lines whose lifecycle this
+   client would otherwise not control, and only the upgrade is actually
+   needed - the plain path on workerd already works through `node:net`.
+
+   The setNoDelay/setKeepAlive/setTimeout trio answers nothing because
+   the runtime exposes no equivalent; they are here so the connect path
+   above can treat both socket kinds the same way. */
+export class WorkerdSocket extends SafeEventEmitter {
+    _wantsTls;
+    _connect;
+    _cf;
+    _writer;
+    _reader;
+    /* True between startTls() and the old socket's `closed` settling: that
+       promise resolves because the socket was replaced, not because the
+       connection went away, and reporting it as a close would end the
+       session in the middle of its handshake. */
+    _upgrading = false;
+    _destroyed = false;
+    _paused;
+    _resume;
+    constructor(_wantsTls, _connect = importCfConnect) {
+        super();
+        this._wantsTls = _wantsTls;
+        this._connect = _connect;
+    }
+    /** Whether a TLS upgrade has been asked for and completed. */
+    get secure() {
+        return this._secure;
+    }
+    _secure = false;
+    /** Whether `destroy()` has been called. */
+    get destroyed() {
+        return this._destroyed;
+    }
+    /** Whether writes are still accepted. */
+    get writable() {
+        return !this._destroyed && !!this._writer;
+    }
+    /* `cork`/`uncork` gather several small writes into one syscall on
+       Node. There is no syscall to gather here - a write is a promise
+       against a stream - so the pair is accepted and does nothing, which
+       is what it means on this runtime. */
+    cork() {
+        /* nothing to gather */
+    }
+    uncork() {
+        /* nothing to gather */
+    }
+    setNoDelay() {
+        return this;
+    }
+    setKeepAlive() {
+        return this;
+    }
+    setTimeout() {
+        return this;
+    }
+    /** Stops reading, so the sender is made to wait. */
+    /* Real backpressure rather than a no-op: the read loop is what pulls
+       from the stream, so not pulling is the whole of it. `pause()` during
+       a COPY TO is the only caller, and a stream left unread is how the
+       runtime learns to stop. */
+    pause() {
+        if (!this._paused)
+            this._paused = new Promise(r => (this._resume = r));
+        return this;
+    }
+    /** Starts reading again. */
+    resume() {
+        const go = this._resume;
+        this._paused = undefined;
+        this._resume = undefined;
+        go?.();
+        return this;
+    }
+    /** Closes the connection once anything already written has gone. */
+    end() {
+        return this.destroy();
+    }
+    /**
+     * Opens the connection and emits `connect` once it is writable.
+     *
+     * @param port The port to reach.
+     * @param host The host to reach.
+     */
+    connect(port, host) {
+        void (async () => {
+            try {
+                const connect = await this._connect();
+                this._cf = connect(`${host}:${port}`, {
+                    // `starttls` leaves the connection in the clear and allows a
+                    // later upgrade, which is what the SSLRequest exchange needs.
+                    secureTransport: this._wantsTls ? 'starttls' : 'off',
+                });
+                /* No read loop yet when a TLS upgrade is coming: `releaseLock()`
+                   throws on a reader with an outstanding read, and a loop parked
+                   in `reader.read()` is exactly that. The negotiation asks for
+                   the one byte it expects through `readOnce()`, and the loop
+                   starts on the upgraded socket. */
+                this._attach(this._cf, !this._wantsTls);
+                await this._writer.ready;
+                this.emit('connect');
+            }
+            catch (e) {
+                this.emit('error', e);
+            }
+        })();
+    }
+    /**
+     * Reads one chunk and hands it over, without starting the loop.
+     *
+     * @param cb Called with the bytes, or with nothing if the connection
+     * ended first.
+     */
+    /* What the SSLRequest exchange needs: a single answer, read while no
+       loop holds the reader, so the lock can be released for the upgrade
+       that follows. */
+    readOnce(cb) {
+        const reader = this._reader;
+        if (!reader)
+            return cb();
+        reader.read().then(({ done, value }) => cb(done || !value ? undefined : Buffer.from(value)), (e) => {
+            this.emit('error', e);
+            cb();
+        });
+    }
+    /**
+     * Upgrades the connection in place.
+     *
+     * @param servername The name to check the certificate against.
+     */
+    /* The locks have to go back before the socket is replaced, and the new
+       one needs its own reader and writer and its own read loop. */
+    startTls(servername) {
+        const cf = this._cf;
+        if (!cf) {
+            this.emit('error', new Error('Cannot upgrade a socket that is not connected'));
+            return;
+        }
+        try {
+            this._writer.releaseLock();
+            this._reader.releaseLock();
+            this._upgrading = true;
+            this._cf = cf.startTls(servername ? { expectedServerHostname: servername } : {});
+            this._attach(this._cf, true);
+            void this._writer.ready.then(() => {
+                this._secure = true;
+                this.emit('secureConnect');
+            }, (e) => this.emit('error', e));
+        }
+        catch (e) {
+            this.emit('error', e);
+        }
+    }
+    /**
+     * Writes to the connection.
+     *
+     * @param data The bytes to send.
+     * @param cb Called once they are written, or with the error.
+     * @returns True - the runtime offers no "buffer is full" answer.
+     */
+    write(data, cb) {
+        const writer = this._writer;
+        if (!writer) {
+            cb?.(new Error('Socket is not connected'));
+            return true;
+        }
+        writer.write(data).then(() => cb?.(), (e) => {
+            cb?.(e);
+            this.emit('error', e);
+        });
+        return true;
+    }
+    /** Closes the connection; `close` follows once the runtime agrees. */
+    destroy() {
+        if (this._destroyed)
+            return this;
+        this._destroyed = true;
+        const cf = this._cf;
+        this._cf = undefined;
+        cf?.close().catch(() => undefined);
+        return this;
+    }
+    _attach(cf, readLoop) {
+        this._writer = cf.writable.getWriter();
+        this._reader = cf.readable.getReader();
+        if (readLoop)
+            void this._read(this._reader);
+        cf.closed.then(() => {
+            if (this._upgrading) {
+                this._upgrading = false;
+                return;
+            }
+            this.emit('close');
+        }, (e) => {
+            if (this._upgrading) {
+                this._upgrading = false;
+                return;
+            }
+            this.emit('error', e);
+        });
+    }
+    async _read(reader) {
+        try {
+            for (;;) {
+                if (this._paused)
+                    await this._paused;
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                /* Asked again on the way out: a pause() during a read already in
+                   flight cannot un-await it, and delivering that chunk anyway
+                   would be data arriving after the consumer said stop. */
+                if (this._paused)
+                    await this._paused;
+                if (value?.length)
+                    this.emit('data', Buffer.from(value));
+            }
+        }
+        catch (e) {
+            // A read that ends because the socket was replaced is the upgrade
+            // happening, not a failure to report.
+            if (!this._upgrading && !this._destroyed)
+                this.emit('error', e);
+        }
+    }
+}

package/util/runtime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether this client is running inside a Cloudflare Worker.
+ *
+ * @returns True on workerd, false on Node.js, Bun and anything else.
+ */
+export declare function isWorkerd(): boolean;

package/util/runtime.js

@@ -0,0 +1,19 @@
+/**
+ * Whether this client is running inside a Cloudflare Worker.
+ *
+ * @returns True on workerd, false on Node.js, Bun and anything else.
+ */
+/* The documented tell, and the one `pg` uses: since the
+   `global_navigator` compatibility flag went on, workerd defines
+   `navigator.userAgent` and sets it to exactly this. Node and Bun define
+   `navigator` too, with a userAgent of their own, so the test is for the
+   whole string rather than a substring of it.
+
+   Asked on each call rather than read once at load: it is reached once
+   per connection, where the cost is nothing, and a value frozen at
+   module load cannot be tested from both sides. */
+export function isWorkerd() {
+    return (typeof navigator === 'object' &&
+        navigator !== null &&
+        navigator.userAgent === 'Cloudflare-Workers');
+}