@wtfalch/foundry 0.42.1 → 0.44.0

package/dist/release/run.js

@@ -0,0 +1,56 @@
+import { decide, healthRange, } from './decide.js';
+import { formatWeights, formatWindow, recordedFrom, releaseKeys, } from './state.js';
+/**
+ * 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 async function runRelease(input) {
+    const { store, orgId, entryKey, deps, now } = input;
+    const ids = await store.getScopeIds(orgId);
+    const recorded = recordedFrom(ids, entryKey);
+    if (!recorded)
+        return { writes: {}, blocked: [], refused: [], decision: null, requestIds: [] };
+    const open = await store.openRequests({ orgId, entryKey });
+    const actions = open.map((r) => r.action);
+    const range = healthRange(recorded, now);
+    const target = recorded.release?.to ?? null;
+    const health = range ? await deps.readHealth(range) : null;
+    const seen = target
+        ? await deps.observeColor(target)
+        : { status: 'other', address: 'unchecked' };
+    const decision = decide({
+        recorded,
+        actions,
+        steps: input.entry.steps,
+        stepHoldMinutes: input.entry.stepHoldMinutes,
+        now,
+        observation: { health, ...seen },
+    });
+    for (const effect of decision.effects)
+        await deps.effect(effect);
+    const k = releaseKeys(entryKey);
+    const next = decision.recorded;
+    const writes = {
+        [k.live]: next.live,
+        [k.weights]: formatWeights(next.weights),
+        [k.digest('blue')]: next.digests.blue,
+        [k.digest('green')]: next.digests.green,
+        [k.window]: formatWindow(next.window, next.release),
+        [k.signal]: decision.signal ? JSON.stringify(decision.signal) : null,
+    };
+    for (const d of recorded.held)
+        if (!next.held.includes(d))
+            writes[k.held(d)] = null;
+    for (const d of next.held)
+        if (!recorded.held.includes(d))
+            writes[k.held(d)] = now.toISOString();
+    return {
+        writes,
+        blocked: decision.blocked,
+        refused: decision.refused,
+        decision,
+        requestIds: open.map((r) => r.id),
+    };
+}

package/dist/release/state.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type { Recorded } from './decide.js';
+import type { Color, ReleaseAction, ReleaseSignal, ReleaseState, WindowState } from './types.js';
+/**
+ * The persistence the release runner and Archon share. `getScopeIds` is the
+ * recorded `bg.*` keys of an org's applied state (or of the platform, for the
+ * orgId `platform`). Requests live in their own table so a click never races
+ * the runner's snapshot write.
+ */
+export interface ReleaseStore {
+    getScopeIds(orgId: string): Promise<Record<string, string>>;
+    addRequest(input: {
+        orgId: string;
+        entryKey: string;
+        action: ReleaseAction;
+        actor: string;
+    }): Promise<void>;
+    /** The open requests, oldest first. Reading consumes nothing: a run that fails leaves them open. */
+    openRequests(input: {
+        orgId: string;
+        entryKey: string;
+    }): Promise<{
+        id: number;
+        action: ReleaseAction;
+        actor: string;
+    }[]>;
+    /** Marks requests consumed. The runner calls it only after its decision is persisted. */
+    consumeRequests(ids: readonly number[]): Promise<void>;
+}
+/** Scope keys (C3). `entry` is a hosting entry key: never `.` or `:`. */
+export declare function releaseKeys(entry: string): {
+    live: string;
+    digest: (c: Color) => string;
+    weights: string;
+    stage: string;
+    window: string;
+    signal: string;
+    heldPrefix: string;
+    held: (digest: string) => string;
+};
+export declare function formatWeights(w: Record<Color, number>): string;
+export declare function parseWeights(value: string | undefined): Record<Color, number> | null;
+/** The window JSON is the C2 state plus the active release's `release` field. */
+export declare function parseWindow(value: string | undefined): {
+    window: WindowState;
+    release: Recorded['release'];
+};
+export declare function formatWindow(window: WindowState, release: Recorded['release']): string;
+export declare function recordedFrom(ids: Record<string, string>, entryKey: string): Recorded | null;
+export declare function readSignal(ids: Record<string, string>, entryKey: string): ReleaseSignal | null;
+/** C2: the release state of one hosting entry, or null before blue/green recorded anything. */
+export declare function readReleaseState(store: ReleaseStore, input: {
+    orgId: string;
+    entryKey: string;
+}): Promise<ReleaseState | null>;
+declare const actionSchema: z.ZodType<ReleaseAction>;
+/** C2: ask the runner to apply an action on its next run. Archon audits it. */
+export declare function requestReleaseAction(store: ReleaseStore, input: {
+    orgId: string;
+    entryKey: string;
+    action: ReleaseAction;
+    actor: string;
+}): Promise<void>;
+export { actionSchema as releaseActionSchema };

