@wtfalch/foundry 0.72.3 → 0.74.0

package/dist/release/state.js

@@ -27,6 +27,8 @@ export function releaseKeys(entry) {
         stageCopyRetry: `${p}.stagecopyretry`,
         /** JSON `{ at, lines }`: the latest run that refused or blocked something (see {@link formatRefusals}). */
         refused: `${p}.refused`,
+        /** `<request id>|<stage deploys tried>|<release number or empty>`: where the go-live being run stands. */
+        goLive: `${p}.golive`,
     };
 }
 export function formatWeights(w) {
@@ -80,6 +82,11 @@ export const RELEASE_EVENT_KINDS = [
     'hard_fail',
     'fanout_done',
     'fanout_failed',
+    'scheduled',
+    'schedule_cancelled',
+    'released',
+    'go_live_failed',
+    'go_live_refused',
 ];
 /** What `foundry_release_events.payload` holds: a line's fields besides `at` and `kind`. */
 export const releaseEventPayload = z.object({
@@ -205,6 +212,10 @@ function stageDeployOf(value) {
         stageDeploy: { at: m[1], outcome: m[2], detail: m[3] },
     };
 }
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
+/** A tag as a release names it: no `|`, `/` or space, so it fits a key and a `|` separated value. */
+const RELEASE_TAG = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/);
+const BUILTIN_ENTRIES = ['boule', 'agora'];
 const actionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('promote') }),
     z.object({ kind: z.literal('rollback') }),
@@ -219,11 +230,112 @@ const actionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('copy_prod_to_stage') }),
     z.object({ kind: z.literal('undo_stage_copy') }),
     z.object({ kind: z.literal('fanout_retry') }),
+    z.object({
+        kind: z.literal('go_live'),
+        tag: RELEASE_TAG,
+        ref: z.string().regex(COMMIT_SHA),
+        required: z.boolean(),
+        requires: z.array(z.enum(['data-service'])),
+    }),
+    z.object({ kind: z.literal('set_required'), tag: RELEASE_TAG, required: z.boolean() }),
 ]);
-/** C2: ask the runner to apply an action on its next run. Archon audits it. */
+const ISO_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+/** C2: ask the runner to apply an action on its next run. Archon audits it. `notBefore` (a `go_live` only) waits for that time. */
 export async function requestReleaseAction(store, input) {
     releaseKeys(input.entryKey);
-    await store.addRequest({ ...input, action: actionSchema.parse(input.action) });
+    const action = actionSchema.parse(input.action);
+    assertBuiltinAction(input, action);
+    if (action.kind === 'set_required')
+        await assertReleased(store, input, action.tag);
+    if (action.kind === 'go_live' && input.notBefore === undefined) {
+        throw new Error('go_live needs a time');
+    }
+    if (input.notBefore !== undefined)
+        assertSchedule(action, input.notBefore, input.now);
+    const { ownerOrgId: _owner, now: _now, ...rest } = input;
+    await store.addRequest({ ...rest, action });
+}
+function assertBuiltinAction(input, action) {
+    if (action.kind !== 'go_live' && action.kind !== 'set_required')
+        return;
+    if (!BUILTIN_ENTRIES.includes(input.entryKey)) {
+        throw new Error('go_live and set_required belong to the entry boule or agora');
+    }
+    if (input.ownerOrgId === undefined || input.ownerOrgId !== input.orgId) {
+        throw new Error('go_live and set_required belong to the owner org');
+    }
+}
+async function assertReleased(store, input, tag) {
+    const versions = releasedFrom(await store.getScopeIds(input.orgId), input.entryKey);
+    if (!versions.some((v) => v.tag === tag)) {
+        throw new Error('set_required needs a tag that went live; change the go-live instead');
+    }
+}
+function assertSchedule(action, notBefore, now = new Date()) {
+    if (action.kind !== 'go_live')
+        throw new Error('only go_live can wait for a time');
+    if (!ISO_WITH_ZONE.test(notBefore) || Number.isNaN(Date.parse(notBefore))) {
+        throw new Error('invalid release time: use ISO 8601 with Z or an offset');
+    }
+    if (Date.parse(notBefore) <= now.getTime())
+        throw new Error('the release time is in the past');
+}
+/** Moves a queued go-live: cancels `id` and queues `action` at `notBefore` in one transaction. False when `id` is consumed, claimed, cancelled or already due. */
+export async function rescheduleRelease(store, input) {
+    releaseKeys(input.entryKey);
+    const action = actionSchema.parse(input.action);
+    assertBuiltinAction(input, action);
+    assertSchedule(action, input.notBefore, input.now);
+    const { ownerOrgId: _owner, ...rest } = input;
+    return store.rescheduleRequest({ ...rest, action });
+}
+const RELEASED_PREFIX = 'released.';
+/** The applied-state key of one released version: `released.<app>.<release>`. */
+export function releasedKey(app, release) {
+    return `${RELEASED_PREFIX}${app}.${release}`;
+}
+/** `tag|sha|required|requires|at`; `requires` is comma separated. */
+export function formatReleased(v) {
+    return [v.tag, v.sha, String(v.required), v.requires.join(','), v.at].join('|');
+}
+/** Reads one `released.*` value; a damaged value reads as absent. */
+export function parseReleased(app, release, value) {
+    const parts = (value ?? '').split('|');
+    if (parts.length !== 5)
+        return null;
+    const [tag, sha, required, requires, at] = parts;
+    if (!RELEASE_TAG.safeParse(tag).success || !COMMIT_SHA.test(sha))
+        return null;
+    if (required !== 'true' && required !== 'false')
+        return null;
+    if (Number.isNaN(Date.parse(at)))
+        return null;
+    const list = requires === '' ? [] : requires.split(',');
+    if (!list.every((r) => r === 'data-service'))
+        return null;
+    return { app, tag, sha, release, required: required === 'true', requires: list, at };
+}
+/** The released versions of `app` in the owner's applied state, newest first. */
+export function releasedFrom(ids, app) {
+    const prefix = `${RELEASED_PREFIX}${app}.`;
+    const out = [];
+    for (const key of Object.keys(ids)) {
+        if (!key.startsWith(prefix))
+            continue;
+        const n = key.slice(prefix.length);
+        if (!/^[1-9][0-9]{0,11}$/.test(n))
+            continue;
+        const v = parseReleased(app, Number(n), ids[key]);
+        if (v)
+            out.push(v);
+    }
+    return out.sort((a, b) => b.release - a.release);
+}
+/** The tags that went live on the owner's Boule or Agora, newest first. A stage-only build is not in it. */
+export async function readReleasedVersions(store, ownerOrgId, app) {
+    if (!BUILTIN_ENTRIES.includes(app))
+        throw new Error('invalid released app');
+    return releasedFrom(await store.getScopeIds(ownerOrgId), app);
 }
 export { actionSchema as releaseActionSchema };
 export const RELEASE_HISTORY_DEFAULT_LIMIT = 200;

