@intentius/chant-lexicon-fly 0.124.30 → 0.124.32

package/dist/op/activities/fly-apply.js

@@ -0,0 +1,911 @@
+/**
+ * fly (Machines API / "flaps") native applier — #739.
+ *
+ * Peer of `gcpApply` (#706): a direct-REST applier that does its own diff,
+ * owned-only prune, and mutation waiting. GCP has no server-side declarative
+ * apply, and neither does flaps, so this loop is hand-rolled — GET-then-
+ * create/update per resource, poll `/wait` after each mutation, and prune only
+ * what chant owns. Unlike GCP's long-running operations, flaps gates mutations
+ * behind machine leases (a nonce echoed in the `fly-machine-lease-nonce`
+ * header), so the tricky paths here are the lease-conflict retry and waiting on
+ * the correct new `instance_id` after an update.
+ *
+ * Input is the #738 serializer's output: a JSON object keyed by entity name,
+ * each value a single flaps create request `{ endpoint, method, body }` (app →
+ * `/v1/apps`, machine → `/v1/apps/{app}/machines`). A machine endpoint may carry
+ * a literal `{app}` placeholder when the stack declares more than one app; it is
+ * resolved from the owning app at apply time.
+ *
+ * D1: direct REST, no flyctl, no state file. D2: owned-only prune via the
+ * `managed-by: chant` machine metadata. D3: endpoint override via
+ * `FLY_FLAPS_BASE_URL` (or an explicit `endpoint` arg), so the same code points
+ * at real Fly or at mudflaps (`:4280`).
+ */
+import { readFileSync } from "node:fs";
+import { sleep } from "@intentius/chant/op";
+import { hasOwnershipMarker } from "@intentius/chant/ownership";
+import { FLY_METADATA_OWNERSHIP_KEYS } from "../../ownership.js";
+import { logProgress } from "./progress.js";
+import { applyResult, } from "@intentius/chant/apply";
+/** Default flaps host when neither an `endpoint` arg nor `FLY_FLAPS_BASE_URL` is set. */
+export const DEFAULT_FLAPS_BASE_URL = "https://api.machines.dev";
+/** Header carrying a lease nonce on a mutating request, matching fly-go/flaps. */
+export const LEASE_NONCE_HEADER = "fly-machine-lease-nonce";
+// Progress lines go to stderr (#2516); the helper is shared with the Sprites activities.
+export { logProgress } from "./progress.js";
+// ── Pure helpers (unit-testable without http) ─────────────────────────────────
+/**
+ * Resolve the flaps base URL (D3): an explicit `endpoint` arg wins, then the
+ * `FLY_FLAPS_BASE_URL` env, then the real-Fly default. The trailing slash is
+ * stripped so `${base}/v1/...` never doubles up. Pure.
+ */
+export function resolveEndpoint(args = {}, env = process.env) {
+    const base = args.endpoint || env.FLY_FLAPS_BASE_URL || DEFAULT_FLAPS_BASE_URL;
+    return base.replace(/\/$/, "");
+}
+/** Parse the serializer's JSON output into a plan. Pure. */
+export function parsePlan(content) {
+    return JSON.parse(content);
+}
+/** True when a request creates an App (`POST /v1/apps`). Pure. */
+export function isAppRequest(req) {
+    return /^\/v1\/apps\/?$/.test(req.endpoint);
+}
+/** True when a request creates a Machine (`.../machines`). Pure. */
+export function isMachineRequest(req) {
+    return /^\/v1\/apps\/[^/]+\/machines\/?$/.test(req.endpoint);
+}
+/** The app segment of a machine endpoint, or the literal `{app}` placeholder. Pure. */
+export function machineAppSegment(endpoint) {
+    const m = endpoint.match(/^\/v1\/apps\/([^/]+)\/machines\/?$/);
+    if (!m)
+        throw new Error(`not a machine endpoint: ${endpoint}`);
+    return decodeURIComponent(m[1]);
+}
+/** True when a request creates a Volume (`.../volumes`). Pure. */
+export function isVolumeRequest(req) {
+    return /^\/v1\/apps\/[^/]+\/volumes\/?$/.test(req.endpoint);
+}
+/** True when a request assigns an IP (`.../ip_assignments`). Pure. */
+export function isIpRequest(req) {
+    return /^\/v1\/apps\/[^/]+\/ip_assignments\/?$/.test(req.endpoint);
+}
+/**
+ * True when a request creates a Certificate: `.../certificates/acme`, or the
+ * bare `.../certificates` that plans built before #3114 carry. Both apply the
+ * same way, through {@link applyCert}. Pure.
+ */
+export function isCertRequest(req) {
+    return /^\/v1\/apps\/[^/]+\/certificates(\/acme)?\/?$/.test(req.endpoint);
+}
+/** True when a request sets a Secret (`.../secrets/{name}`). Pure. */
+export function isSecretRequest(req) {
+    return /^\/v1\/apps\/[^/]+\/secrets\/[^/]+\/?$/.test(req.endpoint);
+}
+/**
+ * The app segment of any app-scoped resource endpoint (volumes, ip_assignments,
+ * certificates, secrets), or the literal `{app}` placeholder. Pure.
+ */
+export function resourceAppSegment(endpoint) {
+    const m = endpoint.match(/^\/v1\/apps\/([^/]+)\//);
+    if (!m)
+        throw new Error(`not an app-scoped endpoint: ${endpoint}`);
+    return decodeURIComponent(m[1]);
+}
+/** The secret name segment of a `.../secrets/{name}` endpoint. Pure. */
+export function secretNameSegment(endpoint) {
+    const m = endpoint.match(/^\/v1\/apps\/[^/]+\/secrets\/([^/]+)\/?$/);
+    if (!m)
+        throw new Error(`not a secret endpoint: ${endpoint}`);
+    return decodeURIComponent(m[1]);
+}
+/**
+ * Resolve a machine's owning app: the endpoint segment as-is, unless it is the
+ * `{app}` placeholder the serializer leaves when it can't decide — then fall
+ * back to the stack's sole app. Throws when neither settles it. Pure.
+ */
+export function resolveApp(segment, soleApp) {
+    if (segment !== "{app}")
+        return segment;
+    if (soleApp)
+        return soleApp;
+    throw new Error("machine endpoint has an unresolved {app} placeholder and the stack declares no single app");
+}
+/** The `app_name` an app request creates. Pure. */
+export function appNameFromRequest(req) {
+    const name = req.body.app_name;
+    if (typeof name !== "string" || !name)
+        throw new Error("app request has no app_name");
+    return name;
+}
+/**
+ * True when a machine's live metadata carries chant's ownership marker (D2).
+ * Pure. Reads the key convention the fly lexicon declares via the #686 seam
+ * (`FLY_METADATA_OWNERSHIP_KEYS`) through core's `hasOwnershipMarker`, so the
+ * prune filter and the serializer's stamp can never drift apart — the marker
+ * key lives in exactly one place.
+ */
+export function isChantOwned(metadata) {
+    return hasOwnershipMarker(metadata ?? undefined, FLY_METADATA_OWNERSHIP_KEYS);
+}
+/** Structural equality over two config values, order-insensitive. Pure. */
+export function configEqual(a, b) {
+    return canonical(a) === canonical(b);
+}
+function canonical(v) {
+    return JSON.stringify(sortKeys(v));
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === "object") {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            out[k] = sortKeys(v[k]);
+        }
+        return out;
+    }
+    return v;
+}
+/**
+ * The lease-conflict retry decision. A 409 whose body mentions a lease is a
+ * stale/lost nonce (the `lease_currently_held` acquire envelope, or the "machine
+ * is leased" gate on a mutation) — the caller should re-acquire and retry once.
+ * A 409 that is not lease-shaped (e.g. "app already exists") is not retried. Pure.
+ */
+export function isLeaseConflict(status, text) {
+    return status === 409 && /lease/i.test(text);
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Pull the nonce out of a lease-acquire success envelope. */
+function parseNonce(text) {
+    const body = parseJson(text);
+    return body?.data?.nonce;
+}
+function parseMachine(text) {
+    const m = parseJson(text);
+    if (!m?.id)
+        throw new Error(`unexpected machine response: ${text}`);
+    return m;
+}
+// ── URL builders ──────────────────────────────────────────────────────────────
+const appsUrl = (base) => `${base}/v1/apps`;
+const appUrl = (base, app) => `${appsUrl(base)}/${encodeURIComponent(app)}`;
+const machinesUrl = (base, app) => `${appUrl(base, app)}/machines`;
+const machineUrl = (base, app, id) => `${machinesUrl(base, app)}/${encodeURIComponent(id)}`;
+const leaseUrl = (base, app, id) => `${machineUrl(base, app, id)}/lease`;
+const volumesUrl = (base, app) => `${appUrl(base, app)}/volumes`;
+const volumeUrl = (base, app, id) => `${volumesUrl(base, app)}/${encodeURIComponent(id)}`;
+const ipsUrl = (base, app) => `${appUrl(base, app)}/ip_assignments`;
+const ipUrl = (base, app, ip) => `${ipsUrl(base, app)}/${encodeURIComponent(ip)}`;
+const certsUrl = (base, app) => `${appUrl(base, app)}/certificates`;
+const certUrl = (base, app, hostname) => `${certsUrl(base, app)}/${encodeURIComponent(hostname)}`;
+// Certificates are listed at `.../certificates` but created at `.../acme`:
+// flaps has no POST on the list path and answers one with 404 (#3114).
+const acmeCertUrl = (base, app) => `${certsUrl(base, app)}/acme`;
+const secretsUrl = (base, app) => `${appUrl(base, app)}/secrets`;
+const secretUrl = (base, app, secretName) => `${secretsUrl(base, app)}/${encodeURIComponent(secretName)}`;
+function waitUrl(base, app, id, state, version, timeoutSecs) {
+    const q = new URLSearchParams({ state, timeout: String(timeoutSecs) });
+    if (version)
+        q.set("version", version);
+    return `${machineUrl(base, app, id)}/wait?${q.toString()}`;
+}
+/**
+ * Default `fetch`-based client. Sends `Authorization: Bearer <token>` when a
+ * token is set (real Fly); mudflaps ignores it. The token defaults to
+ * `FLY_API_TOKEN` at call time.
+ */
+export function defaultFlyHttp(token) {
+    return async (method, url, body, headers, signal) => {
+        const h = { ...headers };
+        if (body !== undefined)
+            h["content-type"] = "application/json";
+        const tok = token ?? process.env.FLY_API_TOKEN;
+        if (tok)
+            h["authorization"] = `Bearer ${tok}`;
+        const res = await fetch(url, {
+            method,
+            headers: Object.keys(h).length ? h : undefined,
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal,
+        });
+        return { status: res.status, text: await res.text() };
+    };
+}
+// ── Leases (the crown-jewel path) ────────────────────────────────────────────
+/**
+ * Acquire a lease, retrying once on a lease-conflict 409. The retry is what
+ * lets a stale/lost hold clear (the prior lease expired or was released) before
+ * the mutation goes out with a fresh nonce. Returns the nonce.
+ */
+export async function acquireLease(ctx, app, id, http, signal) {
+    const url = leaseUrl(ctx.base, app, id);
+    const body = { ttl: 60, description: "chant apply" };
+    let res = await http("POST", url, body, undefined, signal);
+    if (isLeaseConflict(res.status, res.text)) {
+        res = await http("POST", url, body, undefined, signal);
+    }
+    if (res.status >= 300) {
+        throw new Error(`lease acquire failed for ${app}/${id} (${res.status}): ${res.text}`);
+    }
+    const nonce = parseNonce(res.text);
+    if (!nonce)
+        throw new Error(`lease acquire returned no nonce for ${app}/${id}: ${res.text}`);
+    return nonce;
+}
+/** Best-effort lease release. A cleared lease (post-destroy) 404s — ignored. */
+export async function releaseLease(ctx, app, id, nonce, http, signal) {
+    try {
+        await http("DELETE", leaseUrl(ctx.base, app, id), undefined, { [LEASE_NONCE_HEADER]: nonce }, signal);
+    }
+    catch {
+        // Release is best-effort; a leaked lease expires on its TTL.
+    }
+}
+/**
+ * Run a lease-gated mutation: acquire → mutate (nonce in the header) → release.
+ * On a lease-conflict 409 from the mutation (a stale/lost nonce), re-acquire a
+ * fresh nonce and retry the mutation once. `mutate` receives the nonce so the
+ * caller can put it in the header; it returns the raw response. Returns the
+ * final mutation response.
+ */
+export async function withLease(ctx, app, id, http, signal, mutate) {
+    let nonce = await acquireLease(ctx, app, id, http, signal);
+    try {
+        let res = await mutate(nonce);
+        if (isLeaseConflict(res.status, res.text)) {
+            nonce = await acquireLease(ctx, app, id, http, signal);
+            res = await mutate(nonce);
+        }
+        return res;
+    }
+    finally {
+        await releaseLease(ctx, app, id, nonce, http, signal);
+    }
+}
+// ── Wait ───────────────────────────────────────────────────────────────────────
+/**
+ * Poll `GET .../wait` until the machine reaches `state` at the given `version`
+ * (its new `instance_id`). flaps clamps its own timeout to 60s and answers 408
+ * on expiry, so the client re-polls until its own deadline. A destroyed+reaped
+ * machine satisfies a `state=destroyed` wait (flaps returns `ok` on the missing
+ * machine). `http` and the interval are injectable so tests avoid real waits.
+ */
+export async function waitForMachine(ctx, app, id, version, http, signal, opts = {}) {
+    const state = opts.state ?? "started";
+    const timeoutSecs = opts.timeoutSecs ?? 60;
+    const interval = opts.intervalMs ?? 1000;
+    const deadline = Date.now() + (opts.deadlineMs ?? 300000);
+    const url = waitUrl(ctx.base, app, id, state, version, timeoutSecs);
+    let attempt = 0;
+    while (Date.now() < deadline) {
+        if (signal?.aborted)
+            throw new Error("waitForMachine aborted");
+        attempt++;
+        const res = await http("GET", url, undefined, undefined, signal);
+        if (res.status === 200 && parseJson(res.text)?.ok === true) {
+            return;
+        }
+        if (res.status === 200 || res.status === 408) {
+            // Not settled yet (or the server-side long-poll timed out) — re-poll.
+            await sleep(interval, signal);
+            continue;
+        }
+        throw new Error(`wait failed for ${app}/${id} (${res.status}): ${res.text}`);
+    }
+    throw new Error(`machine ${app}/${id} did not reach ${state} within the deadline`);
+}
+// ── Resource operations ────────────────────────────────────────────────────────
+/** Create the app if absent (idempotent). A create-time conflict means it exists. */
+export async function applyApp(ctx, req, http, signal) {
+    const app = appNameFromRequest(req);
+    const get = await http("GET", appUrl(ctx.base, app), undefined, undefined, signal);
+    if (get.status === 200)
+        return { app, created: false };
+    if (get.status !== 404)
+        throw new Error(`app ${app} lookup failed (${get.status}): ${get.text}`);
+    const res = await http("POST", appsUrl(ctx.base), req.body, undefined, signal);
+    if (res.status === 409)
+        return { app, created: false }; // already exists (raced)
+    if (res.status >= 300)
+        throw new Error(`app ${app} create failed (${res.status}): ${res.text}`);
+    return { app, created: true };
+}
+/** List an app's live machines. */
+export async function listMachines(ctx, app, http, signal) {
+    const res = await http("GET", machinesUrl(ctx.base, app), undefined, undefined, signal);
+    if (res.status === 404)
+        return [];
+    if (res.status >= 300)
+        throw new Error(`machine list failed for ${app} (${res.status}): ${res.text}`);
+    const list = parseJson(res.text);
+    return Array.isArray(list) ? list : [];
+}
+/**
+ * Reconcile one machine: create it when absent; when present, update it only if
+ * its config drifted (else no-op). A create/update is followed by a wait on the
+ * machine's new `instance_id`. Updates go through a lease. The declared machine
+ * is identified by name (falling back to the plan entity name), so re-applying
+ * an unchanged machine is a no-op.
+ */
+export async function applyMachine(ctx, app, entityName, req, http, signal, opts = {}) {
+    const name = typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
+    const body = { ...req.body, name };
+    const desiredConfig = req.body.config;
+    const live = (await listMachines(ctx, app, http, signal)).find((m) => m.name === name);
+    if (!live) {
+        const res = await http("POST", machinesUrl(ctx.base, app), body, undefined, signal);
+        if (res.status >= 300)
+            throw new Error(`machine ${app}/${name} create failed (${res.status}): ${res.text}`);
+        const m = parseMachine(res.text);
+        await waitForMachine(ctx, app, m.id, m.instance_id, http, signal, opts);
+        return { action: "created", id: m.id, name };
+    }
+    if (configEqual(desiredConfig, live.config)) {
+        return { action: "noop", id: live.id, name };
+    }
+    const res = await withLease(ctx, app, live.id, http, signal, (nonce) => http("POST", machineUrl(ctx.base, app, live.id), body, { [LEASE_NONCE_HEADER]: nonce }, signal));
+    if (res.status >= 300)
+        throw new Error(`machine ${app}/${name} update failed (${res.status}): ${res.text}`);
+    const m = parseMachine(res.text);
+    await waitForMachine(ctx, app, m.id, m.instance_id, http, signal, opts);
+    return { action: "updated", id: m.id, name };
+}
+/**
+ * States flaps destroys without `force`. A started machine answers a bare
+ * DELETE with 412 failed_precondition (#3115).
+ */
+const DESTROYABLE_STATES = new Set(["stopped", "suspended", "failed", "created"]);
+/** True when a destroy response is flaps refusing a machine that is not stopped. Pure. */
+export function isNotStoppedRefusal(status, text) {
+    return status === 412 || (status >= 400 && /failed_precondition/.test(text));
+}
+/**
+ * Stop a machine under a lease, then wait for `stopped` with no lease held (a
+ * slow stop can outlive the lease TTL). A machine already `stopping` is only
+ * waited on. A wait that runs out fails naming the machine.
+ */
+async function stopForDestroy(ctx, app, id, http, signal, opts, state) {
+    const label = opts.name ? `${app}/${opts.name} (${id})` : `${app}/${id}`;
+    if (state !== "stopping") {
+        const res = await withLease(ctx, app, id, http, signal, (nonce) => http("POST", `${machineUrl(ctx.base, app, id)}/stop`, undefined, { [LEASE_NONCE_HEADER]: nonce }, signal));
+        if (res.status === 404)
+            return;
+        if (res.status >= 300)
+            throw new Error(`machine ${label} stop before destroy failed (${res.status}): ${res.text}`);
+    }
+    const { timeoutSecs, intervalMs, deadlineMs } = opts;
+    try {
+        await waitForMachine(ctx, app, id, "", http, signal, { timeoutSecs, intervalMs, deadlineMs, state: "stopped" });
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        throw new Error(`machine ${label} did not stop, so it was not destroyed (${why}). ` +
+            `Check the machine, or destroy it with force: true to kill it without a stop.`);
+    }
+}
+/**
+ * Destroy a machine and wait for it to be reaped. flaps refuses a bare DELETE
+ * on a running machine (412, #3115), so by default a machine that is not
+ * stopped is stopped first (each mutation under a lease), and a 412 from the
+ * delete (a machine that started after it was listed) gets one stop and retry.
+ * With `force`, the delete carries `?force=true` and no stop is sent.
+ */
+export async function destroyMachine(ctx, app, id, http, signal, opts = {}) {
+    const { force, state } = opts;
+    const label = opts.name ? `${app}/${opts.name} (${id})` : `${app}/${id}`;
+    const waitOpts = { timeoutSecs: opts.timeoutSecs, intervalMs: opts.intervalMs, deadlineMs: opts.deadlineMs };
+    const gone = state === "destroyed" || state === "destroying";
+    if (!gone) {
+        if (!force && state !== undefined && !DESTROYABLE_STATES.has(state)) {
+            await stopForDestroy(ctx, app, id, http, signal, opts, state);
+        }
+        const url = force ? `${machineUrl(ctx.base, app, id)}?force=true` : machineUrl(ctx.base, app, id);
+        const del = () => withLease(ctx, app, id, http, signal, (nonce) => http("DELETE", url, undefined, { [LEASE_NONCE_HEADER]: nonce }, signal));
+        let res = await del();
+        if (!force && isNotStoppedRefusal(res.status, res.text)) {
+            await stopForDestroy(ctx, app, id, http, signal, opts, undefined);
+            res = await del();
+        }
+        if (res.status >= 300 && res.status !== 404) {
+            throw new Error(`machine ${label} destroy failed (${res.status}): ${res.text}`);
+        }
+    }
+    await waitForMachine(ctx, app, id, "", http, signal, { ...waitOpts, state: "destroyed" });
+}
+/** Delete an app (idempotent; a 404 means it is already gone). */
+export async function deleteApp(ctx, app, http, signal) {
+    const res = await http("DELETE", appUrl(ctx.base, app), undefined, undefined, signal);
+    if (res.status === 404)
+        return { app, deleted: false };
+    if (res.status >= 300)
+        throw new Error(`app ${app} delete failed (${res.status}): ${res.text}`);
+    return { app, deleted: true };
+}
+/**
+ * Owned-only prune (D2): for one app, destroy the chant-owned machines whose
+ * name is not in `keep`. An unmarked machine (no `managed-by: chant`) is never
+ * touched, so it survives an apply that would otherwise delete it. Machines
+ * already tearing down are skipped. A running machine is stopped before it is
+ * destroyed unless `opts.force` is set (see {@link destroyMachine}).
+ */
+export async function pruneMachines(ctx, app, keep, http, signal, opts = {}) {
+    const pruned = [];
+    for (const m of await listMachines(ctx, app, http, signal)) {
+        if (!isChantOwned(m.config?.metadata) || keep.has(m.name))
+            continue;
+        if (m.state === "destroyed" || m.state === "destroying")
+            continue;
+        await destroyMachine(ctx, app, m.id, http, signal, { ...opts, state: m.state, name: m.name });
+        logProgress(`pruned: ${app}/${m.name} (${ctx.base})`);
+        pruned.push({ app, name: m.name, id: m.id });
+    }
+    return pruned;
+}
+/**
+ * The declared identity of an IP: its `type` collapses to a family key the
+ * live-list can be mapped back to (shared v4 / dedicated v4 / v6). This lets a
+ * re-apply of the same declared type be a no-op even though the address is
+ * server-allocated. Pure.
+ */
+export function ipType(shared, address) {
+    if (shared)
+        return "shared_v4";
+    return address.includes(":") ? "v6" : "v4";
+}
+/** The declared IP family from a request body's `type`. Pure. */
+export function declaredIpType(type) {
+    if (type === "shared_v4")
+        return "shared_v4";
+    if (type === "v6" || type === "private_v6")
+        return "v6";
+    return "v4";
+}
+/** List an app's live volumes (flaps returns a bare array). */
+export async function listVolumes(ctx, app, http, signal) {
+    const res = await http("GET", volumesUrl(ctx.base, app), undefined, undefined, signal);
+    if (res.status === 404)
+        return [];
+    if (res.status >= 300)
+        throw new Error(`volume list failed for ${app} (${res.status}): ${res.text}`);
+    const list = parseJson(res.text);
+    return Array.isArray(list) ? list : [];
+}
+/** List an app's live IP assignments (`{ ips: [...] }`). */
+export async function listIps(ctx, app, http, signal) {
+    const res = await http("GET", ipsUrl(ctx.base, app), undefined, undefined, signal);
+    if (res.status === 404)
+        return [];
+    if (res.status >= 300)
+        throw new Error(`ip list failed for ${app} (${res.status}): ${res.text}`);
+    const body = parseJson(res.text);
+    return body?.ips ?? [];
+}
+/**
+ * The page size asked of the certificate list. Fly pages it whether or not a
+ * `limit` is given (default 25, max 500), so asking for the max keeps the
+ * common case to one request.
+ */
+export const CERT_PAGE_LIMIT = 500;
+/**
+ * The most certificate pages {@link listCerts} reads before it gives up. At
+ * {@link CERT_PAGE_LIMIT} per page that is 100,000 certificates, far past any
+ * real app, so hitting it means the API never stopped handing out a cursor.
+ */
+export const MAX_CERT_PAGES = 200;
+/**
+ * List an app's live certificates, every page of them (#3224). Fly answers
+ * `{ certificates, next_cursor?, total_count }` and pages the list even
+ * without a `limit`; this follows `next_cursor` until it is absent. A cursor
+ * the API already handed out, or more than {@link MAX_CERT_PAGES} pages,
+ * throws rather than looping or returning a partial list, because callers
+ * read "not listed" as "absent" (re-apply creates it, prune skips it).
+ */
+export async function listCerts(ctx, app, http, signal) {
+    const certs = [];
+    const seen = new Set();
+    let cursor;
+    for (let page = 0; page < MAX_CERT_PAGES; page++) {
+        const q = new URLSearchParams({ limit: String(CERT_PAGE_LIMIT) });
+        if (cursor !== undefined)
+            q.set("cursor", cursor);
+        const res = await http("GET", `${certsUrl(ctx.base, app)}?${q.toString()}`, undefined, undefined, signal);
+        // A 404 on the first page is an absent app; on a later one the list is
+        // half-read, so it is an error like any other.
+        if (res.status === 404 && page === 0)
+            return [];
+        if (res.status >= 300)
+            throw new Error(`certificate list failed for ${app} (${res.status}): ${res.text}`);
+        const body = parseJson(res.text);
+        certs.push(...(body?.certificates ?? []));
+        const next = body?.next_cursor;
+        if (!next)
+            return certs;
+        if (seen.has(next))
+            throw new Error(`certificate list for ${app} repeated cursor ${JSON.stringify(next)} after ${page + 1} page(s)`);
+        seen.add(next);
+        cursor = next;
+    }
+    throw new Error(`certificate list for ${app} still had a next_cursor after ${MAX_CERT_PAGES} pages`);
+}
+/** List an app's live secrets (`{ secrets: [...] }`; digests only, never values). */
+export async function listSecrets(ctx, app, http, signal) {
+    const res = await http("GET", secretsUrl(ctx.base, app), undefined, undefined, signal);
+    if (res.status === 404)
+        return [];
+    if (res.status >= 300)
+        throw new Error(`secret list failed for ${app} (${res.status}): ${res.text}`);
+    const body = parseJson(res.text);
+    return body?.secrets ?? [];
+}
+/** Create a volume if absent (idempotent by name). Machines that mount it apply after. */
+export async function applyVolume(ctx, app, entityName, req, http, signal) {
+    const name = typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
+    if ((await listVolumes(ctx, app, http, signal)).some((v) => v.name === name)) {
+        return { action: "noop", name };
+    }
+    const res = await http("POST", volumesUrl(ctx.base, app), { ...req.body, name }, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`volume ${app}/${name} create failed (${res.status}): ${res.text}`);
+    return { action: "created", name };
+}
+/** Assign an IP if the declared type is not already present (idempotent by family). */
+export async function applyIp(ctx, app, req, http, signal) {
+    const type = declaredIpType(req.body.type);
+    const present = new Set((await listIps(ctx, app, http, signal)).map((ip) => ipType(ip.shared, ip.ip)));
+    if (present.has(type))
+        return { action: "noop", type };
+    const res = await http("POST", ipsUrl(ctx.base, app), req.body, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`ip assign failed for ${app} (${res.status}): ${res.text}`);
+    return { action: "created", type };
+}
+/**
+ * Create an ACME certificate if absent (idempotent by hostname). Always POSTs
+ * `{ hostname }` to `.../certificates/acme`, whatever endpoint the plan entry
+ * names, so a plan built before #3114 applies correctly too.
+ */
+export async function applyCert(ctx, app, req, http, signal) {
+    const hostname = String(req.body.hostname ?? "");
+    if (!hostname)
+        throw new Error(`certificate request for ${app} has no hostname`);
+    if ((await listCerts(ctx, app, http, signal)).some((c) => c.hostname === hostname)) {
+        return { action: "noop", hostname };
+    }
+    const res = await http("POST", acmeCertUrl(ctx.base, app), { hostname }, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`certificate ${app}/${hostname} create failed (${res.status}): ${res.text}`);
+    return { action: "created", hostname };
+}
+/**
+ * True when a plan entry is a Secret with no value, which apply must never
+ * POST. Plans built before `mustExist` existed mark it with an empty body.
+ * Pure.
+ */
+export function isValuelessSecret(req) {
+    return isSecretRequest(req) && (req.mustExist === true || req.body.value === undefined);
+}
+/**
+ * Check a value-less secret (set outside chant) exists on the app. Never
+ * POSTs. Throws naming the secret when the app does not have it.
+ */
+export async function checkSecretExists(ctx, app, name, http, signal) {
+    const live = await listSecrets(ctx, app, http, signal);
+    if (!live.some((s) => s.name === name)) {
+        throw new Error(`secret ${app}/${name} is declared without a value, so it must already exist, ` +
+            `and app ${app} does not have it. Set it with \`fly secrets set ${name}=...\` ` +
+            `or give the Secret a value.`);
+    }
+    return { action: "exists", name };
+}
+/**
+ * Set a secret (D7, apply-only): always POST, never read back for a diff. flaps
+ * returns only a digest, so there is nothing to compare — every apply re-sets it.
+ */
+export async function applySecret(ctx, app, name, req, http, signal) {
+    const res = await http("POST", secretUrl(ctx.base, app, name), req.body, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`secret ${app}/${name} set failed (${res.status}): ${res.text}`);
+    return { action: "set", name };
+}
+/** App-scoped prune (D2): destroy volumes the plan no longer declares (by name). */
+export async function pruneVolumes(ctx, app, keep, http, signal) {
+    const pruned = [];
+    for (const v of await listVolumes(ctx, app, http, signal)) {
+        if (keep.has(v.name))
+            continue;
+        const res = await http("DELETE", volumeUrl(ctx.base, app, v.id), undefined, undefined, signal);
+        if (res.status >= 300 && res.status !== 404)
+            throw new Error(`volume ${app}/${v.name} delete failed (${res.status}): ${res.text}`);
+        logProgress(`pruned: volume/${app}/${v.name} (${ctx.base})`);
+        pruned.push({ app, name: v.name, id: v.id });
+    }
+    return pruned;
+}
+/** App-scoped prune (D2): release IP assignments whose type the plan no longer declares. */
+export async function pruneIps(ctx, app, keep, http, signal) {
+    const pruned = [];
+    for (const ip of await listIps(ctx, app, http, signal)) {
+        if (keep.has(ipType(ip.shared, ip.ip)))
+            continue;
+        const res = await http("DELETE", ipUrl(ctx.base, app, ip.ip), undefined, undefined, signal);
+        if (res.status >= 300 && res.status !== 404)
+            throw new Error(`ip ${app}/${ip.ip} delete failed (${res.status}): ${res.text}`);
+        logProgress(`pruned: ip/${app}/${ip.ip} (${ctx.base})`);
+        pruned.push({ app, address: ip.ip });
+    }
+    return pruned;
+}
+/** App-scoped prune (D2): destroy certificates whose hostname the plan no longer declares. */
+export async function pruneCerts(ctx, app, keep, http, signal) {
+    const pruned = [];
+    for (const c of await listCerts(ctx, app, http, signal)) {
+        if (keep.has(c.hostname))
+            continue;
+        const res = await http("DELETE", certUrl(ctx.base, app, c.hostname), undefined, undefined, signal);
+        if (res.status >= 300 && res.status !== 404)
+            throw new Error(`certificate ${app}/${c.hostname} delete failed (${res.status}): ${res.text}`);
+        logProgress(`pruned: certificate/${app}/${c.hostname} (${ctx.base})`);
+        pruned.push({ app, hostname: c.hostname });
+    }
+    return pruned;
+}
+/**
+ * App-scoped prune (D2) for apply-only secrets: a declared-then-removed secret
+ * is still prunable by name, even though it never enters a drift/diff.
+ */
+export async function pruneSecrets(ctx, app, keep, http, signal) {
+    const pruned = [];
+    for (const s of await listSecrets(ctx, app, http, signal)) {
+        if (keep.has(s.name))
+            continue;
+        const res = await http("DELETE", secretUrl(ctx.base, app, s.name), undefined, undefined, signal);
+        if (res.status >= 300 && res.status !== 404)
+            throw new Error(`secret ${app}/${s.name} delete failed (${res.status}): ${res.text}`);
+        logProgress(`pruned: secret/${app}/${s.name} (${ctx.base})`);
+        pruned.push({ app, name: s.name });
+    }
+    return pruned;
+}
+/**
+ * The native fly applier (#739, #741): read the serialized plan and apply it
+ * straight to flaps in dependency order — app → volumes → machines → ips →
+ * certificates → secrets — then optionally prune. Machines prune owned-only via
+ * the metadata marker (D2); the metadata-less types (volumes/ips/certs/secrets)
+ * prune app-scoped: everything the plan no longer declares under a managed app.
+ * Secrets are apply-only (D7): set, never read back for a diff. `http` is
+ * injectable for tests.
+ */
+/**
+ * Normalize a flyApply result into core's apply envelope (#1446).
+ *
+ * fly returns eleven arrays because it applies six entity classes and prunes
+ * five. That detail is the applier's own and stays; this projects it onto the
+ * shared tri-state so a caller can read any applier's result the same way.
+ *
+ * `notAttempted` is always empty for fly, and that is not an oversight: an entry
+ * the applier cannot classify now throws (#1457) rather than being skipped,
+ * because the serializer produced it and the two being out of sync is a bug in
+ * the lexicon, not a resource the user declined.
+ */
+function readPlanFile(planPath) {
+    if (!planPath)
+        throw new Error("flyApply needs a plan: pass planPath (the fly build output) or plan");
+    return parsePlan(readFileSync(planPath, "utf8"));
+}
+export function toApplyResult(result) {
+    // fly says "noop" where the contract says "unchanged".
+    const act = (a) => a === "noop" ? "unchanged" : a;
+    const applied = [
+        ...result.apps.map((x) => ({
+            kind: "app",
+            name: x.app,
+            action: (x.created ? "created" : "unchanged"),
+        })),
+        ...result.machines.map((x) => ({ kind: "machine", name: x.name, action: act(x.action) })),
+        ...result.volumes.map((x) => ({ kind: "volume", name: x.name, action: act(x.action) })),
+        ...result.ips.map((x) => ({ kind: "ip", name: x.type, action: act(x.action) })),
+        ...result.certs.map((x) => ({ kind: "cert", name: x.hostname, action: act(x.action) })),
+        // Secrets are apply-only (D7) — POSTed every run, never read back, so a
+        // set secret reports updated. A value-less secret is only checked, so it
+        // reports unchanged.
+        ...result.secrets.map((x) => ({
+            kind: "secret",
+            name: x.name,
+            action: (x.action === "exists" ? "unchanged" : "updated"),
+        })),
+    ];
+    const pruned = [
+        ...result.pruned.map((x) => ({ kind: "machine", name: x.name, deleted: true })),
+        ...result.prunedVolumes.map((x) => ({ kind: "volume", name: x.name, deleted: true })),
+        ...result.prunedIps.map((x) => ({ kind: "ip", name: x.address, deleted: true })),
+        ...result.prunedCerts.map((x) => ({ kind: "cert", name: x.hostname, deleted: true })),
+        ...result.prunedSecrets.map((x) => ({ kind: "secret", name: x.name, deleted: true })),
+    ];
+    return applyResult(applied, pruned, []);
+}
+export async function flyApply(args, signal, http = defaultFlyHttp(args.token)) {
+    const plan = args.plan ?? readPlanFile(args.planPath);
+    const ctx = { base: resolveEndpoint(args) };
+    const opts = args.wait ?? {};
+    const appReqs = [];
+    const machineReqs = [];
+    const volumeReqs = [];
+    const ipReqs = [];
+    const certReqs = [];
+    const secretReqs = [];
+    for (const [entityName, req] of Object.entries(plan)) {
+        if (isAppRequest(req))
+            appReqs.push(req);
+        else if (isMachineRequest(req))
+            machineReqs.push([entityName, req]);
+        else if (isVolumeRequest(req))
+            volumeReqs.push([entityName, req]);
+        else if (isIpRequest(req))
+            ipReqs.push([entityName, req]);
+        else if (isCertRequest(req))
+            certReqs.push([entityName, req]);
+        else if (isSecretRequest(req))
+            secretReqs.push([entityName, req]);
+        // #1457: this used to fall off the end. An entry matching none of the six
+        // predicates was discarded — no log, no bucket, absent from all eleven
+        // arrays flyApply returns — and the result read as a full apply.
+        //
+        // Failing is right here, rather than reporting it as not-attempted. The
+        // serializer produced this entry, so the applier not recognising it is a
+        // version skew between the two halves of the same lexicon — a bug in one of
+        // them, not a resource the user chose to skip. It happens exactly when a new
+        // Fly resource type lands on the serializer side alone.
+        else {
+            throw new Error(`fly plan entry "${entityName}" matches no request predicate ` +
+                `(${req.method} ${req.endpoint}). The serializer emitted a shape this applier ` +
+                `does not recognise — they are out of sync. Applying would silently skip it.`);
+        }
+    }
+    const appNames = appReqs.map(appNameFromRequest);
+    const soleApp = appNames.length === 1 ? appNames[0] : undefined;
+    // Apps first.
+    const apps = [];
+    for (const req of appReqs) {
+        const result = await applyApp(ctx, req, http, signal);
+        logProgress(`${result.created ? "created" : "unchanged"}: app/${result.app} (${ctx.base})`);
+        apps.push(result);
+    }
+    // Keep-sets per app, one per resource kind. Seeded empty for every declared
+    // app so an app whose resources were all removed still prunes them. These are
+    // app-scoped (D2): metadata-less types are owned wholesale under a managed app.
+    const keepMachines = new Map();
+    const keepVolumes = new Map();
+    const keepIps = new Map();
+    const keepCerts = new Map();
+    const keepSecrets = new Map();
+    for (const app of appNames) {
+        keepMachines.set(app, new Set());
+        keepVolumes.set(app, new Set());
+        keepIps.set(app, new Set());
+        keepCerts.set(app, new Set());
+        keepSecrets.set(app, new Set());
+    }
+    const track = (m, app, key) => {
+        const set = m.get(app) ?? new Set();
+        set.add(key);
+        m.set(app, set);
+    };
+    // Volumes before machines: a machine's `config.mounts[]` references a volume
+    // by name, so the volume must exist first.
+    const volumes = [];
+    for (const [entityName, req] of volumeReqs) {
+        const app = resolveApp(resourceAppSegment(req.endpoint), soleApp);
+        const result = await applyVolume(ctx, app, entityName, req, http, signal);
+        track(keepVolumes, app, result.name);
+        logProgress(`${result.action}: volume/${app}/${result.name} (${ctx.base})`);
+        volumes.push({ app, name: result.name, action: result.action });
+    }
+    const machines = [];
+    for (const [entityName, req] of machineReqs) {
+        const app = resolveApp(machineAppSegment(req.endpoint), soleApp);
+        const name = typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
+        track(keepMachines, app, name);
+        const result = await applyMachine(ctx, app, entityName, req, http, signal, opts);
+        logProgress(`${result.action}: machine/${app}/${result.name} (${ctx.base})`);
+        machines.push({ app, name: result.name, action: result.action });
+    }
+    // IPs, certificates, secrets after machines (independent of them).
+    const ips = [];
+    for (const [entityName, req] of ipReqs) {
+        const app = resolveApp(resourceAppSegment(req.endpoint), soleApp);
+        const result = await applyIp(ctx, app, req, http, signal);
+        track(keepIps, app, result.type);
+        logProgress(`${result.action}: ip/${app}/${result.type} (${ctx.base})`);
+        ips.push({ app, type: result.type, action: result.action });
+    }
+    const certs = [];
+    for (const [, req] of certReqs) {
+        const app = resolveApp(resourceAppSegment(req.endpoint), soleApp);
+        const result = await applyCert(ctx, app, req, http, signal);
+        track(keepCerts, app, result.hostname);
+        logProgress(`${result.action}: certificate/${app}/${result.hostname} (${ctx.base})`);
+        certs.push({ app, hostname: result.hostname, action: result.action });
+    }
+    // Secrets are apply-only (D7): a secret with a value is set every run and
+    // never read back for a diff. A value-less one is only checked for.
+    const secrets = [];
+    for (const [, req] of secretReqs) {
+        const app = resolveApp(resourceAppSegment(req.endpoint), soleApp);
+        const name = secretNameSegment(req.endpoint);
+        track(keepSecrets, app, name);
+        const result = isValuelessSecret(req)
+            ? await checkSecretExists(ctx, app, name, http, signal)
+            : await applySecret(ctx, app, name, req, http, signal);
+        logProgress(`${result.action}: secret/${app}/${result.name} (${ctx.base})`);
+        secrets.push({ app, name: result.name, action: result.action });
+    }
+    const pruned = [];
+    const prunedVolumes = [];
+    const prunedIps = [];
+    const prunedCerts = [];
+    const prunedSecrets = [];
+    if (args.prune) {
+        for (const [app, keep] of keepMachines) {
+            pruned.push(...(await pruneMachines(ctx, app, keep, http, signal, { ...opts, force: args.force })));
+        }
+        for (const [app, keep] of keepVolumes) {
+            prunedVolumes.push(...(await pruneVolumes(ctx, app, keep, http, signal)));
+        }
+        for (const [app, keep] of keepIps) {
+            prunedIps.push(...(await pruneIps(ctx, app, keep, http, signal)));
+        }
+        for (const [app, keep] of keepCerts) {
+            prunedCerts.push(...(await pruneCerts(ctx, app, keep, http, signal)));
+        }
+        for (const [app, keep] of keepSecrets) {
+            prunedSecrets.push(...(await pruneSecrets(ctx, app, keep, http, signal)));
+        }
+    }
+    return { apps, machines, volumes, ips, certs, secrets, pruned, prunedVolumes, prunedIps, prunedCerts, prunedSecrets };
+}
+/**
+ * The inverse of {@link flyApply}: destroy the machines the plan declares, then
+ * delete the apps (dependents before their app). A running machine is stopped
+ * first unless `args.force` is set. Idempotent — already-absent
+ * resources are a no-op. `http` is injectable for tests.
+ */
+export async function flyDelete(args, signal, http = defaultFlyHttp(args.token)) {
+    const plan = args.plan ?? readPlanFile(args.planPath);
+    const ctx = { base: resolveEndpoint(args) };
+    const opts = args.wait ?? {};
+    const appReqs = [];
+    const machineReqs = [];
+    for (const [entityName, req] of Object.entries(plan)) {
+        if (isAppRequest(req))
+            appReqs.push(req);
+        else if (isMachineRequest(req))
+            machineReqs.push([entityName, req]);
+    }
+    const soleApp = appReqs.length === 1 ? appNameFromRequest(appReqs[0]) : undefined;
+    const machines = [];
+    for (const [entityName, req] of machineReqs) {
+        const app = resolveApp(machineAppSegment(req.endpoint), soleApp);
+        const name = typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
+        const live = (await listMachines(ctx, app, http, signal)).find((m) => m.name === name);
+        if (!live)
+            continue;
+        await destroyMachine(ctx, app, live.id, http, signal, { ...opts, force: args.force, state: live.state, name });
+        machines.push({ app, name });
+    }
+    const apps = [];
+    for (const req of appReqs) {
+        const result = await deleteApp(ctx, appNameFromRequest(req), http, signal);
+        logProgress(`${result.deleted ? "deleted" : "absent"}: app/${result.app} (${ctx.base})`);
+        apps.push(result);
+    }
+    return { machines, apps };
+}