package/dist/release/state.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+/** Scope keys (C3). `entry` is a hosting entry key: never `.` or `:`. */
+export function releaseKeys(entry) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(entry))
+        throw new Error('invalid release entry key');
+    const p = `bg.${entry}`;
+    return {
+        live: `${p}.live`,
+        digest: (c) => `${p}.digest.${c}`,
+        weights: `${p}.weights`,
+        stage: `${p}.stage`,
+        window: `${p}.window`,
+        signal: `${p}.signal`,
+        heldPrefix: `${p}.held.`,
+        held: (digest) => `${p}.held.${digest}`,
+    };
+}
+export function formatWeights(w) {
+    return `blue:${w.blue},green:${w.green}`;
+}
+export function parseWeights(value) {
+    const m = /^blue:(\d{1,3}),green:(\d{1,3})$/.exec(value ?? '');
+    if (!m)
+        return null;
+    return { blue: Number(m[1]), green: Number(m[2]) };
+}
+const color = z.enum(['blue', 'green']);
+const storedWindow = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('idle') }),
+    z.object({ kind: z.literal('step'), percent: z.number(), since: z.string() }),
+    z.object({ kind: z.literal('inconclusive'), percent: z.number(), since: z.string() }),
+    z.object({ kind: z.literal('window'), since: z.string() }),
+    z.object({ kind: z.literal('passed'), at: z.string() }),
+    z.object({ kind: z.literal('rolled_back'), at: z.string(), reason: z.string() }),
+    z.object({ kind: z.literal('cap'), since: z.string() }),
+]);
+const releaseField = z
+    .object({
+    from: color,
+    to: color,
+    digest: z.string(),
+    fails: z.number().int().nonnegative(),
+    checkedAt: z.string().optional(),
+})
+    .nullable()
+    .optional();
+const signalSchema = z.object({
+    requests: z.number(),
+    errors: z.number(),
+    baselineRate: z.number().nullable(),
+    verdict: z.enum(['pass', 'fail', 'hard_fail', 'inconclusive']),
+});
+function parseJson(value) {
+    if (!value)
+        return undefined;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        // A damaged value reads as absent; the runner rewrites it.
+        return undefined;
+    }
+}
+/** The window JSON is the C2 state plus the active release's `release` field. */
+export function parseWindow(value) {
+    const state = storedWindow.safeParse(parseJson(value));
+    if (!state.success)
+        return { window: { kind: 'idle' }, release: null };
+    const rel = releaseField.safeParse(parseJson(value).release);
+    return { window: state.data, release: rel.success ? (rel.data ?? null) : null };
+}
+export function formatWindow(window, release) {
+    return JSON.stringify(release ? { ...window, release } : window);
+}
+export function recordedFrom(ids, entryKey) {
+    const k = releaseKeys(entryKey);
+    const live = color.safeParse(ids[k.live]);
+    if (!live.success)
+        return null;
+    const { window, release } = parseWindow(ids[k.window]);
+    return {
+        live: live.data,
+        digests: { blue: ids[k.digest('blue')] ?? null, green: ids[k.digest('green')] ?? null },
+        stageDigest: ids[k.stage] ?? null,
+        weights: parseWeights(ids[k.weights]) ?? { ...{ blue: 0, green: 0 }, [live.data]: 100 },
+        window,
+        release,
+        held: Object.keys(ids)
+            .filter((key) => key.startsWith(k.heldPrefix))
+            .map((key) => key.slice(k.heldPrefix.length))
+            .sort(),
+    };
+}
+export function readSignal(ids, entryKey) {
+    const parsed = signalSchema.safeParse(parseJson(ids[releaseKeys(entryKey).signal]));
+    return parsed.success ? parsed.data : null;
+}
+/** C2: the release state of one hosting entry, or null before blue/green recorded anything. */
+export async function readReleaseState(store, input) {
+    const ids = await store.getScopeIds(input.orgId);
+    const r = recordedFrom(ids, input.entryKey);
+    if (!r)
+        return null;
+    return {
+        entryKey: input.entryKey,
+        live: r.live,
+        weights: r.weights,
+        digests: r.digests,
+        stageDigest: r.stageDigest,
+        window: r.window,
+        signal: readSignal(ids, input.entryKey),
+        held: r.held,
+    };
+}
+const actionSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('promote') }),
+    z.object({ kind: z.literal('rollback') }),
+    z.object({ kind: z.literal('clear_held'), digest: z.string().min(1) }),
+    z.object({ kind: z.literal('decide_at_cap'), decision: z.enum(['pass', 'rollback']) }),
+]);
+/** C2: ask the runner to apply an action on its next run. Archon audits it. */
+export async function requestReleaseAction(store, input) {
+    releaseKeys(input.entryKey);
+    await store.addRequest({ ...input, action: actionSchema.parse(input.action) });
+}
+export { actionSchema as releaseActionSchema };

