@mason-data/cli 0.10.0 → 0.11.0

package/dist/src/cli/ui-socket.js

@@ -0,0 +1,183 @@
+/**
+ * `MASON_UI_SOCKET` (mason serve): THE WEB PAGE ON A UNIX SOCKET THE OPERATOR NAMES, beside its loopback port, for a
+ * process on the same machine (a supervisor, a local reverse proxy) that should reach the page without a port published
+ * or a `docker exec` per request.
+ *
+ * WHO CAN CONNECT is who can write the socket, so the socket is made mode 0600 in a folder only Mason's user can write
+ * (owned by it, no group or other write), never through a symbolic link: anything else refuses the start, with the way
+ * out. A path that is already there is replaced only when it is a socket of Mason's user that nobody answers on (a run
+ * that crashed left it); a file of any other kind, a link, another user's socket, or one a process answers on is never
+ * removed. The socket is removed when the run stops.
+ *
+ * WHAT A REQUEST ON IT IS TRUSTED WITH: exactly what one through `mason ui --bridge` is, because it reaches the run's own
+ * request handler (src/cli/run-server.ts), behind the same guard (src/cli/security.ts): its Host, the run's token or a
+ * tunnel's ticket and cookie, its Origin. Arriving on the socket proves nothing: no request is taken for a local
+ * browser, or let in at all, for where it came from.
+ */
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as net from "node:net";
+import * as path from "node:path";
+export const UI_SOCKET_SETTING = "MASON_UI_SOCKET";
+/** The longest path a Unix socket may have: `sun_path` holds 108 bytes on Linux, 104 on macOS, each with its NUL. */
+const maxSocketBytes = (platform) => platform === "darwin" ? 103 : 107;
+/** How long a socket at the path has to answer before it is taken for one nobody serves: a live run answers at once. */
+const PROBE_MS = 1_000;
+/** The socket MASON_UI_SOCKET names, absolute; null when it is unset (or set empty); or what is wrong with it. */
+export function uiSocketSetting(env, cwd, platform = process.platform) {
+    const set = env[UI_SOCKET_SETTING];
+    if (!set)
+        return null;
+    if (platform === "win32")
+        return { problem: `${UI_SOCKET_SETTING} is set, and Windows has no Unix socket for the page: unset it (mason ui --ssh <user@server> opens the page from your machine)` };
+    const file = path.resolve(cwd, set);
+    const bytes = Buffer.byteLength(file);
+    if (bytes > maxSocketBytes(platform))
+        return { problem: `${UI_SOCKET_SETTING}=${JSON.stringify(set)} is ${bytes} bytes as a full path, and a Unix socket's path is at most ${maxSocketBytes(platform)}: name a shorter one` };
+    return file;
+}
+const refused = (file, problem, fix) => ({ message: `${UI_SOCKET_SETTING}=${file}: ${problem}`, code: "refused", why: "the socket is how a process on this machine reaches the web page, so only Mason's user may make or replace it", fix });
+export const octal = (mode) => `0${(mode & 0o777).toString(8)}`;
+/** Whether a process answers on the socket at `file`: true, false (nothing listens), or the error that left it unknown. */
+function answers(file) {
+    return new Promise((resolve) => {
+        const c = net.connect(file);
+        const timer = setTimeout(() => { c.destroy(); resolve(new Error(`it neither accepted nor refused a connection in ${PROBE_MS} ms`)); }, PROBE_MS);
+        c.once("connect", () => { clearTimeout(timer); c.destroy(); resolve(true); });
+        c.once("error", (e) => { clearTimeout(timer); resolve(e.code === "ECONNREFUSED" ? false : e); });
+    });
+}
+/**
+ * THE FOLDER OF A FILE ONLY MASON'S USER MAY MAKE (the page's socket, the run's file, src/cli/ui-run-file.ts): a folder,
+ * not a link to one, owned by Mason's user, which no group or other can write; null, or what is wrong and the way out.
+ * Fails closed: a folder it cannot read is refused. `what` names the file in the way out ("socket", "run file").
+ */
+export function ownFolderProblem(file, what, uid) {
+    const dir = path.dirname(file);
+    const ownFolder = `mkdir -m 700 ${dir} as Mason's user, or name a ${what} in a folder that is only its own (the data folder's .mason/ is)`;
+    let d;
+    try {
+        d = fs.lstatSync(dir);
+    }
+    catch (e) {
+        return { problem: `its folder ${dir} cannot be read: ${e.code === "ENOENT" ? "it does not exist" : e.message}`, fix: ownFolder };
+    }
+    if (d.isSymbolicLink()) {
+        let real;
+        try {
+            real = fs.realpathSync(dir);
+        }
+        catch (e) {
+            real = `it names nothing that can be read: ${e.message}`;
+        }
+        return { problem: `its folder ${dir} is a symbolic link`, fix: `name the ${what} in the folder itself (${real}), not through a link to it` };
+    }
+    if (!d.isDirectory())
+        return { problem: `${dir} is not a folder`, fix: ownFolder };
+    if (d.uid !== uid)
+        return { problem: `its folder ${dir} is owned by uid ${d.uid}, not Mason's user (uid ${uid})`, fix: ownFolder };
+    if ((d.mode & 0o022) !== 0)
+        return { problem: `its folder ${dir} can be written by others than Mason's user (mode ${octal(d.mode)})`, fix: `chmod go-w ${dir}, or ${ownFolder}` };
+    return null;
+}
+/**
+ * The folder and the path held to the bar (the header): null when the socket may be made, after a stale one is removed
+ * (`said` is told), or the refusal. Fails closed: a fact it cannot read refuses.
+ */
+export async function prepareUiSocket(file, said, uid = process.getuid()) {
+    const folder = ownFolderProblem(file, "socket", uid);
+    if (folder !== null)
+        return refused(file, folder.problem, folder.fix);
+    let f;
+    try {
+        f = fs.lstatSync(file);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        return refused(file, `it cannot be read: ${e.message}`, "name another path");
+    }
+    const notMine = "remove it yourself if it is not needed, or name another path";
+    if (f.isSymbolicLink())
+        return refused(file, "it is a symbolic link, and Mason never replaces one", notMine);
+    if (!f.isSocket())
+        return refused(file, `it is ${f.isDirectory() ? "a folder" : "a file"}, not a socket, and Mason removes only a socket a run of its own left`, notMine);
+    if (f.uid !== uid)
+        return refused(file, `it is a socket of uid ${f.uid}, not of Mason's user (uid ${uid})`, notMine);
+    const live = await answers(file);
+    if (live === true)
+        return refused(file, "a process answers on it: another Mason, or something else, serves it now", "stop that process, or name another path");
+    if (live instanceof Error)
+        return refused(file, `whether a process answers on it could not be told (${live.message})`, notMine);
+    try {
+        fs.unlinkSync(file);
+    }
+    catch (e) {
+        return refused(file, `the stale socket could not be removed: ${e.message}`, notMine);
+    }
+    said(`replaced the socket a run that did not stop left at ${file}`);
+    return null;
+}
+/**
+ * Listens on `file` (`prepareUiSocket` first) with mode 0600 from the moment it exists (the umask around the bind),
+ * checked after. Until `attach`, a request is answered 503, as /healthz says starting; then each one is the run's
+ * server's own request, behind its guard.
+ */
+export async function listenOnUiSocket(file, said, uid = process.getuid()) {
+    let run = null;
+    const server = http.createServer((req, res) => {
+        if (run !== null) {
+            run.emit("request", req, res);
+            return;
+        }
+        res.writeHead(503, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" }).end("Mason is starting: the page answers once it does\n");
+    });
+    const before = process.umask(0o177);
+    let listening;
+    try {
+        listening = new Promise((resolve) => { server.once("error", resolve); server.listen(file, () => resolve(null)); });
+    }
+    finally {
+        process.umask(before);
+    }
+    const err = await listening;
+    if (err !== null)
+        return refused(file, `the socket cannot be made: ${err.message}`, "name a path in a folder only Mason's user can write");
+    let made;
+    try {
+        fs.chmodSync(file, 0o600);
+        made = fs.lstatSync(file);
+    }
+    catch (e) {
+        server.close();
+        return refused(file, `the socket's mode cannot be set: ${e.message}`, "name a path in a folder only Mason's user can write");
+    }
+    if (!made.isSocket() || made.uid !== uid || (made.mode & 0o777) !== 0o600) {
+        server.close();
+        return refused(file, `the socket is not Mason's alone once made (mode ${octal(made.mode)}, uid ${made.uid})`, "name a path in a folder only Mason's user can write");
+    }
+    let closed = false;
+    return {
+        file,
+        attach: (r) => { run = r; },
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            server.close();
+            server.closeAllConnections();
+            // the listening socket is unlinked as it closes; whatever is still at the path is removed only when it is this one
+            try {
+                const now = fs.lstatSync(file);
+                if (now.isSocket() && now.ino === made.ino && now.dev === made.dev)
+                    fs.unlinkSync(file);
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    said(`the web page's socket ${file} could not be removed: ${e.message}`);
+                return;
+            }
+            said(`removed the web page's socket ${file}`);
+        },
+    };
+}

