@intentius/chant-lexicon-fly 0.101.0 → 0.104.0

package/src/serializer-telemetry.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Telemetry attribution in the fly serializer (#3060): each Machine's
+ * `config.env` gets `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` when the
+ * build hands it `context.telemetry`, and nothing changes without it.
+ */
+import { describe, expect, it } from "vitest";
+import type { Declarable } from "@intentius/chant";
+import { flySerializer } from "./serializer";
+import { App, Machine, MachineConfig } from "./generated/index";
+
+const telemetry = { workspace: "acme", member: "svc", environment: "prod" };
+
+function stack(...entries: Array<[string, unknown]>): Map<string, Declarable> {
+  return new Map(entries as Array<[string, Declarable]>);
+}
+
+const site = (config: Record<string, unknown>) =>
+  stack(["app", new App({ name: "notes", org_slug: "acme" })], ["web", new Machine({ name: "web", config: new MachineConfig(config) })]);
+
+const build = (entities: Map<string, Declarable>, withTelemetry = true) =>
+  JSON.parse(flySerializer.serialize(entities, undefined, withTelemetry ? { telemetry } : undefined) as string);
+
+describe("fly telemetry attribution (#3060)", () => {
+  it("stamps each Machine with the app's name and the Machine's declaration id", () => {
+    const out = build(site({ image: "node:22-slim", env: { PORT: "8080" } }));
+    expect(out.web.body.config.env).toEqual({
+      PORT: "8080",
+      OTEL_SERVICE_NAME: "notes",
+      OTEL_RESOURCE_ATTRIBUTES: "chant.workspace=acme,chant.member=svc,chant.decl=web,deployment.environment.name=prod",
+    });
+    // The App's create body has no env.
+    expect(out.app.body).toEqual({ app_name: "notes", org_slug: "acme" });
+  });
+
+  it("adds an env to a Machine that declares none", () => {
+    const out = build(site({ image: "node:22-slim" }));
+    expect(out.web.body.config.env.OTEL_SERVICE_NAME).toBe("notes");
+  });
+
+  it("keeps the values a Machine sets and appends the missing attributes", () => {
+    const out = build(
+      site({
+        image: "node:22-slim",
+        env: { OTEL_SERVICE_NAME: "notes-web", OTEL_RESOURCE_ATTRIBUTES: "chant.member=team-a,team=core" },
+      }),
+    );
+    expect(out.web.body.config.env).toEqual({
+      OTEL_SERVICE_NAME: "notes-web",
+      OTEL_RESOURCE_ATTRIBUTES: "chant.member=team-a,team=core,chant.workspace=acme,chant.decl=web,deployment.environment.name=prod",
+    });
+  });
+
+  it("gives service.version from an image pinned by digest", () => {
+    const digest = "sha256:" + "a".repeat(64);
+    const out = build(site({ image: `registry.fly.io/notes@${digest}` }));
+    expect(out.web.body.config.env.OTEL_RESOURCE_ATTRIBUTES).toBe(
+      `chant.workspace=acme,chant.member=svc,chant.decl=web,deployment.environment.name=prod,service.version=${encodeURIComponent(digest)}`,
+    );
+  });
+
+  it("names the Machine's app when the stack has several, and falls back to the export name when none is resolved", () => {
+    const out = build(
+      stack(
+        ["a", new App({ name: "alpha" })],
+        ["b", new App({ name: "beta" })],
+        ["worker", new Machine({ app: "beta", config: new MachineConfig({ image: "x" }) })],
+        ["loose", new Machine({ config: new MachineConfig({ image: "x" }) })],
+      ),
+    );
+    expect(out.worker.body.config.env.OTEL_SERVICE_NAME).toBe("beta");
+    expect(out.loose.body.config.env.OTEL_SERVICE_NAME).toBe("loose");
+  });
+
+  it("writes the same bytes as before without context.telemetry", () => {
+    const entities = site({ image: "node:22-slim", env: { PORT: "8080" } });
+    const plain = flySerializer.serialize(entities) as string;
+    expect(plain).not.toContain("OTEL_");
+    expect(flySerializer.serialize(entities, undefined, {})).toBe(plain);
+  });
+});

package/src/serializer.test.ts

@@ -146,14 +146,14 @@ describe("fly serializer", () => {
     });
   });
 
