@intentius/chant-lexicon-fly 0.90.0 → 0.93.0

package/src/op/activities/machines-fake.ts

@@ -0,0 +1,167 @@
+/**
+ * An in-memory Fly Machines (flaps) API, as a {@link FlyHttp} (#2736).
+ *
+ * The twin of ./sprites-fake.ts for the Machines side: the endpoints the
+ * applier (./fly-apply.ts) and the release activities (./machine-release.ts)
+ * call, answered from memory with the response shapes flaps and mudflaps use.
+ * Unit tests inject it where the default client would reach the network; the
+ * docker-gated tests run the same activities against the pinned mudflaps.
+ * It runs nothing; ./machines-local.ts is the opt-in mode that runs each
+ * started Machine's files and command on this host (#2831).
+ *
+ * Not an activity: nothing in ./index.ts exports it, so `loadActivities`
+ * never binds it.
+ */
+
+import type { FlyHttp } from "./fly-apply";
+
+/** One Machine the fake holds. */
+export interface FakeMachine {
+  id: string;
+  name: string;
+  state: string;
+  instance_id: string;
+  config: Record<string, unknown> & { metadata?: Record<string, string> };
+}
+
+/** What an `exec` answers: the Machines API's exec envelope. */
+export interface FakeExecResult {
+  exit_code: number;
+  stdout?: string;
+  stderr?: string;
+}
+
+export interface MachinesFake {
+  http: FlyHttp;
+  apps: Set<string>;
+  machines: Map<string, FakeMachine[]>;
+  /** Every exec, in order: the app, the machine id and the command. */
+  execs: Array<{ app: string; id: string; command: string[] }>;
+  /** Every call, as `METHOD path` (no base, no query). */
+  calls: string[];
+  /** The live machine named `name` in `app`, if any. */
+  machine(app: string, name: string): FakeMachine | undefined;
+}
+
+export interface MachinesFakeOptions {
+  /** Answer an exec. Default: exit 0 with no output. The running mode (./machines-local.ts) answers it by running the command. */
+  exec?: (app: string, machine: FakeMachine, command: string[]) => FakeExecResult | Promise<FakeExecResult>;
+  /** The state a created or updated machine settles in. Default `started`. */
+  settle?: (machine: FakeMachine) => string;
+}
+
+const json = (status: number, body: unknown) => ({ status, text: body === undefined ? "" : JSON.stringify(body) });
+
+let seq = 0;
+const nextId = (prefix: string) => `${prefix}${(++seq).toString(16).padStart(10, "0")}`;
+
+/** A fresh in-memory flaps. */
+export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesFake {
+  const apps = new Set<string>();
+  const machines = new Map<string, FakeMachine[]>();
+  const execs: MachinesFake["execs"] = [];
+  const calls: string[] = [];
+  const settle = options.settle ?? (() => "started");
+  const list = (app: string) => machines.get(app) ?? [];
+  const find = (app: string, id: string) => list(app).find((m) => m.id === id);
+
+  const http: FlyHttp = async (method, url, body) => {
+    const { pathname, searchParams } = new URL(url);
+    calls.push(`${method} ${pathname}`);
+    const seg = pathname.split("/").filter(Boolean).map(decodeURIComponent);
+    // seg: ["v1", "apps", app?, kind?, id?, action?]
+    if (seg[0] !== "v1" || seg[1] !== "apps") return json(404, { error: "not found" });
+    const app = seg[2];
+    const b = (body ?? {}) as Record<string, unknown>;
+
+    if (!app) {
+      if (method === "POST") {
+        const name = String(b.app_name);
+        if (apps.has(name)) return json(409, { error: "app exists" });
+        apps.add(name);
+        return json(201, { name, status: "deployed" });
+      }
+      return json(200, [...apps].map((name) => ({ name })));
+    }
+    if (seg.length === 3) {
+      if (method === "GET") return apps.has(app) ? json(200, { name: app, status: "deployed" }) : json(404, { error: "app not found" });
+      if (method === "DELETE") {
+        apps.delete(app);
+        machines.delete(app);
+        return json(202, undefined);
+      }
+    }
+    if (!apps.has(app)) return json(404, { error: "app not found" });
+    const kind = seg[3];
+
+    if (kind === "machines") {
+      const id = seg[4];
+      const action = seg[5];
+      if (!id) {
+        if (method === "GET") return json(200, list(app));
+        if (method === "POST") {
+          const m: FakeMachine = {
+            id: nextId("m"),
+            name: String(b.name ?? ""),
+            state: "created",
+            instance_id: nextId("I"),
+            config: structuredClone((b.config ?? {}) as FakeMachine["config"]),
+          };
+          m.state = settle(m);
+          machines.set(app, [...list(app), m]);
+          return json(200, m);
+        }
+      }
+      const m = id ? find(app, id) : undefined;
+      if (!m) return action === "wait" ? json(200, { ok: true }) : json(404, { error: "machine not found" });
+      if (!action) {
+        if (method === "GET") return json(200, m);
+        if (method === "POST") {
+          m.config = structuredClone((b.config ?? {}) as FakeMachine["config"]);
+          m.instance_id = nextId("I");
+          m.state = settle(m);
+          return json(200, m);
+        }
+        if (method === "DELETE") {
+          machines.set(app, list(app).filter((x) => x !== m));
+          return json(200, { ok: true });
+        }
+      }
+      if (action === "lease") {
+        if (method === "POST") return json(200, { data: { nonce: nextId("n") } });
+        return json(200, { ok: true });
+      }
+      if (action === "wait") {
+        const want = searchParams.get("state") ?? "started";
+        return json(200, { ok: m.state === want });
+      }
+      if (action === "restart" || action === "start") {
+        m.state = "started";
+        return json(200, { ok: true });
+      }
+      if (action === "stop") {
+        m.state = "stopped";
+        return json(200, { ok: true });
+      }
+      if (action === "exec" && method === "POST") {
+        const command = (b.command as string[] | undefined) ?? String(b.cmd ?? "").split(" ");
+        execs.push({ app, id: m.id, command });
+        return json(200, (await options.exec?.(app, m, command)) ?? { exit_code: 0, stdout: "", stderr: "" });
+      }
+      return json(404, { error: `no ${method} ${action}` });
+    }
+    if (kind === "ip_assignments") return method === "GET" ? json(200, { ips: [] }) : json(200, {});
+    if (kind === "certificates") return method === "GET" ? json(200, { certificates: [] }) : json(200, {});
+    if (kind === "volumes" || kind === "secrets") return method === "GET" ? json(200, []) : json(200, {});
+    return json(404, { error: "not found" });
+  };
+
+  return {
+    http,
+    apps,
+    machines,
+    execs,
+    calls,
+    machine: (app, name) => list(app).find((m) => m.name === name && !["destroyed", "destroying"].includes(m.state)),
+  };
+}

