neonctl 2.22.0 → 2.23.0

package/psql/io/pgservice.js

@@ -0,0 +1,194 @@
+/**
+ * `pg_service.conf` (connection service file) support.
+ *
+ * TypeScript port of libpq's `parseServiceInfo` in `src/interfaces/libpq/
+ * fe-connect.c`. A service file is an INI-style document with one section
+ * per service name; each section's `key=value` pairs map onto libpq
+ * connection parameters.
+ *
+ * Format:
+ *
+ *   # this is a comment
+ *   [servicename]
+ *   host=foo.example.com
+ *   port=5432
+ *   dbname=mydb
+ *   user=myuser
+ *
+ *   [other]
+ *   host=bar
+ *
+ * Resolution order (mirrors libpq):
+ *
+ *   1. `$PGSERVICEFILE` if set and non-empty
+ *   2. `~/.pg_service.conf` (POSIX) / `%APPDATA%\postgresql\.pg_service.conf`
+ *      (Windows)
+ *   3. `$PGSYSCONFDIR/pg_service.conf`
+ *   4. `/etc/pg_service.conf` (POSIX platform-default fallback)
+ *
+ * Files are stat'd in order; the first existing file wins. (libpq merges
+ * service entries across files in load order; we read only the first
+ * existing one to match what neonctl users actually rely on. This matches
+ * the documented "search path" behaviour.)
+ *
+ * Keys in a service section are case-sensitive; the section header is the
+ * service name (libpq normalises neither). Unknown keys are accepted
+ * silently — libpq would also accept them and feed them to `PQconninfoParse`,
+ * which is responsible for the recognised-key gate.
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const isWindows = process.platform === 'win32';
+/**
+ * Return the ordered list of candidate `pg_service.conf` paths to try. The
+ * caller stops at the first one that exists. Pure function — `env` defaults
+ * to `process.env` for ergonomics but can be injected for tests.
+ */
+export const defaultPgServiceFilePath = (env = process.env) => {
+    const out = [];
+    const explicit = env.PGSERVICEFILE;
+    if (explicit !== undefined && explicit.length > 0) {
+        out.push(explicit);
+    }
+    // User-level: `~/.pg_service.conf` (POSIX) or
+    // `%APPDATA%/postgresql/.pg_service.conf` (Windows). Matches libpq.
+    if (isWindows) {
+        const appdata = env.APPDATA;
+        if (appdata !== undefined && appdata.length > 0) {
+            out.push(path.join(appdata, 'postgresql', '.pg_service.conf'));
+        }
+    }
+    else {
+        const home = env.HOME ?? os.homedir();
+        if (home.length > 0) {
+            out.push(path.join(home, '.pg_service.conf'));
+        }
+    }
+    // System-level: `$PGSYSCONFDIR/pg_service.conf`.
+    const sysDir = env.PGSYSCONFDIR;
+    if (sysDir !== undefined && sysDir.length > 0) {
+        out.push(path.join(sysDir, 'pg_service.conf'));
+    }
+    // Platform-default system path. libpq's autoconf picks SYSCONFDIR at build
+    // time; for a portable TS implementation we use `/etc/pg_service.conf` on
+    // POSIX. Windows has no canonical equivalent.
+    if (!isWindows) {
+        out.push('/etc/pg_service.conf');
+    }
+    return out;
+};
+/**
+ * Parse the contents of a `pg_service.conf` string into a Map keyed by
+ * service name. Exported for tests; production callers should use
+ * `loadPgServices` which walks the discovery list.
+ *
+ * Parser behaviour:
+ *   - Lines starting with `#` (after leading whitespace) are comments.
+ *   - Blank lines are skipped.
+ *   - Section header `[name]` opens a new service; later sections with the
+ *     same name OVERRIDE earlier ones within the same file (libpq emits a
+ *     warning; we silently override).
+ *   - `key=value` lines populate the current section. Leading/trailing
+ *     whitespace around `key` and `value` is trimmed; values are NOT quoted
+ *     (libpq's parser is line-oriented).
+ *   - Lines outside any section header are silently ignored.
+ */
+export const parsePgServiceContent = (content) => {
+    const services = new Map();
+    let current;
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('#'))
+            continue;
+        if (line.startsWith('[')) {
+            const close = line.indexOf(']');
+            if (close < 0) {
+                // Malformed header — libpq aborts the file; we mirror by ending the
+                // current section so the bogus line doesn't bleed into it.
+                current = undefined;
+                continue;
+            }
+            const name = line.slice(1, close).trim();
+            if (name.length === 0) {
+                current = undefined;
+                continue;
+            }
+            current = {};
+            services.set(name, current);
+            continue;
+        }
+        if (current === undefined) {
+            // Stray key=value before any [section] header — libpq treats this as
+            // an error; we silently skip so a misformatted file doesn't refuse to
+            // resolve services that appear after the noise.
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (eq < 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        const value = line.slice(eq + 1).trim();
+        if (key.length === 0)
+            continue;
+        current[key] = value;
+    }
+    return services;
+};
+const readIfExists = async (filePath) => {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        // Permission / I/O errors silently degrade — libpq treats an unreadable
+        // service file the same as a missing one (the connection falls back to
+        // other parameter sources).
+        return null;
+    }
+};
+/**
+ * Discover and parse `pg_service.conf`. Walks the candidate list returned by
+ * `defaultPgServiceFilePath`, reading the first existing file.
+ *
+ * Resolves to an empty Map when no file is found. When the user has
+ * explicitly named a file via `$PGSERVICEFILE` and that file is missing,
+ * throws an error with the upstream wording — mirrors libpq's
+ * "service file %s not found" diagnostic (different from a silent
+ * discovery-chain miss, where each candidate may legitimately be absent).
+ *
+ * The `env` argument is exposed so tests can drive the user-specified
+ * branch without touching `process.env`. Production callers leave it
+ * defaulting to `process.env`.
+ */
+export const loadPgServices = async (paths, env = process.env) => {
+    const candidates = paths ?? defaultPgServiceFilePath(env);
+    const userSpecified = env.PGSERVICEFILE;
+    const userSpecifiedAbs = userSpecified !== undefined && userSpecified.length > 0
+        ? userSpecified
+        : null;
+    for (const p of candidates) {
+        const content = await readIfExists(p);
+        if (content === null) {
+            // Hard-fail when the user explicitly named this file (via
+            // PGSERVICEFILE) and it's missing. Silent ENOENT is fine for the
+            // discovery-chain candidates the user didn't ask for.
+            if (userSpecifiedAbs !== null && p === userSpecifiedAbs) {
+                throw new Error(`service file "${p}" not found`);
+            }
+            continue;
+        }
+        return parsePgServiceContent(content);
+    }
+    return new Map();
+};
+/**
+ * Look up a service section by name. Returns `undefined` if not present.
+ *
+ * Service names are case-sensitive (libpq does not normalise).
+ */
+export const lookupService = (services, name) => services.get(name);