package/dist/release/types.d.ts

@@ -0,0 +1,54 @@
+export type Color = 'blue' | 'green';
+export type WindowState = {
+    kind: 'idle';
+} | {
+    kind: 'step';
+    percent: number;
+    since: string;
+} | {
+    kind: 'inconclusive';
+    percent: number;
+    since: string;
+} | {
+    kind: 'window';
+    since: string;
+} | {
+    kind: 'passed';
+    at: string;
+} | {
+    kind: 'rolled_back';
+    at: string;
+    reason: string;
+} | {
+    kind: 'cap';
+    since: string;
+};
+export interface ReleaseSignal {
+    requests: number;
+    errors: number;
+    baselineRate: number | null;
+    verdict: 'pass' | 'fail' | 'hard_fail' | 'inconclusive';
+}
+export interface ReleaseState {
+    entryKey: string;
+    live: Color;
+    weights: Record<Color, number>;
+    digests: Record<Color, string | null>;
+    stageDigest: string | null;
+    window: WindowState;
+    signal: ReleaseSignal | null;
+    held: string[];
+}
+export type ReleaseAction = {
+    kind: 'promote';
+} | {
+    kind: 'rollback';
+} | {
+    kind: 'clear_held';
+    digest: string;
+} | {
+    kind: 'decide_at_cap';
+    decision: 'pass' | 'rollback';
+};
+export declare const COLORS: readonly Color[];
+export declare function otherColor(color: Color): Color;

package/dist/release/types.js

@@ -0,0 +1,4 @@
+export const COLORS = ['blue', 'green'];
+export function otherColor(color) {
+    return color === 'blue' ? 'green' : 'blue';
+}

package/dist/requested-changes.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, MailMode, OrgId } from './org.js';
+import { type DeclaredOrg, type MailMode, type OrgId } from './org.js';
 import type { PlanDetail } from './plan/diff.js';
 /**
  * The whitelist of `DeclaredOrg` fields a company's own Boule can request a
@@ -15,13 +15,22 @@ import type { PlanDetail } from './plan/diff.js';
  * lowering or leaving a limit unchanged -- raising either one needs
  * approval too, until a billing field exists to say what the raise costs.
  */