package/dist/src/web/app.css

@@ -497,6 +497,11 @@ table.catalog tbody tr:hover > td.act { background: var(--hover); }
 tr.removed > * { color: var(--muted); }
 form.formcard { margin: 0 0 var(--space-5); padding: var(--space-3) var(--space-4); background: var(--surface); border: 1px solid var(--frame); border-radius: var(--radius-lg); box-shadow: var(--drop); }
 form.formcard input { width: 18em; }
+/* the Users form's Role: its label and select wrap together on a phone, the select shrinking to the card (a long role's
+   name cut in the closed box, whole in the open list), so the page never scrolls sideways */
+#add-user .role-field { display: inline-flex; align-items: center; gap: var(--space-2); max-width: 100%; min-width: 0; vertical-align: middle; }
+#add-user .role-field label { flex: none; }
+#add-user .role-field select { flex: 0 1 auto; min-width: 0; max-width: 100%; text-overflow: ellipsis; }
 /* ---------------------------------------------------------------- Connect: the URL, its psql line, Create a user */
 /* a box whose title sits on its top edge, as a fieldset's legend does (Connect, Getting started, a chart's name) */
 .connect { background: var(--surface); border: 1px solid var(--frame); border-radius: var(--radius-lg); box-shadow: var(--drop); padding: var(--space-4) var(--space-5); margin: var(--space-6) 0 var(--space-6); }