package/psql/io/psqlrc.js

@@ -0,0 +1,422 @@
+/**
+ * `.psqlrc` autoload.
+ *
+ * TypeScript port of `process_psqlrc()` / `process_psqlrc_file()` in
+ * `src/bin/psql/startup.c`. Two responsibilities:
+ *
+ *   1. `defaultPsqlrcPath(env?)` — pure function returning the path psql
+ *      *would* read in the absence of a `$PSQLRC` override. Resolves to
+ *      `$HOME/.psqlrc` on POSIX and `%APPDATA%/postgresql/psqlrc.conf` on
+ *      Windows (the upstream layout).
+ *
+ *   2. `loadPsqlrc(ctx)` — discover and execute the rc files in upstream
+ *      order:
+ *        a. `$PGSYSCONFDIR/psqlrc-VERSION` and `$PGSYSCONFDIR/psqlrc`
+ *        b. `$PSQLRC` if non-empty (overrides $HOME path)
+ *        c. else `$HOME/.psqlrc-VERSION` then `$HOME/.psqlrc`
+ *      Each existing file's contents are split into statements via the same
+ *      `scanSql` boundary detector the mainloop uses, then dispatched
+ *      through `connection.execSimple` (for SQL) or the backslash registry
+ *      (for `\…` commands).
+ *
+ * Duplication note: we deliberately re-implement a minimal scan-and-dispatch
+ * loop here instead of routing through `core/mainloop.ts`. The mainloop is
+ * locked-down in WP-12 and adding an `executeInputString` helper to it would
+ * touch a file we can't modify in this WP. The two loops share `scanSql` and
+ * `dispatchBackslash` so the divergence is structural, not behavioural.
+ *
+ * Follow-up issue: refactor `mainloop.ts` to expose an `executeInputString`
+ * primitive and delete this duplication. Tracked TODO at the bottom of this
+ * file.
+ */
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { initialScanState } from '../types/scanner.js';
+import { scanSql } from '../scanner/sql.js';
+import { scanSlashArgs } from '../scanner/slash.js';
+import { dispatchBackslash } from '../command/dispatch.js';
+import { attachCondStack, COND_COMMAND_NAMES } from '../command/cmd_cond.js';
+import { sendQuery } from '../core/common.js';
+// ---------------------------------------------------------------------------
+// Path discovery.
+// ---------------------------------------------------------------------------
+const isWindows = process.platform === 'win32';
+const baseRcName = isWindows ? 'psqlrc.conf' : '.psqlrc';
+/**
+ * Return the default user-level psqlrc path. The path is *not* verified to
+ * exist — callers stat it lazily. The Windows layout follows upstream:
+ * `%APPDATA%/postgresql/psqlrc.conf`. On POSIX we use `$HOME/.psqlrc`.
+ */
+export const defaultPsqlrcPath = (env = process.env) => {
+    if (isWindows) {
+        const appData = env.APPDATA;
+        if (appData && appData.length > 0) {
+            return path.join(appData, 'postgresql', baseRcName);
+        }
+        return path.join(env.USERPROFILE ?? '', 'postgresql', baseRcName);
+    }
+    const home = env.HOME ?? '';
+    return path.join(home, baseRcName);
+};
+const versionSuffix = (serverVersion) => {
+    if (!serverVersion || serverVersion <= 0)
+        return null;
+    // PG numeric version is e.g. 170002 (17.2). Upstream uses both
+    // `psqlrc-PG_VERSION` (major.minor) and `psqlrc-PG_MAJORVERSION`. We use
+    // the major (e.g. 17) — the bigger of the two backwards-compat targets.
+    const major = Math.floor(serverVersion / 10000);
+    return String(major);
+};
+export const psqlrcCandidates = (env, serverVersion) => {
+    const out = [];
+    const suffix = versionSuffix(serverVersion);
+    // System-wide.
+    const sysDir = env.PGSYSCONFDIR;
+    if (sysDir && sysDir.length > 0) {
+        const sysBase = isWindows ? 'psqlrc.conf' : 'psqlrc';
+        if (suffix) {
+            out.push({
+                path: path.join(sysDir, `${sysBase}-${suffix}`),
+                description: 'system psqlrc (versioned)',
+            });
+        }
+        out.push({
+            path: path.join(sysDir, sysBase),
+            description: 'system psqlrc',
+        });
+    }
+    // PSQLRC override suppresses HOME-based discovery (matches upstream).
+    const envRc = env.PSQLRC;
+    if (envRc !== undefined && envRc !== '') {
+        out.push({ path: expandTilde(envRc, env), description: '$PSQLRC' });
+        return out;
+    }
+    // HOME-based.
+    const home = env.HOME ?? '';
+    if (isWindows) {
+        const appData = env.APPDATA;
+        const dir = appData && appData.length > 0
+            ? path.join(appData, 'postgresql')
+            : path.join(env.USERPROFILE ?? '', 'postgresql');
+        if (suffix) {
+            out.push({
+                path: path.join(dir, `${baseRcName}-${suffix}`),
+                description: 'user psqlrc (versioned)',
+            });
+        }
+        out.push({
+            path: path.join(dir, baseRcName),
+            description: 'user psqlrc',
+        });
+    }
+    else if (home.length > 0) {
+        if (suffix) {
+            out.push({
+                path: path.join(home, `${baseRcName}-${suffix}`),
+                description: 'user psqlrc (versioned)',
+            });
+        }
+        out.push({
+            path: path.join(home, baseRcName),
+            description: 'user psqlrc',
+        });
+    }
+    return out;
+};
+const expandTilde = (p, env) => {
+    if (p.startsWith('~/') && env.HOME) {
+        return path.join(env.HOME, p.slice(2));
+    }
+    if (p === '~' && env.HOME) {
+        return env.HOME;
+    }
+    return p;
+};
+// ---------------------------------------------------------------------------
+// File read + dispatch.
+// ---------------------------------------------------------------------------
+const readIfExists = async (file) => {
+    try {
+        return await fs.readFile(file, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        // Permission / I/O errors propagate — they're worth surfacing because
+        // they signal a likely misconfiguration. Mirror upstream which prints
+        // a warning but doesn't abort the session; we use a noop for now.
+        return null;
+    }
+};
+const makeBackslashContext = (ctx, cmdName, rawArgs, queryBuf) => {
+    const varLookup = (name) => ctx.settings.vars.get(name);
+    const buffered = new Map();
+    const cursors = new Map();
+    const argsFor = (mode) => {
+        const cached = buffered.get(mode);
+        if (cached)
+            return cached;
+        const parsed = scanSlashArgs(rawArgs, mode, varLookup);
+        buffered.set(mode, parsed);
+        return parsed;
+    };
+    const bctx = {
+        settings: ctx.settings,
+        cmdName,
+        queryBuf,
+        rawArgs,
+        nextArg(mode = 'normal') {
+            const av = argsFor(mode);
+            const idx = cursors.get(mode) ?? 0;
+            if (idx >= av.length)
+                return null;
+            cursors.set(mode, idx + 1);
+            return av[idx];
+        },
+        restOfLine() {
+            return rawArgs;
+        },
+    };
+    attachCondStack(bctx, ctx.cond);
+    return bctx;
+};
+/**
+ * Execute the supplied input string against the running REPL context. Used
+ * by `loadPsqlrc` (and exported for tests). This is a minimal cousin of
+ * `runMainLoop`'s processChunk — see the module header for the duplication
+ * rationale.
+ *
+ * Returns when EOF is reached; `\q` and other exit commands inside an rc
+ * file are treated as "stop reading this file" (the REPL itself continues).
+ *
+ * The returned outcome lets `runPsql`'s `-c`/`-f` loop apply upstream's
+ * per-switch exit-code semantics (see comment above).
+ */
+export const executeInputString = async (input, ctx, opts = {}) => {
+    let working = input;
+    let queryBuf = '';
+    let scanState = initialScanState();
+    let hadError = false;
+    let stoppedOnError = false;
+    let connectionLost = false;
+    const print = opts.print ?? false;
+    const noteConnectionLost = () => {
+        if (ctx.settings.db?.isClosed()) {
+            ctx.stderr.write('psql: error: connection to server was lost\n');
+            connectionLost = true;
+            return true;
+        }
+        return false;
+    };
+    // Inline `:NAME` substitution wired through SQL bodies (handled by
+    // scanSql). Slash-arg bodies are already substituted via
+    // `makeBackslashContext` above. Mirror the mainloop's wiring so `-c`/`-f`
+    // / .psqlrc inputs expand the same way as interactive input.
+    const sqlVarLookup = (name) => ctx.settings.vars.get(name);
+    while (working.length > 0) {
+        const r = scanSql(working, scanState, sqlVarLookup);
+        scanState = r.nextState;
+        if (r.kind === 'semicolon') {
+            // Use the substituted text rather than the raw slice so `:NAME`
+            // expansions land in the executed SQL.
+            const sqlText = queryBuf + r.sql;
+            queryBuf = '';
+            working = working.slice(r.consumed);
+            scanState = initialScanState();
+            if (!ctx.cond.isActive())
+                continue;
+            const trimmed = sqlText.trim();
+            if (trimmed.length === 0)
+                continue;
+            if (!ctx.settings.db)
+                continue;
+            if (print) {
+                // `-c` / `-f`: route through the full SendQuery pipeline so SELECT
+                // tuples, NOTICE messages and `\timing` land on the output streams.
+                const stats = await sendQuery(ctx, sqlText);
+                // LATCH: a multi-statement input must report an error if ANY statement
+                // failed, not just the last one — otherwise `-c "SELECT 1; SELECT 1/0;
+                // SELECT 2"` exits 0 and silently passes CI. The
+                // -f/psqlrc callers ignore this aggregate (they only act on
+                // stoppedOnError), so latching is safe across all callers.
+                if (stats.hadError)
+                    hadError = true;
+                if (noteConnectionLost()) {
+                    return { hadError, stoppedOnError, connectionLost };
+                }
+                if (stats.hadError && ctx.settings.onErrorStop) {
+                    stoppedOnError = true;
+                    return { hadError, stoppedOnError, connectionLost };
+                }
+            }
+            else {
+                try {
+                    await ctx.settings.db.execSimple(sqlText);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    ctx.stderr.write(`psql: ERROR:  ${msg}\n`);
+                    hadError = true;
+                    if (noteConnectionLost()) {
+                        return { hadError, stoppedOnError, connectionLost };
+                    }
+                    if (ctx.settings.onErrorStop) {
+                        stoppedOnError = true;
+                        return { hadError, stoppedOnError, connectionLost };
+                    }
+                }
+            }
+            continue;
+        }
+        if (r.kind === 'backslash') {
+            // Use `r.sql` — the scanner's substituted/processed text that
+            // *preceded* the backslash boundary. The raw consumed slice would
+            // also include the backslash command itself and any separators
+            // (like the `\\` end-of-args marker), which we don't want in the
+            // query buffer. `r.sql` excludes both. Mirrors the mainloop's
+            // `queryBuf += result.sql` path.
+            queryBuf += r.sql;
+            working = working.slice(r.consumed);
+            const cmdName = r.cmd;
+            // Skip cond-commands inside rc — they require the full mainloop state
+            // machine to be useful; we treat them as no-ops here. Other commands
+            // run through the standard registry.
+            if (COND_COMMAND_NAMES.has(cmdName))
+                continue;
+            if (!ctx.cond.isActive())
+                continue;
+            const bctx = makeBackslashContext(ctx, cmdName, r.rest, queryBuf);
+            let res;
+            try {
+                res = await dispatchBackslash(ctx.registry, cmdName, bctx);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                ctx.stderr.write(`psql: ERROR:  ${msg}\n`);
+                hadError = true;
+                if (ctx.settings.onErrorStop) {
+                    stoppedOnError = true;
+                    return { hadError, stoppedOnError, connectionLost };
+                }
+                continue;
+            }
+            if (res.status === 'exit')
+                return { hadError, stoppedOnError, connectionLost };
+            if (res.status === 'reset-buf') {
+                queryBuf = res.newBuf ?? '';
+                scanState = initialScanState();
+            }
+            // Mirror upstream `mainloop.c`: a backslash command that errored
+            // drops the query buffer and resets the scanner. Without this the
+            // residue would re-execute via the tail-dispatch at EOF (or get
+            // glued onto the next dispatched statement), masking the failure.
+            if (res.status === 'error') {
+                queryBuf = '';
+                scanState = initialScanState();
+            }
+            if (res.status === 'error')
+                hadError = true; // latch
+            if (noteConnectionLost()) {
+                return { hadError, stoppedOnError, connectionLost };
+            }
+            if (res.status === 'error' && ctx.settings.onErrorStop) {
+                stoppedOnError = true;
+                return { hadError, stoppedOnError, connectionLost };
+            }
+            continue;
+        }
+        // eof / incomplete: stash residue and stop. Use `r.sql` so any `:NAME`
+        // tokens fully consumed in this chunk make it into the buffer in
+        // substituted form. (Same caveat as the mainloop: cross-chunk colon
+        // references fall back to the literal.)
+        queryBuf += r.sql;
+        working = '';
+    }
+    // Tail dispatch: if the file ended mid-statement (no trailing `;`), run
+    // the residue. This matches `process_file` behaviour in upstream.
+    const tail = queryBuf.trim();
+    if (tail.length > 0 && ctx.settings.db && ctx.cond.isActive()) {
+        if (print) {
+            const stats = await sendQuery(ctx, queryBuf);
+            // LATCH, same as the semicolon branch — a trailing statement (no `;`)
+            // that succeeds must not clear an earlier error, or `-c "bad; ok"`
+            // wrongly exits 0. The function's latch invariant applies
+            // to the tail path too.
+            if (stats.hadError)
+                hadError = true;
+            noteConnectionLost();
+        }
+        else {
+            try {
+                await ctx.settings.db.execSimple(queryBuf);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                ctx.stderr.write(`psql: ERROR:  ${msg}\n`);
+                hadError = true;
+                noteConnectionLost();
+            }
+        }
+    }
+    return { hadError, stoppedOnError, connectionLost };
+};
+/**
+ * Discover and execute `.psqlrc` files against `ctx`. Honors the `-X` flag
+ * via `opts.skip = true`. Safe to call before the connection is ready —
+ * commands that need `db` will simply no-op (see `executeInputString`).
+ */
+export const loadPsqlrc = async (ctx, opts = {}) => {
+    if (opts.skip)
+        return;
+    const env = opts.env ?? process.env;
+    // Single-path mode (test ergonomics / explicit override).
+    if (opts.path !== undefined) {
+        const content = await readIfExists(opts.path);
+        if (content === null)
+            return;
+        const prevSource = ctx.settings.curCmdSource;
+        ctx.settings.curCmdSource = 'rcfile';
+        try {
+            await executeInputString(content, ctx);
+        }
+        finally {
+            ctx.settings.curCmdSource = prevSource;
+        }
+        return;
+    }
+    const serverVersion = ctx.settings.db?.serverVersion;
+    const candidates = psqlrcCandidates(env, serverVersion);
+    // Upstream `process_psqlrc()` is first-match-wins PER LOCATION: it reads at
+    // most ONE system file (versioned preferred over unversioned) and then at
+    // most ONE user file. Running both the versioned AND unversioned file in a
+    // location double-executes side effects and lets the unversioned file
+    // clobber the versioned one.
+    let systemDone = false;
+    for (const c of candidates) {
+        const isSystem = c.description.startsWith('system');
+        if (isSystem && systemDone)
+            continue; // first system file already ran
+        const content = await readIfExists(c.path);
+        if (content === null)
+            continue;
+        const prevSource = ctx.settings.curCmdSource;
+        ctx.settings.curCmdSource = 'rcfile';
+        try {
+            await executeInputString(content, ctx);
+        }
+        finally {
+            ctx.settings.curCmdSource = prevSource;
+        }
+        if (isSystem) {
+            systemDone = true; // consumed the system location; move to the user one
+            continue;
+        }
+        // First user / $PSQLRC match wins; nothing further to read.
+        return;
+    }
+};
+// TODO(WP-26-followup): Refactor `core/mainloop.ts` to export an
+// `executeInputString(input, ctx)` primitive, then have this module call it
+// instead of duplicating the scan-and-dispatch loop. The duplication today is
+// roughly 60 LOC; the refactor would shrink this file by half.