@wtfalch/foundry 0.32.0 → 0.34.0

package/dist/plan/own-sfu.js

@@ -0,0 +1,255 @@
+import { mintLivekitCredentials } from '../calls-sfu-keys.js';
+import { LIVEKIT_SIGNALLING_PORT, sfuSlotPorts } from '../calls-sfu.js';
+import { ensureCloudflaredConnector } from './cloudflared-connector.js';
+import { waitForNewDeployment } from './deploy-health.js';
+import { healthCheckSettings } from './health-check-settings.js';
+import { recordOwnDnsHostname } from './own-dns.js';
+/** The LiveKit image, the same repository the shared SFU runs. */
+export const OWN_SFU_IMAGE = 'livekit/livekit-server';
+export const OWN_SFU_APP_SCOPE_KEY = 'coolify_own_sfu_app';
+export const OWN_SFU_TUNNEL_SCOPE_KEY = 'cloudflare_own_sfu_tunnel';
+export const OWN_SFU_CONNECTOR_APP_SCOPE_KEY = 'coolify_own_sfu_connector_app';
+/** Set to the app id before the key pair leaves, cleared after the pair is delivered and written to the app. */
+export const OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY = 'own_sfu_keys_undelivered';
+/** The app id once the company's key pair is delivered and in the app's env. */
+export const OWN_SFU_KEYS_SCOPE_KEY = 'own_sfu_keys_set';
+export const OWN_SFU_DEPLOY_PENDING_SCOPE_KEY = 'own_sfu_deploy_pending';
+export const OWN_SFU_APPLIED_VERSION_SCOPE_KEY = 'own_sfu_applied_version';
+export const OWN_SFU_APPLIED_SLOT_SCOPE_KEY = 'own_sfu_applied_slot';
+export const OWN_SFU_APPLIED_HOSTNAME_SCOPE_KEY = 'own_sfu_applied_hostname';
+export const SFU_INTERNAL_URL_SCOPE_KEY = 'sfu_internal_url';
+export const SFU_PUBLIC_URL_SCOPE_KEY = 'sfu_public_url';
+const KEYS_DELIVERY_ATTEMPTS = 3;
+const CONFIG_ENV = 'LIVEKIT_CONFIG';
+/** The Docker `ports_mappings` string for a slot: the UDP range and the TCP fallback port, one to one. */
+export function sfuPortsMappings(slot) {
+    const { udpStart, udpEnd, tcp } = sfuSlotPorts(slot);
+    return `${udpStart}-${udpEnd}:${udpStart}-${udpEnd}/udp,${tcp}:${tcp}`;
+}
+/**
+ * LiveKit takes its whole config from one env value. `node_ip` is the
+ * server's address: the app is not on the host network, so the media ports
+ * reach it through the published mappings.
+ */
+export function sfuConfig(input) {
+    const { udpStart, udpEnd, tcp } = sfuSlotPorts(input.slot);
+    return [
+        `port: ${LIVEKIT_SIGNALLING_PORT}`,
+        'rtc:',
+        `  tcp_port: ${tcp}`,
+        `  port_range_start: ${udpStart}`,
+        `  port_range_end: ${udpEnd}`,
+        '  use_external_ip: false',
+        `  node_ip: ${input.nodeIp}`,
+        'keys:',
+        `  ${input.keys.apiKey}: ${input.keys.apiSecret}`,
+        '',
+    ].join('\n');
+}
+function heldPairOf(value) {
+    if (!value)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+    const { apiKey, apiSecret } = (parsed ?? {});
+    return typeof apiKey === 'string' &&
+        typeof apiSecret === 'string' &&
+        KEY_PAIR_SHAPE.test(apiKey) &&
+        KEY_PAIR_SHAPE.test(apiSecret)
+        ? { apiKey, apiSecret }
+        : null;
+}
+function keysOf(config) {
+    const match = /^keys:\n {2}([A-Za-z0-9]+): ([A-Za-z0-9]+)$/m.exec(config ?? '');
+    return match ? { apiKey: match[1], apiSecret: match[2] } : null;
+}
+const KEY_PAIR_SHAPE = /^[A-Za-z0-9]{8,128}$/;
+/**
+ * One company's LiveKit media server as a Coolify app: the image, its slot's
+ * ports published to the server, and a tunnel for signalling at `sfu.<domain>`.
+ * The company's single key pair is minted once, delivered to
+ * `target.refs.livekitKeys` as JSON, and written to the app's env; it is never
+ * recorded. Rules 1 to 6 of `CLAUDE.md` "Platform steps".
+ */
+export async function provisionSfuApp(scope, deps, target, input) {
+    const { coolify, network, deliverSecret, runtime } = deps;
+    const label = `own step coolify:own-sfu for ${target.id}`;
+    sfuSlotPorts(input.slot);
+    const zoneId = await network.zoneId(input.apex);
+    if (!zoneId)
+        throw new Error(`${label}: no Cloudflare zone for ${input.apex}`);
+    const projectUuid = await input.project.ensure(coolify, scope);
+    const { environment } = await coolify.findOrCreateEnvironment(projectUuid, 'production');
+    const servers = await coolify.listServers();
+    const server = servers.find((s) => s.is_usable && s.is_reachable) ?? servers[0];
+    if (!server)
+        throw new Error(`${label}: no usable Coolify server is registered`);
+    if (!server.ip)
+        throw new Error(`${label}: the Coolify server has no address to give LiveKit`);
+    const existingApp = await coolify.findApplicationByName(target.names.sfuApp, {
+        environmentIds: [environment.id],
+    });
+    let appId;
+    if (existingApp) {
+        appId = existingApp.uuid;
+    }
+    else {
+        appId = (await coolify.createDockerImageApplication({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            docker_registry_image_name: OWN_SFU_IMAGE,
+            docker_registry_image_tag: input.version,
+            ports_exposes: String(LIVEKIT_SIGNALLING_PORT),
+            ports_mappings: sfuPortsMappings(input.slot),
+            name: target.names.sfuApp,
+            description: `LiveKit media server for ${target.id}`,
+            instant_deploy: false,
+        })).uuid;
+    }
+    scope.recordScopeId(OWN_SFU_APP_SCOPE_KEY, appId);
+    const recorded = scope.recordedIds();
+    const changed = recorded[OWN_SFU_APPLIED_VERSION_SCOPE_KEY] !== input.version ||
+        recorded[OWN_SFU_APPLIED_SLOT_SCOPE_KEY] !== String(input.slot) ||
+        recorded[OWN_SFU_APPLIED_HOSTNAME_SCOPE_KEY] !== input.hostname;
+    // Set on every run: a declared version or slot reaches an existing app here.
+    await coolify.updateApplication(appId, {
+        custom_internal_name: target.internal.sfu,
+        docker_registry_image_tag: input.version,
+        ports_exposes: String(LIVEKIT_SIGNALLING_PORT),
+        ports_mappings: sfuPortsMappings(input.slot),
+        ...healthCheckSettings('/', LIVEKIT_SIGNALLING_PORT),
+    });
+    const liveConfig = (await coolify.listEnvs(appId)).find((e) => e.key === CONFIG_ENV && !e.is_preview)?.value;
+    let keys;
+    let keysJustSet = false;
+    if (scope.recordedIds()[OWN_SFU_KEYS_SCOPE_KEY]) {
+        const held = keysOf(liveConfig);
+        if (!held) {
+            throw new Error(`${label}: the app's ${CONFIG_ENV} no longer holds the company's key`);
+        }
+        keys = held;
+        deps.onSecret?.(keys.apiSecret);
+    }
+    else {
+        const lost = scope.recordedIds()[OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY];
+        const resumed = lost
+            ? heldPairOf((await deps.readSecret?.(target.refs.livekitKeys)) ?? null)
+            : null;
+        if (lost && !resumed) {
+            throw new Error(`${label}: a LiveKit key pair (${lost}) was minted but never confirmed delivered; remove the recorded key ${OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY} to mint a new one`);
+        }
+        if (resumed) {
+            keys = resumed;
+            deps.onSecret?.(keys.apiSecret);
+            keysJustSet = true;
+        }
+        else {
+            keys = (deps.mintLivekitCredentials ?? mintLivekitCredentials)();
+            if (!KEY_PAIR_SHAPE.test(keys.apiKey) || !KEY_PAIR_SHAPE.test(keys.apiSecret)) {
+                throw new Error(`${label}: the minted LiveKit key has characters the config cannot hold`);
+            }
+            deps.onSecret?.(keys.apiSecret);
+            scope.recordScopeId(OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY, appId);
+            await scope.persist();
+            let delivered = false;
+            const payload = JSON.stringify({ apiKey: keys.apiKey, apiSecret: keys.apiSecret });
+            for (let attempt = 1; attempt <= KEYS_DELIVERY_ATTEMPTS && !delivered; attempt++) {
+                try {
+                    await deliverSecret(target.refs.livekitKeys, payload);
+                    delivered = true;
+                }
+                catch {
+                    // Retried; the error is dropped in case it echoes the key.
+                }
+            }
+            if (!delivered) {
+                throw new Error(`${label}: the LiveKit key pair could not be delivered after ${KEYS_DELIVERY_ATTEMPTS} attempts`);
+            }
+            keysJustSet = true;
+        }
+    }
+    const config = sfuConfig({ slot: input.slot, nodeIp: server.ip, keys });
+    deps.onSecret?.(config);
+    const envChanged = liveConfig !== config;
+    const pending = Boolean(scope.recordedIds()[OWN_SFU_DEPLOY_PENDING_SCOPE_KEY]) || changed || envChanged;
+    if (pending) {
+        scope.recordScopeId(OWN_SFU_DEPLOY_PENDING_SCOPE_KEY, '1');
+        await scope.persist();
+    }
+    if (envChanged) {
+        await coolify.bulkUpsertEnvs(appId, [{ key: CONFIG_ENV, value: config, literal: true }]);
+    }
+    if (keysJustSet) {
+        scope.recordScopeId(OWN_SFU_KEYS_SCOPE_KEY, appId);
+        scope.recordScopeId(OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY, '');
+        await scope.persist();
+    }
+    const running = (await coolify.getApplication(appId)).status?.startsWith('running') ?? false;
+    if (!existingApp || pending || !running) {
+        await waitForNewDeployment(coolify, appId, { kind: 'deployment-only' }, runtime, runtime.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))), label, 'the media server keeps its old version');
+    }
+    if (pending) {
+        scope.recordScopeId(OWN_SFU_DEPLOY_PENDING_SCOPE_KEY, '');
+        await scope.persist();
+    }
+    const tunnels = await network.tunnels();
+    const tunnel = (await tunnels.findTunnelByName(target.names.sfuTunnel)) ??
+        (await tunnels.createTunnel(target.names.sfuTunnel));
+    scope.recordScopeId(OWN_SFU_TUNNEL_SCOPE_KEY, tunnel.id);
+    await tunnels.putTunnelConfig(tunnel.id, {
+        ingress: [
+            {
+                hostname: input.hostname,
+                service: `http://${target.internal.sfu}:${LIVEKIT_SIGNALLING_PORT}`,
+            },
+            { service: 'http_status:404' },
+        ],
+    });
+    await ensureCloudflaredConnector({
+        coolify,
+        tunnels,
+        tunnelId: tunnel.id,
+        appName: target.names.sfuCloudflared,
+        projectUuid,
+        environment,
+        resolveServer: async () => server,
+        recordedConnectorAppId: scope.recordedIds()[OWN_SFU_CONNECTOR_APP_SCOPE_KEY] ?? null,
+        recordAppId: async (id) => {
+            scope.recordScopeId(OWN_SFU_CONNECTOR_APP_SCOPE_KEY, id);
+            await scope.persist();
+        },
+    });
+    const dns = await network.dns();
+    const dnsTarget = `${tunnel.id}.cfargotunnel.com`;
+    const [record] = await dns.findDnsRecord(input.apex, input.hostname, 'CNAME');
+    const cname = { type: 'CNAME', name: input.hostname, content: dnsTarget, proxied: true };
+    if (!record)
+        await dns.createDnsRecord(input.apex, cname);
+    else if (record.content !== dnsTarget)
+        await dns.updateDnsRecord(input.apex, record.id, cname);
+    await recordOwnDnsHostname(scope, input.hostname);
+    scope.recordScopeId(OWN_SFU_APPLIED_VERSION_SCOPE_KEY, input.version);
+    scope.recordScopeId(OWN_SFU_APPLIED_SLOT_SCOPE_KEY, String(input.slot));
+    scope.recordScopeId(OWN_SFU_APPLIED_HOSTNAME_SCOPE_KEY, input.hostname);
+    scope.recordScopeId(SFU_INTERNAL_URL_SCOPE_KEY, `http://${target.internal.sfu}:${LIVEKIT_SIGNALLING_PORT}`);
+    scope.recordScopeId(SFU_PUBLIC_URL_SCOPE_KEY, `https://${input.hostname}`);
+    return { resourceId: appId };
+}
+/**
+ * The addresses of the company's media server, from its recorded ids. Before
+ * the step is recorded the pair is empty, which `resolveCallsSfuUrls` refuses:
+ * an own org's calls service never falls back to the shared SFU's addresses.
+ */
+export function ownSfuUrls(ids) {
+    return {
+        privateUrl: ids[SFU_INTERNAL_URL_SCOPE_KEY] ?? '',
+        publicUrl: ids[SFU_PUBLIC_URL_SCOPE_KEY] ?? '',
+    };
+}

