neonctl 2.37.0 → 2.38.0

package/dist/psql/command/cmd_lo.js

@@ -1,393 +0,0 @@
-/**
- * psql large-object backslash commands (WP-23).
- *
- * TypeScript port of upstream `src/bin/psql/large_obj.c`:
- *
- *   - `\lo_list` / `\lo_list+` — list large-object metadata
- *   - `\lo_import FILE [COMMENT]` — read a local file, store as new LO
- *   - `\lo_export OID FILE` — read LO, write to a local file
- *   - `\lo_unlink OID` — delete an LO
- *
- * The upstream `do_lo_*` functions wrap their work in
- * `start_lo_xact`/`finish_lo_xact` and call libpq's lo client API
- * (`lo_import`, `lo_export`, `lo_unlink`). We don't have libpq's
- * client-side large-object API in this TS port, so we drive the same
- * operations through the server-side functions that psql ≥ 9.4 exposes:
- *
- *   - `pg_catalog.lo_from_bytea(0, $bytea)` returns the new OID in one
- *     call (replaces the upstream lo_creat + lo_write loop).
- *   - `pg_catalog.lo_get($oid)` returns the bytes as a `bytea` value.
- *   - `pg_catalog.lo_unlink($oid)` deletes the LO.
- *
- * All three calls use the connection's extended-query path (WP-21) for
- * parameter binding, which keeps us out of the libpq escape dance.
- * Bytea payloads are sent as `\x<hex>` text — the server's text-format
- * bytea parser converts back to bytes.
- *
- * `\lo_list` runs the same SELECT against `pg_largeobject_metadata` that
- * upstream's `listLargeObjects()` from `describe.c` uses (already ported
- * in WP-20's `queries.ts::listLargeObjects`). We register a primary
- * `lo_list` / `lo_list+` spec here so the dispatcher takes our entry
- * over the existing alias `dl::lo_list` (which would not match the
- * `+` suffix).
- *
- * Variable side-effects: `\lo_import` sets `LASTOID` to the new OID
- * (mirrors `do_lo_import`'s `SetVariable(pset.vars, "LASTOID", oidbuf)`).
- */
-import { Buffer } from "node:buffer";
-import { promises as fsPromises } from "node:fs";
-import { listLargeObjects } from "../describe/queries.js";
-import { alignedPrinter } from "../print/aligned.js";
-import { writeErr, writeOut } from "./shared.js";
-// ---------------------------------------------------------------------------
-// Helpers shared by all four commands
-// ---------------------------------------------------------------------------
-/** Return the live connection, or null. */
-const conn = (ctx) => ctx.settings.db;
-/** Emit "no current connection" error in the psql style. */
-const noConn = (ctx) => {
-    writeErr(`\\${ctx.cmdName}: no connection to the server\n`);
-    ctx.settings.lastErrorResult = { message: "no connection to the server" };
-    return { status: "error" };
-};
-/** Pull the diagnostic-style error message off a thrown value. */
-const errMsg = (err) => err instanceof Error ? err.message : String(err);
-/**
- * Encode a `Buffer` as a Postgres text-format bytea literal: `\x<hex>`.
- * Hex form is unambiguous and works regardless of `bytea_output` or
- * `standard_conforming_strings`.
- */
-const byteaText = (buf) => `\\x${buf.toString("hex")}`;
-/**
- * Parse a string argument as an unsigned 32-bit OID. Returns `null` on
- * malformed input (negative, non-integer, or out of range). Matches the
- * permissive behaviour of upstream `atooid`, which accepts any leading
- * digit run.
- */
-const parseOid = (raw) => {
-    if (!/^\d+$/.test(raw))
-        return null;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n < 0 || n > 0xffffffff)
-        return null;
-    return n;
-};
-/**
- * Coerce a single cell coming back from the protocol layer into a string.
- * Used by the `\lo_list` renderer. Matches the helper in
- * `describe/formatters.ts`.
- */
-const cellToString = (v) => {
-    if (v === null || v === undefined)
-        return "";
-    if (typeof v === "string")
-        return v;
-    if (Buffer.isBuffer(v))
-        return v.toString("utf-8");
-    if (typeof v === "number" ||
-        typeof v === "boolean" ||
-        typeof v === "bigint") {
-        return String(v);
-    }
-    try {
-        return JSON.stringify(v);
-    }
-    catch {
-        return "";
-    }
-};
-// ---------------------------------------------------------------------------
-// \lo_list / \lo_list+
-// ---------------------------------------------------------------------------
-/**
- * Render the result of `listLargeObjects` through the aligned printer.
- * The query body itself lives in `describe/queries.ts` (WP-20) — we just
- * dispatch to it and feed the result through `alignedPrinter` with the
- * upstream "Large objects" title.
- */
-const runLoList = async (ctx, verbose) => {
-    const c = conn(ctx);
-    if (!c)
-        return noConn(ctx);
-    const query = listLargeObjects({ verbose, serverVersion: c.serverVersion });
-    try {
-        const rs = await c.query(query.sql, query.params);
-        const coerced = {
-            ...rs,
-            rows: rs.rows.map((row) => row.map((v) => v === null || v === undefined ? null : cellToString(v))),
-        };
-        const titleOverride = query.description ?? ctx.settings.popt.title;
-        const opts = {
-            ...ctx.settings.popt,
-            title: titleOverride,
-            topt: {
-                ...ctx.settings.popt.topt,
-                title: titleOverride ?? ctx.settings.popt.topt.title,
-            },
-        };
-        await alignedPrinter.printQuery(coerced, opts, process.stdout);
-        return { status: "ok" };
-    }
-    catch (err) {
-        writeErr(`\\${ctx.cmdName}: ${errMsg(err)}\n`);
-        ctx.settings.lastErrorResult = { message: errMsg(err) };
-        return { status: "error" };
-    }
-};
-/** `\lo_list` — non-verbose listing. */
-export const cmdLoList = {
-    name: "lo_list",
-    helpKey: "lo_list",
-    run: (ctx) => runLoList(ctx, false),
-};
-/** `\lo_list+` — verbose listing (adds Access privileges column). */
-export const cmdLoListPlus = {
-    name: "lo_list+",
-    helpKey: "lo_list",
-    run: (ctx) => runLoList(ctx, true),
-};
-// ---------------------------------------------------------------------------
-// \lo_import FILE [COMMENT]
-// ---------------------------------------------------------------------------
-/**
- * `\lo_import FILE [COMMENT]`.
- *
- * Strategy:
- *   1. `fs.readFile(file)` → Buffer.
- *   2. `SELECT pg_catalog.lo_from_bytea(0, $1::bytea)` → new OID. The
- *      bytea param is the file's bytes serialized as `\x<hex>` text.
- *   3. If COMMENT was supplied: `COMMENT ON LARGE OBJECT <oid> IS
- *      '<escaped>'` (single execSimple round-trip, escaped via the
- *      connection's `escapeLiteral`).
- *   4. Print `lo_import <oid>\n` and set the `LASTOID` variable.
- *
- * Errors fall through to the standard `\lo_import: <msg>` diagnostic.
- */
-export const cmdLoImport = {
-    name: "lo_import",
-    helpKey: "lo_import",
-    run: async (ctx) => {
-        const c = conn(ctx);
-        if (!c)
-            return noConn(ctx);
-        const file = ctx.nextArg("normal");
-        if (file === null || file.length === 0) {
-            writeErr("\\lo_import: missing required argument\n");
-            ctx.settings.lastErrorResult = {
-                message: "missing required argument",
-            };
-            return { status: "error" };
-        }
-        // Comment is the next lexed slash-arg token, mirroring upstream
-        // `do_lo_import`'s second `psql_scan_slash_option(OT_NORMAL)`. Using the
-        // lexer (not the raw line) means it picks up the token AFTER the file —
-        // `restOfLine()` ignored the read cursor and re-included the filename
-        // itself in the comment.
-        const commentRaw = ctx.nextArg("normal");
-        const comment = commentRaw !== null && commentRaw.length > 0 ? commentRaw : null;
-        let bytes;
-        try {
-            bytes = await fsPromises.readFile(file);
-        }
-        catch (err) {
-            writeErr(`\\lo_import: ${errMsg(err)}\n`);
-            ctx.settings.lastErrorResult = { message: errMsg(err) };
-            return { status: "error" };
-        }
-        let oidStr;
-        try {
-            const rs = await c.query("SELECT pg_catalog.lo_from_bytea(0, $1::bytea)", [byteaText(bytes)]);
-            if (rs.rows.length === 0) {
-                throw new Error("lo_from_bytea returned no rows");
-            }
-            oidStr = cellToString(rs.rows[0][0]);
-            if (!/^\d+$/.test(oidStr)) {
-                throw new Error(`lo_from_bytea returned invalid oid: ${oidStr}`);
-            }
-        }
-        catch (err) {
-            writeErr(`\\lo_import: ${errMsg(err)}\n`);
-            ctx.settings.lastErrorResult = { message: errMsg(err) };
-            return { status: "error" };
-        }
-        if (comment !== null) {
-            try {
-                await c.execSimple(`COMMENT ON LARGE OBJECT ${oidStr} IS ${c.escapeLiteral(comment)}`);
-            }
-            catch (err) {
-                writeErr(`\\lo_import: ${errMsg(err)}\n`);
-                ctx.settings.lastErrorResult = { message: errMsg(err) };
-                return { status: "error" };
-            }
-        }
-        // Side effect: set LASTOID (matches upstream `do_lo_import`).
-        ctx.settings.vars.set("LASTOID", oidStr);
-        writeOut(`lo_import ${oidStr}\n`);
-        return { status: "ok" };
-    },
-};
-// ---------------------------------------------------------------------------
-// \lo_export OID FILE
-// ---------------------------------------------------------------------------
-/**
- * `\lo_export OID FILE`.
- *
- * `SELECT pg_catalog.lo_get($1::oid)` returns a single-row, single-col
- * result whose cell is the LO's bytes. We then `fs.writeFile` to the
- * supplied path. The protocol layer decodes bytea text into a `Buffer`
- * for us when the column oid is bytea; if we get a `\x...` string back
- * we decode it explicitly.
- *
- * Print `lo_export\n` on success — matches upstream `do_lo_export`.
- */
-export const cmdLoExport = {
-    name: "lo_export",
-    helpKey: "lo_export",
-    run: async (ctx) => {
-        const c = conn(ctx);
-        if (!c)
-            return noConn(ctx);
-        const oidArg = ctx.nextArg("normal");
-        const file = ctx.nextArg("normal");
-        if (oidArg === null || file === null || file.length === 0) {
-            writeErr("\\lo_export: missing required argument\n");
-            ctx.settings.lastErrorResult = {
-                message: "missing required argument",
-            };
-            return { status: "error" };
-        }
-        const oid = parseOid(oidArg);
-        if (oid === null) {
-            writeErr(`\\lo_export: "${oidArg}" is not a valid large object OID\n`);
-            ctx.settings.lastErrorResult = { message: "invalid OID" };
-            return { status: "error" };
-        }
-        let bytes;
-        try {
-            const rs = await c.query("SELECT pg_catalog.lo_get($1::oid)", [
-                oid,
-            ]);
-            if (rs.rows.length === 0) {
-                throw new Error("lo_get returned no rows");
-            }
-            const cell = rs.rows[0][0];
-            bytes = coerceBytea(cell);
-        }
-        catch (err) {
-            writeErr(`\\lo_export: ${errMsg(err)}\n`);
-            ctx.settings.lastErrorResult = { message: errMsg(err) };
-            return { status: "error" };
-        }
-        try {
-            await fsPromises.writeFile(file, bytes);
-        }
-        catch (err) {
-            writeErr(`\\lo_export: ${errMsg(err)}\n`);
-            ctx.settings.lastErrorResult = { message: errMsg(err) };
-            return { status: "error" };
-        }
-        writeOut("lo_export\n");
-        return { status: "ok" };
-    },
-};
-/**
- * Decode a bytea cell coming back from the protocol. The connection may
- * deliver:
- *   - a `Buffer` (decoded by a future binary-format path)
- *   - a `\x<hex>` string (text format, modern)
- *   - a legacy `octal-escape` string (text format, pre-9.0 servers; we
- *     don't generate this but it's the historical default).
- */
-const coerceBytea = (cell) => {
-    if (Buffer.isBuffer(cell))
-        return cell;
-    if (typeof cell !== "string") {
-        throw new Error(`lo_get returned unexpected cell type: ${typeof cell}`);
-    }
-    if (cell.startsWith("\\x")) {
-        return Buffer.from(cell.slice(2), "hex");
-    }
-    // Legacy octal-escape decode (`\\\\NNN` → byte, `\\\\` → `\\`, others
-    // pass through). Upstream `PQunescapeBytea` does the same.
-    const out = [];
-    let i = 0;
-    while (i < cell.length) {
-        if (cell[i] === "\\") {
-            if (cell[i + 1] === "\\") {
-                out.push(0x5c);
-                i += 2;
-                continue;
-            }
-            if (/^[0-7][0-7][0-7]$/.test(cell.slice(i + 1, i + 4))) {
-                out.push(parseInt(cell.slice(i + 1, i + 4), 8));
-                i += 4;
-                continue;
-            }
-        }
-        out.push(cell.charCodeAt(i));
-        i++;
-    }
-    return Buffer.from(out);
-};
-// ---------------------------------------------------------------------------
-// \lo_unlink OID
-// ---------------------------------------------------------------------------
-/**
- * `\lo_unlink OID` — drop a large object by OID. Implemented via
- * `SELECT pg_catalog.lo_unlink($1::oid)`. The function returns `1` on
- * success or raises an ERROR on missing OID; we just surface either
- * outcome.
- *
- * Print `lo_unlink <oid>\n` on success.
- */
-export const cmdLoUnlink = {
-    name: "lo_unlink",
-    helpKey: "lo_unlink",
-    run: async (ctx) => {
-        const c = conn(ctx);
-        if (!c)
-            return noConn(ctx);
-        const oidArg = ctx.nextArg("normal");
-        if (oidArg === null) {
-            writeErr("\\lo_unlink: missing required argument\n");
-            ctx.settings.lastErrorResult = {
-                message: "missing required argument",
-            };
-            return { status: "error" };
-        }
-        const oid = parseOid(oidArg);
-        if (oid === null) {
-            writeErr(`\\lo_unlink: "${oidArg}" is not a valid large object OID\n`);
-            ctx.settings.lastErrorResult = { message: "invalid OID" };
-            return { status: "error" };
-        }
-        try {
-            await c.query("SELECT pg_catalog.lo_unlink($1::oid)", [oid]);
-        }
-        catch (err) {
-            writeErr(`\\lo_unlink: ${errMsg(err)}\n`);
-            ctx.settings.lastErrorResult = { message: errMsg(err) };
-            return { status: "error" };
-        }
-        writeOut(`lo_unlink ${String(oid)}\n`);
-        return { status: "ok" };
-    },
-};
-// ---------------------------------------------------------------------------
-// Registration
-// ---------------------------------------------------------------------------
-/**
- * Register the four large-object commands on the supplied registry.
- * Called from `dispatch.ts::defaultRegistry()` (one new line).
- *
- * Note: `\lo_list` and `\lo_list+` shadow the existing `dl::lo_list`
- * alias from `cmd_describe.ts` — the registry's lookup checks primary
- * names before alias mappings, so this registration is the winning one.
- */
-export const registerLargeObjectCommands = (registry) => {
-    registry.register(cmdLoList);
-    registry.register(cmdLoListPlus);
-    registry.register(cmdLoImport);
-    registry.register(cmdLoExport);
-    registry.register(cmdLoUnlink);
-};