@intentius/chant-lexicon-fly 0.89.0 → 0.91.0

package/src/op/activities/index.ts

@@ -35,6 +35,29 @@ export {
 } from "./fly-apply";
 export type { FlyApplyArgs, FlyPlan, FlapsRequest, FlapsMachine, FlyHttp, WaitOpts, ApplyCtx } from "./fly-apply";
 
+// The release a Machine serves and the site steps over the Machines API
+// (#2736, ws-056): upload and start, exec (migrations), restart, stop, verify,
+// restore. `loadActivities(["fly"])` binds these by name; the `fly-release`
+// and `fly-rollback` capabilities compose them.
+export {
+  flyMachineRelease,
+  flyMachineExec,
+  flyMachineRestart,
+  flyMachineStop,
+  flyMachineVerify,
+  flyMachineRestore,
+} from "./machine-release";
+export type {
+  MachineRelease,
+  FlyMachineReleaseArgs,
+  FlyMachineReleaseResult,
+  FlyMachineExecArgs,
+  FlyMachineExecResult,
+  FlyMachineStateArgs,
+  FlyMachineVerifyArgs,
+  FlyMachineRestoreArgs,
+} from "./machine-release";
+
 // mudflaps (Fly Machines API emulator) lifecycle — boots/tears down the local
 // flaps target flyApply is exercised against.
 export {
@@ -61,7 +84,10 @@ export {
   spriteRestore,
   listCheckpoints,
   spriteDestroy,
+  spriteDelete,
+  spriteUrl,
   resolveSpritesEndpoint,
+  resolveSpritesToken,
   defaultSpritesHttp,
   spriteCreateBody,
   parseCreateResponse,
@@ -84,8 +110,39 @@ export type {
   ListCheckpointsArgs,
   Checkpoint,
   SpriteDestroyArgs,
+  SpriteDeleteArgs,
+  SpriteUrlArgs,
+  SpriteUrlResult,
 } from "./sprites";
 
+// Sprite Services activities (#2711) — imperative create/get/list/start/stop/
+// delete/logs for one background service at a time, the single-service
+// primitives underneath `spriteApplyServices`'s batch reconcile.
+// `loadActivities(["fly"])` binds these; the step builders live in core.
+export {
+  spriteServiceCreate,
+  spriteServiceGet,
+  spriteServiceList,
+  spriteServiceStart,
+  spriteServiceStop,
+  spriteServiceDelete,
+  spriteServiceLogs,
+  spriteServiceCreateBody,
+  parseServiceLogNdjson,
+} from "./sprite-services";
+export type {
+  SpriteService,
+  SpriteServiceState,
+  SpriteServiceCreateArgs,
+  SpriteServiceGetArgs,
+  SpriteServiceListArgs,
+  SpriteServiceStartArgs,
+  SpriteServiceStopArgs,
+  SpriteServiceDeleteArgs,
+  SpriteServiceLogsArgs,
+  SpriteServiceLogsResult,
+} from "./sprite-services";
+
 // Sprite filesystem activities (#848) — imperative file I/O over the fs API.
 // `loadActivities(["fly"])` binds these; the step builders live in core.
 export {

package/src/op/activities/machine-release.integration.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { flapsUp, flapsDown } from "./flaps";
+import { defaultFlyHttp, deleteApp } from "./fly-apply";
+import { findMachine } from "./machine-release";
+import { readMachineRelease } from "../../release-metadata";
+import { createFlyReleaseCapability, createFlyRollbackCapability } from "../../components/fly-release";
+import { memoryMachineConfigStore } from "../../release-store";
+import { describeResources } from "../../describe-resources";
+import type { EffectReceiptRef } from "@intentius/chant/op/receipt-store";
+
+// A release, a migration, a second release and a rollback against a live
+// mudflaps container (#2736): the `fly-release` / `fly-rollback` capabilities
+// over the real Machines wire protocol, then describeResources reading the
+// release back the way `chant components status --live` does. Docker is
+// required; the suite skips in CI unless a job opts in with FLY_IT=1, like
+// ./fly-apply.integration.test.ts. No Fly credentials: mudflaps ignores tokens.
+
+const APP = "chant-release-it";
+const CONTAINER = "chant-mudflaps-release-it";
+const PORT = 4284;
+const WAIT = { intervalMs: 50, timeoutSecs: 5, deadlineMs: 30_000 };
+const http = defaultFlyHttp();
+
+let endpoint = "";
+let available = false;
+let tmp = "";
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.FLY_IT) return;
+  tmp = mkdtempSync(join(tmpdir(), "fly-release-it-"));
+  try {
+    endpoint = (await flapsUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 })).endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (available) {
+    await deleteApp({ base: endpoint }, APP, http).catch(() => undefined);
+    await flapsDown({ name: CONTAINER });
+  }
+  if (tmp) rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("fly-release against mudflaps", () => {
+  test("release, migrate, release again, roll back; the Machine's metadata names each release", async (ctx) => {
+    if (!available) ctx.skip();
+    const planPath = join(tmp, "fly.json");
+    writeFileSync(
+      planPath,
+      JSON.stringify({
+        app: { endpoint: "/v1/apps", method: "POST", body: { app_name: APP, org_slug: "personal" } },
+        web: {
+          endpoint: `/v1/apps/${APP}/machines`,
+          method: "POST",
+          body: { name: "web", region: "iad", config: { image: "nginx:1", metadata: { "managed-by": "chant" } } },
+        },
+      }),
+    );
+    const configs = memoryMachineConfigStore();
+    const receipts = new Map<string, string>();
+    const deps = {
+      http,
+      configStore: () => configs,
+      receiptStore: () => ({
+        read: async (r: EffectReceiptRef) => receipts.get(r.name),
+        write: async (r: EffectReceiptRef, v: string) => void receipts.set(r.name, v),
+      }),
+      headCommit: async () => "1111111111111111111111111111111111111111",
+      log: () => undefined,
+    };
+    const release = createFlyReleaseCapability(deps);
+    const rollback = createFlyRollbackCapability(deps);
+    const c = { env: "it", component: "web" };
+    const common = { plan: planPath, endpoint, wait: WAIT, verify: { intervalMs: 100, timeoutMs: 10_000 } };
+
+    const one = await release.run(c, { ...common, digest: "sha256:one", image: "nginx:1", migrations: [{ name: "001.sql", command: "echo migrate 001" }] });
+    expect(one.migrations).toEqual([{ name: "001.sql", fired: true }]);
+    const two = await release.run(c, { ...common, digest: "sha256:two", image: "nginx:2", migrations: [{ name: "001.sql", command: "echo migrate 001" }] });
+    expect(two.migrations).toEqual([{ name: "001.sql", fired: false }]);
+    expect(two.previous?.digest).toBe("sha256:one");
+
+    let m = await findMachine({ base: endpoint }, APP, "web", http);
+    expect(readMachineRelease(m?.config?.metadata)).toMatchObject({ digest: "sha256:two", previousDigest: "sha256:one" });
+    expect(m?.config?.image).toBe("nginx:2");
+
+    const observed = await describeResources(
+      {
+        environment: "it",
+        buildOutput: "",
+        entityNames: ["app", "web"],
+        entities: new Map([
+          ["app", { entityType: "Fly::Machines::App", props: { name: APP } }],
+          ["web", { entityType: "Fly::Machines::Machine", props: { name: "web" } }],
+        ]),
+        endpoint,
+      },
+      http,
+    );
+    expect((observed.resources.web?.attributes as { digest?: string }).digest).toBe("sha256:two");
+
+    const back = await rollback.run(c, { plan: planPath, endpoint, wait: WAIT, verify: { intervalMs: 100, timeoutMs: 10_000 } });
+    expect(back.digest).toBe("sha256:one");
+    m = await findMachine({ base: endpoint }, APP, "web", http);
+    expect(m?.config?.image).toBe("nginx:1");
+    expect(readMachineRelease(m?.config?.metadata)?.digest).toBe("sha256:one");
+  }, 120_000);
+});

package/src/op/activities/machine-release.test.ts

@@ -0,0 +1,138 @@
+import { describe, test, expect } from "vitest";
+import {
+  RELEASE_METADATA_KEYS,
+  flyMachineExec,
+  flyMachineRelease,
+  flyMachineRestart,
+  flyMachineRestore,
+  flyMachineStop,
+  flyMachineVerify,
+  readMachineRelease,
+  releaseTarget,
+  withReleaseMetadata,
+} from "./machine-release";
+import { createMachinesFake } from "./machines-fake";
+import type { FlyPlan } from "./fly-apply";
+
+const ENDPOINT = "http://flaps.test";
+const NO_WAIT = { intervalMs: 0, deadlineMs: 2_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: "shop:1", env: { PORT: "8080" }, metadata: { "managed-by": "chant" } } },
+  },
+};
+
+describe("release metadata (pure)", () => {
+  test("withReleaseMetadata stamps the release and keeps other metadata", () => {
+    const config = withReleaseMetadata({ image: "x", metadata: { "managed-by": "chant", [RELEASE_METADATA_KEYS.release]: "old" } }, {
+      digest: "sha256:a",
+      gitSha: "abc1234",
+    });
+    expect(config.metadata).toEqual({
+      "managed-by": "chant",
+      [RELEASE_METADATA_KEYS.digest]: "sha256:a",
+      [RELEASE_METADATA_KEYS.gitSha]: "abc1234",
+    });
+    expect(readMachineRelease(config.metadata)).toEqual({ digest: "sha256:a", gitSha: "abc1234" });
+  });
+
+  test("readMachineRelease names no release without a digest", () => {
+    expect(readMachineRelease({ "managed-by": "chant" })).toBeUndefined();
+    expect(readMachineRelease(undefined)).toBeUndefined();
+  });
+
+  test("releaseTarget picks the plan's one Machine, or the one named", () => {
+    expect(releaseTarget(PLAN)).toMatchObject({ app: "shop", entity: "web", name: "web" });
+    expect(() => releaseTarget(PLAN, "worker")).toThrow(/no Machine named "worker"/);
+    const two: FlyPlan = { ...PLAN, worker: { endpoint: "/v1/apps/shop/machines", method: "POST", body: { name: "worker", config: {} } } };
+    expect(() => releaseTarget(two)).toThrow(/declares 2 Machines/);
+    expect(releaseTarget(two, "worker").name).toBe("worker");
+  });
+});
+
+describe("Machines activities against the fake", () => {
+  test("a first release creates the App and Machine with the release in its metadata", async () => {
+    const fake = createMachinesFake();
+    const r = await flyMachineRelease(
+      { plan: PLAN, endpoint: ENDPOINT, release: { digest: "sha256:one", gitSha: "1111111" }, image: "shop@sha256:img1", env: { MODE: "prod" }, wait: NO_WAIT },
+      undefined,
+      fake.http,
+    );
+    expect(r).toMatchObject({ app: "shop", action: "created", previous: null, release: { digest: "sha256:one", gitSha: "1111111" } });
+    const m = fake.machine("shop", "web")!;
+    expect(m.config.image).toBe("shop@sha256:img1");
+    expect(m.config.env).toEqual({ PORT: "8080", MODE: "prod" });
+    expect(readMachineRelease(m.config.metadata)).toEqual({ digest: "sha256:one", gitSha: "1111111" });
+    expect(m.config.metadata?.["managed-by"]).toBe("chant");
+  });
+
+  test("a second release records the one it replaced, and re-running it keeps that", async () => {
+    const fake = createMachinesFake();
+    const args = { plan: PLAN, endpoint: ENDPOINT, wait: NO_WAIT };
+    await flyMachineRelease({ ...args, release: { digest: "sha256:one" } }, undefined, fake.http);
+    const two = await flyMachineRelease({ ...args, release: { digest: "sha256:two" } }, undefined, fake.http);
+    expect(two.action).toBe("updated");
+    expect(two.release.previousDigest).toBe("sha256:one");
+    expect(two.previous?.release?.digest).toBe("sha256:one");
+    expect(readMachineRelease(two.previous?.config.metadata)?.digest).toBe("sha256:one");
+    const again = await flyMachineRelease({ ...args, release: { digest: "sha256:two" } }, undefined, fake.http);
+    expect(again.action).toBe("noop");
+    expect(again.release.previousDigest).toBe("sha256:one");
+  });
+
+  test("exec runs a command in the Machine and fails on a non-zero exit", async () => {
+    const fake = createMachinesFake({ exec: (_app, _m, cmd) => (cmd.join(" ").includes("bad") ? { exit_code: 3, stderr: "no table" } : { exit_code: 0, stdout: "ok" }) });
+    await flyMachineRelease({ plan: PLAN, endpoint: ENDPOINT, release: { digest: "sha256:one" }, wait: NO_WAIT }, undefined, fake.http);
+    const ok = await flyMachineExec({ app: "shop", machine: "web", command: "migrate 001", endpoint: ENDPOINT }, undefined, fake.http);
+    expect(ok).toEqual({ exitCode: 0, stdout: "ok", stderr: "" });
+    expect(fake.execs[0].command).toEqual(["sh", "-c", "migrate 001"]);
+    await expect(flyMachineExec({ app: "shop", machine: "web", command: ["bad"], endpoint: ENDPOINT }, undefined, fake.http)).rejects.toThrow(
+      /exited 3.*no table/,
+    );
+  });
+
+  test("stop and restart settle the Machine under a lease", async () => {
+    const fake = createMachinesFake();
+    await flyMachineRelease({ plan: PLAN, endpoint: ENDPOINT, release: { digest: "sha256:one" }, wait: NO_WAIT }, undefined, fake.http);
+    await flyMachineStop({ app: "shop", machine: "web", endpoint: ENDPOINT, wait: NO_WAIT }, undefined, fake.http);
+    expect(fake.machine("shop", "web")!.state).toBe("stopped");
+    await flyMachineRestart({ app: "shop", machine: "web", endpoint: ENDPOINT, wait: NO_WAIT }, undefined, fake.http);
+    expect(fake.machine("shop", "web")!.state).toBe("started");
+    expect(fake.calls.filter((c) => c.endsWith("/lease"))).toHaveLength(4);
+  });
+
+  test("verify: started with the release, and the health endpoint reports it", async () => {
+    const fake = createMachinesFake();
+    await flyMachineRelease(
+      { plan: PLAN, endpoint: ENDPOINT, release: { digest: "sha256:one", gitSha: "1111111" }, wait: NO_WAIT },
+      undefined,
+      fake.http,
+    );
+    const health = (revision: string) => (async () => new Response(JSON.stringify({ status: "healthy", revision }))) as unknown as typeof fetch;
+    const base = { app: "shop", machine: "web", endpoint: ENDPOINT, intervalMs: 1, timeoutMs: 20 };
+    await expect(flyMachineVerify({ ...base, digest: "sha256:one", url: "https://shop.test" }, undefined, fake.http, health("1111111"))).resolves.toMatchObject({
+      release: { digest: "sha256:one" },
+    });
+    await expect(flyMachineVerify({ ...base, digest: "sha256:two" }, undefined, fake.http)).rejects.toThrow(/serves sha256:one, expected sha256:two/);
+    await expect(flyMachineVerify({ ...base, digest: "sha256:one", url: "https://shop.test" }, undefined, fake.http, health("2222222"))).rejects.toThrow(
+      /reports 2222222/,
+    );
+    await flyMachineStop({ app: "shop", machine: "web", endpoint: ENDPOINT, wait: NO_WAIT }, undefined, fake.http);
+    await expect(flyMachineVerify({ ...base, digest: "sha256:one" }, undefined, fake.http)).rejects.toThrow(/is stopped/);
+  });
+
+  test("restore puts a recorded Machine config back", async () => {
+    const fake = createMachinesFake();
+    const args = { plan: PLAN, endpoint: ENDPOINT, wait: NO_WAIT };
+    const one = await flyMachineRelease({ ...args, release: { digest: "sha256:one" }, image: "shop:1" }, undefined, fake.http);
+    await flyMachineRelease({ ...args, release: { digest: "sha256:two" }, image: "shop:2" }, undefined, fake.http);
+    expect(fake.machine("shop", "web")!.config.image).toBe("shop:2");
+    const restored = await flyMachineRestore({ app: "shop", machine: "web", config: one.config, endpoint: ENDPOINT, wait: NO_WAIT }, undefined, fake.http);
+    expect(restored.release?.digest).toBe("sha256:one");
+    expect(fake.machine("shop", "web")!.config).toEqual(one.config);
+  });
+});