@wtfalch/foundry 0.34.0 → 0.35.1

package/dist/plan/destinations.js

@@ -0,0 +1,217 @@
+import { OWN_LIMITS_TIMEOUT_MS } from './own-limits.js';
+/** The Docker network of the server's default destination: everything on the platform side. */
+export const PLATFORM_NETWORK = 'coolify';
+/**
+ * Whether a customer company gets its own `co-<slug>` network. Off for go-live: every company shares the
+ * platform network, because Archon (on it) calls each company's files, mail admin and jobs at internal
+ * addresses and Coolify cannot put Archon on a second network. Per-company networks return after go-live,
+ * once a design lists every call that crosses the split. `let` so tests can turn it on.
+ */
+export let COMPANY_NETWORKS = false;
+/** Test-only: turns the per-company networks on or off. */
+export function setCompanyNetworksForTests(on) {
+    COMPANY_NETWORKS = on;
+}
+/** A company runs on the platform network: the owner always, a customer while {@link COMPANY_NETWORKS} is off. */
+export function onPlatformNetwork(ownerCompany) {
+    return ownerCompany === true || !COMPANY_NETWORKS;
+}
+/** Coolify's destination name for a company, so a listing says who owns it. */
+export const COMPANY_DESTINATION_NAME_PREFIX = 'foundry:';
+/** A Docker network name is at most 64 characters; keep room under it. */
+const MAX_NETWORK_LENGTH = 60;
+const NETWORK_NAME = /^[a-z0-9][a-z0-9_.-]*$/;
+/** Docker's default address pools give about 30 user networks; stop a little short. */
+export const DEFAULT_MAX_DESTINATIONS = 25;
+/** The company's own Docker network: `co-<slug>`. */
+export function companyNetworkName(slug) {
+    const network = `co-${slug}`;
+    return validateNetworkName(network);
+}
+/** Refuses a name Docker or this module cannot take; the message names no value. */
+export function validateNetworkName(network) {
+    if (typeof network !== 'string' || network.length === 0)
+        throw new Error('destination: the network name is empty');
+    if (network.length > MAX_NETWORK_LENGTH)
+        throw new Error(`destination: the network name is over ${MAX_NETWORK_LENGTH} characters`);
+    if (!NETWORK_NAME.test(network))
+        throw new Error('destination: the network name has a character outside a-z, 0-9, _, . and -');
+    return network;
+}
+/** A server already holds as many networks as the capacity gate allows. */
+export class DestinationCapacityError extends Error {
+    limit;
+    constructor(limit) {
+        super(`destination: the server already has ${limit} destinations; raise Docker's address pools`);
+        this.limit = limit;
+        this.name = 'DestinationCapacityError';
+    }
+}
+function readList(body) {
+    if (!Array.isArray(body))
+        throw new Error('destination: the destination list is not an array');
+    const out = [];
+    for (const row of body) {
+        const r = row;
+        if (r && typeof r.uuid === 'string' && typeof r.network === 'string')
+            out.push({ uuid: r.uuid, network: r.network });
+    }
+    return out;
+}
+async function bounded(work, what) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`destination: ${what} timed out`)), OWN_LIMITS_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The uuid of the server's destination on `network`, or undefined. Creates nothing. */
+export async function findDestination(coolify, serverUuid, network) {
+    const path = `/servers/${encodeURIComponent(serverUuid)}/destinations`;
+    const body = await bounded(coolify.raw('GET', path), 'listing the destinations');
+    // A listing that is not an array names no destination: the create goes out as it was.
+    if (!Array.isArray(body))
+        return undefined;
+    return readList(body).find((r) => r.network === network)?.uuid;
+}
+/**
+ * The uuid of the server's destination on `network`; creates it when absent.
+ * Coolify makes the Docker network and attaches its proxy to it when the
+ * destination is created. Each call has a 60 second timeout. A create that
+ * fails (Coolify answers 409 when the network already exists) is followed by
+ * one more listing; found there, that uuid is used, so two runs at once and a
+ * re-run after a crash converge on one destination. `maxDestinations` stops a
+ * create on a server that already holds that many (`DestinationCapacityError`,
+ * before anything is created).
+ */
+export async function ensureDestination(coolify, serverUuid, network, options = {}) {
+    validateNetworkName(network);
+    const path = `/servers/${encodeURIComponent(serverUuid)}/destinations`;
+    const list = async () => readList(await bounded(coolify.raw('GET', path), 'listing the destinations'));
+    const found = (rows) => rows.find((r) => r.network === network)?.uuid;
+    const rows = await list();
+    const have = found(rows);
+    if (have)
+        return have;
+    const limit = options.maxDestinations ?? DEFAULT_MAX_DESTINATIONS;
+    if (rows.length >= limit)
+        throw new DestinationCapacityError(limit);
+    try {
+        const created = (await bounded(coolify.raw('POST', path, {
+            network,
+            name: options.name ?? `${COMPANY_DESTINATION_NAME_PREFIX}${network}`,
+        }), 'creating the destination'));
+        if (created && typeof created.uuid === 'string')
+            return created.uuid;
+    }
+    catch {
+        // Fall through to one more listing: a 409 means someone else made it.
+        const again = found(await list());
+        if (again)
+            return again;
+        throw new Error('destination: creating the destination failed');
+    }
+    const after = found(await list());
+    if (after)
+        return after;
+    throw new Error('destination: the created destination is not in the listing');
+}
+const CREATES = [
+    'createGithubAppApplication',
+    'createDockerImageApplication',
+    'createDockerfileApplication',
+    'createPostgresDatabase',
+];
+/**
+ * The Coolify port with `destination_uuid` added to the four create calls
+ * (the other calls pass through). `resolve` gives the destination of the
+ * input's `server_uuid`; it runs once per server for this port. A create that
+ * already names a destination keeps it. A `resolve` that gives nothing leaves
+ * the create as it was. Composes with `limited`: `limited(placed(port, ...))`.
+ */
+export function placed(coolify, resolve) {
+    const cache = new Map();
+    const destinationOf = (serverUuid) => {
+        let hit = cache.get(serverUuid);
+        if (!hit) {
+            hit = resolve(serverUuid);
+            cache.set(serverUuid, hit);
+            hit.catch(() => cache.delete(serverUuid));
+        }
+        return hit;
+    };
+    const over = {};
+    for (const method of CREATES) {
+        const create = coolify[method];
+        if (!create)
+            continue;
+        over[method] = async (input) => {
+            if (input.destination_uuid)
+                return create.call(coolify, input);
+            const destination = await destinationOf(input.server_uuid);
+            return create.call(coolify, (destination ? { ...input, destination_uuid: destination } : input));
+        };
+    }
+    return new Proxy(coolify, {
+        get(target, prop) {
+            if (typeof prop === 'string' && prop in over)
+                return over[prop];
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+/**
+ * `placed` on the platform's destination (Docker network `coolify`) of each
+ * server. Once a server has a company destination, a create without
+ * `destination_uuid` is refused by Coolify, so every platform create names the
+ * default one. A server whose listing has no `coolify` destination, and a port
+ * with no `raw`, get the create unchanged.
+ */
+export function placedOnPlatform(coolify) {
+    const { raw } = coolify;
+    if (typeof raw !== 'function')
+        return coolify;
+    return placed(coolify, (serverUuid) => findDestination({ raw: raw.bind(coolify) }, serverUuid, PLATFORM_NETWORK));
+}
+/**
+ * `placed`, with the destination chosen by the step now running: `scope` gives a key (the company) and
+ * the resolver for it, or nothing, and a create then goes out as it was. One `placed` wrapper is made
+ * per key, so its answers are never shared between companies.
+ */
+export function placedByScope(coolify, scope) {
+    const perKey = new Map();
+    const over = {};
+    for (const method of CREATES) {
+        const create = coolify[method];
+        if (!create)
+            continue;
+        over[method] = async (input) => {
+            const current = scope();
+            if (!current)
+                return create.call(coolify, input);
+            let wrapper = perKey.get(current.key);
+            if (!wrapper) {
+                wrapper = placed(coolify, current.resolve);
+                perKey.set(current.key, wrapper);
+            }
+            const made = wrapper[method];
+            return made.call(wrapper, input);
+        };
+    }
+    return new Proxy(coolify, {
+        get(target, prop) {
+            if (typeof prop === 'string' && prop in over)
+                return over[prop];
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}

package/dist/plan/diff.d.ts

@@ -41,6 +41,8 @@ export interface DraftStep {
  * New ones go here, not in new positional arguments (rule 7).
  */
 export interface PlanOrgOptions {
+    /** The platform's edge has the `oikos.host` zone: a company without a domain waits on it for its own services. */
+    oikosZoneReady?: boolean;
     /** #267: the executor was built with a `loginHostBindings` port. */
     loginHostBindings?: boolean;
     /** A live read said the org's login host serves OIDC discovery as `https://<host>`. Absent: not read, so Agora keeps the platform issuer. */
@@ -73,6 +75,14 @@ export interface PlanOrgOptions {
     ownSfuKeysHeld?: boolean;
     /** The relay is declared and has applied a route list; an own org's mail server waits for it. */
     mailRelayApplied?: boolean;
+    /** The host port an own org's mail server publishes for the relay (`plan-apply.ts` allocates it). */
+    ownMailSmtpPort?: number;
+    /**
+     * The relay has applied a route for this org's mail domain. `false` holds the org's `coolify:mail`
+     * step: it publishes the MX, and until the relay routes the domain senders get a permanent 5xx.
+     * Absent counts as held.
+     */
+    mailRelayRoute?: boolean;
     /** The host confirmed the ports of an own org's media server slot are open on the server. */
     sfuPortsOpen?: boolean;
     /** What the executor's own files dependencies supply: valid keys worker settings, and a bucket port. Absent counts as neither. */
@@ -88,6 +98,12 @@ export interface PlanOrgOptions {
         r2Keys: boolean;
         storeR2Credentials: boolean;
     };
+    /**
+     * F6: the uuid of the platform's backup storage on Coolify. Absent: the host
+     * wired no backups, so a company's databases get no backup step. `null`: wired,
+     * but the storage is not registered, so each database is reported blocked.
+     */
+    backupStorageUuid?: string | null;
 }
 export interface PlanDetail {
     orgId: OrgId;
@@ -157,14 +173,7 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * against this seam.
  */
 export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>, agoraHost?: AgoraHostReading, jobsAvailable?: boolean, platformReadiness?: OrgPlatformReadiness, options?: PlanOrgOptions): PlanDetail;
-/**
- * #488: the bare hostname out of an issuer URL (`https://<hostname>`, the
- * only shape {@link agoraHostValuesFromPlatform} or a host-supplied
- * `AgoraHostPort` ever hands back), or `null` when there is no issuer to
- * read one from. What {@link loginHostnameFor} compares the org's own
- * computed `auth.<domain>` against, so the platform's own org never plans
- * its login host equal to the shared ZITADEL instance's own.
- */
+/** True when `org` is the platform's owner company. */
 export declare function isPlatformOwnOrg(org: Pick<DeclaredOrg, 'id'>, platformOwnerOrgId: string | null): boolean;
 /**
  * What {@link planOrgPostgres} reports about the org's one shared Postgres