@wtfalch/foundry 0.19.0 → 0.20.0

package/dist/plan/edge-workers.js

@@ -0,0 +1,165 @@
+import { EdgeApiError } from '@wtfalch/edge';
+import { EDGE_DNS_WRITE_CONCURRENCY, limiter, rateLimitRetrier, } from './edge-dns.js';
+/** Edge answers a first upload of a name that another upload is making, or a delete in flight, `conflict` + `busy`. */
+export const EDGE_WORKERS_BUSY_ATTEMPTS = 5;
+const BUSY_FIRST_DELAY_MS = 1000;
+const BUSY_MAX_DELAY_MS = 8000;
+const isNotFound = (error) => error instanceof EdgeApiError && error.code === 'not_found';
+const isExists = (error) => error instanceof EdgeApiError && error.code === 'conflict' && String(error.reason) === 'exists';
+const isBusy = (error) => error instanceof EdgeApiError && error.code === 'conflict' && String(error.reason) === 'busy';
+/**
+ * Retries a call edge answered `conflict` + `busy`, waiting 1 s, 2 s, 4 s, then
+ * 8 s (the cap), up to {@link EDGE_WORKERS_BUSY_ATTEMPTS} tries.
+ */
+function busyRetrier(sleepOption) {
+    const sleep = sleepOption ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    return async (task) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await task();
+            }
+            catch (error) {
+                if (!isBusy(error) || attempt >= EDGE_WORKERS_BUSY_ATTEMPTS)
+                    throw error;
+                await sleep(Math.min(BUSY_FIRST_DELAY_MS * 2 ** (attempt - 1), BUSY_MAX_DELAY_MS));
+            }
+        }
+    };
+}
+/**
+ * {@link WorkersPort} over edge's `platform.workers`. The host fetches the
+ * artifact (`fetchArtifact`); this sends its base64 bytes and the sha256 to
+ * edge, which checks the digest again. The bytes are never kept, logged or
+ * put into an error here.
+ *
+ * Edge refuses to touch a live script or route that has no edge row (an upload
+ * of a live name answers `exists`, a delete answers `not_found`). So the
+ * adapter adopts one the moment it is about to be uploaded over or deleted:
+ * it lists the name (or the zone's routes), and adopts only a view whose
+ * `owner` is `null`. Adopt is idempotent and the list reports the owner
+ * afterwards, so nothing is recorded in the plan. A `skipped` route is an
+ * error. `scriptExists` and `findRoute` only read: a foreign script or route
+ * foundry refuses to overwrite is never adopted. A 404 on a delete means gone.
+ * A `rate_limited` or `busy` answer is retried.
+ */
+export function createEdgeWorkers(client, options) {
+    const rateRetry = rateLimitRetrier(options.sleep);
+    const busyRetry = busyRetrier(options.sleep);
+    const retrying = (task) => busyRetry(() => rateRetry(task));
+    const writeSlot = options.writeSlot ?? limiter(EDGE_DNS_WRITE_CONCURRENCY);
+    /** Script names and `zoneId/routeId` keys already adopted (or created) through this adapter. */
+    const adoptedScripts = new Set();
+    const adoptedRoutes = new Set();
+    const liveScript = async (name) => {
+        const { scripts } = await retrying(() => client.listScripts({ name }));
+        return scripts.find((s) => s.name === name && s.state !== 'removed');
+    };
+    const liveRoute = async (zoneId, pattern) => {
+        const { routes } = await retrying(() => client.listRoutes({ zoneId, pattern }));
+        return routes.find((r) => r.pattern === pattern && r.state !== 'removed');
+    };
+    /** Adopts `name` when its live script has no edge row. Returns false when no live script exists. */
+    const adoptScript = async (name) => {
+        if (adoptedScripts.has(name))
+            return true;
+        const view = await liveScript(name);
+        if (!view)
+            return false;
+        if (view.owner === null) {
+            const { scripts } = await writeSlot(() => retrying(() => client.adopt({ scripts: [{ name }] })));
+            if (scripts.notFound.length > 0)
+                return false;
+        }
+        adoptedScripts.add(name);
+        return true;
+    };
+    /** Adopts the route `id` in `zoneId` when it has no edge row. Returns false when it is gone. */
+    const adoptRoute = async (zoneId, id) => {
+        const key = `${zoneId}/${id}`;
+        if (adoptedRoutes.has(key))
+            return true;
+        const { routes: live } = await retrying(() => client.listRoutes({ zoneId }));
+        const view = live.find((r) => r.id === id && r.state !== 'removed');
+        if (!view)
+            return false;
+        if (view.owner === null) {
+            const { routes } = await writeSlot(() => retrying(() => client.adopt({ routes: [{ zoneId, pattern: view.pattern, id: view.id }] })));
+            const skipped = routes.skipped[0];
+            if (skipped) {
+                throw new Error(`edge workers: route ${view.pattern} in zone ${zoneId} cannot be adopted (${skipped.reason}); remove or fix it by hand`);
+            }
+            if (routes.notFound.length > 0)
+                return false;
+        }
+        adoptedRoutes.add(key);
+        return true;
+    };
+    return {
+        async scriptExists(name) {
+            return (await liveScript(name)) !== undefined;
+        },
+        async uploadScript(input) {
+            await adoptScript(input.name);
+            const bytes = await options.fetchArtifact(input.artifactUrl, input.artifactSha256);
+            await writeSlot(() => retrying(() => client.uploadScript(input.name, {
+                script: Buffer.from(bytes).toString('base64'),
+                artifactSha256: input.artifactSha256,
+                compatibilityDate: input.compatibilityDate,
+                ...(input.bindings ? { bindings: input.bindings } : {}),
+            })));
+            adoptedScripts.add(input.name);
+        },
+        async findRoute(zoneId, pattern) {
+            const view = await liveRoute(zoneId, pattern);
+            return view?.script ? { id: view.id, script: view.script } : undefined;
+        },
+        async createRoute(zoneId, pattern, script) {
+            const create = () => writeSlot(() => retrying(() => client.createRoute({ zoneId, pattern, ...(script ? { script } : {}) })));
+            let created;
+            try {
+                created = await create();
+            }
+            catch (error) {
+                if (!isExists(error))
+                    throw error;
+                // A live route on the pattern with no edge row (made before edge owned
+                // Workers): adopt it when it is the one route there and runs the same
+                // script (or none). Anything else is not foundry's to take.
+                const { routes } = await retrying(() => client.listRoutes({ zoneId, pattern }));
+                const live = routes.filter((r) => r.pattern === pattern && r.state !== 'removed');
+                const only = live.length === 1 ? live[0] : undefined;
+                if (!only || only.owner !== null || (only.script ?? null) !== (script ?? null))
+                    throw error;
+                if (!(await adoptRoute(zoneId, only.id)))
+                    throw error;
+                created = { id: only.id };
+            }
+            adoptedRoutes.add(`${zoneId}/${created.id}`);
+            return { id: created.id };
+        },
+        async deleteRoute(zoneId, routeId) {
+            if (!(await adoptRoute(zoneId, routeId)))
+                return;
+            try {
+                await writeSlot(() => retrying(() => client.removeRoute(zoneId, routeId)));
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+            adoptedRoutes.delete(`${zoneId}/${routeId}`);
+        },
+        async deleteScript(name) {
+            if (!(await adoptScript(name)))
+                return;
+            try {
+                await writeSlot(() => retrying(() => client.removeScript(name)));
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+            adoptedScripts.delete(name);
+        },
+    };
+}

package/dist/plan/edge-zones.d.ts

@@ -0,0 +1,37 @@
+import type { createEdgeClient } from '@wtfalch/edge';
+import { type WriteSlot } from './edge-dns.js';
+/** The edge SDK's platform zones client: `createEdgeClient({ ... }).platform.zones`. */
+export type EdgePlatformZones = ReturnType<typeof createEdgeClient>['platform']['zones'];
+/**
+ * Foundry's Cloudflare zone calls. Both go through this; the one implementation
+ * is {@link createEdgeZones}, which speaks to the edge service with the platform credential.
+ */
+export interface ZonePort {
+    /** The zone that serves `domain`: the longest suffix of it that is a live zone, or `undefined`. */
+    findZoneByApex(domain: string): Promise<{
+        id: string;
+        name: string;
+    } | undefined>;
+    /** Makes the zone, or returns the one already made for that name. */
+    createZone(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface EdgeZonesOptions {
+    sleep?: (ms: number) => Promise<void>;
+    /** Share one slot of {@link EDGE_DNS_WRITE_CONCURRENCY} with the other edge adapters: edge counts them all. */
+    writeSlot?: WriteSlot;
+}
+/**
+ * {@link ZonePort} over edge's `platform.zones`.
+ *
+ * Edge lists a zone by its exact name, so a lookup tries the full name and
+ * then each parent down to two labels, and never writes. Edge answers a create
+ * of a live zone that has no edge row `exists`. So the adapter adopts that zone
+ * the moment it is about to create it: it lists the name, and adopts a view
+ * whose `owner` is `null`. Adopt is idempotent and the list reports the owner
+ * afterwards, so nothing is recorded in the plan. A zone edge reports as
+ * `taken` is an error. A `rate_limited` or `busy` answer is retried.
+ */
+export declare function createEdgeZones(client: EdgePlatformZones, options?: EdgeZonesOptions): ZonePort;

package/dist/plan/edge-zones.js

@@ -0,0 +1,64 @@
+import { EdgeApiError } from '@wtfalch/edge';
+import { EDGE_DNS_WRITE_CONCURRENCY, limiter, rateLimitRetrier, } from './edge-dns.js';
+import { busyRetrier, hasReason } from './edge-ratelimits.js';
+/**
+ * {@link ZonePort} over edge's `platform.zones`.
+ *
+ * Edge lists a zone by its exact name, so a lookup tries the full name and
+ * then each parent down to two labels, and never writes. Edge answers a create
+ * of a live zone that has no edge row `exists`. So the adapter adopts that zone
+ * the moment it is about to create it: it lists the name, and adopts a view
+ * whose `owner` is `null`. Adopt is idempotent and the list reports the owner
+ * afterwards, so nothing is recorded in the plan. A zone edge reports as
+ * `taken` is an error. A `rate_limited` or `busy` answer is retried.
+ */
+export function createEdgeZones(client, options = {}) {
+    const rateRetry = rateLimitRetrier(options.sleep);
+    const busyRetry = busyRetrier(options.sleep);
+    const retrying = (task) => busyRetry(() => rateRetry(task));
+    const writeSlot = options.writeSlot ?? limiter(EDGE_DNS_WRITE_CONCURRENCY);
+    const adoptLive = async (name) => {
+        const { zones } = await retrying(() => client.list({ name }));
+        const view = zones.find((z) => z.name === name);
+        if (!view || view.owner !== null)
+            return;
+        const result = await writeSlot(() => retrying(() => client.adopt({ zones: [{ name }] })));
+        if (result.skipped.length > 0) {
+            throw new Error(`edge zones: zone ${name} cannot be adopted (${result.skipped[0]?.reason}); remove or fix it by hand`);
+        }
+    };
+    const create = (name) => writeSlot(() => retrying(() => client.create({ name }))).catch((error) => {
+        if (error instanceof EdgeApiError && error.code === 'not_configured') {
+            throw new Error(`edge zones: edge's Cloudflare token cannot create zones yet, so zone ${name} was not created; give it the Zone Edit permission or create the zone by hand`);
+        }
+        throw error;
+    });
+    return {
+        async findZoneByApex(domain) {
+            const labels = domain.toLowerCase().split('.');
+            for (let i = 0; labels.length - i >= 2; i++) {
+                const name = labels.slice(i).join('.');
+                const { zones } = await retrying(() => client.list({ name }));
+                const view = zones.find((z) => z.name === name);
+                if (view)
+                    return { id: view.id, name: view.name };
+            }
+            return undefined;
+        },
+        async createZone(name) {
+            await adoptLive(name);
+            try {
+                const made = await create(name);
+                return { id: made.id, name: made.name };
+            }
+            catch (error) {
+                if (!hasReason(error, 'exists'))
+                    throw error;
+                // The zone went live between the adopt and the create: adopt it and try once more.
+                await adoptLive(name);
+                const made = await create(name);
+                return { id: made.id, name: made.name };
+            }
+        },
+    };
+}

package/dist/plan/entry-edge-key.d.ts

@@ -35,6 +35,16 @@ export declare const entryEdgeMintedAtScopeKey: (entryKey: string) => string;
 export declare const EDGE_ENTRY_KEY_WARN_WINDOW_DAYS = 30;
 /** The reserved labels last sent to the edge service, as that sorted list's own JSON. */
 export declare const EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY = "edge_reserved_labels_applied";
+/**
+ * F3: the org's own Boule holds an edge key too, so a company edits its DNS
+ * records there (`records:read`, `records:edit`: edge's entry keys carry both).
+ * It rides the hosting-entry key path under this entry key. The leading
+ * underscore is one no hosting entry key can have (`ENTRY_KEY` in `org.ts`),
+ * so it never collides with a declared entry.
+ */
+export declare const BOULE_EDGE_ENTRY_KEY = "_boule";
+/** The recorded-id key of the Coolify app an edge key's env is written to. */
+export declare function edgeKeyAppRecordKey(org: DeclaredOrg, entryKey: string): string;
 export declare const entryEdgeKeyName: (org: DeclaredOrg, entry: HostingEntry) => string;
 /**
  * Every label under `org.domain` that foundry provisions or the platform

package/dist/plan/entry-edge-key.js

@@ -36,6 +36,20 @@ export const EDGE_ENTRY_KEY_WARN_WINDOW_DAYS = 30;
 const DAY_MS = 24 * 60 * 60 * 1000;
 /** The reserved labels last sent to the edge service, as that sorted list's own JSON. */
 export const EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY = 'edge_reserved_labels_applied';
+/**
+ * F3: the org's own Boule holds an edge key too, so a company edits its DNS
+ * records there (`records:read`, `records:edit`: edge's entry keys carry both).
+ * It rides the hosting-entry key path under this entry key. The leading
+ * underscore is one no hosting entry key can have (`ENTRY_KEY` in `org.ts`),
+ * so it never collides with a declared entry.
+ */
+export const BOULE_EDGE_ENTRY_KEY = '_boule';
+/** The recorded-id key of the Coolify app an edge key's env is written to. */
+export function edgeKeyAppRecordKey(org, entryKey) {
+    return entryKey === BOULE_EDGE_ENTRY_KEY
+        ? `coolify:boule:${org.id}`
+        : `coolify:app:${appStepKey(org, entryKey)}`;
+}
 export const entryEdgeKeyName = (org, entry) => `${org.slug}-${entry.key}-edge`;
 /**
  * Mail names foundry's mail setup puts on the org's domain. Stalwart's and
@@ -97,7 +111,15 @@ export function planEntryEdgeKeys(org, recordedIds, plannedSteps, readiness, now
     // throws before `runSteps` sees a `resourceId`), so scanning the main
     // prefix alone would never find it to revoke once its entry is gone
     // (#317 review).
-    const declared = new Set(org.hosting.entries.filter((e) => e.uses?.edge).map((e) => e.key));
+    // Boule's key is wanted whenever the org has its own domain (with-domain
+    // mode): edge refuses a company on oikos.host, so none is minted there.
+    const holders = org.hosting.entries
+        .filter((e) => e.uses?.edge)
+        .map((e) => ({ entryKey: e.key, name: entryEdgeKeyName(org, e) }));
+    if (org.domain) {
+        holders.push({ entryKey: BOULE_EDGE_ENTRY_KEY, name: `${org.slug}-boule-edge` });
+    }
+    const declared = new Set(holders.map((h) => h.entryKey));
     const mainPrefix = `edge:key:${org.id}:`;
     const undeliveredPrefix = 'edge_key_undelivered_';
     const goneEntryKeys = new Set();
@@ -146,11 +168,11 @@ export function planEntryEdgeKeys(org, recordedIds, plannedSteps, readiness, now
             },
         });
     }
-    for (const entry of org.hosting.entries) {
-        if (!entry.uses?.edge)
-            continue;
+    for (const holder of holders) {
+        const entry = { key: holder.entryKey };
         const stepKey = appStepKey(org, entry.key);
         const key = `edge:key:${stepKey}`;
+        const appRecordKey = edgeKeyAppRecordKey(org, entry.key);
         const liveKeyId = recordedIds[key] && recordedIds[entryEdgeRetiredScopeKey(entry.key)] !== recordedIds[key]
             ? recordedIds[key]
             : undefined;
@@ -186,12 +208,20 @@ export function planEntryEdgeKeys(org, recordedIds, plannedSteps, readiness, now
         // re-review) -- blocking indefinitely, as a prior round did, left the
         // orphan live for up to 365 days with no recorded trace an operator
         // could act on beyond this description.
+        // Boule's key is not something the org declared, so a platform with no
+        // edge service, or a Boule not planned yet, is quiet: no blocked row.
+        const isBoule = entry.key === BOULE_EDGE_ENTRY_KEY;
         if (!readiness.edgeReady) {
-            block('the host supplies no edge service, or the platform has not enabled it');
+            if (!isBoule)
+                block('the host supplies no edge service, or the platform has not enabled it');
             continue;
         }
-        if (!recordedIds[`coolify:app:${stepKey}`] && !planned('coolify', 'app', stepKey)) {
-            block("the entry's app is not recorded yet");
+        const appPlanned = isBoule
+            ? planned('coolify', 'boule', org.id)
+            : planned('coolify', 'app', stepKey);
+        if (!recordedIds[appRecordKey] && !appPlanned) {
+            if (!isBoule)
+                block("the entry's app is not recorded yet");
             continue;
         }
         steps.push({
@@ -201,7 +231,7 @@ export function planEntryEdgeKeys(org, recordedIds, plannedSteps, readiness, now
                 key: stepKey,
                 desired: {
                     mode: 'mint',
-                    name: entryEdgeKeyName(org, entry),
+                    name: holder.name,
                     edgeUrl: readiness.edgeUrl,
                 },
             },