postgrejs 2.23.1 → 3.0.2

package/protocol/pgoutput.d.ts

@@ -0,0 +1,76 @@
+import { BufferReader } from './buffer-reader.js';
+export interface PgOutputColumn {
+    name: string;
+    dataTypeId: number;
+    typeModifier: number;
+    /** Part of the replica identity, so it can identify a row on its own. */
+    isKey: boolean;
+}
+export interface PgOutputRelation {
+    relationId: number;
+    schema: string;
+    name: string;
+    replicaIdentity: string;
+    columns: PgOutputColumn[];
+}
+export type PgOutputMessage = {
+    kind: 'begin';
+    finalLsn: bigint;
+    commitTime: Date;
+    xid: number;
+} | {
+    kind: 'commit';
+    commitLsn: bigint;
+    endLsn: bigint;
+    commitTime: Date;
+} | {
+    kind: 'relation';
+    relation: PgOutputRelation;
+} | {
+    kind: 'type';
+    dataTypeId: number;
+    schema: string;
+    name: string;
+} | {
+    kind: 'insert';
+    relation: PgOutputRelation;
+    row: TupleValues;
+} | {
+    kind: 'update';
+    relation: PgOutputRelation;
+    row: TupleValues;
+    oldRow?: TupleValues;
+} | {
+    kind: 'delete';
+    relation: PgOutputRelation;
+    oldRow: TupleValues;
+} | {
+    kind: 'truncate';
+    relations: PgOutputRelation[];
+} | {
+    kind: 'origin';
+    commitLsn: bigint;
+    name: string;
+} | {
+    kind: 'message';
+    prefix: string;
+    content: Buffer;
+    lsn: bigint;
+} | {
+    kind: 'unknown';
+    code: string;
+};
+/**
+ * A row as pgoutput sends it: column name to its raw text, or null. A value
+ * left out because it did not change and lives in TOAST storage is absent
+ * from the map entirely - which is not the same as being null.
+ */
+export type TupleValues = Record<string, string | null>;
+export declare class PgOutputDecoder {
+    protected readonly _relations: Map<number, PgOutputRelation>;
+    decode(data: Buffer): PgOutputMessage;
+    protected _relation(relationId: number): PgOutputRelation;
+    protected _tuple(io: BufferReader, relation: PgOutputRelation): TupleValues;
+}
+/** `0/16B3748`, the form PostgreSQL prints an LSN in. */
+export declare function formatLsn(lsn: bigint): string;

package/protocol/pgoutput.js