package/src/op/activities/machines-local-cli.ts

@@ -0,0 +1,73 @@
+/**
+ * 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, type LocalPublish } from "./machines-local";
+
+export function parseArgs(argv: string[]): { port: number; root?: string; publish?: LocalPublish; log?: string } {
+  let port = 4280;
+  let root: string | undefined;
+  let log: string | undefined;
+  let all: number | undefined;
+  const byName: Record<string, number> = {};
+  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: LocalPublish | undefined =
+    named ? (app, m) => byName[`${app}/${m.name}`] ?? byName[m.name] ?? all : all;
+  return { port, root, publish, log };
+}
+
+async function main(): Promise<void> {
+  let args: ReturnType<typeof parseArgs>;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`machines-local: ${(error as Error).message}`);
+    console.error("usage: machines-local-cli.ts [--listen <port>] [--root <dir>] [--publish <port> | --publish <name>=<port>]... [--log <file>]");
+    process.exit(2);
+  }
+  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/src/op/activities/machines-local.test.ts

@@ -0,0 +1,225 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createLocalMachines, serveLocalMachines } from "./machines-local";
+import { parseArgs } from "./machines-local-cli";
+import { flyMachineExec, flyMachineRelease, flyMachineRestore, flyMachineStop, type MachineFile } from "./machine-release";
+import type { FlyPlan } from "./fly-apply";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(here, "../../../../..");
+const tsxLoader = pathToFileURL(join(repoRoot, "node_modules/tsx/dist/loader.mjs")).href;
+
+/** A tiny app: serves page.txt and, when a migration has written it, /data/state. */
+const SERVER = `
+import { createServer } from "node:http";
+import { readFileSync, existsSync } from "node:fs";
+const state = () => (existsSync(process.env.DATA + "/state") ? readFileSync(process.env.DATA + "/state", "utf8").trim() : "none");
+createServer((req, res) => res.end(readFileSync(new URL("./page.txt", import.meta.url), "utf8").trim() + " " + state())).listen(Number(process.env.PORT), "127.0.0.1");
+`;
+
+const b64 = (s: string) => Buffer.from(s).toString("base64");
+const files = (page: string): MachineFile[] => [
+  { guest_path: "/srv/app/server.mjs", raw_value: b64(SERVER) },
+  { guest_path: "/srv/app/page.txt", raw_value: b64(page) },
+];
+const config = (page: string) => ({
+  image: "node:22-slim",
+  env: { PORT: "8080", DATA: "/data" },
+  services: [{ protocol: "tcp", internal_port: 8080 }],
+  mounts: [{ volume: "data", path: "/data" }],
+  files: files(page),
+  init: { cmd: ["sh", "-c", "cd /srv/app && exec node server.mjs"] },
+});
+
+/** Is `pid` running, as `ps` sees it? */
+const alive = (pid: number) => spawnSync("ps", ["-p", String(pid)]).status === 0;
+const get = async (url: string) => (await fetch(url)).text();
+
+let dirs: string[] = [];
+let open: Array<{ close(): Promise<void> }> = [];
+const tmp = () => {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), "chant-machines-local-")));
+  dirs.push(d);
+  return d;
+};
+afterEach(async () => {
+  for (const o of open) await o.close();
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  open = [];
+  dirs = [];
+});
+
+describe("the running mode of the local Machines API (#2831)", () => {
+  test("runs a Machine's files and command, serves it, restarts it on a new config, and stops it with no process left", { timeout: 60_000 }, async () => {
+    const root = tmp();
+    const served = await serveLocalMachines({ port: 0, root, log: join(root, "machines.log") });
+    open.push(served);
+    const machines = served.machines;
+    const call = async (method: string, path: string, body?: unknown) => {
+      const res = await fetch(`${served.url}${path}`, { method, body: body === undefined ? undefined : JSON.stringify(body), headers: { "content-type": "application/json" } });
+      const text = await res.text();
+      return { status: res.status, json: text ? JSON.parse(text) : undefined };
+    };
+
+    expect((await call("GET", "/_mudflaps/health")).status).toBe(200);
+    await call("POST", "/v1/apps", { app_name: "shop", org_slug: "personal" });
+    const created = await call("POST", "/v1/apps/shop/machines", { name: "web", config: config("A") });
+    expect(created.status).toBe(200);
+    const id = created.json.id as string;
+
+    const url = machines.endpoint("shop", "web");
+    expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    expect(await get(url!)).toBe("A none");
+    // The files are under root, the guest paths the command named mapped there.
+    expect(readFileSync(join(root, "srv/app/page.txt"), "utf8")).toBe("A");
+    const [first] = machines.processes();
+    expect(first).toMatchObject({ app: "shop", name: "web", id });
+    expect(alive(first.pid!)).toBe(true);
+
+    // An exec runs in the Machine's env, against the Volume the app reads.
+    const exec = await call("POST", `/v1/apps/shop/machines/${id}/exec`, { command: ["sh", "-c", "echo migrated > $DATA/state && echo done"], timeout: 30 });
+    expect(exec.json).toMatchObject({ exit_code: 0, stdout: "done\n" });
+    expect(await get(url!)).toBe("A migrated");
+
+    // A new config is a new instance: the process starts again on the new files, on the same port, and the Volume is kept.
+    const updated = await call("POST", `/v1/apps/shop/machines/${id}`, { config: config("B") });
+    expect(updated.json.instance_id).not.toBe(created.json.instance_id);
+    const [second] = machines.processes();
+    expect(second.pid).not.toBe(first.pid);
+    expect(alive(first.pid!)).toBe(false);
+    expect(machines.endpoint("shop", "web")).toBe(url);
+    expect(await get(url!)).toBe("B migrated");
+
+    // A restart runs it again.
+    await call("POST", `/v1/apps/shop/machines/${id}/restart`);
+    const [third] = machines.processes();
+    expect(third.pid).not.toBe(second.pid);
+    expect(alive(second.pid!)).toBe(false);
+    expect(await get(url!)).toBe("B migrated");
+
+    // A stop leaves nothing running and removes the instance's files; the Volume stays.
+    await call("POST", `/v1/apps/shop/machines/${id}/stop`);
+    expect(machines.processes()).toEqual([]);
+    expect(alive(third.pid!)).toBe(false);
+    expect(machines.endpoint("shop", "web")).toBeUndefined();
+    expect(existsSync(join(root, "srv/app/page.txt"))).toBe(false);
+    expect(readFileSync(join(root, "data/state"), "utf8")).toBe("migrated\n");
+
+    // Start, then delete: running again, then gone.
+    await call("POST", `/v1/apps/shop/machines/${id}/start`);
+    const [fourth] = machines.processes();
+    expect(await get(url!)).toBe("B migrated");
+    await call("DELETE", `/v1/apps/shop/machines/${id}`);
+    expect(machines.processes()).toEqual([]);
+    expect(alive(fourth.pid!)).toBe(false);
+  });
+
+  test("the release activities: release A, a migration, release B, then A restored serves A again", { timeout: 60_000 }, async () => {
+    const root = tmp();
+    const machines = createLocalMachines({ root });
+    open.push(machines);
+    const endpoint = "http://flaps.local";
+    const wait = { intervalMs: 20, deadlineMs: 10_000 };
+    const plan: FlyPlan = {
+      shop: { endpoint: "/v1/apps", method: "POST", body: { app_name: "shop", org_slug: "personal" } },
+      web: {
+        endpoint: "/v1/apps/shop/machines",
+        method: "POST",
+        body: { name: "web", config: { image: "node:22-slim", env: { PORT: "8080", DATA: "/data" }, services: [{ internal_port: 8080 }], mounts: [{ volume: "data", path: "/data" }] } },
+      },
+    };
+    const release = (page: string, digest: string) =>
+      flyMachineRelease({ plan, endpoint, release: { digest }, files: files(page), cmd: "cd /srv/app && exec node server.mjs", wait }, undefined, machines.http);
+
+    const a = await release("A", "sha256:a");
+    const url = machines.endpoint("shop", "web")!;
+    expect(await get(url)).toBe("A none");
+    await flyMachineExec({ app: "shop", machine: "web", command: "echo v1 > /data/state", endpoint }, undefined, machines.http);
+    expect(await get(url)).toBe("A v1");
+
+    await release("B", "sha256:b");
+    expect(await get(url)).toBe("B v1");
+
+    await flyMachineRestore({ app: "shop", machine: "web", config: a.config, endpoint, wait }, undefined, machines.http);
+    expect(await get(url)).toBe("A v1");
+
+    const [p] = machines.processes();
+    await flyMachineStop({ app: "shop", machine: "web", endpoint, wait }, undefined, machines.http);
+    expect(machines.processes()).toEqual([]);
+    expect(alive(p.pid!)).toBe(false);
+  });
+
+  test("a process that exits on its own leaves its Machine stopped", { timeout: 30_000 }, async () => {
+    const machines = createLocalMachines({ root: tmp(), log: join(tmp(), "log") });
+    open.push(machines);
+    await machines.http("POST", "http://f/v1/apps", { app_name: "shop" });
+    const r = await machines.http("POST", "http://f/v1/apps/shop/machines", { name: "web", config: { init: { cmd: ["sh", "-c", "exit 3"] } } });
+    const id = JSON.parse(r.text).id as string;
+    for (let i = 0; i < 100 && machines.machine("shop", "web")!.state === "started"; i++) await new Promise((ok) => setTimeout(ok, 20));
+    expect(machines.machine("shop", "web")!.state).toBe("stopped");
+    expect(machines.processes()).toEqual([]);
+    expect(JSON.parse((await machines.http("GET", `http://f/v1/apps/shop/machines/${id}/wait?state=started`)).text)).toEqual({ ok: false });
+  });
+
+  test("with no root, guest paths are host paths", async () => {
+    const dir = tmp();
+    const machines = createLocalMachines({ log: join(dir, "log") });
+    open.push(machines);
+    await machines.http("POST", "http://f/v1/apps", { app_name: "shop" });
+    await machines.http("POST", "http://f/v1/apps/shop/machines", {
+      name: "web",
+      config: { files: [{ guest_path: join(dir, "a/b.txt"), raw_value: b64("hi") }] },
+    });
+    expect(readFileSync(join(dir, "a/b.txt"), "utf8")).toBe("hi");
+  });
+
+  for (const how of ["SIGTERM", "SIGINT", "exit"] as const) {
+    test(`a Machine's process does not outlive its host process (${how})`, { timeout: 60_000 }, async () => {
+      const root = tmp();
+      const script = join(root, "host.mts");
+      writeFileSync(
+        script,
+        `import { createLocalMachines } from ${JSON.stringify(join(here, "machines-local.ts"))};
+const m = createLocalMachines({ root: ${JSON.stringify(root)}, log: ${JSON.stringify(join(root, "log"))} });
+await m.http("POST", "http://f/v1/apps", { app_name: "shop" });
+await m.http("POST", "http://f/v1/apps/shop/machines", { name: "web", config: { init: { cmd: ["sh", "-c", "sleep 300 & exec sleep 301"] } } });
+console.log(JSON.stringify(m.processes()[0].pid));
+${how === "exit" ? "setTimeout(() => process.exit(0), 100);" : "setInterval(() => undefined, 1000);"}
+`,
+      );
+      const host = spawn(process.execPath, ["--import", tsxLoader, script], {
+        stdio: ["ignore", "pipe", "inherit"],
+        // tsx's on-disk cache can stall for seconds under load; this script is too small to need it.
+        env: { ...process.env, TSX_DISABLE_CACHE: "1" },
+      });
+      const pid = await new Promise<number>((ok) => host.stdout!.once("data", (d) => ok(Number(String(d).trim()))));
+      expect(alive(pid)).toBe(true);
+      const exited = new Promise((ok) => host.once("exit", ok));
+      if (how !== "exit") host.kill(how);
+      await exited;
+      for (let i = 0; i < 50 && alive(pid); i++) await new Promise((ok) => setTimeout(ok, 20));
+      expect(alive(pid)).toBe(false);
+      // Nor does anything the command started in its group.
+      const left = spawnSync("pgrep", ["-g", String(pid)], { encoding: "utf8" }).stdout.trim();
+      expect(left).toBe("");
+    });
+  }
+});
+
+describe("machines-local-cli args", () => {
+  test("--publish takes one port for every Machine, or name=port", () => {
+    expect(parseArgs([])).toMatchObject({ port: 4280, publish: undefined });
+    expect(parseArgs(["--listen", "4999", "--root", "/r", "--publish", "8080"])).toMatchObject({ port: 4999, root: "/r", publish: 8080 });
+    const { publish } = parseArgs(["--publish", "web=8080", "--publish", "shop/api=9090"]);
+    const fn = publish as (app: string, m: { name: string }) => number | undefined;
+    expect(fn("shop", { name: "web" })).toBe(8080);
+    expect(fn("shop", { name: "api" })).toBe(9090);
+    expect(fn("shop", { name: "other" })).toBeUndefined();
+    expect(() => parseArgs(["--publish"])).toThrow(/needs a value/);
+    expect(() => parseArgs(["--nope", "1"])).toThrow(/unknown flag/);
+  });
+});