@wtfalch/foundry 0.42.1 → 0.43.0

package/dist/bootstrap/versions.d.ts

@@ -18,6 +18,8 @@ export interface PinnedVersions {
     busybox: string;
     /** The sign-in database's image (#746). Its major version is the data directory's format: a bump past 16 needs a dump and restore, not an image change. */
     postgres: string;
+    /** The load balancer of a blue/green app (`plan/blue-green.ts`): Traefik with a file provider. */
+    traefik: string;
 }
 export declare function loadVersions(): PinnedVersions;
 export declare const VERSIONS: PinnedVersions;

package/dist/index.d.ts

@@ -16,8 +16,12 @@ export { StaleLeaseError } from './store.js';
 export type { PlanApply, DestroyProgress } from './apply.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
+export type { Color, ReleaseAction, ReleaseSignal, ReleaseState, WindowState, } from './release/types.js';
+export type { ReleaseStore } from './release/state.js';
+export { readReleaseState, requestReleaseAction } from './release/state.js';
+export { createPostgresReleaseStore } from './store/postgres.js';
 export type { FoundryStoreDb } from './store/postgres.js';
-export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type AppliedVersionRow, type NewAppliedVersionRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
+export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryReleaseRequests, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type AppliedVersionRow, type NewAppliedVersionRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, StepSystem, PlanDetail, OrgPostgresPlan, PlatformPlanDetail, MailRoute, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, FoundryApplyOptions, UnconfirmedUpgrade, } from './plan/index.js';
 export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';

package/dist/index.js

@@ -10,7 +10,9 @@ export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export { StaleLeaseError } from './store.js';
 export { createPostgresAppliedVersionsStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
-export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
+export { readReleaseState, requestReleaseAction } from './release/state.js';
+export { createPostgresReleaseStore } from './store/postgres.js';
+export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryReleaseRequests, foundryRequestedChanges, } from './store/schema.js';
 export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';

package/dist/migrations/0055_release_requests.sql

@@ -0,0 +1,20 @@
+-- @wtfalch/foundry: an operator's release action (promote, roll back, clear a
+-- held digest, decide at the cap) waiting for the release runner. The runner
+-- marks a row consumed in one statement, so each request is applied once.
+-- Additive: a new table, no existing row touched. Copies 0036_applied_versions
+-- (an appended table with no foreign key, because `org_id` may be `platform`).
+-- Mirrors src/store/schema.ts's `foundryReleaseRequests`.
+
+create table if not exists foundry_release_requests (
+  id          bigserial primary key,
+  org_id      text not null,
+  entry_key   text not null,
+  action      jsonb not null,
+  actor       text not null,
+  created_at  timestamptz not null default now(),
+  consumed_at timestamptz
+);
+
+create index if not exists foundry_release_requests_open_idx
+  on foundry_release_requests (org_id, entry_key, id)
+  where consumed_at is null;

package/dist/migrations/0056_platform_archon_blue_green.sql

@@ -0,0 +1,7 @@
+-- @wtfalch/foundry: `archon_blue_green` is `platform.archon.blueGreen` as JSON ({ steps?, stepHoldMinutes? });
+-- null (the default) keeps platform-archon on one app. Copies 0052_platform_mail_relay.sql: one
+-- nullable column added with `if not exists`, so it is safe to run at container start on live rows.
+-- Mirrors src/store/schema.ts's `foundryDeclaredPlatform` table addition.
+
+alter table foundry_declared_platform
+  add column if not exists archon_blue_green jsonb;

package/dist/org.d.ts