package/dist/src/web/app.js

@@ -62,7 +62,7 @@ import { page as usagePage } from "./pages/usage.js";
 import { page as syncsPage } from "./pages/syncs.js";
 
 /** What the shell itself reads when the page shown does not: the state (the sidebar's project, badge and version). */
-const SHELL_STATE = { path: "/api/state", everyMs: 60_000 };
+const SHELL_STATE = { path: "api/state", everyMs: 60_000 };
 
 /** A text that moves with the clock (an age, a running time), and a part's HTML without them: `paint` sets those
  *  texts in place when nothing else changed. */
@@ -76,7 +76,7 @@ export const PRESS_HOLD_MS = 2000;
 export * from "./shared.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 { renderUsers, renderAdded, renderAddUser, attributesText } from "./pages/users.js";
 export { renderRequests } from "./pages/queries.js";
 export { renderRunning, renderSessions, renderClients, renderSlowest, queriesHref } from "./pages/usage.js";
 
@@ -182,7 +182,7 @@ export function createApp(fetchFn, now = () => new Date(), shown = "status") {
   // 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;
+    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 };
@@ -236,7 +236,7 @@ export function createApp(fetchFn, now = () => new Date(), shown = "status") {
       afterRead();
     },
     view() {
-      const st = store.get("/api/state")?.body;
+      const st = store.get("api/state")?.body;
       return {
         nav: renderNav(m.shown, m.range),
         // the range control in the shown view's header row (each group page's own slot; the others empty)

package/dist/src/web/index.html

@@ -7,9 +7,9 @@
 <!-- no favicon request: an empty one, inline (img-src allows data:) -->
 <link rel="icon" href="data:,">
 <!-- every file Mason's own, from its allowlist (src/cli/run-server.ts PAGE_ROUTES): the fonts are app.css's, vendored -->
-<link rel="stylesheet" href="/app.css">
-<link rel="stylesheet" href="/vendor/uplot-1.6.32/uPlot.min.css">
-<script type="module" src="/app.js"></script>
+<link rel="stylesheet" href="app.css">
+<link rel="stylesheet" href="vendor/uplot-1.6.32/uPlot.min.css">
+<script type="module" src="app.js"></script>
 </head>
 <body>
 <!-- the shell (src/web/app.js): the sidebar — the project, the nav, when it was updated and the version — and the page
@@ -69,11 +69,8 @@
   </section>
   <section id="page-users" aria-labelledby="users-h" hidden>
     <div class="page-head"><h2 id="users-h">Users</h2><p class="desc">A user is the name and password psql, a BI tool or your app connects to Mason with; it does not expire. The same users as <code>mason user</code>.</p></div>
-    <form id="add-user" class="formcard" autocomplete="off">
-      <label for="user-name">Name</label>
-      <input id="user-name" name="name" required placeholder="metabase" spellcheck="false" autocapitalize="off">
-      <button type="submit" class="primary">Add a user</button>
-    </form>
+    <!-- the add form is the page's (src/web/pages/users.js renderAddUser): none on a read-only page -->
+    <div id="add-user-box"></div>
     <div id="action"></div>
     <div id="added"></div>
     <div id="users-connect"></div>

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

@@ -14,7 +14,7 @@
 import { msText, agoText, bytesText, esc, firstLine, n, empty, renderFailure, rowsHtml, utcText, utcMsText, details, createOpenSet, status,
   clip, capped, TITLE_MAX, sortTh, sortedBy, nextSort, RANGES, DEFAULT_RANGE, clientText, renderConnect, copyClick, UNLISTED_STATEMENTS, statementCell, rangeEvery } from "../shared.js";
 
-const STATE = "/api/state";
+const STATE = "api/state";
 const NEWEST_EVERY_MS = 5000;
 /** The newest page while a search is set: a search reads every statement's text of the range (7 days of a busy log,
  *  ~0.6 s a read), so it is read every 30 s, not 5 — said under the log (SEARCH_NOTE). */
@@ -103,7 +103,7 @@ export function requestsPath(filters, before, range = DEFAULT_RANGE) {
   if (filters.slow) p.set("slow", "1");
   if (filters.search) p.set("search", filters.search);
   if (before) p.set("before", before);
-  return `/api/requests?${p.toString()}`;
+  return `api/requests?${p.toString()}`;
 }
 
 export const page = {
@@ -156,7 +156,7 @@ export const page = {
         const s = ctx.read(STATE)?.body;
         return {
           "request-log": (log?.failure ? renderFailure(log.failure) : "") + (log?.body ? renderRequests(log.body, { paged: m.before !== null, filtered: filtered(), isOpen: opened.has, now: ctx.now().getTime(), sort: m.sort,
-            span: m.filters.since ? "" : (RANGES[ctx.range()] ?? RANGES[DEFAULT_RANGE]).span, connect: renderConnect(s?.postgres, { first: true, table: s?.tables?.find((t) => t.added && t.copy?.phase === "done")?.table ?? null }) }) : "") +
+            span: m.filters.since ? "" : (RANGES[ctx.range()] ?? RANGES[DEFAULT_RANGE]).span, connect: renderConnect(s?.postgres, { first: true, table: s?.tables?.find((t) => t.added && t.copy?.phase === "done")?.table ?? null, readOnly: s?.pageReadOnly ?? null }) }) : "") +
             (log?.body && m.filters.search && m.before === null ? `<p class="dim refresh-note">${esc(SEARCH_NOTE)}</p>` : ""),
         };
       },

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

