@intentius/chant-lexicon-fly 0.91.0 → 0.93.0

package/src/components/fly-release.test.ts

@@ -1,5 +1,7 @@
 import { describe, test, expect } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { archiveSourceTree } from "@intentius/chant/op/source-archive";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach } from "vitest";
@@ -103,6 +105,29 @@ describe("fly-release", () => {
     expect(out.gitSha).toBe("0000000000000000000000000000000000000000");
   });
 
+  test("the commit goes into the Machine's APP_REVISION env var, as chud's fly-site.mjs set it (#2834)", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa"));
+    const m = s.fake.machine("shop", "web")!;
+    expect((m.config.env as Record<string, string>).APP_REVISION).toBe("aaaaaaa");
+  });
+
+  test("a caller's own env.APP_REVISION overrides the commit (#2834)", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { env: { APP_REVISION: "custom" } }));
+    const m = s.fake.machine("shop", "web")!;
+    expect((m.config.env as Record<string, string>).APP_REVISION).toBe("custom");
+  });
+
+  test("a rollback restores the recorded APP_REVISION with the rest of the config (#2834)", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa"));
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb"));
+    await s.rollback.run(CTX, { plan: planPath, endpoint: ENDPOINT, wait: NO_WAIT, verify: { intervalMs: 1, timeoutMs: 20 } });
+    const m = s.fake.machine("shop", "web")!;
+    expect((m.config.env as Record<string, string>).APP_REVISION).toBe("aaaaaaa");
+  });
+
   test("each migration fires once per environment, then the Machine restarts", async () => {
     const s = setup();
     const migrations = [
@@ -242,3 +267,112 @@ describe("components status --live over a Fly release", () => {
     });
   });
 });
