neonctl 2.22.0 → 2.23.0

package/psql/wire/protocol.js

@@ -0,0 +1,466 @@
+/**
+ * PostgreSQL wire protocol message codec — thin adapter over `pg-protocol`.
+ *
+ * Background (per the plan): the original module was a hand-rolled wire codec
+ * for protocol v3.0. We've now swapped the bytes for `pg-protocol@1.14`
+ * (node-postgres' upstream codec) and this file is the seam:
+ *
+ *   - Frontend builders (`Query`, `StartupMessage`, `Parse`, `Bind`, …) are
+ *     re-exports of `serialize.*` adapted to our existing call signatures, so
+ *     `connection.ts` and `pipeline.ts` keep working unchanged.
+ *   - `MessageParser` wraps pg-protocol's synchronous `Parser` and reshapes
+ *     each parsed message into our existing `BackendMessage` union — so the
+ *     connection-state-machine switches on `.type` ('RowDescription', 'DataRow',
+ *     …) and reads the same field names ('values', 'tag', 'fields', …) as
+ *     before.
+ *
+ * Exceptions (kept hand-rolled):
+ *
+ *   - `CancelRequest`: pg-protocol exposes one as `serialize.cancel`, and it
+ *     is layout-compatible with our previous output. We delegate to it.
+ *   - `SSLRequest`: pg-protocol *does* expose this as `serialize.requestSsl`;
+ *     we re-export it for symmetry. No hand-roll needed.
+ *   - `StartupMessage`: pg-protocol's `serialize.startup` unconditionally
+ *     appends `client_encoding=UTF8` to whatever the caller supplies. We
+ *     defensively filter `client_encoding` from the caller-provided map
+ *     before passing through, since our connect layer always sets it to UTF8
+ *     anyway. If it's set to something else, that's a caller bug — assert.
+ *
+ * Why this shim layer (instead of using pg-protocol directly):
+ *
+ *   - Field-name mapping. pg-protocol's parser emits camelCase names
+ *     (`'rowDescription'`, `'dataRow'`, …) and uses different field names
+ *     (`fields` vs `values`, `text` vs `tag`, `processID` vs `processId`).
+ *     Translating in one place keeps `connection.ts` minimal.
+ *   - DataRow values. pg-protocol parses every value as a UTF-8 string;
+ *     our connection layer expects `(Buffer | null)[]` (so binary-format
+ *     columns can keep their bytes intact later). We re-buffer here.
+ *   - ErrorResponse / NoticeResponse fields. pg-protocol attaches the parsed
+ *     fields as named properties on the Error/Notice instance. We re-pack
+ *     them into the Map<tag,value> shape our `fieldsToNotice` helper consumes.
+ */
+import { Buffer } from 'node:buffer';
+// pg-protocol@1.14 ships two entry points via its `exports` map:
+//   - `./esm/index.js` (the `"import"` key) — a thin ESM wrapper that does
+//     `import * as protocol from '../dist/index.js'`.
+//   - `./dist/index.js` (the `"require"` / `"default"` keys) — the actual
+//     CJS implementation.
+// On Node 20, resolving `'pg-protocol'` from an ESM context picks the
+// `esm/index.js` wrapper, BUT the surrounding `package.json` has no
+// `"type": "module"` field. Node 20 still parses the wrapper as CJS, hits
+// the `import` syntax, and dies with `SyntaxError: Cannot use import
+// statement outside a module`. Node 22+ honours the `"import"` exports
+// key as a forced-ESM hint and avoids this. To stay portable across both,
+// we import the CJS implementation directly — same pattern node-postgres
+// uses for the `Parser` subpath, and what we already do on the next line.
+import pgProtocol from 'pg-protocol/dist/index.js';
+const { serialize } = pgProtocol;
+import { Parser } from 'pg-protocol/dist/parser.js';
+export class ProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProtocolError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Frontend message encoders
+//
+// These are thin wrappers over `pg-protocol`'s `serialize.*`. The signatures
+// mirror our previous hand-rolled API so callers in `connection.ts` and
+// `pipeline.ts` don't need to change.
+// ---------------------------------------------------------------------------
+/**
+ * StartupMessage. pg-protocol always appends `client_encoding=UTF8`; we
+ * strip any incoming `client_encoding` to avoid duplicating it on the wire.
+ * Our connect layer always sets UTF8 anyway, so this is a no-op in practice.
+ */
+export function StartupMessage(params) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        if (key === 'client_encoding')
+            continue;
+        filtered[key] = value;
+    }
+    return serialize.startup(filtered);
+}
+/** SSLRequest — pg-protocol exposes this as `requestSsl`. */
+export function SSLRequest() {
+    return serialize.requestSsl();
+}
+/** CancelRequest — pg-protocol's `cancel` is layout-compatible. */
+export function CancelRequest(processId, secretKey) {
+    return serialize.cancel(processId, secretKey);
+}
+/** Query: 'Q' + cstring(sql). */
+export function Query(sql) {
+    return serialize.query(sql);
+}
+/** Terminate: 'X' + 4-byte length. */
+export function Terminate() {
+    return serialize.end();
+}
+/** Sync: 'S' + 4-byte length. */
+export function Sync() {
+    return serialize.sync();
+}
+/** Flush: 'H' + 4-byte length. */
+export function Flush() {
+    return serialize.flush();
+}
+/** Parse: 'P' + cstring(name) + cstring(sql) + Int16 nparam + {Int32 oid}*. */
+export function Parse(name, sql, paramTypes) {
+    return serialize.parse({ name, text: sql, types: paramTypes });
+}
+/**
+ * Bind: 'B' + cstring(portal) + cstring(stmt) + per-value param formats +
+ * value array + result formats.
+ *
+ * Note on parameter formats: pg-protocol's `serialize.bind` auto-detects the
+ * format byte per value (`Buffer → 1`, `string/null → 0`); the caller-supplied
+ * `paramFormats` arg is therefore ignored. This matches the hand-rolled
+ * codec's effective behaviour because every caller passes either an empty
+ * array (= "all text", which is what pg-protocol picks for strings) or a
+ * format list that already agrees with the value's type.
+ *
+ * Note on result formats: we want every column in *text* format (`[0]`) for
+ * `psql`-style printing. pg-protocol forces a single shared result-format
+ * byte (`binary: boolean`); we pass `binary: false` to get text columns
+ * regardless of the caller-supplied `resultFormats` array.
+ */
+export function Bind(portal, stmt, paramFormats, params, resultFormats) {
+    // `paramFormats` and `resultFormats` are read for the rare future caller
+    // that might want explicit control; pg-protocol's `serialize.bind` doesn't
+    // expose either, so we intentionally drop them on the floor for now.
+    void paramFormats;
+    void resultFormats;
+    return serialize.bind({
+        portal,
+        statement: stmt,
+        values: params,
+        binary: false,
+    });
+}
+/** Describe: 'D' + byte('S'|'P') + cstring(name). */
+export function Describe(target, name) {
+    return serialize.describe({ type: target, name });
+}
+/** Execute: 'E' + cstring(portal) + Int32 maxRows. */
+export function Execute(portal, maxRows) {
+    return serialize.execute({ portal, rows: maxRows });
+}
+/** Close: 'C' + byte('S'|'P') + cstring(name). */
+export function Close(target, name) {
+    return serialize.close({ type: target, name });
+}
+/** PasswordMessage: 'p' + cstring(password). */
+export function PasswordMessage(password) {
+    return serialize.password(password);
+}
+/**
+ * SASLInitialResponse: 'p' + cstring(mechanism) + Int32(bodyLen) + body.
+ *
+ * pg-protocol takes the initial response as a *string*; our SCRAM client
+ * hands back a Buffer. SCRAM-SHA-256 messages are ASCII so this round-trips
+ * losslessly via UTF-8.
+ */
+export function SASLInitialResponse(mechanism, response) {
+    return serialize.sendSASLInitialResponseMessage(mechanism, response.toString('utf8'));
+}
+/** SASLResponse: 'p' + opaque body (no NUL terminator). */
+export function SASLResponse(response) {
+    return serialize.sendSCRAMClientFinalMessage(response.toString('utf8'));
+}
+/** CopyData: 'd' + opaque bytes. */
+export function CopyData(data) {
+    return serialize.copyData(data);
+}
+/** CopyDone: 'c' + 4-byte length. */
+export function CopyDone() {
+    return serialize.copyDone();
+}
+/** CopyFail: 'f' + cstring(reason). */
+export function CopyFail(message) {
+    return serialize.copyFail(message);
+}
+// ---------------------------------------------------------------------------
+// Backend message parser
+// ---------------------------------------------------------------------------
+/**
+ * Streaming framer with a synchronous `feed()` API.
+ *
+ * Internally delegates to `pg-protocol`'s `Parser` (which exposes a
+ * `parse(buffer, callback)` method that emits each completed backend message
+ * via callback). On each `feed()` call we drain the parser and collect the
+ * emitted messages into an array, reshaping each pg-protocol message into our
+ * `BackendMessage` union (so `connection.ts`'s switch arms keep working).
+ *
+ * pg-protocol's `Parser.parse` calls the callback synchronously for every
+ * complete message and keeps incomplete trailing bytes buffered internally.
+ * That's a near-perfect match for our previous hand-rolled `MessageParser`.
+ */
+export class MessageParser {
+    constructor() {
+        this.inner = new Parser();
+        /** Bytes buffered inside `inner` but not yet emitted. Diagnostic only. */
+        this.buffered = 0;
+    }
+    feed(chunk) {
+        const out = [];
+        try {
+            this.inner.parse(chunk, (msg) => {
+                out.push(adaptBackendMessage(msg));
+            });
+        }
+        catch (err) {
+            // pg-protocol throws plain `Error` on bad input (unknown auth
+            // subtype, truncated frames, …). Normalize to our type.
+            throw err instanceof ProtocolError
+                ? err
+                : new ProtocolError(err instanceof Error ? err.message : String(err));
+        }
+        // Probe the parser's leftover length via its internal field. Used by a
+        // handful of tests for diagnostics; not relied on in production code.
+        const probe = this.inner;
+        this.buffered = probe.bufferLength ?? 0;
+        return out;
+    }
+    /**
+     * Number of bytes buffered but not yet emitted (e.g. partial trailing
+     * message). Exposed for tests / diagnostics.
+     */
+    get bufferedBytes() {
+        return this.buffered;
+    }
+}
+function adaptBackendMessage(raw) {
+    const msg = raw;
+    switch (msg.name) {
+        case 'authenticationOk':
+            return { type: 'AuthenticationOk' };
+        case 'authenticationCleartextPassword':
+            return { type: 'AuthenticationCleartextPassword' };
+        case 'authenticationMD5Password':
+            return {
+                type: 'AuthenticationMD5Password',
+                salt: Buffer.from(msg.salt),
+            };
+        case 'authenticationSASL':
+            return {
+                type: 'AuthenticationSASL',
+                mechanisms: msg.mechanisms,
+            };
+        case 'authenticationSASLContinue':
+            return {
+                type: 'AuthenticationSASLContinue',
+                data: Buffer.from(msg.data, 'utf8'),
+            };
+        case 'authenticationSASLFinal':
+            return {
+                type: 'AuthenticationSASLFinal',
+                data: Buffer.from(msg.data, 'utf8'),
+            };
+        case 'parameterStatus':
+            return {
+                type: 'ParameterStatus',
+                name: msg.parameterName,
+                value: msg.parameterValue,
+            };
+        case 'backendKeyData':
+            return {
+                type: 'BackendKeyData',
+                processId: msg.processID,
+                secretKey: msg.secretKey,
+            };
+        case 'readyForQuery': {
+            const status = msg.status;
+            if (status !== 'I' && status !== 'T' && status !== 'E') {
+                throw new ProtocolError(`ReadyForQuery: unexpected status ${JSON.stringify(status)}`);
+            }
+            return { type: 'ReadyForQuery', status };
+        }
+        case 'rowDescription': {
+            const fields = msg.fields.map((f) => ({
+                name: f.name,
+                tableID: f.tableID,
+                columnID: f.columnID,
+                dataTypeID: f.dataTypeID,
+                dataTypeSize: f.dataTypeSize,
+                dataTypeModifier: f.dataTypeModifier,
+                format: f.format === 'binary' ? 1 : 0,
+            }));
+            return { type: 'RowDescription', fields };
+        }
+        case 'dataRow': {
+            // pg-protocol always parses values as UTF-8 strings (or null for SQL
+            // NULL). Our connection layer expects (Buffer | null)[] so it can hand
+            // text-format columns through `.toString('utf8')` and pass binary
+            // columns through unchanged. Re-encode here.
+            const fields = msg.fields;
+            const values = new Array(fields.length);
+            for (let i = 0; i < fields.length; i++) {
+                const v = fields[i];
+                values[i] = v === null ? null : Buffer.from(v, 'utf8');
+            }
+            return { type: 'DataRow', values };
+        }
+        case 'commandComplete':
+            return { type: 'CommandComplete', tag: msg.text };
+        case 'emptyQuery':
+            return { type: 'EmptyQueryResponse' };
+        case 'error':
+            return { type: 'ErrorResponse', fields: errorOrNoticeFields(msg) };
+        case 'notice':
+            return { type: 'NoticeResponse', fields: errorOrNoticeFields(msg) };
+        case 'notification':
+            return {
+                type: 'NotificationResponse',
+                processId: msg.processId,
+                channel: msg.channel,
+                payload: msg.payload,
+            };
+        case 'copyInResponse':
+            return adaptCopyResponse('CopyInResponse', msg);
+        case 'copyOutResponse':
+            return adaptCopyResponse('CopyOutResponse', msg);
+        case 'replicationStart':
+            // pg-protocol emits a bare marker for the 'W' (CopyBothResponse) byte
+            // — its `Parser` recognises the message code but does not decode the
+            // payload (overall format + per-column format bytes). The body shape
+            // is identical to CopyInResponse / CopyOutResponse but we don't need
+            // those fields: the connection layer reacts to CopyBothResponse by
+            // raising a clean diagnostic because this client does not implement
+            // CopyBoth streaming.
+            return { type: 'CopyBothResponse' };
+        case 'copyData':
+            return { type: 'CopyData', data: Buffer.from(msg.chunk) };
+        case 'copyDone':
+            return { type: 'CopyDone' };
+        case 'noData':
+            return { type: 'NoData' };
+        case 'parseComplete':
+            return { type: 'ParseComplete' };
+        case 'bindComplete':
+            return { type: 'BindComplete' };
+        case 'closeComplete':
+            return { type: 'CloseComplete' };
+        case 'portalSuspended':
+            return { type: 'PortalSuspended' };
+        case 'parameterDescription':
+            return {
+                type: 'ParameterDescription',
+                oids: msg.dataTypeIDs,
+            };
+        default:
+            throw new ProtocolError(`Unknown backend message: ${String(msg.name)}`);
+    }
+}
+function adaptCopyResponse(type, msg) {
+    const binary = msg.binary;
+    const columnTypes = msg.columnTypes;
+    const columnFormats = columnTypes.map((f) => (f === 1 ? 1 : 0));
+    return {
+        type,
+        overallFormat: binary ? 1 : 0,
+        columnFormats,
+    };
+}
+/**
+ * Re-pack pg-protocol's flattened Error/Notice fields (named properties like
+ * `severity`, `code`, `detail`, …) into our previous `Map<tag, value>` shape
+ * keyed by the on-wire single-letter tag. The map is consumed by
+ * `fieldsToNotice` below.
+ */
+function errorOrNoticeFields(msg) {
+    const out = new Map();
+    // The on-wire tag → field-name mapping is per PG docs §53.8. pg-protocol
+    // stores `severity` from BOTH `S` and `V` (it overwrites with `V` if present)
+    // — to preserve our previous behaviour (where the map carried both raw
+    // tags), we copy S = V = severity when severity is defined. Consumers like
+    // `fieldsToNotice` look at V then S so this matches.
+    const set = (tag, value) => {
+        if (typeof value === 'string')
+            out.set(tag, value);
+    };
+    set('S', msg.severity);
+    set('V', msg.severity);
+    set('C', msg.code);
+    set('M', msg.message);
+    set('D', msg.detail);
+    set('H', msg.hint);
+    set('P', msg.position);
+    set('p', msg.internalPosition);
+    set('q', msg.internalQuery);
+    set('W', msg.where);
+    set('s', msg.schema);
+    set('t', msg.table);
+    set('c', msg.column);
+    set('d', msg.dataType);
+    set('n', msg.constraint);
+    set('F', msg.file);
+    set('L', msg.line);
+    set('R', msg.routine);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Notice helper (unchanged; consumed by connection.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Convert a notice/error field map into a Notice-shaped object. The wire
+ * tags are PG's single-letter codes; we promote the ones the Connection
+ * interface exposes.
+ */
+export function fieldsToNotice(fields) {
+    // Per PG docs: V is the non-localized severity (preferred when present),
+    // S is the localized severity (always present). Message M is mandatory.
+    const severity = fields.get('V') ?? fields.get('S') ?? '';
+    const message = fields.get('M') ?? '';
+    const out = { severity, message };
+    const code = fields.get('C');
+    if (code !== undefined)
+        out.code = code;
+    const detail = fields.get('D');
+    if (detail !== undefined)
+        out.detail = detail;
+    const hint = fields.get('H');
+    if (hint !== undefined)
+        out.hint = hint;
+    const position = fields.get('P');
+    if (position !== undefined)
+        out.position = position;
+    const internalPosition = fields.get('p');
+    if (internalPosition !== undefined)
+        out.internalPosition = internalPosition;
+    const internalQuery = fields.get('q');
+    if (internalQuery !== undefined)
+        out.internalQuery = internalQuery;
+    const where = fields.get('W');
+    if (where !== undefined)
+        out.where = where;
+    const schema = fields.get('s');
+    if (schema !== undefined)
+        out.schema = schema;
+    const table = fields.get('t');
+    if (table !== undefined)
+        out.table = table;
+    const column = fields.get('c');
+    if (column !== undefined)
+        out.column = column;
+    const dataType = fields.get('d');
+    if (dataType !== undefined)
+        out.dataType = dataType;
+    const constraint = fields.get('n');
+    if (constraint !== undefined)
+        out.constraint = constraint;
+    const file = fields.get('F');
+    if (file !== undefined)
+        out.file = file;
+    const line = fields.get('L');
+    if (line !== undefined)
+        out.line = line;
+    const routine = fields.get('R');
+    if (routine !== undefined)
+        out.routine = routine;
+    return out;
+}