@mason-data/cli 0.6.2 → 0.8.0

package/dist/src/cli/control.js

@@ -1,3 +1,9 @@
+/**
+ * THE COMMANDS' LINE TO A RUN: `mason status`, `mason tables`, `mason add` and `mason wait` ask the run's
+ * command server (src/cli/run-server.ts) — with the
+ * run's token as `Authorization: Bearer` (src/cli/security.ts), read from the project's .mason/config.json (src/cli/runs.ts).
+ */
+import * as http from "node:http";
 /** The run does not answer: a failure with the reason as `why` and mason logs as the way out (`failure` is what a command
  *  hands src/cli/command.ts failed). */
 export class RunUnreachable extends Error {
@@ -34,3 +40,56 @@ export async function callRun(run, method, route, body, timeoutMs = 30_000) {
     }
     return { status: res.status, body: parsed };
 }
+/**
+ * ONE REQUEST HELD OPEN (src/cli/share.ts): the run answers a line of JSON and keeps the answer open, so the end of the
+ * connection is the end of what was asked, however this process ends. On node:http, not fetch: fetch gives up on a body
+ * silent for five minutes, and here silence is the normal state. A refusal is answered whole, as `callRun` returns it.
+ */
+export function holdRun(run, route, body, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+        const unreachable = (why) => new RunUnreachable(`Mason for ${run.name} (pid ${run.pid}) does not answer at ${run.control.url}`, why);
+        const text = JSON.stringify(body);
+        const req = http.request(`${run.control.url}${route}`, { method: "POST", headers: { Authorization: `Bearer ${run.control.token}`, "Content-Type": "application/json", "Content-Length": Buffer.byteLength(text) } }, (res) => {
+            let got = "", first = null, said = null;
+            let finish = () => undefined;
+            const ended = new Promise((r) => { finish = r; });
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                got += chunk;
+                if (res.statusCode !== 200)
+                    return;
+                for (let at = got.indexOf("\n"); at >= 0; at = got.indexOf("\n")) {
+                    const line = JSON.parse(got.slice(0, at));
+                    got = got.slice(at + 1);
+                    if (first === null) {
+                        first = line;
+                        clearTimeout(timer);
+                        resolve({ first, ended, close: () => req.destroy() });
+                    }
+                    else if (typeof line.ended === "string")
+                        said = line.ended;
+                }
+            });
+            res.on("close", () => {
+                clearTimeout(timer);
+                if (res.statusCode === 200) {
+                    if (first === null)
+                        reject(unreachable("it closed the answer before it said anything"));
+                    finish(said);
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(got);
+                }
+                catch {
+                    parsed = { error: got.trim() || `HTTP ${res.statusCode}` };
+                }
+                resolve({ status: res.statusCode ?? 0, body: parsed });
+            });
+        });
+        const timer = setTimeout(() => { req.destroy(); reject(unreachable(`no answer in ${timeoutMs / 1000} s`)); }, timeoutMs);
+        req.on("error", (e) => { clearTimeout(timer); reject(unreachable(e.code ?? e.message)); });
+        req.end(text);
+    });
+}

package/dist/src/cli/demo.js