+
+describe("fly-release with a source tree (#2782)", () => {
+  function archived() {
+    const repo = join(dir, "repo");
+    const git = (...args: string[]) => execFileSync("git", args, { cwd: repo, stdio: "pipe" });
+    mkdirSync(join(repo, "app/migrations"), { recursive: true });
+    writeFileSync(join(repo, "app/server.js"), "console.log('serving');\n");
+    writeFileSync(join(repo, "app/migrations/0001_init.sql"), "CREATE TABLE t (id INTEGER);\n");
+    git("init", "-q", "-b", "main");
+    git("-c", "user.email=t@t", "-c", "user.name=t", "add", "-A");
+    git("-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "-m", "app");
+    return archiveSourceTree({ dir: "app", cwd: repo });
+  }
+
+  test("puts the approved tree on the Machine with its start command, and a retry changes nothing", async () => {
+    const s = setup();
+    const a = archived();
+    const source = { archive: a.archive, digest: a.digest, dir: a.dir, start: "node server.js" };
+    const first = await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { source }));
+    const m = s.fake.machine("shop", "web")!;
+    const files = m.config.files as Array<{ guest_path: string; raw_value: string }>;
+    expect(files.map((f) => f.guest_path).sort()).toEqual(["/srv/app/migrations/0001_init.sql", "/srv/app/server.js"]);
+    expect(Buffer.from(files.find((f) => f.guest_path === "/srv/app/server.js")!.raw_value, "base64").toString()).toBe("console.log('serving');\n");
+    expect(m.config.init).toEqual({ cmd: ["sh", "-c", "cd /srv/app && exec node server.js"] });
+    expect(m.config.image).toBe("shop:declared");
+    expect(first.digest).toBe("sha256:aaaaaaaaaaaa");
+
+    const calls = s.fake.calls.length;
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { source }));
+    // The same release again: the Machine's config is unchanged, so nothing is updated.
+    expect(s.fake.calls.slice(calls).filter((c) => c.startsWith("POST") && !c.endsWith("/wait"))).toEqual([]);
+  });
+
+  test("an archive that is not the approved digest is refused before the Machine changes", async () => {
+    const s = setup();
+    const a = archived();
+    await expect(
+      s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { source: { archive: a.archive, digest: "sha256:0000", dir: a.dir, start: "node server.js" } })),
+    ).rejects.toThrow(/not the approved sha256:0000/);
+    expect(s.fake.calls.filter((c) => c.startsWith("POST"))).toEqual([]);
+  });
+});
+
+describe("fly-rollback with a source tree (#2800)", () => {
+  /** Two commits of an app, each archived. */
+  function twoReleases() {
+    const repo = join(dir, "repo2");
+    const git = (...args: string[]) => execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", ...args], { cwd: repo, stdio: "pipe" });
+    mkdirSync(join(repo, "app"), { recursive: true });
+    git("init", "-q", "-b", "main");
+    const commit = (body: string, out: string) => {
+      writeFileSync(join(repo, "app/server.js"), body);
+      git("add", "-A");
+      git("commit", "-q", "-m", body);
+      return archiveSourceTree({ dir: "app", cwd: repo, out });
+    };
+    return { a: commit("console.log('a');\n", "a.tar"), b: commit("console.log('b');\n", "b.tar") };
+  }
+  const src = (x: { archive: string; digest: string; dir: string }) => ({ archive: x.archive, digest: x.digest, dir: x.dir });
+  const rollbackInput = (to: string, source: ReturnType<typeof src>) => ({ plan: planPath, endpoint: ENDPOINT, wait: NO_WAIT, verify: { intervalMs: 1, timeoutMs: 20 }, to, source });
+
+  test("puts back the recorded config of the release whose tree it is, and a rerun changes nothing", async () => {
+    const s = setup();
+    const { a, b } = twoReleases();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { source: { ...src(a), start: "node server.js" } }));
+    const one = structuredClone(s.fake.machine("shop", "web")!.config);
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { source: { ...src(b), start: "node server.js" } }));
+    expect(s.fake.machine("shop", "web")!.config).not.toEqual(one);
+
+    const back = await s.rollback.run(CTX, rollbackInput("sha256:aaaaaaaaaaaa", src(a)));
+    expect(back).toMatchObject({ digest: "sha256:aaaaaaaaaaaa", previous: { digest: "sha256:bbbbbbbbbbbb" } });
+    const m = s.fake.machine("shop", "web")!;
+    expect(m.config).toEqual(one);
+    const server = (m.config.files as Array<{ guest_path: string; raw_value: string }>).find((f) => f.guest_path === "/srv/app/server.js")!;
+    expect(Buffer.from(server.raw_value, "base64").toString()).toBe("console.log('a');\n");
+
+    const calls = s.fake.calls.length;
+    await s.rollback.run(CTX, rollbackInput("sha256:aaaaaaaaaaaa", src(a)));
+    expect(s.fake.calls.slice(calls).filter((c) => c.startsWith("POST") && !c.endsWith("/wait"))).toEqual([]);
+    expect(s.fake.machine("shop", "web")!.config).toEqual(one);
+  });
+
+  test("an archive that is not its digest is refused before any flaps call", async () => {
+    const s = setup();
+    const { a, b } = twoReleases();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { source: { ...src(a), start: "node server.js" } }));
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { source: { ...src(b), start: "node server.js" } }));
+    const calls = s.fake.calls.length;
+    await expect(s.rollback.run(CTX, rollbackInput("sha256:aaaaaaaaaaaa", { ...src(a), digest: b.digest }))).rejects.toThrow(/not the approved/);
+    expect(s.fake.calls.length).toBe(calls);
+  });
+
+  test("a recorded config that does not carry the tree is refused, and the Machine is left as it is", async () => {
+    const s = setup();
+    const { a, b } = twoReleases();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { source: { ...src(a), start: "node server.js" } }));
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { source: { ...src(b), start: "node server.js" } }));
+    const serving = structuredClone(s.fake.machine("shop", "web")!.config);
+    await expect(s.rollback.run(CTX, rollbackInput("sha256:aaaaaaaaaaaa", src(b)))).rejects.toThrow(/does not carry the tree .*\/srv\/app\/server\.js has other bytes/);
+    expect(s.fake.machine("shop", "web")!.config).toEqual(serving);
+  });
+
+  test("a release with no recorded Machine config is refused by name", async () => {
+    const s = setup();
+    const { a, b } = twoReleases();
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { source: { ...src(b), start: "node server.js" } }));
+    await expect(s.rollback.run(CTX, rollbackInput("sha256:aaaaaaaaaaaa", src(a)))).rejects.toThrow("fly-rollback: no recorded Machine config for sha256:aaaaaaaaaaaa on shop/web");
+  });
+});

