@antelopejs/dms 0.11.0 → 0.12.0

package/bin/control/processes.mjs

@@ -0,0 +1,325 @@
+import { spawn } from "node:child_process";
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+} from "node:fs";
+import { createConnection, createServer } from "node:net";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+const POLL_MS = 500;
+const STOP_GRACE_MS = 10_000;
+const PROBE_TIMEOUT_MS = 3_000;
+const LISTEN_STATE = "0A";
+const HEX = 16;
+
+/**
+ * Asks the kernel for a free TCP port on the loopback interface.
+ *
+ * @returns {Promise<number>} The port
+ */
+export function freePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * Starts a long-running program in its own process group, its output going
+ * straight to `<logs>/<name>.log` so it survives the caller.
+ *
+ * @param {{ name: string, program: string, args: string[], cwd: string, env: NodeJS.ProcessEnv, logs: string }} spec What to start and where its log goes
+ * @returns {{ name: string, pid: number, command: string, cwd: string, log: string, startedAt: string }} The process record
+ */
+export function startDetached(spec) {
+  const log = join(spec.logs, `${spec.name}.log`);
+  const output = openSync(log, "a");
+  const child = spawn(spec.program, spec.args, {
+    cwd: spec.cwd,
+    env: spec.env,
+    detached: true,
+    stdio: ["ignore", output, output],
+  });
+  closeSync(output);
+  child.unref();
+  if (child.pid === undefined) {
+    throw new Error(`Could not start ${spec.name}: ${spec.program}`);
+  }
+  return {
+    name: spec.name,
+    pid: child.pid,
+    command: [spec.program, ...spec.args].join(" "),
+    cwd: spec.cwd,
+    log,
+    startedAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Runs a program to completion, its output appended to `<logs>/<name>.log`.
+ *
+ * @param {{ name: string, program: string, args: string[], cwd: string, env: NodeJS.ProcessEnv, logs: string }} spec What to run
+ * @returns {Promise<void>} Resolves on exit code 0
+ * @throws When the program exits otherwise, naming its log
+ */
+export function runToEnd(spec) {
+  const log = join(spec.logs, `${spec.name}.log`);
+  const output = openSync(log, "a");
+  return new Promise((resolve, reject) => {
+    const child = spawn(spec.program, spec.args, {
+      cwd: spec.cwd,
+      env: spec.env,
+      stdio: ["ignore", output, output],
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      closeSync(output);
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(`${spec.name} exited with ${code ?? signal}; see ${log}`),
+      );
+    });
+  });
+}
+
+/**
+ * Whether a process with this PID exists.
+ *
+ * @param {number} pid The process id
+ * @returns {boolean} True while it runs
+ */
+export function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The status of one GET, or `null` when nothing answered.
+ *
+ * @param {string} url The URL
+ * @returns {Promise<number | null>} The HTTP status
+ */
+export async function probe(url) {
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    await response.body?.cancel();
+    return response.status;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Polls `url` until it answers 200, the process exits or the timeout passes.
+ *
+ * @param {string} url The readiness URL
+ * @param {{ pid: number, log: string }} record The process that must serve it
+ * @param {number} timeoutMs How long to wait
+ * @returns {Promise<void>} Resolves once ready
+ * @throws When the process exits first or the timeout passes, naming its log
+ */
+export async function waitForOk(url, record, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if ((await probe(url)) === 200) return;
+    if (!isAlive(record.pid)) {
+      throw new Error(`${url}: the process exited first; see ${record.log}`);
+    }
+    await sleep(POLL_MS);
+  }
+  throw new Error(
+    `${url} did not answer 200 in ${timeoutMs} ms; see ${record.log}`,
+  );
+}
+
+function accepts(port) {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    socket.once("connect", () => {
+      socket.end();
+      resolve(true);
+    });
+    socket.once("error", () => resolve(false));
+  });
+}
+
+/**
+ * Polls a loopback port until it accepts a connection, the process exits or
+ * the timeout passes.
+ *
+ * @param {number} port The port
+ * @param {{ name: string, pid: number, log: string }} record The process that must listen
+ * @param {number} timeoutMs How long to wait
+ * @returns {Promise<void>} Resolves once it listens
+ * @throws When the process exits first or the timeout passes, naming its log
+ */
+export async function waitForPort(port, record, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await accepts(port)) return;
+    if (!isAlive(record.pid)) break;
+    await sleep(POLL_MS);
+  }
+  throw new Error(
+    `${record.name} did not listen on ${port}; see ${record.log}`,
+  );
+}
+
+/**
+ * Polls until the process itself listens on the port, so a port another
+ * program took after it was picked is not mistaken for ours.
+ *
+ * @param {number} port The port
+ * @param {{ name: string, pid: number, log: string }} record The process that must listen
+ * @param {number} timeoutMs How long to wait
+ * @returns {Promise<void>} Resolves once the process listens
+ * @throws When it exits first (the port was taken) or the timeout passes
+ */
+export async function waitForOwnPort(port, record, timeoutMs) {
+  if (listenersOf(port) === null) return waitForPort(port, record, timeoutMs);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && isAlive(record.pid)) {
+    if (listenersOf(port).includes(record.pid)) return;
+    await sleep(POLL_MS);
+  }
+  throw new Error(
+    `${record.name} does not listen on ${port}; see ${record.log}`,
+  );
+}
+
+function procEntries() {
+  try {
+    return readdirSync("/proc").filter((entry) => /^\d+$/.test(entry));
+  } catch {
+    return [];
+  }
+}
+
+function parentOf(pid) {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+  } catch {
+    return -1;
+  }
+}
+
+/**
+ * Every live descendant of `pids`, read from /proc. Empty where /proc is
+ * missing. A child that left the process group is found here too.
+ *
+ * @param {number[]} pids The roots
+ * @returns {number[]} The descendants, roots excluded
+ */
+export function descendantsOf(pids) {
+  const parents = new Map(
+    procEntries().map((entry) => [Number(entry), parentOf(entry)]),
+  );
+  const found = new Set(pids);
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const [pid, parent] of parents) {
+      if (!found.has(pid) && found.has(parent)) {
+        found.add(pid);
+        grew = true;
+      }
+    }
+  }
+  return [...found].filter((pid) => !pids.includes(pid));
+}
+
+function listeningInodes(port) {
+  const inodes = new Set();
+  for (const table of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+    if (!existsSync(table)) continue;
+    for (const line of readFileSync(table, "utf8").split("\n").slice(1)) {
+      const fields = line.trim().split(/\s+/);
+      const local = fields[1]?.split(":")[1];
+      if (
+        local &&
+        Number.parseInt(local, HEX) === port &&
+        fields[3] === LISTEN_STATE
+      ) {
+        inodes.add(fields[9]);
+      }
+    }
+  }
+  return inodes;
+}
+
+function socketInodes(pid) {
+  try {
+    return readdirSync(`/proc/${pid}/fd`).flatMap((fd) => {
+      const link = readlinkSync(`/proc/${pid}/fd/${fd}`, { encoding: "utf8" });
+      const match = /^socket:\[(\d+)\]$/.exec(link);
+      return match ? [match[1]] : [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The processes listening on a TCP port, read from /proc, or `null` where
+ * /proc cannot tell.
+ *
+ * @param {number} port The port
+ * @returns {number[] | null} The PIDs that hold a listening socket on it
+ */
+export function listenersOf(port) {
+  if (!existsSync("/proc/net/tcp")) return null;
+  const inodes = listeningInodes(port);
+  return procEntries()
+    .map(Number)
+    .filter((pid) => socketInodes(pid).some((inode) => inodes.has(inode)));
+}
+
+function signalGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      return;
+    }
+  }
+}
+
+/**
+ * Stops recorded processes and every descendant: SIGTERM to each process
+ * group, then SIGKILL to whatever outlives the grace period.
+ *
+ * @param {number[]} pids The recorded PIDs
+ * @returns {Promise<string[]>} One line per process signalled
+ */
+export async function stopAll(pids) {
+  const targets = [...pids, ...descendantsOf(pids)].filter(isAlive);
+  for (const pid of targets) signalGroup(pid, "SIGTERM");
+  const deadline = Date.now() + STOP_GRACE_MS;
+  while (targets.some(isAlive) && Date.now() < deadline) await sleep(POLL_MS);
+  const stubborn = targets.filter(isAlive);
+  for (const pid of stubborn) signalGroup(pid, "SIGKILL");
+  return targets.map(
+    (pid) => `stopped pid ${pid}${stubborn.includes(pid) ? " (SIGKILL)" : ""}`,
+  );
+}

package/bin/control/run-state.mjs

@@ -0,0 +1,111 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const RUN_FILE = "run.json";
+const ID_BYTES = 3;
+const TIMESTAMP_LENGTH = 15;
+
+/**
+ * Where runs are created: `--runs`, else `DMS_CONTROL_RUNS`, else
+ * `<tmpdir>/dms-control`. A run holds a playground copy and its frontend
+ * build, a few hundred megabytes, so prefer a folder on disk over a tmpfs.
+ *
+ * @param {string | undefined} option The `--runs` value
+ * @returns {string} The absolute runs folder
+ */
+export function runsRoot(option) {
+  return resolve(
+    option ?? process.env.DMS_CONTROL_RUNS ?? join(tmpdir(), "dms-control"),
+  );
+}
+
+/**
+ * A new run id: the UTC time to the second and three random bytes, so two
+ * runs started in the same second never share a folder or a database.
+ *
+ * @returns {string} The run id, such as `20261029T034501-a1b2c3`
+ */
+export function newRunId() {
+  const stamp = new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .slice(0, TIMESTAMP_LENGTH);
+  return `${stamp}-${randomBytes(ID_BYTES).toString("hex")}`;
+}
+
+/**
+ * The folders of a run, all under its root.
+ *
+ * @param {string} dir The run root
+ * @returns {{ dir: string, root: string, home: string, logs: string, mongo: string, browser: string, evidence: string, cache: string }} The run's folders
+ */
+export function runPaths(dir) {
+  return {
+    dir,
+    root: join(dir, "root"),
+    home: join(dir, "home"),
+    logs: join(dir, "logs"),
+    mongo: join(dir, "mongo"),
+    browser: join(dir, "browser"),
+    evidence: join(dir, "evidence"),
+    cache: join(dir, "cache"),
+  };
+}
+
+/**
+ * The database a run owns: `verify_<run id>` with every character MongoDB
+ * refuses in a name replaced.
+ *
+ * @param {string} id The run id
+ * @returns {string} The database name
+ */
+export function databaseName(id) {
+  return `verify_${id.replace(/[^A-Za-z0-9_]/g, "_")}`;
+}
+
+/**
+ * Creates the folders of a new run.
+ *
+ * @param {string} dir The run root
+ * @returns {ReturnType<typeof runPaths>} The run's folders
+ */
+export function createRunFolders(dir) {
+  const paths = runPaths(dir);
+  for (const folder of [paths.home, paths.logs, paths.evidence]) {
+    mkdirSync(folder, { recursive: true });
+  }
+  return paths;
+}
+
+/**
+ * Reads the state `up` recorded for a run.
+ *
+ * @param {string} dir The run root, as `up` printed it
+ * @returns {Record<string, any>} The run state
+ * @throws When the folder holds no run.json
+ */
+export function loadRun(dir) {
+  const file = join(resolve(dir), RUN_FILE);
+  if (!existsSync(file)) {
+    throw new Error(
+      `No run at ${dir}: run.json is missing. Start one with dms-control up.`,
+    );
+  }
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+
+/**
+ * Writes the run state, readable by its owner only since it holds the run's
+ * secrets and the admin password.
+ *
+ * @param {Record<string, any>} state The run state
+ */
+export function saveRun(state) {
+  writeFileSync(
+    join(state.dir, RUN_FILE),
+    `${JSON.stringify(state, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+}

package/bin/control/session.mjs

@@ -0,0 +1,219 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { saveRun } from "./run-state.mjs";
+
+const REQUEST_TIMEOUT_MS = 30_000;
+const UNAUTHORIZED = 401;
+const PASSWORD_BYTES = 9;
+const OK_MIN = 200;
+const OK_MAX = 299;
+
+/**
+ * The credentials of the run's administrator, derived from the run id so a
+ * journey can name them before onboarding.
+ *
+ * @param {{ id: string }} state The run
+ * @returns {{ email: string, password: string, firstName: string, lastName: string }} The administrator's credentials
+ */
+export function adminCredentials(state) {
+  return {
+    email: `admin+${state.id}@verify.local`.toLowerCase(),
+    password: state.adminPassword,
+    firstName: "Verify",
+    lastName: "Admin",
+  };
+}
+
+/**
+ * A password the DMS policy accepts: an uppercase letter, a digit and one of
+ * `@$!%*?&`, at least eight characters.
+ *
+ * @returns {string} The password
+ */
+export function newPassword() {
+  return `Vr1!${randomBytes(PASSWORD_BYTES).toString("base64url").replace(/[-_]/g, "x")}`;
+}
+
+function slug(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60);
+}
+
+/**
+ * A new numbered evidence folder under `<run>/evidence/<group>/`.
+ *
+ * @param {{ evidence: string }} state The run
+ * @param {string} group The command that writes it, such as `api`
+ * @param {string} label What the step does
+ * @returns {string} The folder
+ */
+export function nextFolder(state, group, label) {
+  const parent = join(state.evidence, group);
+  mkdirSync(parent, { recursive: true });
+  const index = readdirSync(parent).length + 1;
+  const folder = join(
+    parent,
+    `${String(index).padStart(2, "0")}-${slug(label)}`,
+  );
+  mkdirSync(folder, { recursive: true });
+  return folder;
+}
+
+function parseBody(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Sends one request to the run's backend and writes request.json and
+ * response.json into `folder`. Secrets in the request are left out.
+ *
+ * @param {string} folder Where the evidence goes
+ * @param {{ url: string, method: string, body?: any, token?: string }} request What to send
+ * @returns {Promise<{ status: number | null, body: any, error: string | null }>} The answer
+ */
+export async function recordedRequest(folder, request) {
+  const headers = { accept: "application/json" };
+  if (request.body !== undefined) headers["content-type"] = "application/json";
+  if (request.token) headers.authorization = `Bearer ${request.token}`;
+  writeFileSync(
+    join(folder, "request.json"),
+    `${JSON.stringify({ method: request.method, url: request.url, authenticated: Boolean(request.token), body: request.body ?? null }, null, 2)}\n`,
+  );
+  let answer;
+  try {
+    const response = await fetch(request.url, {
+      method: request.method,
+      headers,
+      body:
+        request.body === undefined ? undefined : JSON.stringify(request.body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    answer = {
+      status: response.status,
+      body: parseBody(await response.text()),
+      error: null,
+    };
+  } catch (error) {
+    answer = { status: null, body: null, error: String(error?.cause ?? error) };
+  }
+  writeFileSync(
+    join(folder, "response.json"),
+    `${JSON.stringify(answer, null, 2)}\n`,
+  );
+  return answer;
+}
+
+/**
+ * Whether an answer is a 2xx.
+ *
+ * @param {{ status: number | null }} answer The answer
+ * @returns {boolean} True on 2xx
+ */
+export function isOk(answer) {
+  return (
+    answer.status !== null && answer.status >= OK_MIN && answer.status <= OK_MAX
+  );
+}
+
+/**
+ * Signs an account in through `POST /api/auth/login` and keeps its tokens in
+ * the run state.
+ *
+ * @param {Record<string, any>} state The run
+ * @param {string} account The account name, `admin` for the run's administrator
+ * @returns {Promise<{ status: number | null, body: any }>} The login answer
+ */
+export async function signIn(state, account) {
+  const credentials = state.accounts?.[account];
+  if (!credentials) {
+    throw new Error(
+      `No account ${account} in the run; onboard first or add it with dms-control account.`,
+    );
+  }
+  const folder = nextFolder(state, "auth", `login ${account}`);
+  const answer = await recordedRequest(folder, {
+    url: `${state.apiUrl}/api/auth/login`,
+    method: "POST",
+    body: { email: credentials.email, password: credentials.password },
+  });
+  if (isOk(answer) && answer.body?.access_token) {
+    state.tokens = { ...state.tokens, [account]: answer.body.access_token };
+    saveRun(state);
+  }
+  return answer;
+}
+
+/**
+ * Creates the run's administrator through `POST /api/onboarding/register`,
+ * then signs it in.
+ *
+ * @param {Record<string, any>} state The run
+ * @param {{ platformName?: string }} options Wizard details
+ * @returns {Promise<{ register: { status: number | null, body: any }, login: { status: number | null, body: any } | null }>} Both answers
+ */
+export async function onboard(state, options) {
+  const admin = adminCredentials(state);
+  const register = await recordedRequest(
+    nextFolder(state, "onboard", "register"),
+    {
+      url: `${state.apiUrl}/api/onboarding/register`,
+      method: "POST",
+      body: {
+        ...admin,
+        platformName: options.platformName ?? `Verify ${state.id}`,
+      },
+    },
+  );
+  if (!isOk(register)) return { register, login: null };
+  state.accounts = {
+    ...state.accounts,
+    admin: {
+      email: admin.email,
+      password: admin.password,
+      userId: register.body?.[0] ?? null,
+    },
+  };
+  saveRun(state);
+  return { register, login: await signIn(state, "admin") };
+}
+
+/**
+ * An authenticated (or anonymous) request to the run's backend, signing the
+ * account in again once when its token was refused.
+ *
+ * @param {Record<string, any>} state The run
+ * @param {{ method: string, path: string, body?: any, as: string, label?: string, folder?: () => string }} request What to send and as whom; `as` is an account name or `anon`; `folder` makes each attempt's evidence folder
+ * @returns {Promise<{ status: number | null, body: any, error: string | null, folder: string }>} The answer and its evidence folder
+ */
+export async function apiRequest(state, request) {
+  const label = request.label ?? `${request.method} ${request.path}`;
+  const makeFolder = request.folder ?? (() => nextFolder(state, "api", label));
+  const send = async () => {
+    const folder = makeFolder();
+    const token =
+      request.as === "anon" ? undefined : state.tokens?.[request.as];
+    return {
+      ...(await recordedRequest(folder, {
+        url: `${state.apiUrl}${request.path}`,
+        method: request.method,
+        body: request.body,
+        token,
+      })),
+      folder,
+    };
+  };
+  if (request.as !== "anon" && !state.tokens?.[request.as])
+    await signIn(state, request.as);
+  const first = await send();
+  if (first.status !== UNAUTHORIZED || request.as === "anon") return first;
+  await signIn(state, request.as);
+  return send();
+}