@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/ui.js

@@ -2,23 +2,40 @@
  * `mason ui` — THE WEB PAGE OF THE RUNNING MASON, IN THE BROWSER (src/web/, docs/WEB-UI.md): the Overview (what `mason
  * status` says), the Tables (`mason tables`, `add`, `remove`, `sync`), the Users (`mason user`) and Observability (`mason
  * logs`, `mason usage`), refreshed while the tab is seen. It prints the page's URL WITH the run's token (src/cli/security.ts: the first request trades it for an HttpOnly cookie and is redirected to a URL without
- * it) and opens the browser. The reader is the person at this terminal, whom `mason user add` already shows a
+ * it) and opens the browser when its stdout is a terminal (as `mason login` does: a pipe, a file or an agent's shell has
+ * no one at a browser, so it gets the address alone). The reader is the person at this terminal, whom `mason user add` already shows a
  * password once; the token is never written anywhere else — not in `mason start`'s output (its log is a file), not in
  * `mason status`, which prints the URL without it.
  *
  * Before it prints anything it ASKS the page (`GET /` with the run's token as the commands send it), so a run that serves
- * none (`mason serve`'s, or one from before the page) is said, never a URL that answers 404.
+ * none (one from before the page) is said, never a URL that answers 404.
+ *
+ * `--ssh <user@server>` (src/cli/ui-ssh.ts, docs/WEB-UI.md "On a server") opens a server's page from this machine, through
+ * the machine's own ssh, and stays in the foreground until Ctrl-C, as `mason share` does; it needs no project here. Its
+ * URL carries a ticket for one use, never the run's token, which stays on the server. `--bridge` is what it runs there.
+ *
+ * `--replica <org>/<name>` (else `MASON_REPLICA`; src/cli/ui-hosted.ts, docs/HOSTED-API.md "A replica's page") opens a
+ * replica's page on a hosted Mason service: one request, whose one-use address is opened as this command opens a run's.
  */
 import { spawn } from "node:child_process";
 import { failed, jsonText, parseCommand, reportText } from "./command.js";
 import { reach } from "./state.js";
+import { bridge, openSshTunnel, targetProblem } from "./ui-ssh.js";
+import { version } from "./version.js";
 import { RunUnreachable } from "./control.js";
+import { parseDuration } from "../lib/table-sync.js";
+import { replicaOf } from "./replica.js";
+import { hostedUi } from "./ui-hosted.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
+const say = (m) => { process.stderr.write(`${m}\n`); };
+const DEFAULT_TIMEOUT_S = 60;
 export const UI = {
     needs: "run",
     name: "ui",
     summary: "the status, tables, users and statements, in your browser",
     usage: `usage: mason ui [--no-open] [--json]
+       mason ui --ssh <user@server> [--mason <command>] [--timeout <duration>] [--no-open] [--json]
+       mason ui --replica <org>/<name> [--no-open] [--json]
 
   Opens the running Mason's web page in your browser, refreshed while the tab is open: the Overview (what mason status
   says: whether the synced data is ready, the database, the sync, the statements and the recent errors); the Tables (add,
@@ -26,20 +43,51 @@ export const UI = {
   the URL to paste, or remove one); and Observability: the statements running and that ran (mason logs --requests,
   cancel one), usage over time (mason usage), and the sync's events (mason logs --events).
 
-  The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
-  bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
-  token, so after a restart run mason ui again. The page is mason start's: mason serve serves none (off this
-  machine it would need TLS and a login).
-
     mason ui
     mason ui --no-open        print the URL, open no browser
     mason ui --json
+    mason ui --ssh deploy@mason.example.com
+    mason ui --ssh deploy@mason.example.com --mason "docker exec -i mason-mason-1 mason"
+    mason ui --ssh deploy@mason.example.com --mason "cd /var/lib/mason && mason" --timeout 120 --no-open
+    mason ui --replica acme/shop     a replica's page on a hosted Mason service
+    mason ui --bridge --local-port 51000      what --ssh runs on the server; its stdout is a stream, not for reading
+
+  --no-open            print the URL only (as when its output is not a terminal: a browser opens only for one)
+  --ssh <target>       the server, as you give it to ssh: user@server, or a Host of your ssh config
+  --mason <command>    how to run mason on the server (default mason); a shell's text, kept to ssh's command line
+  --timeout <duration> how long ssh and the server have to answer (default ${DEFAULT_TIMEOUT_S}s; a bare number is seconds;
+                       2m): a passphrase or a touch counts; past it, exit 124
+  --bridge             the server's end of --ssh, on stdin and stdout
+  --local-port <n>     the port the browser names, for --bridge: the laptop's
+  --replica <org>/<name> a replica on a hosted Mason service, as the service lists it
+  --json               as data: its shape is at the end
 
-  --no-open   print the URL only
-  --json      as data: { url (with this run's token), port }, next; it never opens a browser
+  The URL carries this run's token: the page trades it for a cookie at once and drops it from the address
+  bar. It is printed for you alone, like a user's password: paste it nowhere else. Every mason start makes a new
+  token, so after a restart run mason ui again.
+
+  --ssh opens a server's page (mason serve's) from this machine, with nothing public: it runs your ssh, so your
+  ~/.ssh/config, keys and SSO apply, starts mason there, and forwards a free local port to the page, which listens on the
+  server's loopback alone. It stays in the foreground: Ctrl-C closes the tunnel. It needs no project here. Its URL
+  carries a ticket for one use, never the run's token, which stays on the server. The server's Mason must be this
+  version or close to it, and must be a command ssh can run: --mason says how, for a container or a folder.
+
+  --replica opens the page of a replica on a hosted Mason service (else MASON_REPLICA, unless --ssh or --bridge names
+  the target), for the organisation's owner alone: the service answers an address that opens it once, for a few
+  minutes. The page is read-only: the service refuses changes through it, so add or remove users with mason user …
+  --replica. It needs no project here, and goes with --no-open and --json alone. Opened in your browser, the address is
+  not printed: run it again for another tab. A replica not ready yet is said, with when to try again.
+
+  The --json answer: { url (with this run's token; with --ssh a ticket for one use; null when Ctrl-C came
+    before the server answered, as port is, exit 0; with --replica the one-use address), port, server,
+    project, version (with --ssh: the server's Mason, for what its answer may lack), replica
+    (with --replica: "<org>/<name>"), expiresAt (with --replica: until when the address opens it)
+    }, next; it never opens a
+    browser. With --ssh it then holds the tunnel: the end is on stderr, exit 0 for Ctrl-C or SIGTERM, 1 otherwise
 `,
-    options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false } },
-    json: ["url", "port", "next"],
+    options: { "no-open": { type: "boolean", default: false }, json: { type: "boolean", default: false }, ssh: { type: "string" }, mason: { type: "string" },
+        timeout: { type: "string" }, bridge: { type: "boolean", default: false }, "local-port": { type: "string" }, replica: { type: "string" } },
+    json: ["url", "port", "server", "project", "version", "replica", "expiresAt", "next"],
 };
 const NEXT = [["mason status", "the same, in this terminal"], ["mason user list", "the users"]];
 /** The command that opens a URL in the person's browser, by platform (macOS `open`, Windows `start`, else `xdg-open`). */
