neonctl 2.22.2 → 2.23.0

package/psql/io/history.js

@@ -0,0 +1,299 @@
+/**
+ * psql history file I/O.
+ *
+ * TypeScript port of the history-handling portion of PostgreSQL's
+ * `src/bin/psql/input.c`. Implements the read/append/truncate operations the
+ * REPL drives plus the small env-resolution helpers (`PSQL_HISTORY`,
+ * `HISTSIZE`).
+ *
+ * On-disk format follows GNU readline's history file:
+ *
+ *   - One entry per line, UTF-8.
+ *   - Multi-line entries are encoded with the literal escape sequences
+ *     `\n` (backslash + n), `\r`, and `\\`. We decode them back to real
+ *     newlines / carriage returns / backslashes on load and re-encode on
+ *     write. Upstream psql uses an in-memory NL_IN_HISTORY (0x01) marker
+ *     that libreadline then translates to the same on-disk form; we skip
+ *     the intermediate marker and operate on real strings throughout.
+ *   - Lines whose first character is `#` are treated as timestamp / comment
+ *     markers (libreadline writes them when `history_write_timestamps` is
+ *     set) and silently skipped on load. psql itself never writes them.
+ *
+ * Intentional deviations from upstream:
+ *
+ *   - Append-only writes use `fs.promises.appendFile`, which opens the file
+ *     with `O_APPEND` on POSIX so concurrent appends from multiple psql
+ *     instances do not interleave within a single write call. On Windows
+ *     there is a small race window we accept; the alternative (an external
+ *     lock file) is not worth the dependency churn.
+ *   - `truncateHistory` writes the trimmed history to a sibling temp file
+ *     and `rename`s it into place. POSIX `rename(2)` is atomic w.r.t. other
+ *     processes observing the path; Windows is best-effort.
+ *   - HISTCONTROL comparisons run on the raw (decoded) entry — this matches
+ *     bash/readline behaviour where the user's literal input is what gets
+ *     deduped, not the escaped on-disk form.
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** psql's compiled-in default for HISTSIZE (see `src/bin/psql/settings.h`). */
+const DEFAULT_HISTSIZE = 500;
+/**
+ * In-memory command-line history for the current session, oldest first.
+ *
+ * Upstream psql delegates history to GNU readline, whose `history_list()`
+ * backs the `\s` meta-command (`exec_command_s` in `command.c` prints the
+ * live in-memory history, NOT the on-disk file). We keep our own
+ * process-local mirror here, populated by {@link recordHistory} from the
+ * same funnel the REPL uses to persist a submitted line ({@link
+ * appendHistory}). `\s` reads it via {@link getHistory}.
+ *
+ * Module-level state matches the single-session lifetime of a psql process;
+ * tests reset it with {@link clearHistory}.
+ */
+let inMemoryHistory = [];
+/**
+ * Record one submitted line in the session's in-memory history.
+ *
+ * Empty lines and an exact duplicate of the immediately preceding entry are
+ * dropped, mirroring readline's default behaviour (and {@link
+ * LineEditor.pushHistory}); HISTCONTROL filtering is applied by the caller
+ * ({@link appendHistory}) before this is reached.
+ */
+export const recordHistory = (entry) => {
+    if (entry.length === 0)
+        return;
+    if (inMemoryHistory[inMemoryHistory.length - 1] === entry)
+        return;
+    inMemoryHistory.push(entry);
+};
+/**
+ * Return the session's in-memory history (oldest first). Returns a copy so
+ * callers can't mutate the backing store.
+ */
+export const getHistory = () => inMemoryHistory.slice();
+/** Reset the in-memory history. Primarily for tests and `\s`-less restarts. */
+export const clearHistory = () => {
+    inMemoryHistory = [];
+};
+/** Encode a single in-memory entry to the on-disk libreadline form. */
+const encodeEntry = (entry) => entry.replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+/**
+ * Decode a single on-disk libreadline line back to its in-memory form.
+ *
+ * Recognised escapes: `\\` → `\`, `\n` → newline, `\r` → CR. Any other
+ * `\<x>` sequence is left as-is (matching readline's lenient decoder), so
+ * a stray backslash at the end of the file does not eat the next entry.
+ */
+const decodeEntry = (line) => {
+    let out = '';
+    for (let i = 0; i < line.length; i++) {
+        const c = line.charCodeAt(i);
+        if (c === 0x5c /* '\\' */ && i + 1 < line.length) {
+            const next = line[i + 1];
+            if (next === 'n') {
+                out += '\n';
+                i++;
+                continue;
+            }
+            if (next === 'r') {
+                out += '\r';
+                i++;
+                continue;
+            }
+            if (next === '\\') {
+                out += '\\';
+                i++;
+                continue;
+            }
+        }
+        out += line[i];
+    }
+    return out;
+};
+/**
+ * Return `true` if `entry` should be filtered out under `histcontrol`
+ * relative to the most recent entry already in history (`prev`).
+ *
+ * Mirrors `pg_send_history()`'s filter in `input.c`.
+ */
+const shouldIgnore = (entry, prev, histcontrol) => {
+    const ignoreSpace = histcontrol === 'ignorespace' || histcontrol === 'ignoreboth';
+    const ignoreDups = histcontrol === 'ignoredups' || histcontrol === 'ignoreboth';
+    if (ignoreSpace && entry.length > 0 && /^\s/.test(entry))
+        return true;
+    if (ignoreDups && prev !== undefined && prev === entry)
+        return true;
+    return false;
+};
+/**
+ * Read a libreadline history file and return entries in chronological
+ * order (oldest first). A missing file resolves to `[]` so callers can
+ * unconditionally `loadHistory` at startup.
+ *
+ * Lines beginning with `#` are silently skipped (libreadline timestamp
+ * markers; psql itself never writes them but we tolerate them).
+ *
+ * Other I/O errors (EACCES, EISDIR, …) propagate to the caller.
+ */
+export const loadHistory = async (filePath) => {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err &&
+            typeof err === 'object' &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+    // Strip a single trailing newline so a well-formed file ending in `\n`
+    // doesn't produce a phantom empty entry. Don't strip more than one — a
+    // blank line in the middle of the file represents an entry that was
+    // literally the empty string (rare but possible), and we round-trip it.
+    if (raw.endsWith('\n'))
+        raw = raw.slice(0, -1);
+    if (raw.length === 0)
+        return [];
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        if (line.startsWith('#'))
+            continue;
+        entries.push(decodeEntry(line));
+    }
+    return entries;
+};
+/**
+ * Append a single entry to the history file, subject to HISTCONTROL.
+ *
+ * Implementation notes:
+ *
+ *   - On POSIX, `fs.appendFile` opens with `O_APPEND`, which guarantees
+ *     each `write(2)` lands at the current end-of-file. A single
+ *     encoded entry plus its trailing `\n` is one write, so concurrent
+ *     psql instances writing to the same history file never interleave
+ *     within an entry. We accept a small race on Windows.
+ *   - `ignoredups` consults the *last* entry currently on disk. We read
+ *     the tail of the file rather than the whole history to keep this
+ *     O(1)-ish for large histories; for simplicity we read everything
+ *     when ignoredups is in effect — typical history files are well
+ *     under 1 MiB.
+ */
+export const appendHistory = async (filePath, entry, histcontrol = 'none') => {
+    if (histcontrol === 'ignoredups' ||
+        histcontrol === 'ignoreboth' ||
+        histcontrol === 'ignorespace') {
+        let prev;
+        if (histcontrol === 'ignoredups' || histcontrol === 'ignoreboth') {
+            const existing = await loadHistory(filePath);
+            prev = existing[existing.length - 1];
+        }
+        if (shouldIgnore(entry, prev, histcontrol))
+            return;
+    }
+    // Mirror the line into the session's in-memory history (what `\s` prints)
+    // using the same funnel that persists it to disk, so the two stay in
+    // lock-step under HISTCONTROL. Recording happens AFTER the ignore check
+    // so an ignored line is absent from both.
+    recordHistory(entry);
+    await fs.appendFile(filePath, encodeEntry(entry) + '\n', 'utf8');
+};
+/**
+ * Trim the history file to its last `maxLines` entries.
+ *
+ * If `maxLines <= 0` the file is removed entirely (matching psql's
+ * behaviour when HISTSIZE is set to 0). If the file already fits the
+ * cap, it's left untouched. Otherwise we write the kept tail to a
+ * sibling temp file and `rename` it into place.
+ *
+ * `rename(2)` on POSIX is atomic w.r.t. observers of the destination
+ * path; on Windows the platform call may briefly fail if another
+ * process has the destination open, in which case the error propagates.
+ */
+export const truncateHistory = async (filePath, maxLines) => {
+    if (maxLines <= 0) {
+        try {
+            await fs.unlink(filePath);
+        }
+        catch (err) {
+            if (err &&
+                typeof err === 'object' &&
+                'code' in err &&
+                err.code === 'ENOENT') {
+                return;
+            }
+            throw err;
+        }
+        return;
+    }
+    const entries = await loadHistory(filePath);
+    if (entries.length <= maxLines)
+        return;
+    const kept = entries.slice(entries.length - maxLines);
+    const body = kept.map(encodeEntry).join('\n') + '\n';
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath);
+    const tmpPath = path.join(dir, `.${base}.${randomUUID()}.tmp`);
+    await fs.writeFile(tmpPath, body, { encoding: 'utf8', mode: 0o600 });
+    try {
+        await fs.rename(tmpPath, filePath);
+    }
+    catch (err) {
+        // Best-effort cleanup; the temp file is harmless but noisy.
+        try {
+            await fs.unlink(tmpPath);
+        }
+        catch {
+            /* ignore */
+        }
+        throw err;
+    }
+};
+/**
+ * Resolve the on-disk history file path psql would use, in order of
+ * precedence:
+ *
+ *   1. `$PSQL_HISTORY` if set and non-empty.
+ *   2. On Windows: `%APPDATA%\postgresql\psql_history`.
+ *   3. Otherwise: `$HOME/.psql_history` (falling back to `os.homedir()`
+ *      if `$HOME` is unset, e.g. in some sandboxes).
+ *
+ * Pure function — `env` defaults to `process.env` but can be injected
+ * for tests.
+ */
+export const defaultHistoryPath = (env = process.env) => {
+    const explicit = env.PSQL_HISTORY;
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    if (process.platform === 'win32') {
+        const appdata = env.APPDATA;
+        if (appdata !== undefined && appdata.length > 0) {
+            return path.join(appdata, 'postgresql', 'psql_history');
+        }
+        // Fall through to homedir() if APPDATA isn't set; matches psql's
+        // graceful degradation on a minimally-configured Windows session.
+    }
+    const home = env.HOME ?? os.homedir();
+    return path.join(home, '.psql_history');
+};
+/**
+ * Resolve the effective HISTSIZE: the `HISTSIZE` env var (if a
+ * non-negative integer) or psql's compiled-in default of 500.
+ *
+ * Values that fail to parse as a non-negative integer fall back to the
+ * default — psql itself ignores malformed HISTSIZE and warns, but at
+ * this layer we don't have a logger.
+ */
+export const resolveHistSize = (env = process.env) => {
+    const raw = env.HISTSIZE;
+    if (raw === undefined || raw === '')
+        return DEFAULT_HISTSIZE;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0)
+        return DEFAULT_HISTSIZE;
+    return n;
+};

