postgrejs 2.23.1 → 3.0.1

package/protocol/pg-socket.js

@@ -2,10 +2,12 @@ import crypto from 'node:crypto';
 import net from 'node:net';
 import path from 'node:path';
 import tls from 'node:tls';
+import DoublyLinked from 'doublylinked';
 import promisify from 'putil-promisify';
 import { ConnectionState } from '../constants.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { Backend } from './backend.js';
+import { signatureHashOfCertificate } from './cert-signature.js';
 import { DatabaseError } from './database-error.js';
 import { Frontend } from './frontend.js';
 import { Protocol } from './protocol.js';
@@ -22,6 +24,13 @@ export class PgSocket extends SafeEventEmitter {
     _saslSession;
     _processID;
     _secretKey;
+    _captureQueue = new DoublyLinked();
+    _pendingWrites = [];
+    _flushScheduled = false;
+    _hosts = [];
+    _hostIndex = 0;
+    _sessionAttrsChecked = false;
+    _standbyState;
     constructor(options) {
         super();
         this.options = options;
@@ -45,8 +54,17 @@ export class PgSocket extends SafeEventEmitter {
     connect() {
         if (this._socket)
             return;
-        this._state = ConnectionState.CONNECTING;
         const options = this.options;
+        this._hosts = options.hosts?.length
+            ? options.hosts
+            : [{ host: options.host || 'localhost', port: options.port }];
+        this._hostIndex = 0;
+        this._connectToHost();
+    }
+    _connectToHost() {
+        this._sessionAttrsChecked = false;
+        this._state = ConnectionState.CONNECTING;
+        const target = this._hosts[this._hostIndex];
         const socket = (this._socket = new net.Socket());
         const errorHandler = (err) => {
             this._state = ConnectionState.CLOSED;
@@ -54,49 +72,128 @@ export class PgSocket extends SafeEventEmitter {
             this._reset();
             socket.destroy();
             this._socket = undefined;
+            if (this._hostIndex + 1 < this._hosts.length) {
+                this._hostIndex++;
+                this._connectToHost();
+                return;
+            }
             this.emit('error', err);
         };
         const connectHandler = () => {
             socket.setTimeout(0);
             if (this.options.keepAlive || this.options.keepAlive == null)
                 socket.setKeepAlive(true);
-            socket.write(this._frontend.getSSLRequestMessage());
-            socket.once('data', x => {
+            this._negotiateTls(socket, target, readySocket => {
+                this._socket = readySocket;
                 this._removeListeners();
-                if (x.toString() === 'S') {
-                    const tslOptions = { ...options.ssl, socket };
-                    if (options.host && net.isIP(options.host) === 0)
-                        tslOptions.servername = options.host;
-                    const tlsSocket = (this._socket = tls.connect(tslOptions));
-                    tlsSocket.once('error', errorHandler);
-                    tlsSocket.once('secureConnect', () => {
-                        this._removeListeners();
-                        this._handleConnect();
-                    });
-                    return;
-                }
-                if (x.toString() === 'N') {
-                    if (options.requireSSL) {
-                        return errorHandler(new Error('Server does not support SSL connections'));
-                    }
-                    this._removeListeners();
-                    this._handleConnect();
-                    return;
-                }
-                return errorHandler(new Error('There was an error establishing an SSL connection'));
-            });
+                this._handleConnect();
+            }, errorHandler);
         };
         socket.setNoDelay(true);
-        socket.setTimeout(options.connectTimeoutMs || 30000, () => errorHandler(new Error('Connection timed out')));
+        socket.setTimeout(this.options.connectTimeoutMs || 30000, () => errorHandler(new Error('Connection timed out')));
         socket.once('error', errorHandler);
         socket.once('connect', connectHandler);
         this.emit('connecting');
-        const port = options.port || DEFAULT_PORT_NUMBER;
-        if (options.host && options.host.startsWith('/')) {
-            socket.connect(path.join(options.host, '/.s.PGSQL.' + port));
+        const port = target.port || DEFAULT_PORT_NUMBER;
+        if (target.host && target.host.startsWith('/')) {
+            socket.connect(path.join(target.host, '/.s.PGSQL.' + port));
         }
         else
-            socket.connect(options.port || DEFAULT_PORT_NUMBER, options.host || 'localhost');
+            socket.connect(port, target.host || 'localhost');
+    }
+    /**
+     * Negotiates TLS on an already TCP-connected `socket`, if configured -
+     * shared between the long-lived connection above (_connectToHost) and
+     * cancel() below, which needs the exact same host/TLS handling for its
+     * own short-lived socket, just without ever sending a StartupMessage
+     * afterwards. Resolves `onReady` with whichever socket ends up ready to
+     * speak the PostgreSQL protocol: the plain one, or its TLS upgrade.
+     */
+    _negotiateTls(socket, target, onReady, onError) {
+        const options = this.options;
+        const startTls = () => {
+            const tlsOptions = { ...options.ssl, socket };
+            if (target.host && net.isIP(target.host) === 0)
+                tlsOptions.servername = target.host;
+            if (options.sslNegotiation === 'direct')
+                tlsOptions.ALPNProtocols = ['postgresql'];
+            const tlsSocket = tls.connect(tlsOptions);
+            tlsSocket.once('error', onError);
+            tlsSocket.once('secureConnect', () => onReady(tlsSocket));
+        };
+        const wantsSSL = !!options.ssl ||
+            !!options.requireSSL ||
+            options.sslNegotiation === 'direct';
+        if (!wantsSSL)
+            return onReady(socket);
+        if (options.sslNegotiation === 'direct') {
+            // Straight into the handshake: no SSLRequest, nothing in the clear.
+            return startTls();
+        }
+        socket.write(this._frontend.getSSLRequestMessage());
+        socket.once('data', x => {
+            const command = x.toString();
+            if (command === 'S')
+                return startTls();
+            if (command === 'N') {
+                if (options.requireSSL) {
+                    return onError(new Error('Server does not support SSL connections'));
+                }
+                return onReady(socket);
+            }
+            return onError(new Error('There was an error establishing an SSL connection'));
+        });
+    }
+    /**
+     * Asks the server to cancel whatever this session is currently running.
+     *
+     * Opens its own short-lived connection and closes it again: a backend busy
+     * with a query is not reading its own socket, so the request cannot travel
+     * down the connection it is meant to interrupt. The server answers nothing
+     * - it either finds a matching session and signals it or does not - so
+     * this resolves once the bytes are out, and the cancelled query reports
+     * the outcome itself, as an ordinary error on its own connection.
+     *
+     * No StartupMessage or authentication is ever sent here - the
+     * CancelRequest is the only message this socket carries, and it is
+     * self-authorized by the processID/secretKey pair BackendKeyData handed
+     * out to the session being cancelled, not by a separate login. TLS is
+     * still negotiated via _negotiateTls() when configured, because a
+     * `hostssl` pg_hba.conf rule can reject a plaintext connection outright
+     * before the server ever reads what request it carries - and the target
+     * is `_hosts[_hostIndex]`, the host this session actually ended up
+     * connected to, not `options.host`, which after a multi-host failover may
+     * name a candidate this session never used.
+     */
+    cancel() {
+        const processID = this._processID;
+        const secretKey = this._secretKey;
+        // Nothing to cancel before the session is established.
+        if (processID == null || secretKey == null)
+            return Promise.resolve();
+        const data = this._frontend.getCancelRequestMessage(processID, secretKey);
+        const target = this._hosts[this._hostIndex];
+        return new Promise((resolve, reject) => {
+            const socket = new net.Socket();
+            const fail = (err) => {
+                socket.destroy();
+                reject(err);
+            };
+            const send = (readySocket) => {
+                readySocket.end(data, () => {
+                    readySocket.destroy();
+                    resolve();
+                });
+            };
+            socket.setNoDelay(true);
+            socket.once('error', fail);
+            socket.once('connect', () => this._negotiateTls(socket, target, send, fail));
+            const port = target.port || DEFAULT_PORT_NUMBER;
+            if (target.host && target.host.startsWith('/'))
+                socket.connect(path.join(target.host, '/.s.PGSQL.' + port));
+            else
+                socket.connect(port, target.host || 'localhost');
+        });
     }
     close() {
         if (!this._socket || this._socket.destroyed) {
@@ -113,35 +210,150 @@ export class PgSocket extends SafeEventEmitter {
         socket.once('close', () => this._handleClose());
         socket.destroy();
     }
-    sendParseMessage(args, cb) {
-        if (this.listenerCount('debug'))
-            this.emit('debug', { location: 'PgSocket.sendParseMessage', args });
-        this._send(this._frontend.getParseMessage(args), cb);
+    sendExecuteMessage(args, cb) {
+        return this._sendAndCapture(this._frontend.getExecuteMessage(args), cb, 'sendExecuteMessage', args);
     }
-    sendBindMessage(args, cb) {
-        if (this.listenerCount('debug'))
-            this.emit('debug', { location: 'PgSocket.sendBindMessage', args });
-        this._send(this._frontend.getBindMessage(args), cb);
+    sendCloseMessage(args, cb) {
+        return this._sendAndCapture(this._frontend.getCloseMessage(args), cb, 'sendCloseMessage', args);
     }
-    sendDescribeMessage(args, cb) {
-        if (this.listenerCount('debug'))
-            this.emit('debug', { location: 'PgSocket.sendDescribeMessage', args });
-        this._send(this._frontend.getDescribeMessage(args), cb);
+    /**
+     * Sends Parse+Bind+Describe+Execute+Sync as a single write with a single
+     * FIFO capture entry, instead of 5 separate sendXMessage() round trips -
+     * the one-shot Extended Query fast path (IntlConnection.queryOnce()).
+     * Callers pass unnamed statement/portal (omit statement/portal/name) so
+     * no Close message is needed at all: PostgreSQL auto-clears an unnamed
+     * statement/portal at the next Parse/Bind referencing the unnamed name.
+     */
+    sendExtendedQueryMessages(args, cb) {
+        const data = [
+            this._frontend.getParseMessage(args.parse),
+            this._frontend.getBindMessage(args.bind),
+            this._frontend.getDescribeMessage(args.describe),
+            this._frontend.getExecuteMessage(args.execute),
+            this._frontend.getSyncMessage(),
+        ];
+        return this._sendAndCapture(data, cb, 'sendExtendedQueryMessages', args);
     }
-    sendExecuteMessage(args, cb) {
-        if (this.listenerCount('debug'))
-            this.emit('debug', { location: 'PgSocket.sendDescribeMessage', args });
-        this._send(this._frontend.getExecuteMessage(args), cb);
+    /**
+     * Parse + Describe(statement) + Sync as a single round trip - used by
+     * PreparedStatement.prepare() instead of a separate awaited Parse then a
+     * separate awaited Sync, and fetches the RowDescription/NoData in the
+     * same round trip so PreparedStatement can cache it instead of every
+     * later execute() re-Describing its own portal.
+     */
+    sendPrepareMessages(args, cb) {
+        const data = [
+            this._frontend.getParseMessage(args.parse),
+            this._frontend.getDescribeMessage(args.describe),
+            this._frontend.getSyncMessage(),
+        ];
+        return this._sendAndCapture(data, cb, 'sendPrepareMessages', args);
     }
-    sendCloseMessage(args, cb) {
-        if (this.listenerCount('debug'))
-            this.emit('debug', { location: 'PgSocket.sendCloseMessage', args });
-        this._send(this._frontend.getCloseMessage(args), cb);
+    /**
+     * Bind + Execute + Sync as a single round trip, against an UNNAMED
+     * portal (args.bind.portal/args.execute.portal left unset) - used by
+     * PreparedStatement._execute() to reuse an already-prepared (named)
+     * statement without the per-call Describe/Close that Portal's own
+     * bind()/retrieveFields()/execute()/close() sequence needs for a
+     * freshly-created named portal. No Close message is needed: PostgreSQL
+     * auto-clears an unnamed portal at the next Bind naming it.
+     */
+    sendBindExecuteMessages(args, cb) {
+        const data = [
+            this._frontend.getBindMessage(args.bind),
+            this._frontend.getExecuteMessage(args.execute),
+            this._frontend.getSyncMessage(),
+        ];
+        return this._sendAndCapture(data, cb, 'sendBindExecuteMessages', args);
+    }
+    /**
+     * Bind + Describe(portal) + Flush as a single round trip (NOT Sync - see
+     * Portal.bindAndRetrieveFields()'s doc comment for why a Sync here would
+     * be unsafe: it would commit an implicit/autocommit transaction and
+     * destroy the just-bound named portal before any fetch() could use it).
+     * Used by PreparedStatement._execute()'s cursor branch instead of two
+     * separately-awaited Portal.bind()/retrieveFields() round trips.
+     */
+    sendBindDescribeMessages(args, cb) {
+        const data = [
+            this._frontend.getBindMessage(args.bind),
+            this._frontend.getDescribeMessage(args.describe),
+            this._frontend.getFlushMessage(),
+        ];
+        return this._sendAndCapture(data, cb, 'sendBindDescribeMessages', args);
+    }
+    /**
+     * Close + Sync under ONE capture, rather than a Close capture followed by
+     * a separate Sync capture. That split is unsafe after an ErrorResponse:
+     * the server then skips every message until Sync, so the only reply is
+     * the Sync's ReadyForQuery - which the FIFO hands to the *Close* capture
+     * (the older entry), making it fail with "unexpected response message
+     * (Z)" and leaving the Sync capture orphaned, to silently swallow the
+     * first message of whatever request comes next. With one capture,
+     * ReadyForQuery is simply this request's end marker whether or not the
+     * Close itself was honoured.
+     */
+    sendCloseAndSyncMessages(args, cb) {
+        const data = [
+            this._frontend.getCloseMessage(args),
+            this._frontend.getSyncMessage(),
+        ];
+        return this._sendAndCapture(data, cb, 'sendCloseAndSyncMessages', args);
+    }
+    /**
+     * Close(portal) + Close(statement) + Sync as a single round trip - used
+     * by PreparedStatement._maybeCloseWithPortal() when a Cursor's close()
+     * brings the owning PreparedStatement's refcount to 0, instead of two
+     * separately-batched Close+Sync round trips (Portal.close() then
+     * PreparedStatement._close()). Sync here is safe/intended: this is final
+     * teardown, no portal needs to survive past it.
+     */
+    sendClosePortalAndStatementMessages(args, cb) {
+        const data = [
+            this._frontend.getCloseMessage(args.portal),
+            this._frontend.getCloseMessage(args.statement),
+            this._frontend.getSyncMessage(),
+        ];
+        return this._sendAndCapture(data, cb, 'sendClosePortalAndStatementMessages', args);
     }
     sendQueryMessage(sql, cb) {
-        if (this.listenerCount('debug'))
-            this.emit('debug', { location: 'PgSocket.sendQueryMessage', sql });
-        this._send(this._frontend.getQueryMessage(sql), cb);
+        return this._sendAndCapture(this._frontend.getQueryMessage(sql), cb, 'sendQueryMessage', sql);
+    }
+    /**
+     * COPY IN data. Unlike every other send*() here this pushes nothing onto
+     * the capture queue: while a COPY is in progress the server answers no
+     * individual CopyData message, so the response still belongs to the
+     * Query capture that opened the copy.
+     *
+     * Returns false when the socket's buffer is full, exactly as
+     * net.Socket.write() does - the caller is expected to stop writing until
+     * `cb` fires, which is what CopyFromStream hands straight to its own
+     * Writable callback.
+     */
+    sendCopyData(data, cb) {
+        return this._sendCopy(this._frontend.getCopyDataMessage(data), cb);
+    }
+    /** Ends a COPY IN normally; the server replies CommandComplete. */
+    sendCopyDone(cb) {
+        return this._sendCopy(this._frontend.getCopyDoneMessage(), cb);
+    }
+    /**
+     * Aborts a COPY IN. The server discards the copy, reports `message` as an
+     * ErrorResponse and returns to its normal state - without this a failed
+     * import would leave the connection waiting for data forever.
+     */
+    sendCopyFail(message, cb) {
+        return this._sendCopy(this._frontend.getCopyFailMessage(message), cb);
+    }
+    /**
+     * Stops reading from the socket, so a COPY OUT consumer that cannot keep
+     * up doesn't buffer the whole export in memory. Safe to call repeatedly.
+     */
+    pause() {
+        this._socket?.pause();
+    }
+    resume() {
+        this._socket?.resume();
     }
     sendFlushMessage(cb) {
         if (this.listenerCount('debug'))
@@ -153,46 +365,31 @@ export class PgSocket extends SafeEventEmitter {
             this.emit('debug', { location: 'PgSocket.sendTerminateMessage' });
         this._send(this._frontend.getTerminateMessage(), cb);
     }
-    sendSyncMessage() {
-        if (this.listenerCount('debug'))
-            this.emit('debug', { location: 'PgSocket.sendSyncMessage' });
-        this._send(this._frontend.getSyncMessage());
+    sendSyncMessage(cb) {
+        return this._sendAndCapture(this._frontend.getSyncMessage(), cb, 'sendSyncMessage', undefined);
     }
-    capture(callback) {
-        if (this._state === ConnectionState.CLOSING ||
-            this._state === ConnectionState.CLOSED) {
-            return Promise.reject(new Error('Connection closed'));
-        }
-        if (this._state !== ConnectionState.READY)
-            return Promise.reject(new Error('Connection is not ready'));
+    /**
+     * The only way anything outside this class can receive a correlated
+     * backend response. Sends `data` and pushes `cb` onto the FIFO capture
+     * queue in the same call, so a response can never arrive before its
+     * capturer is registered, and a capturer can never be registered without
+     * a message actually going out for it - there is no separate, decoupled
+     * "start listening" step to race or misuse.
+     */
+    _sendAndCapture(data, cb, location, args) {
+        if (typeof cb !== 'function')
+            throw new TypeError(`${location}() requires a CaptureCallback`);
+        if (this.listenerCount('debug'))
+            this.emit('debug', { location: `PgSocket.${location}`, args });
         return new Promise((resolve, reject) => {
-            const done = (err, result) => {
-                this.removeListener('close', closeHandler);
-                this.removeListener('error', errorHandler);
-                this.removeListener('message', msgHandler);
-                if (err)
-                    reject(err);
-                else
-                    resolve(result);
-            };
-            const errorHandler = (err) => {
-                this.removeListener('close', closeHandler);
-                this.removeListener('message', msgHandler);
-                reject(err);
-            };
-            const closeHandler = () => {
-                this.removeListener('error', errorHandler);
-                this.removeListener('message', msgHandler);
-                reject(new Error('Connection closed'));
-            };
-            const msgHandler = (code, msg) => {
-                const x = callback(code, msg, done);
-                if (promisify.isPromise(x))
-                    x.catch(err => done(err));
-            };
-            this.once('close', closeHandler);
-            this.once('error', errorHandler);
-            this.on('message', msgHandler);
+            const entry = { callback: cb, resolve, reject };
+            this._captureQueue.push(entry);
+            if (!this._send(data)) {
+                // Nothing else can have run between the push above and here (fully
+                // synchronous), so the entry just pushed is still the tail.
+                this._captureQueue.pop();
+                reject(new Error('Socket is not writable'));
+            }
         });
     }
     _removeListeners() {
@@ -209,6 +406,9 @@ export class PgSocket extends SafeEventEmitter {
         this._processID = undefined;
         this._secretKey = undefined;
         this._saslSession = undefined;
+        // Anything still queued belonged to the connection being reset - it
+        // must never reach a freshly connected socket.
+        this._pendingWrites = [];
     }
     _handleConnect() {
         const socket = this._socket;
@@ -223,20 +423,99 @@ export class PgSocket extends SafeEventEmitter {
             user: this.options.user || 'postgres',
             database: this.options.database || '',
             application_name: this.options.applicationName || '',
+            ...(this.options.replication
+                ? { replication: this.options.replication }
+                : undefined),
         }));
     }
+    /**
+     * Called once the server is ready. With `targetSessionAttrs` set, the
+     * session has to be checked before it is handed over: a server that does
+     * not match is dropped and the next candidate tried, which is how
+     * `read-write` finds whichever node is currently the primary.
+     */
+    _finishConnect() {
+        const wanted = this.options.targetSessionAttrs;
+        if (!wanted || this._sessionAttrsChecked) {
+            this.emit('ready');
+            return;
+        }
+        this._sessionAttrsChecked = true;
+        const reported = this._sessionParameters;
+        if (reported.in_hot_standby != null &&
+            reported.default_transaction_read_only != null) {
+            this._applySessionAttrs(wanted, reported.in_hot_standby === 'on', reported.default_transaction_read_only === 'on');
+            return;
+        }
+        this.sendQueryMessage('select pg_catalog.pg_is_in_recovery()::text as a,' +
+            " current_setting('transaction_read_only') as b", (code, msg, done) => {
+            if (code === Protocol.BackendMessageCode.DataRow) {
+                // Two text columns, each length-prefixed within the row buffer.
+                const data = msg.data;
+                const aLen = data.readInt32BE(0);
+                const a = data.toString('utf8', 4, 4 + aLen);
+                const bOffset = 4 + aLen;
+                const bLen = data.readInt32BE(bOffset);
+                const b = data.toString('utf8', bOffset + 4, bOffset + 4 + bLen);
+                this._standbyState = { standby: a === 'true', readOnly: b === 'on' };
+            }
+            else if (code === Protocol.BackendMessageCode.ReadyForQuery) {
+                done(undefined);
+                const st = this._standbyState;
+                this._applySessionAttrs(wanted, !!st?.standby, !!st?.readOnly);
+            }
+        }).catch(err => this.emit('error', err));
+    }
+    /** Accepts this server, or drops it and moves to the next candidate. */
+    _applySessionAttrs(wanted, standby, readOnly) {
+        const rejected = (wanted === 'read-write' && readOnly) ||
+            (wanted === 'read-only' && !readOnly) ||
+            (wanted === 'primary' && standby) ||
+            (wanted === 'standby' && !standby) ||
+            // prefer-standby settles for a primary, but only once nothing else
+            // is left to try.
+            (wanted === 'prefer-standby' &&
+                !standby &&
+                this._hostIndex + 1 < this._hosts.length);
+        if (!rejected) {
+            this.emit('ready');
+            return;
+        }
+        const target = this._hosts[this._hostIndex];
+        if (this._hostIndex + 1 >= this._hosts.length) {
+            this.close();
+            this.emit('error', new Error(`No server matched target_session_attrs "${wanted}" ` +
+                `(last tried ${target.host}:${target.port ?? this.options.port ?? DEFAULT_PORT_NUMBER})`));
+            return;
+        }
+        this._hostIndex++;
+        const socket = this._socket;
+        this._removeListeners();
+        this._socket = undefined;
+        this._reset();
+        socket?.destroy();
+        this._connectToHost();
+    }
     _handleClose() {
+        this._failPendingCaptures(new Error('Connection closed'));
         this._reset();
         this._socket = undefined;
         this._state = ConnectionState.CLOSED;
         this.emit('close');
     }
     _handleError(err) {
+        this._failPendingCaptures(err instanceof Error ? err : new Error(String(err)));
         if (this._state !== ConnectionState.READY) {
             this._socket?.end();
         }
         this.emit('error', err);
     }
+    /** Rejects and clears every still-open capture, e.g. on close/error. */
+    _failPendingCaptures(err) {
+        const pending = this._captureQueue;
+        this._captureQueue = new DoublyLinked();
+        pending.forEach(entry => entry.reject(err));
+    }
     _handleData(data) {
         this._backend.parse(data, (code, payload) => {
             try {
@@ -245,7 +524,7 @@ export class PgSocket extends SafeEventEmitter {
                         this._handleAuthenticationMessage(payload);
                         break;
                     case Protocol.BackendMessageCode.ErrorResponse:
-                        this.emit('error', new DatabaseError(payload));
+                        this._dispatch(code, new DatabaseError(payload));
                         break;
                     case Protocol.BackendMessageCode.NoticeResponse:
                         this.emit('notice', payload);
@@ -262,18 +541,18 @@ export class PgSocket extends SafeEventEmitter {
                     case Protocol.BackendMessageCode.ReadyForQuery:
                         if (this._state !== ConnectionState.READY) {
                             this._state = ConnectionState.READY;
-                            this.emit('ready');
+                            this._finishConnect();
                         }
                         else
-                            this.emit('message', code, payload);
+                            this._dispatch(code, payload);
                         break;
                     case Protocol.BackendMessageCode.CommandComplete: {
                         const msg = this._handleCommandComplete(payload);
-                        this.emit('message', code, msg);
+                        this._dispatch(code, msg);
                         break;
                     }
                     default:
-                        this.emit('message', code, payload);
+                        this._dispatch(code, payload);
                 }
             }
             catch (e) {
@@ -281,6 +560,44 @@ export class PgSocket extends SafeEventEmitter {
             }
         });
     }
+    /**
+     * Routes one backend message to the capture at the front of the FIFO -
+     * the oldest still-open request, i.e. the one whose turn it is given the
+     * order messages were written to the socket. This *is* the request/
+     * response correlation, since the wire protocol has no id of its own.
+     * The same entry keeps receiving messages (ParseComplete, BindComplete,
+     * RowDescription, DataRow*, CommandComplete, ReadyForQuery, ...) until
+     * its callback calls `done()`, at which point it is dequeued and the
+     * next entry becomes the one messages are routed to.
+     */
+    _dispatch(code, payload) {
+        const entry = this._captureQueue.head?.value;
+        if (!entry) {
+            if (payload instanceof DatabaseError) {
+                this.emit('error', payload);
+                return;
+            }
+            this.emit('error', new Error(`PgSocket: received message code=${String(code)} with an empty capture queue`));
+            return;
+        }
+        const done = (err, result) => {
+            if (this._captureQueue.head?.value !== entry)
+                return;
+            this._captureQueue.shift();
+            if (err)
+                entry.reject(err);
+            else
+                entry.resolve(result);
+        };
+        try {
+            const x = entry.callback(code, payload, done);
+            if (promisify.isPromise(x))
+                x.catch(err => done(err));
+        }
+        catch (err) {
+            done(err);
+        }
+    }
     _resolvePassword(cb) {
         (async () => {
             const pass = typeof this.options.password === 'function'
@@ -310,10 +627,21 @@ export class PgSocket extends SafeEventEmitter {
                 });
                 break;
             case Protocol.AuthenticationMessageKind.SASL: {
-                if (!msg.mechanisms.includes('SCRAM-SHA-256')) {
-                    throw new Error('SASL: Only mechanism SCRAM-SHA-256 is currently supported');
+                const mode = this.options.channelBinding || 'prefer';
+                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');
+                }
+                if (!useBinding && !msg.mechanisms?.includes('SCRAM-SHA-256')) {
+                    throw new Error('SASL: Only mechanisms SCRAM-SHA-256 and SCRAM-SHA-256-PLUS are supported');
                 }
-                const saslSession = (this._saslSession = SASL.createSession(this.options.user || '', 'SCRAM-SHA-256'));
+                const saslSession = (this._saslSession = SASL.createSession(this.options.user || '', useBinding ? 'SCRAM-SHA-256-PLUS' : 'SCRAM-SHA-256', useBinding ? this._channelBindingData(tlsSocket) : undefined, !!tlsSocket));
                 this._send(this._frontend.getSASLMessage(saslSession));
                 break;
             }
@@ -337,9 +665,26 @@ export class PgSocket extends SafeEventEmitter {
                 break;
             }
             default:
-                break;
+                throw new Error(`Authentication method "${msg.kind}" is not supported. ` +
+                    'Supported methods are cleartext password, MD5 and SCRAM-SHA-256 ' +
+                    '(with or without channel binding).');
         }
     }
+    /**
+     * tls-server-end-point: the server certificate hashed with the algorithm
+     * its own signature used (RFC 5929), which is why the DER has to be read
+     * rather than one of Node's fixed fingerprints taken.
+     */
+    _channelBindingData(socket) {
+        const cert = socket.getPeerX509Certificate?.();
+        if (!cert)
+            throw new Error('SASL: SCRAM-SHA-256-PLUS needs the server certificate, which this connection did not provide');
+        const der = cert.raw;
+        return crypto
+            .createHash(signatureHashOfCertificate(der))
+            .update(der)
+            .digest();
+    }
     _handleParameterStatus(msg) {
         this._sessionParameters[msg.name] = msg.value;
     }
@@ -360,9 +705,101 @@ export class PgSocket extends SafeEventEmitter {
             result.rowCount = parseInt(m[2], 10);
         return result;
     }
+    /**
+     * Queues `data` for the socket instead of writing it straight through:
+     * everything handed to _send() during the same synchronous burst (e.g.
+     * many concurrent query() calls fired via Promise.all over one
+     * connection) is flushed together on the next tick, corked, so Node
+     * turns the whole batch into a single underlying writev rather than one
+     * socket write per call. Measured against postgres.js, which coalesces
+     * the same way at the application level (its connection.js write()/
+     * nextWrite() pair, flushing on a 1KB threshold or setImmediate): 50
+     * concurrent prepared executes cost it 3 socket writes where this cost
+     * us 50, and that write path was the single largest non-idle item in a
+     * CPU profile of the scenario.
+     *
+     * nextTick rather than setImmediate, deliberately: it still batches a
+     * whole synchronous burst, but a lone query doesn't have to wait for the
+     * event loop's check phase before its bytes go out - which would trade
+     * away the sequential/single-query scenarios to win the concurrent ones.
+     *
+     * Returns whether the socket could accept the data at all; the write
+     * itself is reported through `cb` (and a socket that dies before the
+     * flush rejects every pending capture via _failPendingCaptures()).
+     */
     _send(data, cb) {
-        if (this._socket && this._socket.writable) {
-            this._socket.write(data, cb);
+        if (!this._socket || !this._socket.writable)
+            return false;
+        if (Array.isArray(data)) {
+            const l = data.length;
+            for (let i = 0; i < l; i++)
+                this._pendingWrites.push({
+                    data: data[i],
+                    cb: i === l - 1 ? cb : undefined,
+                });
+        }
+        else
+            this._pendingWrites.push({ data, cb });
+        if (this._captureQueue.length > 1) {
+            if (!this._flushScheduled) {
+                this._flushScheduled = true;
+                process.nextTick(this._flushPendingWrites);
+            }
+        }
+        else
+            this._flushPendingWrites();
+        return true;
+    }
+    /**
+     * Writes COPY bytes straight through instead of queueing them for the
+     * next tick like _send() does. Two reasons: during a copy the capture
+     * queue holds exactly one entry (the Query that opened it), so _send()'s
+     * "batch only when more than one request is in flight" test would never
+     * fire and every chunk would be written on its own anyway; and the
+     * caller needs write()'s own return value to know when to stop, which a
+     * deferred write cannot give it.
+     */
+    _sendCopy(data, cb) {
+        const socket = this._socket;
+        if (!socket || !socket.writable)
+            return false;
+        this._flushPendingWrites();
+        if (!Array.isArray(data))
+            return socket.write(data, cb);
+        socket.cork();
+        try {
+            const l = data.length;
+            let writable = true;
+            let i;
+            for (i = 0; i < l; i++)
+                writable = socket.write(data[i], i === l - 1 ? cb : undefined);
+            return writable;
+        }
+        finally {
+            socket.uncork();
         }
     }
+    /** Arrow property, not a method: used as a bare process.nextTick callback. */
+    _flushPendingWrites = () => {
+        this._flushScheduled = false;
+        const pending = this._pendingWrites;
+        if (!pending.length)
+            return;
+        this._pendingWrites = [];
+        const socket = this._socket;
+        if (!socket || !socket.writable)
+            return;
+        socket.cork();
+        try {
+            const l = pending.length;
+            let i;
+            for (i = 0; i < l; i++) {
+                const { data, cb } = pending[i];
+                socket.write(data, cb);
+            }
+        }
+        finally {
+            socket.uncork();
+        }
+    };
 }