@intentius/chant-lexicon-fly 0.124.67 → 0.124.68

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

@@ -22,6 +22,19 @@ export interface FakeMachine {
   state: string;
   instance_id: string;
   config: Record<string, unknown> & { metadata?: Record<string, string> };
+  /** When the machine was last created or updated (RFC 3339), as flaps reports it. */
+  updated_at?: string;
+}
+
+/** One volume the fake holds, as flaps lists it. */
+export interface FakeVolume {
+  id: string;
+  name: string;
+  region?: string;
+  size_gb?: number;
+  state: string;
+  /** The Machine whose config mounts it by id; null when none does. */
+  attached_machine_id: string | null;
 }
 
 /** What an `exec` answers: the Machines API's exec envelope. */
@@ -35,6 +48,8 @@ export interface MachinesFake {
   http: FlyHttp;
   apps: Set<string>;
   machines: Map<string, FakeMachine[]>;
+  /** Each app's volumes, in creation order, with ids `vol_...` (#4717). */
+  volumes: Map<string, FakeVolume[]>;
   /** Each app's certificate hostnames, in creation order. */
   certs: Map<string, string[]>;
   /** Every exec, in order: the app, the machine id and the command. */
@@ -50,6 +65,23 @@ export interface MachinesFakeOptions {
   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;
+  /** The clock a create or update stamps `updated_at` with. Default: the wall clock. */
+  now?: () => Date;
+  /**
+   * The Fly checks a machine reports each time it is read (#4719), as the
+   * Machines API's `checks`: asked on every GET of the machine or its list.
+   * Default: none.
+   */
+  checks?: (app: string, machine: FakeMachine) => FakeCheck[] | undefined;
+}
+
+/** One Fly check's status on a machine, as the Machines API reports it. */
+export interface FakeCheck {
+  name: string;
+  status: "passing" | "warning" | "critical";
+  output?: string;
+  /** When the check last reported (RFC 3339). */
+  updated_at?: string;
 }
 
 const json = (status: number, body: unknown) => ({ status, text: body === undefined ? "" : JSON.stringify(body) });
@@ -75,12 +107,30 @@ const nextId = (prefix: string) => `${prefix}${(++seq).toString(16).padStart(10,
 export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesFake {
   const apps = new Set<string>();
   const machines = new Map<string, FakeMachine[]>();
+  const volumes = new Map<string, FakeVolume[]>();
   const certs = new Map<string, string[]>();
   const execs: MachinesFake["execs"] = [];
   const calls: string[] = [];
   const settle = options.settle ?? (() => "started");
+  const stamp = () => (options.now?.() ?? new Date()).toISOString();
   const list = (app: string) => machines.get(app) ?? [];
   const find = (app: string, id: string) => list(app).find((m) => m.id === id);
+  const withChecks = (app: string, m: FakeMachine) => {
+    const checks = options.checks?.(app, m);
+    return checks ? { ...m, checks } : m;
+  };
+  const vols = (app: string) => volumes.get(app) ?? [];
+  // A volume is attached to the Machine whose config mounts its id, as Fly
+  // attaches it. A mount naming no volume id attaches nothing.
+  const attach = (app: string, m: FakeMachine | undefined, id: string) => {
+    const mounted = new Set(
+      ((m?.config.mounts as Array<{ volume?: unknown }> | undefined) ?? []).map((x) => x.volume).filter((v) => typeof v === "string"),
+    );
+    for (const v of vols(app)) {
+      if (v.attached_machine_id === id && !mounted.has(v.id)) v.attached_machine_id = null;
+      if (m && mounted.has(v.id)) v.attached_machine_id = id;
+    }
+  };
 
   const http: FlyHttp = async (method, url, body) => {
     const { pathname, searchParams } = new URL(url);
@@ -105,6 +155,7 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
       if (method === "DELETE") {
         apps.delete(app);
         machines.delete(app);
+        volumes.delete(app);
         certs.delete(app);
         return json(202, undefined);
       }
@@ -116,7 +167,7 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
       const id = seg[4];
       const action = seg[5];
       if (!id) {
-        if (method === "GET") return json(200, list(app));
+        if (method === "GET") return json(200, list(app).map((m) => withChecks(app, m)));
         if (method === "POST") {
           const m: FakeMachine = {
             id: nextId("m"),
@@ -124,20 +175,24 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
             state: "created",
             instance_id: nextId("I"),
             config: structuredClone((b.config ?? {}) as FakeMachine["config"]),
+            updated_at: stamp(),
           };
           // skip_launch: the Machine is created and not booted (#4696).
           m.state = b.skip_launch === true ? "created" : settle(m);
           machines.set(app, [...list(app), m]);
+          attach(app, m, m.id);
           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 === "GET") return json(200, withChecks(app, m));
         if (method === "POST") {
           m.config = structuredClone((b.config ?? {}) as FakeMachine["config"]);
           m.instance_id = nextId("I");
+          m.updated_at = stamp();
+          attach(app, m, m.id);
           // skip_launch: the new config isn't started (#4696). A Machine that
           // never ran stays created; one that ran is stopped.
           m.state = b.skip_launch === true ? (m.state === "created" ? "created" : "stopped") : settle(m);
@@ -152,6 +207,7 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
             });
           }
           machines.set(app, list(app).filter((x) => x !== m));
+          attach(app, undefined, m.id);
           return json(200, { ok: true });
         }
       }
@@ -180,10 +236,39 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
     }
     if (kind === "ip_assignments") return method === "GET" ? json(200, { ips: [] }) : json(200, {});
     if (kind === "certificates") return certificates(app, method, seg.slice(4), b, searchParams);
-    if (kind === "volumes" || kind === "secrets") return method === "GET" ? json(200, []) : json(200, {});
+    if (kind === "volumes") return volumeCall(app, method, seg[4], b);
+    if (kind === "secrets") return method === "GET" ? json(200, []) : json(200, {});
     return json(404, { error: "not found" });
   };
 
+  // Volumes (#4717): created with a `vol_` id, listed with their region and
+  // the Machine they are attached to, read and deleted by id.
+  function volumeCall(app: string, method: string, id: string | undefined, b: Record<string, unknown>) {
+    if (!id) {
+      if (method === "GET") return json(200, vols(app));
+      if (method === "POST") {
+        const v: FakeVolume = {
+          id: nextId("vol_"),
+          name: String(b.name ?? ""),
+          ...(typeof b.region === "string" ? { region: b.region } : {}),
+          ...(typeof b.size_gb === "number" ? { size_gb: b.size_gb } : {}),
+          state: "created",
+          attached_machine_id: null,
+        };
+        volumes.set(app, [...vols(app), v]);
+        return json(200, v);
+      }
+    }
+    const v = vols(app).find((x) => x.id === id);
+    if (!v) return json(404, { error: "volume not found" });
+    if (method === "GET") return json(200, v);
+    if (method === "DELETE") {
+      volumes.set(app, vols(app).filter((x) => x !== v));
+      return json(200, { ...v, state: "destroyed" });
+    }
+    return json(404, { error: `no ${method} on a volume` });
+  }
+
   // Certificates, as the real API routes them (#3114): listed at
   // `.../certificates`, created only at `.../certificates/acme`, read and
   // deleted at `.../certificates/{hostname}`. A POST to the bare list path is
@@ -229,6 +314,7 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
     http,
     apps,
     machines,
+    volumes,
     certs,
     execs,
     calls,

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

@@ -127,6 +127,7 @@ describe("the running mode of the local Machines API (#2831)", () => {
     const wait = { intervalMs: 20, deadlineMs: 10_000 };
     const plan: FlyPlan = {
       shop: { endpoint: "/v1/apps", method: "POST", body: { app_name: "shop", org_slug: "personal" } },
+      data: { endpoint: "/v1/apps/shop/volumes", method: "POST", body: { name: "data", region: "iad", size_gb: 1 } },
       web: {
         endpoint: "/v1/apps/shop/machines",
         method: "POST",

package/src/skills/chant-fly-ops.md

@@ -89,13 +89,37 @@ export const web: Component = {
 };
 ```
 
-The step updates the Machine in place with the release in its `config.metadata`: `chant-release-digest`, `chant-release-git-sha` (the commit, `git rev-parse HEAD` unless given), and `chant-release-previous-digest` (the release it replaced). Each migration then runs inside the Machine through the Machines API's exec, once per environment: its receipt is kept on `chant/lifecycle` at `<env>/receipts/`, and a migration fires again only when its `sha` (or command) changes. After a migration fires, the Machine restarts, and the step checks that it is started with this release and, given a `url`, that its health endpoint answers with this commit or digest. If anything fails after the Machine changed, the step puts back the config the Machine served before (on a first release, it stops the Machine) and fails.
+The step updates the Machine in place with the release in its `config.metadata`: `chant-release-digest`, `chant-release-git-sha` (the commit, `git rev-parse HEAD` unless given), and `chant-release-previous-digest` (the release it replaced). Each migration then runs inside the Machine through the Machines API's exec, once per environment: its receipt is kept on `chant/lifecycle` at `<env>/receipts/`, and a migration fires again only when its `sha` (or command) changes. After a migration fires, the Machine restarts, and the step checks that it is started with this release and, given a `url`, that its health endpoint answers with this commit or digest. If anything fails after the Machine changed, the step puts back the config the Machine served before (on a first release, it stops the Machine) and fails. That includes an apply that fails partway: the Machines it had already updated go back too.
 
 The step's output carries `uri` and `digest`, so `chant run --components web --env prod` records the release in the ledger. `chant components status prod --live` reads the Machine's metadata back and compares its digest with the ledger's: the row is `reconciled` when they agree and `drifted` when the Machine serves something the ledger does not name. The component joins the Machine by name: name the component after the Machine entity, or list it in `liveNames`.
 
 Each release's Machine config is kept on `chant/lifecycle` at `<env>/fly/<app>/<machine>/<digest>.json`. `fly-rollback` puts back the config of the release the serving one replaced (or the digest given as `to`), checks it, and outputs that digest so the ledger records it again. `fly-release`'s own saga compensation does the same.
 
-The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once.
+### Several serving Machines with Fly checks
+
+An app served by more than one Machine, such as two Machines behind Flycast with no public address, declares them all in the plan. `fly-release` releases the one named by `machine` and gives the others their image through `images`:
+
+```ts
+{
+  kind: "fly-release",
+  plan: "dist/fly.json",
+  machine: "platform-1",
+  digest: "@Publish.digest",
+  image: "@Publish.uri",
+  images: { "platform-2": "@Publish.uri" },
+  checks: { timeoutMs: 300_000 },
+}
+```
+
+Without `checks`, the apply updates the Machines in plan order and waits for each to be `started` only, and verify reads the serving Machine alone.
+
+With `checks`, the apply updates the Machines one at a time, as `fly deploy` does. Once a Machine is started, the step reads its Fly checks from the Machines API (`checks[].status` on the Machine) until every one is `passing`, and only then updates the next Machine. A check counts only when its `updated_at` is at or after the Machine's own `updated_at` as the update call answered it, so a `passing` left over from before the update does not count. Both times are flaps' own, so the local clock plays no part; a check with no `updated_at` counts on its status. A Machine whose config declares checks that have not reported yet is still waiting. `checks.timeoutMs` (default 300000, five minutes) bounds the wait for each Machine, and `checks.intervalMs` (default 1000) is how often it looks; `checks: true` takes both defaults. A Machine with no checks configured is done once it is started, and a scheduled Machine is not waited for. The wait comes right after each Machine's update, before migrations run, so a release whose new code can't pass its checks until a migration has run should leave `checks` off.
+
+Under `checks`, a Machine whose checks do not pass in time fails the release with an error naming the Machine and each check that is not passing, for example `machine platform/platform-2 (e784...) did not pass its Fly checks within 300s: check servicecheck-00-http-8080 is critical (503 Service Unavailable)`. The Machines after it are left alone. Every Machine the release changed goes back to its old config, the last one changed first, and each restore waits for its Machine to be started with its checks passing before the next one. On a first release the serving Machine is stopped instead.
+
+Under `checks`, verify then covers every Machine the release started: the serving one is started with this release and its checks passing (and its health URL answering, when given), and each other one is started with its checks passing, within `verify.timeoutMs`. A failure there restores them all in the same way.
+
+The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once. `flyMachineRelease` and `flyMachineRestore` wait for Fly checks when given `checks`, and `flyMachineVerify` reads them with `checks: true`; without them they wait for `started` only.
 
 ### A source tree instead of an image
 

package/src/skills/chant-fly-patterns.md

@@ -10,9 +10,11 @@ Beyond the App and Machine covered in `chant-fly`, the lexicon models `Volume`,
 
 ## Volumes and mounts
 
-`flyApply` applies volumes before machines, because a machine's `config.mounts[]` references a volume by name, so the volume must exist first. A volume is created if absent (idempotent by name); a re-apply of an existing volume is a no-op.
+`flyApply` applies volumes before machines. A volume is created if absent (idempotent by name); a re-apply of an existing volume is a no-op.
 
-The FLY011 build check enforces the link statically: every machine mount must reference a `Volume` declared in the stack, checked across files. A mount that points at an undeclared volume fails `chant build` before anything reaches the API.
+A mount can name its volume. The Machines API takes the volume's id in `config.mounts[].volume`, so before it creates or updates a Machine, `flyApply` looks the name up among the app's live volumes and sends `{ volume: "vol_...", name: "data", path }`, as flyctl does. A volume declared in the same apply is created first, so its id is there to look up. Fly lets several volumes share a name (one per Machine), so the lookup takes the one already attached to the Machine, else the one in the Machine's region that no Machine has. No volume of that name, or more than one that fits, fails the apply naming the candidates; give the mount the id to settle it. A mount given an id (`vol_...`) is sent as it is. `flyMachineRestore` and the `fly-release` capability do the same lookup. The build output and a release's recorded config keep the name.
+
+The FLY011 build check enforces the link statically: every machine mount must reference a `Volume` declared in the stack, checked across files, or give a volume id. A mount that points at an undeclared volume fails `chant build` before anything reaches the API.
 
 ```ts
 import { App, Machine, MachineConfig, MachineGuest, Volume, Fly } from "@intentius/chant-lexicon-fly";

package/src/skills/chant-fly.md

@@ -72,7 +72,7 @@ Build synthesizes the flaps plan and runs the lint rules before anything reaches
 | FLY002 | Guest sizing (`cpu_kind` / `cpus` / `memory_mb`) is not a valid combination |
 | FLY004 | A secret value written inline in machine config |
 | FLY010 | A machine config with no `image` |
-| FLY011 | A machine mount that references a `Volume` not declared in the stack (checked across files) |
+| FLY011 | A machine mount that references a `Volume` not declared in the stack (checked across files); a volume id (`vol_...`) passes |
 | FLY012 | A machine `schedule` other than `hourly`, `daily`, `weekly` or `monthly` |
 
 Fix every reported violation before applying. Secret values belong in a `Secret` or a reference, never inline (FLY004).

package/src/volume-id.ts

@@ -0,0 +1,11 @@
+/**
+ * A Fly volume's id, as the Machines API gives it (`vol_r68lmz2doox9myd4`).
+ * A Machine's `config.mounts[].volume` takes this id; chant also lets it name
+ * a volume, and `flyApply` looks the name up (#4717). Kept apart from the
+ * applier so the FLY011 lint check can use it without loading the applier.
+ */
+
+/** True when `value` is a volume id (`vol_...`), not a volume's name. Pure. */
+export function isVolumeId(value: string): boolean {
+  return /^vol_[A-Za-z0-9]+$/.test(value);
+}