@@ -21,7 +21,7 @@ const LINKS = { tables: "#tables", failedTables: "#tables?show=failed", usage: "
   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,
-  badge, button, copyable, pop, renderFailure, json } from "../shared.js";
+  badge, button, copyable, pop, renderFailure, json, readOnlyLine } 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). */
@@ -289,6 +289,8 @@ export function renderFacts(s, now = Date.now()) {
   const d = s.disk;
   rows.push(...diskRows(d).map(([k, v]) => factRow(k, v, d.freeBytes === null || (d.projectedBytes !== null && d.projectedBytes > d.freeBytes))));
   rows.push(...sessionsRows(s.sessions).map(([k, v]) => factRow(k, v)));
+  // `pageSocket` (mason serve with MASON_UI_SOCKET): said without its path, as the page shows no absolute path
+  if (typeof s.pageSocket === "string") rows.push(factRow("Web page", "served on a Unix socket on the server too (MASON_UI_SOCKET)"));
   return `<table class="facts-table"><caption>Mason</caption><tbody>${rows.join("")}</tbody></table>`;
 }
 
@@ -398,10 +400,12 @@ export function renderChecklist(s, queries, users) {
   const answered = queries.queries.week.completed > 0;
   if (copied && user && answered) return "";
   const copying = added && !copied && copyingCount(s) > 0;
+  // a read-only page (MASON_UI_READ_ONLY=1) sends no one to add what it would refuse to add
+  const looks = (s.pageReadOnly ?? null) !== null;
   const steps = [
     ["Mason is running", true, ""],
-    ["A table synced", copied, copying ? `<span class="dim">syncing now</span>` : added ? "" : `<a class="btn small primary" href="${LINKS.tables}">Add a table</a>`],
-    ["A user created", user, `<a class="btn small${copied ? " primary" : ""}" href="#users">Create a user</a>`],
+    ["A table synced", copied, copying ? `<span class="dim">syncing now</span>` : added || looks ? "" : `<a class="btn small primary" href="${LINKS.tables}">Add a table</a>`],
+    ["A user created", user, looks ? "" : `<a class="btn small${copied ? " primary" : ""}" href="#users">Create a user</a>`],
     // the psql line is Connect's (rendered under the checklist once a table is added): its Copy copies it
     ["A first statement answered", answered, copied ? `${`<button type="button" class="small${user ? " primary" : ""}" data-copy="connect-psql">Copy the psql line</button>`} <span class="dim">then run a select on a synced table</span>` : ""],
   ];
@@ -423,8 +427,9 @@ export function renderStatus(s, o = {}) {
   // 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, 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) +
+    share: renderShare(s, o.share ?? NO_SHARE, now), readOnly: s.pageReadOnly ?? null }) : "";
+  // a read-only page (MASON_UI_READ_ONLY=1): why it offers no share, no user and no table to add, as Tables and Users say it
+  return readOnlyLine("Nothing is shared, added or created", s.pageReadOnly) + 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) : "");
 }
 