@@ -0,0 +1,155 @@
+import { BufferReader } from './buffer-reader.js';
+/**
+ * Decoder for `pgoutput`, the logical decoding plugin PostgreSQL ships with,
+ * at protocol version 1.
+ *
+ * The server does not repeat a table's shape with every row: a Relation
+ * message describes it once and later Insert/Update/Delete messages refer to
+ * it by OID, so a decoder has to remember relations as it goes. That is why
+ * this is a class rather than a function.
+ */
+/** Microseconds since 2000-01-01, which is how this protocol tells time. */
+const PG_EPOCH_MS = Date.UTC(2000, 0, 1);
+export class PgOutputDecoder {
+    _relations = new Map();
+    decode(data) {
+        const io = new BufferReader(data);
+        const code = String.fromCharCode(io.readUInt8());
+        switch (code) {
+            case 'B':
+                return {
+                    kind: 'begin',
+                    finalLsn: readLsn(io),
+                    commitTime: readTime(io),
+                    xid: io.readUInt32BE(),
+                };
+            case 'C': {
+                io.readUInt8(); // flags, unused at this version
+                return {
+                    kind: 'commit',
+                    commitLsn: readLsn(io),
+                    endLsn: readLsn(io),
+                    commitTime: readTime(io),
+                };
+            }
+            case 'O':
+                return {
+                    kind: 'origin',
+                    commitLsn: readLsn(io),
+                    name: io.readCString(),
+                };
+            case 'R': {
+                const relation = {
+                    relationId: io.readUInt32BE(),
+                    schema: io.readCString(),
+                    name: io.readCString(),
+                    replicaIdentity: String.fromCharCode(io.readUInt8()),
+                    columns: [],
+                };
+                const count = io.readUInt16BE();
+                for (let i = 0; i < count; i++) {
+                    relation.columns.push({
+                        isKey: io.readUInt8() === 1,
+                        name: io.readCString(),
+                        dataTypeId: io.readUInt32BE(),
+                        typeModifier: io.readInt32BE(),
+                    });
+                }
+                this._relations.set(relation.relationId, relation);
+                return { kind: 'relation', relation };
+            }
+            case 'Y':
+                return {
+                    kind: 'type',
+                    dataTypeId: io.readUInt32BE(),
+                    schema: io.readCString(),
+                    name: io.readCString(),
+                };
+            case 'I': {
+                const relation = this._relation(io.readUInt32BE());
+                io.readUInt8(); // 'N'
+                return { kind: 'insert', relation, row: this._tuple(io, relation) };
+            }
+            case 'U': {
+                const relation = this._relation(io.readUInt32BE());
+                let oldRow;
+                // 'K' is the old row's key columns, 'O' the whole old row; either
+                // appears only when the table's replica identity provides it, and
+                // the 'N' tag for the new row follows in every case.
+                const tag = String.fromCharCode(io.readUInt8());
+                if (tag === 'K' || tag === 'O') {
+                    oldRow = this._tuple(io, relation);
+                    io.readUInt8(); // 'N'
+                }
+                return {
+                    kind: 'update',
+                    relation,
+                    row: this._tuple(io, relation),
+                    oldRow,
+                };
+            }
+            case 'D': {
+                const relation = this._relation(io.readUInt32BE());
+                io.readUInt8(); // 'K' or 'O'
+                return { kind: 'delete', relation, oldRow: this._tuple(io, relation) };
+            }
+            case 'T': {
+                const count = io.readUInt32BE();
+                io.readUInt8(); // flags: cascade / restart identity
+                const relations = [];
+                for (let i = 0; i < count; i++)
+                    relations.push(this._relation(io.readUInt32BE()));
+                return { kind: 'truncate', relations };
+            }
+            case 'M': {
+                io.readUInt8(); // flags
+                const lsn = readLsn(io);
+                const prefix = io.readCString();
+                const length = io.readUInt32BE();
+                return { kind: 'message', prefix, lsn, content: io.readBuffer(length) };
+            }
+            default:
+                return { kind: 'unknown', code };
+        }
+    }
+    _relation(relationId) {
+        const relation = this._relations.get(relationId);
+        if (!relation)
+            throw new Error(`Logical replication: a change arrived for relation ${relationId} before its description did`);
+        return relation;
+    }
+    _tuple(io, relation) {
+        const count = io.readUInt16BE();
+        const out = {};
+        for (let i = 0; i < count; i++) {
+            const column = relation.columns[i];
+            const kind = String.fromCharCode(io.readUInt8());
+            if (kind === 'n') {
+                out[column.name] = null;
+            }
+            else if (kind === 'u') {
+                // Unchanged and stored out of line: the server did not send it, and
+                // leaving the key out says so rather than claiming it is null.
+                continue;
+            }
+            else {
+                const length = io.readUInt32BE();
+                out[column.name] = io.readBuffer(length).toString('utf8');
+            }
+        }
+        return out;
+    }
+}
+function readLsn(io) {
+    const hi = BigInt(io.readUInt32BE());
+    const lo = BigInt(io.readUInt32BE());
+    return (hi << 32n) | lo;
+}
+function readTime(io) {
+    const micros = (BigInt(io.readUInt32BE()) << 32n) | BigInt(io.readUInt32BE());
+    return new Date(PG_EPOCH_MS + Number(micros / 1000n));
+}
+/** `0/16B3748`, the form PostgreSQL prints an LSN in. */
+export function formatLsn(lsn) {
+    return `${(lsn >> 32n).toString(16).toUpperCase()}/${(lsn & 0xffffffffn).toString(16).toUpperCase()}`;
+}

package/protocol/protocol.d.ts