package/src/components/fly-release.ts

@@ -14,7 +14,11 @@
  * (../op/activities/machine-release.ts):
  *
  * 1. upload and start: apply the plan with the Machine serving the release,
- *    its digest and commit in the Machine's metadata;
+ *    its digest and commit in the Machine's metadata, and the commit in its
+ *    `APP_REVISION` env var (#2834, as chud's fly-site.mjs set it), so the
+ *    app's own `/health` can report it. A caller's `env.APP_REVISION`
+ *    overrides it. `fly-rollback` restores it for free: it puts back the
+ *    whole recorded config, env included;
  * 2. migrate: each migration runs inside the Machine once per environment,
  *    witnessed by a receipt in chant's lifecycle receipt store
  *    (`@intentius/chant/op/lifecycle-receipt-store`), then the Machine restarts
@@ -32,7 +36,9 @@
  * Each release's Machine config is kept on the lifecycle branch
  * (../release-store.ts). `fly-rollback` puts back the config of the release
  * the serving one replaced (or the digest it is given), which is also the
- * saga compensation `fly-release` declares.
+ * saga compensation `fly-release` declares. Given the source tree of that
+ * release (#2800), it checks the archive against its digest before any flaps
+ * call and refuses a recorded config that does not carry exactly that tree.
  */
 
 import { createHash } from "node:crypto";
@@ -48,6 +54,7 @@ import {
   flyMachineVerify,
   readMachineRelease,
   releaseTarget,
+  type MachineFile,
   type MachineRelease,
 } from "../op/activities/machine-release";
 import { defaultFlyHttp, parsePlan, resolveEndpoint, type FlyHttp, type WaitOpts } from "../op/activities/fly-apply";
@@ -64,6 +71,55 @@ export interface FlyMigration {
   sha?: string;
 }
 
+/** A source tree a release puts on the Machine. */
+export interface FlySource {
+  /** The archive (`sourceArchive`'s `archive`, a `git archive` tar). */
+  archive: string;
+  /** The sha256 the archive must have (`sha256:...`). */
+  digest: string;
+  /** The directory the archive holds, stripped from each path (`sourceArchive`'s `dir`). */
+  dir?: string;
+  /** Where the files go on the Machine. Default `/srv/app`. */
+  into?: string;
+  /** The command that starts the app, run in `into`: an argv, or a string run with `sh -c`. */
+  start: string[] | string;
+}
+
+/** Most bytes of files, base64, a release puts in a Machine's config (as chud's fly-site.mjs capped them). */
+export const SOURCE_FILES_LIMIT = 1024 * 1024;
+
+/** Where a source tree goes on the Machine, without a trailing slash. */
+const intoOf = (source: { into?: string }) => (source.into ?? "/srv/app").replace(/\/+$/, "");
+
+/** A source tree's files as a Machine config carries them, once its archive is the approved one. */
+async function sourceTreeFiles(source: Omit<FlySource, "start">, kind: string): Promise<MachineFile[]> {
+  const { readSourceArchive } = await import("@intentius/chant/op/source-archive");
+  const into = intoOf(source);
+  const files: MachineFile[] = readSourceArchive(source).map((f) => ({
+    guest_path: `${into}/${f.path}`,
+    raw_value: f.data.toString("base64"),
+    ...(f.executable ? { mode: 0o755 } : {}),
+  }));
+  if (files.length === 0) throw new Error(`${kind}: ${source.archive} holds no files`);
+  return files;
+}
+
+/** A source tree as Machine files and the start command, once its archive is the approved one. */
+export async function sourceMachineFiles(source: FlySource): Promise<{ files: MachineFile[]; cmd: string[] }> {
+  const into = intoOf(source);
+  const files = await sourceTreeFiles(source, "fly-release");
+  const bytes = files.reduce((n, f) => n + f.raw_value.length, 0);
+  if (bytes > SOURCE_FILES_LIMIT) {
+    throw new Error(
+      `fly-release: the source tree is ${Math.round(bytes / 1024)} KiB encoded; a Machine's config carries at most ${SOURCE_FILES_LIMIT / 1024} KiB of files. Ship a larger app as an image (\`image\`).`,
+    );
+  }
+  const start = typeof source.start === "string" ? source.start : source.start.map(shellQuote).join(" ");
+  return { files, cmd: ["sh", "-c", `cd ${shellQuote(into)} && exec ${start}`] };
+}
+
+const shellQuote = (v: string) => (/^[A-Za-z0-9_./:=@%+-]+$/.test(v) ? v : `'${v.replaceAll("'", "'\\''")}'`);
+
 /** Health check after the release serves. */
 export interface FlyVerify {
   /** The app's public URL. Without it, only the Machine's state and metadata are checked. */
@@ -87,8 +143,15 @@ export interface FlyReleaseInput {
   release?: string;
   /** An image to run in place of the declared one. */
   image?: string;
-  /** Env added to the declared Machine's env. */
+  /** Env added to the declared Machine's env, over `APP_REVISION` (the commit, #2834) unless this names its own. */
   env?: Record<string, string>;
+  /**
+   * A source tree to put on the Machine (#2782), for an app shipped as its
+   * own files on a declared runtime image rather than as an image of its own.
+   * The archive is read only once its bytes hash to `digest` (the digest the
+   * release plan carries), so the Machine never gets a tree nobody approved.
+   */
+  source?: FlySource;
   /** Migrations, in order. */
   migrations?: FlyMigration[];
   verify?: FlyVerify;
@@ -110,12 +173,22 @@ export interface FlyReleaseOutput {
   migrations: Array<{ name: string; fired: boolean }>;
 }
 
+/** The source tree a rollback puts back (#2800): the archive of the release it goes back to. */
+export type FlyRollbackSource = Omit<FlySource, "start">;
+
 export interface FlyRollbackInput {
   /** Path to the fly build output, naming the App and Machine. */
   plan: string;
   machine?: string;
   /** The release digest to go back to. Default: the one the serving release replaced. */
   to?: string;
+  /**
+   * The source tree of the release it goes back to (#2800). The archive is
+   * read only once its bytes hash to `digest`, before any flaps call, and the
+   * Machine config recorded for `to` must carry exactly that tree under
+   * `into`, or the rollback is refused.
+   */
+  source?: FlyRollbackSource;
   verify?: FlyVerify;
   endpoint?: string;
   wait?: WaitOpts;
@@ -210,6 +283,13 @@ export function createFlyReleaseCapability(deps: FlyReleaseDeps = {}): Capabilit
       const { plan } = loadTarget(input.plan, input.machine);
       const gitSha = input.gitSha ?? (await (deps.headCommit ?? defaultHeadCommit)());
       const configs = await (deps.configStore ?? defaultConfigStore)(ctx);
+      // The tree is checked against its digest before the Machine changes.
+      const source = input.source ? await sourceMachineFiles(input.source) : undefined;
+
+      // APP_REVISION carries the commit into the Machine's env, as chud's
+      // fly-site.mjs did (chant#2834), so the app's own /health can report
+      // it. A caller's own APP_REVISION (input.env) wins over the commit.
+      const env = { APP_REVISION: gitSha, ...(input.env ?? {}) };
 
       const released = await flyMachineRelease(
         {
@@ -217,7 +297,8 @@ export function createFlyReleaseCapability(deps: FlyReleaseDeps = {}): Capabilit
           machine: input.machine,
           release: { digest: input.digest, gitSha, ...(input.release ? { release: input.release } : {}) },
           image: input.image,
-          env: input.env,
+          env,
+          ...(source ? { files: source.files, cmd: source.cmd } : {}),
           endpoint: input.endpoint,
           wait: input.wait,
         },
@@ -296,12 +377,18 @@ export function createFlyRollbackCapability(deps: FlyReleaseDeps = {}): Capabili
   const log = deps.log ?? ((line: string) => console.error(line));
   const httpFor = () => deps.http ?? defaultFlyHttp();
 
-  async function restoreTo(ctx: DeployContext, input: FlyRollbackInput, app: string, machine: string, digest: string) {
+  async function recordedConfig(ctx: DeployContext, app: string, machine: string, digest: string): Promise<Record<string, unknown>> {
     const store = await (deps.configStore ?? defaultConfigStore)(ctx);
     const config = await store.read({ app, machine, digest });
     if (!config) throw new Error(`fly-rollback: no recorded Machine config for ${digest} on ${app}/${machine}`);
+    return config;
+  }
+
+  async function restoreTo(ctx: DeployContext, input: FlyRollbackInput, app: string, machine: string, digest: string, config?: Record<string, unknown>, serving?: string) {
+    config ??= await recordedConfig(ctx, app, machine, digest);
     const http = httpFor();
-    await flyMachineRestore({ app, machine, config, endpoint: input.endpoint, wait: input.wait }, undefined, http);
+    // Already serving it (a rerun after the rollback finished): leave the Machine as it is.
+    if (serving !== digest) await flyMachineRestore({ app, machine, config, endpoint: input.endpoint, wait: input.wait }, undefined, http);
     await flyMachineVerify({ app, machine, digest, endpoint: input.endpoint, ...(input.verify ?? {}) }, undefined, http, deps.fetch);
     return readMachineRelease((config as { metadata?: Record<string, string> }).metadata);
   }
@@ -310,6 +397,8 @@ export function createFlyRollbackCapability(deps: FlyReleaseDeps = {}): Capabili
     kind: "fly-rollback",
     rollbackPolicy: "native",
     async run(ctx, input) {
+      // The tree is checked against its digest before any flaps call.
+      const tree = input.source ? await sourceTreeFiles(input.source, "fly-rollback") : undefined;
       const http = httpFor();
       const { target } = loadTarget(input.plan, input.machine);
       const live = await findMachine({ base: resolveEndpoint(input) }, target.app, target.name, http);
@@ -317,8 +406,19 @@ export function createFlyRollbackCapability(deps: FlyReleaseDeps = {}): Capabili
       const serving = readMachineRelease(live.config?.metadata);
       const to = input.to ?? serving?.previousDigest;
       if (!to) throw new Error(`fly-rollback: ${target.app}/${target.name} serves ${serving?.digest ?? "no release"}, with no release before it to roll back to`);
-      const restored = await restoreTo(ctx, input, target.app, target.name, to);
-      log(`fly-rollback: ${target.app}/${target.name} serves ${to} again (was ${serving?.digest ?? "no release"})`);
+      const config = await recordedConfig(ctx, target.app, target.name, to);
+      if (tree) {
+        const differs = treeDifference(config, tree, intoOf(input.source!));
+        if (differs) {
+          throw new Error(`fly-rollback: the Machine config recorded for ${to} does not carry the tree ${input.source!.digest} (${differs}); refusing to restore it`);
+        }
+      }
+      const restored = await restoreTo(ctx, input, target.app, target.name, to, config, serving?.digest);
+      log(
+        serving?.digest === to
+          ? `fly-rollback: ${target.app}/${target.name} already serves ${to}`
+          : `fly-rollback: ${target.app}/${target.name} serves ${to} again (was ${serving?.digest ?? "no release"})`,
+      );
       return {
         uri: uriOf(target.app, target.name),
         digest: to,
@@ -335,6 +435,23 @@ export function createFlyRollbackCapability(deps: FlyReleaseDeps = {}): Capabili
   };
 }
 
+/**
+ * How a recorded Machine config's files under `into` differ from a source
+ * tree, or undefined when they are the same files with the same bytes. Pure.
+ */
+export function treeDifference(config: Record<string, unknown>, tree: MachineFile[], into: string): string | undefined {
+  const prefix = `${into}/`;
+  const recorded = new Map(((config.files as MachineFile[] | undefined) ?? []).filter((f) => f.guest_path.startsWith(prefix)).map((f) => [f.guest_path, f.raw_value]));
+  for (const f of tree) {
+    const bytes = recorded.get(f.guest_path);
+    if (bytes === undefined) return `${f.guest_path} is not in it`;
+    if (bytes !== f.raw_value) return `${f.guest_path} has other bytes`;
+    recorded.delete(f.guest_path);
+  }
+  const extra = [...recorded.keys()][0];
+  return extra ? `it also carries ${extra}` : undefined;
+}
+
 /** The default `fly-release` capability. */
 export const flyReleaseCapability = createFlyReleaseCapability();
 /** The default `fly-rollback` capability. */

package/src/composites/catalog.test.ts

@@ -11,10 +11,11 @@ import { describe, expect, test } from "vitest";
 import { isCompositeDefinition } from "@intentius/chant";
 import * as flyDeployModule from "./fly-deploy";
 import * as flyOtelCollectorModule from "./fly-otel-collector";
+import * as flySiteModule from "./fly-site";
 import { compositeCatalog } from "./catalog";
 import { flyPlugin } from "../plugin";
 
-const exported = Object.entries({ ...flyDeployModule, ...flyOtelCollectorModule })
+const exported = Object.entries({ ...flyDeployModule, ...flyOtelCollectorModule, ...flySiteModule })
   .filter(([, value]) => isCompositeDefinition(value))
   .map(([name]) => name)
   .sort();

package/src/composites/catalog.ts

@@ -79,5 +79,103 @@ export const compositeCatalog: CompositeEntry[] = [
         "description": "Per-member defaults for fine-grained overrides."
       }
     ]
+  },
+  {
+    "name": "FlySite",
+    "lexicon": "fly",
+    "description": "Create a FlySite composite.",
+    "bundles": [
+      "App",
+      "IPAddress",
+      "Machine",
+      "Secret",
+      "Volume"
+    ],
+    "params": [
+      {
+        "name": "app",
+        "type": "string",
+        "required": true,
+        "description": "The App's name."
+      },
+      {
+        "name": "org",
+        "type": "string | Declarable",
+        "required": false,
+        "description": "The owning org (default: `Fly.OrgSlug`, which the build resolves from `FLY_ORG`)."
+      },
+      {
+        "name": "region",
+        "type": "string | Declarable",
+        "required": false,
+        "description": "Region of the Machine and the Volume (default: `Fly.Region`, from `FLY_REGION`)."
+      },
+      {
+        "name": "machine",
+        "type": "string",
+        "required": false,
+        "description": "The Machine's name (default: \"web\")."
+      },
+      {
+        "name": "image",
+        "type": "string",
+        "required": true,
+        "description": "The image the Machine runs until a release replaces it."
+      },
+      {
+        "name": "port",
+        "type": "number",
+        "required": false,
+        "description": "The port the app listens on inside the Machine (default: 8080)."
+      },
+      {
+        "name": "env",
+        "type": "Record<string, string>",
+        "required": false,
+        "description": "The Machine's env."
+      },
+      {
+        "name": "cpuKind",
+        "type": "string",
+        "required": false,
+        "description": "Guest CPU kind (default: \"shared\")."
+      },
+      {
+        "name": "cpus",
+        "type": "number",
+        "required": false,
+        "description": "Guest CPUs (default: 1)."
+      },
+      {
+        "name": "memoryMb",
+        "type": "number",
+        "required": false,
+        "description": "Guest memory in MB (default: 256)."
+      },
+      {
+        "name": "volume",
+        "type": "{ name: string; sizeGb: number; path: string }",
+        "required": false,
+        "description": "A Volume for the app's data, mounted at `path`."
+      },
+      {
+        "name": "ip",
+        "type": "\"shared_v4\" | \"v4\" | \"v6\"",
+        "required": false,
+        "description": "A public IP of this type (for example \"shared_v4\")."
+      },
+      {
+        "name": "secrets",
+        "type": "Record<string, string | undefined>",
+        "required": false,
+        "description": "The app's Secrets, by name."
+      },
+      {
+        "name": "defaults",
+        "type": "{ app?: Partial<Record<string, unknown>>; machine?: Partial<Record<string, unknown>>; volume?: Partial<Record<string,...",
+        "required": false,
+        "description": "Per-member defaults for fine-grained overrides."
+      }
+    ]
   }
 ];

package/src/composites/fly-site.test.ts

@@ -0,0 +1,66 @@
+/**
+ * The FlySite composite (#2809): the App and the Machine a release ships to,
+ * with the Volume, IP and Secrets it is asked for, serialized to the flaps
+ * requests the applier and the `fly-release` steps read.
+ */
+import { describe, expect, test } from "vitest";
+import type { Declarable } from "@intentius/chant";
+import { flySerializer } from "../serializer";
+import { releaseTarget } from "../op/activities/machine-release";
+import { FlySite } from "./fly-site";
+
+function plan(members: Record<string, Declarable>): Record<string, { endpoint: string; body: Record<string, unknown> }> {
+  return JSON.parse(flySerializer.serialize(new Map(Object.entries(members).map(([k, v]) => [`flySite_${k}`, v]))) as string);
+}
+
+describe("FlySite", () => {
+  test("declares the App, the Volume, the IP, the Secret and the one Machine, mounted and behind 443 and 80", () => {
+    const site = FlySite({
+      app: "notes",
+      org: "acme",
+      region: "iad",
+      image: "node:22-slim",
+      env: { PORT: "8080", APP_DATA: "/data" },
+      volume: { name: "data", sizeGb: 1, path: "/data" },
+      ip: "shared_v4",
+      secrets: { APP_SECRET: undefined },
+    });
+    expect(Object.keys(site.members).sort()).toEqual(["app", "appSecret", "ip", "machine", "volume"]);
+
+    const out = plan(site.members);
+    expect(out.flySite_app.body).toEqual({ app_name: "notes", org_slug: "acme" });
+    expect(out.flySite_volume).toMatchObject({ endpoint: "/v1/apps/notes/volumes", body: { name: "data", region: "iad", size_gb: 1 } });
+    expect(out.flySite_ip.endpoint).toBe("/v1/apps/notes/ip_assignments");
+    expect(out.flySite_appSecret.endpoint).toBe("/v1/apps/notes/secrets/APP_SECRET");
+    expect(out.flySite_machine).toMatchObject({
+      endpoint: "/v1/apps/notes/machines",
+      body: {
+        name: "web",
+        region: "iad",
+        config: {
+          image: "node:22-slim",
+          guest: { cpu_kind: "shared", cpus: 1, memory_mb: 256 },
+          mounts: [{ volume: "data", path: "/data" }],
+          services: [{ protocol: "tcp", internal_port: 8080, ports: [{ port: 443, handlers: ["tls", "http"] }, { port: 80, handlers: ["http"] }] }],
+          env: { PORT: "8080", APP_DATA: "/data" },
+        },
+      },
+    });
+
+    // A release finds the Machine without being told its name.
+    expect(releaseTarget(out as never)).toMatchObject({ app: "notes", entity: "flySite_machine", name: "web" });
+  });
+
+  test("declares only the App and the Machine when nothing else is asked for", () => {
+    const site = FlySite({ app: "bare", org: "acme", region: "ord", machine: "api", image: "nginx:1", port: 80 });
+    expect(Object.keys(site.members).sort()).toEqual(["app", "machine"]);
+    const out = plan(site.members);
+    expect(out.flySite_machine.body).toMatchObject({ name: "api", config: { image: "nginx:1", services: [{ internal_port: 80 }] } });
+    expect((out.flySite_machine.body.config as Record<string, unknown>).mounts).toBeUndefined();
+  });
+
+  test("a Secret never takes another member's name", () => {
+    const site = FlySite({ app: "x", org: "acme", region: "iad", image: "i", secrets: { APP: "v", DB_URL: "u" } });
+    expect(Object.keys(site.members).sort()).toEqual(["app", "appSecret", "dbUrl", "machine"]);
+  });
+});