@wtfalch/foundry 0.33.1 → 0.35.1

package/dist/plan/company-backups.js

@@ -0,0 +1,101 @@
+import { ownsServices } from '../org.js';
+import { BOULE_DATABASE_SCOPE_KEY } from './boule.js';
+import { CHAT_REKEY_MAS_DB_SCOPE_KEY, CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY } from './executor.js';
+/**
+ * F6: the Postgres databases of a company that get a nightly backup, and the
+ * recorded id each one's uuid sits under. The keys are second, documented
+ * copies of the constants in `executor.ts` and `platform-providers.ts` (the
+ * way `PLATFORM_BACKUP_DATABASE_SCOPE_KEYS` copies the platform's): a renamed
+ * key shows up as a database the planner no longer sees, and the test in
+ * `platform-providers.backup.test.ts` plans every name here from a recorded id.
+ * `app` is the hosting entry's database, recorded as a resource id.
+ */
+export function companyDatabaseKeys(org) {
+    return {
+        app: `coolify:database:${org.id}`,
+        cms: 'coolify_cms_database',
+        auth: 'coolify_platform_auth_database',
+        files: 'coolify_platform_files_database',
+        jobs: 'coolify_jobs_database',
+        chat: 'coolify_chat_service_database',
+        calls: 'coolify_calls_service_database',
+        synapse: 'coolify_calls_synapse_database',
+        mas: 'coolify_calls_mas_database',
+        chat_synapse: 'coolify_chat_synapse_database',
+        chat_mas: 'coolify_chat_mas_database',
+        boule: BOULE_DATABASE_SCOPE_KEY,
+        chat_rekey_synapse: CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY,
+        chat_rekey_mas: CHAT_REKEY_MAS_DB_SCOPE_KEY,
+    };
+}
+/** What every recorded-id key of a company database's backup schedule starts with. */
+export const BACKUP_SCOPE_PREFIX = 'backup_';
+/** The recorded-id key a company database's backup schedule uuid is stored under. */
+export function backupScopeKey(db) {
+    return `${BACKUP_SCOPE_PREFIX}${db}`;
+}
+/** The databases an upgrade of `service` can migrate, by the names in {@link companyDatabaseKeys}. Empty: not coverable here. */
+export function databasesForService(service) {
+    switch (service) {
+        case 'zitadel':
+            return ['auth'];
+        case 'files':
+            return ['files'];
+        case 'jobs':
+            return ['jobs'];
+        case 'synapse':
+            return ['synapse', 'chat_synapse'];
+        case 'mas':
+            return ['mas', 'chat_mas'];
+        case 'postgres':
+            return 'all';
+        default:
+            return [];
+    }
+}
+/**
+ * One `coolify:backup:<orgSlug>:<db>` step per company database that has a
+ * recorded uuid and no recorded backup yet. `storageUuid` undefined means the
+ * host did not wire backups, so nothing is planned and nothing is said; null
+ * means the platform's backup storage is not registered, so each database is
+ * reported as blocked instead (rule 2). A company that runs its own mail
+ * server carries a note that the Stalwart volume has no Postgres to dump.
+ */
+export function planCompanyBackups(org, recordedIds, storageUuid) {
+    const steps = [];
+    const blocked = [];
+    if (storageUuid === undefined)
+        return { steps, blocked };
+    for (const [db, key] of Object.entries(companyDatabaseKeys(org))) {
+        const databaseId = recordedIds[key];
+        if (!databaseId || recordedIds[backupScopeKey(db)])
+            continue;
+        if (!storageUuid) {
+            blocked.push({
+                description: `${org.slug}'s ${db} database backup is blocked, not planned: the platform's backup storage is not registered yet`,
+                key: `backup-blocked:${org.slug}:${db}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'backup',
+                key: `${org.slug}:${db}`,
+                desired: { databaseId, database: db, storageUuid },
+            },
+            step: {
+                description: `schedule a nightly backup of ${org.slug}'s ${db} database to the platform's backup bucket`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    if (ownsServices(org)) {
+        blocked.push({
+            description: `${org.slug}'s mail server keeps its data on a volume, not in Postgres: no backup covers it yet`,
+            key: 'backup-not-covered:mail',
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/deploy-health.d.ts

@@ -69,6 +69,12 @@ export interface DeployAndWaitPort {
         deploymentUuid: string;
         status: string;
     }>;
+    /** Present on a real client; `build-record.ts` reads it to record the built commit. */
+    listApplicationDeployments?(uuid: string, take?: number): Promise<Array<{
+        deployment_uuid: string;
+        commit?: string;
+        status: string;
+    }>>;
 }
 /**
  * How a call site proves the new version is the one that answers (or that
@@ -114,7 +120,9 @@ export interface DeployHealthRuntime {
  * with no such ordering constraint calls {@link waitForNewDeployment}
  * instead, never this plus {@link waitForHealthyVersion} by hand.
  */
-export declare function waitForDeploymentFinished(coolify: DeployAndWaitPort, appId: string, runtime: DeployHealthRuntime, label: string, appliedRefDescription: string): Promise<void>;
+export declare function waitForDeploymentFinished(coolify: DeployAndWaitPort, appId: string, runtime: DeployHealthRuntime, label: string, appliedRefDescription: string): Promise<{
+    deploymentUuid: string;
+}>;
 /**
  * Phase 2 alone: the health check named by `health.kind`, with no deploy and
  * no Coolify polling -- see {@link waitForDeploymentFinished}'s own doc
@@ -133,4 +141,6 @@ export declare function waitForHealthyVersion(appId: string, health: DeployHealt
  * what is still live so a caller's error is actionable without the helper
  * itself knowing any step's scope keys.
  */
-export declare function waitForNewDeployment(coolify: DeployAndWaitPort, appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<void>;
+export declare function waitForNewDeployment(coolify: DeployAndWaitPort, appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<{
+    deploymentUuid: string;
+}>;

package/dist/plan/deploy-health.js

@@ -93,6 +93,7 @@ export async function waitForDeploymentFinished(coolify, appId, runtime, label,
     if (status !== DEPLOYMENT_SUCCEEDED) {
         throw new Error(`${label}: the deployment (${deploymentUuid}) of ${appId} did not finish (status: ${status}); ${appliedRefDescription}. Apply again`);
     }
+    return { deploymentUuid };
 }
 /**
  * Phase 2 alone: the health check named by `health.kind`, with no deploy and
@@ -132,8 +133,9 @@ export async function waitForHealthyVersion(appId, health, runtime, sleep, label
  * itself knowing any step's scope keys.
  */
 export async function waitForNewDeployment(coolify, appId, health, runtime, sleep, label, appliedRefDescription) {
-    await waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription);
+    const { deploymentUuid } = await waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription);
     await waitForHealthyVersion(appId, health, runtime, sleep, label, appliedRefDescription);
+    return { deploymentUuid };
 }
 async function matchesHealth(fetchImpl, health) {
     try {

package/dist/plan/destinations.d.ts

@@ -0,0 +1,73 @@
+import type { CoolifyPort } from './executor.js';
+/** The Docker network of the server's default destination: everything on the platform side. */
+export declare 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 declare let COMPANY_NETWORKS: boolean;
+/** Test-only: turns the per-company networks on or off. */
+export declare function setCompanyNetworksForTests(on: boolean): void;
+/** A company runs on the platform network: the owner always, a customer while {@link COMPANY_NETWORKS} is off. */
+export declare function onPlatformNetwork(ownerCompany: boolean | undefined): boolean;
+/** Coolify's destination name for a company, so a listing says who owns it. */
+export declare const COMPANY_DESTINATION_NAME_PREFIX = "foundry:";
+/** Docker's default address pools give about 30 user networks; stop a little short. */
+export declare const DEFAULT_MAX_DESTINATIONS = 25;
+/** The company's own Docker network: `co-<slug>`. */
+export declare function companyNetworkName(slug: string): string;
+/** Refuses a name Docker or this module cannot take; the message names no value. */
+export declare function validateNetworkName(network: unknown): string;
+/** A server already holds as many networks as the capacity gate allows. */
+export declare class DestinationCapacityError extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+type DestinationRaw = Pick<CoolifyPort, 'raw'>;
+/** The uuid of the server's destination on `network`, or undefined. Creates nothing. */
+export declare function findDestination(coolify: DestinationRaw, serverUuid: string, network: string): Promise<string | undefined>;
+/**
+ * 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 declare function ensureDestination(coolify: DestinationRaw, serverUuid: string, network: string, options?: {
+    name?: string;
+    maxDestinations?: number;
+}): Promise<string>;
+type PlacedPort = Partial<Pick<CoolifyPort, '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 declare function placed<C extends PlacedPort>(coolify: C, resolve: (serverUuid: string) => Promise<string | undefined>): C;
+/**
+ * `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 declare function placedOnPlatform<C extends PlacedPort & {
+    raw?: CoolifyPort['raw'];
+}>(coolify: C): C;
+/**
+ * `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 declare function placedByScope<C extends PlacedPort>(coolify: C, scope: () => {
+    key: string;
+    resolve: (serverUuid: string) => Promise<string | undefined>;
+} | undefined): C;
+export {};

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,8 +41,12 @@ 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. */
+    loginHostServesDiscovery?: boolean;
     /** The executor's ZITADEL client has `updateOidcAppIdTokenUserinfoAssertion`; without it `planIdTokenUserinfo` plans nothing. */
     zitadelIdTokenUserinfo?: boolean;
     /** F5: the executor was built with a `broker` port. */
@@ -59,6 +63,47 @@ export interface PlanOrgOptions {
     ownerInviteMail?: boolean;
     /** The platform's own service hostnames: `edgeReservedLabels` reserves them under the org's domain, and a wildcard Worker route (`planWorkers`) keeps them out. */
     platformHostnames?: readonly string[];
+    /** The executor was built with an `ownServices` port. Without it an own org's own-service steps are blocked. */
+    ownServices?: boolean;
+    /** An own org's Lettermint key (`orgTarget(org).refs.brokerMailKey`) is held. */
+    ownMailKeyHeld?: boolean;
+    /** The executor can mint an own org's Lettermint key (`FoundryStepExecutor.ownMailKeyMintable`). */
+    ownMailKeyMintable?: boolean;
+    /** The own jobs admin token's held-key ref holds a value. */
+    ownJobsTokenHeld?: boolean;
+    /** The own media server's key pair ref holds a value. */
+    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. */
+    ownFilesDeps?: {
+        keys: boolean;
+        bucket: boolean;
+    };
+    /**
+     * Which ports the own files storage key step needs the host supplied. Absent: the executor was not
+     * asked, and the step is neither planned nor reported.
+     */
+    ownFilesR2Ports?: {
+        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;
@@ -128,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