@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/metrics.js

@@ -0,0 +1,79 @@
+/** The content type of the text exposition format, version 0.0.4. */
+export const METRICS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/**
+ * HOW MANY SAMPLES OLD A NUMBER READ FROM THE DATABASE (the stream's position, the slot) or THE SAMPLER (p50 / p95) may
+ * be and still be said: the sampler refreshes each once a minute (src/duck/usage.ts SAMPLE_SECONDS), and a scrape never
+ * reads them itself (src/cli/run-server.ts `metricsFacts`), so one older than two samples means the sampler could not
+ * take them — said as unknown (absent), never as a stale number that looks current.
+ */
+export const FRESH_SAMPLES = 2;
+/** a label value escaped as the format says: backslash, double quote and line feed */
+const labelValue = (v) => v.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n");
+/** a sample's value: an integer as written, a fraction as JavaScript prints it (Go's ParseFloat reads both) */
+const valueText = (n) => (Number.isInteger(n) ? n.toFixed(0) : String(n));
+/** a sample that must be a count: a whole number, at least 0 */
+const isCount = (s, kind) => kind === "counter" || s.suffix === "_count";
+/** One metric's lines, its HELP and TYPE first — or none, the WHOLE family absent, when a sample it needs is unknown
+ *  or any value is not finite (or a count not a whole number). */
+function metric(name, kind, help, samples) {
+    const whole = samples.every((s) => s.value === null ? s.optional === true
+        : Number.isFinite(s.value) && (!isCount(s, kind) || (Number.isInteger(s.value) && s.value >= 0)));
+    const kept = samples.filter((s) => s.value !== null);
+    if (!whole || kept.length === 0)
+        return [];
+    const lines = [`# HELP ${name} ${help.replaceAll("\\", "\\\\").replaceAll("\n", "\\n")}`, `# TYPE ${name} ${kind}`];
+    for (const s of kept) {
+        const labels = s.labels ? Object.entries(s.labels).map(([k, v]) => `${k}="${labelValue(v ?? "")}"`).join(",") : "";
+        lines.push(`${name}${s.suffix ?? ""}${labels ? `{${labels}}` : ""} ${valueText(s.value)}`);
+    }
+    return lines;
+}
+/** The PHASES `mason_tables` says, in order: the sync's (src/duck/sync.ts `CopyState.phase`), as `/healthz` counts them. */
+export const TABLE_PHASES = ["copied", "copying", "waiting", "failed"];
+/** The OUTCOMES `mason_statements_total` says: the request log's (`outcomeOf`), `ok` said as `completed`. */
+export const STATEMENT_OUTCOMES = ["completed", "failed", "refused", "cancelled"];
+/**
+ * THE BODY OF `GET /metrics`. Starting or stopping: `mason_ready 0` and `mason_info` alone (a scrape must not fail
+ * while Mason starts; whether it is up is `/healthz`'s to say). Serving: `mason_ready 1` and the run's numbers.
+ */
+export function metricsText(f) {
+    const lines = [
+        ...metric("mason_ready", "gauge", "1 once Mason serves the synced data; 0 while it starts or stops (/healthz answers 503 then).", [{ value: f.run === null ? 0 : 1 }]),
+        ...metric("mason_info", "gauge", "Mason's version, as a label; the value is always 1.", [{ labels: { version: f.version }, value: 1 }]),
+    ];
+    const r = f.run;
+    if (r !== null) {
+        const u = r.usage, st = r.statements;
+        // a number read from the database (the stream's position, the slot) as of `readAt`: said only while fresh
+        const fresh = (value, readAt) => readAt !== null && isFresh(r, readAt) ? value : null;
+        lines.push(...metric("mason_uptime_seconds", "gauge", "Seconds since mason serve started.", [{ value: r.uptimeSeconds }]), ...metric("mason_tables", "gauge", "The synced tables the run holds, by phase (a removed table's data is held until dropped).", TABLE_PHASES.map((phase) => ({ labels: { phase }, value: u.tables[phase] }))), ...metric("mason_copy_bytes", "gauge", "The size of the synced data's file on disk, bytes.", [{ value: u.copyBytes }]), ...metric("mason_copy_rows", "gauge", "The rows of the synced tables served.", [{ value: u.totals.rows }]), 
+        // absent, not NaN, before any added table was synced: nothing has an age yet (see the module's comment)
+        ...metric("mason_sync_oldest_age_seconds", "gauge", "Seconds since the stalest added table was last brought current; absent before any sync.", [{ value: u.oldestSyncSeconds }]), 
+        // absent where no table is replicated (the run polls): a 0 would claim a stream that is not there. The database's
+        // position under the bytes, and the slot, are as the sampler last read them (a scrape never asks the database):
+        // absent when that is more than FRESH_SAMPLES samples old. The seconds are the run's own clock against the last
+        // batch's commit time, read from nothing: current at every scrape
+        ...metric("mason_stream_lag_bytes", "gauge", "Replication: WAL bytes between the database's position (as last sampled, at most two samples old) and what Mason has applied; absent when nothing is replicated or not known.", [{ value: fresh(u.streamLag?.bytes ?? null, u.streamLagReadAt) }]), ...metric("mason_stream_lag_seconds", "gauge", "Replication: seconds since the newest change applied was committed on the database; absent when nothing is replicated.", [{ value: u.streamLag?.seconds ?? null }]), ...metric("mason_slot_wal_held_bytes", "gauge", "Replication: WAL bytes the replication slot holds on the database (as last sampled, at most two samples old); absent when nothing is replicated or not known.", [{ value: fresh(u.slotWalHeldBytes, u.slotWalReadAt) }]), ...metric("mason_disk_free_bytes", "gauge", "Bytes free on the disk the synced data is on.", [{ value: u.diskFreeBytes }]), ...metric("mason_sessions_open", "gauge", "Sessions logged in to Mason's Postgres API now.", [{ value: u.sessionsOpen }]), ...metric("mason_statements_total", "counter", "Statements the listener answered since the process started, whether or not the request log kept each, by outcome (refused: the statement's fault; failed: Mason's or the machine's).", STATEMENT_OUTCOMES.map((outcome) => ({ labels: { outcome }, value: outcome === "completed" ? st.completed : st[outcome] }))), ...durationSummary(r));
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** a time `readAt` (ISO) at most `freshSeconds` before the facts were read */
+const isFresh = (r, readAt) => (r.at - Date.parse(readAt)) / 1000 <= r.freshSeconds;
+/**
+ * `mason_statement_duration_seconds`, a summary: the quantiles are the last usage sample's (its minute's completed
+ * statements, as `mason usage` says them: src/duck/usage.ts `lastDurations`; past DURATIONS_KEPT in a minute, of a
+ * uniform sample of them), absent before the first sample, for a minute none completed, and when the last sample is
+ * more than FRESH_SAMPLES samples old (a sample that could not be taken keeps the one before); `_sum` and `_count` are
+ * the completed statements since the process started (the counter), as a Prometheus client's summary is: quantiles
+ * over a recent window, sum and count cumulative.
+ */
+function durationSummary(r) {
+    const d = r.durations !== null && isFresh(r, r.durations.at) ? r.durations : null;
+    const seconds = (ms) => (ms === null || ms === undefined ? null : ms / 1000);
+    return metric("mason_statement_duration_seconds", "summary", "Completed statements' duration, seconds: p50 and p95 of the last minute's usage sample (sampled: a busy minute's of a uniform sample); sum and count since the process started.", [
+        { labels: { quantile: "0.5" }, value: seconds(d?.p50Ms), optional: true },
+        { labels: { quantile: "0.95" }, value: seconds(d?.p95Ms), optional: true },
+        { suffix: "_sum", value: r.statements.completedMs / 1000 },
+        { suffix: "_count", value: r.statements.completed },
+    ]);
+}

package/dist/src/cli/output-gate.js

@@ -0,0 +1,176 @@
+/**
+ * THE OUTPUT'S GATE: every byte a hosted command writes, on stdout and on stderr, put to the exact test at the point it
+ * is written (PR 645's class round: what was tested was not what was printed — a page tested whole and printed cut
+ * inside a `%XX` escape, a name tested with a lone surrogate read as a separator and printed by --json as `\udc00`, a
+ * page tested as it came and printed as the URL parser rewrote it). The per-value tests of src/cli/hosted.ts stay the
+ * first line (`carriesNoSecret`, `pageUrl`, `serviceText`); this is the last, and the authority: the bytes written.
+ *
+ * WHAT IS READ: each stream's text as written, after every transformation the CLI makes — styling (colour, the CLI's
+ * own line breaks: src/cli/command.ts serviceStyle), `JSON.stringify`'s escapes, a value's cut, the masks, the
+ * spinner's redraws — and the two streams together (a log that takes `2>&1`). Each is read in eight ways: with its
+ * terminal escapes and without them (what a log keeps; what a person sees), keeping `-` and `_` or not, and a `%XX`
+ * escape decoded or read as the characters it is written with — each as src/cli/hosted.ts reads a value (`bodyRead`:
+ * re-cased, in its compatibility form, every other character skipped). A run that crosses two writes is read whole:
+ * each reading keeps the last `ECHO_RUN - 1` characters it read, and a raw tail is kept for the shapes.
+ *
+ * WHAT FIRES IT: `ECHO_RUN` of a held secret's body in a row in any reading, or anything shaped as a documented token
+ * or (unless the command prints a password it made: `mason user add --replica`) a Mason user's password. Then the
+ * write that would complete it is NOT written, nor anything after it: the command's refusal is written instead, in the
+ * CLI's words (on stdout under --json, as its one object), and the process exits 1 (`gatedExit`). What was written
+ * before showed at most `ECHO_RUN - 1` in a row.
+ *
+ * HONEST OUTPUT IS NEVER REFUSED BY CHANCE, by `ECHO_RUN`'s derivation (src/cli/hosted.ts): an honest output is
+ * independent of the token, and a command writes a few KiB; read 8 ways and over 3 streams it is under 2^20
+ * characters read, and the bound W × 43 × 2 × 31^-11 is under 10^-8. tests/cli-hosted.test.ts measures it with a fixed
+ * seed over the honest outputs of deploy, login, logout and mason user --replica.
+ *
+ * ONE VALUE MAY BE PRINTED ONCE (`holdOutput`'s `once`: the CI token `mason token create` made, the one answer that
+ * carries a token by design): its FIRST whole occurrence in a write (`onceAt`: exactly as it is; the CLI writes it on a
+ * line of its own, never broken) is read as a separator, never as the secret it is, and is written; every other byte is read as before, the value held among the secrets, so a second
+ * occurrence, a piece of it elsewhere (11 of its body in a row) or anything else shaped as a token is refused as any
+ * secret is. What it allows is exactly that value, whole, one time, in one write.
+ *
+ * INERT until a command holds a secret (`holdOutput`): every other command writes as it always did.
+ */
+import { failed, serviceStyle } from "./command.js";
+import { bodyRead, canonicalTexts, ECHO_RUN, echoViews, ESCAPES, shapedSecret, wholeInCanonical } from "./hosted.js";
+import { err as styleErr } from "./style.js";
+/** The eight readings: [with escapes, without] × [keeping `-` and `_`, not] × [a `%XX` decoded, not]. */
+const READINGS = [true, false].flatMap((escapes) => [true, false].flatMap((keep) => [true, false].map((percent) => ({ escapes, keep, percent }))));
+const TAIL = ECHO_RUN - 1;
+/** The raw tail kept for the shapes and the secrets read whole: longer than any shape (a token is 56 characters, a
+ *  password 55), and than any held secret written `%XX`-encoded (`rawTail`). */
+const RAW_TAIL = 80;
+const rawTail = (secrets) => Math.max(RAW_TAIL, ...secrets.map((x) => 3 * x.length));
+export const nothingWritten = () => ({ reads: READINGS.map(() => ""), raw: "" });
+/**
+ * WHETHER WRITING `text` AFTER `before` WOULD WRITE A SECRET (the gate's test, pure): `ECHO_RUN` of a held secret's body
+ * in a row in any reading of the two together, or a shape. The stream as it would stand after it, either way.
+ */
+export function writes(before, text, secrets, o = {}) {
+    return writesAfter([before], readingsOf(text), secrets, o)[0];
+}
+/**
+ * `fresh` (a text's readings, `readingsOf(text)`) written after each of `befores`: the text is read and scanned once,
+ * and only where it meets each stream's tail again (a window of `ECHO_RUN` crossing into it lies within the tail and
+ * the text's first `TAIL` characters).
+ */
+function writesAfter(befores, fresh, secrets, o) {
+    const inside = readingsCarry(fresh, secrets, o);
+    const tail = rawTail(secrets);
+    return befores.map((before) => {
+        const meet = { reads: before.reads.map((r, i) => r + fresh.reads[i].slice(0, TAIL)), raw: before.raw + fresh.raw.slice(0, tail) };
+        const after = { reads: before.reads.map((r, i) => (r + fresh.reads[i]).slice(-TAIL)), raw: (before.raw + fresh.raw).slice(-tail) };
+        return { secret: inside || readingsCarry(meet, secrets, o), after };
+    });
+}
+/** `text`'s readings, after what was written before it (its tails): what `readingsCarry` tests. */
+export function readingsOf(text, before = nothingWritten()) {
+    // a text with no escape, or no `%`, reads the same either way: each distinct reading is made once
+    const stripped = text.includes("\x1b") ? text.replace(ESCAPES, "") : text, percents = text.includes("%");
+    const made = new Map();
+    const read = (escapes, keep, percent) => {
+        const key = `${escapes && stripped !== text}${keep}${percent && percents}`;
+        let r = made.get(key);
+        if (r === undefined) {
+            r = bodyRead(escapes ? text : stripped, keep, percent);
+            made.set(key, r);
+        }
+        return r;
+    };
+    return { reads: READINGS.map(({ escapes, keep, percent }, i) => before.reads[i] + read(escapes, keep, percent)), raw: before.raw + text };
+}
+/** Whether readings hold a secret: `run` of a held secret's body in a row in any of them, the secret whole, or a shape. */
+export function readingsCarry(read, secrets, o = {}) {
+    if (shapedSecret(read.raw, o) || shapedSecret(read.raw.replace(ESCAPES, ""), o))
+        return true;
+    for (const secret of secrets) {
+        if (!secret)
+            continue;
+        // whole, in the one reading, with its terminal escapes and without them (src/cli/hosted.ts wholeIn)
+        read.canonical ??= canonicalTexts(read.raw);
+        if (read.canonical.some((t) => wholeInCanonical(t, secret)))
+            return true;
+        for (const { keep, n, grams } of echoViews(secret, o.run ?? ECHO_RUN)) {
+            if (n === 0)
+                continue;
+            // a text with no escape and no `%` reads the same in several ways: each distinct reading is scanned once
+            const distinct = new Set(READINGS.flatMap((r, i) => r.keep === keep ? [read.reads[i]] : []));
+            for (const text of distinct)
+                for (let j = 0; j + n <= text.length; j++)
+                    if (grams.has(text.slice(j, j + n)))
+                        return true;
+        }
+    }
+    return false;
+}
+/** WHERE `value` IS WRITTEN WHOLE in `text`, exactly as it is (the CLI writes it alone, never broken: src/cli/token-hosted.ts);
+ *  null when it is not. The span, from its first character to its last. */
+export function onceAt(text, value) {
+    const i = text.indexOf(value);
+    return i < 0 ? null : [i, i + value.length];
+}
+let held = null;
+let refused = false;
+let originals = null;
+const state = { out: nothingWritten(), err: nothingWritten(), both: nothingWritten() };
+/** The refusal written in place of what the gate held back: the CLI's words alone. */
+const REFUSAL = {
+    message: "the service's answer would print a secret this command holds, so nothing more of it is printed",
+    code: "refused",
+    why: "what was about to be written held a secret this command holds (11 or more characters of a token's body in a row, or the database's password it sent), or something shaped as a token or a password: a hosted service's text is printed only when it carries none",
+    fix: "a service that repeats the token it was sent is answering outside its documented API: sign in again (mason login), so this token is replaced, and revoke it in the service's web app if it was shared",
+    next: [["mason login", "sign in again"]],
+};
+/**
+ * Hold `secrets` from here on, for `command`, whose answer is `--json` or not; again with more (login's new token)
+ * adds them. `passwords` false: this command prints a password it made (its answer's), so a password's shape is no
+ * secret in its output. `once`: a secret this command prints one time, whole (above), held as a secret beside it.
+ */
+export function holdOutput(o) {
+    const secrets = [...(held?.secrets ?? []), ...o.secrets.filter(Boolean), ...(o.once ? [o.once] : [])];
+    held = { command: o.command, json: o.json, secrets, passwords: o.passwords ?? held?.passwords ?? true, once: o.once || (held?.once ?? null) };
+}
+/** Whether the gate held output back: the process then exits 1, whatever the command returned. */
+export const outputRefused = () => refused;
+export const gatedExit = (code) => refused ? 1 : code;
+/** The gate, on process.stdout and process.stderr, once, before anything else wraps them (src/cli/main.ts). */
+export function installOutputGate() {
+    if (originals !== null)
+        return;
+    originals = { out: process.stdout.write.bind(process.stdout), err: process.stderr.write.bind(process.stderr) };
+    const gate = (which) => ((chunk, ...rest) => {
+        const original = originals[which];
+        const text = typeof chunk === "string" ? chunk : chunk instanceof Uint8Array ? Buffer.from(chunk).toString("utf8") : String(chunk);
+        const done = rest.find((x) => typeof x === "function");
+        // nothing to write (exitWhenWritten's flush), or nothing held: as it always was; once refused, nothing more
+        if (text === "")
+            return original(chunk, ...rest);
+        if (refused) {
+            if (done)
+                setImmediate(done);
+            return true;
+        }
+        if (held === null)
+            return original(chunk, ...rest);
+        // the one value printed once, whole, the first time it is written: read as a separator (above)
+        const once = held.once === null ? null : onceAt(text, held.once);
+        const tested = once === null ? text : `${text.slice(0, once[0])} ${text.slice(once[1])}`;
+        const [own, both] = writesAfter([state[which], state.both], readingsOf(tested), held.secrets, { passwords: held.passwords });
+        if (!own.secret && !both.secret) {
+            state[which] = own.after;
+            state.both = both.after;
+            if (once !== null)
+                held = { ...held, once: null };
+            return original(chunk, ...rest);
+        }
+        refused = true;
+        const io = { out: (m) => { originals.out(`${m}\n`); }, err: (m) => { originals.err(`\n${m}\n`); } };
+        failed(held.command, REFUSAL, { json: held.json, io, style: serviceStyle(styleErr()) });
+        if (done)
+            setImmediate(done);
+        return true;
+    });
+    process.stdout.write = gate("out");
+    process.stderr.write = gate("err");
+}

package/dist/src/cli/page-share.js

@@ -0,0 +1,96 @@
+import { newSharePassword, shareSecret } from "./share-run.js";
+import { probeShare, startTunnel, tunnelPlan } from "./tunnel.js";
+/** How often the page beats, and how long a share waits for a beat before it ends (the header says why each). */
+export const BEAT_MS = 15_000;
+export const BOUND_MS = 120_000;
+/** How long the tunnel has to give its address: `mason share`'s default. */
+const TIMEOUT_MS = 30_000;
+/** A tunnel's failure in the page's words: what to do there, never a flag of the command's. */
+function pageFailure(f, plan) {
+    if (f.code === "not_found") {
+        return { message: `${plan.bin} is not on this machine, and Connect from anywhere needs it`, code: "not_found", why: "the temporary address is a tunnel opened over ssh",
+            fix: `install ${plan.install}, then Connect from anywhere again`, next: [["mason doctor", "checks this machine"]] };
+    }
+    return { message: f.message, code: f.code, ...(f.why !== undefined ? { why: f.why } : {}),
+        fix: f.message.startsWith("the tunnel gave no address") ? "the tunnel's service answered in a way this Mason cannot read: nothing was left open; mason share, in a terminal, offers another tunnel"
+            : `${f.fix ?? "is this machine online? Port 443 outbound is all it needs"}; nothing was left open`,
+        next: [["mason logs", "the run's log"]] };
+}
+export class PageShares {
+    deps;
+    /** the page's share open now: its user, the tunnel once up, and the timer its beats reset */
+    current = null;
+    constructor(deps) { this.deps = deps; }
+    get bound() { return this.deps.boundMs ?? BOUND_MS; }
+    /** The roles the page offers before it asks (`RunShares.choices`). */
+    choices() { return this.deps.shares.choices(); }
+    /** Opens the page's share: the login, the tunnel, the probe; refused, the failure, and nothing left open. */
+    async open(o) {
+        const { shares } = this.deps;
+        const password = newSharePassword();
+        const opened = await shares.open({ secret: shareSecret(password), role: o.role, from: "page" });
+        if ("failure" in opened)
+            return opened;
+        const user = opened.user;
+        const mine = { user, tunnel: null, timer: this.lapse(user) };
+        this.current = mine;
+        // however it ends (Stop sharing, no beat, its tunnel, the run stopping), the tunnel's client goes with it
+        shares.onEnd(user, () => { clearTimeout(mine.timer); mine.tunnel?.stop(); if (this.current === mine)
+            this.current = null; });
+        const plan = tunnelPlan("pinggy", { port: opened.port, home: this.deps.home, token: null });
+        const t = await (this.deps.start ?? startTunnel)(plan, { timeoutMs: this.deps.timeoutMs ?? TIMEOUT_MS, onPid: (pid) => { shares.update(user, { pid, via: plan.via, state: "opening" }); } });
+        if ("message" in t) {
+            await shares.close(user, "its tunnel did not open");
+            return { failure: pageFailure(t, plan) };
+        }
+        if (this.current !== mine) {
+            t.stop();
+            return { failure: this.endedWhileOpening(user) };
+        }
+        mine.tunnel = t;
+        const probe = await (this.deps.probe ?? probeShare)(t, opened.fingerprint);
+        if (this.current !== mine) {
+            t.stop();
+            return { failure: this.endedWhileOpening(user) };
+        }
+        if (probe === "other") {
+            await shares.close(user, "its address answered with another certificate");
+            return { failure: { message: `${t.host}:${t.port} is not this share: something else answers there`, code: "failed", why: "the tunnel gave that address, and the certificate there is not this share's",
+                    fix: "nothing was left open. Do not connect a tool to that address", next: [["mason logs", "the run's log"]] } };
+        }
+        shares.update(user, { host: t.host, port: t.port, endsAt: t.endsAt, state: "up", pid: t.pid, via: plan.via });
+        void t.ended.then((why) => shares.close(user, `its tunnel closed (${why})`)).catch((e) => this.deps.log(`share: closing ${user} after its tunnel: ${e.message}`));
+        this.deps.log(`share: ${user} opened from the web page, at ${t.host}:${t.port}`);
+        return { user, host: t.host, port: t.port, database: opened.database, password, sslmode: "require", fingerprint: opened.fingerprint, role: opened.role, reads: opened.reads,
+            openedAt: new Date().toISOString(), endsAt: t.endsAt, verified: probe === "same", beatMs: BEAT_MS, boundMs: this.bound };
+    }
+    endedWhileOpening(user) {
+        const why = this.deps.shares.ended?.user === user ? this.deps.shares.ended.why : "it was stopped";
+        return { message: `the share ended while its tunnel opened: ${why}`, code: "failed", fix: "nothing was left open: Connect from anywhere again" };
+    }
+    /** The timer a beat resets: past the bound with no beat, the share ends. */
+    lapse(user) {
+        const t = setTimeout(() => {
+            void this.deps.shares.close(user, `the web page stopped checking in for ${Math.round(this.bound / 1000)} s (closed, asleep or gone)`)
+                .catch((e) => this.deps.log(`share: closing ${user}: ${e.message}`));
+        }, this.bound);
+        t.unref();
+        return t;
+    }
+    /** A beat from the page: true when `user` is the page's share and still open. */
+    beat(user) {
+        const c = this.current;
+        if (c === null || c.user !== user || this.deps.shares.fromOf(user) !== "page")
+            return false;
+        clearTimeout(c.timer);
+        c.timer = this.lapse(user);
+        return true;
+    }
+    /** Stop sharing: the page's share ended now. false: no such share of the page's is open. */
+    async stop(user) {
+        if (this.deps.shares.fromOf(user) !== "page")
+            return false;
+        await this.deps.shares.close(user, "Stop sharing, on the web page");
+        return true;
+    }
+}

package/dist/src/cli/pg-tls.js

@@ -31,7 +31,7 @@ export function runListenerSettings(shell, o) {
             fix: "drop --self-signed-tls to serve your certificate, or unset MASON_PG_TLS_CERT and MASON_PG_TLS_KEY to serve a self-signed one" };
     }
     const s = pgListenerSettings({
-        MASON_PG_HOST: shell.MASON_PG_HOST, MASON_PG_PORT: String(o.port), MASON_PG_PLAIN: shell.MASON_PG_PLAIN,
+        MASON_PG_HOST: shell.MASON_PG_HOST, MASON_PG_PORT: String(o.port), MASON_PG_PLAIN: shell.MASON_PG_PLAIN, MASON_PG_PROXY_FROM: shell.MASON_PG_PROXY_FROM,
         MASON_PG_TLS_CERT: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.cert) : shell.MASON_PG_TLS_CERT,
         MASON_PG_TLS_KEY: o.selfSigned ? path.join(o.home, SELF_SIGNED_FILES.key) : shell.MASON_PG_TLS_KEY,
     }, "127.0.0.1");
