@wtfalch/foundry 0.19.1 → 0.20.0

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

@@ -0,0 +1,54 @@
+import type { createEdgeClient } from '@wtfalch/edge';
+import { type WriteSlot } from './edge-dns.js';
+/** The edge SDK's platform rate limiting client: `createEdgeClient({ ... }).platform.ratelimits`. */
+export type EdgePlatformRateLimits = ReturnType<typeof createEdgeClient>['platform']['ratelimits'];
+/** One rate limiting rule, in the shape foundry has always sent Cloudflare. */
+export interface RateLimitRuleInput {
+    description: string;
+    expression: string;
+    action: string;
+    ratelimit: {
+        characteristics: string[];
+        period: number;
+        requests_per_period: number;
+        mitigation_timeout: number;
+    };
+}
+/**
+ * Foundry's Cloudflare rate limiting calls. Every one goes through this; the
+ * one implementation is {@link createEdgeRateLimits}, which speaks to the edge
+ * service with the platform credential.
+ */
+export interface RateLimitPort {
+    /** Every live rule in the zone, whoever owns it. */
+    listRateLimitRules(zoneId: string): Promise<Array<{
+        id: string;
+        description: string | null;
+    }>>;
+    /** Makes the rule, or returns the one already made for that zone and description. Never changes an existing rule. */
+    createRateLimitRule(zoneId: string, rule: RateLimitRuleInput): Promise<{
+        id: string;
+    }>;
+}
+/** Edge answers a create another create of the same rule is making `conflict` + `busy`. */
+export declare const EDGE_RATELIMITS_BUSY_ATTEMPTS = 5;
+export declare const hasReason: (error: unknown, reason: string) => boolean;
+/** Waits 1 s, 2 s, 4 s, then 8 s (the cap) between tries of a `busy` answer. */
+export declare function busyRetrier(sleepOption?: (ms: number) => Promise<void>): <T>(task: () => Promise<T>) => Promise<T>;
+export interface EdgeRateLimitsOptions {
+    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 RateLimitPort} over edge's `platform.ratelimits`.
+ *
+ * Edge answers a create of a live rule that has no edge row `exists`. So the
+ * adapter adopts that rule the moment it is about to create it: it lists the
+ * description, 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 rule edge reports as `taken` is an error. Create is keyed by zone
+ * and description and never compares content, so a rule that exists comes back
+ * unchanged. A `rate_limited` or `busy` answer is retried.
+ */
+export declare function createEdgeRateLimits(client: EdgePlatformRateLimits, options?: EdgeRateLimitsOptions): RateLimitPort;

package/dist/plan/edge-ratelimits.js

