@mason-data/cli 0.8.0 → 0.9.0

package/dist/src/lib/secret-mask.js

@@ -0,0 +1,142 @@
+/**
+ * AN ERROR'S WORDS, AS MASON REPEATS THEM (issue 599: the engine's error repeated the connection string, `password='…'`
+ * included, into the log, the ledger, `mason status` and the web page).
+ *
+ * WHERE THE PASSWORD CAN STILL REACH AN ERROR decides how wide this is. The engine is given the password in ONE
+ * statement, the TEMPORARY SECRET (src/duck/sync.ts `sourceSecretSql`), whose own error is never repeated (its code
+ * alone); the ATTACH's path holds no credential (`attachPath`), so the extension's `Unable to connect to Postgres at
+ * "<path>"` cannot hold it; the sync's own Postgres client sends it only inside its auth messages (src/cdc/pg-wire.ts),
+ * never in a string. So no error the sync meets holds the password, and the one form a regression would bring back is
+ * the one the old string leaked: a libpq `password=` keyword's value. That alone is masked.
+ *
+ * NEVER A SUBSTRING OF THE PASSWORD (the reviews of PR 620): an error's words carry identifiers — a table's name, the
+ * user's, the database's, a slot's, a row's value — and a mask that cut the password out of them showed where it sat
+ * (`public.****_archive` under `orders2024`, `for user "****"` under a password equal to the user's name), while a
+ * branch matching the words flipped (a catch-up's wider numeric, a ROLLBACK's `no transaction is active`). A
+ * `password=` value is no identifier, so masking it shows nothing of the password and changes no word a branch reads;
+ * and no branch reads these words at all: a decision reads `messageOf`, the raw words, which are never shown.
+ * tests/secret-mask.test.ts holds both rules over src/duck/sync.ts and src/duck/stream.ts.
+ */
+/** What a masked value reads as. */
+export const MASKED = "****";
+/** libpq's `password=` keyword and its value: quoted (`'…'`, a `\` escaping the next character, to the closing quote
+ *  or the text's end, a `\` that ends the text included: issue 621, a text cut there was returned whole) or bare (to the
+ *  next space or quote); any case, spaces allowed around the `=` as libpq allows */
+const PASSWORD_KEYWORD = /\b(password\s*=\s*)(?:'(?:[^'\\]|\\[\s\S]?)*(?:'|$)|[^\s'"]+)/gi;
+/** `text` with every `password=` keyword's value masked, and nothing else changed: the leaked form alone, safe for any
+ *  stored free text (an error's words, the ledger read back, the scrub at open). */
+export function maskPasswordKeyword(text) {
+    return text.replace(PASSWORD_KEYWORD, (_m, key) => `${key}${MASKED}`);
+}
+/** The keyword with its value not begun at the text's end (`password`, `password =`): what follows on the next line may
+ *  be its value, as libpq allows a newline among the spaces around the `=` */
+const KEYWORD_OPEN = /\bpassword\s*(?:=\s*)?$/i;
+/** Whether a quoted value (its opening `'` first) has its closing quote, by the keyword's own escapes */
+function closed(value) {
+    let escaped = false;
+    for (let i = 1; i < value.length; i++) {
+        const c = value[i];
+        if (escaped)
+            escaped = false;
+        else if (c === "\\")
+            escaped = true;
+        else if (c === "'")
+            return true;
+    }
+    return false;
+}
+/**
+ * A TEXT READ A LINE AT A TIME, MASKED AS `maskPasswordKeyword` MASKS IT WHOLE (issue 621: a log file an older Mason
+ * wrote, read by `mason logs`, holds the leaked form in its lines): the same keyword, the same value, masked the same way,
+ * and nothing else changed — never a substring of the password (the reviews of PR 620: an identifier holding it is
+ * structure, and a mask cut into it showed where the password sat).
+ *
+ * A LINE IS ITS UNIT, AND AN ENTRY ITS BOUND. A log entry is a line at the margin and the indented lines under it
+ * (src/lib/log.ts `textEntry`), so a value can run on past its line only inside its entry: a quote open at a line's end
+ * masks the next indented lines to its closing quote (a password holding a newline), and a keyword at a line's end
+ * (`password`, `password =`) takes its value from the next indented line. A line at the margin, or a blank one, starts
+ * afresh: a quote an older Mason's line left open (a message cut off) masks its own entry, never the rest of the file.
+ * Each line's answer is decided by it and the lines before it, so a reader releases a line as soon as it has it whole,
+ * whatever its own chunks (src/lib/log-read.ts), and the answer is the same for every way the file is cut.
+ */
+export class PasswordLineMask {
+    /** what the previous line left open: a quoted value (to its closing quote), or the keyword with its value not begun */
+    open = null;
+    /** A line not ended yet, masked as it stands, the state left as it was: what a follow shows of a line still being
+     *  written (src/lib/log-read.ts `follow`), the whole line read by `line` once its newline comes. */
+    peek(raw) {
+        const open = this.open;
+        try {
+            return this.line(raw);
+        }
+        finally {
+            this.open = open;
+        }
+    }
+    /** One line (no newline), masked. */
+    line(raw) {
+        if (raw.trim() === "" || /^\S/.test(raw))
+            this.open = null; // a new entry: nothing carries into it
+        const open = this.open;
+        this.open = null;
+        if (open !== null && "quote" in open) {
+            // the value runs on from the line before: masked to its closing quote (the newline ended any escape), the rest read as any line
+            const indent = /^\s*/.exec(raw)[0];
+            let escaped = false;
+            for (let i = indent.length; i < raw.length; i++) {
+                const c = raw[i];
+                if (escaped)
+                    escaped = false;
+                else if (c === "\\")
+                    escaped = true;
+                else if (c === "'")
+                    return `${indent}${MASKED}${this.alone(raw.slice(i + 1))}`;
+            }
+            this.open = { quote: true };
+            return `${indent}${MASKED}`;
+        }
+        if (open !== null) {
+            // the keyword ended the line before: read with it, and its own text taken off again (the key is kept as written)
+            return this.alone(`${open.keyword}\n${raw}`).slice(open.keyword.length + 1);
+        }
+        return this.alone(raw);
+    }
+    /** `text` masked whole, and what it leaves open at its end noted for the next line */
+    alone(text) {
+        let atEnd = null; // the value of a match that runs to the text's end
+        const masked = text.replace(PASSWORD_KEYWORD, (match, key, index) => {
+            if (index + match.length === text.length)
+                atEnd = match.slice(key.length);
+            return `${key}${MASKED}`;
+        });
+        const value = atEnd;
+        if (value !== null) {
+            if (value.startsWith("'") && !closed(value))
+                this.open = { quote: true };
+        }
+        else {
+            const k = KEYWORD_OPEN.exec(text);
+            if (k !== null)
+                this.open = { keyword: text.slice(k.index) };
+        }
+        return masked;
+    }
+}
+/** An error's code: a Postgres SQLSTATE or a system error's (`ECONNREFUSED`), the kind the engine names its error by
+ *  (`IO Error`), else none — what is said of an error whose words are never repeated (the secret's statement). */
+export function errorCode(e) {
+    if (e !== null && typeof e === "object" && typeof e.code === "string" && e.code !== "")
+        return e.code;
+    const m = e instanceof Error ? /^([A-Z][A-Za-z]*(?: [A-Za-z]+)* Error):/.exec(e.message) : null;
+    return m?.[1] ?? null;
+}
+/** A CAUGHT ERROR'S WORDS, AS MASON REPEATS THEM (a log line, an event, a table's `error`, an answer): its message (or,
+ *  `stack`, its stack), every `password=` value masked. Never matched by a branch: that reads `messageOf`. */
+export function errorText(e, o = {}) {
+    return maskPasswordKeyword(e instanceof Error ? (o.stack === true ? e.stack ?? e.message : e.message) : String(e));
+}
+/** A CAUGHT ERROR'S RAW WORDS, FOR A DECISION ALONE (which failure it is: a wider numeric, a transaction already ended):
+ *  never shown — said, logged or stored, an error's words are `errorText`'s. */
+export function messageOf(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/src/lib/table-sync.js

@@ -52,33 +52,48 @@ export function intervalOf(seconds) {
     const s = Math.max(MIN_POLL_SECONDS, Math.round(seconds));
     return s % 3600 === 0 ? `${s / 3600}h` : s % 60 === 0 ? `${s / 60}m` : `${s}s`;
 }
-/** an interval (`<n>s|m|h`) read, or why it is not one, with the interval to write when there is one */
-function parseInterval(v) {
+/** an interval (`<n>s|m|h`) read, or why it is not one, with the interval to write when there is one. ONE grammar with three
+ *  entrances, each worded as it is written: a `sync:`'s `poll <interval>`, a generated table's `target_lag:`, and a
+ *  command's wait (`parseDuration`) */
+function parseInterval(v, write = "poll ") {
     const m = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i.exec(v);
-    const how = `an interval is <n>s, <n>m or <n>h, a whole number, at least ${MIN_POLL_SECONDS}s (${EXAMPLES})`;
+    const examples = write === "" ? "5s, 5m or 1h" : EXAMPLES;
+    const how = `an interval is <n>s, <n>m or <n>h, a whole number, at least ${MIN_POLL_SECONDS}s (${examples})`;
     if (m === null)
         return { problem: `${JSON.stringify(v)} is not an interval: ${how}` };
     const n = Number(m[1]), word = m[2].toLowerCase();
     if (word === "ms")
-        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s (a poll scans the table whole on your database): write poll ${MIN_POLL_SECONDS}s or longer` };
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s${write === "" ? "" : " (a poll scans the table whole on your database)"}: write ${write}${MIN_POLL_SECONDS}s or longer` };
     const unit = UNIT_WORDS[word];
     if (unit === undefined) {
-        const days = /^(d|day|days)$/.test(word) ? `: write poll ${intervalOf(n * 86_400)}` : "";
+        const days = /^(d|day|days)$/.test(word) ? `: write ${write}${intervalOf(n * 86_400)}` : "";
         return { problem: `${v}: ${word} is not a unit of an interval — ${days ? `days are hours${days}` : how}` };
     }
     const seconds = n * UNIT_SECONDS[unit];
     if (!Number.isInteger(n))
-        return { problem: `${v}: an interval is a whole number — write poll ${intervalOf(seconds)}` };
+        return { problem: `${v}: an interval is a whole number — write ${write}${intervalOf(seconds)}` };
     if (seconds < MIN_POLL_SECONDS)
-        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s: write poll ${MIN_POLL_SECONDS}s or longer` };
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s: write ${write}${MIN_POLL_SECONDS}s or longer` };
     if (seconds > MAX_POLL_SECONDS)
-        return { problem: `${v} is over the longest interval, ${intervalOf(MAX_POLL_SECONDS)}: write poll ${intervalOf(MAX_POLL_SECONDS)}, or off with mason sync <table> run by a scheduler` };
+        return { problem: `${v} is over the longest interval, ${intervalOf(MAX_POLL_SECONDS)}: write ${write}${intervalOf(MAX_POLL_SECONDS)}${write === "" ? "" : ", or off with mason sync <table> run by a scheduler"}` };
     // the number as a number is written (`05s` is `5s`): two spellings of one interval would read as a change of sync
     const canonical = `${n}${unit}`;
     if (canonical !== v)
-        return { problem: `${JSON.stringify(v)}: write poll ${canonical}` };
+        return { problem: `${JSON.stringify(v)}: write ${write}${canonical}` };
     return { every: canonical, seconds };
 }
+/** A generated table's `target_lag:` read (src/cli/generated-files.ts): an interval alone, in the grammar and the range a
+ *  poll's takes, or what is wrong with it in the words a person fixes it from. */
+export function parseLag(v) {
+    if (typeof v !== "string" || v.trim() === "")
+        return { problem: `is ${v === null || v === undefined ? "nothing" : typeof v === "number" ? `the number ${String(v)}` : "not an interval"}: write how far behind the table may be, like 30s, 5m or 1h` };
+    return parseInterval(v.trim(), "");
+}
+/** A command's own wait, as an interval (`mason deploy --timeout 10m`): the grammar and range a poll's and a `target_lag:`
+ *  take, so a span of time is written one way at every entrance. */
+export function parseDuration(v) {
+    return parseInterval(v.trim(), "");
+}
 /**
  * A `sync:` VALUE READ, or what is wrong with it in the words a person fixes it from (the key is the caller's to say):
  * the line to write, a `did you mean` for a misspelt mode, the floor for a short interval. Whether a table CAN be

package/dist/src/web/app.js

@@ -1,5 +1,5 @@
 /**
- * THE WEB PAGE OF `mason start` (`mason ui`; docs/WEB-UI.md, and .claude/rules/web-ui.md for whoever builds it out):
+ * THE WEB PAGE OF A RUN (`mason ui`, and `mason ui --ssh` for a server's; docs/WEB-UI.md, and .claude/rules/web-ui.md for whoever builds it out):
  * the SHELL — a left sidebar (the project, then a nav of links with icons: Overview · Tables · Users, and the
  * Observability group: Queries · Usage · Logs; at its foot when it was updated and the version; an icon rail on a narrow
  * window, a menu on a phone) and one section per page, the one shown chosen by the URL's hash (`#overview`, the
@@ -52,7 +52,7 @@
  * A page is registered by its import and its place in PAGES below, its route in PAGE_ROUTES, and its section in
  * index.html.
  */
-import { esc, badge, icon, createAsk, renderFailure, updatedText, placePops, RANGES, DEFAULT_RANGE, rangeOf, rangeOffered, isLive, POLL_MS } from "./shared.js";
+import { esc, badge, icon, createAsk, overTunnel, renderFailure, updatedText, placePops, RANGES, DEFAULT_RANGE, rangeOf, rangeOffered, isLive, POLL_MS } from "./shared.js";
 import { createCharts } from "./charts.js";
 import { page as statusPage } from "./pages/status.js";
 import { page as tablesPage } from "./pages/tables.js";
@@ -74,7 +74,7 @@ export const PRESS_HOLD_MS = 2000;
 
 // every renderer the tests import from here, wherever it lives now
 export * from "./shared.js";
-export { copyingText, tableLine, keptAge, sourceRows, renderStatus } from "./pages/status.js";
+export { copyingText, tableLine, keptAge, keptWords, sourceRows, renderStatus, renderShare, createShare } from "./pages/status.js";
 export { tableFacts, addedLines, removedReport, pickBody, columnsPath, renderTableAdded, renderTablesRemoved, renderTables } from "./pages/tables.js";
 export { renderUsers, renderAdded, attributesText } from "./pages/users.js";
 export { renderRequests } from "./pages/queries.js";
@@ -176,9 +176,14 @@ function renderWhere(s) {
  * `view()` is the HTML of every part of the page, from what it knows now. Nothing here touches a document.
  */
 export function createApp(fetchFn, now = () => new Date(), shown = "status") {
-  const ask = createAsk(fetchFn);
+  const asked = createAsk(fetchFn);
   // what was read, by path: the last body, this read's failure (null when it answered), when it was asked
   const store = new Map();
+  // every answer passes here: on a server's page a failure the page words itself is the tunnel's (`overTunnel`)
+  const ask = async (path, init) => {
+    const r = await asked(path, init);
+    return "failure" in r && store.get("/api/state")?.body?.served === true ? { failure: overTunnel(r.failure) } : r;
+  };
   const first = parseHash(shown);
   const m = { shown: first.id, range: rangeOf(first.params.range), pollFailure: null, updatedAt: null, rangeReadAt: null };
   const put = (path, at, r) => {

package/dist/src/web/pages/status.js

@@ -20,7 +20,8 @@
 const LINKS = { tables: "#tables", failedTables: "#tables?show=failed", usage: "#observability/usage?range=24h", queries: "#observability/queries?range=24h",
   slow: "#observability/queries?slow=1&range=24h", failedQueries: "#observability/queries?status=refused-or-failed&range=24h", failedEvents: "#observability/syncs?failures=1&range=7d" };
 import { msText, bytesText, code, esc, fileSize, firstLine, n, percent, leftText, spanText, duration, entryName, streamRows, slotWarns, masonRow, sessionsRows, diskRows, restartsRows, utcText,
-  utcMinute, oneLine, clientText, eventCells, unsupportedEntry, usagePath, POLL_MS, card, cards, details, createOpenSet, skeleton, renderConnect, copyClick } from "../shared.js";
+  utcMinute, oneLine, clientText, eventCells, unsupportedEntry, usagePath, POLL_MS, card, cards, details, createOpenSet, skeleton, renderConnect, copyClick,
+  badge, button, copyable, pop, renderFailure, json } from "../shared.js";
 import { spark, seriesOf, drawable } from "../charts.js";
 
 /** How many recent errors of each kind are shown: mason status's (src/cli/commands.ts `RECENT_ERRORS`, held equal by the tests). */
@@ -62,18 +63,29 @@ export function copyingText(copied, rowsEstimate, p) {
  * current and how old its copy is (`keptAge`).
  */
 export function tableLine(t, now = Date.now()) {
-  if (t.error) return { state: "failed", fraction: 1, what: `its first sync failed: ${firstLine(t.error)}` };
+  if (t.error) return { state: "failed", fraction: 1, what: t.copy?.phase === "done" ? copiedFailedText(t, now) : `its first sync failed: ${firstLine(t.error)}` };
   if (t.copy?.phase === "copying") {
     const c = copyingText(t.copy.rowsCopied, t.rows, t.copy.progress);
     return { state: "copying", fraction: c.fraction ?? 0, what: /^\d/.test(c.text) ? `syncing ${c.text}` : c.text };
   }
   if (!t.copy) return { state: "waiting", fraction: 0, what: "waiting for its first sync to start" };
-  const age = keptAge(t, now);
+  const age = keptWords(t, now);
+  const what = `${n(t.copy.rowsCopied ?? 0)} rows · synced${t.copy.retired ? ` · ${t.copy.retired}` : ""}${age ? ` · ${age}` : ""}`;
   // a copy the poll does not keep current (it waits for its catch-up) is a warning, as mason status paints it (paintBar)
-  if ((t.kept?.by === "poll" && t.kept.pending !== undefined) || (t.kept?.by === "replication" && (t.kept.state !== "streamed" || t.kept.notRunning !== null))) {
-    return { state: "unsynced", fraction: 1, what: `${n(t.copy.rowsCopied ?? 0)} rows · synced${t.copy.retired ? ` · ${t.copy.retired}` : ""} · ${age}` };
+  // and so is one behind what its sync promises (`tables[].sync.state`, src/cli/readiness.ts behindOf), of any kind
+  if ((t.kept?.by === "poll" && t.kept.pending !== undefined) || (t.kept?.by === "replication" && (t.kept.state !== "streamed" || t.kept.notRunning !== null)) || t.sync?.state === "behind") {
+    return { state: "unsynced", fraction: 1, what };
   }
-  return { state: "done", fraction: 1, what: `${n(t.copy.rowsCopied ?? 0)} rows · synced${t.copy.retired ? ` · ${t.copy.retired}` : ""}${age ? ` · ${age}` : ""}` };
+  return { state: "done", fraction: 1, what };
+}
+
+/** What a served table's line says after `synced`, for every kind: its keeping and age, then behind (src/cli/commands.ts `keptWords`). */
+export function keptWords(t, now = Date.now()) {
+  const age = keptAge(t, now), s = t.sync;
+  if (s?.state !== "behind" || s.behindBySeconds == null) return age;
+  const why = s.behindWhy ?? "its next sync is late";
+  const by = `behind by ${duration(s.behindBySeconds)}${age !== null && age.includes(why) ? "" : `: ${why}`}`;
+  return age === null ? by : `${age} — ${by}`;
 }
 
 /** How long ago a table was synced, as `mason status` says it on its line (src/lib/table-sync.ts `agoText`, which
@@ -93,7 +105,7 @@ export function keptAge(t, now = Date.now()) {
   if (k?.by === "replication") {
     if (k.state !== "streamed") return `NOT kept current (${k.syncedAt === null ? "never synced" : `last synced ${syncedAgo(k.syncedAt, now)}`}): ${k.why ?? "it is not streamed yet"}`;
     const at = `replicated, at ${k.position}, ${k.syncedAt === null ? "not synced yet" : syncedAgo(k.syncedAt, now)}`;
-    return k.notRunning === null ? at : `${at} — NOT kept current now, the stream is not running: ${k.notRunning}`;
+    return k.notRunning === null || t.sync?.state === "behind" ? at : `${at} — NOT kept current now, the stream is not running: ${k.notRunning}`;
   }
   if (k?.by !== "poll") return null;
   const synced = k.syncedAt === null ? "never synced" : `last synced ${syncedAgo(k.syncedAt, now)}`;
@@ -102,6 +114,15 @@ export function keptAge(t, now = Date.now()) {
   return `polled every ${k.sync.every}, ${k.syncedAt === null ? "not polled yet" : `last ${syncedAgo(k.syncedAt, now)}`}`;
 }
 
+/** A served table whose sync failed, as mason status says it (src/cli/commands.ts `copiedFailedText`). */
+function copiedFailedText(t, now) {
+  const k = t.kept;
+  const reason = k?.by === "replication" ? (k.state !== "streamed" ? k.why : k.notRunning === null ? null : `the stream is not running: ${k.notRunning}`)
+    : k?.by === "poll" || k?.by === "recopy" ? k.pending ?? null : null;
+  const asOf = t.sync?.asOf ?? (k && k.by !== "generated" && k.by !== "recopy" ? k.syncedAt : null) ?? t.sync?.syncedAt ?? null;
+  return `${n(t.copy?.rowsCopied ?? 0)} rows · synced · NOT kept current, its sync failed (${asOf === null ? "never synced" : `last synced ${syncedAgo(asOf, now)}`}): ${reason ?? firstLine(t.error)}`;
+}
+
 /**
  * A COPY'S BAR, the one renderer of the Overview's "copies not finished" and the Tables page's rows: a thin rounded
  * track and a solid fill to the share drawn, its % as text at the bar's END (as `mason wait` prints it beside its bar),
@@ -162,6 +183,7 @@ export function sourceRows(s) {
           `${s.source.replication.owned ? "Mason's own, carrying them alone" : "named: read as it is, never altered"}); the others by a SELECT of their changed rows`
         : s.source.demo ? "the demo database is checked this way only"
         : "sync: replication on an entry streams that table as it happens instead")],
+    ...(s.source.textOrder ? [["Text order", s.source.textOrder]] : []),
   ];
 }
 
@@ -400,11 +422,58 @@ export function renderStatus(s, o = {}) {
   // how to connect, once a table is added: first under the cards while nothing has asked Mason anything (the last
   // day's and week's statements, read as none), else after the facts, for the next tool
   const first = isFirstConnect(o.queries);
-  const connect = added ? renderConnect(s.postgres, { first, table: s.tables.find((t) => t.added && t.copy?.phase === "done")?.table ?? null }) : "";
+  const connect = added ? renderConnect(s.postgres, { first, served: s.served === true, table: s.tables.find((t) => t.added && t.copy?.phase === "done")?.table ?? null,
+    share: renderShare(s, o.share ?? NO_SHARE, now) }) : "";
   return renderHealth(s) + renderChecklist(s, o.queries, o.users) + renderKpis(s, { ...o, now }) + (first ? connect : "") + renderProgress(s, o.open, o.shares, o.before) + renderFacts(s, now) + (first ? "" : connect) + renderStream(s, now) +
     (added ? renderQueries(o.queries) : "") + (added ? renderRecentErrors(o.events, o.requests, o.unsupported) : "");
 }
 
+// ------------------------------------------------------------------ Connect from anywhere (mason share, from the page)
+
+/** The page's share before anything was asked: what `renderShare` and the page's model start from. */
+export const NO_SHARE = Object.freeze({ phase: "none", choices: null, reads: null, role: null, opened: null, ended: null, failure: null });
+
+/** The share the page holds, as `/api/state` `share` lists it (`from: "page"`), or null. */
+export const pageShareOf = (s) => s?.share?.shares?.find((x) => x.from === "page") ?? null;
+
+/** When a free share ends, as `mason share` says it: about an hour, and the time. */
+const endsLine = (endsAt, now) => endsAt === null || endsAt === undefined ? "It ends when you Stop sharing, or when this page closes."
+  : `A free share ends within about an hour: at ${new Date(endsAt).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}, in about ${Math.max(0, Math.round((Date.parse(endsAt) - now) / 60_000))} minutes. Then Connect from anywhere again gives a new address and password.`;
+
+/**
+ * CONNECT FROM ANYWHERE, the Connect card's part (src/cli/page-share.ts; `mason share`'s, from the page): a pure function
+ * of the state (`s`) and the page's own model (`m`: `phase` none · asking · opening · open · ended · refused, the roles
+ * offered, the answer that opened it — the password is in it alone — and the failure). Nothing under `mason serve`.
+ */
+export function renderShare(s, m = NO_SHARE, now = Date.now()) {
+  if (s?.served === true) return "";
+  const open = pageShareOf(s);
+  const head = `<p class="connect-title share-title">Connect from anywhere</p>`;
+  const ask = button("Connect from anywhere", { shareAsk: "" }, "", { disabled: m.phase === "asking" || m.phase === "opening" });
+  const askLine = `<p class="tip" id="share-anchor">${ask} <span>For a tool in the cloud, which cannot reach this machine: a temporary public address and a password, as ${code("mason share")} opens. TLS is required of every connection.</span></p>`;
+  if (open !== null && m.phase !== "ended") {
+    const mine = m.opened !== null && m.opened.user === open.user ? m.opened : null;
+    const rows = [["Host", open.host ?? "opening…", "share-host"], ["Port", open.port === null ? "…" : String(open.port), "share-port"], ["Database", mine?.database ?? s.postgres?.database ?? "", null],
+      ["User", open.user, "share-user"], ...(mine !== null ? [["Password", mine.password, "share-password"]] : []), ["SSL mode", "require", null]];
+    return `<div class="share open" role="status">${head}<p class="headline">Shared ${badge("Public", "warn")} for <time data-tick datetime="${esc(open.openedAt)}">${esc(spanText((now - Date.parse(open.openedAt)) / 1000))}</time>` +
+      `${open.role !== null ? `, reading as the role ${esc(open.role)}` : ""}: ${esc(open.reads)}</p>` +
+      `<dl class="facts">${rows.map(([k, v, id]) => `<dt>${esc(k)}</dt><dd>${id ? copyable(id, v) : esc(v)}</dd>`).join("")}</dl>` +
+      (mine !== null ? `<p class="tip">Paste it into the tool now: the password is shown this once, is kept nowhere, and ends with the share.</p>`
+        : `<p class="tip">The password was shown once, when it opened, and is kept nowhere: Stop sharing and Connect from anywhere again for a new one.</p>`) +
+      `<p class="tip">${esc(endsLine(open.endsAt, now))} It also ends within two minutes of this page closing.</p>` +
+      `<p class="tip">${button("Stop sharing", { shareStop: open.user }, "danger")}</p></div>`;
+  }
+  if (m.phase === "opening") return `<div class="share">${head}<p class="dim" aria-busy="true">Opening a temporary public address… (up to 30 s)</p></div>`;
+  const before = m.phase === "ended" && m.ended !== null
+    ? `<p class="said">The share ended: ${esc(m.ended.why)}. Its address no longer answers, and its password no longer works.</p>`
+    : m.phase === "refused" && m.failure !== null ? renderFailure(m.failure) : "";
+  const question = m.phase !== "asking" ? "" : pop("share-anchor", m.choices === null ? `<p class="dim">Reading the roles…</p>` :
+    `<p>This opens a <strong>temporary public address</strong>: anyone with it and its password reads ${esc(m.reads ?? "what the role you choose reads")}. A free share ends within about an hour, and when this page closes.</p>` +
+    (m.choices.length > 0 ? `<label for="share-role">Read as the role</label> <select id="share-role">${m.choices.map((c) => `<option value="${esc(c.role)}"${c.role === m.role ? " selected" : ""}>${esc(`${c.role}: ${c.reads}${c.default ? " (the file's default)" : ""}`)}</option>`).join("")}</select>` : "") +
+    `<p>${button("Open the address", { shareOpen: "" }, "primary")} ${button("Cancel", { shareCancel: "", popClose: "" })}</p>`, { kind: "dialog", label: "Connect from anywhere" });
+  return `<div class="share">${head}${before}${askLine}${question}</div>`;
+}
+
 /** Nothing has asked Mason anything yet: the last day's statements were read (`/api/queries`' body), and are none. */
 export const isFirstConnect = (q) => q !== undefined && !("failure" in q) && q.queries.day.statements === 0 && q.queries.week.statements === 0;
 
@@ -427,20 +496,116 @@ export const page = {
     // the details open (a copy's whole error), by key: a poll rewrites the section, and they stay open
     const opened = createOpenSet();
     const monotone = createMonotone();
+    const share = createShare(ctx);
     return {
-      model: { open: opened.open },
+      model: { open: opened.open, share: share.m },
       reads: () => [{ path: "/api/state", everyMs: POLL_MS }, ...SLOWER.map((path) => ({ path, everyMs: 30_000 })), { path: HOURLY, everyMs: 60_000 }],
-      actions: {},
+      actions: share.actions,
+      afterRead: () => share.afterRead(ctx.read("/api/state")?.body),
+      input: (target) => share.input(target),
       view() {
         const st = ctx.read("/api/state");
         if (!st?.body) return { status: st?.failure ? "" : skeleton(4) };
         const [queries, events, requests, unsupported, users] = SLOWER.map((p) => asRequest(ctx.read(p)));
-        return { status: renderStatus(st.body, { now: ctx.now().getTime(), queries, events, requests, unsupported, users, usage: ctx.read(HOURLY)?.body, open: opened.has, shares: monotone.of(st.body), before: monotone.before }) };
+        return { status: renderStatus(st.body, { now: ctx.now().getTime(), queries, events, requests, unsupported, users, usage: ctx.read(HOURLY)?.body, open: opened.has, shares: monotone.of(st.body), before: monotone.before, share: share.m }) };
       },
       toggle: (target) => opened.toggle(target),
-      // Connect's Copy buttons
-      click: (d, button, env) => copyClick(d, button, env),
+      // Connect's Copy buttons, and Connect from anywhere's
+      click: (d, button, env) => share.click(d) ?? copyClick(d, button, env),
       charts: () => sparkSpecs(ctx.read(HOURLY)?.body),
     };
   },
 };
+
+/** What a page beats with, when the answer that opened the share does not say (src/cli/page-share.ts BEAT_MS). */
+const BEAT_MS = 15_000;
+
+/**
+ * THE PAGE'S SIDE OF CONNECT FROM ANYWHERE (src/cli/page-share.ts has why each choice): ask once, open, BEAT while the
+ * share is open — on a timer of its own, which runs while the tab is hidden (the poll does not: the person is in their
+ * tool's tab, pasting) —, Stop sharing. The password is in `m.opened` alone, the page's memory, and is dropped the moment
+ * the share is seen ended. `ctx.timers` is a test's clock; a browser's own otherwise.
+ */
+export function createShare(ctx) {
+  const m = { ...NO_SHARE };
+  const timers = ctx.timers ?? globalThis;
+  let beating = null;
+  const stopBeats = () => { if (beating !== null) { timers.clearInterval(beating.id); beating = null; } };
+  const ended = (user, why) => { stopBeats(); m.opened = null; m.phase = "ended"; m.ended = { user, why }; };
+  const beat = async () => {
+    if (beating === null) return;
+    const user = beating.user;
+    const r = await ctx.ask(`/api/share/${encodeURIComponent(user)}/beat`, json("POST"));
+    if ("failure" in r && r.failure.code === "not_found" && beating?.user === user) { ended(user, r.failure.message.replace(/^.*?; it ended: /, "")); await ctx.refresh(["/api/state"]); }
+  };
+  const startBeats = (user, everyMs = BEAT_MS) => {
+    if (beating?.user === user) return;
+    stopBeats();
+    beating = { user, id: timers.setInterval(() => { void beat(); }, everyMs) };
+  };
+  const actions = {
+    /** Connect from anywhere: what a share would read, then the question */
+    async shareAsk() {
+      Object.assign(m, NO_SHARE, { phase: "asking" });
+      const r = await ctx.ask("/api/share/choices");
+      if (m.phase !== "asking") return;
+      if ("failure" in r) { m.phase = "refused"; m.failure = r.failure; return; }
+      m.choices = r.body.choices;
+      m.reads = r.body.reads ?? null;
+      m.role = r.body.choices.find((c) => c.default)?.role ?? r.body.choices[0]?.role ?? null;
+    },
+    shareCancel() { Object.assign(m, NO_SHARE); },
+    shareRole(role) { if (m.choices?.some((c) => c.role === role)) m.role = role; },
+    /** the person said yes: the run opens the share (confirmed), and its one answer carries the password */
+    async shareOpen() {
+      if (m.phase !== "asking" || m.choices === null) return;
+      const role = m.choices.length > 0 ? m.role : null;
+      Object.assign(m, { phase: "opening", failure: null });
+      const r = await ctx.ask("/api/share", json("POST", { from: "page", confirmed: true, ...(role !== null ? { role } : {}) }));
+      if ("failure" in r) { m.phase = "refused"; m.failure = r.failure; return; }
+      Object.assign(m, { phase: "open", opened: { ...r.body, seen: false } });
+      startBeats(r.body.user, r.body.beatMs);
+      await ctx.refresh(["/api/state"]);
+    },
+    async shareStop(user) {
+      const r = await ctx.ask(`/api/share/${encodeURIComponent(user)}`, json("DELETE"));
+      if ("failure" in r && r.failure.code !== "not_found") { m.phase = "refused"; m.failure = r.failure; return; }
+      ended(user, "Stop sharing, on this page");
+      await ctx.refresh(["/api/state"]);
+    },
+    shareBeat: beat,
+  };
+  return {
+    m,
+    actions,
+    /** after each read of the state: a share of the page's open is beaten (a reload's too); the one this page opened,
+     *  once listed and now gone, ended — said with the run's why, and its password dropped */
+    afterRead(s) {
+      if (s === undefined || s === null) return;
+      const open = pageShareOf(s);
+      if (open !== null) {
+        if (m.opened?.user === open.user) m.opened.seen = true;
+        if (m.phase === "ended" && m.ended?.user === open.user) return;
+        if (m.phase === "none" || m.phase === "ended") m.phase = "open";
+        startBeats(open.user);
+        return;
+      }
+      if (m.phase === "open" && (m.opened === null || m.opened.seen)) {
+        const user = m.opened?.user ?? beating?.user ?? null;
+        ended(user, s.shareEnded !== null && s.shareEnded !== undefined && s.shareEnded.user === user ? s.shareEnded.why : "it is no longer open");
+      }
+    },
+    input(target) {
+      if (target?.id !== "share-role") return null;
+      actions.shareRole(target.value);
+      return true;
+    },
+    click(d) {
+      if (d.shareAsk !== undefined) return actions.shareAsk() ?? true;
+      if (d.shareOpen !== undefined) return actions.shareOpen();
+      if (d.shareCancel !== undefined) return actions.shareCancel() ?? true;
+      if (d.shareStop !== undefined) return actions.shareStop(d.shareStop);
+      return null;
+    },
+  };
+}

package/dist/src/web/pages/syncs.js

@@ -59,7 +59,7 @@ export function renderEvents(b, { failuresOnly = false, kind = "", table = "", n
 
 /** EVERY KIND OF SYNC EVENT, in its order (src/duck/events.ts `EVENT_KINDS`, held equal by the tests): the Kind filter
  *  offers each, whether the range has one or not. */
-export const EVENT_KINDS = ["copy_failed", "poll_failed", "catch_up_failed", "stream_failed", "source_unreachable", "restart", "copied", "recovered", "synced", "sync_changed"];
+export const EVENT_KINDS = ["copy_failed", "poll_failed", "catch_up_failed", "stream_failed", "source_unreachable", "generated_failed", "restart", "copied", "recovered", "synced", "sync_changed"];
 
 /** The kind and table filters' controls: EVERY kind (EVENT_KINDS), and EVERY added table (`/api/state` `tables`, `s`) —
  *  the sync's own "(the sync)" first — whether the range has an event of it or not, so the choices never depend on what

package/dist/src/web/pages/tables.js

@@ -24,7 +24,7 @@ export const syncsHref = (table) => `#observability/syncs?table=${encodeURICompo
 export const columnsPath = (table) => `/api/tables/${encodeURIComponent(table)}/columns`;
 
 /** A table's sync in one word (`/api/state` `tables[].sync.state`, src/cli/readiness.ts `syncStateOf`). */
-const SYNC_WORDS = { synced: "Synced", syncing: "Syncing", failed: "Failed", waiting: "Waiting" };
+const SYNC_WORDS = { synced: "Synced", syncing: "Syncing", behind: "Behind", failed: "Failed", waiting: "Waiting" };
 
 /** Whether a table's name has the search box's text (any case; nothing typed: every table). */
 const nameMatches = (table, filter) => !filter || table.toLowerCase().includes(filter.trim().toLowerCase());
@@ -199,6 +199,8 @@ export function renderTables(s, ui = {}) {
   const { removing = null, choosing = null, columns = null, outcome = null, ticked = null, filter = "", show = "all", sizes, syncing = [], adding = [], shares = new Map(), before = new Map(), synced = null, open = () => false, limit = TABLE_ROWS } = ui;
   const now = ui.now ?? Date.now();
   if (!s.tables.length) return empty(`${s.source.database} has no table this user can read.`);
+  // why no table can be added or removed from here (a server's sources file this run cannot write), or null
+  const readOnly = s.sourcesReadOnly ?? null;
   const stream = s.stream ? new Map(streamRows(s.stream, now).tables) : null;
   // SEVEN NARROW COLUMNS OF FIXED WIDTHS, NOTHING LONG IN A CELL, AND NOTHING A CLICK INSERTS: a table's state is its word
   // over its copy's bar (a line kept for it when it has none); its last sync an age over how long it took; whatever is
@@ -227,7 +229,9 @@ export function renderTables(s, ui = {}) {
       ? `<a class="btn small" href="${esc(syncsHref(t.table))}">View events</a> ` +
         (syncing.includes(t.table) ? button("Syncing…", {}, "small", { room: ROOMS.sync, disabled: true }) : button(syncedNow ? "Synced ✓" : "Sync now", { syncTable: t.table }, "small", { room: ROOMS.sync })) + " " +
         // while it asks, Remove stays where it was, held down: the question beside it answers it
-        (asking ? button("Remove", {}, "danger small", { disabled: true, expanded: true }) : button("Remove", { removeTable: t.table }, "danger small"))
+        (readOnly ? "" : asking ? button("Remove", {}, "danger small", { disabled: true, expanded: true }) : button("Remove", { removeTable: t.table }, "danger small"))
+      // a sources file this run cannot write (`s.sourcesReadOnly`, a server's): no control that could only fail
+      : readOnly ? ""
       : t.reason === null
         ? `${button("Add", { addTable: t.table }, "primary small")} ${choosing === t.table ? button("Columns…", {}, "small", { disabled: true, expanded: true }) : button("Columns…", { choose: t.table }, "small")}`
         : t.key.length ? "" : choosing === t.table ? button("Name its key…", {}, "small", { disabled: true, expanded: true }) : button("Name its key…", { choose: t.table }, "small");
@@ -284,7 +288,8 @@ export function renderTables(s, ui = {}) {
   const matching = filter.trim() ? `<p class="count dim">${n(shown.length)} with “${esc(filter.trim())}” in the name</p>` : "";
   const sizesFailed = added && sizes && "failure" in sizes ? `<p class="count">The synced tables' own sizes: could not read them (${esc(firstLine(sizes.failure.message))}; ${code("mason usage")} has them)</p>` : "";
   const rowsHtml_ = written.map(line).join("");
-  return stray + (added ? "" : empty("No table added yet", `Add one from the list, as ${code("mason add <table>")} does.`)) + matching +
+  return stray + (readOnly === null ? "" : `<p class="count">Tables are not added or removed from this page: ${esc(readOnly)}.</p>`) +
+    (added ? "" : empty("No table added yet", readOnly === null ? `Add one from the list, as ${code("mason add <table>")} does.` : `The sources file names the tables to sync.`)) + matching +
     panel(`<table class="catalog"><thead><tr>${head.map(([h, c]) => `<th scope="col"${c ? ` class="${c}"` : ""}>${h}</th>`).join("")}</tr></thead>` +
       `<tbody>${rowsHtml_}</tbody></table>`) + pops.join("") + moreRows("tables", Math.min(limit, shown.length), shown.length, TABLE_ROWS) +
     (!shown.length ? `<p class="dim">No ${show === "added" ? "added " : show === "failed" ? "failed " : show === "not-added" ? "table that is not added, " : ""}table${filter.trim() ? `'s name has “${esc(filter.trim())}”` : ""}.</p>` : "") + sizesFailed +

package/dist/src/web/pages/users.js

@@ -3,7 +3,7 @@
  * POST /api/users/<name>/disable and /enable, DELETE /api/users/<name>. An added user's password lives in this page's memory until the person dismisses it, never in
  * storage, a URL or a log line.
  */
-import { actId, badge, button, code, copyable, copyClick, duration, empty, esc, json, panel, pop, renderFailure, ROOMS, status, utcMinute } from "../shared.js";
+import { actId, badge, button, code, copyable, copyClick, duration, empty, esc, json, panel, pop, renderFailure, ROOMS, serverHostNote, status, utcMinute } from "../shared.js";
 
 /** The users as the page reads them: with each one's last use (`mason user list` asks the same), then every 30 s. */
 const USERS = "/api/users?lastUsed=1";
@@ -97,12 +97,13 @@ export function renderUsers(list, confirming = null, now = Date.now(), refused =
  * state), and a user's password is copied only from the card shown once when it is added (`renderAdded`). "" when the
  * run did not say.
  */
-export function renderUsersConnect(pg) {
+export function renderUsersConnect(pg, served = false) {
   if (!pg || typeof pg.shown !== "string") return "";
   const rows = [["Host", pg.host, "users-connect-host"], ["Port", String(pg.port), "users-connect-port"], ["Database", pg.database, "users-connect-database"],
     ["SSL mode", pg.sslmode ?? "disable", "users-connect-sslmode"], ["URL", pg.shown, "users-connect-url"], ["psql", pg.psql, "users-connect-psql"]];
   return `<div class="connect"><p class="connect-title">Connect</p>` +
     `<dl class="facts">${rows.map(([k, v, id]) => `<dt>${esc(k)}</dt><dd>${copyable(id, v)}</dd>`).join("")}</dl>` +
+    (served ? `<p class="tip">${serverHostNote(pg)}</p>` : "") +
     `<p class="tip">A user's name and password go in place of ${code("<user>")} and ${code("<password>")}. The password is shown once, when the user is added: lost, remove the user and add it again.</p></div>`;
 }
 
@@ -192,7 +193,7 @@ export const page = {
         return {
           // the roles file's state is the run's (/api/state roles): a file that cannot be read refuses every user held to it
           users: u ? renderUsers(u, m.confirming, ctx.now().getTime(), m.refused, ctx.read(STATE)?.body?.roles ?? null) : "",
-          "users-connect": renderUsersConnect(ctx.read(STATE)?.body?.postgres),
+          "users-connect": renderUsersConnect(ctx.read(STATE)?.body?.postgres, ctx.read(STATE)?.body?.served === true),
           added: m.added ? renderAdded(m.added) : "",
           action: m.actionFailure ? renderFailure(m.actionFailure) : "",
         };