@mason-data/cli 0.6.2 → 0.7.0

package/dist/src/cdc/pg-wire.js

@@ -18,10 +18,13 @@ import * as tls from "node:tls";
 export class PgError extends Error {
     code;
     detail;
+    /** the ErrorResponse's own fields, by their one-letter codes (M the message alone, H the hint, P the position) */
+    fields;
     constructor(fields) {
         super(`${fields.S ?? "ERROR"}: ${fields.M ?? "unknown error"}${fields.D ? ` (${fields.D})` : ""}`);
         this.code = fields.C ?? "";
         this.detail = fields.D;
+        this.fields = fields;
     }
 }
 /** Microseconds between the Unix epoch and Postgres's (2000-01-01). */
@@ -72,45 +75,39 @@ export class PgConnection {
     }
     /** TCP connect, the SSL negotiation and the startup exchange; `hold` is told the live socket, for a timeout to destroy. */
     async handshake(hold) {
-        const o = this.opts;
-        const mode = o.sslmode ?? "prefer";
-        const raw = await new Promise((resolve, reject) => {
-            const s = net.connect({ host: o.host, port: o.port });
-            hold(s);
-            s.once("connect", () => resolve(s));
-            s.once("error", (e) => reject(new Error(`connecting to ${o.host}:${o.port}: ${socketErrorText(e)}`)));
-        });
-        let sock = raw;
-        if (mode !== "disable" && mode !== "allow") {
-            // SSLRequest: length 8, code 80877103; the server answers one byte, S or N
-            raw.write(Buffer.from([0, 0, 0, 8, 0x04, 0xd2, 0x16, 0x2f]));
-            const answer = await new Promise((resolve, reject) => {
-                raw.once("data", (d) => resolve(String.fromCharCode(d[0])));
-                raw.once("error", reject);
-            });
-            if (answer === "S") {
-                const verify = mode === "verify-ca" || mode === "verify-full";
-                sock = await new Promise((resolve, reject) => {
-                    const t = tls.connect({
-                        socket: raw, rejectUnauthorized: verify,
-                        ...(mode === "verify-full" ? { servername: o.host } : { checkServerIdentity: () => undefined }),
-                    });
-                    hold(t);
-                    t.once("secureConnect", () => resolve(t));
-                    t.once("error", reject);
-                });
-            }
-            else if (mode !== "prefer") {
-                raw.destroy();
-                throw new Error(`sslmode=${mode}, but ${o.host} does not accept TLS`);
-            }
-        }
+        const sock = await transport(this.opts, hold);
         this.socket = sock;
         sock.on("data", (d) => this.onData(d));
         sock.on("error", (e) => this.fail(e));
         sock.on("close", () => this.fail(new Error("connection closed by the server")));
         await this.startup();
     }