package/dist/release/types.d.ts

@@ -80,8 +80,11 @@ export interface StageCopyState {
     outcome: 'ok' | 'refused' | 'failed';
     detail: string;
 }
-export type ReleaseAction = {
+export type ReleaseAction = 
+/** `redeploy`: set by a go-live only (a request cannot carry it); promotes the idle color to the commit the live color already runs. */
+{
     kind: 'promote';
+    redeploy?: boolean;
 } | {
     kind: 'rollback';
 } | {
@@ -111,12 +114,55 @@ export type ReleaseAction = {
 /** Owner org, entry key `boule` or `agora`: continue the built-in fan-out from the org that failed. */
  | {
     kind: 'fanout_retry';
+}
+/**
+ * Owner org, entry key `boule` or `agora`: put the tag's commit live. The runner deploys stage at `ref` if stage
+ * differs, deploys the idle color with the tag's `APP_*` env, opens it, and records the {@link ReleasedVersion}
+ * once the release completes (one color at 100 %, window closed). Usually queued with a time.
+ */
+ | {
+    kind: 'go_live';
+    tag: string;
+    ref: string;
+    required: boolean;
+    requires: ReleaseRequirement[];
+}
+/** Owner org, entry key `boule` or `agora`: mark a tag that went live required or not. */
+ | {
+    kind: 'set_required';
+    tag: string;
+    required: boolean;
 };
+/** What a tag needs before a company can take it. `data-service`: the company's data service is applied and its data moved. */
+export type ReleaseRequirement = 'data-service';
+/** One tag that went live on the owner's Boule or Agora. Newest first in {@link readReleasedVersions}. */
+export interface ReleasedVersion {
+    app: 'boule' | 'agora';
+    tag: string;
+    /** The 40-hex commit. */
+    sha: string;
+    /** The UTC second the idle color was deployed with it. The same number on every copy of the tag. */
+    release: number;
+    required: boolean;
+    requires: ReleaseRequirement[];
+    /** ISO time the release completed. */
+    at: string;
+}
 export type ReleaseEventKind = 'promote' | 'step' | 'check' | 'pause' | 'resume' | 'step_now' | 'approve' | 'open' | 'rollback' | 'passed' | 'hard_fail'
 /** The built-in fan-out put an org's copy on the live commit (`reason` is the org slug). */
  | 'fanout_done'
 /** The built-in fan-out stopped at an org (`reason` is `<slug>: <fixed text>`). */
- | 'fanout_failed';
+ | 'fanout_failed'
+/** A go-live was queued for a time (`reason` is `<tag> at <ISO time>`). */
+ | 'scheduled'
+/** A queued go-live was cancelled before its time (`reason` is the tag). */
+ | 'schedule_cancelled'
+/** A tag finished going live: one color at 100 % and the window closed (`reason` is the tag). */
+ | 'released'
+/** A step of a go-live did not work and is tried again by the next tick (`reason` is fixed text). */
+ | 'go_live_failed'
+/** A go-live was refused and its request consumed (`reason` is fixed text). */
+ | 'go_live_refused';
 /** C1: one line of a release's history, written by the release run (`foundry_release_events`). */
 export interface ReleaseEvent {
     at: string;

package/dist/store/postgres.js

@@ -1,4 +1,4 @@
-import { and, asc, desc, eq, gte, inArray, isNull, ne, sql } from 'drizzle-orm';
+import { and, asc, desc, eq, gt, gte, inArray, isNotNull, isNull, lte, ne, or, sql, } from 'drizzle-orm';
 import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, normalizeHostingRepos, refuseBuiltinBlueGreen, refuseCustomers, refuseHosting, validateBlueGreen, validateBuyerIdentity, validateCalls, validateDomain, validateDomainClaim, validateMail, validateOwners, validateServices, validateSignIn, validateSite, validateVersionPin, withNewOrgAppsDefault, } from '../org.js';
 import { hostingNames } from '../plan/locked-hostnames.js';
 import { findNameClashes, nameClashMessage } from '../plan/org-names.js';
@@ -1066,6 +1066,46 @@ export function createPostgresAppliedVersionsStore(db) {
         },
     };
 }
+/** A request row, and for a go-live with a time its `scheduled` line, in the caller's transaction. */
+async function insertScheduledRequest(tx, input) {
+    const { orgId, entryKey, action, actor, notBefore } = input;
+    await tx.insert(foundryReleaseRequests).values({
+        orgId,
+        entryKey,
+        action,
+        actor,
+        ...(notBefore ? { notBefore: new Date(notBefore) } : {}),
+    });
+    if (notBefore && action.kind === 'go_live') {
+        await tx.insert(foundryReleaseEvents).values({
+            orgId,
+            entryKey,
+            at: new Date(),
+            kind: 'scheduled',
+            payload: { actor, reason: `${action.tag} at ${new Date(notBefore).toISOString()}` },
+        });
+    }
+}
+/** Consumes a waiting request in one statement and writes `schedule_cancelled` with it. False when it was not open, was claimed, or is already due. */
+async function cancelScheduledRequest(tx, input) {
+    const rows = await tx
+        .update(foundryReleaseRequests)
+        .set({ consumedAt: sql `now()` })
+        .where(and(eq(foundryReleaseRequests.id, input.id), eq(foundryReleaseRequests.orgId, input.orgId), eq(foundryReleaseRequests.entryKey, input.entryKey), isNull(foundryReleaseRequests.consumedAt), isNull(foundryReleaseRequests.claimedAt), gt(foundryReleaseRequests.notBefore, input.now ?? sql `now()`)))
+        .returning({ action: foundryReleaseRequests.action });
+    const row = rows[0];
+    if (!row)
+        return false;
+    const tag = row.action.tag;
+    await tx.insert(foundryReleaseEvents).values({
+        orgId: input.orgId,
+        entryKey: input.entryKey,
+        at: new Date(),
+        kind: 'schedule_cancelled',
+        payload: { actor: input.actor, ...(typeof tag === 'string' ? { reason: tag } : {}) },
+    });
+    return true;
+}
 /**
  * `ReleaseStore` (`../release/state.ts`) on Postgres: the recorded `bg.*`
  * keys come from an org's applied state, or the platform's for the orgId
@@ -1089,18 +1129,69 @@ export function createPostgresReleaseStore(db) {
                 .limit(1);
             return row?.ids ?? {};
         },
-        async addRequest({ orgId, entryKey, action, actor }) {
-            await db.insert(foundryReleaseRequests).values({ orgId, entryKey, action, actor });
+        async addRequest({ orgId, entryKey, action, actor, notBefore }) {
+            await db.transaction(async (tx) => {
+                await insertScheduledRequest(tx, { orgId, entryKey, action, actor, notBefore });
+            });
         },
-        async openRequests({ orgId, entryKey }) {
+        async openRequests({ orgId, entryKey, now }) {
             const rows = await db
                 .select()
                 .from(foundryReleaseRequests)
-                .where(and(eq(foundryReleaseRequests.orgId, orgId), eq(foundryReleaseRequests.entryKey, entryKey), isNull(foundryReleaseRequests.consumedAt)))
+                .where(and(eq(foundryReleaseRequests.orgId, orgId), eq(foundryReleaseRequests.entryKey, entryKey), isNull(foundryReleaseRequests.consumedAt), or(isNull(foundryReleaseRequests.notBefore), lte(foundryReleaseRequests.notBefore, now ?? sql `now()`))))
                 .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 }] : [];
+                return action.success
+                    ? [
+                        {
+                            id: row.id,
+                            action: action.data,
+                            actor: row.actor,
+                            notBefore: row.notBefore ? row.notBefore.toISOString() : null,
+                        },
+                    ]
+                    : [];
+            });
+        },
+        async claimRequests(ids) {
+            if (ids.length === 0)
+                return;
+            await db
+                .update(foundryReleaseRequests)
+                .set({ claimedAt: sql `now()` })
+                .where(and(inArray(foundryReleaseRequests.id, [...ids]), isNull(foundryReleaseRequests.claimedAt)));
+        },
+        async cancelRequest(input) {
+            return db.transaction((tx) => cancelScheduledRequest(tx, input));
+        },
+        async readScheduled({ orgId, entryKey }) {
+            const rows = await db
+                .select()
+                .from(foundryReleaseRequests)
+                .where(and(eq(foundryReleaseRequests.orgId, orgId), eq(foundryReleaseRequests.entryKey, entryKey), isNull(foundryReleaseRequests.consumedAt), isNotNull(foundryReleaseRequests.notBefore)))
+                .orderBy(asc(foundryReleaseRequests.notBefore), asc(foundryReleaseRequests.id));
+            return rows.flatMap((row) => {
+                const action = releaseActionSchema.safeParse(row.action);
+                return action.success && row.notBefore
+                    ? [
+                        {
+                            id: row.id,
+                            action: action.data,
+                            notBefore: row.notBefore.toISOString(),
+                            actor: row.actor,
+                            claimed: row.claimedAt !== null,
+                        },
+                    ]
+                    : [];
+            });
+        },
+        async rescheduleRequest({ id, orgId, entryKey, action, notBefore, actor, now }) {
+            return db.transaction(async (tx) => {
+                if (!(await cancelScheduledRequest(tx, { id, orgId, entryKey, actor, now })))
+                    return false;
+                await insertScheduledRequest(tx, { orgId, entryKey, action, actor, notBefore });
+                return true;
             });
         },
         async consumeRequests(ids) {

package/dist/store/schema.d.ts

@@ -2906,6 +2906,40 @@ export declare const foundryReleaseRequests: import("drizzle-orm/pg-core").PgTab
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        notBefore: import("drizzle-orm/pg-core").PgColumn<{
+            name: "not_before";
+            tableName: "foundry_release_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        claimedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "claimed_at";
+            tableName: "foundry_release_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
     };
     dialect: "pg";
 }>;

package/dist/store/schema.js

@@ -1,4 +1,5 @@
-import { bigint, bigserial, boolean, integer, jsonb, pgTable, text, timestamp, } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+import { bigint, bigserial, boolean, index, integer, jsonb, pgTable, text, timestamp, } from 'drizzle-orm/pg-core';
 /**
  * Mirrors `migrations/0001_declared_org.sql`, which is the source of truth:
  * the SQL carries the CHECKs drizzle-kit does not generate here (this
@@ -271,7 +272,15 @@ export const foundryReleaseRequests = pgTable('foundry_release_requests', {
     actor: text('actor').notNull(),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     consumedAt: timestamp('consumed_at', { withTimezone: true }),
-});
+    /** `migrations/0071_release_request_schedule.sql`: null is due at once. */
+    notBefore: timestamp('not_before', { withTimezone: true }),
+    /** Set when the runner starts a due go-live; a claimed request can no longer be cancelled or moved. */
+    claimedAt: timestamp('claimed_at', { withTimezone: true }),
+}, (t) => [
+    index('foundry_release_requests_scheduled_idx')
+        .on(t.orgId, t.entryKey, t.notBefore)
+        .where(sql `consumed_at is null and not_before is not null`),
+]);
 /** Mirrors `migrations/0069_release_events.sql`: a release's history, appended by the release run and never changed. */
 export const foundryReleaseEvents = pgTable('foundry_release_events', {
     id: bigserial('id', { mode: 'number' }).primaryKey(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.72.3",
+  "version": "0.74.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",