@@ -0,0 +1,79 @@
+import { EdgeApiError } from '@wtfalch/edge';
+import { EDGE_DNS_WRITE_CONCURRENCY, limiter, rateLimitRetrier, } from './edge-dns.js';
+/** Edge answers a create another create of the same rule is making `conflict` + `busy`. */
+export const EDGE_RATELIMITS_BUSY_ATTEMPTS = 5;
+const BUSY_FIRST_DELAY_MS = 1000;
+const BUSY_MAX_DELAY_MS = 8000;
+export const hasReason = (error, reason) => error instanceof EdgeApiError && error.code === 'conflict' && String(error.reason) === reason;
+/** Waits 1 s, 2 s, 4 s, then 8 s (the cap) between tries of a `busy` answer. */
+export 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 (!hasReason(error, 'busy') || attempt >= EDGE_RATELIMITS_BUSY_ATTEMPTS)
+                    throw error;
+                await sleep(Math.min(BUSY_FIRST_DELAY_MS * 2 ** (attempt - 1), BUSY_MAX_DELAY_MS));
+            }
+        }
+    };
+}
+/**
+ * {@link RateLimitPort} over edge's `platform.ratelimits`.
+ *
+ * Edge answers a create of a live rule that has no edge row `exists`. So the
+ * adapter adopts that rule the moment it is about to create it: it lists the
+ * description, 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 rule edge reports as `taken` is an error. Create is keyed by zone
+ * and description and never compares content, so a rule that exists comes back
+ * unchanged. A `rate_limited` or `busy` answer is retried.
+ */
+export function createEdgeRateLimits(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);
+    /** `zoneId/description` keys already adopted (or created) through this adapter. */
+    const adopted = new Set();
+    const adoptLive = async (zoneId, description) => {
+        const key = `${zoneId}/${description}`;
+        if (adopted.has(key))
+            return;
+        const { rules } = await retrying(() => client.list({ zoneId, description }));
+        const view = rules.find((r) => r.description === description && r.state !== 'removed');
+        if (view && view.owner === null) {
+            const result = await writeSlot(() => retrying(() => client.adopt({ rules: [{ zoneId, description, id: view.id }] })));
+            if (result.skipped.length > 0) {
+                throw new Error(`edge rate limits: rule '${description}' in zone ${zoneId} cannot be adopted (${result.skipped[0]?.reason}); remove or fix it by hand`);
+            }
+        }
+        adopted.add(key);
+    };
+    return {
+        async listRateLimitRules(zoneId) {
+            const { rules } = await retrying(() => client.list({ zoneId }));
+            return rules
+                .filter((r) => r.state !== 'removed')
+                .map((r) => ({ id: r.id, description: r.description }));
+        },
+        async createRateLimitRule(zoneId, rule) {
+            await adoptLive(zoneId, rule.description);
+            const create = () => writeSlot(() => retrying(() => client.create({ zoneId, ...rule })));
+            try {
+                return { id: (await create()).id };
+            }
+            catch (error) {
+                if (!hasReason(error, 'exists'))
+                    throw error;
+                // The rule went live between the adopt and the create: adopt it and try once more.
+                adopted.delete(`${zoneId}/${rule.description}`);
+                await adoptLive(zoneId, rule.description);
+                return { id: (await create()).id };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,44 @@
+import type { TunnelIngressRule, createEdgeClient } from '@wtfalch/edge';
+import { type WriteSlot } from './edge-dns.js';
+/** The edge SDK's platform tunnel client: `createEdgeClient({ ... }).platform.tunnels`. */
+export type EdgePlatformTunnels = ReturnType<typeof createEdgeClient>['platform']['tunnels'];
+/** One ingress rule. `path` tells rules on one hostname apart; the catch-all has none. */
+export type TunnelIngress = TunnelIngressRule;
+export interface TunnelSummary {
+    /** Cloudflare's tunnel id: what every edge tunnel call takes. */
+    id: string;
+    name: string;
+}
+/**
+ * Foundry's tunnel calls. Every tunnel call in foundry goes through this; the
+ * one implementation is {@link createEdgeTunnels}, which speaks to the edge
+ * service with the platform credential.
+ */
+export interface TunnelPort {
+    /** The tunnel named `name` that foundry may use (the platform's own, or one nobody adopted yet). */
+    findTunnelByName(name: string): Promise<TunnelSummary | undefined>;
+    createTunnel(name: string): Promise<TunnelSummary>;
+    /** Replaces the whole ingress; the last rule is the catch-all and has no hostname. */
+    putTunnelConfig(tunnelId: string, config: {
+        ingress: TunnelIngress[];
+    }): Promise<void>;
+    /** The connector token: a live credential. Hand it to the connector and nowhere else. */
+    getTunnelToken(tunnelId: string): Promise<string>;
+    deleteTunnel(tunnelId: string): Promise<void>;
+}
+/**
+ * Edge answers a config, token or delete call for a live tunnel with no edge
+ * row `not_found` ("create or adopt it first"). So the adapter adopts a tunnel
+ * the moment it is about to be configured, read the token of or deleted: a
+ * tunnel it found by name (or that a create refused with `exists`) and whose
+ * owner the list reported as `null` is remembered, and adopted just before the
+ * first such call. A tunnel foundry recorded in an earlier apply and now names
+ * by id only is looked up on `not_found`, adopted if unowned, and the call
+ * retried once. Adopt is idempotent and the list reports the owner afterwards,
+ * so nothing is recorded in the plan and a later apply adopts nothing. A
+ * name claim's tunnel (`organisation`) is never touched. A `rate_limited` answer is retried with edge's hint, up to 5 tries.
+ */
+export declare function createEdgeTunnels(client: EdgePlatformTunnels, options?: {
+    sleep?: (ms: number) => Promise<void>;
+    writeSlot?: WriteSlot;
+}): TunnelPort;

package/dist/plan/edge-tunnels.js

@@ -0,0 +1,108 @@
+import { EdgeApiError } from '@wtfalch/edge';
+import { EDGE_DNS_WRITE_CONCURRENCY, limiter, rateLimitRetrier, } from './edge-dns.js';
+const isNotFound = (error) => error instanceof EdgeApiError && error.code === 'not_found';
+/** Edge's 409 for a live tunnel with the name and no edge row. */
+const isExists = (error) => error instanceof EdgeApiError && error.code === 'conflict' && error.reason === 'exists';
+/**
+ * Edge answers a config, token or delete call for a live tunnel with no edge
+ * row `not_found` ("create or adopt it first"). So the adapter adopts a tunnel
+ * the moment it is about to be configured, read the token of or deleted: a
+ * tunnel it found by name (or that a create refused with `exists`) and whose
+ * owner the list reported as `null` is remembered, and adopted just before the
+ * first such call. A tunnel foundry recorded in an earlier apply and now names
+ * by id only is looked up on `not_found`, adopted if unowned, and the call
+ * retried once. Adopt is idempotent and the list reports the owner afterwards,
+ * so nothing is recorded in the plan and a later apply adopts nothing. A
+ * name claim's tunnel (`organisation`) is never touched. A `rate_limited` answer is retried with edge's hint, up to 5 tries.
+ */
+export function createEdgeTunnels(client, options = {}) {
+    const retrying = rateLimitRetrier(options.sleep);
+    const tunnels = {
+        list: (filter) => retrying(() => client.list(filter)),
+        create: (input) => retrying(() => client.create(input)),
+        putConfig: (id, input) => retrying(() => client.putConfig(id, input)),
+        token: (id) => retrying(() => client.token(id)),
+        remove: (id) => retrying(() => client.remove(id)),
+        adopt: (input) => retrying(() => client.adopt(input)),
+    };
+    const writeSlot = options.writeSlot ?? limiter(EDGE_DNS_WRITE_CONCURRENCY);
+    /** tunnel id -> a seen live tunnel with no edge row yet. */
+    const unadopted = new Map();
+    const remember = (views) => {
+        for (const view of views) {
+            if (view.owner === null)
+                unadopted.set(view.id, view);
+            else
+                unadopted.delete(view.id);
+        }
+    };
+    const adopt = async (view) => {
+        const result = await writeSlot(() => tunnels.adopt({ tunnels: [{ name: view.name, id: view.id }] }));
+        const skipped = result.skipped[0];
+        if (skipped) {
+            throw new Error(skipped.reason === 'organisation'
+                ? `edge tunnels: ${view.name} is a company's own tunnel; foundry will not change it`
+                : `edge tunnels: ${view.name} cannot be adopted (${skipped.reason}); remove or fix it by hand`);
+        }
+        if (result.notFound.length > 0) {
+            throw new EdgeApiError(404, 'not_found', `edge tunnels: ${view.name} is no longer live`);
+        }
+        unadopted.delete(view.id);
+    };
+    /** Runs a call on a tunnel; adopts it first when seen unowned, and once more on `not_found`. */
+    const onTunnel = async (tunnelId, call) => {
+        const seen = unadopted.get(tunnelId);
+        if (seen)
+            await adopt(seen);
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            const live = (await tunnels.list()).tunnels;
+            remember(live);
+            const view = live.find((t) => t.id === tunnelId);
+            if (!view || view.owner !== null)
+                throw error;
+            await adopt(view);
+            return call();
+        }
+    };
+    const usable = (views) => views.find((v) => v.owner === 'platform') ?? views.find((v) => v.owner === null);
+    const findTunnelByName = async (name) => {
+        const { tunnels: found } = await tunnels.list({ name });
+        remember(found);
+        const view = usable(found.filter((v) => v.name === name && v.state !== 'removed'));
+        return view ? { id: view.id, name: view.name } : undefined;
+    };
+    return {
+        findTunnelByName,
+        async createTunnel(name) {
+            try {
+                const created = await writeSlot(() => tunnels.create({ name }));
+                return { id: created.id, name: created.name };
+            }
+            catch (error) {
+                // A live tunnel of this name exists with no edge row (made before edge
+                // owned tunnels): use it, adopting it before its first config call.
+                if (!isExists(error))
+                    throw error;
+                const found = await findTunnelByName(name);
+                if (!found)
+                    throw error;
+                return found;
+            }
+        },
+        async putTunnelConfig(tunnelId, config) {
+            await onTunnel(tunnelId, () => writeSlot(() => tunnels.putConfig(tunnelId, config)));
+        },
+        async getTunnelToken(tunnelId) {
+            const { token } = await onTunnel(tunnelId, () => tunnels.token(tunnelId));
+            return token;
+        },
+        async deleteTunnel(tunnelId) {
+            await onTunnel(tunnelId, () => writeSlot(() => tunnels.remove(tunnelId)));
+        },
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { createEdgeClient } from '@wtfalch/edge';
+import { type WriteSlot } from './edge-dns.js';
+import type { WorkersPort } from './executor.js';
+/** The edge SDK's platform Workers client: `createEdgeClient({ ... }).platform.workers`. */
+export type EdgePlatformWorkers = ReturnType<typeof createEdgeClient>['platform']['workers'];
+/** Edge answers a first upload of a name that another upload is making, or a delete in flight, `conflict` + `busy`. */
+export declare const EDGE_WORKERS_BUSY_ATTEMPTS = 5;
+/** What the host supplies: fetches the artifact and returns its bytes, verified against `sha256`. Foundry never fetches. */
+export interface EdgeWorkersOptions {
+    fetchArtifact: (url: string, sha256: string) => Promise<Uint8Array>;
+    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 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 declare function createEdgeWorkers(client: EdgePlatformWorkers, options: EdgeWorkersOptions): WorkersPort;

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