-export type RequestableField = 'calls' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier';
+export type RequestableField = 'calls' | 'customers' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier';
 export declare const REQUESTABLE_FIELDS: readonly RequestableField[];
 /** Turn the org's own calls Matrix stack (`org.ts`'s `CallsConfig.enabled`) on or off. */
 export interface CallsChange {
     field: 'calls';
     enabled: boolean;
 }
+/**
+ * Turn the org's customers on or off and let them register themselves
+ * (`org.ts`'s `CustomersConfig`). `signUp` needs `enabled`: the request is refused otherwise.
+ */
+export interface CustomersChange {
+    field: 'customers';
+    enabled: boolean;
+    signUp: boolean;
+}
 /** Change the org's own spend limit on Files (`org.ts`'s `StorageConfig`). */
 export interface StorageLimitChange {
     field: 'storageLimit';
@@ -48,7 +57,7 @@ export interface MailTierChange {
  * {@link RequestableField}. `classifyChange` and the store both switch on
  * `.field`.
  */
-export type RequestedChangeValue = CallsChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange;
+export type RequestedChangeValue = CallsChange | CustomersChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange;
 /**
  * `auto`: nothing further is required -- archon may carry the request
  * straight into a plan and apply it. `approval`: a human must approve the

package/dist/requested-changes.js

@@ -1,5 +1,7 @@
+import { validateCustomers } from './org.js';
 export const REQUESTABLE_FIELDS = [
     'calls',
+    'customers',
     'storageLimit',
     'aiLimit',
     'domain',
@@ -27,6 +29,8 @@ function applyRequestedChange(org, change) {
     switch (change.field) {
         case 'calls':
             return { ...org, calls: { ...org.calls, enabled: change.enabled } };
+        case 'customers':
+            return { ...org, customers: { enabled: change.enabled, signUp: change.signUp } };
         case 'storageLimit':
             return {
                 ...org,
@@ -69,6 +73,15 @@ function isLimitRaise(before, after) {
         return true;
     return BigInt(after) > BigInt(before);
 }
+/** Throws {@link RequestedChangeError} unless both switches are booleans and sign-up comes with customers on. */
+function validateCustomersChange(change) {
+    if (typeof change.enabled !== 'boolean' || typeof change.signUp !== 'boolean') {
+        throw new RequestedChangeError('customers needs enabled and signUp, both true or false');
+    }
+    if (change.signUp && !change.enabled) {
+        throw new RequestedChangeError('customers.signUp needs customers.enabled');
+    }
+}
 /**
  * `auto` when `change` is small and safe (`calls`, and `storageLimit`/
  * `aiLimit` in the lowering or unchanged direction), the plan it causes has
@@ -102,6 +115,14 @@ export function classifyChange(org, change, plan) {
     if (!REQUESTABLE_FIELDS.includes(change.field)) {
         throw new RequestedChangeError(`'${change.field}' is not a requestable field`);
     }
+    if (change.field === 'customers') {
+        validateCustomersChange(change);
+        // The org after the change must still pass the rule apply checks, for example open registration
+        // on a hosting entry needs customers on; otherwise the request is stored and fails at apply.
+        const invalid = validateCustomers(applyRequestedChange(org, change));
+        if (invalid)
+            throw new RequestedChangeError(invalid);
+    }
     if (plan?.plannedSteps.some((planned) => planned.step.destroys || planned.step.migrates)) {
         return 'approval';
     }
@@ -110,6 +131,7 @@ export function classifyChange(org, change, plan) {
         return 'approval';
     switch (change.field) {
         case 'calls':
+        case 'customers':
             return 'auto';
         case 'storageLimit':
             return isLimitRaise(org.storage.limitBytes, change.limitBytes) ||

package/dist/store/postgres.d.ts

@@ -1,4 +1,5 @@
 import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import { type ReleaseStore } from '../release/state.js';
 import { type AppliedVersionsStore, type DeclaredOrgStore, type PlatformStore, type RequestedChangeStore } from '../store.js';
 /**
  * The host's own drizzle handle or a transaction open on it, same shape
@@ -98,3 +99,10 @@ export declare function createPostgresRequestedChangeStore(db: FoundryStoreDb):
  * lost the way `foundry_applied_state`'s one row per service would lose it.
  */
 export declare function createPostgresAppliedVersionsStore(db: FoundryStoreDb): AppliedVersionsStore;
+/**
+ * `ReleaseStore` (`../release/state.ts`) on Postgres: the recorded `bg.*`
+ * keys come from an org's applied state, or the platform's for the orgId
+ * `platform`; requests are rows in `foundry_release_requests`. Reading leaves
+ * the open rows consumed only when the caller says its run succeeded (`consumeRequests`).
+ */
+export declare function createPostgresReleaseStore(db: FoundryStoreDb): ReleaseStore;

package/dist/store/postgres.js

@@ -1,12 +1,13 @@
-import { and, asc, desc, eq, ne, sql } from 'drizzle-orm';
-import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, validateBuyerIdentity, validateCalls, validateDomain, validateDomainClaim, validateHosting, validateMail, validateOwners, validateServices, validateSignIn, validateSite, validateVersionPin, } from '../org.js';
-import { lockedHostnames } from '../plan/locked-hostnames.js';
+import { and, asc, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm';
+import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, validateBlueGreen, validateBuyerIdentity, validateCalls, validateCustomers, validateDomain, validateDomainClaim, validateHosting, validateMail, validateOwners, validateServices, validateSignIn, validateSite, validateVersionPin, } from '../org.js';
+import { hostingNames } from '../plan/locked-hostnames.js';
 import { findNameClashes, nameClashMessage } from '../plan/org-names.js';
 import { validatePlatform } from '../platform.js';
+import { releaseActionSchema } from '../release/state.js';
 import { RequestedChangeError, classifyChange } from '../requested-changes.js';
 import { validateSlug } from '../slug.js';
 import { StaleLeaseError, } from '../store.js';
-import { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryDeclaredPlatform, foundryMutationLeases, foundryRequestedChanges, } from './schema.js';
+import { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryDeclaredPlatform, foundryMutationLeases, foundryReleaseRequests, foundryRequestedChanges, } from './schema.js';
 const UNIQUE_VIOLATION = '23505';
 /**
  * #441: runs `write`, and with a `fence` only if its token is still the
@@ -148,6 +149,10 @@ function rowToOrg(row) {
             : {}),
         // Omitted while off.
         ...(row.signInInApp ? { signIn: { inApp: true } } : {}),
+        // Omitted while off.
+        ...(row.customersEnabled || row.customersSignUp
+            ? { customers: { enabled: row.customersEnabled, signUp: row.customersSignUp } }
+            : {}),
         // Omitted while unset. Validated on read: a stored value is not trusted.
         ...(row.versionPin ? { versionPin: readVersionPin(row) } : {}),
         site: { enabled: row.siteEnabled, usesDomain: row.siteUsesDomain },
@@ -201,6 +206,8 @@ function orgToRow(org) {
         callsVersionPinMas: org.calls.versionPin?.mas ?? null,
         issuerUsesDomain: org.issuer.usesDomain,
         signInInApp: org.signIn?.inApp ?? false,
+        customersEnabled: org.customers?.enabled ?? false,
+        customersSignUp: org.customers?.signUp ?? false,
         servicesOwn: org.services?.own ?? false,
         servicesSfuSlot: org.services?.sfuSlot ?? null,
         versionPin: org.versionPin && Object.keys(org.versionPin).length > 0 ? org.versionPin : null,
@@ -350,10 +357,7 @@ export function createPostgresDeclaredOrgStore(db) {
     // #71: same place `requireValidBuyer` checks the buyer identity (#67), on
     // both `create` and the merged result of `update`.
     function requireValidHosting(org) {
-        const reason = validateHosting(org.hosting, {
-            domain: org.domain,
-            locked: lockedHostnames(org, []),
-        });
+        const reason = validateHosting(org.hosting, hostingNames(org, []));
         if (reason)
             throw new DeclaredOrgError(`hosting invalid: ${reason} (#71)`);
     }
@@ -407,6 +411,9 @@ export function createPostgresDeclaredOrgStore(db) {
         const signInReason = validateSignIn(org);
         if (signInReason)
             throw new DeclaredOrgError(`signIn invalid: ${signInReason}`);
+        const customersReason = validateCustomers(org);
+        if (customersReason)
+            throw new DeclaredOrgError(`customers invalid: ${customersReason}`);
         const slot = org.services?.sfuSlot ?? null;
         if (slot === null)
             return;
@@ -718,6 +725,10 @@ function rowToPlatform(row) {
             enabled: row.archonEnabled,
             hostname: row.archonHostname,
             gitRef: row.archonGitRef,
+            // Omitted while off. Validated on read: a stored value is not trusted.
+            ...(row.archonBlueGreen && validateBlueGreen(row.archonBlueGreen, 'archon') === null
+                ? { blueGreen: row.archonBlueGreen }
+                : {}),
         },
         edge: {
             enabled: row.edgeEnabled,
@@ -771,6 +782,7 @@ function platformToRow(platform) {
         archonEnabled: platform.archon.enabled,
         archonHostname: platform.archon.hostname,
         archonGitRef: platform.archon.gitRef,
+        archonBlueGreen: platform.archon.blueGreen ?? null,
         edgeEnabled: platform.edge.enabled,
         edgeHostname: platform.edge.hostname,
         edgeGitRef: platform.edge.gitRef,
@@ -923,3 +935,50 @@ export function createPostgresAppliedVersionsStore(db) {
         },
     };
 }
+/**
+ * `ReleaseStore` (`../release/state.ts`) on Postgres: the recorded `bg.*`
+ * keys come from an org's applied state, or the platform's for the orgId
+ * `platform`; requests are rows in `foundry_release_requests`. Reading leaves
+ * the open rows consumed only when the caller says its run succeeded (`consumeRequests`).
+ */
+export function createPostgresReleaseStore(db) {
+    return {
+        async getScopeIds(orgId) {
+            if (orgId === 'platform') {
+                const [row] = await db
+                    .select({ ids: foundryDeclaredPlatform.serviceIds })
+                    .from(foundryDeclaredPlatform)
+                    .limit(1);
+                return row?.ids ?? {};
+            }
+            const [row] = await db
+                .select({ ids: foundryAppliedState.serviceIds })
+                .from(foundryAppliedState)
+                .where(eq(foundryAppliedState.orgId, orgId))
+                .limit(1);
+            return row?.ids ?? {};
+        },
+        async addRequest({ orgId, entryKey, action, actor }) {
+            await db.insert(foundryReleaseRequests).values({ orgId, entryKey, action, actor });
+        },
+        async openRequests({ orgId, entryKey }) {
+            const rows = await db
+                .select()
+                .from(foundryReleaseRequests)
+                .where(and(eq(foundryReleaseRequests.orgId, orgId), eq(foundryReleaseRequests.entryKey, entryKey), isNull(foundryReleaseRequests.consumedAt)))
+                .orderBy(asc(foundryReleaseRequests.id));
+            return rows.flatMap((row) => {
+                const action = releaseActionSchema.safeParse(row.action);
+                return action.success ? [{ id: row.id, action: action.data, actor: row.actor }] : [];
+            });
+        },
+        async consumeRequests(ids) {
+            if (ids.length === 0)
+                return;
+            await db
+                .update(foundryReleaseRequests)
+                .set({ consumedAt: sql `now()` })
+                .where(and(inArray(foundryReleaseRequests.id, [...ids]), isNull(foundryReleaseRequests.consumedAt)));
+        },
+    };
+}