+    /** the server's key for this session (BackendKeyData), for a CancelRequest */
+    key = null;
+    /**
+     * ASK THE SERVER TO CANCEL THIS SESSION'S RUNNING STATEMENT (Postgres's CancelRequest, on a connection of its own,
+     * TLS as this one's sslmode): the statement ends with 57014 on this connection, which stays usable. Resolves once
+     * the request is written.
+     */
+    async cancel() {
+        const key = this.key;
+        if (key === null)
+            throw new Error("the server sent no key for this session: it cannot be cancelled");
+        let held = null;
+        const timer = setTimeout(() => { held?.destroy(); }, this.opts.connectTimeoutMs ?? 15_000);
+        try {
+            const s = await transport(this.opts, (x) => { held = x; });
+            const b = Buffer.alloc(16);
+            b.writeInt32BE(16, 0);
+            b.writeInt32BE(80877102, 4);
+            b.writeInt32BE(key.pid, 8);
+            b.writeInt32BE(key.secret, 12);
+            await new Promise((resolve, reject) => { s.once("error", reject); s.end(b, () => resolve()); });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     fail(e) {
         if (this.closedWith)
             return;
@@ -167,6 +164,16 @@ export class PgConnection {
         if (k !== undefined)
             this.parameters[k] = v ?? "";
     }
+    /** the next message of a statement's reply; when the server closed the connection after an ErrorResponse it sent
+     *  (a FATAL: a user removed, a shutdown) and before ReadyForQuery, that error — never the bare "connection closed" */
+    async reply(error) {
+        try {
+            return await this.next();
+        }
+        catch (e) {
+            throw error ?? e;
+        }
+    }
     next() {
         const m = this.queue.shift();
         if (m) {
@@ -195,7 +202,7 @@ export class PgConnection {
         const params = [
             ["user", o.user], ["database", o.database], ["client_encoding", "UTF8"],
             // Text values in the forms the reader parses: ISO dates in UTC, floats round-trippable
-            ["DateStyle", "ISO, YMD"], ["TimeZone", "UTC"], ["extra_float_digits", "3"], ["IntervalStyle", "iso_8601"],
+            ...(o.textForms ?? [["DateStyle", "ISO, YMD"], ["TimeZone", "UTC"], ["extra_float_digits", "3"], ["IntervalStyle", "iso_8601"]]).map(([k, v]) => [k, v]),
             ["application_name", o.applicationName ?? "mason"],
         ];
         if (o.replication)
@@ -216,8 +223,10 @@ export class PgConnection {
                 await this.auth(m.body);
                 continue;
             }
-            if (m.type === "K")
-                continue; // BackendKeyData
+            if (m.type === "K") {
+                this.key = { pid: m.body.readInt32BE(0), secret: m.body.readInt32BE(4) };
+                continue;
+            } // BackendKeyData
             if (m.type === "Z")
                 return;
             throw new Error(`unexpected message ${m.type} during startup`);
@@ -288,7 +297,7 @@ export class PgConnection {
         let result = { fields: [], rows: [], command: "" };
         let error = null;
         for (;;) {
-            const m = await this.next();
+            const m = await this.reply(error);
             switch (m.type) {
                 case "T":
                     result = { fields: rowDescription(m.body), rows: [], command: "" };
@@ -321,7 +330,7 @@ export class PgConnection {
         this.send("Q", cstr(sql));
         let error = null;
         for (;;) {
-            const m = await this.next();
+            const m = await this.reply(error);
             switch (m.type) {
                 case "D":
                     if (error === null)
@@ -338,6 +347,52 @@ export class PgConnection {
             }
         }
     }
+    /**
+     * ONE STATEMENT THROUGH THE EXTENDED PROTOCOL (`mason mcp`'s query): Parse, Bind, Describe and Execute of the unnamed
+     * portal, then Sync — so the server takes exactly one statement (a second is Postgres's 42601), and `maxRows` is the
+     * Execute's row count: the server stops at it and says so (PortalSuspended), so a query an agent leaves unbounded is
+     * never sent whole. 0 is every row. Every value is text.
+     */
+    async extended(sql, maxRows) {
+        const int16 = (n) => { const b = Buffer.alloc(2); b.writeInt16BE(n); return b; };
+        this.send("P", Buffer.concat([cstr(""), cstr(sql), int16(0)]));
+        // no parameters, every result column in text
+        this.send("B", Buffer.concat([cstr(""), cstr(""), int16(0), int16(0), int16(0)]));
+        this.send("D", Buffer.concat([Buffer.from("P"), cstr("")]));
+        this.send("E", Buffer.concat([cstr(""), int32(maxRows)]));
+        this.send("S", Buffer.alloc(0));
+        const result = { fields: [], rows: [], suspended: false, command: "", empty: false };
+        let error = null;
+        for (;;) {
+            const m = await this.reply(error);
+            switch (m.type) {
+                case "T":
+                    result.fields = rowFields(m.body);
+                    break;
+                case "D":
+                    if (error === null)
+                        result.rows.push(dataRow(m.body));
+                    break;
+                case "s":
+                    result.suspended = true;
+                    break;
+                case "C":
+                    result.command = cstrings(m.body)[0] ?? "";
+                    break;
+                case "E":
+                    error = new PgError(errorFields(m.body));
+                    break;
+                case "I":
+                    result.empty = true;
+                    break;
+                case "Z":
+                    if (error)
+                        throw error;
+                    return result;
+                default: break; // ParseComplete, BindComplete, NoData
+            }
+        }
+    }
     // ------------------------------------------------------------------ replication
     /** START_REPLICATION, then an async stream of XLogData and keepalives until the connection ends. */
     async *replicate(command) {
@@ -392,6 +447,42 @@ export class PgConnection {
     }
 }
 // ------------------------------------------------------------------ helpers
+/** TCP connect and the SSL negotiation (libpq's sslmode): the socket a startup, or a CancelRequest, is written to. */
+async function transport(o, hold) {
+    const mode = o.sslmode ?? "prefer";
+    const raw = await new Promise((resolve, reject) => {
+        const s = net.connect({ host: o.host, port: o.port });
+        hold(s);
+        s.once("connect", () => resolve(s));
+        s.once("error", (e) => reject(new Error(`connecting to ${o.host}:${o.port}: ${socketErrorText(e)}`)));
+    });
+    let sock = raw;
+    if (mode !== "disable" && mode !== "allow") {
+        // SSLRequest: length 8, code 80877103; the server answers one byte, S or N
+        raw.write(Buffer.from([0, 0, 0, 8, 0x04, 0xd2, 0x16, 0x2f]));
+        const answer = await new Promise((resolve, reject) => {
+            raw.once("data", (d) => resolve(String.fromCharCode(d[0])));
+            raw.once("error", reject);
+        });
+        if (answer === "S") {
+            const verify = mode === "verify-ca" || mode === "verify-full";
+            sock = await new Promise((resolve, reject) => {
+                const t = tls.connect({
+                    socket: raw, rejectUnauthorized: verify,
+                    ...(mode === "verify-full" ? { servername: o.host } : { checkServerIdentity: () => undefined }),
+                });
+                hold(t);
+                t.once("secureConnect", () => resolve(t));
+                t.once("error", reject);
+            });
+        }
+        else if (mode !== "prefer") {
+            raw.destroy();
+            throw new Error(`sslmode=${mode}, but ${o.host} does not accept TLS`);
+        }
+    }
+    return sock;
+}
 /** `16/B374D848` -> its 64-bit position; throws on anything else. */
 export function parseLsn(text) {
     const m = /^([0-9A-Fa-f]{1,8})\/([0-9A-Fa-f]{1,8})$/.exec(text.trim());
@@ -452,6 +543,21 @@ function rowDescription(b) {
     }
     return names;
 }
+/** A RowDescription's columns with their types (rowDescription keeps the names alone). */
+function rowFields(b) {
+    const n = b.readInt16BE(0);
+    const out = [];
+    let i = 2;
+    for (let k = 0; k < n; k++) {
+        const end = b.indexOf(0, i);
+        const name = b.toString("utf8", i, end);
+        i = end + 1;
+        // table oid (4), column number (2), type oid (4), type size (2), type modifier (4), format (2)
+        out.push({ name, typeOid: b.readUInt32BE(i + 6), typmod: b.readInt32BE(i + 12) });
+        i += 18;
+    }
+    return out;
+}
 /** onData pauses the socket above this many queued bytes, and next() resumes it below a quarter of it. */
 const QUEUE_PAUSE_BYTES = 16 * 1024 * 1024;
 function dataRow(b) {

package/dist/src/cli/background.js

@@ -19,8 +19,9 @@ import { fileURLToPath } from "node:url";
 import { runnable } from "../lib/runnable.js";
 import { READY, STEP_MARK } from "./dev.js";
 import { liveRun } from "./runs.js";
-import { theProject } from "./project.js";
+import { projectSource, theProject } from "./project.js";
 import { runListenerSettings } from "./pg-tls.js";
+import { demoChangesRefusal, demoPort } from "./demo.js";
 import { endText, failed, jsonText, nextBlock } from "./command.js";
 import { DEV } from "./registry.js";
 import { out as styleOut, stepRenderer } from "./style.js";
@@ -38,6 +39,18 @@ export const NEXT_STEPS = [
     ["mason logs", "its log: every copy, poll and statement"],
     ["mason stop", "stop Mason; the next mason start resumes where it stopped"],
 ];
+/** The ports a demo project's database takes (its URL's port, read as the run reads it), for the API's choice to avoid;
+ *  none for any other project. A sources file or a URL that cannot be read gives none HERE: the run refuses it in its
+ *  own words (its source step, its demo step), shown by this start as every other refusal of the run's is. */
+function demoPortsOf(project) {
+    if (project.config.demo !== true)
+        return new Set();
+    const src = projectSource(project, process.env);
+    if ("message" in src)
+        return new Set();
+    const at = demoPort(src.resolved, src.from);
+    return new Set("port" in at ? [at.port] : []);
+}
 /** `args` are `mason start`'s own, passed on to the run with --attach. */
 export async function devInBackground(args, o) {
     const t = theProject(process.cwd());
@@ -55,9 +68,14 @@ export async function devInBackground(args, o) {
         say(nextBlock([["mason status", "what it is doing"], ["mason stop", "stop it"]]));
         return 0;
     }
+    // a demo project with --replication (src/cli/demo.ts): refused here too, where it is read, before a run is spawned
+    const demoRefused = demoChangesRefusal(t.project.config, o.changes ?? null);
+    if (demoRefused)
+        return failed("start", demoRefused, { json: o.json });
     // a MASON_PG_PORT that is no port, or is held, is refused HERE, where the person (or --json) reads it, before a run is
-    // spawned; the run checks again for itself (choosePgPort, src/cli/ports.ts), since a port may be taken in between
-    const pg = await choosePgPort(process.env.MASON_PG_PORT, new Set(), t.project.config.pgPort ?? null);
+    // spawned; the run checks again for itself (choosePgPort, src/cli/ports.ts), since a port may be taken in between.
+    // A demo project's database port (its URL's, src/cli/demo.ts demoPort) is avoided as the run avoids it
+    const pg = await choosePgPort(process.env.MASON_PG_PORT, demoPortsOf(t.project), t.project.config.pgPort ?? null);
     if ("problem" in pg)
         return failed("start", pg, { json: o.json });
     // and so is a listener off loopback without TLS, by the run's own check (src/cli/pg-tls.ts): read, never written
@@ -140,8 +158,8 @@ export async function devInBackground(args, o) {
                         steps.fail(l.slice(STEP_MARK.fail.length));
                         continue;
                     }
-                    // the run's line (src/cli/dev.ts: "Postgres  <url>")
-                    const pgLine = /^\s+Postgres\s+(postgresql:\S+)/.exec(l);
+                    // the run's line (src/cli/dev.ts: "Postgres  <url>", the URL in its shown form, `withPlaceholders`: postgres://<user>:<password>@…)
+                    const pgLine = /^\s+Postgres\s+(postgres:\/\/<user>:<password>@\S+)/.exec(l);
                     if (pgLine) {
                         postgres = postgresLink(withoutPlaceholders(pgLine[1]));
                         steps.print(`  ${st.dim("Postgres API")}  ${pgLine[1]}  ${st.dim("(mason user add <name> makes a user)")}`);
@@ -151,6 +169,12 @@ export async function devInBackground(args, o) {
                         steps.print(`  ${st.dim("Web UI".padEnd("Postgres API".length))}  ${st.cyan("mason ui")}  ${st.dim("(the status page and the users, in your browser)")}`);
                         continue;
                     }
+                    // a demo project's line (src/cli/dev.ts: "Demo  a new order lands every <n> s: …"), in the same column
+                    const demoLine = /^\s+Demo\s{2}(.+)$/.exec(l);
+                    if (demoLine) {
+                        steps.print(`  ${st.dim("Demo".padEnd("Postgres API".length))}  ${demoLine[1]}`);
+                        continue;
+                    }
                     if (l.trim())
                         since.push(l.trim().replace(/^mason start: /, ""));
                     steps.print(l);

package/dist/src/cli/command.js

@@ -24,7 +24,7 @@ export function parseCommand(spec, argv) {
         parsed = parseArgs({ args: argv, options: { ...spec.options, ...HELP }, allowPositionals: true });
     }
     catch (e) {
-        return failed(spec.name, { message: e.message, code: "usage", usage: spec.usage, next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv) });
+        return failed(spec.name, { message: e.message, code: "usage", usage: spec.usage, next: [[`mason ${spec.name} --help`, "its usage, with every option"]] }, { json: wantsJson(argv, spec) });
     }
     if (parsed.values.help) {
         process.stdout.write(spec.usage);
@@ -76,8 +76,9 @@ export function nextJson(steps = []) {
     return steps.map(([command, what]) => what ? { command, what } : { command });
 }
 /** Whether a command line asked for data: `--json` anywhere on it (read before the line is parsed, so a wrong line
- *  is answered in JSON too). */
-export const wantsJson = (argv) => argv.includes("--json");
+ *  is answered in JSON too) — never for a command whose stdout is a protocol's (`CommandSpec.stdout`), whose every
+ *  failure is said on stderr. */
+export const wantsJson = (argv, spec) => spec?.stdout !== "protocol" && argv.includes("--json");
 /**
  * A COMMAND'S --json ANSWER (an agent wants clear, unambiguous context and a machine-readable format, and a person
  * and an agent both want the next steps): one JSON object on stdout, always with `next` — the same steps the human