@wtfalch/foundry 0.42.1 → 0.43.0

package/dist/plan/release-host.d.ts

@@ -0,0 +1,59 @@
+import { type ReleaseDeps } from '../release/run.js';
+import type { ReleaseStore } from '../release/state.js';
+import { type BlueGreenSubject } from './blue-green.js';
+import { type DeployHealthRuntime } from './deploy-health.js';
+import type { CoolifyPort } from './executor.js';
+/** The recorded ids a release run reads and writes: an org's apply context, or the platform's. */
+export interface ReleaseContext {
+    recordedIds(): Readonly<Record<string, string>>;
+    recordScopeId(key: string, id: string): void;
+    forgetId(key: string): void;
+    persist(): Promise<void>;
+}
+/** What a run needs besides the runner's own deps: stage, and the balancers' weights on every server. */
+export interface ReleaseHost {
+    deps: ReleaseDeps;
+    /** Records stage's newest finished build as `bg.<id>.stage`. A failed read changes nothing. */
+    refreshStage(): Promise<void>;
+    /** Writes the recorded weights to the balancer on every server that has one. */
+    writeWeights(): Promise<void>;
+}
+export interface ReleaseHostInput {
+    subject: BlueGreenSubject;
+    context: ReleaseContext;
+    coolify: Pick<CoolifyPort, 'getApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'deployAndWait' | 'raw' | 'listStorages' | 'createFileStorage' | 'updateFileStorage'> & {
+        listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
+    };
+    /** Reads the entry's health token (`sharedSecretRef(org.id, healthTokenName(id))`). Never mints. */
+    healthToken: () => Promise<string | null>;
+    /** Registers a value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+    primaryUuid: string;
+    /** The Coolify app of the blue copy on the primary (the entry's `coolify:app`, or the running archon app). */
+    primaryBlueAppId: string;
+    runtime: DeployHealthRuntime;
+    fetch?: typeof fetch;
+    /** Extends the mutation lease; called before each outside call that can take long. */
+    renew: () => Promise<void>;
+    label: string;
+}
+export declare function createReleaseHost(input: ReleaseHostInput): ReleaseHost;
+/**
+ * One release run for one subject, writing into `context` (the live recorded ids of the run that holds
+ * the mutation lease, so no stale copy is ever written back). Seeds `live` and the weights on the first run
+ * after the structure is applied. The weights the runner decided reach every server's balancer before this
+ * returns; a balancer that fails leaves `bg.<id>.lb.<server>` behind the weights, and the next run
+ * (like the next apply, through its `bluegreen-lb` step) writes it again.
+ */
+export declare function runSubjectRelease(input: {
+    store: Pick<ReleaseStore, 'openRequests' | 'consumeRequests'>;
+    scopeOwnerId: string;
+    subject: BlueGreenSubject;
+    host: ReleaseHost;
+    context: ReleaseContext;
+    now: Date;
+    primaryUuid: string;
+}): Promise<{
+    blocked: string[];
+    refused: string[];
+}>;

package/dist/plan/release-host.js