package/psql/io/input.js

@@ -0,0 +1,120 @@
+/**
+ * Interactive line input for the psql REPL — the shared "read one line from
+ * the user" primitive used by `\prompt` and `\password`.
+ *
+ * Models upstream psql's password / prompt reading:
+ *   - `simple_prompt` (`src/port/sprompt.c`) reads a line with optional echo
+ *     suppression. On a TTY it disables terminal echo for the duration of the
+ *     read (we emulate this with Node's raw mode + manual character handling);
+ *     when stdin is NOT a TTY it falls back to a plain line read and the
+ *     `echo` flag is a no-op — the line is still consumed. We match that: a
+ *     non-interactive caller piping a password in still has it read.
+ *   - `\prompt` (`exec_command_prompt`) reads with echo on; `\prompt -`
+ *     (no-echo password form) and `\password` read with echo suppressed.
+ *
+ * The terminal handling is parameterised over the input/output streams so the
+ * non-TTY path (the only one testable without a real PTY) can be exercised in
+ * unit tests; production callers use {@link readLine} with the process
+ * defaults.
+ */
+import { createInterface } from 'node:readline';
+/** True when `stream` is a TTY whose echo we can suppress via raw mode. */
+const isRawCapableTty = (stream) => {
+    const s = stream;
+    return Boolean(s.isTTY) && typeof s.setRawMode === 'function';
+};
+/**
+ * Read one line of input, optionally suppressing echo.
+ *
+ *   - `echo: false` on a TTY → put the terminal in raw mode, echo nothing,
+ *     accumulate characters until Enter, then restore cooked mode. Used for
+ *     password entry (`\password`, `\prompt -`).
+ *   - `echo: true`, or any non-TTY input → a plain line read. On a non-TTY the
+ *     `echo` flag is a no-op: we still consume and return the line, matching
+ *     upstream `simple_prompt`'s behaviour with redirected stdin.
+ *
+ * The returned string excludes the trailing newline. EOF before any newline
+ * resolves to whatever was typed so far (empty string if nothing).
+ */
+export const readLine = (prompt, opts) => {
+    const input = opts.input ?? process.stdin;
+    const output = opts.output ?? process.stderr;
+    if (!opts.echo && isRawCapableTty(input)) {
+        return readNoEchoTty(prompt, input, output);
+    }
+    return readEchoLine(prompt, input, output);
+};
+/** Plain, echoing (or non-TTY) line read via `node:readline`. */
+const readEchoLine = (prompt, input, output) => {
+    const rl = createInterface({ input, output, terminal: false });
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (line) => {
+            if (settled)
+                return;
+            settled = true;
+            rl.close();
+            resolve(line);
+        };
+        if (prompt.length > 0)
+            output.write(prompt);
+        // Resolve on the first complete line. Closing without one (EOF) yields ''.
+        // We don't rely on `line` firing before `close`: whichever lands first
+        // wins, and a buffered final line is delivered as a `line` event.
+        rl.on('line', (l) => {
+            settle(l);
+        });
+        rl.on('close', () => {
+            settle('');
+        });
+    });
+};
+/**
+ * No-echo read on a raw-capable TTY. Mirrors upstream `simple_prompt`'s
+ * echo-off branch: switch to raw mode, gather bytes, never echo them, and
+ * restore on Enter / EOF / interrupt. Backspace edits the buffer; Ctrl-C and
+ * Ctrl-D abort with whatever has been typed (empty on a clean Ctrl-C).
+ */
+const readNoEchoTty = (prompt, input, output) => {
+    return new Promise((resolve) => {
+        if (prompt.length > 0)
+            output.write(prompt);
+        input.setRawMode(true);
+        input.resume();
+        input.setEncoding('utf8');
+        let buf = '';
+        const finish = (result) => {
+            input.setRawMode(false);
+            input.pause();
+            input.removeListener('data', onData);
+            // Terminate the (un-echoed) line the user couldn't see themselves type.
+            output.write('\n');
+            resolve(result);
+        };
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\n' || ch === '\r') {
+                    finish(buf);
+                    return;
+                }
+                if (ch === '') {
+                    // Ctrl-C: cancel, return nothing.
+                    finish('');
+                    return;
+                }
+                if (ch === '') {
+                    // Ctrl-D (EOF): return what we have.
+                    finish(buf);
+                    return;
+                }
+                if (ch === '' || ch === '\b') {
+                    // DEL / Backspace: drop the last character.
+                    buf = buf.slice(0, -1);
+                    continue;
+                }
+                buf += ch;
+            }
+        };
+        input.on('data', onData);
+    });
+};