@@ -1,4 +1,3 @@
-import type { Nullable } from '../types.js';
 export declare namespace Protocol {
     const VERSION_MAJOR = 3;
     const VERSION_MINOR = 0;
@@ -10,7 +9,7 @@ export declare namespace Protocol {
         CommandComplete = 67,// C
         CopyData = 100,// d
         CopyDone = 99,// c
-        CopyInResponse = 103,// G
+        CopyInResponse = 71,// G
         CopyOutResponse = 72,// H
         CopyBothResponse = 87,// W
         DataRow = 68,// D
@@ -29,7 +28,7 @@ export declare namespace Protocol {
         RowDescription = 84
     }
     enum FrontendMessageCode {
-        Bind = 66,// R
+        Bind = 66,// B
         Close = 67,// C
         CopyData = 100,// d
         CopyDone = 99,// c
@@ -119,7 +118,7 @@ export declare namespace Protocol {
     }
     interface DataRowMessage {
         columnCount: number;
-        columns: Nullable<Buffer>[];
+        data: Buffer;
     }
     interface ErrorResponseMessage {
         severity?: string;

package/protocol/protocol.js

@@ -12,7 +12,7 @@ export var Protocol;
         BackendMessageCode[BackendMessageCode["CommandComplete"] = 67] = "CommandComplete";
         BackendMessageCode[BackendMessageCode["CopyData"] = 100] = "CopyData";
         BackendMessageCode[BackendMessageCode["CopyDone"] = 99] = "CopyDone";
-        BackendMessageCode[BackendMessageCode["CopyInResponse"] = 103] = "CopyInResponse";
+        BackendMessageCode[BackendMessageCode["CopyInResponse"] = 71] = "CopyInResponse";
         BackendMessageCode[BackendMessageCode["CopyOutResponse"] = 72] = "CopyOutResponse";
         BackendMessageCode[BackendMessageCode["CopyBothResponse"] = 87] = "CopyBothResponse";
         BackendMessageCode[BackendMessageCode["DataRow"] = 68] = "DataRow";

package/protocol/sasl.d.ts

@@ -6,8 +6,18 @@ export declare namespace SASL {
         clientFirstMessage: string;
         clientFinalMessage: string;
         serverSignature: string;
+        /** The GS2 header this session announced; repeated in the final message. */
+        gs2Header: string;
+        /** tls-server-end-point data, present only for SCRAM-SHA-256-PLUS. */
+        bindingData?: Buffer;
     }
-    function createSession(username: string, mechanism: string): Session;
+    /**
+     * @param bindingData - the server certificate's hash, for
+     *   SCRAM-SHA-256-PLUS. Pass undefined for the plain mechanism, and
+     *   `supportsBinding` to say whether the client could have done it, which
+     *   is what tells the server a stripped -PLUS offer would be an attack.
+     */
+    function createSession(username: string, mechanism: string, bindingData?: Buffer, supportsBinding?: boolean): Session;
     function continueSession(session: Session, password: string, data: string): void;
     function finalizeSession(session: Session, data: string): void;
 }

package/protocol/sasl.js

@@ -3,14 +3,36 @@ export var SASL;
 (function (SASL) {
     const CLIENT_KEY = 'Client Key';
     const SERVER_KEY = 'Server Key';
-    const GS2_HEADER = 'n,,';
-    function createSession(username, mechanism) {
+    /**
+     * The GS2 header states what the client can do about channel binding, and
+     * the server checks it against what it offered. `n` means the client does
+     * not support it; `y` means it does but saw no -PLUS mechanism offered -
+     * which is what lets the server notice an attacker having stripped it;
+     * `p=...` means it is in use.
+     */
+    const GS2_NONE = 'n,,';
+    const GS2_SUPPORTED_UNUSED = 'y,,';
+    const GS2_BOUND = 'p=tls-server-end-point,,';
+    /**
+     * @param bindingData - the server certificate's hash, for
+     *   SCRAM-SHA-256-PLUS. Pass undefined for the plain mechanism, and
+     *   `supportsBinding` to say whether the client could have done it, which
+     *   is what tells the server a stripped -PLUS offer would be an attack.
+     */
+    function createSession(username, mechanism, bindingData, supportsBinding) {
         const nonce = crypto.randomBytes(18).toString('base64');
-        const clientFirstMessage = `${GS2_HEADER}${firstMessageBare(username, nonce)}`;
+        const gs2Header = bindingData
+            ? GS2_BOUND
+            : supportsBinding
+                ? GS2_SUPPORTED_UNUSED
+                : GS2_NONE;
+        const clientFirstMessage = `${gs2Header}${firstMessageBare(username, nonce)}`;
         return {
             username,
             mechanism,
             nonce,
+            gs2Header,
+            bindingData,
             clientFirstMessage,
         };
     }
@@ -45,7 +67,16 @@ export var SASL;
         if (!nonce.startsWith(session.nonce))
             throw new Error('SASL: Server nonce does not start with client nonce');
         const serverFirstMessage = `r=${nonce},s=${salt},i=${iteration}`;
-        const clientFinalMessageWithoutProof = `c=${encode64(GS2_HEADER)},r=${nonce}`;
+        // c= carries the header again, with the binding data appended when the
+        // channel is bound - so an attacker who relayed the exchange over a
+        // different TLS connection produces a different proof.
+        const cbind = session.bindingData
+            ? Buffer.concat([
+                Buffer.from(session.gs2Header, 'utf8'),
+                session.bindingData,
+            ]).toString('base64')
+            : encode64(session.gs2Header);
+        const clientFinalMessageWithoutProof = `c=${cbind},r=${nonce}`;
         const authMessage = `${firstMessageBare(session.username, session.nonce)},${serverFirstMessage},${clientFinalMessageWithoutProof}`;
         const saltPass = hi(password, salt, iteration);
         const clientKey = hmac(saltPass, CLIENT_KEY);
@@ -65,7 +96,7 @@ export var SASL;
         const arr = data.split(',');
         for (const s of arr) {
             if (s[0] === 'v')
-                serverSignature = s.substr(2);
+                serverSignature = s.substring(2);
         }
         if (serverSignature !== session.serverSignature)
             throw new Error('SASL: Server signature does not match');

package/protocol/smart-buffer.d.ts

@@ -9,7 +9,6 @@ export declare class SmartBuffer extends BufferReader {
     static DEFAULT_MAX_SIZE: number;
     private readonly _houseKeepInterval;
     private _houseKeepTimer?;
-    private _lastHouseKeep;
     private _stMaxPages;
     private _length;
     readonly pageSize: number;
@@ -20,7 +19,6 @@ export declare class SmartBuffer extends BufferReader {
     start(): this;
     flush(): Buffer;
     growSize(len: number): this;
-    fill(value?: number, len?: number): this;
     writeCString(str: string, encoding?: BufferEncoding): this;
     writeLString(str?: string, encoding?: BufferEncoding): this;
     writeString(str: string, encoding?: BufferEncoding): this;

package/protocol/smart-buffer.js

@@ -2,11 +2,10 @@ import * as os from 'os';
 import { writeBigUInt64BE } from '../util/bigint-methods.js';
 import { BufferReader } from './buffer-reader.js';
 export class SmartBuffer extends BufferReader {
-    static DEFAULT_PAGE_SIZE = 4096;
+    static DEFAULT_PAGE_SIZE = 512;
     static DEFAULT_MAX_SIZE = Math.min(Math.floor(os.totalmem() / 2), 1024 * 1024 * 1024 * 2);
     _houseKeepInterval;
     _houseKeepTimer;
-    _lastHouseKeep = 0;
     _stMaxPages = 1;
     _length = 0;
     pageSize;
@@ -38,15 +37,16 @@ export class SmartBuffer extends BufferReader {
             clearTimeout(this._houseKeepTimer);
         const length = this.length;
         this._length = 0;
-        const out = this.buffer.slice(0, length);
+        const out = Buffer.from(this.buffer.subarray(0, length));
         const pages = length ? Math.ceil(length / this.pageSize) : 1;
         this._stMaxPages = Math.max(this._stMaxPages, pages);
-        if (this._lastHouseKeep < Date.now() + this._houseKeepInterval)
-            this._houseKeep();
-        this._houseKeepTimer = setTimeout(() => {
-            this._houseKeepTimer = undefined;
-            this._houseKeep();
-        }, this._houseKeepInterval).unref();
+        this._houseKeep();
+        if (this.buffer.length > this.pageSize) {
+            this._houseKeepTimer = setTimeout(() => {
+                this._houseKeepTimer = undefined;
+                this._houseKeep();
+            }, this._houseKeepInterval).unref();
+        }
         return out;
     }
     growSize(len) {
@@ -54,7 +54,8 @@ export class SmartBuffer extends BufferReader {
         if (this.capacity < endOffset) {
             if (endOffset > this.maxSize)
                 throw new Error('Buffer limit exceeded.');
-            const newSize = Math.ceil(endOffset / this.pageSize) * this.pageSize;
+            const byPage = Math.ceil(endOffset / this.pageSize) * this.pageSize;
+            const newSize = Math.min(Math.max(byPage, this.capacity * 2), this.maxSize);
             const newBuffer = Buffer.allocUnsafe(newSize);
             this.buffer.copy(newBuffer);
             this.buffer = newBuffer;
@@ -62,12 +63,6 @@ export class SmartBuffer extends BufferReader {
         this._length = Math.max(this.length, endOffset);
         return this;
     }
-    fill(value = 0, len = 1) {
-        this.ensureSize(len);
-        this.buffer.fill(value, this.offset, this.offset + len);
-        this.offset += len;
-        return this;
-    }
     writeCString(str, encoding) {
         const len = str ? Buffer.byteLength(str, encoding) : 0;
         this.ensureSize(len + 1);

package/types.d.ts

@@ -5,11 +5,13 @@ export type Maybe<T> = T | undefined;
 export type Nullable<T> = T | null;
 export type Row = any;
 export type Callback = (err?: Error | null) => void;
-export type DecodeBinaryFunction = (buf: Buffer, options: DataMappingOptions & Record<string, any>) => any;
+export type DecodeBinaryFunction = (buf: Buffer, offset: number, options: DataMappingOptions & Record<string, any>) => any;
+export type DecodeTextBufferFunction = (buf: Buffer, offset: number, len: number, options: DataMappingOptions & Record<string, any>) => any;
 export type EncodeBinaryFunction = (buf: SmartBuffer, v: any, options: DataMappingOptions) => void;
 export type EncodeCalculateDimFunction = (v: any[]) => number[];
 export type EncodeAsNullFunction = (v: any, options: DataMappingOptions) => boolean;
-export type ParseTextFunction = (v: any, options: DataMappingOptions) => any;
+export type DecodeTextFunction = (v: any, options: DataMappingOptions) => any;
 export type EncodeTextFunction = (v: any, options: DataMappingOptions) => string;
-export type AnyParseFunction = ParseTextFunction | DecodeBinaryFunction;
+export type ResolvedColumnParser = (data: Buffer, offset: number, len: number, options: DataMappingOptions & Record<string, any>) => any;
+export type AnyParseFunction = ResolvedColumnParser;
 export type DebugLogger = (namespace: string, format: any, ...args: any[]) => void;

package/util/abort-signal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The error an aborted operation rejects with.
+ *
+ * Prefers the signal's own reason, so `AbortSignal.timeout()` still reports
+ * itself as a TimeoutError and a caller's `controller.abort(myError)` still
+ * arrives intact. The database error that actually ended the query (SQLSTATE
+ * 57014) is attached as `cause` rather than replacing it: the reason is what
+ * callers branch on, the cause is what they need when reporting it.
+ */
+export declare function abortError(signal: AbortSignal, cause?: unknown): Error;
+/**
+ * Runs `run()` under an AbortSignal, asking `cancel()` to interrupt it if the
+ * signal fires.
+ *
+ * Cancelling a PostgreSQL query is a request, not a guarantee: it travels on
+ * its own connection and the statement may well finish first. So this does
+ * not settle early - it lets the query end the way the server ends it and
+ * only then reports the abort, which is also what keeps the connection
+ * usable, since its response still has to be read either way.
+ *
+ * The listener is always removed again: one long-lived signal shared by many
+ * queries would otherwise accumulate a listener per query.
+ *
+ * Not `async` itself: the overwhelmingly common case (no signal passed) just
+ * returns `run()`'s own promise straight through. Marking this function
+ * `async` would still be correct, but every `async function` return goes
+ * through the spec's promise-resolve machinery - a real extra microtask
+ * tick, even for a value that is already the right kind of promise - and
+ * this sits on every query's hot path, signal or not. The slow path (a
+ * signal actually given) is factored into its own async helper below, where
+ * the cost is negligible next to the abort-listener bookkeeping it already
+ * does.
+ */
+export declare function withAbortSignal<T>(signal: AbortSignal | undefined, cancel: () => Promise<void>, run: () => Promise<T>): Promise<T>;

package/util/abort-signal.js

@@ -0,0 +1,76 @@
+/**
+ * The error an aborted operation rejects with.
+ *
+ * Prefers the signal's own reason, so `AbortSignal.timeout()` still reports
+ * itself as a TimeoutError and a caller's `controller.abort(myError)` still
+ * arrives intact. The database error that actually ended the query (SQLSTATE
+ * 57014) is attached as `cause` rather than replacing it: the reason is what
+ * callers branch on, the cause is what they need when reporting it.
+ */
+export function abortError(signal, cause) {
+    const reason = signal.reason;
+    const err = reason instanceof Error
+        ? reason
+        : Object.assign(new Error('The operation was aborted'), {
+            name: 'AbortError',
+        });
+    if (cause !== undefined && err.cause === undefined) {
+        try {
+            err.cause = cause;
+        }
+        catch {
+            // A reason the caller froze; the error itself is still correct.
+        }
+    }
+    return err;
+}
+/**
+ * Runs `run()` under an AbortSignal, asking `cancel()` to interrupt it if the
+ * signal fires.
+ *
+ * Cancelling a PostgreSQL query is a request, not a guarantee: it travels on
+ * its own connection and the statement may well finish first. So this does
+ * not settle early - it lets the query end the way the server ends it and
+ * only then reports the abort, which is also what keeps the connection
+ * usable, since its response still has to be read either way.
+ *
+ * The listener is always removed again: one long-lived signal shared by many
+ * queries would otherwise accumulate a listener per query.
+ *
+ * Not `async` itself: the overwhelmingly common case (no signal passed) just
+ * returns `run()`'s own promise straight through. Marking this function
+ * `async` would still be correct, but every `async function` return goes
+ * through the spec's promise-resolve machinery - a real extra microtask
+ * tick, even for a value that is already the right kind of promise - and
+ * this sits on every query's hot path, signal or not. The slow path (a
+ * signal actually given) is factored into its own async helper below, where
+ * the cost is negligible next to the abort-listener bookkeeping it already
+ * does.
+ */
+export function withAbortSignal(signal, cancel, run) {
+    if (!signal)
+        return run();
+    // Already aborted: nothing has been sent, so nothing needs cancelling.
+    if (signal.aborted)
+        return Promise.reject(abortError(signal));
+    return runWithAbortSignal(signal, cancel, run);
+}
+async function runWithAbortSignal(signal, cancel, run) {
+    const onAbort = () => {
+        // A failed cancel (the session already gone, say) must not replace the
+        // error the query itself is about to report.
+        cancel().catch(() => undefined);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        return await run();
+    }
+    catch (e) {
+        if (signal.aborted)
+            throw abortError(signal, e);
+        throw e;
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}

package/util/array-calculatedim.js

@@ -3,7 +3,9 @@ export function arrayCalculateDim(arr) {
         return [0];
     const dim = [arr.length];
     const iterate = (a, level) => {
-        for (let i = 0; i < a.length; i++) {
+        let i;
+        const l = a.length;
+        for (i = 0; i < l; i++) {
             if (Array.isArray(a[i])) {
                 dim[level] = Math.max(dim[level] || 0, a[i].length);
                 iterate(a[i], level + 1);