@intentius/chant-lexicon-fly 0.100.0 → 0.102.0

package/src/serializer.ts

@@ -56,6 +56,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;
 }
 
 /**
@@ -260,22 +265,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) };
   }