@wtfalch/foundry 0.42.1 → 0.44.0

package/dist/plan/zitadel-machine-user.d.ts

@@ -76,6 +76,18 @@ export declare class ZitadelLoginClientRoleConflictError extends Error {
     readonly roles: readonly string[];
     constructor(userId: string, roles: readonly string[]);
 }
+/** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
+export declare const ORG_DIRECTORY_READER_ROLE = "ORG_OWNER_VIEWER";
+/**
+ * C3: thrown by `mintOrgDirectoryReader` when the user already exists with an organisation role other
+ * than the read-only one. That user was not made by foundry; granting it more or handing out its PAT
+ * would widen access nobody asked for. A person resolves it by hand.
+ */
+export declare class ZitadelDirectoryRoleConflictError extends Error {
+    readonly userId: string;
+    readonly roles: readonly string[];
+    constructor(userId: string, roles: readonly string[]);
+}
 export interface ZitadelMinterOptions {
     /** The new instance's base URL, e.g. `https://auth.companyincluded.com`. */
     url: string;
@@ -84,4 +96,4 @@ export interface ZitadelMinterOptions {
     fetchImpl?: typeof fetch;
     instanceHost?: string;
 }
-export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName'>;
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'mintOrgDirectoryReader' | 'revokeOrgDirectoryReader'>;

package/dist/plan/zitadel-machine-user.js

@@ -84,6 +84,23 @@ export class ZitadelLoginClientRoleConflictError extends Error {
         this.name = 'ZitadelLoginClientRoleConflictError';
     }
 }