@@ -42,22 +42,30 @@ export function runListenerSettings(shell, o) {
         ...(s.fix ? { fix: s.kind === "plain" ? `${s.fix}. Or mason start --self-signed-tls: a certificate made for this project in .mason/` : s.fix } : {}),
         ...(s.kind === "plain" ? { next: [["mason start --self-signed-tls", "TLS from a certificate made in .mason/ (clients connect with sslmode=require)"]] } : {}) };
 }
+/** The name in every self-signed certificate: a certificate is handed to whoever connects, before any login, so it
+ *  names no project. */
+const SELF_SIGNED_NAME = "mason";
 /**
  * The project's self-signed certificate: the one in `.mason/` when it is still good (it parses, its key is its own, it
- * has not expired), else a new one, both files 0600. `said` is why a new one was made, for the run to print.
+ * has not expired, it names no project), else a new one, both files 0600. `said` is why a new one was made, for the run to print.
  */
-export function ensureSelfSigned(home, project, now = new Date()) {
+export function ensureSelfSigned(home, now = new Date()) {
     const certFile = path.join(home, SELF_SIGNED_FILES.cert), keyFile = path.join(home, SELF_SIGNED_FILES.key);
     const kept = keptCertificate(certFile, keyFile, now);
     if ("fingerprint" in kept)
         return { fingerprint: kept.fingerprint, said: null };
-    const made = selfSignedCertificate(`mason-${project}`, { now });
+    const made = selfSignedCertificate(SELF_SIGNED_NAME, { now });
     for (const [file, text] of [[keyFile, made.key], [certFile, made.cert]]) {
         fs.writeFileSync(file, text, { mode: 0o600 });
         fs.chmodSync(file, 0o600); // a file that was there keeps its mode through writeFileSync
     }
     return { fingerprint: new crypto.X509Certificate(made.cert).fingerprint256, said: kept.why };
 }
+/** The project's self-signed certificate as a listener reads it: the two files of `ensureSelfSigned`, and what it said. */
+export function selfSignedPair(home) {
+    const { fingerprint, said } = ensureSelfSigned(home);
+    return { cert: fs.readFileSync(path.join(home, SELF_SIGNED_FILES.cert)), key: fs.readFileSync(path.join(home, SELF_SIGNED_FILES.key)), fingerprint, said };
+}
 function keptCertificate(certFile, keyFile, now) {
     if (!fs.existsSync(certFile) || !fs.existsSync(keyFile))
         return { why: `made a self-signed certificate: .mason/${SELF_SIGNED_FILES.cert}` };
@@ -65,6 +73,8 @@ function keptCertificate(certFile, keyFile, now) {
         const x = new crypto.X509Certificate(fs.readFileSync(certFile));
         if (!x.checkPrivateKey(crypto.createPrivateKey(fs.readFileSync(keyFile))))
             return { why: `made a new self-signed certificate: .mason/${SELF_SIGNED_FILES.key} was not the key of .mason/${SELF_SIGNED_FILES.cert}` };
+        if (x.subject !== `CN=${SELF_SIGNED_NAME}` || x.issuer !== `CN=${SELF_SIGNED_NAME}`)
+            return { why: "made a new self-signed certificate: the one in .mason/ named this project to whoever connected" };
         if (new Date(x.validTo).getTime() <= now.getTime())
             return { why: `made a new self-signed certificate: the one in .mason/ expired ${x.validTo}` };
         return { fingerprint: x.fingerprint256 };

package/dist/src/cli/pg-url.js

@@ -40,6 +40,10 @@ export const withPlaceholders = (recorded) => recorded.replace(/^postgresql:\/\/
 export const withoutPlaceholders = (shown) => shown.replace(/^postgres:\/\/<user>:<password>@/, "postgresql://");
 /** The psql line for a URL, quoted for a shell. */
 export const psqlLine = (url) => `psql ${shellWord(url)}`;
+/** WHERE A TOOL CONNECTS, as `mason status --json` and `/api/state` say it (`postgres`): the recorded URL's parts, the
+ *  URL with the credentials' place shown (`shown`, what `mason start` and `mason status` print) and its psql line — one
+ *  builder, so the web page's Connect panel and the commands print the same line. */
+export const postgresFacts = (recorded) => ({ ...postgresLink(recorded), shown: withPlaceholders(recorded), psql: psqlLine(withPlaceholders(recorded)) });
 /** What a tool connecting to the listener should know: it listens on every address; its certificate is self-signed. */
 export function listenerTips(l) {
     if (l === null)

package/dist/src/cli/pin.js

@@ -1,32 +1,37 @@
 /**
  * THE PROJECT'S VERSION PIN, as the mason command holds it (src/lib/project-version.ts has the rule and the image's
  * side): `mason init` writes `mason.yml` with this command's version, `mason start` writes it into a project made
- * before there was one, and `mason init` and `mason start` refuse a command of another release line — what the
- * developer runs is then what production's image is held to.
+ * before there was one, and `mason init`, `mason start` and a `mason serve` of the package refuse a command of another
+ * release line — what the developer runs is then what production is held to.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { parseVersion, pinFileText, pinProblem, readPin, versionText, PIN_FILE } from "../lib/project-version.js";
+import { parseVersion, pinFileText, projectPinProblem, PIN_FILE } from "../lib/project-version.js";
+import { projectWriteRefusal } from "./project.js";
 /** Why this mason command may not run the project in `folder`, or null (a checkout's `dev` checks nothing). */
+export function commandPinProblem(folder, cliVersion) {
+    return projectPinProblem(folder, cliVersion, { what: "this mason command",
+        run: (p) => `run the mason command it names: npm i -g @mason-data/cli@${p} (or npx @mason-data/cli@${p} …)` });
+}
+const sentence = (clause) => `${clause[0].toUpperCase()}${clause.slice(1)}.`;
+/** The refusal as `mason init` and `mason start` say it: one line of sentences. */
 export function cliPinProblem(folder, cliVersion) {
-    const running = parseVersion(cliVersion);
-    if (running === null)
-        return null;
-    const read = readPin(folder);
-    if ("problem" in read)
-        return read.problem;
-    if (read.pin === null)
+    const r = commandPinProblem(folder, cliVersion);
+    if (r === null)
         return null;
-    const p = versionText(read.pin);
-    return pinProblem(read.pin, running, read.file, "this mason command", `Run the mason command it names: npm i -g @mason-data/cli@${p} (or npx @mason-data/cli@${p} …).`);
+    const [run, ...others] = r.ways;
+    return run === undefined ? r.problem : [`${r.problem}.`, sentence(run), ...others.map((w) => sentence(`or ${w}`))].join(" ");
 }
 /**
  * Write `folder`'s mason.yml with this command's version when it has none; the file written, or null when there was one
- * already (or this is a checkout's `dev`, which has no version to write).
+ * already (or this is a checkout's `dev`, which has no version to write), or when the project's files are read-only here
+ * (src/cli/project.ts `projectWriteRefusal`, asked of `root`, the project's: a deployed project's pin is the one committed).
  */
-export function ensurePin(folder, cliVersion) {
+export function ensurePin(folder, cliVersion, root, env = process.env) {
     if (parseVersion(cliVersion) === null)
         return null;
+    if (projectWriteRefusal(root, env) !== null)
+        return null;
     const file = path.join(folder, PIN_FILE);
     if (fs.existsSync(file))
         return null;

package/dist/src/cli/pool-size.cjs

@@ -0,0 +1,85 @@
+/**
+ * THE SIZE OF LIBUV'S POOL (issue 88). A statement in flight holds one of its threads for as long as DuckDB computes
+ * (docs/FLOWS.md "What waits, and where"), and at Node's four a fifth statement waits behind four heavy ones: 10 s to 50 s
+ * for a `SELECT 1`. libuv reads UV_THREADPOOL_SIZE once, when the first task reaches the pool, so this must run before
+ * anything uses it: CommonJS, loaded synchronously, by src/cli/mason.cjs and as main.ts's FIRST import. Nothing here may
+ * use the pool: every read is synchronous.
+ *
+ * WHY 32, MEASURED AND NOT DERIVED (docs/DESIGN.md "The pool"): Mason admits no fixed number of running statements. A
+ * session runs one at a time and CANCEL_SLOTS allows 4,096 sessions, past the 1,024 threads libuv allows, so no pool
+ * sits above that limit. The 1,024 itself is refused: libuv starts every thread at once and ABORTS the process with no
+ * message when one cannot be made (exit 133 under `--pids-limit=300`). 16 fixed five statements and 32 fixed eight; past
+ * eight there is no data, and the old queue was the only limit on how much memory statements take at once.
+ *
+ * A LIMIT ON THREADS IS READ FIRST, because that abort under a platform's restart is a silent loop. Below what Mason
+ * needs the size is lowered to fit and said; an operator's own size that does not fit refuses the start, as an invalid
+ * one does (`abc` would run 1 thread, `-1` 1,024). A size of 4 or less is never refused: it is Node's own, and what a
+ * run inherits from the `mason start` that lowered it.
+ *
+ * ON WINDOWS `process.env` never reaches libuv's getenv, so what this sets does nothing and the pool stays at 4:
+ * UV_THREADPOOL_SIZE must be set in the shell before `mason`.
+ */
+"use strict";
+const fs = require("node:fs");
+const os = require("node:os");
+
+const POOL_THREADS = 32;
+const LIBUV_MAX = 1024;
+/** Node's own size: never lowered past it */
+const FLOOR = 4;
+const CGROUP_LIMITS = ["/sys/fs/cgroup/pids.max", "/sys/fs/cgroup/pids/pids.max"];
+const PROCESS_LIMITS = "/proc/self/limits";
+
+/** A file's text; null when this machine has no such file, or it cannot be read: then it says no limit. */
+function read(file) {
+  try { return fs.readFileSync(file, "utf8"); }
+  catch { return null; }
+}
+
+/** The lowest numeric limit on threads the files say; null when none does (`max`, `unlimited`, not Linux). */
+function threadLimit(cgroupFiles, processLimits) {
+  const said = cgroupFiles.map((f) => /^\s*(\d+)\s*$/.exec(read(f) ?? "")?.[1]);
+  said.push(/^Max processes\s+(\d+)/m.exec(read(processLimits) ?? "")?.[1]);
+  const numbers = said.filter((n) => n !== undefined).map(Number);
+  return numbers.length === 0 ? null : Math.min(...numbers);
+}
+
+/**
+ * Sets UV_THREADPOOL_SIZE in `o.env` and returns the size, or refuses by `o.refuse`. Everything it reads is a parameter,
+ * for tests/cli-pool-size.test.ts. `o.announce`: say a lowered size (the commands that start a run; any other would
+ * repeat it on every call).
+ */
+function sizePool(o = {}) {
+  const env = o.env ?? process.env;
+  const platform = o.platform ?? process.platform;
+  const cpus = o.cpus ?? os.availableParallelism();
+  const say = o.say ?? ((line) => process.stderr.write(`${line}\n`));
+  const refuse = o.refuse ?? ((line) => { say(line); process.exit(1); });
+  const limit = platform !== "linux" ? null : threadLimit(o.cgroupFiles ?? CGROUP_LIMITS, o.processLimits ?? PROCESS_LIMITS);
+  /** the threads of a run with a pool of `size`: its other threads are about 20 plus five a CPU (read off real runs) */
+  const needs = (size) => size + 20 + 5 * cpus;
+  const fitting = limit === null ? POOL_THREADS : Math.min(POOL_THREADS, Math.max(FLOOR, limit - needs(0)));
+
+  const own = env.UV_THREADPOOL_SIZE;
+  if (own) {
+    if (!/^[1-9]\d*$/.test(own) || Number(own) > LIBUV_MAX) {
+      refuse(`UV_THREADPOOL_SIZE=${JSON.stringify(own)} is not a number of threads from 1 to ${LIBUV_MAX}: set one, or unset it for Mason's ${POOL_THREADS}`);
+      return null;
+    }
+    const size = Number(own);
+    if (limit !== null && size > FLOOR && limit < needs(size)) {
+      refuse(`UV_THREADPOOL_SIZE=${own} does not fit: this machine allows ${limit} threads, Mason would need about ${needs(size)}, and Node exits with no message past the limit: set UV_THREADPOOL_SIZE=${fitting}`);
+      return null;
+    }
+    return size;
+  }
+  if (fitting < POOL_THREADS && o.announce === true) {
+    say(`this machine allows ${limit} threads and Mason wants about ${needs(POOL_THREADS)}, so it uses a pool of ${fitting}: set UV_THREADPOOL_SIZE=${fitting} to choose it, or another that fits`);
+  }
+  env.UV_THREADPOOL_SIZE = String(fitting);
+  return fitting;
+}
+
+sizePool({ announce: ["start", "serve"].includes(process.argv[2] ?? "") });
+
+module.exports = { sizePool, POOL_THREADS };

package/dist/src/cli/ports.js

@@ -11,6 +11,8 @@
  */
 import * as net from "node:net";
 import { DEFAULT_PG_PORT, pgListenerAddress } from "../api/postgres/listener.js";
+/** The port the commands and the web page reach a run on, unless a flag or a setting says another. */
+export const DEFAULT_UI_PORT = 4039;
 export const PROBE_ADDRESSES = ["127.0.0.1", "0.0.0.0", "::", "::1"];
 /** The address that holds `port`, or null when every address binds. */
 export async function portHolder(port) {