@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/plan-apply.js

@@ -1,6 +1,9 @@
 import { createHash } from 'node:crypto';
-import { computePlanDetail, toPlan } from './diff.js';
-import { readLiveResources } from './live.js';
+import { NO_AGORA_HOST_VALUES, readAgoraHost, } from './agora.js';
+import { AI_KEY_UNDELIVERED_SCOPE_KEY, JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY, computePlanDetail, toPlan, } from './diff.js';
+import { readLivePlatformResources, readLiveResources, } from './live.js';
+import { planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
+import { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export class DeclaredOrgNotFoundError extends Error {
     constructor(orgId) {
         super(`no declared org ${orgId}`);
@@ -34,6 +37,31 @@ export class NotATestOrgError extends Error {
         this.name = 'NotATestOrgError';
     }
 }
+/** #167: {@link DeclaredOrgNotFoundError}, for the platform's own singleton record (#166). */
+export class DeclaredPlatformNotFoundError extends Error {
+    constructor() {
+        super('no declared platform (#166); declare one before planning or applying it');
+        this.name = 'DeclaredPlatformNotFoundError';
+    }
+}
+/** #167: {@link StalePlanError}, for `planPlatform`/`applyPlatform`. */
+export class PlatformStalePlanError extends Error {
+    constructor() {
+        super('the platform plan no longer matches live state; recompute planPlatform() and try again (#9, #10, #167)');
+        this.name = 'PlatformStalePlanError';
+    }
+}
+/**
+ * #167: {@link ConfirmationRequiredError}, for `applyPlatform` -- typed as
+ * the literal word `platform` rather than a declared name, since
+ * {@link DeclaredPlatform} has no `displayName` of its own to type (#166).
+ */
+export class PlatformConfirmationRequiredError extends Error {
+    constructor() {
+        super("the platform plan has a step that destroys or migrates data; type 'platform' exactly to apply it (#9, #167)");
+        this.name = 'PlatformConfirmationRequiredError';
+    }
+}
 /**
  * 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
@@ -48,7 +76,12 @@ export class FoundryPlanApply {
     audit;
     authz;
     actor;
+    agora;
+    jobsScheduler;
+    hostFiles;
+    hostAi;
     now;
+    platformDeps;
     constructor(options) {
         this.store = options.store;
         this.readers = options.readers;
@@ -57,7 +90,12 @@ export class FoundryPlanApply {
         this.audit = options.audit;
         this.authz = options.authz;
         this.actor = options.actor;
+        this.agora = options.agora;
+        this.jobsScheduler = options.jobsScheduler ?? false;
+        this.hostFiles = options.filesOrganisation ?? false;
+        this.hostAi = options.aiOrganisation ?? false;
         this.now = options.now ?? (() => new Date());
+        this.platformDeps = options.platform;
     }
     async plan(id) {
         const { plan } = await this.computeFreshPlan(id);
@@ -76,13 +114,62 @@ export class FoundryPlanApply {
             await this.refuse(plan, 'stale: live state has moved since this plan was computed');
             throw new StalePlanError(orgId);
         }
-        const needsConfirmation = plan.steps.some((step) => step.destroys || step.migrates);
-        if (needsConfirmation && confirmedOrgName.trim() !== org.displayName.trim()) {
+        if (planNeedsConfirmation(plan.steps) && confirmedOrgName.trim() !== org.displayName.trim()) {
             await this.refuse(plan, "destructive or migrating step without the org's name typed correctly");
             throw new ConfirmationRequiredError(orgId);
         }
         return this.runSteps(org, plan, detail);
     }
+    /**
+     * #167: {@link plan}, for the shared platform (#166) rather than an org --
+     * there is no id to pass, since `DeclaredPlatform` is one singleton record.
+     */
+    async planPlatform() {
+        const { plan } = await this.computeFreshPlatformPlan();
+        await this.audit.recordPlan({
+            actor: this.actor,
+            orgId: plan.orgId,
+            plan,
+            target: 'platform',
+            at: this.now(),
+        });
+        return plan;
+    }
+    /**
+     * #167: {@link apply}, for the platform. `plan.orgId` is the platform's own
+     * `ownerOrgId` (`toPlatformPlan`'s own doc comment), so the same
+     * `AuditLog`/`AuthzGate` seams `apply` uses need no platform-specific
+     * shape of their own. `confirmedName` must be the literal word `platform`
+     * rather than a declared name -- `DeclaredPlatform` has none.
+     */
+    async applyPlatform(plan, confirmedName) {
+        const { store, executor } = this.requirePlatformDeps();
+        const declared = await store.get();
+        if (!declared)
+            throw new DeclaredPlatformNotFoundError();
+        // A plan for any other org id is forged or misrouted; refuse it before
+        // the authz gate is asked about an org this platform does not belong to.
+        if (plan.orgId !== declared.ownerOrgId) {
+            await this.refusePlatform(plan, declared.ownerOrgId, 'plan is not the platform’s own');
+            throw new PlatformStalePlanError();
+        }
+        // A gate that cannot answer for the platform refuses it (secure default).
+        const authorized = (await this.authz.canApplyPlatform?.(this.actor)) === true;
+        if (!authorized) {
+            await this.refusePlatform(plan, declared.ownerOrgId, 'not authorized');
+            throw new NotAuthorizedError(this.actor, plan.orgId);
+        }
+        const { platform, plan: freshPlan, detail } = await this.computeFreshPlatformPlan();
+        if (!plansMatch(plan, freshPlan)) {
+            await this.refusePlatform(plan, platform.ownerOrgId, 'stale: live state has moved since this plan was computed');
+            throw new PlatformStalePlanError();
+        }
+        if (planNeedsConfirmation(plan.steps) && confirmedName.trim() !== 'platform') {
+            await this.refusePlatform(plan, platform.ownerOrgId, "destructive or migrating step without 'platform' typed correctly");
+            throw new PlatformConfirmationRequiredError();
+        }
+        return this.runPlatformSteps(platform, plan, detail, executor);
+    }
     /**
      * Deletes every resource foundry recorded for `id`, in reverse creation
      * order, then the declared org and its applied state themselves (goal
@@ -158,6 +245,17 @@ export class FoundryPlanApply {
             at: this.now(),
         });
     }
+    async refusePlatform(plan, ownerOrgId, reason) {
+        await this.audit.recordApply({
+            actor: this.actor,
+            orgId: ownerOrgId,
+            plan,
+            outcome: 'refused',
+            reason,
+            target: 'platform',
+            at: this.now(),
+        });
+    }
     async refuseDestroy(orgId, reason) {
         await this.audit.recordDestroy({
             actor: this.actor,
@@ -180,6 +278,15 @@ export class FoundryPlanApply {
             recordScopeId: (key, id) => {
                 serviceIds[key] = id;
             },
+            persistScopeIds: async () => {
+                await this.store.putAppliedState({
+                    orgId,
+                    serviceIds: { ...serviceIds },
+                    checkpoints: [...checkpoints],
+                    failedFields: previous?.failedFields ?? [],
+                    lastApplied: previous?.lastApplied ?? null,
+                });
+            },
         };
         try {
             for (const planned of detail.plannedSteps) {
@@ -204,7 +311,7 @@ export class FoundryPlanApply {
                 orgId,
                 serviceIds,
                 checkpoints,
-                failedFields: failedFields(org, detail, checkpoints.length),
+                failedFields: failedFields(org, detail, checkpoints.length, serviceIds),
                 lastApplied: previous?.lastApplied ?? null,
             });
             await this.audit.recordApply({
@@ -221,7 +328,7 @@ export class FoundryPlanApply {
             orgId,
             serviceIds,
             checkpoints,
-            failedFields: failedFields(org, detail, detail.plannedSteps.length),
+            failedFields: failedFields(org, detail, detail.plannedSteps.length, serviceIds),
             lastApplied: { at: this.now().toISOString(), declaredOrgVersion: hashOrg(org) },
         };
         await this.store.putAppliedState(applied);
@@ -238,13 +345,164 @@ export class FoundryPlanApply {
         const org = await this.store.get(id);
         if (!org)
             throw new DeclaredOrgNotFoundError(id);
-        const [live, applied] = await Promise.all([
+        const [live, applied, platformReadiness, agoraHost] = await Promise.all([
             readLiveResources(id, this.readers),
             this.store.getAppliedState(id),
+            this.orgPlatformReadiness(),
+            this.orgAgoraHost(id),
         ]);
-        const detail = computePlanDetail(org, live, applied?.serviceIds ?? {});
+        const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness);
         return { org, plan: toPlan(detail), detail };
     }
+    /**
+     * #177: an org's plan reads the shared platform's own addresses and
+     * readiness through the very `platform` deps `planPlatform`/`applyPlatform`
+     * already use. With no platform wired or declared, {@link
+     * DEFAULT_ORG_PLATFORM_READINESS} reports every service not ready, so every
+     * org step that needs one is blocked.
+     */
+    async orgPlatformReadiness() {
+        if (!this.platformDeps)
+            return DEFAULT_ORG_PLATFORM_READINESS;
+        const platform = await this.platformDeps.store.get();
+        if (!platform)
+            return DEFAULT_ORG_PLATFORM_READINESS;
+        const recorded = await this.platformDeps.store.getServiceIds();
+        const heldKeys = this.platformDeps.heldKeys;
+        // A service the host supplies its own port for needs no platform key.
+        const refs = new Set(heldKeys ? await heldPlatformKeyRefs(heldKeys) : []);
+        if (this.hostFiles)
+            refs.add(ORG_PLATFORM_KEY_REFS.files);
+        if (this.hostAi)
+            refs.add(ORG_PLATFORM_KEY_REFS.ai);
+        if (this.jobsScheduler)
+            refs.add(ORG_PLATFORM_KEY_REFS.jobs);
+        return orgPlatformReadinessFrom(platform, recorded, refs, !heldKeys);
+    }
+    /**
+     * #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.
+     */
+    async orgAgoraHost(id) {
+        if (this.agora)
+            return readAgoraHost(this.agora, id);
+        if (!this.platformDeps)
+            return NO_AGORA_HOST_VALUES;
+        const platform = await this.platformDeps.store.get();
+        if (!platform)
+            return NO_AGORA_HOST_VALUES;
+        const recorded = await this.platformDeps.store.getServiceIds();
+        return agoraHostValuesFromPlatform(platform, recorded);
+    }
+    /** #167: `FoundryPlanApplyOptions.platform`, or a plain `Error` naming what's missing. */
+    requirePlatformDeps() {
+        if (!this.platformDeps) {
+            throw new Error('FoundryPlanApply: planPlatform/applyPlatform need `platform` in FoundryPlanApplyOptions (#167)');
+        }
+        return this.platformDeps;
+    }
+    async computeFreshPlatformPlan() {
+        const { store, readers, executor } = this.requirePlatformDeps();
+        const platform = await store.get();
+        if (!platform)
+            throw new DeclaredPlatformNotFoundError();
+        const [live, serviceIds] = await Promise.all([
+            readLivePlatformResources(readers),
+            store.getServiceIds(),
+        ]);
+        const sfuBlocked = await this.sfuBlockedReason(platform);
+        const detail = computePlatformPlanDetail(platform, live, {
+            jobsObservable: readers.coolify !== undefined,
+            sfuBlocked,
+            recordedIds: serviceIds,
+            blocked: (await executor.blockedSteps?.(platform, serviceIds)) ?? {},
+            drifted: (await executor.driftedSteps?.(platform, serviceIds)) ?? {},
+        });
+        return { platform, plan: toPlatformPlan(detail, platform.ownerOrgId), detail };
+    }
+    async sfuBlockedReason(platform) {
+        if (!platform.sfu.enabled)
+            return null;
+        const port = this.requirePlatformDeps().sfuConnection;
+        if (!port) {
+            return 'the platform SFU is blocked, not planned: the host supplies no SFU connection port (#170)';
+        }
+        let held = null;
+        try {
+            held = await port.resolveConnection();
+        }
+        catch {
+            held = null;
+        }
+        if (!held) {
+            return 'the platform SFU is blocked, not planned: no SSH key and host key fingerprint are held for the SFU VM yet (#170 "Human steps")';
+        }
+        return null;
+    }
+    /**
+     * {@link runSteps}, for the platform. The ids the steps return are recorded
+     * in `PlatformStore`'s applied state (`system:kind:key`, like an org's
+     * `serviceIds`), so a later plan finds a resource by its recorded id even
+     * when a provider's list has not caught up with a create.
+     */
+    async runPlatformSteps(platform, plan, detail, executor) {
+        const { store } = this.requirePlatformDeps();
+        const serviceIds = { ...(await store.getServiceIds()) };
+        const context = {
+            platform,
+            recordedIds: () => ({ ...serviceIds }),
+            recordScopeId: (key, id) => {
+                serviceIds[key] = id;
+            },
+            persist: () => store.putServiceIds(serviceIds),
+        };
+        try {
+            for (const planned of detail.plannedSteps) {
+                const result = await executor.execute(planned.action, context);
+                if (result?.resourceId) {
+                    const { system, kind, key } = planned.action;
+                    serviceIds[`${system}:${kind}:${key}`] = result.resourceId;
+                }
+            }
+        }
+        catch (e) {
+            // Whatever completed stays recorded, as an org's apply does.
+            await store.putServiceIds(serviceIds);
+            await this.audit.recordApply({
+                actor: this.actor,
+                orgId: platform.ownerOrgId,
+                plan,
+                outcome: 'failed',
+                reason: e instanceof Error ? e.message : String(e),
+                target: 'platform',
+                at: this.now(),
+            });
+            throw e;
+        }
+        await store.putServiceIds(serviceIds);
+        await this.audit.recordApply({
+            actor: this.actor,
+            orgId: platform.ownerOrgId,
+            plan,
+            outcome: 'applied',
+            target: 'platform',
+            at: this.now(),
+        });
+        return { serviceIds };
+    }
+}
+/**
+ * #9 (resolved): whether any step in a plan needs its name typed before
+ * `apply` runs it. Shared by `apply` (the org's `displayName`) and
+ * `applyPlatform` (the literal word `platform`, #167) so the platform gets
+ * the identical gate an org already has, proven end-to-end above, rather
+ * than a second copy that could drift from it.
+ */
+export function planNeedsConfirmation(steps) {
+    return steps.some((step) => step.destroys || step.migrates);
 }
 /** `AppliedState.serviceIds`' two flat ZITADEL scope keys (`executor.ts`'s `ensureZitadelProject`/`zitadelIssuer`) -- no `:`, unlike a resource key. */
 const ZITADEL_PROJECT_SCOPE_KEY = 'zitadel_project';
@@ -337,6 +595,7 @@ const STEP_FIELDS = {
     'coolify:calls-service': 'calls.enabled',
     'files:storage': 'storage',
     'ai:budget': 'ai',
+    'ai:key': 'ai',
     'cms:site': 'site',
     'coolify:app': 'hosting.enabled',
     'coolify:database': 'hosting.database',
@@ -369,8 +628,18 @@ function stepField(action) {
  * - on a failed apply, the field of every planned step from the one that
  *   threw onwards (`completed` is how many steps finished).
  */
-function failedFields(org, detail, completed) {
+function failedFields(org, detail, completed, serviceIds) {
     const failed = new Set();
+    // `planAiKey` plans no step for a key minted but never delivered, so no
+    // step is left to fail. Without this, the next apply would record the org
+    // as converged with no working key.
+    if (serviceIds[AI_KEY_UNDELIVERED_SCOPE_KEY] && !serviceIds[`ai:key:${org.id}`])
+        failed.add('ai');
+    // The same for a jobs registration whose credentials never reached the host.
+    if (serviceIds[JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY] &&
+        !serviceIds[`jobs:registration:${org.id}`]) {
+        failed.add('jobs.registration');
+    }
     if (org.sso.enabled)
         failed.add('sso.enabled');
     if (org.guests.enabled)