-  it("emits the Certificate create body (createCertificateRequest: hostname) under the app", () => {
+  it("emits the Certificate create body (createAcmeCertificateRequest: hostname) at /certificates/acme (#3114)", () => {
     const entities = stack(
       ["app", new App({ name: "my-app" })],
       ["cert", new Certificate({ hostname: "example.com" })],
     );
     const out = JSON.parse(flySerializer.serialize(entities) as string);
     expect(out.cert).toEqual({
-      endpoint: "/v1/apps/my-app/certificates",
+      endpoint: "/v1/apps/my-app/certificates/acme",
       method: "POST",
       body: { hostname: "example.com" },
     });
@@ -172,6 +172,21 @@ describe("fly serializer", () => {
       applyOnly: true,
     });
   });
+
+  it("marks a value-less Secret mustExist and takes its name from `name` (#2516)", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["dbUrl", new Secret({ name: "DATABASE_URL" })],
+    );
+    const out = JSON.parse(flySerializer.serialize(entities) as string);
+    expect(out.dbUrl).toEqual({
+      endpoint: "/v1/apps/my-app/secrets/DATABASE_URL",
+      method: "POST",
+      body: {},
+      applyOnly: true,
+      mustExist: true,
+    });
+  });
 });
 
 // ── Pseudo-parameters (Fly.Region / Fly.OrgSlug) ────────────────────────────

package/src/serializer.ts

