cortad 0.3.1-rc.8 → 0.3.1

package/lib/mongo.mjs

@@ -0,0 +1,74 @@
+// A MongoDB database copied for a session on the server it lives on, with MongoDB's own tools: a
+// dump of it restored under a name of ours, and dropped after. The address carries the password, so
+// it reaches mongodump and mongorestore through a config file only this user can read, and mongosh
+// through its environment: never a command line another process on this machine can read.
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// A database bigger than this is not copied: said instead, so the person decides.
+export const MONGO_CAP = 1024 ** 3;
+
+// The address with another database in it. A user kept in the app's own database signs in there,
+// which the address says by naming that database, so the copy's address names it as the place to
+// sign in. Rewritten as text: a replica set's host list (a:27017,b:27018) is no URL a parser takes.
+export function withDb(uri, db, source) {
+  const [, head, hosts, path = "", query = "", tail = ""] = /^([^:]+:\/\/)([^/?#]*)(?:\/([^?#]*))?(\?[^#]*)?(#.*)?$/.exec(uri);
+  const cut = hosts.lastIndexOf("@");
+  const signsIn = cut > 0 && !hosts.startsWith(":") && !/[?&]authSource=/i.test(query);
+  const own = (() => { try { return decodeURIComponent(path); } catch { return path; } })();
+  const from = signsIn ? `${query ? `${query}&` : "?"}authSource=${encodeURIComponent(own || source || "admin")}` : query;
+  return `${head}${hosts}/${encodeURIComponent(db)}${from}${tail}`;
+}
+
+function run(bin, args, { env = {}, stdin = null } = {}) {
+  return new Promise((done) => {
+    const child = spawn(bin, args, { env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", ...env }, stdio: [stdin ? "pipe" : "ignore", "pipe", "pipe"] });
+    let out = "", err = "";
+    child.stdout.on("data", (d) => { out += d; });
+    child.stderr.on("data", (d) => { err = (err + d).slice(-4000); });
+    if (stdin) stdin.pipe(child.stdin);
+    child.on("error", (e) => done({ code: e.code === "ENOENT" ? "missing" : 1, out, err: String(e.message) }));
+    child.on("close", (code) => done({ code, out, err }));
+  });
+}
+// One statement against the server, the address in the environment.
+const shell = (uri, script) => run("mongosh", ["--nodb", "--quiet", "--eval", `const c = new Mongo(process.env.CORTAD_MONGO); ${script}`], { env: { CORTAD_MONGO: uri } });
+
+// Why a tool refused, as a class the sentence is written from, never in the server's own words.
+export function refusal(r) {
+  if (r.code === "missing") return "missing";
+  if (/Authentication failed|AuthenticationFailed|auth error/i.test(r.err)) return "auth";
+  if (/not authorized|Unauthorized|requires authentication/i.test(r.err)) return "rights";
+  if (/ECONNREFUSED|connection refused|server selection|No servers available|timed out/i.test(r.err)) return "down";
+  return "other";
+}
+
+export async function cloneMongo(conn, source, clone) {
+  const size = await shell(withDb(conn.uri, source, source), `print(c.getDB(${JSON.stringify(source)}).stats().dataSize)`);
+  if (size.code !== 0) return { why: refusal(size) };
+  if (Number(size.out.trim()) > MONGO_CAP) return { why: "big" };
+  const dir = mkdtempSync(join(tmpdir(), "cortad-mongo-"));
+  try {
+    writeFileSync(join(dir, "from.yaml"), `uri: ${JSON.stringify(withDb(conn.uri, source, source))}\n`, { mode: 0o600 });
+    writeFileSync(join(dir, "to.yaml"), `uri: ${JSON.stringify(withDb(conn.uri, "", source))}\n`, { mode: 0o600 });
+    const dump = spawn("mongodump", [`--config=${join(dir, "from.yaml")}`, `--db=${source}`, "--archive"], { env: { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "" }, stdio: ["ignore", "pipe", "pipe"] });
+    let dumpErr = "";
+    dump.stderr.on("data", (d) => { dumpErr = (dumpErr + d).slice(-4000); });
+    const dumped = new Promise((done) => { dump.on("error", (e) => done(e.code === "ENOENT" ? "missing" : 1)); dump.on("close", done); });
+    const restored = await run("mongorestore", [`--config=${join(dir, "to.yaml")}`, "--archive", `--nsInclude=${source}.*`, `--nsFrom=${source}.*`, `--nsTo=${clone}.*`], { stdin: dump.stdout });
+    const dumpCode = await dumped;
+    if (dumpCode === 0 && restored.code === 0) return { how: "dump" };
+    await dropMongo(conn, clone, source);
+    // Either side ending stops the other, which then fails for that reason alone: the telling one wins.
+    const whys = [dumpCode === 0 ? null : refusal({ code: dumpCode, err: dumpErr }), restored.code === 0 ? null : refusal(restored)].filter(Boolean);
+    return { why: whys.find((w) => w !== "other") ?? "other" };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export async function dropMongo(conn, clone, source) {
+  return (await shell(withDb(conn.uri, clone, source), `c.getDB(${JSON.stringify(clone)}).dropDatabase()`)).code === 0;
+}

package/lib/numbers-text.mjs

@@ -0,0 +1,68 @@
+import { clip, closeToCall, has, num, pack, pageOf, plural } from "./words.mjs";
+
+// Every number the run measured, whole, one call away (`findings numbers`): each group with its count
+// by class, of how many, the interval on the share that matters, and one exchange from the worst
+// group of each.
+
+const pct = (x) => `${Math.round(x * 100)}%`;
+const interval = (b) => `${pct(b.lo)} to ${pct(b.hi)}`;
+const isScale = (t) => t.classes.every((c) => /^\d+$/.test(c));
+
+const units = (n, unit) => (unit === "replies" ? plural(n, "reply", "replies") : plural(n, "conversation"));
+
+const SPLIT_WORDS = { journey: "By journey", segment: "By user segment", situation: "By place in your app", reply: "By reply" };
+const SPLIT_WORD = { journey: "journey", segment: "user segment", situation: "place", reply: "reply" };
+// The server counts in "trials"; the person reads conversations.
+const unitSaid = (unit) => (unit === "replies" ? "replies" : "conversations");
+
+// One group as a row under its header: the counts in the header's order, of how many, the average
+// on a scale, then the share named with its interval.
+function row(t, d, said) {
+  const of = units(d.of, t.unit);
+  const unsure = d.unsure ? `; ${closeToCall(d.unsure, said)}` : "";
+  const share = d.bad && d.of ? `, ${interval(d.bad)}` : "";
+  if (t.kind === "question") return `${num(d.counts?.broke ?? 0)} of ${of}${share}${unsure}`;
+  const counts = t.classes.map((c) => num(d.counts?.[c] ?? 0)).join(", ");
+  const mean = has(d.mean) ? `, average ${d.mean.toFixed(2)}` : "";
+  return `${counts} of ${of}${mean}${d.bad && t.badSaid ? `; ${num(d.bad.k)}${share}` : ""}${unsure}`;
+}
+
+// How the rows are read: a question's conversations broken, or a measurement's classes and its share.
+const headerOf = (t) => (t.kind === "question"
+  ? `  Counted as: the ${unitSaid(t.unit)} it broke in, of the ${unitSaid(t.unit)} that asked it, with the 95% interval.`
+  : `  Counted as: ${isScale(t) ? `levels ${t.classes.join(", ")}` : t.classes.join(", ")} of ${unitSaid(t.unit)}${t.badSaid ? `; then how many ${t.badSaid}, with the 95% interval` : ""}.`);
+
+function tableBlock(t) {
+  const said = {};
+  const lines = [`${t.kind === "question" ? `${t.id}  ` : ""}${clip(t.title, 400)}${t.from ? ` (${t.from})` : ""}`];
+  if (t.legend) lines.push(`  ${clip(t.legend, 500)}`);
+  lines.push(headerOf(t), `  All: ${row(t, t.all, said)}`);
+  for (const split of ["journey", "segment", "situation", "reply"]) {
+    const groups = t.by?.[split] ?? [];
+    if (!groups.length || (split !== "reply" && groups.length === 1 && groups[0].of === t.all.of)) continue;
+    lines.push(`  ${SPLIT_WORDS[split]}:`, ...groups.map((d) => `    ${clip(d.value, 90)}${d.kept ? " (saved to test fixes)" : ""}: ${row(t, d, said)}`));
+  }
+  const w = t.worst;
+  if (w) {
+    const e = w.exchange;
+    lines.push(`  Worst: ${SPLIT_WORD[w.split] ?? w.split} ${clip(w.value, 90)}.${e ? ` Conversation ${String(e.trialId).slice(0, 8)}, reply ${e.reply}.` : " Its conversations are saved to test fixes."}`);
+    if (e?.sent) lines.push(`    Sent: "${clip(e.sent, 300)}"`);
+    if (e?.answer) lines.push(`    Reply ${e.reply}: "${clip(e.answer, 300)}"`);
+    if (e?.after) lines.push(`    Then the customer: "${clip(e.after, 300)}"`);
+    if (e?.quote && e.quote !== e.answer) lines.push(`    It broke on: "${clip(e.quote, 240)}"`);
+  }
+  return lines.join("\n");
+}
+
+// Every number, whole, in pages under what every client shows at once.
+export function numbersText(d, page = 1) {
+  const n = d?.numbers;
+  if (!n) return d?.why ?? "No run has finished on this repository yet.";
+  const head = [
+    `Run ${n.runId}: every number it measured, ${plural(n.measures.length, "measurement")} and ${plural(n.questions.length, "question")} over ${plural(n.trials, "conversation")}, ${plural(n.replies, "reply", "replies")} and ${plural(n.readings, "reading")}.`,
+    "A conversation counts once in each group it played in; a reply split counts each conversation at that reply.",
+  ].join("\n");
+  const blocks = [...n.measures, ...n.questions].map(tableBlock);
+  const pages = pack(head, blocks.map((b) => `\n${b}`), `Run ${n.runId}, numbers continued.`);
+  return pageOf(pages, page, (k) => `findings numbers with page ${k}`);
+}

package/lib/pg.mjs

@@ -0,0 +1,118 @@
+// A Postgres database copied for a session on the server it lives on, with the credentials the
+// app's own settings carry, and dropped after. Postgres's own tools do the work (psql, and pg_dump
+// when the database is in use); the password reaches them through their environment, never a
+// command line another process on this machine can read.
+import { spawn } from "node:child_process";
+
+// A database bigger than this is not copied: said instead, so the person decides.
+export const PG_CAP = 1024 ** 3;
+const quote = (name) => `"${String(name).replace(/"/g, '""')}"`;
+const literal = (text) => `'${String(text).replace(/'/g, "''")}'`;
+
+const envOf = (conn, db) => ({
+  PATH: process.env.PATH ?? "",
+  HOME: process.env.HOME ?? "",
+  PGDATABASE: db,
+  PGCONNECT_TIMEOUT: "10",
+  PGAPPNAME: "cortad",
+  ...(conn.host ? { PGHOST: conn.host } : {}),
+  ...(conn.port ? { PGPORT: String(conn.port) } : {}),
+  ...(conn.user ? { PGUSER: conn.user } : {}),
+  ...(conn.password ? { PGPASSWORD: conn.password } : {}),
+  ...(conn.sslmode ? { PGSSLMODE: conn.sslmode } : {}),
+});
+
+function run(bin, args, env, input = null) {
+  return new Promise((done) => {
+    const child = spawn(bin, args, { env, stdio: [input ? "pipe" : "ignore", "pipe", "pipe"] });
+    let out = "", err = "";
+    child.stdout.on("data", (d) => { out += d; });
+    child.stderr.on("data", (d) => { err = (err + d).slice(-4000); });
+    if (input) input.pipe(child.stdin);
+    child.on("error", (e) => done({ code: e.code === "ENOENT" ? "missing" : 1, out, err: String(e.message) }));
+    child.on("close", (code) => done({ code, out, err }));
+  });
+}
+
+// One statement per -c: CREATE and DROP DATABASE refuse to run inside a transaction, and several
+// statements in one string are one.
+const psql = (conn, db, ...statements) =>
+  run("psql", ["-X", "-q", "-A", "-t", "-v", "ON_ERROR_STOP=1", "-v", "VERBOSITY=verbose", ...statements.flatMap((s) => ["-c", s])], envOf(conn, db));
+
+// Why psql refused, as a class the sentence is written from. Never the server's own words: they
+// name the user and the host, and the sentence leaves this machine.
+export function refusal(err) {
+  const code = /(?:ERROR|FATAL):\s+([0-9A-Z]{5}):/.exec(err)?.[1];
+  // A refusal while connecting carries no code, only the server's words.
+  if (code === "28P01" || code === "28000" || /password authentication failed|no pg_hba\.conf entry|role "[^"]*" does not exist|no password supplied/i.test(err)) return "auth";
+  if (code === "42501") return "rights";
+  if (code === "55006") return "busy";
+  if (code === "3D000" || /database "[^"]*" does not exist/i.test(err)) return "gone";
+  if (/server version mismatch|aborting because of server version/i.test(err)) return "version";
+  if (/Connection refused|could not connect|No such file or directory|timeout expired|could not translate host/i.test(err)) return "down";
+  return "other";
+}
+
+// The database to stand in while a copy is made: never the source, which a template copy needs
+// free of every connection, ours included.
+async function maintenance(conn, source) {
+  for (const db of ["postgres", "template1"].filter((d) => d !== source)) {
+    const r = await psql(conn, db, "select 1");
+    if (r.code === 0) return { db };
+    if (r.code === "missing") return { why: "missing" };
+    const why = refusal(r.err);
+    if (why !== "gone") return { why };
+  }
+  return { why: "other" };
+}
+
+// The copy: a template copy first, which Postgres makes file by file; when the database is in use,
+// which a template copy refuses, a dump of it restored into an empty one. Answers { how } or { why }.
+export async function clonePg(conn, source, clone) {
+  const home = await maintenance(conn, source);
+  if (!home.db) return { why: home.why };
+  const size = await psql(conn, home.db, `select pg_database_size(${literal(source)})`);
+  if (size.code !== 0) return { why: refusal(size.err) };
+  if (Number(size.out.trim()) > PG_CAP) return { why: "big" };
+  const made = await psql(conn, home.db, `CREATE DATABASE ${quote(clone)} TEMPLATE ${quote(source)}`);
+  if (made.code === 0) return { how: "template" };
+  const why = refusal(made.err);
+  if (why !== "busy") return { why };
+  const empty = await psql(conn, home.db, `CREATE DATABASE ${quote(clone)}`);
+  if (empty.code !== 0) return { why: refusal(empty.err) };
+  const dump = spawn("pg_dump", ["--no-owner", "--no-privileges"], { env: envOf(conn, source), stdio: ["ignore", "pipe", "pipe"] });
+  let dumpErr = "";
+  dump.stderr.on("data", (d) => { dumpErr = (dumpErr + d).slice(-4000); });
+  const dumped = new Promise((done) => { dump.on("error", (e) => done(e.code === "ENOENT" ? "missing" : 1)); dump.on("close", done); });
+  const restored = await run("psql", ["-X", "-q", "-v", "ON_ERROR_STOP=1", "-v", "VERBOSITY=verbose"], envOf(conn, clone), dump.stdout);
+  const dumpCode = await dumped;
+  if (dumpCode === 0 && restored.code === 0) return { how: "dump" };
+  await dropPg(conn, clone);
+  if (dumpCode === "missing") return { why: "missing" };
+  // Either side ending stops the other, which then fails for that reason alone: the telling one wins.
+  const whys = [dumpCode === 0 ? null : refusal(dumpErr), restored.code === 0 ? null : refusal(restored.err)].filter(Boolean);
+  return { why: whys.find((w) => w !== "other") ?? "other" };
+}
+
+// An empty database on a server of this machine, for a stand-in of one kept elsewhere: the app's own
+// migrations fill it. Answers { how } or { why }.
+export async function emptyPg(conn, name) {
+  const home = await maintenance(conn);
+  if (!home.db) return { why: home.why };
+  const made = await psql(conn, home.db, `CREATE DATABASE ${quote(name)}`);
+  return made.code === 0 ? { how: "empty" } : { why: refusal(made.err) };
+}
+
+// One migration file, run whole: a failed statement stops it.
+export const applySql = async (conn, db, file) =>
+  (await run("psql", ["-X", "-q", "-v", "ON_ERROR_STOP=1", "-f", file], envOf(conn, db))).code === 0;
+
+// The copy's own connections are ended first: the app is stopped by then, but a pool can outlive it.
+export async function dropPg(conn, clone) {
+  const home = await maintenance(conn);
+  if (!home.db) return false;
+  const r = await psql(conn, home.db,
+    `select pg_terminate_backend(pid) from pg_stat_activity where datname = ${literal(clone)} and pid <> pg_backend_pid()`,
+    `DROP DATABASE IF EXISTS ${quote(clone)}`);
+  return r.code === 0;
+}

package/lib/proc.mjs

@@ -0,0 +1,100 @@
+// The app's processes: started tied to the runner, found by descent, stopped for certain, and the
+// holder of a port named.
+import { execFile, spawn } from "node:child_process";
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+const TETHER = fileURLToPath(new URL("./tether.mjs", import.meta.url));
+
+// ps's etime, [[dd-]hh:]mm:ss, in milliseconds.
+export function elapsedMs(etime) {
+  const [days, clock] = String(etime).includes("-") ? String(etime).split("-") : [0, String(etime)];
+  const [s = 0, m = 0, h = 0] = clock.split(":").map(Number).reverse();
+  return (((Number(days) * 24 + h) * 60 + m) * 60 + s) * 1000;
+}
+
+// Every process descended from pid. By descent, not by process group: nodemon, pm2 and concurrently
+// put the real server in a group of its own, and an app started through one of them was never seen
+// to open its port.
+export async function familyOf(pid) {
+  const table = (await exec("ps", ["-axo", "pid=,ppid="])).stdout.trim().split("\n").map((l) => l.trim().split(/\s+/).map(Number));
+  const family = new Set([pid]);
+  for (let grew = true; grew;) { grew = false; for (const [p, parent] of table) if (family.has(parent) && !family.has(p)) { family.add(p); grew = true; } }
+  return [...family];
+}
+
+// TCP ports pid and its descendants listen on.
+export async function listening(pid) {
+  try {
+    const { stdout } = await exec("lsof", ["-nP", "-a", "-p", (await familyOf(pid)).join(","), "-iTCP", "-sTCP:LISTEN", "-Fn"]);
+    return [...new Set([...stdout.matchAll(/^n.*:(\d+)$/gm)].map((m) => Number(m[1])).filter((p) => p > 0))];
+  } catch { return []; }
+}
+
+// The top of the chain that runs the app: nodemon, npm, the sh -c under it. Climbs from the listener
+// while the parent is a runner, never into the person's own shell or terminal.
+const RUNNER = /^(?:\S*\/)?(?:node|npm|npx|pnpm|yarn|bun|deno|python[\d.]*|uvicorn|gunicorn|flask|tsx|ts-node|nodemon|concurrently|pm2)(?:\s|$)|^(?:\/bin\/)?sh -c\b/;
+export async function chainOf(pid) {
+  const rows = (await exec("ps", ["-axo", "pid=,ppid=,etime=,args="])).stdout.trim().split("\n").map((l) => l.trim());
+  const table = new Map(rows.map((l) => { const m = /^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/.exec(l); return m ? [Number(m[1]), { pid: Number(m[1]), ppid: Number(m[2]), etime: m[3], args: m[4] }] : [0, null]; }));
+  const chain = table.get(pid) ? [table.get(pid)] : [];
+  for (let i = 0; i < 8 && chain.length; i++) {
+    const parent = table.get(chain.at(-1).ppid);
+    if (!parent || !RUNNER.test(parent.args)) break;
+    chain.push(parent);
+  }
+  return chain;
+}
+export const supervisorOf = async (pid) => (await chainOf(pid)).at(-1)?.pid ?? pid;
+
+// The process listening on a port.
+export async function listenerOn(port) {
+  try { return Number((await exec("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"])).stdout.trim().split("\n")[0]) || null; } catch { return null; }
+}
+
+// The port a bind failure names, in the app's own words: uvicorn's "('127.0.0.1', 8105): address
+// already in use", Go's "0.0.0.0:8080: bind: address already in use", Node's "EADDRINUSE: address
+// already in use :::3000" or "... 127.0.0.1:3000", Rails' "... for "127.0.0.1" port 3000". 0 when
+// it names none.
+export const portInError = (said) => Number(/[:\s(,](\d{4,5})\)?:?[^\n\d]{0,12}address already in use/i.exec(said)?.[1] ?? /(?:EADDRINUSE|address already in use)[^\n]{0,60}?[:\s](\d{4,5})\b/i.exec(said)?.[1] ?? 0);
+
+// Whoever holds a port: its pid, the program and its first argument (never the rest of its command
+// line, which can carry a key), and the folder it runs in.
+export async function holderOf(port) {
+  const pid = await listenerOn(port);
+  if (!pid) return null;
+  const [args, cwd] = await Promise.all([
+    exec("ps", ["-o", "args=", "-p", String(pid)]).then((r) => r.stdout.trim(), () => ""),
+    exec("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"]).then((r) => /^n(.+)$/m.exec(r.stdout)?.[1] ?? null, () => null),
+  ]);
+  return { port, pid, command: args.split(/\s+/).filter(Boolean).slice(0, 2).map((w) => basename(w)).join(" "), cwd };
+}
+
+// pid and everything it started, stopped: asked first, then made to. The group is signalled too, for
+// what its leader started before it exited.
+export async function stopTree(pid) {
+  const family = await familyOf(pid).catch(() => [pid]);
+  const signal = (sig) => { for (const p of family) { try { process.kill(p, sig); } catch { /* already gone */ } } try { process.kill(-pid, sig); } catch { /* no group left */ } };
+  const alive = () => family.some((p) => { try { process.kill(p, 0); return true; } catch { return false; } });
+  signal("SIGTERM");
+  for (let i = 0; i < 15 && alive(); i++) await new Promise((r) => setTimeout(r, 200));
+  if (alive()) signal("SIGKILL");
+}
+
+// A shell command in a process group of its own, stopped with this process however this process
+// ends. A watchdog (lib/tether.mjs) holds the read end of a pipe from here and stops the command's
+// tree when the pipe closes, which the kernel does for a process killed outright. The watchdog runs
+// with a bare environment, so the hooks handed to the app never load into it.
+export function spawnTied(cmd, { cwd, env }) {
+  const app = spawn("/bin/sh", ["-c", cmd], { cwd, env, stdio: ["ignore", "pipe", "pipe"], detached: true });
+  if (!app.pid) return app;
+  const dog = spawn(process.execPath, [TETHER, String(app.pid)], { stdio: ["pipe", "ignore", "ignore"], detached: true, env: { PATH: process.env.PATH ?? "" } });
+  dog.unref();
+  dog.stdin.unref?.();
+  dog.stdin.on("error", () => { /* the watchdog is gone; the runner stops the app itself */ });
+  // An app that ended while this process lives is this process's to clean up, not the watchdog's.
+  app.once("exit", () => { try { dog.kill("SIGKILL"); } catch { /* gone */ } });
+  return app;
+}