@@ -446,7 +451,8 @@ const endsLine = (endsAt, now) => endsAt === null || endsAt === undefined ? "It
  * 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 "";
+  // a server's run has no share to open, and a read-only page (MASON_UI_READ_ONLY=1) opens nothing
+  if (s?.served === true || (s?.pageReadOnly ?? null) !== null) 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" });
@@ -483,7 +489,7 @@ export const UNSUPPORTED_LIMIT = 100;
 
 /** What the page reads every 30 s beside the state: the request log's summary, the recent errors, and the last day's
  *  unsupported SQL. */
-const SLOWER = ["/api/queries", `/api/events?failed=1&limit=${RECENT_ERRORS}`, `/api/requests?failed=1&limit=${RECENT_ERRORS}`, `/api/unsupported?limit=${UNSUPPORTED_LIMIT}`, "/api/users"];
+const SLOWER = ["api/queries", `api/events?failed=1&limit=${RECENT_ERRORS}`, `api/requests?failed=1&limit=${RECENT_ERRORS}`, `api/unsupported?limit=${UNSUPPORTED_LIMIT}`, "api/users"];
 
 /** A read as `renderStatus` takes it: the body, or `{ failure }` when it could not be read; undefined before any read. */
 const asRequest = (r) => r === undefined ? undefined : r.failure ? { failure: r.failure } : r.body;
@@ -499,12 +505,12 @@ export const page = {
     const share = createShare(ctx);
     return {
       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 }],
+      reads: () => [{ path: "api/state", everyMs: POLL_MS }, ...SLOWER.map((path) => ({ path, everyMs: 30_000 })), { path: HOURLY, everyMs: 60_000 }],
       actions: share.actions,