@@ -36,6 +36,7 @@ import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { ownershipEntries, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { mergeResourceAttributes, telemetryEnvironment, type TelemetryAttribution } from "@intentius/chant/telemetry-attribution";
 import { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
 
 const APP_ENTITY_TYPE = "Fly::Machines::App";
@@ -56,6 +57,11 @@ interface FlapsRequest {
    * honors this flag by skipping the drift/diff read and always POSTing.
    */
   applyOnly?: boolean;
+  /**
+   * A Secret declared without a value. Its value is set outside chant, so the
+   * applier never posts it and only checks that the app has it.
+   */
+  mustExist?: boolean;
 }
 
 /**
@@ -146,6 +152,39 @@ function appName(entity: Declarable, entityName: string): string {
   return typeof name === "string" ? name : entityName;
 }
 
+// ── Telemetry attribution (#3060, D22) ────────────────────────────
+
+/** The digest of an image reference pinned with `@sha256:...`, or undefined. */
+function imageDigest(image: unknown): string | undefined {
+  if (typeof image !== "string") return undefined;
+  const at = image.lastIndexOf("@");
+  return at === -1 ? undefined : image.slice(at + 1);
+}
+
+/**
+ * Stamp one Machine's attributes as `OTEL_SERVICE_NAME` and
+ * `OTEL_RESOURCE_ATTRIBUTES` in its `config.env`, the env the Machine's
+ * process gets. `service` is the owning app's name on Fly, `decl` the
+ * Machine's declaration id. A value the Machine already sets is kept: its own
+ * `OTEL_SERVICE_NAME` wins, and its own resource attributes keep their keys
+ * while the missing ones are appended.
+ *
+ * Machine env values are literal strings, so there is no reference to the
+ * release attributes here: `fly-release` writes them into the value it
+ * deploys (#3061, ws-081).
+ */
+function stampTelemetry(config: Record<string, unknown>, service: string, decl: string, telemetry: TelemetryAttribution): void {
+  const version = imageDigest(config.image);
+  const vars = telemetryEnvironment(telemetry, { service, decl, ...(version ? { version } : {}) });
+  const env: Record<string, unknown> =
+    config.env && typeof config.env === "object" && !Array.isArray(config.env) ? { ...(config.env as Record<string, unknown>) } : {};
+  if (!("OTEL_SERVICE_NAME" in env)) env.OTEL_SERVICE_NAME = vars.OTEL_SERVICE_NAME;
+  const own = env.OTEL_RESOURCE_ATTRIBUTES;
+  if (own === undefined) env.OTEL_RESOURCE_ATTRIBUTES = vars.OTEL_RESOURCE_ATTRIBUTES;
+  else if (typeof own === "string") env.OTEL_RESOURCE_ATTRIBUTES = mergeResourceAttributes(own, vars.OTEL_RESOURCE_ATTRIBUTES);
+  config.env = env;
+}
+
 /**
  * fly flaps serializer.
  */
@@ -237,8 +276,15 @@ export const flySerializer: Serializer = {
         }
         body.config = config;
 
+        // Telemetry attribution (#3060): service.name is the app's name on
+        // Fly, or the Machine's export name when no app is resolved.
+        const owningApp = resolveOwningApp(entity);
+        if (context?.telemetry) {
+          stampTelemetry(config, owningApp === "{app}" ? name : owningApp, name, context.telemetry);
+        }
+
         requests[name] = {
-          endpoint: `/v1/apps/${resolveOwningApp(entity)}/machines`,
+          endpoint: `/v1/apps/${owningApp}/machines`,
           method: "POST",
           body,
         };
@@ -260,22 +306,26 @@ export const flySerializer: Serializer = {
         if (entityType === SECRET_ENTITY_TYPE) {
           // Apply-only (D7): name is the URL segment; `value` is the only body
           // field. mudflaps returns just a digest, so this never enters a diff.
+          // A Secret with no value is set out of band. It is marked
+          // `mustExist`, and the applier checks for it instead of posting.
           const secretName = typeof props.name === "string" ? props.name : name;
-          requests[name] = {
-            endpoint: `/v1/apps/${app}/secrets/${encodeURIComponent(secretName)}`,
-            method: "POST",
-            body: props.value !== undefined ? { value: props.value } : {},
-            applyOnly: true,
-          };
+          const endpoint = `/v1/apps/${app}/secrets/${encodeURIComponent(secretName)}`;
+          requests[name] =
+            props.value !== undefined
+              ? { endpoint, method: "POST", body: { value: props.value }, applyOnly: true }
+              : { endpoint, method: "POST", body: {}, applyOnly: true, mustExist: true };
           continue;
         }
 
+        // A Certificate is an ACME certificate. flaps creates those at
+        // `.../certificates/acme` and answers a bare POST to `.../certificates`
+        // with 404 (#3114).
         const segment =
           entityType === VOLUME_ENTITY_TYPE
             ? "volumes"
             : entityType === IP_ENTITY_TYPE
               ? "ip_assignments"
-              : "certificates";
+              : "certificates/acme";
         const body: Record<string, unknown> = {};
         for (const [key, value] of Object.entries(props)) {
           if (key === "app" || value === undefined) continue;

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

@@ -46,6 +46,14 @@ Prune is off by default and destructive. It removes resources the plan no longer
 
 Each prune logs the resource and endpoint it removed, so a prune run is auditable from the Op output.
 
+## Destroying a running machine
+
+Fly refuses to destroy a machine that is still running: a plain `DELETE` answers 412 `failed_precondition` unless it carries `?force=true`. So prune and `flyDelete` stop a running machine first (under a lease), wait for `state=stopped`, and then destroy it. The stop sends the machine's configured kill signal and honours its kill timeout, so the process can drain. A machine that is already stopped, suspended or failed is destroyed without a stop.
+
+If the stop does not reach `stopped` before the wait deadline, the destroy fails with an error naming the app, machine and id, and the machine is left in place. Pass `force: true` to `flyApply` or `flyDelete` to skip the stop and destroy with `?force=true`, which kills the machine at once.
+
+The mudflaps emulator does not enforce the 412 yet (INTENTIUS/mudflaps#70), so only the in-memory flaps and a real org exercise this path.
+
 ## Teardown
 
 `flyDelete` is the inverse of `flyApply`: destroy the machines the plan declares (dependents first), then delete the apps. It is idempotent, so an already-absent machine or app is a no-op. The deploy Op's teardown phase uses this to tear the emulator's app down at the end of an offline loop.

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

@@ -38,7 +38,7 @@ An IP is assigned if the declared type is not already present, keyed by family (
 
 ## Certificates
 
-A certificate is created if absent, idempotent by hostname. A re-apply for a hostname that already has a certificate is a no-op.
+A `Certificate` is an ACME certificate that Fly issues once the hostname's DNS points at the app. `flyApply` creates it with `POST /v1/apps/{app}/certificates/acme`, if absent, idempotent by hostname. A re-apply for a hostname that already has a certificate is a no-op. Uploading your own certificate and key (Fly's `/certificates/custom`) is not modeled.
 
 ## Apply-only secrets
 

package/src/spec/parse.ts

@@ -68,6 +68,11 @@ interface ResourceSpec {
   typeName: string;
   request: string;
   response: string;
+  /**
+   * Authoring props the request schema lacks because flaps takes them from the
+   * URL. The serializer moves them into the endpoint.
+   */
+  pathProps?: ParsedProperty[];
 }
 
 const RESOURCES: ResourceSpec[] = [
@@ -76,7 +81,22 @@ const RESOURCES: ResourceSpec[] = [
   { typeName: `Fly::${SERVICE}::Volume`, request: "CreateVolumeRequest", response: "Volume" },
   { typeName: `Fly::${SERVICE}::IPAddress`, request: "assignIPRequest", response: "IPAssignment" },
   { typeName: `Fly::${SERVICE}::Certificate`, request: "createAcmeCertificateRequest", response: "CertificateDetail" },
-  { typeName: `Fly::${SERVICE}::Secret`, request: "SetAppSecretRequest", response: "AppSecret" },
+  {
+    typeName: `Fly::${SERVICE}::Secret`,
+    request: "SetAppSecretRequest",
+    response: "AppSecret",
+    pathProps: [
+      {
+        name: "name",
+        tsType: "string",
+        required: false,
+        description:
+          "The secret's name on the app. Defaults to the declaration's export name. " +
+          "A Secret with no value is never sent: apply checks that the app already has it.",
+        constraints: {},
+      },
+    ],
+  },
 ];
 
 const REF_PREFIX = "#/components/schemas/";
@@ -117,11 +137,14 @@ export function parseFlyOpenAPI(data: string | Buffer): FlyParseResult[] {
         constraints: coreExtractConstraints(prop as JsonSchemaProperty),
       });
     }
+    for (const extra of rspec.pathProps ?? []) {
+      if (!(extra.name in reqProps)) properties.push(extra);
+    }
 
     // Attributes = response props not present in the request schema.
     const attributes: Array<{ name: string; tsType: string }> = [];
     for (const [name, prop] of Object.entries(res?.properties ?? {})) {
-      if (name in reqProps) continue;
+      if (properties.some((p) => p.name === name)) continue;
       attributes.push({ name, tsType: resolve(prop) });
     }
 

package/src/teardown.test.ts

@@ -48,6 +48,8 @@ const OTHER_STACK = { "managed-by": "chant", "chant-stack": "blog", "chant-env":
  * A stateful scripted flaps: `apps` maps app name to its machines; deletes
  * mutate the state, so the app-boundary re-check after a destroy sees what a
  * real flaps would. An app mapped to the string "boom" fails its machine list.
+ * Like flaps, a bare DELETE on a machine that is not stopped answers 412
+ * (#3115), and a stop moves it to `stopped`.
  */
 function scriptedFlaps(apps: Record<string, FakeMachine[] | "boom">): { http: FlyHttp; log: string[] } {
   const log: string[] = [];
@@ -62,10 +64,22 @@ function scriptedFlaps(apps: Record<string, FakeMachine[] | "boom">): { http: Fl
     if (method === "GET" && /\/machines\/[^/]+\/wait\?/.test(url)) {
       return { status: 200, text: JSON.stringify({ ok: true }) };
     }
-    let m = url.match(/\/v1\/apps\/([^/?]+)\/machines\/([^/?]+)$/);
+    let m = url.match(/\/v1\/apps\/([^/?]+)\/machines\/([^/?]+)\/stop$/);
+    if (m && method === "POST") {
+      const held = apps[m[1]];
+      if (Array.isArray(held)) for (const mm of held) if (mm.id === m[2]) mm.state = "stopped";
+      return { status: 200, text: "{}" };
+    }
+    m = url.match(/\/v1\/apps\/([^/?]+)\/machines\/([^/?]+)(\?force=true)?$/);
     if (m && method === "DELETE") {
       const held = apps[m[1]];
-      if (Array.isArray(held)) apps[m[1]] = held.filter((mm) => mm.id !== m![2]);
+      if (Array.isArray(held)) {
+        const target = held.find((mm) => mm.id === m![2]);
+        if (target && target.state !== "stopped" && !m[3]) {
+          return { status: 412, text: JSON.stringify({ error: "failed_precondition: unable to destroy machine, not currently stopped" }) };
+        }
+        apps[m[1]] = held.filter((mm) => mm.id !== m![2]);
+      }
       return { status: 200, text: "{}" };
     }
     m = url.match(/\/v1\/apps\/([^/?]+)\/machines$/);
@@ -147,7 +161,7 @@ describe("teardownOwned — marker machines + the app boundary (#743)", () => {
 });
 
 describe("executeTeardown — machines first, apps last", () => {
-  test("destroys the machines (lease → destroy → wait), then deletes the app", async () => {
+  test("destroys the machines (stop → destroy → wait, each under a lease), then deletes the app", async () => {
     const state: Record<string, FakeMachine[] | "boom"> = {
       mine: [machine("web", MINE), machine("worker", MINE)],
     };
@@ -176,6 +190,11 @@ describe("executeTeardown — machines first, apps last", () => {
       `DELETE ${ENDPOINT}/v1/apps/mine/machines/m-worker`,
       `DELETE ${ENDPOINT}/v1/apps/mine`,
     ]);
+    // Started machines are stopped before the destroy: flaps refuses a bare DELETE otherwise (#3115).
+    expect(log.filter((l) => l.endsWith("/stop"))).toEqual([
+      `POST ${ENDPOINT}/v1/apps/mine/machines/m-web/stop`,
+      `POST ${ENDPOINT}/v1/apps/mine/machines/m-worker/stop`,
+    ]);
     expect(state.mine).toBeUndefined();
   });
 

package/src/teardown.ts

@@ -220,7 +220,7 @@ async function destroyMachineCandidate(
   }
 
   try {
-    await destroyMachine(ctx, app, live.id, http, undefined, wait ?? {});
+    await destroyMachine(ctx, app, live.id, http, undefined, { ...(wait ?? {}), state: live.state, name: live.name });
   } catch (err) {
     return { ...base, outcome: "failed", detail: err instanceof Error ? err.message : String(err) };
   }

package/src/telemetry-build.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Telemetry attribution through a real fly build (#3060): inside a workspace
+ * each Machine's env names the workspace and the member,
+ * `telemetry.attribution: false` turns that off, and outside a workspace
+ * nothing is stamped unless `telemetry.attribution: true` opts in.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildCommand } from "@intentius/chant/cli/commands/build";
+import { loadPlugins, resolveProjectLexicons } from "@intentius/chant/cli";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const made: string[] = [];
+afterAll(() => {
+  for (const dir of made) rmSync(dir, { recursive: true, force: true });
+});
+
+const APP = `import { App, Machine, MachineConfig } from "@intentius/chant-lexicon-fly";
+
+export const app = new App({ name: "notes", org_slug: "acme" });
+
+export const web = new Machine({
+  name: "web",
+  region: "iad",
+  config: new MachineConfig({ image: "node:22-slim", env: { PORT: "8080" } }),
+});
+`;
+
+/** A fly project, inside a one-member workspace or on its own, built to its flaps plan. */
+async function build(options: { workspace: boolean; attribution?: boolean }): Promise<Record<string, { body: { config?: { env?: Record<string, string> } } }>> {
+  const root = mkdtempSync(join(tmpdir(), "chant-3060-"));
+  made.push(root);
+  mkdirSync(join(root, ".git"));
+  const project = options.workspace ? join(root, "svc") : root;
+  mkdirSync(join(project, "src"), { recursive: true });
+  if (options.workspace) {
+    writeFileSync(
+      join(root, "chant.workspace.json"),
+      JSON.stringify({ name: "acme", schema: 1, members: [{ name: "svc", dir: "svc", kind: "chant" }] }, null, 2),
+    );
+  }
+  const telemetry = options.attribution === undefined ? "" : `  telemetry: { attribution: ${options.attribution} },\n`;
+  writeFileSync(join(project, "chant.config.ts"), `export default {\n  lexicons: ["fly"],\n${telemetry}};\n`);
+  writeFileSync(join(project, "src", "app.ts"), APP);
+  symlinkSync(join(repoRoot, "node_modules"), join(project, "node_modules"), "dir");
+
+  const src = join(project, "src");
+  const plugins = await loadPlugins(await resolveProjectLexicons(src));
+  const serializers = plugins.map((p) => p.serializer).filter((s) => s.name === "fly");
+  const output = join(project, "fly.json");
+  const result = await buildCommand({ path: src, output, format: "json", serializers, plugins });
+  expect(result.success, result.errors.join("\n")).toBe(true);
+  return JSON.parse(readFileSync(output, "utf-8"));
+}
+
+describe("telemetry attribution in a fly build (#3060)", () => {
+  test("inside a workspace the Machine names the workspace, the member and the declaration", async () => {
+    const env = (await build({ workspace: true })).web.body.config!.env!;
+    expect(env.OTEL_SERVICE_NAME).toBe("notes");
+    expect(env.OTEL_RESOURCE_ATTRIBUTES).toBe("chant.workspace=acme,chant.member=svc,chant.decl=web");
+  });
+
+  test("telemetry.attribution false turns it off inside a workspace", async () => {
+    expect(JSON.stringify(await build({ workspace: true, attribution: false }))).not.toContain("OTEL_");
+  });
+
+  test("outside a workspace nothing is stamped, and telemetry.attribution true opts in without workspace or member", async () => {
+    expect(JSON.stringify(await build({ workspace: false }))).not.toContain("OTEL_");
+    const env = (await build({ workspace: false, attribution: true })).web.body.config!.env!;
+    expect(env.OTEL_RESOURCE_ATTRIBUTES).toBe("chant.decl=web");
+  });
+});