postgrejs 2.23.1 → 3.0.2

package/protocol/pg-socket.d.ts

@@ -1,3 +1,5 @@
+import net from 'node:net';
+import tls from 'node:tls';
 import { ConnectionState } from '../constants.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
@@ -18,33 +20,242 @@ export declare class PgSocket extends SafeEventEmitter {
     private _saslSession?;
     private _processID?;
     private _secretKey?;
+    private _captureQueue;
+    private _pendingWrites;
+    private _flushScheduled;
+    private _hosts;
+    private _hostIndex;
+    private _sessionAttrsChecked;
+    private _standbyState?;
     constructor(options: ConnectionConfiguration);
     get state(): ConnectionState;
     get processID(): Maybe<number>;
     get secretKey(): Maybe<number>;
     get sessionParameters(): Record<string, string>;
     connect(): void;
+    protected _connectToHost(): void;
+    /**
+     * 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.
+     */
+    protected _negotiateTls(socket: net.Socket, target: {
+        host: string;
+        port?: number;
+    }, onReady: (socket: net.Socket | tls.TLSSocket) => void, onError: (err: Error) => void): void;
+    /**
+     * 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(): Promise<void>;
     close(): void;
-    sendParseMessage(args: Frontend.ParseMessageArgs, cb?: Callback): void;
-    sendBindMessage(args: Frontend.BindMessageArgs, cb?: Callback): void;
-    sendDescribeMessage(args: Frontend.DescribeMessageArgs, cb?: Callback): void;
-    sendExecuteMessage(args: Frontend.ExecuteMessageArgs, cb?: Callback): void;
-    sendCloseMessage(args: Frontend.CloseMessageArgs, cb?: Callback): void;
-    sendQueryMessage(sql: string, cb?: Callback): void;
+    sendExecuteMessage(args: Frontend.ExecuteMessageArgs, cb: CaptureCallback): Promise<any>;
+    sendCloseMessage(args: Frontend.CloseMessageArgs, cb: CaptureCallback): Promise<any>;
+    /**
+     * 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: {
+        parse: Frontend.ParseMessageArgs;
+        bind: Frontend.BindMessageArgs;
+        describe: Frontend.DescribeMessageArgs;
+        execute: Frontend.ExecuteMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * 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: {
+        parse: Frontend.ParseMessageArgs;
+        describe: Frontend.DescribeMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * 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: {
+        bind: Frontend.BindMessageArgs;
+        execute: Frontend.ExecuteMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * 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: {
+        bind: Frontend.BindMessageArgs;
+        describe: Frontend.DescribeMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * 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: Frontend.CloseMessageArgs, cb: CaptureCallback): Promise<any>;
+    /**
+     * 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: {
+        portal: Frontend.CloseMessageArgs;
+        statement: Frontend.CloseMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    sendQueryMessage(sql: string, cb: CaptureCallback): Promise<any>;
+    /**
+     * 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: Buffer, cb?: Callback): boolean;
+    /** Ends a COPY IN normally; the server replies CommandComplete. */
+    sendCopyDone(cb?: Callback): boolean;
+    /**
+     * 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: string, cb?: Callback): boolean;
+    /**
+     * 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(): void;
+    resume(): void;
     sendFlushMessage(cb?: Callback): void;
     sendTerminateMessage(cb?: Callback): void;
-    sendSyncMessage(): void;
-    capture(callback: CaptureCallback): Promise<any>;
+    sendSyncMessage(cb: CaptureCallback): Promise<any>;
+    /**
+     * 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.
+     */
+    private _sendAndCapture;
     protected _removeListeners(): void;
     protected _reset(): void;
     protected _handleConnect(): void;
+    /**
+     * 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.
+     */
+    protected _finishConnect(): void;
+    /** Accepts this server, or drops it and moves to the next candidate. */
+    protected _applySessionAttrs(wanted: string, standby: boolean, readOnly: boolean): void;
     protected _handleClose(): void;
     protected _handleError(err: unknown): void;
+    /** Rejects and clears every still-open capture, e.g. on close/error. */
+    private _failPendingCaptures;
     protected _handleData(data: Buffer): void;
+    /**
+     * 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.
+     */
+    private _dispatch;
     protected _resolvePassword(cb: (password: string) => void): void;
     protected _handleAuthenticationMessage(msg?: any): void;
+    /**
+     * 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.
+     */
+    protected _channelBindingData(socket: tls.TLSSocket): Buffer;
     protected _handleParameterStatus(msg: Protocol.ParameterStatusMessage): void;
     protected _handleBackendKeyData(msg: Protocol.BackendKeyDataMessage): void;
     protected _handleCommandComplete(msg: any): Protocol.CommandCompleteMessage;
-    protected _send(data: Buffer, cb?: Callback): void;
+    /**
+     * 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()).
+     */
+    protected _send(data: Buffer | Buffer[], cb?: Callback): boolean;
+    /**
+     * 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.
+     */
+    protected _sendCopy(data: Buffer | Buffer[], cb?: Callback): boolean;
+    /** Arrow property, not a method: used as a bare process.nextTick callback. */
+    private _flushPendingWrites;
 }