-      afterRead: () => share.afterRead(ctx.read("/api/state")?.body),
+      afterRead: () => share.afterRead(ctx.read("api/state")?.body),
       input: (target) => share.input(target),
       view() {
-        const st = ctx.read("/api/state");
+        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, share: share.m }) };
@@ -535,8 +541,8 @@ export function createShare(ctx) {
   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 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;
@@ -547,7 +553,7 @@ export function createShare(ctx) {
     /** 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");
+      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;
@@ -561,17 +567,17 @@ export function createShare(ctx) {
       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 } : {}) }));
+      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"]);
+      await ctx.refresh(["api/state"]);
     },
     async shareStop(user) {
-      const r = await ctx.ask(`/api/share/${encodeURIComponent(user)}`, json("DELETE"));
+      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"]);
+      await ctx.refresh(["api/state"]);
     },
     shareBeat: beat,
   };

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

@@ -15,9 +15,9 @@ import { esc, agoText, utcText, badge, empty, panel, n, sortTh, nextSort, moreRo
 const EVENTS_LIMIT = 500;
 const EVENTS_SHOWN = 100;
 /** The events of a range: the newest EVENTS_LIMIT since its start. */
-const eventsPath = (range = DEFAULT_RANGE) => `/api/events?limit=${EVENTS_LIMIT}&since=${RANGES[rangeOf(range)].since}`;
-const LOGS = "/api/logs?lines=200";
-const STATE = "/api/state";
+const eventsPath = (range = DEFAULT_RANGE) => `api/events?limit=${EVENTS_LIMIT}&since=${RANGES[rangeOf(range)].since}`;
+const LOGS = "api/logs?lines=200";
+const STATE = "api/state";
 
 const th = (cols) => cols.map((c) => `<th scope="col">${esc(c)}</th>`).join("");
 

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

@@ -10,18 +10,18 @@
  * `copySizes` every minute; a table's columns once, when its Columns… or Name its key… form opens
  * (`GET /api/tables/<table>/columns`, `columnsPath`).
  */
-import { msText, bytesText, button, card, cards, code, createOpenSet, moreRows, details, empty, entryName, esc, fileSize, firstLine, json, n, panel, renderFailure, rowsHtml, spanText, duration, status, streamRows, utcText, pop, fresh, actId, ROOMS, POLL_MS } from "../shared.js";
+import { msText, bytesText, button, card, cards, code, createOpenSet, moreRows, details, empty, entryName, esc, fileSize, firstLine, json, n, panel, renderFailure, rowsHtml, spanText, duration, status, streamRows, utcText, pop, fresh, actId, ROOMS, POLL_MS, readOnlyLine } from "../shared.js";
 import { copyBar, copyingCount, createMonotone, tableLine } from "./status.js";
 
 /** `/api/usage` asked for the copies' own sizes alone: the last minute's samples (none needed), and `copySizes`. */
-const SIZES_PATH = "/api/usage?since=1m";
+const SIZES_PATH = "api/usage?since=1m";
 
 /** Where one table's columns are read, when its form opens (src/cli/run-server.ts tableColumns): never with the state,
  *  which is polled every 2 s and would carry every table's (3.4 MB at 800 tables of 50 columns). */
 /** A table's sync events: Observability › Sync events narrowed to it (src/web/pages/syncs.js `route`), over the week (its
  *  copy and failures are rarely in the last 15 minutes, Now's). */
 export const syncsHref = (table) => `#observability/syncs?table=${encodeURIComponent(table)}&range=7d`;
-export const columnsPath = (table) => `/api/tables/${encodeURIComponent(table)}/columns`;
+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", behind: "Behind", failed: "Failed", waiting: "Waiting" };
@@ -199,8 +199,10 @@ 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;
+  // why the page changes nothing (MASON_UI_READ_ONLY=1: not even a Sync), or null
+  const viewOnly = s.pageReadOnly ?? null;
+  // why no table can be added or removed from here (that, or a server's sources file this run cannot write), or null
+  const readOnly = viewOnly ?? 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,7 @@ export function renderTables(s, ui = {}) {
       // Sync now → Syncing… → Synced ✓ in the one room (ROOMS.sync), so the actions never move
       // View events: its sync events, on Observability › Sync events (a link: it goes to another page)
       ? `<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 })) + " " +
+        (viewOnly ? "" : 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
         (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
@@ -288,7 +290,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 + (readOnly === null ? "" : `<p class="count">Tables are not added or removed from this page: ${esc(readOnly)}.</p>`) +
+  return stray + (viewOnly !== null ? readOnlyLine("Tables are not added, removed or synced", viewOnly)
+    : 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) +
@@ -301,7 +304,7 @@ export const page = {
   title: "Tables",
   create(ctx) {
     const m = { removing: null, choosing: null, columns: null, outcome: null, ticked: null, held: null, heldFilter: null, heldShow: null, filter: "", show: "all", syncing: [], adding: [], synced: null, limit: TABLE_ROWS };
-    const state = () => ctx.read("/api/state")?.body ?? null;
+    const state = () => ctx.read("api/state")?.body ?? null;
     const monotone = createMonotone();
     // the details open (a copy's whole error), by key: a poll rewrites the part, and they stay open
     const opened = createOpenSet();
@@ -325,12 +328,12 @@ export const page = {
         // from the click: the row says Adding… (the page paints before the answer), then the state read again shows the copy
         m.adding = [...m.adding, table];
         if (m.choosing !== table) { m.outcome = null; m.synced = null; }
-        const r = await ctx.ask("/api/pick", json("POST", pickBody(table, columns, key)));
+        const r = await ctx.ask("api/pick", json("POST", pickBody(table, columns, key)));
         m.adding = m.adding.filter((x) => x !== table);
         // refused: said over the form, in its popover, written again with the boxes the person had ticked
         if ("failure" in r) { m.outcome = { table, failure: r.failure }; if (m.choosing === table) m.ticked = { columns, key }; return false; }
         m.outcome = { table, added: r.body, at: ctx.now().getTime() }; m.choosing = null; m.columns = null; hold();
-        await ctx.refresh(["/api/state"]);
+        await ctx.refresh(["api/state"]);
         return true;
       },
       /** Open a table's form: its columns read now, once (the state the page polls carries none). */
@@ -348,11 +351,11 @@ export const page = {
       cancelRemoveTable() { m.removing = null; hold(); },
       /** Remove a table (`mason remove`), once asked: the answer beside its actions, then the state read again. */
       async confirmRemoveTable(table) {
-        const r = await ctx.ask("/api/remove", json("POST", { tables: [table] }));
+        const r = await ctx.ask("api/remove", json("POST", { tables: [table] }));
         m.removing = null; hold();
         if ("failure" in r) { m.outcome = { table, failure: r.failure }; return false; }
         m.outcome = { table, removed: r.body, at: ctx.now().getTime() };
-        await ctx.refresh(["/api/state"]);
+        await ctx.refresh(["api/state"]);
         return true;
       },
       dismissOutcome() { m.outcome = null; },
@@ -360,10 +363,10 @@ export const page = {
       async syncTable(table) {
         m.syncing = [...m.syncing, table];
         m.outcome = null; m.synced = null;
-        const r = await ctx.ask("/api/sync", json("POST", { tables: [table] }));
+        const r = await ctx.ask("api/sync", json("POST", { tables: [table] }));
         m.syncing = m.syncing.filter((x) => x !== table);
         m.synced = "failure" in r ? { table, failure: r.failure } : { table, synced: r.body, at: ctx.now().getTime() };
-        await ctx.refresh(["/api/state"]);
+        await ctx.refresh(["api/state"]);
         return !("failure" in r);
       },
       dismissSynced() { m.synced = null; },
@@ -377,7 +380,7 @@ export const page = {
     };
     return {
       model: m,
-      reads: () => [{ path: "/api/state", everyMs: POLL_MS }, { path: SIZES_PATH, everyMs: 60_000 }],
+      reads: () => [{ path: "api/state", everyMs: POLL_MS }, { path: SIZES_PATH, everyMs: 60_000 }],
       afterRead() {
         const s = state();
         if (s === null) return;