@intentius/chant-lexicon-fly 0.124.31 → 0.124.32

package/dist/op/activities/machines-local-cli.js

@@ -0,0 +1,85 @@
+/**
+ * A local Fly Machines API that runs its Machines (#2831), as a command:
+ *
+ *   tsx node_modules/@intentius/chant-lexicon-fly/src/op/activities/machines-local-cli.ts \
+ *     [--listen 4280] [--root <dir>] [--publish <port> | --publish <name>=<port> ...] [--log <file>]
+ *
+ * Point the release activities at it with `FLY_FLAPS_BASE_URL=http://127.0.0.1:4280`.
+ * `--publish 8080` publishes every Machine's service on 8080; `--publish web=8080`
+ * publishes the Machine named `web` there; with no `--publish` each Machine gets a free
+ * port, which the event lines say. SIGINT or SIGTERM stops every Machine's process
+ * and exits. See ./machines-local.ts.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { serveLocalMachines } from "./machines-local.js";
+export function parseArgs(argv) {
+    let port = 4280;
+    let root;
+    let log;
+    let all;
+    const byName = {};
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        const value = argv[i + 1];
+        if (value === undefined)
+            throw new Error(`${flag} needs a value`);
+        if (flag === "--listen")
+            port = Number(value);
+        else if (flag === "--root")
+            root = value;
+        else if (flag === "--log")
+            log = value;
+        else if (flag === "--publish") {
+            const eq = value.lastIndexOf("=");
+            if (eq === -1)
+                all = Number(value);
+            else
+                byName[value.slice(0, eq)] = Number(value.slice(eq + 1));
+        }
+        else
+            throw new Error(`unknown flag ${flag}`);
+        i++;
+    }
+    for (const n of [port, all, ...Object.values(byName)])
+        if (n !== undefined && !Number.isInteger(n))
+            throw new Error(`not a port: ${n}`);
+    const named = Object.keys(byName).length > 0;
+    const publish = named ? (app, m) => byName[`${app}/${m.name}`] ?? byName[m.name] ?? all : all;
+    return { port, root, publish, log };
+}
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(`machines-local: ${error.message}`);
+        console.error("usage: machines-local-cli.ts [--listen <port>] [--root <dir>] [--publish <port> | --publish <name>=<port>]... [--log <file>]");
+        process.exit(2);
+    }
+    // A standalone server, not an Op activity: its stdout is its output. The flaps URL and the
+    // event lines (which name each Machine's published port) stay there for the person or
+    // script that started it; errors and usage go to stderr.
+    const served = await serveLocalMachines({ ...args, handleSignals: false, onEvent: (line) => console.log(`machines-local: ${line}`) });
+    console.log(`machines-local: flaps on ${served.url}${args.root ? `, guest paths under ${args.root}` : ""}`);
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void served.close().then(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+const invoked = (() => {
+    try {
+        return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+})();
+if (invoked)
+    void main();

package/dist/op/activities/machines-local.js

@@ -0,0 +1,395 @@
+/**
+ * A local Fly Machines API that runs its Machines (#2831).
+ *
+ * ./machines-fake.ts answers the flaps endpoints from memory and runs nothing,
+ * and so does mudflaps. That is what unit tests want, and it stays the
+ * default. This module is the opt-in running mode: the same in-memory API,
+ * with each started Machine run as a process on this host, so a release that
+ * puts a source tree on a Machine (`config.files` plus `init.cmd`) can be
+ * checked over HTTP.
+ *
+ * For each Machine the fake holds in state `started`:
+ *
+ *   - `config.files` are written at their `guest_path` (under `root` when one
+ *     is given), and the files an earlier instance wrote are removed first, as
+ *     a Machine's root filesystem starts again from its image;
+ *   - `config.mounts` are directories that outlive instances (a Volume);
+ *   - `init.exec`, or `init.entrypoint` then `init.cmd`, runs with
+ *     `config.env`, and an `exec` (a migration) runs its command with the same
+ *     env;
+ *   - a service's `internal_port` is published on a host port: when the
+ *     Machine's env sets `PORT` to an `internal_port`, the process gets the
+ *     host port instead, since every Machine here shares the host's network.
+ *
+ * No image is pulled: the command runs on this host's binaries (a Node app
+ * runs on this host's Node).
+ *
+ * A create or an update (a new `instance_id`) starts the process again, a
+ * `restart` restarts it, a `stop` or a delete stops it, and a process that
+ * exits on its own leaves its Machine `stopped`. Each call answers only after
+ * that is done, and a started process is given until its published port
+ * accepts a connection, so the next call (a migration's exec, a health check)
+ * finds the files and the server.
+ *
+ * Processes run in their own process group. `close()` stops them all
+ * (SIGTERM, then SIGKILL); if the host process exits or is ended by SIGINT,
+ * SIGTERM or SIGHUP first, they are killed with it. Only a SIGKILL of the host
+ * process can leave them running.
+ */
+import { spawn } from "node:child_process";
+import { chmodSync, closeSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
+import { createConnection, createServer as createNetServer } from "node:net";
+import { dirname, join } from "node:path";
+import { createMachinesFake } from "./machines-fake.js";
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Is `pid`'s process group still there? */
+function groupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function killGroup(child, signal) {
+    if (!child?.pid)
+        return;
+    try {
+        process.kill(-child.pid, signal);
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * SIGKILL a process group until nothing in it is left to kill. One kill(-pgid)
+ * can miss a child that a member is forking at that moment: the child joins the
+ * group after the signal went out, and then outlives the rest (seen on macOS,
+ * #3202). Sending again once the forker is dead catches it. Synchronous, so it
+ * works in an "exit" handler; it stops as soon as the group is empty (or only
+ * zombies), and gives up after about 100ms.
+ */
+function killGroupNow(child) {
+    if (!child?.pid)
+        return;
+    const pause = new Int32Array(new SharedArrayBuffer(4));
+    for (let i = 0; i < 20; i++) {
+        try {
+            process.kill(-child.pid, "SIGKILL");
+        }
+        catch {
+            return;
+        }
+        Atomics.wait(pause, 0, 0, 5);
+    }
+}
+async function freePort() {
+    const srv = createNetServer();
+    await new Promise((ok, fail) => srv.once("error", fail).listen(0, "127.0.0.1", ok));
+    const { port } = srv.address();
+    await new Promise((ok) => srv.close(() => ok()));
+    return port;
+}
+function connects(port) {
+    return new Promise((done) => {
+        const socket = createConnection({ port, host: "127.0.0.1" });
+        socket.once("connect", () => {
+            socket.destroy();
+            done(true);
+        });
+        socket.once("error", () => done(false));
+    });
+}
+/** An in-memory Machines API that runs each started Machine on this host. See the module header. */
+export function createLocalMachines(options = {}) {
+    const root = options.root;
+    const readyTimeoutMs = options.readyTimeoutMs ?? 15000;
+    const stopTimeoutMs = options.stopTimeoutMs ?? 5000;
+    const say = options.onEvent ?? (() => undefined);
+    const running = new Map();
+    /** Host ports picked for Machines with no declared one, by `app/name`, so a new instance serves where the last did. */
+    const picked = new Map();
+    const host = (guest) => (root ? join(root, guest) : guest);
+    /** Rewrites guest paths named in a string to host paths (identity with no root). */
+    function mapperOf(config) {
+        if (!root)
+            return (s) => s;
+        const prefixes = new Set();
+        for (const m of config.mounts ?? [])
+            if (m.path)
+                prefixes.add(m.path.replace(/\/+$/, ""));
+        for (const f of config.files ?? [])
+            if (f.guest_path)
+                prefixes.add(dirname(f.guest_path));
+        prefixes.delete("");
+        prefixes.delete("/");
+        if (prefixes.size === 0)
+            return (s) => s;
+        const alts = [...prefixes].sort((a, b) => b.length - a.length).map(escape).join("|");
+        const re = new RegExp(`(^|[\\s=:'"(;&|])(${alts})(?=$|[/\\s'":;)&|])`, "g");
+        return (s) => s.replace(re, (_m, pre, path) => `${pre}${host(path)}`);
+    }
+    async function publishedPort(app, m) {
+        const env = m.config.env ?? {};
+        const internal = (m.config.services ?? []).map((s) => String(s.internal_port));
+        if (env.PORT === undefined || !internal.includes(String(env.PORT)))
+            return undefined;
+        const p = options.publish;
+        const declared = typeof p === "number" ? p : typeof p === "function" ? p(app, m) : p ? (p[`${app}/${m.name}`] ?? p[m.name]) : undefined;
+        if (declared !== undefined)
+            return declared;
+        const key = `${app}/${m.name}`;
+        if (!picked.has(key))
+            picked.set(key, await freePort());
+        return picked.get(key);
+    }
+    function envOf(config, port) {
+        const map = mapperOf(config);
+        const env = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/" };
+        for (const [k, v] of Object.entries(config.env ?? {}))
+            env[k] = map(String(v));
+        if (port !== undefined)
+            env.PORT = String(port);
+        return env;
+    }
+    function argvOf(config) {
+        const init = (config.init ?? {});
+        const map = mapperOf(config);
+        if (init.exec?.length)
+            return init.exec.map(map);
+        const cmd = typeof init.cmd === "string" ? ["sh", "-c", init.cmd] : (init.cmd ?? []);
+        const argv = [...(init.entrypoint ?? []), ...cmd];
+        return argv.length ? argv.map(map) : undefined;
+    }
+    const stdio = () => {
+        if (!options.log)
+            return { out: 2, close: () => undefined };
+        mkdirSync(dirname(options.log), { recursive: true });
+        const fd = openSync(options.log, "a");
+        return { out: fd, close: () => closeSync(fd) };
+    };
+    async function stop(key) {
+        const r = running.get(key);
+        if (!r)
+            return;
+        running.delete(key);
+        r.stopping = true;
+        const child = r.child;
+        if (child?.pid && groupAlive(child.pid)) {
+            const exited = child.exitCode === null && child.signalCode === null ? new Promise((ok) => child.once("exit", ok)) : Promise.resolve();
+            killGroup(child, "SIGTERM");
+            const deadline = Date.now() + stopTimeoutMs;
+            // Wait for the leader to exit and the rest of its group to go.
+            await Promise.race([exited, new Promise((ok) => setTimeout(ok, stopTimeoutMs))]);
+            while (groupAlive(child.pid) && Date.now() < deadline)
+                await new Promise((ok) => setTimeout(ok, 25));
+            // Sent again each round: one group kill can miss a child being forked as it lands (see killGroupNow).
+            while (groupAlive(child.pid)) {
+                killGroup(child, "SIGKILL");
+                await new Promise((ok) => setTimeout(ok, 25));
+            }
+        }
+        for (const path of r.files)
+            rmSync(path, { force: true });
+        say(`stopped ${key} (instance ${r.instance})`);
+    }
+    async function start(app, m) {
+        const key = `${app}/${m.id}`;
+        await stop(key);
+        const { config } = m;
+        for (const mount of config.mounts ?? [])
+            if (mount.path)
+                mkdirSync(host(mount.path), { recursive: true });
+        const files = [];
+        for (const f of config.files ?? []) {
+            const path = host(f.guest_path);
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, Buffer.from(f.raw_value ?? "", "base64"));
+            if (f.mode)
+                chmodSync(path, f.mode);
+            files.push(path);
+        }
+        const argv = argvOf(config);
+        const port = argv ? await publishedPort(app, m) : undefined;
+        const r = { app, id: m.id, name: m.name, instance: m.instance_id, files, child: undefined, port, stopping: false, exited: false };
+        running.set(key, r);
+        if (!argv) {
+            say(`started ${key} instance ${m.instance_id}: ${files.length} files, no command`);
+            return;
+        }
+        const log = stdio();
+        const child = spawn(argv[0], argv.slice(1), { cwd: root ?? "/", env: envOf(config, port), stdio: ["ignore", log.out, log.out], detached: true });
+        log.close();
+        child.unref();
+        r.child = child;
+        child.once("error", (error) => say(`${key} instance ${m.instance_id} failed to start: ${error.message}`));
+        child.once("exit", (code, signal) => {
+            r.exited = true;
+            if (r.stopping)
+                return;
+            say(`${key} instance ${m.instance_id} exited ${signal ?? code}`);
+            // A process that ends on its own leaves its Machine stopped, and its group is killed with it.
+            killGroupNow(child);
+            if (m.instance_id === r.instance && m.state === "started")
+                m.state = "stopped";
+        });
+        say(`started ${key} instance ${m.instance_id}: ${files.length} files, ${argv.join(" ")}${port ? `, on 127.0.0.1:${port}` : ""}`);
+        if (port !== undefined) {
+            const deadline = Date.now() + readyTimeoutMs;
+            while (!r.exited && Date.now() < deadline && !(await connects(port)))
+                await new Promise((ok) => setTimeout(ok, 50));
+            if (!r.exited && Date.now() >= deadline)
+                say(`${key} instance ${m.instance_id} is not accepting connections on ${port} after ${readyTimeoutMs}ms`);
+        }
+    }
+    async function exec(app, m, command, timeoutSecs) {
+        const map = mapperOf(m.config);
+        const argv = command.map(map);
+        const port = running.get(`${app}/${m.id}`)?.port;
+        return new Promise((done) => {
+            const child = spawn(argv[0], argv.slice(1), { cwd: root ?? "/", env: envOf(m.config, port), stdio: ["ignore", "pipe", "pipe"], detached: true });
+            let stdout = "";
+            let stderr = "";
+            child.stdout.on("data", (d) => (stdout += d));
+            child.stderr.on("data", (d) => (stderr += d));
+            // killGroupNow: a child missed by one group kill would hold the output pipes, and "close" would wait for it.
+            const timer = setTimeout(() => killGroupNow(child), timeoutSecs * 1000);
+            child.once("error", (error) => {
+                clearTimeout(timer);
+                done({ exit_code: 127, stdout, stderr: `${stderr}${error.message}` });
+            });
+            child.once("close", (code, signal) => {
+                clearTimeout(timer);
+                const exit = code ?? (signal ? 128 : 1);
+                say(`exec on ${app}/${m.id}: ${command.join(" ")} exited ${signal ?? code}${exit === 0 ? "" : `: ${`${stderr}${stdout}`.trim().slice(-500)}`}`);
+                done({ exit_code: exit, stdout, stderr });
+            });
+        });
+    }
+    /** The exec timeout the last exec call asked for, read before the fake answers it. */
+    let execTimeout = 120;
+    const fake = createMachinesFake({
+        settle: options.settle,
+        exec: (app, m, command) => exec(app, m, command, execTimeout),
+    });
+    /** Make what runs match the fake's Machines after a call; `restarted` names a Machine (`app/id`) whose process starts again. */
+    async function reconcile(restarted) {
+        const live = new Set();
+        for (const [app, machines] of fake.machines) {
+            for (const m of machines) {
+                const key = `${app}/${m.id}`;
+                live.add(key);
+                const r = running.get(key);
+                if (m.state !== "started")
+                    await stop(key);
+                else if (!r || r.exited || r.instance !== m.instance_id || key === restarted)
+                    await start(app, m);
+            }
+        }
+        for (const key of [...running.keys()])
+            if (!live.has(key))
+                await stop(key);
+    }
+    // One call at a time, so a start never races the next call.
+    let queue = Promise.resolve();
+    const http = (method, url, body, headers, signal) => {
+        const next = queue.then(async () => {
+            const seg = new URL(url).pathname.split("/").filter(Boolean).map(decodeURIComponent);
+            if (method === "POST" && seg[3] === "machines" && seg[5] === "exec") {
+                const t = Number(body?.timeout);
+                execTimeout = Number.isFinite(t) && t > 0 ? t : 120;
+            }
+            const out = await fake.http(method, url, body, headers, signal);
+            if (method !== "GET" && !(seg[5] === "exec" || seg[5] === "lease" || seg[5] === "wait")) {
+                const restarted = method === "POST" && seg[3] === "machines" && seg[5] === "restart" && out.status < 300 ? `${seg[2]}/${seg[4]}` : undefined;
+                await reconcile(restarted);
+            }
+            return out;
+        });
+        queue = next.catch(() => undefined);
+        return next;
+    };
+    // Nothing is left running when this process ends: on exit, and on a signal (which is then raised again, so it still ends the process).
+    const killAll = () => {
+        for (const r of running.values()) {
+            r.stopping = true;
+            killGroupNow(r.child);
+        }
+    };
+    const onSignal = (sig) => {
+        killAll();
+        detach();
+        if (process.listenerCount(sig) === 0)
+            process.kill(process.pid, sig);
+    };
+    const detach = () => {
+        process.off("exit", killAll);
+        for (const s of SIGNALS)
+            process.off(s, onSignal);
+    };
+    process.on("exit", killAll);
+    if (options.handleSignals !== false)
+        for (const s of SIGNALS)
+            process.on(s, onSignal);
+    return {
+        ...fake,
+        http,
+        endpoint(app, name) {
+            const m = fake.machine(app, name);
+            const r = m ? running.get(`${app}/${m.id}`) : undefined;
+            const port = r && !r.exited ? r.port : undefined;
+            return port === undefined ? undefined : `http://127.0.0.1:${port}`;
+        },
+        processes: () => [...running.values()].filter((r) => !r.exited).map((r) => ({ app: r.app, id: r.id, name: r.name, instance: r.instance, pid: r.child?.pid, port: r.port })),
+        async close() {
+            await queue;
+            for (const key of [...running.keys()])
+                await stop(key);
+            detach();
+        },
+    };
+}
+/**
+ * Serve {@link createLocalMachines} over HTTP, where the release activities
+ * reach it through `FLY_FLAPS_BASE_URL`. `GET /_mudflaps/health` answers 200,
+ * as mudflaps' health check does.
+ */
+export async function serveLocalMachines(options = {}) {
+    const machines = createLocalMachines(options);
+    const hostname = options.host ?? "127.0.0.1";
+    const server = createHttpServer((req, res) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => {
+            void (async () => {
+                let out;
+                try {
+                    if (req.method === "GET" && req.url === "/_mudflaps/health")
+                        out = { status: 200, text: JSON.stringify({ status: "ok" }) };
+                    else {
+                        const text = Buffer.concat(chunks).toString("utf-8");
+                        out = await machines.http(req.method ?? "GET", `http://${hostname}${req.url}`, text ? JSON.parse(text) : undefined, {});
+                    }
+                }
+                catch (error) {
+                    out = { status: 500, text: JSON.stringify({ error: error.message }) };
+                }
+                res.writeHead(out.status, out.text ? { "content-type": "application/json" } : {});
+                res.end(out.text);
+            })();
+        });
+    });
+    await new Promise((ok, fail) => server.once("error", fail).listen(options.port ?? 4280, hostname, ok));
+    const { port } = server.address();
+    return {
+        url: `http://${hostname}:${port}`,
+        machines,
+        async close() {
+            await machines.close();
+            await new Promise((ok) => server.close(() => ok()));
+        },
+    };
+}

package/dist/op/activities/progress.js

@@ -0,0 +1,10 @@
+/**
+ * Progress output for the fly Op activities (#2516, #3200).
+ *
+ * An Op step's stdout is its output, so activities write their progress lines
+ * ("created: sprite/x", "pruned: ...") to stderr and keep stdout free for
+ * machine-readable results.
+ */
+export function logProgress(line) {
+    process.stderr.write(`${line}\n`);
+}