@@ -51,8 +99,11 @@ export function openCommand(platform, url) {
         return ["cmd", ["/c", "start", "", url]];
     return ["xdg-open", [url]];
 }
+/** An address Mason hands the browser by itself (a sign-in page, a replica's page): a plain https (or this machine's
+ *  http) URL, and none of the characters a shell or `cmd /c start` reads (the service's URL is not ours). */
+export const OPENABLE = /^https?:\/\/[A-Za-z0-9.:[\]-]+(?:\/[A-Za-z0-9._~/?=+-]*)?$/;
 /** Open `url` in the browser: null once the opener started, else why it could not (the URL is printed either way). */
-function openBrowser(url) {
+export function openBrowser(url) {
     const [command, args] = openCommand(process.platform, url);
     return new Promise((resolve) => {
         const child = spawn(command, args, { detached: true, stdio: "ignore" });
@@ -60,6 +111,9 @@ function openBrowser(url) {
         child.once("spawn", () => { child.unref(); resolve(null); });
     });
 }
+/** Whether to open a browser: asked for (no --no-open) and stdout a terminal, a person in front of it (never a pipe,
+ *  a file or a coding agent's shell, which get the address alone). */
+const opens = (noOpen) => !noOpen && process.stdout.isTTY === true;
 /** Whether the run serves the page: its `GET /` answered, with the token the commands send. */
 async function servesPage(run) {
     let res;
@@ -72,21 +126,111 @@ async function servesPage(run) {
     await res.arrayBuffer();
     return res.status === 200 && /^text\/html/.test(res.headers.get("content-type") ?? "");
 }
+/**
+ * THE PAGE OF A SERVER (the header): the tunnel, the URL once, and held until Ctrl-C or until it drops. As `mason share`:
+ * what `--json` prints is one object, once, and everything after it is on stderr, so stdout stays one document. The
+ * signals are heard before ssh starts: a Ctrl-C at a passphrase ends both.
+ */
+async function overSsh(target, mason, timeoutMs, open, json) {
+    let signalled = null;
+    const signal = new Promise((resolve) => {
+        const heard = (s) => { signalled = s; resolve(s); };
+        process.once("SIGINT", heard);
+        process.once("SIGTERM", heard);
+    });
+    const t = await openSshTunnel({ target, mason, timeoutMs, interactive: !json && process.stdin.isTTY === true, stopped: signal });
+    const next = [[`mason ui --ssh ${target}`, "again, once this one is closed: a new port and a new ticket"]];
+    if ("message" in t) {
+        if (signalled === null)
+            return failed("ui", t, { json });
+        // stopped on purpose, exit 0: under --json still the one object every answer is, its url null as nothing opened
+        if (json)
+            out(jsonText(UI, { url: null, port: null, server: target }, next));
+        else
+            say(`stopped before ${target} answered: nothing was left open`);
+        return 0;
+    }
+    if (json)
+        out(jsonText(UI, { url: t.url, port: t.port, server: target, project: t.project, version: t.serverVersion }, next));
+    else {
+        const couldNot = open ? await openBrowser(t.url) : null;
+        out(reportText({
+            headline: open && couldNot === null ? `${t.project} on ${target}, opened in your browser` : `${t.project} on ${target}`,
+            details: [["url", t.url], ["server", target], ["project", t.project], ["version", t.serverVersion]],
+            tips: [
+                ...(couldNot !== null ? [`Could not open a browser (${couldNot}): open the URL yourself.`] : []),
+                ...(t.serverVersion !== version() ? [`This machine's Mason is ${version()}: the page is the server's.`] : []),
+                "The URL carries a ticket for one use, and works for 5 minutes. Ctrl-C closes the tunnel.",
+            ],
+            next,
+        }));
+    }
+    const how = await Promise.race([signal.then((s) => ({ signal: s })), t.ended.then((why) => ({ why }))]);
+    if ("signal" in how) {
+        await t.stop();
+        say(`the tunnel to ${target} is closed`);
+        return 0;
+    }
+    return failed("ui", { message: `the tunnel to ${target} dropped`, code: "failed", why: how.why, fix: "is the server up, and this machine online? The page in your browser stops answering until a new tunnel opens one", next }, { json: false });
+}
 export async function ui(argv) {
     const f = parseCommand(UI, argv);
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
+    const v = f.values;
+    const wrong = (message) => failed("ui", { message, code: "usage", usage: UI.usage }, { json });
     if (f.positionals.length)
-        return failed("ui", { message: `mason ui takes no argument: ${f.positionals.join(" ")}`, code: "usage", usage: UI.usage }, { json });
+        return wrong(`mason ui takes no argument: ${f.positionals.join(" ")}`);
+    if (v.replica !== undefined) {
+        const beside = [["--ssh", v.ssh !== undefined], ["--bridge", v.bridge], ["--mason", v.mason !== undefined], ["--timeout", v.timeout !== undefined],
+            ["--local-port", v["local-port"] !== undefined]].filter(([, given]) => given).map(([name]) => name);
+        if (beside.length)
+            return wrong(`--replica opens a hosted replica's page: it goes with --no-open and --json alone, not ${beside.join(", ")}`);
+    }
+    if (v.bridge) {
+        if (v.ssh !== undefined || v.mason !== undefined || v.timeout !== undefined || json)
+            return wrong("--bridge is mason ui --ssh's own end on the server: it goes with --local-port alone");
+        const port = Number(v["local-port"]);
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+            return wrong(`--bridge needs --local-port, a port number, not ${JSON.stringify(v["local-port"] ?? "")}`);
+        return bridge(port);
+    }
+    if (v["local-port"] !== undefined)
+        return wrong("--local-port goes with --bridge");
+    if (v.ssh === undefined && (v.mason !== undefined || v.timeout !== undefined))
+        return wrong(`${v.mason !== undefined ? "--mason" : "--timeout"} goes with --ssh <user@server>`);
+    if (v.ssh !== undefined) {
+        const problem = targetProblem(v.ssh);
+        if (problem !== null)
+            return wrong(`--ssh: ${problem}`);
+        if (v.mason !== undefined && (v.mason.trim() === "" || /[\r\n]/.test(v.mason)))
+            return wrong("--mason is one line of shell that runs mason on the server");
+        const read = parseDuration(v.timeout ?? String(DEFAULT_TIMEOUT_S));
+        if ("problem" in read)
+            return wrong(`--timeout ${read.problem}`);
+        const seconds = read.seconds;
+        return overSsh(v.ssh, v.mason ?? "mason", seconds * 1000, opens(v["no-open"]), json);
+    }
+    // a replica on a hosted service (--replica, else MASON_REPLICA): --ssh and --bridge name their own target, above
+    const replica = replicaOf(v.replica, UI.usage);
+    if (replica !== null && "message" in replica)
+        return failed("ui", replica, { json });
+    if (replica !== null)
+        return hostedUi(replica, { open: opens(v["no-open"]), json });
     const w = await reach(UI, json);
     if (w === null || w.state !== "up")
         return 1;
     const run = w.run;
+    if (w.project.config.served === true) {
+        return failed("ui", { message: `Mason for ${run.name} runs on this server: its page is opened from your own machine`, code: "refused",
+            why: "the page listens on this machine's loopback alone, and a browser on a server has no one in front of it",
+            fix: "on your machine, mason ui --ssh <user@server> (mason ui --help: for a container, --mason)", next: [["mason status", "what it is doing, in this terminal"]] }, { json });
+    }
     if (!await servesPage(run)) {
         return failed("ui", { message: `Mason for ${run.name} serves no web page`, code: "refused",
-            why: "the page is mason start's: this is mason serve's run, or a run started by a Mason from before the page",
-            fix: "on your machine, mason stop && mason start runs it with the page; a server's Mason is read with mason status",
+            why: "this run was started by a Mason from before the page",
+            fix: "mason stop && mason start runs it with the page",
             next: [["mason status", "what it is doing, in this terminal"]] }, { json });
     }
     const url = `${run.control.url}/?token=${encodeURIComponent(run.control.token)}`;
@@ -95,8 +239,9 @@ export async function ui(argv) {
         out(jsonText(UI, { url, port }, NEXT));
         return 0;
     }
-    const couldNot = f.values["no-open"] === true ? null : await openBrowser(url);
-    const opened = f.values["no-open"] !== true && couldNot === null;
+    const open = opens(v["no-open"]);
+    const couldNot = open ? await openBrowser(url) : null;
+    const opened = open && couldNot === null;
     out(reportText({
         headline: opened ? `Mason's web page, opened in your browser` : `Mason's web page`,
         details: [["url", url], ["project", run.name]],

package/dist/src/cli/usage.js

@@ -12,9 +12,10 @@ import { fileSize, guarded, runFailure } from "./commands.js";
 import { timeOf } from "./request-filter.js";
 import { duration, msText } from "./readiness.js";
 import { SIZE_EVERY_MS } from "../duck/usage.js";
+import { parseDuration } from "../lib/table-sync.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const n = (x) => x.toLocaleString("en-US");
-export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>] [--step <span>] [--json]
+export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>] [--step <duration>] [--json]
 
   What Mason was and did over time, from a sample it takes every minute and keeps MASON_HISTORY_DAYS days
   (default 7): a line each span — the statements of the Postgres API (how many, how many were refused, failed or
@@ -29,15 +30,18 @@ export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>]
 
   --since <when>   from when: an age (90s, 30m, 6h, 7d) or an ISO 8601 date or time with its zone; default 1h
   --until <when>   until when, the same way; default now
-  --step <span>    a line per span (1m to the days kept; default 5m), or 0 for every sample as it was taken
-  --json           as data: { since, until, stepSeconds (null: every sample), sampleSeconds, keptDays, samples: [{ at
-                   (with a step, the span's start), seconds, copyBytes, copyRows, tablesAdded, tablesCopied,
-                   tablesFailed, oldestSyncSeconds, statements, statementsRefused, statementsFailed, statementsCancelled,
-                   rowsSent, bytesSent, durationP50Ms, durationP95Ms, streamLagBytes, streamLagSeconds, rssBytes,
-                   heapUsedBytes, copyMemoryBytes, copyMemoryLimitBytes, slotWalHeldBytes (replication: the WAL the
-                   slot holds on the database), diskFreeBytes (free where the synced data is; with a step, the lowest),
-                   sessionsOpen (the Postgres API's sessions logged in) }],
-                   copySizes: [{ table, bytes, at }], next }
+  --step <duration>  a line per span (1m to the days kept; default 5m; a bare number is seconds), or 0 for every
+                   sample as it was taken
+  --json           as data: its shape is at the end
+
+  The --json answer: { since, until, stepSeconds (null: every sample), sampleSeconds, keptDays, samples: [{ at
+    (with a step, the span's start), seconds, copyBytes, copyRows, tablesAdded, tablesCopied,
+    tablesFailed, oldestSyncSeconds, statements, statementsRefused, statementsFailed, statementsCancelled,
+    rowsSent, bytesSent, durationP50Ms, durationP95Ms, streamLagBytes, streamLagSeconds, rssBytes,
+    heapUsedBytes, copyMemoryBytes, copyMemoryLimitBytes, slotWalHeldBytes (replication: the WAL the
+    slot holds on the database), diskFreeBytes (free where the synced data is; with a step, the lowest),
+    sessionsOpen (the Postgres API's sessions logged in) }],
+    copySizes: [{ table, bytes, at }], next }
 `;
 export const USAGE = {
     needs: "run",
@@ -47,13 +51,13 @@ export const USAGE = {
     options: { since: { type: "string" }, until: { type: "string" }, step: { type: "string" }, json: { type: "boolean" } },
     json: ["since", "until", "stepSeconds", "sampleSeconds", "keptDays", "samples", "copySizes", "next"],
 };
-const UNIT = { s: 1, m: 60, h: 3600, d: 86_400 };
-/** A span as the options write it (90s, 30m, 6h, 7d; 0), in seconds, or null when it is not one. */
+/** A span as the options write it (the command line's one duration grammar, src/lib/table-sync.ts `parseDuration`:
+ *  90s, 30m, 6h, 7d, a bare number of seconds; 0 for every sample), in whole seconds, or null when it is not one. */
 export function spanSeconds(text) {
     if (text.trim() === "0")
         return 0;
-    const m = /^\s*(\d+)\s*([smhd])\s*$/.exec(text);
-    return m ? Number(m[1]) * UNIT[m[2]] : null;
+    const d = parseDuration(text, { zero: true });
+    return "problem" in d || !Number.isInteger(d.seconds) ? null : d.seconds;
 }
 /** One sample on one line: the time, the statements, those refused, failed or cancelled, p95, rows sent, the copy, its rows, the stalest copy, the lag, the memory. */
 export function sampleLine(s, withLag) {
@@ -87,7 +91,7 @@ export async function usage(argv, now = Date.now()) {
             return failed("usage", { ...t, usage: USAGE_USAGE }, { json });
     const step = spanSeconds(v.step ?? "5m");
     if (step === null)
-        return failed("usage", { message: `--step is a span (1m, 5m, 1h, 1d) or 0 for every sample, not ${JSON.stringify(v.step)}`, code: "usage", usage: USAGE_USAGE }, { json });
+        return failed("usage", { message: `--step is a duration (300, 1m, 5m, 1h, 1d: a bare number is seconds) or 0 for every sample, not ${JSON.stringify(v.step)}`, code: "usage", usage: USAGE_USAGE }, { json });
     const w = await reach(USAGE, json);
     if (w === null || !("run" in w))
         return 1;