+/** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
+export const ORG_DIRECTORY_READER_ROLE = 'ORG_OWNER_VIEWER';
+/**
+ * C3: thrown by `mintOrgDirectoryReader` when the user already exists with an organisation role other
+ * than the read-only one. That user was not made by foundry; granting it more or handing out its PAT
+ * would widen access nobody asked for. A person resolves it by hand.
+ */
+export class ZitadelDirectoryRoleConflictError extends Error {
+    userId;
+    roles;
+    constructor(userId, roles) {
+        super(`ZITADEL machine user ${userId} already exists with organisation role(s) [${roles.join(', ') || 'none'}], not only [${ORG_DIRECTORY_READER_ROLE}] -- refusing to reuse it as a directory reader`);
+        this.userId = userId;
+        this.roles = roles;
+        this.name = 'ZitadelDirectoryRoleConflictError';
+    }
+}
 export function createZitadelAdminMinter(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     async function call(method, path, body, orgId) {
@@ -263,7 +280,70 @@ export function createZitadelAdminMinter(options) {
         }
         return { userId };
     }
+    /**
+     * C3: a machine user inside one ZITADEL organisation with the read-only org role
+     * {@link ORG_DIRECTORY_READER_ROLE} and nothing else, plus a fresh PAT. Every PAT it already holds is
+     * revoked first, so a rerun leaves exactly one live token. An existing user that holds any other
+     * org role is refused, not reused. The calls follow ZITADEL's published v1 management API and have
+     * not been run against a live instance.
+     */
+    async function mintOrgDirectoryReader(orgId, input) {
+        const found = await call('POST', '/management/v1/users/_search', {
+            queries: [
+                { userNameQuery: { userName: input.userName, method: 'TEXT_QUERY_METHOD_EQUALS' } },
+            ],
+        }, orgId);
+        const existing = found.result?.[0]?.id;
+        let userId = existing;
+        if (!userId) {
+            const created = await call('POST', '/management/v1/users/machine', {
+                userName: input.userName,
+                name: input.name,
+                accessTokenType: 'ACCESS_TOKEN_TYPE_BEARER',
+            }, orgId);
+            userId = typeof created.userId === 'string' ? created.userId : undefined;
+        }
+        if (!userId)
+            throw new Error('ZITADEL did not return the machine user id');
+        if (existing) {
+            const members = await call('POST', '/management/v1/orgs/me/members/_search', { queries: [{ userIdQuery: { userId } }] }, orgId);
+            const roles = (members.result ?? [])
+                .filter((m) => m.userId === userId)
+                .flatMap((m) => m.roles ?? []);
+            if (roles.some((role) => role !== ORG_DIRECTORY_READER_ROLE)) {
+                throw new ZitadelDirectoryRoleConflictError(userId, roles);
+            }
+        }
+        try {
+            await call('POST', '/management/v1/orgs/me/members', { userId, roles: [ORG_DIRECTORY_READER_ROLE] }, orgId);
+        }
+        catch (e) {
+            if (!(e instanceof ZitadelHttpError && e.status === 409))
+                throw e;
+        }
+        await revokeAllPats(orgId, userId);
+        const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, orgId);
+        const patId = typeof pat.tokenId === 'string' && pat.tokenId !== '' ? pat.tokenId : undefined;
+        if (typeof pat.token !== 'string' || pat.token === '' || !patId) {
+            throw new Error(`ZITADEL returned no token for machine user ${userId}`);
+        }
+        return { userId, token: pat.token, patId };
+    }
+    /** Deletes every PAT of a user; a PAT already gone (404) is the outcome wanted. */
+    async function revokeAllPats(orgId, userId) {
+        for (const patId of await listPats(orgId, userId)) {
+            try {
+                await call('DELETE', `/management/v1/users/${userId}/pats/${patId}`, undefined, orgId);
+            }
+            catch (e) {
+                if (!(e instanceof ZitadelHttpError && e.status === 404))
+                    throw e;
+            }
+        }
+    }
     return {
+        mintOrgDirectoryReader,
+        revokeOrgDirectoryReader: revokeAllPats,
         mintAdminMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_OWNER').then(({ userId, token }) => ({ userId, token })),
         mintLoginClientMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_LOGIN_CLIENT'),
         // #216 round 2: lets the caller (`platform-providers.ts`) re-check, after

package/dist/platform.d.ts

@@ -12,6 +12,16 @@ export interface PlatformService {
     hostname: string;
     gitRef: string;
 }
+/**
+ * `archon`'s own extra field: presence turns blue/green on for platform-archon, through the same code as a hosting
+ * entry (`plan/blue-green.ts`). The tunnel moves to the balancer only once a balancer is recorded.
+ */
+export interface PlatformArchonService extends PlatformService {
+    blueGreen?: {
+        steps?: number[];
+        stepHoldMinutes?: number;
+    };
+}
 /**
  * `sfu`'s own extra field. A host that changes what the SFU VM is reached
  * with (its SSH key, host key or tunnel token) sets a new `connectionRevision`
@@ -97,7 +107,7 @@ export interface DeclaredPlatform {
     ai: PlatformService;
     jobs: PlatformService;
     integrations: PlatformService;
-    archon: PlatformService;
+    archon: PlatformArchonService;
     /** #317 (F7). No deploy step reads this service's own `gitRef` yet -- `N1` is deployed by hand until it exists. */
     edge: PlatformService;
     /**

package/dist/platform.js

@@ -1,5 +1,5 @@
 import { isIPv4 } from 'node:net';
-import { validateDomain } from './org.js';
+import { validateBlueGreen, validateDomain } from './org.js';
 /** Where Archon publishes the Worker script for `tag` (a private repo; the host's `fetchArtifact` fetches it). */
 export function uptimeArtifactUrl(tag) {
     return `https://github.com/wtfalch/archon/releases/download/${tag}/archon-uptime-worker.js`;
@@ -69,6 +69,9 @@ export function validatePlatform(platform) {
             return `${key}.gitRef must not be empty once ${key}.enabled is true`;
         }
     }
+    const blueGreenReason = validateBlueGreen(platform.archon.blueGreen, 'archon');
+    if (blueGreenReason)
+        return blueGreenReason;
     const revision = platform.sfu.connectionRevision;
     if (revision != null && !/^[A-Za-z0-9:.-]{0,64}$/.test(revision)) {
         return 'sfu.connectionRevision must be at most 64 characters of A-Z, a-z, 0-9, ":", "." and "-"';

package/dist/release/decide.d.ts

@@ -0,0 +1,95 @@
+import { type Color, type ReleaseAction, type ReleaseSignal, type WindowState } from './types.js';
+/** ADR 0001 rule 5: the default steps and the least time on each. */
+export declare const DEFAULT_STEPS: readonly number[];
+export declare const DEFAULT_STEP_HOLD_MINUTES = 60;
+/** Rule 7: errors this share of requests, with at least HARD_FAIL_MIN_REQUESTS, roll back at any level. */
+export declare const HARD_FAIL_ERROR_RATE = 0.9;
+export declare const HARD_FAIL_MIN_REQUESTS = 2;
+/** Rule 8: a relative fail needs this many requests and this many failed checks in a row. */
+export declare const RELATIVE_MIN_REQUESTS = 20;
+export declare const RELATIVE_FAILED_CHECKS = 3;
+/** A relative check counts only this long after the last counted one, so runs close together (applies also run releases) are one check. */
+export declare const CHECK_INTERVAL_MINUTES = 10;
+/** The new color matches the baseline while its error rate is at most baseline plus this (absolute). */
+export declare const ERROR_RATE_MARGIN = 0.02;
+/** Rules 12 and 13: the window at 100% closes after this long, and at most this long. */
+export declare const WINDOW_MIN_HOURS = 24;
+export declare const WINDOW_CAP_DAYS = 7;
+/** The new color must be running and answer on its own address within this time of the deploy. */
+export declare const DEPLOY_TIMEOUT_MINUTES = 30;
+export interface ActiveRelease {
+    from: Color;
+    to: Color;
+    digest: string;
+    /** Relative-fail checks in a row. */
+    fails: number;
+    /** When the last counted relative check ran (ISO). Absent: none yet in this step. */
+    checkedAt?: string | undefined;
+}
+export interface Recorded {
+    live: Color;
+    digests: Record<Color, string | null>;
+    stageDigest: string | null;
+    weights: Record<Color, number>;
+    window: WindowState;
+    /** Set while window.kind is step, inconclusive, window or cap. */
+    release: ActiveRelease | null;
+    held: string[];
+}
+export interface ColorCounts {
+    requests: number;
+    errors: number;
+}
+/** The reporting health read (C1), once validated. */
+export interface HealthRead {
+    colors: Record<Color, ColorCounts>;
+    daily: {
+        days: number;
+        requestsPerDay: number;
+        errorsPerDay: number;
+    };
+}
+export interface Observation {
+    /** null when the health read failed: counted as inconclusive, never as a pass. */
+    health: HealthRead | null;
+    /** The new color's Coolify status. */
+    status: 'running' | 'crash_loop' | 'other';
+    /** The new color's own address, checked over HTTP. */
+    address: 'ok' | 'failed' | 'unchecked';
+}
+export type ReleaseEffect = {
+    kind: 'deploy';
+    color: Color;
+    digest: string;
+} | {
+    kind: 'stop';
+    color: Color;
+};
+export interface Decision {
+    recorded: Recorded;
+    signal: ReleaseSignal | null;
+    effects: ReleaseEffect[];
+    /** Blocked items for the operator, fixed text. */
+    blocked: string[];
+    /** Actions that changed nothing, with a fixed reason. */
+    refused: string[];
+}
+export declare function normalizeSteps(steps: readonly number[] | undefined): number[];
+/** The time a health read should cover: from the step or window start to now. */
+export declare function healthRange(r: Recorded, now: Date): {
+    from: string;
+    to: string;
+} | null;
+/**
+ * The whole release decision for one run: from the recorded state, the
+ * actions requested, one observation and the time, the next recorded state.
+ * Pure: it reads nothing and writes nothing (ADR 0001 rules 5, 7-13, 16).
+ */
+export declare function decide(input: {
+    recorded: Recorded;
+    actions: readonly ReleaseAction[];
+    steps?: readonly number[] | undefined;
+    stepHoldMinutes?: number | undefined;
+    now: Date;
+    observation: Observation;
+}): Decision;

package/dist/release/decide.js

@@ -0,0 +1,242 @@
+import { otherColor, } from './types.js';
+/** ADR 0001 rule 5: the default steps and the least time on each. */
+export const DEFAULT_STEPS = [5, 10, 25, 50, 100];
+export const DEFAULT_STEP_HOLD_MINUTES = 60;
+/** Rule 7: errors this share of requests, with at least HARD_FAIL_MIN_REQUESTS, roll back at any level. */
+export const HARD_FAIL_ERROR_RATE = 0.9;
+export const HARD_FAIL_MIN_REQUESTS = 2;
+/** Rule 8: a relative fail needs this many requests and this many failed checks in a row. */
+export const RELATIVE_MIN_REQUESTS = 20;
+export const RELATIVE_FAILED_CHECKS = 3;
+/** A relative check counts only this long after the last counted one, so runs close together (applies also run releases) are one check. */
+export const CHECK_INTERVAL_MINUTES = 10;
+/** The new color matches the baseline while its error rate is at most baseline plus this (absolute). */
+export const ERROR_RATE_MARGIN = 0.02;
+/** Rules 12 and 13: the window at 100% closes after this long, and at most this long. */
+export const WINDOW_MIN_HOURS = 24;
+export const WINDOW_CAP_DAYS = 7;
+/** The new color must be running and answer on its own address within this time of the deploy. */
+export const DEPLOY_TIMEOUT_MINUTES = 30;
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+export function normalizeSteps(steps) {
+    const wanted = steps && steps.length > 0 ? steps : DEFAULT_STEPS;
+    const valid = [...new Set(wanted.filter((n) => Number.isInteger(n) && n >= 1 && n <= 100))].sort((a, b) => a - b);
+    if (valid.length === 0)
+        return [...DEFAULT_STEPS];
+    if (valid[valid.length - 1] !== 100)
+        valid.push(100);
+    return valid;
+}
+function weightsFor(to, percent) {
+    return { [to]: percent, [otherColor(to)]: 100 - percent };
+}
+function rollback(r, now, reason) {
+    const rel = r.release;
+    if (!rel)
+        return r;
+    return {
+        ...r,
+        live: rel.from,
+        weights: weightsFor(rel.from, 100),
+        window: { kind: 'rolled_back', at: now.toISOString(), reason },
+        release: null,
+        held: r.held.includes(rel.digest) ? r.held : [...r.held, rel.digest],
+    };
+}
+function rate(c) {
+    return c.requests > 0 ? c.errors / c.requests : 0;
+}
+function dailyRate(h) {
+    return h.daily.requestsPerDay > 0 ? h.daily.errorsPerDay / h.daily.requestsPerDay : 0;
+}
+/** The time a health read should cover: from the step or window start to now. */
+export function healthRange(r, now) {
+    const w = r.window;
+    if (w.kind === 'step' || w.kind === 'inconclusive' || w.kind === 'window' || w.kind === 'cap') {
+        if (w.kind === 'inconclusive' && w.percent === 0)
+            return null;
+        return { from: w.since, to: now.toISOString() };
+    }
+    return null;
+}
+function applyActions(r, actions, now, out) {
+    let cur = r;
+    let promoted = false;
+    let ended = false;
+    for (const a of actions) {
+        if (a.kind === 'clear_held') {
+            cur = { ...cur, held: cur.held.filter((d) => d !== a.digest) };
+        }
+        else if (a.kind === 'promote') {
+            const idle = !cur.release;
+            const digest = cur.stageDigest;
+            if (!idle)
+                out.refused.push('promote refused: a release is running');
+            else if (!digest)
+                out.refused.push('promote refused: stage has no digest');
+            else if (cur.held.includes(digest))
+                out.refused.push('promote refused: digest is held');
+            else if (digest === cur.digests[cur.live])
+                out.refused.push('promote refused: digest is already live');
+            else {
+                const to = otherColor(cur.live);
+                cur = {
+                    ...cur,
+                    digests: { ...cur.digests, [to]: digest },
+                    window: { kind: 'inconclusive', percent: 0, since: now.toISOString() },
+                    release: { from: cur.live, to, digest, fails: 0 },
+                };
+                out.effects.push({ kind: 'deploy', color: to, digest });
+                promoted = true;
+            }
+        }
+        else if (a.kind === 'rollback') {
+            if (!cur.release)
+                out.refused.push('rollback refused: no release is running');
+            else {
+                cur = rollback(cur, now, 'operator');
+                ended = true;
+            }
+        }
+        else if (a.kind === 'decide_at_cap') {
+            if (cur.window.kind !== 'cap' || !cur.release)
+                out.refused.push('decision refused: no release is at the cap');
+            else if (a.decision === 'rollback') {
+                cur = rollback(cur, now, 'operator at cap');
+                ended = true;
+            }
+            else {
+                out.effects.push({ kind: 'stop', color: cur.release.from });
+                cur = { ...cur, window: { kind: 'passed', at: now.toISOString() }, release: null };
+                ended = true;
+            }
+        }
+    }
+    return { recorded: cur, promoted, ended };
+}
+/**
+ * The whole release decision for one run: from the recorded state, the
+ * actions requested, one observation and the time, the next recorded state.
+ * Pure: it reads nothing and writes nothing (ADR 0001 rules 5, 7-13, 16).
+ */
+export function decide(input) {
+    const { now, observation } = input;
+    const steps = normalizeSteps(input.steps);
+    const holdMs = (input.stepHoldMinutes ?? DEFAULT_STEP_HOLD_MINUTES) * MINUTE;
+    const out = { effects: [], refused: [] };
+    const applied = applyActions(input.recorded, input.actions, now, out);
+    let r = applied.recorded;
+    let signal = null;
+    const blocked = [];
+    const rel = r.release;
+    if (!applied.promoted && !applied.ended && rel) {
+        const since = Date.parse('since' in r.window ? r.window.since : '');
+        const elapsed = now.getTime() - since;
+        const hard = observation.status === 'crash_loop'
+            ? 'hard fail: crash loop'
+            : observation.address === 'failed'
+                ? 'hard fail: address check failed'
+                : null;
+        if (r.window.kind === 'inconclusive' && r.window.percent === 0) {
+            if (hard)
+                r = rollback(r, now, hard);
+            else if (observation.status === 'running' && observation.address === 'ok') {
+                const first = steps[0];
+                r = stepTo(r, rel, first, now);
+            }
+            else if (elapsed >= DEPLOY_TIMEOUT_MINUTES * MINUTE)
+                r = rollback(r, now, 'deploy timeout');
+        }
+        else {
+            const health = observation.health;
+            const newC = health?.colors[rel.to] ?? { requests: 0, errors: 0 };
+            const atWindow = r.window.kind === 'window' || r.window.kind === 'cap';
+            let baseline = null;
+            if (health) {
+                const old = health.colors[rel.from];
+                baseline = !atWindow && old.requests > 0 ? rate(old) : dailyRate(health);
+            }
+            const hardRate = newC.requests >= HARD_FAIL_MIN_REQUESTS && rate(newC) >= HARD_FAIL_ERROR_RATE;
+            let verdict;
+            if (hard || hardRate)
+                verdict = 'hard_fail';
+            else if (!health || baseline === null || newC.requests < RELATIVE_MIN_REQUESTS)
+                verdict = 'inconclusive';
+            else
+                verdict = rate(newC) > baseline + ERROR_RATE_MARGIN ? 'fail' : 'pass';
+            signal = { requests: newC.requests, errors: newC.errors, baselineRate: baseline, verdict };
+            if (verdict === 'hard_fail') {
+                r = rollback(r, now, hard ?? 'hard fail: error rate');
+            }
+            else {
+                const spaced = !rel.checkedAt ||
+                    now.getTime() - Date.parse(rel.checkedAt) >= CHECK_INTERVAL_MINUTES * MINUTE;
+                const counted = spaced && verdict !== 'inconclusive';
+                const fails = !counted ? rel.fails : verdict === 'fail' ? rel.fails + 1 : 0;
+                if (fails >= RELATIVE_FAILED_CHECKS) {
+                    r = rollback(r, now, 'relative fail: failed checks in a row');
+                }
+                else {
+                    r = {
+                        ...r,
+                        release: { ...rel, fails, ...(counted ? { checkedAt: now.toISOString() } : {}) },
+                    };
+                    if (!atWindow) {
+                        const pct = r.window.percent;
+                        const holdDone = elapsed >= holdMs;
+                        if (holdDone && verdict !== 'fail') {
+                            const next = steps.find((s) => s > pct);
+                            r = stepTo(r, rel, next, now);
+                        }
+                        else {
+                            const kind = verdict === 'inconclusive' ? 'inconclusive' : 'step';
+                            r = {
+                                ...r,
+                                window: { kind, percent: pct, since: r.window.since },
+                            };
+                        }
+                    }
+                    else {
+                        const required = Math.max(1, Math.ceil(health?.daily.requestsPerDay ?? 0));
+                        const closable = health !== null &&
+                            baseline !== null &&
+                            elapsed >= WINDOW_MIN_HOURS * HOUR &&
+                            newC.requests >= required &&
+                            rate(newC) <= baseline + ERROR_RATE_MARGIN;
+                        if (closable) {
+                            out.effects.push({ kind: 'stop', color: rel.from });
+                            r = { ...r, window: { kind: 'passed', at: now.toISOString() }, release: null };
+                        }
+                        else if (elapsed >= WINDOW_CAP_DAYS * DAY) {
+                            r = { ...r, window: { kind: 'cap', since: new Date(since).toISOString() } };
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (r.window.kind === 'cap')
+        blocked.push('release window reached the cap without enough data: pass or roll back in Archon');
+    return { recorded: r, signal, effects: out.effects, blocked, refused: out.refused };
+}
+function stepTo(r, rel, percent, now) {
+    const at = now.toISOString();
+    const fresh = { from: rel.from, to: rel.to, digest: rel.digest, fails: 0 };
+    if (percent >= 100) {
+        return {
+            ...r,
+            live: rel.to,
+            weights: weightsFor(rel.to, 100),
+            window: { kind: 'window', since: at },
+            release: fresh,
+        };
+    }
+    return {
+        ...r,
+        weights: weightsFor(rel.to, percent),
+        window: { kind: 'step', percent, since: at },
+        release: fresh,
+    };
+}

package/dist/release/health.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { HealthRead } from './decide.js';
+/** The reporting health read has this long to answer. */
+export declare const HEALTH_READ_TIMEOUT_MS = 10000;
+/** The color's own address check has this long to answer. */
+export declare const ADDRESS_CHECK_TIMEOUT_MS = 10000;
+/** C1's 200 body. */
+export declare const healthBody: z.ZodObject<{
+    colors: z.ZodObject<{
+        blue: z.ZodObject<{
+            requests: z.ZodNumber;
+            errors: z.ZodNumber;
+        }, z.core.$strip>;
+        green: z.ZodObject<{
+            requests: z.ZodNumber;
+            errors: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    daily: z.ZodObject<{
+        days: z.ZodNumber;
+        requestsPerDay: z.ZodNumber;
+        errorsPerDay: z.ZodNumber;
+    }, z.core.$strip>;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `GET <address>/api/reporting/release-health?from&to` with the bearer token.
+ * Returns null for any failure (network, timeout, status, shape): the caller
+ * counts that as inconclusive, never as a pass. Nothing about the response or
+ * the token reaches a log or an error.
+ */
+export declare function readReleaseHealth(input: {
+    address: string;
+    token: string;
+    from: string;
+    to: string;
+    /** Extra request headers, e.g. the load balancer's color pin. */
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}): Promise<HealthRead | null>;
+/** An HTTP check of the color's health path on its own address. */
+export declare function checkColorAddress(input: {
+    address: string;
+    healthPath: string | null;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}): Promise<'ok' | 'failed'>;

package/dist/release/health.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/** The reporting health read has this long to answer. */
+export const HEALTH_READ_TIMEOUT_MS = 10_000;
+/** The color's own address check has this long to answer. */
+export const ADDRESS_CHECK_TIMEOUT_MS = 10_000;
+const counts = z.object({
+    requests: z.number().int().nonnegative(),
+    errors: z.number().int().nonnegative(),
+});
+/** C1's 200 body. */
+export const healthBody = z.object({
+    colors: z.object({ blue: counts, green: counts }),
+    daily: z.object({
+        days: z.number().nonnegative(),
+        requestsPerDay: z.number().nonnegative(),
+        errorsPerDay: z.number().nonnegative(),
+    }),
+    from: z.string(),
+    to: z.string(),
+});
+/**
+ * `GET <address>/api/reporting/release-health?from&to` with the bearer token.
+ * Returns null for any failure (network, timeout, status, shape): the caller
+ * counts that as inconclusive, never as a pass. Nothing about the response or
+ * the token reaches a log or an error.
+ */
+export async function readReleaseHealth(input) {
+    try {
+        const url = new URL('/api/reporting/release-health', input.address);
+        url.searchParams.set('from', input.from);
+        url.searchParams.set('to', input.to);
+        const res = await (input.fetchImpl ?? fetch)(url, {
+            headers: { ...input.headers, authorization: `Bearer ${input.token}` },
+            signal: AbortSignal.timeout(HEALTH_READ_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const parsed = healthBody.safeParse(await res.json());
+        if (!parsed.success)
+            return null;
+        return { colors: parsed.data.colors, daily: parsed.data.daily };
+    }
+    catch {
+        // Network error, timeout or invalid JSON: all the same to the caller.
+        return null;
+    }
+}
+/** An HTTP check of the color's health path on its own address. */
+export async function checkColorAddress(input) {
+    try {
+        const res = await (input.fetchImpl ?? fetch)(new URL(input.healthPath ?? '/', input.address), {
+            ...(input.headers ? { headers: input.headers } : {}),
+            signal: AbortSignal.timeout(ADDRESS_CHECK_TIMEOUT_MS),
+        });
+        return res.ok ? 'ok' : 'failed';
+    }
+    catch {
+        // Unreachable counts as a failed check.
+        return 'failed';
+    }
+}

package/dist/release/run.d.ts

@@ -0,0 +1,40 @@
+import { type Decision, type Observation, type ReleaseEffect } from './decide.js';
+import { type ReleaseStore } from './state.js';
+import type { Color } from './types.js';
+/** What the runner needs from the outside. Each call is bounded by its own timeout. */
+export interface ReleaseDeps {
+    /** The reporting health read for the range, or null when it failed. */
+    readHealth(range: {
+        from: string;
+        to: string;
+    }): Promise<Observation['health']>;
+    /** The Coolify status and the own-address check of a color. */
+    observeColor(color: Color): Promise<Pick<Observation, 'status' | 'address'>>;
+    effect(effect: ReleaseEffect): Promise<void>;
+}
+export interface ReleaseRunResult {
+    /** Scope keys to record (null removes one). The caller persists them with the rest of the run. */
+    writes: Record<string, string | null>;
+    blocked: string[];
+    refused: string[];
+    decision: Decision | null;
+    /** The requests this run acted on. The caller consumes them with `store.consumeRequests` after it persists `writes`. */
+    requestIds: number[];
+}
+/**
+ * One run for one entry. Reads the recorded keys fresh and the open
+ * requests (it consumes none), decides and runs the effects. A failure, or a
+ * crash before the caller persists and consumes, leaves the requests open and
+ * the recorded keys as they were: the next run decides again from them.
+ */
+export declare function runRelease(input: {
+    store: ReleaseStore;
+    orgId: string;
+    entryKey: string;
+    entry: {
+        steps?: number[];
+        stepHoldMinutes?: number;
+    };
+    now: Date;
+    deps: ReleaseDeps;
+}): Promise<ReleaseRunResult>;