@@ -0,0 +1,158 @@
+/**
+ * THE DEMO PROJECT, THE CLI'S SIDE (`mason init demo`; the database itself is src/demo/source.ts): a project whose
+ * database is one Mason hosts itself — a Postgres in this process, persisted in `.mason/demo/`, served on a loopback
+ * port over the Postgres wire protocol and seeded with a small shop schema — so a person tries Mason with nothing to
+ * install. The project stays an ordinary one: its sources file names `url: ${DATABASE_URL}` and three of the four
+ * tables (the fourth, `DEMO_TABLE_TO_ADD`, is the person's to add), `.env` the demo's URL, and `mason start` reads it
+ * over the wire as it reads any Postgres, so the demo runs the read path production runs (docs/DESIGN.md "The demo
+ * database").
+ *
+ *   - THE PORT LIVES IN THE URL ALONE: `mason init demo` picks one free and writes it into `.env`; `mason start` reads
+ *     it back from the resolved URL (`demoPort`), never from a second record that could disagree with it.
+ *   - POLL ONLY: the demo database has no change log (no WAL sender), so a table whose `sync:` is `replication` is
+ *     refused before anything starts (`demoChangesRefusal`).
+ *   - A WRITER: every MASON_DEMO_CHANGE_MS (`demoSettings`) the run makes one round of changes (`demoChanges`), so the
+ *     copy is seen keeping current.
+ *
+ * The demo's module is imported when it is used (`demoModule`): a command that never hosts it never loads its database;
+ * its URL and names are src/demo/seed.ts's, which loads none.
+ */
+import * as path from "node:path";
+import { parseSource, isLocalHost } from "./preflight.js";
+import { entryName, replicatedEntries } from "./sources.js";
+import { heldText, portHolder } from "./ports.js";
+import { DEMO_DIR, STATE_DIR } from "./project.js";
+import { DEMO_DATABASE, DEMO_USER, demoUrl } from "../demo/seed.js";
+/** What `mason init` takes in the URL's place to make a demo project. */
+export const DEMO_ARG = "demo";
+/** The port `mason init demo` prefers for the demo database (the next free one when it is held): beside Mason's 5433. */
+export const DEMO_PORT = 5434;
+/** The demo database's tables (the seed's own list), the ones `mason init demo` adds to the sources file and the one it
+ *  leaves for the person to add, and its URL (src/demo/seed.ts: no PGlite is loaded by it, so `mason init demo` and
+ *  `demoPort` never load the database). */
+export { DEMO_ADDED_TABLES, DEMO_SYNC, DEMO_TABLES, DEMO_TABLE_TO_ADD, demoUrl } from "../demo/seed.js";
+/** How often the run changes the demo database by default (MASON_DEMO_CHANGE_MS). */
+export const DEMO_CHANGE_MS = 5000;
+const DEMO_CHANGE_MIN_MS = 100;
+/** The demo database's module (`DemoSource`, and PGlite with it), loaded when the run hosts it, never to build or read
+ *  its URL (src/demo/seed.ts has those). */
+export const demoModule = () => import("../demo/source.js");
+/** What the run reads of the demo from its environment: how often it changes the database. Throws on a value that is no
+ *  number of milliseconds, said with the way out (as src/duck/sync.ts copyParallelOf). */
+export function demoSettings(env) {
+    const v = env.MASON_DEMO_CHANGE_MS;
+    if (v === undefined || v === "")
+        return { changeMs: DEMO_CHANGE_MS };
+    const n = Number(v);
+    if (!/^\d+$/.test(v.trim()) || n < DEMO_CHANGE_MIN_MS) {
+        throw new Error(`MASON_DEMO_CHANGE_MS=${JSON.stringify(v)} is not a number of milliseconds: how often the demo database changes (a new order, an older one's status moved on); ` +
+            `set it to ${DEMO_CHANGE_MIN_MS} or more, or unset it for ${DEMO_CHANGE_MS}`);
+    }
+    return { changeMs: n };
+}
+/**
+ * THE DEMO DATABASE'S PORT, READ FROM THE URL THE SOURCES FILE RESOLVED (`from` says where: `DATABASE_URL in .env`) — or
+ * why that URL is not the demo's, with the way out: a host off this machine (the demo database listens on 127.0.0.1
+ * alone), or any other change to `postgres://demo@127.0.0.1:<port>/demo`. The port is the one fact that may differ.
+ */
+export function demoPort(url, from) {
+    const wayOut = "mason destroy and mason init demo again in a new folder, or put the URL back";
+    const parsed = parseSource(url);
+    if ("problem" in parsed)
+        return { problem: `${from} was changed: ${parsed.problem}. The demo database is postgres://${DEMO_USER}@127.0.0.1:<port>/${DEMO_DATABASE}; ${wayOut}` };
+    const s = parsed.source;
+    // loopback alone: the demo database listens on nothing else (0.0.0.0 or a container's host name is not it)
+    if (!isLocalHost(s.host) || s.host === "0.0.0.0" || s.host === "host.docker.internal") {
+        return { problem: `${from} names ${s.host}, which is not this machine's loopback: the demo database is hosted by mason start on 127.0.0.1 alone (${demoUrl(s.port)}); ${wayOut}` };
+    }
+    if (s.url !== demoUrl(s.port))
+        return { problem: `${from} was changed: the demo database is ${demoUrl(s.port)}; ${wayOut}` };
+    return { port: s.port };
+}
+/** The refusal of logical replication for a demo project (a table whose sync: is replication in its sources file,
+ *  `shown`, or the mode an older Mason recorded in the config, edited to it): before anything starts, with the way out;
+ *  null for any other project, or a demo one polled. */
+export function demoChangesRefusal(cfg, file = null, shown = "") {
+    if (cfg.demo !== true)
+        return null;
+    const streamed = file === null ? [] : replicatedEntries(file).map((e) => entryName(e.table));
+    if (streamed.length) {
+        return { message: `the demo database is read by polling only: sync: replication does not apply to it (${streamed.join(", ")})`, code: "refused",
+            why: "the demo database has no change log for logical replication to read; Mason polls it with SELECTs",
+            fix: `write sync: poll 5s for ${streamed.length === 1 ? "it" : "them"} in ${shown}, then mason start`, next: [["mason start", "the demo database and Mason, polled"]] };
+    }
+    if (cfg.changes !== "replication")
+        return null;
+    return { message: `the demo database is read by polling only: "changes": "replication" in ${STATE_DIR}/config.json does not apply to it`, code: "refused",
+        why: "the demo database has no change log for logical replication to read; mason start polls it with SELECTs, every few seconds",
+        fix: `remove "changes": "replication" from ${STATE_DIR}/config.json, then mason start`,
+        next: [["mason start", "the demo database and Mason, polled"]] };
+}
+/** The step's done line: where the demo database listens, and whether it was seeded now or kept from the last run. */
+export function demoDoneLine(port, seeded) {
+    return `Demo database on 127.0.0.1:${port} (Postgres, hosted by this process in ${STATE_DIR}/${DEMO_DIR}; ${seeded ? "seeded with the shop schema" : "kept from the last run"})`;
+}
+/**
+ * THE DEMO DATABASE OPENED for the run in `home`/demo (`home` the project's `.mason/`), its events to `log`: the handle and
+ * the step's done line, or why it did not open — its own message (what failed), and when something holds the port, the
+ * way out ONCE, with its choices: mason stop for a run of this project's that may still hold it, stop what does, or move
+ * the demo database by changing the port in its URL, where `from` says the URL is (`DATABASE_URL in .env`: the port
+ * lives there alone). The port is free for every other reason, so the probe tells a held port apart without reading
+ * the message.
+ */
+export async function openDemo(o) {
+    const open = o.open ?? (async (a) => (await demoModule()).DemoSource.open(a));
+    try {
+        const demo = await open({ dir: path.join(o.home, DEMO_DIR), port: o.port, log: o.log });
+        return { demo, done: demoDoneLine(demo.port, demo.seeded) };
+    }
+    catch (e) {
+        const problem = `the demo database did not start: ${e.message}`;
+        const held = await portHolder(o.port);
+        if (held === null)
+            return { problem };
+        const move = `move the demo database: change the port in ${o.from} (postgres://${DEMO_USER}@127.0.0.1:<another>/${DEMO_DATABASE}) and mason start again`;
+        return { problem: held.code === "EACCES"
+                ? `${problem} (${heldText(o.port, held)}): ${move}`
+                : `${problem}: mason stop ends a run that may still hold it, else stop what does (lsof -nP -iTCP:${o.port} -sTCP:LISTEN names it), or ${move}` };
+    }
+}
+/**
+ * THE WRITER: one round of changes every `ms`, each said to `log` as the demo says it; a round that fails is said and
+ * the next one tried, and a round is never begun while the last one runs. Returns what stops it (idempotent).
+ */
+export function demoChanges(demo, ms, log) {
+    let busy = false;
+    const timer = setInterval(() => {
+        if (busy)
+            return;
+        busy = true;
+        demo.change().then((line) => log(line), (e) => log(`a change failed (the next one is tried in ${ms / 1000} s): ${e.message}`))
+            .finally(() => { busy = false; });
+    }, ms);
+    return () => clearInterval(timer);
+}
+/** The demo database closed once, however often it is asked: null when it closed, else what went wrong (said by the
+ *  caller, never swallowed). */
+export function closingOnce(demo) {
+    let closing = null;
+    return () => closing ??= demo.close().then(() => null, (e) => e.message);
+}
+/** What the crash path says of a demo database still closing when it stops waiting (`closedWithin`). */
+export const DEMO_STILL_CLOSING = (ms) => `closing the demo database: still closing after ${ms / 1000} s; its data may need seeding again at the next start`;
+/**
+ * A close waited for `ms` at most, and SAID when it is not done by then (`late`), never left silent: the crash path
+ * stops waiting so the supervisor can start the run again. The timer is cleared when the close wins, and is not
+ * unref'd, so a close that hangs is said before the process ends. A close that rejects rejects this.
+ */
+export async function closedWithin(closing, ms, late) {
+    let timer;
+    const timedOut = new Promise((resolve) => { timer = setTimeout(() => resolve(true), ms); });
+    try {
+        if (await Promise.race([closing.then(() => false), timedOut]))
+            late();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}