@@ -355,6 +355,17 @@ export interface HostingEntry {
      * is the org's own domain.
      */
     worker?: WorkerConfig;
+    /**
+     * Blue/green releases (docs/adr/0001-blue-green-releases.md). Presence turns it on: foundry runs the app as a
+     * blue and a green copy behind a load balancer on every server it manages, and the tunnel routes to the balancer.
+     */
+    blueGreen?: BlueGreenConfig;
+}
+/** The traffic steps (percent to the new color) and the hold at each step. Both default in `plan/blue-green.ts`. */
+export interface BlueGreenConfig {
+    /** Ascending, each 1..100, ending at 100. */
+    steps?: number[];
+    stepHoldMinutes?: number;
 }
 /** One named volume on a hosting entry's app. */
 export interface EntryVolume {
@@ -552,6 +563,8 @@ export declare function validateHosting(hosting: HostingConfig, names?: {
     domain: string | null;
     locked: ReadonlySet<string>;
 }): string | null;
+/** `blueGreen`: steps ascending, each a whole number 1..100, the last 100; a hold of 1..1440 minutes. */
+export declare function validateBlueGreen(value: unknown, at: string): string | null;
 export declare function validateDomain(domain: string): string | null;
 /**
  * A broker entry name foundry writes itself: Archon's, and any company's Boule.

package/dist/org.js

@@ -351,6 +351,8 @@ const VOLUME_MOUNT_PATH_MAX = 255;
 const REPO = /^wtfalch\/[A-Za-z0-9._-]+$/;
 // The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
 const FOUNDRY_ENV_NAME = /^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
+// Set only on the colors of a blueGreen entry; any other entry may declare them.
+const BLUE_GREEN_ENV_NAME = /^REPORTING_(COLOR|RELEASE|HEALTH_TOKEN)$/;
 const SECRET_ENV_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
 const HELD_SECRETS = "declare it as { from: 'heldSecret' }, not a plain value";
 /** The rules for one {@link HostingEntry}; `null` when it is valid. */
@@ -392,11 +394,19 @@ function validateHostingEntry(entry, enabled) {
     const invalidVolumes = validateEntryVolumes(entry, at);
     if (invalidVolumes)
         return invalidVolumes;
+    const invalidBlueGreen = validateBlueGreen(entry.blueGreen, at);
+    if (invalidBlueGreen)
+        return invalidBlueGreen;
+    if (entry.blueGreen !== undefined &&
+        entry.key !== APP_ENTRY_KEY &&
+        !entry.hostnames.some((name) => name !== '*')) {
+        return `${at} blueGreen needs a public hostname: the release check reaches each color through it`;
+    }
     for (const [name, value] of Object.entries(entry.env)) {
         if (!name) {
             return `${at} env needs a non-empty env var name`;
         }
-        if (FOUNDRY_ENV_NAME.test(name)) {
+        if (FOUNDRY_ENV_NAME.test(name) || (entry.blueGreen && BLUE_GREEN_ENV_NAME.test(name))) {
             return `${at} env '${name}' is set by foundry and cannot be declared`;
         }
         if (typeof value !== 'string') {
@@ -424,6 +434,33 @@ function validateHostingEntry(entry, enabled) {
     }
     return null;
 }
+/** `blueGreen`: steps ascending, each a whole number 1..100, the last 100; a hold of 1..1440 minutes. */
+export function validateBlueGreen(value, at) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return `${at} blueGreen must be an object`;
+    }
+    const { steps, stepHoldMinutes } = value;
+    if (steps !== undefined) {
+        if (!Array.isArray(steps) || steps.length === 0 || steps.length > 20) {
+            return `${at} blueGreen steps must be a list of 1 to 20 percentages`;
+        }
+        if (!steps.every((n) => Number.isInteger(n) && n >= 1 && n <= 100)) {
+            return `${at} blueGreen steps must be whole numbers from 1 to 100`;
+        }
+        if (!steps.every((n, i) => i === 0 || n > steps[i - 1])) {
+            return `${at} blueGreen steps must be ascending`;
+        }
+        if (steps[steps.length - 1] !== 100)
+            return `${at} blueGreen steps must end at 100`;
+    }
+    if (stepHoldMinutes !== undefined &&
+        !(Number.isInteger(stepHoldMinutes) && stepHoldMinutes >= 1 && stepHoldMinutes <= 1440)) {
+        return `${at} blueGreen stepHoldMinutes must be a whole number from 1 to 1440`;
+    }
+    return null;
+}
 /** `volumes`: a bounded list of named volumes at distinct absolute paths, none on the log volume's path or name,
  * on `/app` or under a system path. */
 function validateEntryVolumes(entry, at) {

package/dist/plan/archon-blue-green.d.ts

@@ -0,0 +1,54 @@
+import { type BlueGreenApplyDeps } from './blue-green-apply.js';
+import { type BlueGreenSubject } from './blue-green.js';
+import type { DeployHealthRuntime } from './deploy-health.js';
+import type { PlatformTunnelPort } from './platform-providers.js';
+export interface ArchonBlueGreenRun {
+    subject: BlueGreenSubject;
+    /** The owner company's id: the health token's held ref is `sharedSecretRef(ownerOrgId, ...)` like an entry's. */
+    ownerOrgId: string;
+    desired: {
+        primary: string;
+    };
+    recorded(): Readonly<Record<string, string>>;
+    record(key: string, value: string): void;
+    persist(): Promise<void>;
+    coolify: BlueGreenApplyDeps['coolify'] & {
+        listServers(): Promise<Array<{
+            uuid: string;
+            is_usable: boolean;
+            is_reachable: boolean;
+        }>>;
+        findOrCreateEnvironment(projectUuid: string, name: string): Promise<{
+            environment: {
+                id: number;
+                name: string;
+                uuid: string;
+            };
+        }>;
+    };
+    heldKeys: {
+        resolve(ref: string): Promise<string | null>;
+        put(ref: string, value: string): Promise<void>;
+    };
+    /** Registers a value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+    /** Archon's Coolify project, its blue app and its tunnel, all recorded by the archon step. */
+    projectUuid: string;
+    blueAppId: string;
+    tunnelId: string;
+    hostname: string;
+    tunnels: Pick<PlatformTunnelPort, 'putTunnelConfig'>;
+    runtime: DeployHealthRuntime;
+    sleep: (ms: number) => Promise<void>;
+    logDir: string;
+    isRunning: (status: string | undefined) => boolean;
+}
+/**
+ * platform-archon on the blue/green path (`platform.archon.blueGreen`): the archon app keeps its name and is
+ * blue; green, the balancer and stage are new apps beside it on the primary server. The tunnel moves to the
+ * balancer last, only after every part of the structure is applied and running, so a first apply never has the
+ * tunnel point at a balancer that does not answer. A failure halfway leaves the apps already made, recorded by
+ * id; the structure is recorded as applied only after its last part, so the next apply repeats from there and
+ * the tunnel stays on the app until then.
+ */
+export declare function applyArchonBlueGreen(run: ArchonBlueGreenRun): Promise<void>;

package/dist/plan/archon-blue-green.js

@@ -0,0 +1,72 @@
+import { randomBytes } from 'node:crypto';
+import { sharedSecretRef } from '../org.js';
+import { applyBlueGreenServer } from './blue-green-apply.js';
+import { ARCHON_BG_ORIGIN_SCOPE_KEY, DEFAULT_WEIGHTS, PRIMARY_SERVER_SCOPE_KEY, bgKey, healthTokenName, lbOrigin, splitServers, } from './blue-green.js';
+/**
+ * platform-archon on the blue/green path (`platform.archon.blueGreen`): the archon app keeps its name and is
+ * blue; green, the balancer and stage are new apps beside it on the primary server. The tunnel moves to the
+ * balancer last, only after every part of the structure is applied and running, so a first apply never has the
+ * tunnel point at a balancer that does not answer. A failure halfway leaves the apps already made, recorded by
+ * id; the structure is recorded as applied only after its last part, so the next apply repeats from there and
+ * the tunnel stays on the app until then.
+ */
+export async function applyArchonBlueGreen(run) {
+    const { subject } = run;
+    const id = subject.id;
+    const label = `coolify:archon-bluegreen:${id}`;
+    const { up } = splitServers((await run.coolify.listServers()).map((s) => ({
+        uuid: s.uuid,
+        usable: s.is_usable,
+        reachable: s.is_reachable,
+    })));
+    const primary = run.recorded()[PRIMARY_SERVER_SCOPE_KEY] ?? up[0];
+    if (!primary || !up.includes(primary) || primary !== run.desired.primary) {
+        throw new Error(`${label}: the plan's primary server is not the usable recorded one`);
+    }
+    if (!run.recorded()[PRIMARY_SERVER_SCOPE_KEY]) {
+        run.record(PRIMARY_SERVER_SCOPE_KEY, primary);
+        await run.persist();
+    }
+    if (!run.recorded()[bgKey.weights(id)]) {
+        run.record(bgKey.weights(id), DEFAULT_WEIGHTS);
+        await run.persist();
+    }
+    const { environment } = await run.coolify.findOrCreateEnvironment(run.projectUuid, 'production');
+    const ref = sharedSecretRef(run.ownerOrgId, healthTokenName(id));
+    const deps = {
+        coolify: run.coolify,
+        recorded: run.recorded,
+        record: run.record,
+        persist: run.persist,
+        projectUuid: run.projectUuid,
+        environment,
+        healthToken: async () => {
+            const held = await run.heldKeys.resolve(ref);
+            if (held) {
+                run.secret(held);
+                return held;
+            }
+            const minted = randomBytes(32).toString('base64url');
+            run.secret(minted);
+            await run.heldKeys.put(ref, minted);
+            return minted;
+        },
+        secret: run.secret,
+        runtime: run.runtime,
+        sleep: run.sleep,
+        label,
+        primaryBlueAppId: run.blueAppId,
+        logDir: run.logDir,
+        isRunning: run.isRunning,
+    };
+    await applyBlueGreenServer(deps, subject, { uuid: primary, primaryUuid: primary });
+    // The structure is applied and every part ran: now, and only now, the tunnel moves.
+    const origin = lbOrigin(subject);
+    if (run.recorded()[ARCHON_BG_ORIGIN_SCOPE_KEY] !== origin) {
+        await run.tunnels.putTunnelConfig(run.tunnelId, {
+            ingress: [{ hostname: run.hostname, service: origin }, { service: 'http_status:404' }],
+        });
+        run.record(ARCHON_BG_ORIGIN_SCOPE_KEY, origin);
+        await run.persist();
+    }
+}

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

@@ -0,0 +1,82 @@
+import { type BlueGreenSubject } from './blue-green.js';
+import { ensureConnectorsOnServers } from './cloudflared-connector.js';
+import { type DeployHealthRuntime } from './deploy-health.js';
+import type { TunnelPort } from './edge-tunnels.js';
+import type { CoolifyPort } from './executor.js';
+/** The Coolify calls this module makes. */
+type Coolify = Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'deployAndWait' | 'listStorages' | 'createPersistentStorage' | 'createFileStorage' | 'updateFileStorage' | 'requireGithubApp' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw'> & {
+    listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
+};
+export interface BlueGreenApplyDeps {
+    coolify: Coolify;
+    /** The ids recorded so far, and how to record one. */
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    projectUuid: string;
+    environment: {
+        id: number;
+        name: string;
+        uuid: string;
+    };
+    /** The entry's one health token: held once, handed to the env writes below and nowhere else. */
+    healthToken: () => Promise<string>;
+    /** Registers a value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+    runtime: DeployHealthRuntime;
+    sleep: (ms: number) => Promise<void>;
+    /** The step's name, for errors. */
+    label: string;
+    /** The app id of the blue copy `coolify:app` made on the primary. */
+    primaryBlueAppId: string;
+    logDir: string;
+    isRunning: (status: string | undefined) => boolean;
+}
+/** What writing a balancer's config needs; {@link BlueGreenApplyDeps} and the release runner both have it. */
+export interface LbConfigDeps {
+    coolify: Pick<Coolify, 'listStorages' | 'createFileStorage' | 'updateFileStorage'>;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    label: string;
+}
+/** Replaces the host in a connection URL; `null` when it is not one. Never throws a value. */
+export declare function withDatabaseHost(url: string, host: string): string | null;
+/** `postgres://user:password@host/db` for a stage runtime role: the password is minted by the caller. */
+export declare function runtimeDatabaseUrl(ownerUrl: string, role: string, password: string): string | null;
+/**
+ * Applies one server's blue/green structure for `subject`: green (and blue, off the primary) beside the
+ * primary's blue, the balancer with the recorded weights, and on the primary the stage app. Every color
+ * gets the primary blue's env (the database host rewritten off the primary) and its three reporting
+ * values. A failure halfway leaves the apps already made, recorded by id; the next run finds them and
+ * does the rest. Nothing is recorded as applied until every part is done.
+ */
+export declare function applyBlueGreenServer(deps: BlueGreenApplyDeps, subject: BlueGreenSubject, server: {
+    uuid: string;
+    primaryUuid: string;
+}): Promise<void>;
+/** Writes the balancer's config with the recorded weights and records them for this server. */
+export declare function applyBlueGreenWeights(deps: LbConfigDeps, subject: BlueGreenSubject, server: {
+    uuid: string;
+    primaryUuid: string;
+}): Promise<void>;
+/** A connector for the org's tunnel on each given server; the primary's is the existing one. */
+export declare function applyBlueGreenConnectors(input: {
+    coolify: Parameters<typeof ensureConnectorsOnServers>[0]['coolify'];
+    tunnels: Pick<TunnelPort, 'getTunnelToken'>;
+    tunnelId: string;
+    baseAppName: string;
+    baseScopeKey: string;
+    primaryUuid: string;
+    serverUuids: readonly string[];
+    projectUuid: string;
+    environment: {
+        id: number;
+        name: string;
+        uuid: string;
+    };
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+}): Promise<void>;
+export {};