@@ -0,0 +1,239 @@
+import { checkColorAddress, readReleaseHealth } from '../release/health.js';
+import { runRelease } from '../release/run.js';
+import { applyBlueGreenWeights } from './blue-green-apply.js';
+import { DEFAULT_WEIGHTS, LB_COLOR_HEADER, LB_PIN_HEADER, bgKey, formatWeights, parseWeights, reportingEnv, } from './blue-green.js';
+import { waitForNewDeployment } from './deploy-health.js';
+import { isNotFoundError } from './executor.js';
+const COMMIT = /^[0-9a-f]{40}$/;
+/** Coolify reports a restarting container as `restarting:...`; a crash loop is that. */
+function statusOf(status) {
+    if (status?.startsWith('running'))
+        return 'running';
+    if (status?.startsWith('restarting'))
+        return 'crash_loop';
+    return 'other';
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export function createReleaseHost(input) {
+    const { subject, context, coolify } = input;
+    const id = subject.id;
+    const recorded = () => context.recordedIds();
+    /** Every Coolify app of `color`, one per server that has the structure applied. */
+    const colorApps = (color) => {
+        const ids = recorded();
+        const apps = [];
+        if (color === 'blue')
+            apps.push(input.primaryBlueAppId);
+        const prefix = `bg.${id}.app.`;
+        for (const key of Object.keys(ids).sort()) {
+            if (!key.startsWith(prefix) || !key.endsWith(`.${color}`))
+                continue;
+            const value = ids[key];
+            if (value)
+                apps.push(value);
+        }
+        return apps;
+    };
+    const primaryColorApp = (color) => color === 'blue' ? input.primaryBlueAppId : recorded()[bgKey.app(id, input.primaryUuid, color)];
+    /**
+     * Where the runner reaches a color: the entry's first public hostname, pinned to the color by the balancer's
+     * header router. The balancer routes the pinned request to that color whatever its weight.
+     */
+    const addressOf = (color) => {
+        const hostname = subject.hostnames.find((name) => !name.startsWith('*'));
+        if (!hostname)
+            throw new Error(`${input.label}: the app has no public hostname to check through`);
+        const pinKey = recorded()[bgKey.pinKey(id)];
+        if (!pinKey)
+            throw new Error(`${input.label}: the balancer's pin key is not recorded`);
+        return {
+            address: `https://${hostname}`,
+            headers: { [LB_COLOR_HEADER]: color, [LB_PIN_HEADER]: pinKey },
+        };
+    };
+    /** The color a health read goes to: the one being released, else the live one. */
+    const healthColor = () => {
+        try {
+            const window = JSON.parse(recorded()[bgKey.window(id)] ?? '{}');
+            if (window.release?.to === 'blue' || window.release?.to === 'green')
+                return window.release.to;
+        }
+        catch {
+            // A damaged window reads as no release; the runner rewrites it.
+        }
+        return recorded()[bgKey.live(id)] === 'green' ? 'green' : 'blue';
+    };
+    const deployTo = async (color, digest) => {
+        if (!COMMIT.test(digest))
+            throw new Error(`${input.label}: the release is not a built commit`);
+        const token = await input.healthToken();
+        if (!token)
+            throw new Error(`${input.label}: the health token is not held`);
+        input.secret(token);
+        const apps = colorApps(color);
+        if (apps.length === 0)
+            throw new Error(`${input.label}: ${color} has no app recorded`);
+        for (const appId of apps) {
+            await input.renew();
+            await coolify.updateApplication(appId, { git_commit_sha: digest });
+            try {
+                await coolify.bulkUpsertEnvs(appId, reportingEnv({ color, release: digest, healthToken: token }).map((e) => ({
+                    ...e,
+                    literal: true,
+                })));
+            }
+            catch {
+                // A Coolify error can echo the request body, which holds the token.
+                throw new Error(`${input.label}: writing env to app ${appId} failed`);
+            }
+            await waitForNewDeployment(coolify, appId, { kind: 'deployment-only' }, input.runtime, input.runtime.sleep ?? defaultSleep, `${input.label} ${color}`, `${color} stays as it was`);
+        }
+    };
+    const stop = async (color) => {
+        for (const appId of colorApps(color)) {
+            await input.renew();
+            try {
+                await coolify.raw('POST', `/applications/${appId}/stop`);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+    };
+    const deps = {
+        async readHealth(range) {
+            await input.renew();
+            const token = await input.healthToken();
+            if (!token)
+                return null;
+            input.secret(token);
+            return readReleaseHealth({
+                ...addressOf(healthColor()),
+                token,
+                ...range,
+                ...(input.fetch ? { fetchImpl: input.fetch } : {}),
+            });
+        },
+        async observeColor(color) {
+            await input.renew();
+            const appId = primaryColorApp(color);
+            if (!appId)
+                return { status: 'other', address: 'unchecked' };
+            const status = statusOf((await coolify.getApplication(appId)).status);
+            if (status !== 'running')
+                return { status, address: 'unchecked' };
+            return {
+                status,
+                address: await checkColorAddress({
+                    ...addressOf(color),
+                    healthPath: subject.healthPath,
+                    ...(input.fetch ? { fetchImpl: input.fetch } : {}),
+                }),
+            };
+        },
+        async effect(effect) {
+            if (effect.kind === 'deploy')
+                await deployTo(effect.color, effect.digest);
+            else
+                await stop(effect.color);
+        },
+    };
+    return {
+        deps,
+        async refreshStage() {
+            const stageId = recorded()[bgKey.app(id, input.primaryUuid, 'stage')];
+            if (!stageId || !coolify.listApplicationDeployments)
+                return;
+            let rows;
+            try {
+                rows = await coolify.listApplicationDeployments(stageId, 5);
+            }
+            catch {
+                // The next run reads it again; a stale stage digest only delays a promote.
+                return;
+            }
+            const built = rows.find((row) => row.status === 'finished' && COMMIT.test(row.commit ?? ''));
+            if (built?.commit && recorded()[bgKey.stage(id)] !== built.commit) {
+                context.recordScopeId(bgKey.stage(id), built.commit);
+            }
+        },
+        async writeWeights() {
+            const pattern = new RegExp(`^bg\\.${id}\\.app\\.([^.]+)\\.lb$`);
+            const servers = Object.keys(recorded())
+                .map((key) => pattern.exec(key)?.[1])
+                .filter((uuid) => Boolean(uuid));
+            for (const uuid of servers) {
+                await input.renew();
+                await applyBlueGreenWeights({
+                    coolify,
+                    recorded,
+                    record: (key, value) => context.recordScopeId(key, value),
+                    persist: () => context.persist(),
+                    label: input.label,
+                }, subject, { uuid, primaryUuid: input.primaryUuid });
+            }
+        },
+    };
+}
+/** Whether any server's balancer was last written with weights other than `weights`. */
+function balancerLags(ids, id, weights) {
+    const pattern = new RegExp(`^bg\\.${id}\\.app\\.([^.]+)\\.lb$`);
+    return Object.keys(ids).some((key) => {
+        const uuid = pattern.exec(key)?.[1];
+        return uuid !== undefined && ids[bgKey.lb(id, uuid)] !== weights;
+    });
+}
+/**
+ * One release run for one subject, writing into `context` (the live recorded ids of the run that holds
+ * the mutation lease, so no stale copy is ever written back). Seeds `live` and the weights on the first run
+ * after the structure is applied. The weights the runner decided reach every server's balancer before this
+ * returns; a balancer that fails leaves `bg.<id>.lb.<server>` behind the weights, and the next run
+ * (like the next apply, through its `bluegreen-lb` step) writes it again.
+ */
+export async function runSubjectRelease(input) {
+    const { subject, context } = input;
+    const id = subject.id;
+    const ids = () => context.recordedIds();
+    if (!ids()[bgKey.applied(id, input.primaryUuid)])
+        return { blocked: [], refused: [] };
+    if (!ids()[bgKey.live(id)]) {
+        context.recordScopeId(bgKey.live(id), 'blue');
+        if (!ids()[bgKey.weights(id)])
+            context.recordScopeId(bgKey.weights(id), DEFAULT_WEIGHTS);
+        await context.persist();
+    }
+    await input.host.refreshStage();
+    const before = ids()[bgKey.weights(id)];
+    const result = await runRelease({
+        store: {
+            getScopeIds: async () => ({ ...ids() }),
+            addRequest: async () => {
+                throw new Error('the release runner takes requests; it does not add them');
+            },
+            openRequests: (query) => input.store.openRequests(query),
+            consumeRequests: async () => {
+                throw new Error('the release runner consumes requests after it persists');
+            },
+        },
+        orgId: input.scopeOwnerId,
+        entryKey: id,
+        entry: subject.config,
+        now: input.now,
+        deps: input.host.deps,
+    });
+    for (const [key, value] of Object.entries(result.writes)) {
+        if (value === null)
+            context.forgetId(key);
+        else
+            context.recordScopeId(key, value);
+    }
+    await context.persist();
+    await input.store.consumeRequests(result.requestIds);
+    const after = parseWeights(ids()[bgKey.weights(id)]);
+    // Also when a balancer lags the weights (an earlier write failed), so the next tick retries it.
+    if (after && (formatWeights(after) !== before || balancerLags(ids(), id, formatWeights(after)))) {
+        await input.host.writeWeights();
+    }
+    return { blocked: result.blocked, refused: result.refused };
+}

package/dist/plan/remote-database.d.ts

@@ -0,0 +1,124 @@
+import type { DeclaredOrg } from '../org.js';
+import { type BlueGreenServer } from './blue-green.js';
+import type { DraftStep } from './diff.js';
+import type { AccessPort } from './edge-access.js';
+import type { DnsPort } from './edge-dns.js';
+import type { TunnelIngress, TunnelPort } from './edge-tunnels.js';
+import type { ZonePort } from './edge-zones.js';
+import type { CoolifyPort } from './executor.js';
+/**
+ * A blue/green app on a server other than the database's reaches its one database through a
+ * Cloudflare tunnel TCP route behind an Access service token (William, 2026-10-15). The tunnel has a
+ * `tcp://<org>-db:5432` rule on an internal hostname; Access lets only the service token in; a
+ * `cloudflared access tcp` sidecar on each other server listens on 5432 under the name
+ * {@link remoteDatabaseHost}.
+ */
+export declare const REMOTE_DATABASE_PORT = 5432;
+/** The sidecar's name on the Docker network of `serverUuid`, or `null` on the database's own server. */
+export declare function remoteDatabaseHost(entryKey: string, serverUuid: string, primaryUuid: string): string | null;
+/** The `host:port` a color on a server other than the database's connects to. */
+export declare const remoteDatabaseAddress: (host: string) => string;
+/** What the host knows when it plans. Absent from the plan options: the host cannot do this, nothing is planned. */
+export interface RemoteDatabaseFacts {
+    /** Every usable, reachable Coolify server. */
+    serverUuids: readonly string[];
+    /** The server that holds the database. */
+    primaryUuid: string | null;
+    /** The internal zone's apex at the platform's edge; `null` when it has none. */
+    zone: string | null;
+    /** The executor has Access, tunnel, DNS and zone ports. */
+    access: boolean;
+}
+/**
+ * The facts for {@link planRemoteDatabase}, from what the planner already read. The zone is the one the org's
+ * tunnel names live in (`org.domain`); `access` says the host can reach Access, tunnels, DNS and zones.
+ */
+export declare function remoteDatabaseFactsFrom(input: {
+    org: DeclaredOrg;
+    servers: readonly BlueGreenServer[];
+    recorded: Readonly<Record<string, string>>;
+    access: boolean;
+}): RemoteDatabaseFacts;
+/** One TCP rule: the hostname under the internal zone and the database it reaches. */
+export interface TcpRoute {
+    hostname: string;
+    service: string;
+}
+/** The scope ids one entry's step keeps. None holds a secret. */
+export declare const remoteDatabaseKeys: (entryKey: string) => {
+    /** The service token's id, from its mint until its secret reached every sidecar. No `:`. */
+    undelivered: string;
+    /** The service token's id once delivered. */
+    token: string;
+    access: string;
+    route: string;
+    applied: string;
+    sidecar: (serverUuid: string) => string;
+};
+/** The tunnel's HTTP rules as the org tunnel step last wrote them (JSON), so a later write keeps them. */
+export declare const TUNNEL_HTTP_INGRESS_SCOPE_KEY = "cloudflare_tunnel_http_ingress";
+/** Every TCP route recorded for the org, in key order. */
+export declare function recordedTcpRoutes(recorded: Readonly<Record<string, string>>): TcpRoute[];
+/** The HTTP rules recorded by the tunnel step, catch-all included; `[]` if none or unreadable. */
+export declare function recordedHttpIngress(recorded: Readonly<Record<string, string>>): TunnelIngress[];
+/**
+ * The tunnel's whole ingress: the TCP rules first (their names are exact), then every HTTP rule, the
+ * catch-all last. `putTunnelConfig` replaces the whole list, so every writer builds it through this.
+ */
+export declare function mergeTcpIngress(http: TunnelIngress[], tcp: TcpRoute[]): TunnelIngress[];
+/** What the step carries to the executor (`action.desired`). No secret. */
+export interface RemoteDatabaseDesired {
+    entry: string;
+    app: string;
+    hostname: string;
+    /** The recorded id of the org's database; the executor reads its container name from the live database. */
+    database: string;
+    primary: string;
+    servers: string[];
+    zone: string;
+}
+/** Whether the route step has been applied for `serverUuid`: its marker names the server. */
+export declare function remoteDatabaseAppliedFor(recorded: Readonly<Record<string, string>>, entryKey: string, serverUuid: string): boolean;
+/**
+ * Plans the remote database route for the org's blue/green database entry. One server, or no facts,
+ * plans nothing. A missing zone, port, tunnel or primary is a blocked line (rule 2), and so is a token
+ * that was minted and never delivered (rule 1): it is never minted again.
+ */
+export declare function planRemoteDatabase(org: DeclaredOrg, facts: RemoteDatabaseFacts | undefined, recorded: Readonly<Record<string, string>>): {
+    step: DraftStep | null;
+    blocked: {
+        description: string;
+        key: string;
+    } | null;
+};
+/** The Dockerfile of the sidecar: the pinned `cloudflared`, listening on 5432 for the Access-protected route. */
+export declare function remoteDatabaseDockerfile(hostname: string): string;
+export interface RemoteDatabaseDeps {
+    tunnels: Pick<TunnelPort, 'putTunnelConfig'>;
+    access: Pick<AccessPort, 'listAccessApps' | 'createAccessApp' | 'listAccessPolicies' | 'createAccessPolicy' | 'findServiceTokenByName' | 'createServiceToken'>;
+    dns: Pick<DnsPort, 'findDnsRecord' | 'createDnsRecord'>;
+    zones: Pick<ZonePort, 'findZoneByApex'>;
+    coolify: Pick<CoolifyPort, 'getApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'findOrCreateEnvironment'>;
+    /** Registers a value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+}
+export interface RemoteDatabaseRun {
+    org: DeclaredOrg;
+    desired: RemoteDatabaseDesired;
+    /** The database's container name on the Docker network, as the app's `DATABASE_URL` names it. */
+    databaseHost: string;
+    projectUuid: string;
+    recorded(): Readonly<Record<string, string>>;
+    record(key: string, value: string): void;
+    persist(): Promise<void>;
+}
+/**
+ * Applies one entry's route. The Access app and its service-token policy come first, so the tunnel route
+ * and the DNS record never exist without the gate in front of them. The service token is minted once
+ * (rule 1): its id is recorded and persisted before delivery, the secret goes only to the sidecars' env
+ * (rule 6), the delivered id replaces it, and the applied marker is the last write. A failure halfway
+ * leaves a repair for the next run: the Access app, sidecars, route and DNS are found again; a minted
+ * token is never minted again. A sidecar made after the mint takes its secret from an existing sidecar's
+ * env. Every outside call is bounded by the ports' own timeouts (edge SDK and Coolify client).
+ */
+export declare function applyRemoteDatabase(deps: RemoteDatabaseDeps, run: RemoteDatabaseRun): Promise<void>;