package/dist/plan/plan-apply.d.ts

@@ -10,6 +10,7 @@ import { type AgoraHostPort } from './agora.js';
 import { type UnconfirmedUpgrade } from './confirm-upgrade.js';
 import { type StepAction } from './diff.js';
 import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
+import { type LoginHostDiscoveryPort } from './login-host.js';
 import { type EdgePortName, type HeldKeyResolver } from './platform-org.js';
 import type { CallsSfuConnectionPort } from './platform-sfu.js';
 /** Who did it, for `@wtfalch/audit`'s "who, when, the plan, the result" (#9, #19). */
@@ -172,6 +173,38 @@ export interface StepExecutor {
      * an executor without it supplies none.
      */
     ownEdgePorts?(): Partial<Record<EdgePortName, boolean>>;
+    /**
+     * What the executor's own files dependencies supply (`ownServices.provision.files`):
+     * valid keys worker settings, and a bucket port. The planner blocks an own
+     * org's files host until both are true. Optional: an executor without it supplies neither.
+     */
+    ownFilesDeps?(): {
+        keys: boolean;
+        bucket: boolean;
+    };
+    /**
+     * Which ports an own org's files storage key step needs this executor has: the R2 key port, and
+     * `storeR2Credentials` on the org's files-organisation port. Optional: an executor without it
+     * leaves the step unplanned.
+     */
+    ownFilesR2Ports?(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<{
+        r2Keys: boolean;
+        storeR2Credentials: boolean;
+    }>;
+    /** Whether the executor can mint an own org's Lettermint key: a Lettermint port and a reader for the held ref. */
+    ownMailKeyMintable?(): boolean;
+    /**
+     * Whether the host's scoped ports for this own org include a files-organisation
+     * port. The planner plans no `files:organisation` step for an own org while
+     * this says false. Optional: an executor without it is taken to have the port.
+     */
+    ownFilesOrganisationPort?(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<boolean>;
+    /**
+     * Every secret this executor minted or read so far (peer password, bridge
+     * secret, invite code and link). The host's run adds them to its redactor
+     * after each step, so an error or progress line that quotes one is masked.
+     */
+    secretsHandled?(): readonly string[];
 }
 /**
  * #167: {@link StepExecutionContext}'s platform-scoped counterpart -- what
@@ -232,6 +265,8 @@ export interface PlatformStepExecutor {
         ai?: string;
         archon?: string;
         mail?: string;
+        /** See `PlanPlatformOptions.blocked.relay` (`platform-diff.ts`). */
+        relay?: string;
         /** #604: see `PlanPlatformOptions.blocked.accessProvider` (`platform-diff.ts`). */
         accessProvider?: string;
         /** #257: see `PlanPlatformOptions.blocked.backupExecutorMissing` (`platform-diff.ts`). */
@@ -376,6 +411,14 @@ export interface FoundryPlanApplyOptions {
      * before zitadel-login's binding can be written.
      */
     loginHostBindings?: boolean;
+    /**
+     * Reads `GET https://<login host>/.well-known/openid-configuration` for a
+     * company's login host (5 s limit). Optional, and without it every company's
+     * Agora keeps the platform issuer and the plan carries a blocked line for the
+     * switch. The host must route the company's login host to a login app that
+     * serves discovery (https://github.com/wtfalch/auth/pull/233).
+     */
+    loginHostDiscovery?: LoginHostDiscoveryPort;
     /**
      * True when the host's ZITADEL client has `updateOidcAppIdTokenUserinfoAssertion`
      * (`@wtfalch/providers` at the version that has it). Optional, and false
@@ -395,6 +438,12 @@ export interface FoundryPlanApplyOptions {
      * reported blocked instead of planned.
      */
     edgeWorkers?: boolean;
+    /**
+     * True when the host's executor was built with `ownerInviteMail`. Optional,
+     * and false without it: each owner's invite is then reported blocked
+     * instead of planned.
+     */
+    ownerInviteMail?: boolean;
     /**
      * #177: true when the host's executor was built with its own `filesOrganisation`
      * / `aiOrganisation` port. Without one, the org step needs the platform's
@@ -408,6 +457,32 @@ export interface FoundryPlanApplyOptions {
      * reported blocked instead of planned to fail.
      */
     edge?: boolean;
+    /**
+     * The executor was built with an `ownServices` port. Without it, an org
+     * that runs its own services (`services.own`) is reported blocked and none of
+     * its steps run.
+     */
+    ownServices?: boolean;
+    /**
+     * Says whether an own org's media server slot has its ports open on the
+     * Coolify server. Foundry opens none, so without this the plan keeps a
+     * fixed line naming them. A call that fails or takes over five seconds
+     * counts as not open.
+     */
+    sfuPortsOpen?: (range: {
+        udpStart: number;
+        udpEnd: number;
+        tcp: number;
+    }) => Promise<boolean>;
+    /**
+     * Narrows every org plan to the steps `step` accepts, and its blocked items
+     * to the keys `blocked` accepts, so a plan, its stale check and its apply
+     * all see the same slice. Absent: the whole plan.
+     */
+    onlySteps?: {
+        step(action: StepAction): boolean;
+        blocked(key: string): boolean;
+    };
     /** Overridable for tests; defaults to `() => new Date()`. */
     now?: () => Date;
     /** #441: how long a mutation lease lasts before another caller may take it over. Defaults to 30 minutes. */
@@ -466,12 +541,6 @@ export interface FoundryPlanApplyOptions {
         heldKeys?: HeldKeyResolver;
     };
 }
-/**
- * The #19 implementation of {@link PlanApply}: computes a plan against live
- * state, and refuses to apply one that has gone stale, one that touches a
- * destructive or migrating step without the org's name typed, or one the
- * actor is not authorized to run.
- */
 export declare class FoundryPlanApply implements PlanApply {
     private readonly store;
     private readonly readers;
@@ -483,12 +552,17 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly agora;
     private readonly jobsScheduler;
     private readonly loginHostBindings;
+    private readonly loginHostDiscovery;
     private readonly zitadelIdTokenUserinfo;
     private readonly broker;
     private readonly edgeWorkers;
+    private readonly ownerInviteMail;
     private readonly hostFiles;
     private readonly hostAi;
     private readonly hostEdge;
+    private readonly hostOwnServices;
+    private readonly sfuPortsOpen;
+    private readonly onlySteps;
     private readonly now;
     private readonly leaseTtlMs;
     private readonly appliedVersions;
@@ -630,6 +704,8 @@ export declare class FoundryPlanApply implements PlanApply {
     private refusePlatform;
     private refuseDestroy;
     private runSteps;
+    /** An own org with calls on: the host's answer about its slot's ports. A failure or a slow answer is "not open". */
+    private readSfuPortsOpen;
     private computeFreshPlan;
     /**
      * An entry may not take a name foundry owns (`locked-hostnames.ts`). The
@@ -646,12 +722,20 @@ export declare class FoundryPlanApply implements PlanApply {
      * org step that needs one is blocked.
      */
     private orgPlatformReadiness;
+    /** An own org's Lettermint key is held. A resolver that throws counts as not held. */
+    private ownMailKeyHeld;
+    /** Which of an own org's undelivered-secret refs hold a value now, so a rerun resumes instead of blocking. */
+    private ownResumableRefs;
+    /** The relay is declared and has recorded the routes it last applied: port 25 reaches the mail servers. */
+    private mailRelayApplied;
+    private sharedPlatformReadiness;
     /**
      * #177: `AgoraHostValues` from the applied platform, the same
      * `platformDeps` {@link orgPlatformReadiness} reads -- but only when the
      * host supplies no `agora` port of its own. An explicit `agora` (#164)
      * always wins, unchanged, so a host that already has its own values
-     * (perhaps not yet wired to this platform) keeps them.
+     * (perhaps not yet wired to this platform) keeps them. An org that owns its
+     * services never takes the host's values: they belong to the shared services.
      */
     private orgAgoraHost;
     /**
@@ -667,6 +751,16 @@ export declare class FoundryPlanApply implements PlanApply {
     /** #167: `FoundryPlanApplyOptions.platform`, or a plain `Error` naming what's missing. */
     private requirePlatformDeps;
     private computeFreshPlatformPlan;
+    /**
+     * What the shared mail relay needs from the orgs. A route exists for an org
+     * that owns its services, serves mail on its own domain and has recorded its
+     * mail server's SMTP address (`mail_smtp_internal`, written by the company
+     * mail step). Every other org with mail on its own domain, the platform
+     * apex and the shared no-domain apex are platform domains: the platform's Stalwart receives them. An org
+     * that owns its services but has no mail server yet appears in neither list,
+     * so the relay refuses its mail until the server exists.
+     */
+    private mailRelayInputs;
     private sfuBlockedReason;
     /**
      * {@link runSteps}, for the platform. The ids the steps return are recorded