@wtfalch/foundry 0.65.0 → 0.66.0

package/dist/release/types.d.ts

@@ -27,6 +27,12 @@ export type WindowState = {
  | {
     kind: 'staff';
     since: string;
+}
+/** A person held the step with `pause`. `since` is when the step began; `resume` returns to `step` with it. */
+ | {
+    kind: 'paused';
+    percent: number;
+    since: string;
 };
 export interface ReleaseSignal {
     requests: number;
@@ -88,6 +94,12 @@ export type ReleaseAction = {
     kind: 'approve_step';
 } | {
     kind: 'open';
+} | {
+    kind: 'pause';
+} | {
+    kind: 'resume';
+} | {
+    kind: 'step_now';
 } | {
     kind: 'deploy_stage';
     ref: string;
@@ -96,6 +108,38 @@ export type ReleaseAction = {
 } | {
     kind: 'undo_stage_copy';
 };
+export type ReleaseEventKind = 'promote' | 'step' | 'check' | 'pause' | 'resume' | 'step_now' | 'approve' | 'open' | 'rollback' | 'passed' | 'hard_fail';
+/** C1: one line of a release's history, written by the release run (`foundry_release_events`). */
+export interface ReleaseEvent {
+    at: string;
+    kind: ReleaseEventKind;
+    percent?: number;
+    /** Who asked, when a person did. */
+    actor?: string;
+    reason?: string;
+    release?: {
+        from: string;
+        to: string;
+    };
+    signal?: ReleaseSignal;
+}
+/** C2: what reporting counts for one color in one bucket. */
+export interface ReleaseSeriesColor {
+    requests: number;
+    errors: number;
+    slow: number;
+    durationMsSum: number;
+    signIns: number;
+    signInFailures: number;
+}
+/** C2: reporting's `GET /api/reporting/release-series` body. */
+export interface ReleaseSeries {
+    bucketMinutes: number;
+    buckets: Array<{
+        start: string;
+        colors: Record<Color, ReleaseSeriesColor>;
+    }>;
+}
 /** The requests that run a stage copy. They are handled by the tick's second phase, never by an apply. */
 export declare const isStageCopyAction: (action: ReleaseAction) => boolean;
 export declare const COLORS: readonly Color[];

package/dist/store/postgres.js

@@ -1,13 +1,13 @@
-import { and, asc, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm';
+import { and, asc, desc, eq, gte, inArray, isNull, ne, 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, } 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 { releaseActionSchema, releaseEventKind, releaseEventPayload, } 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, foundryReleaseRequests, foundryRequestedChanges, } from './schema.js';
+import { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryDeclaredPlatform, foundryMutationLeases, foundryReleaseEvents, foundryReleaseRequests, foundryRequestedChanges, } from './schema.js';
 const UNIQUE_VIOLATION = '23505';
 /**
  * #441: runs `write`, and with a `fence` only if its token is still the
@@ -1100,5 +1100,31 @@ export function createPostgresReleaseStore(db) {
                 .set({ consumedAt: sql `now()` })
                 .where(and(inArray(foundryReleaseRequests.id, [...ids]), isNull(foundryReleaseRequests.consumedAt)));
         },
+        async appendEvents({ orgId, entryKey, events }) {
+            if (events.length === 0)
+                return;
+            await db.insert(foundryReleaseEvents).values(events.map(({ at, kind, ...payload }) => ({
+                orgId,
+                entryKey,
+                at: new Date(at),
+                kind,
+                payload,
+            })));
+        },
+        async readEvents({ orgId, entryKey, since, limit }) {
+            const rows = await db
+                .select()
+                .from(foundryReleaseEvents)
+                .where(and(eq(foundryReleaseEvents.orgId, orgId), eq(foundryReleaseEvents.entryKey, entryKey), ...(since ? [gte(foundryReleaseEvents.at, new Date(since))] : [])))
+                .orderBy(desc(foundryReleaseEvents.at), desc(foundryReleaseEvents.id))
+                .limit(limit);
+            return rows.flatMap((row) => {
+                const kind = releaseEventKind.safeParse(row.kind);
+                const payload = releaseEventPayload.safeParse(row.payload);
+                return kind.success && payload.success
+                    ? [{ at: row.at.toISOString(), kind: kind.data, ...payload.data }]
+                    : [];
+            });
+        },
     };
 }

package/dist/store/schema.d.ts

@@ -2854,6 +2854,118 @@ export declare const foundryReleaseRequests: import("drizzle-orm/pg-core").PgTab
     };
     dialect: "pg";
 }>;
+/** Mirrors `migrations/0069_release_events.sql`: a release's history, appended by the release run and never changed. */
+export declare const foundryReleaseEvents: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "foundry_release_events";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "foundry_release_events";
+            dataType: "number";
+            columnType: "PgBigSerial53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        orgId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "org_id";
+            tableName: "foundry_release_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        entryKey: import("drizzle-orm/pg-core").PgColumn<{
+            name: "entry_key";
+            tableName: "foundry_release_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        at: import("drizzle-orm/pg-core").PgColumn<{
+            name: "at";
+            tableName: "foundry_release_events";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        kind: import("drizzle-orm/pg-core").PgColumn<{
+            name: "kind";
+            tableName: "foundry_release_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        payload: import("drizzle-orm/pg-core").PgColumn<{
+            name: "payload";
+            tableName: "foundry_release_events";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+    };
+    dialect: "pg";
+}>;
 export type DeclaredOrgRow = typeof declaredOrgs.$inferSelect;
 export type NewDeclaredOrgRow = typeof declaredOrgs.$inferInsert;
 export type AppliedStateRow = typeof foundryAppliedState.$inferSelect;

package/dist/store/schema.js

@@ -268,3 +268,12 @@ export const foundryReleaseRequests = pgTable('foundry_release_requests', {
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
     consumedAt: timestamp('consumed_at', { withTimezone: true }),
 });
+/** 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(),
+    orgId: text('org_id').notNull(),
+    entryKey: text('entry_key').notNull(),
+    at: timestamp('at', { withTimezone: true }).notNull(),
+    kind: text('kind').notNull(),
+    payload: jsonb('payload').notNull().$type().default({}),
+});

package/dist/worker-app-config.d.ts

@@ -43,12 +43,28 @@ export interface WorkerAppConfig {
      * `KEYS_CREDENTIAL`, at most one) delivers a keys custody Worker credential
      * for the app's own host id (`workerAppHostId`), with `KEYS_URL` as a var.
      * `keys` (an issued API key) is refused: custody does not accept one.
+     * `heldSecret` is a value the company supplies (a webhook address, a vendor
+     * key): it is read from the held-key store at `heldEnvRef(orgId, entryKey, name)`,
+     * the ref a `heldSecret` env of a Coolify entry uses, and set on the Worker
+     * only while a value is held. With no value the Worker deploys without the
+     * secret and the plan says so.
      */
     secrets?: Record<string, {
         from: 'generated';
     } | {
         from: 'keysCustody';
+    } | {
+        from: 'heldSecret';
     }>;
+    /**
+     * Cloudflare cron triggers: at most three standard five-field cron
+     * expressions (minute hour day-of-month month day-of-week, UTC), each
+     * once. The Worker's `scheduled` handler receives them. Empty or absent
+     * clears the triggers.
+     */
+    triggers?: {
+        crons?: string[];
+    };
     /** True delivers the entry's sign-in env as Worker vars. Needs `uses.auth`. */
     authEnv?: boolean;
     /**
@@ -64,9 +80,14 @@ export interface WorkerAppConfig {
      * functions the runtime role may execute, as `name(type, ...)` or
      * `schema.name(type, ...)`: the security definer functions a migration
      * revoked from public, such as `@wtfalch/audit`'s ledger functions.
+     * `noDelete` names tables the runtime role may select, insert into and
+     * update but never delete from or truncate (a looser `appendOnly`: a table
+     * in both lists is refused). The app removes rows from them through a
+     * `grants` function, as a retention job does.
      */
     database?: {
         appendOnly?: string[];
+        noDelete?: string[];
         grants?: string[];
         migrationsSha256?: string;
     };
@@ -80,7 +101,7 @@ export declare const WORKER_APP_COMPATIBILITY_FLAGS: ReadonlySet<string>;
 export declare const WORKER_APP_INSTANCE_TYPES: ReadonlySet<string>;
 /** The most instances one container class may scale to. */
 export declare const WORKER_APP_MAX_INSTANCES = 100;
-export { WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
+export { WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_CRONS_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_NO_DELETE_MAX, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
 export declare const WORKER_APP_KEYS_URL_VAR = "KEYS_URL";
 /** True when the entry needs the org's Postgres database: a Coolify app with `database`, or a Worker app with `workerApp.database`. */
 export declare const entryHasDatabase: (entry: {

package/dist/worker-app-config.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { WORKER_APP_ENV_NAME as ENV_NAME, WORKER_APP_FUNCTION_SIGNATURE as FUNCTION_SIGNATURE, SECRET_LIKE_NAME as SECRET_NAME, WORKER_APP_TABLE_NAME as TABLE_NAME, WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
+import { WORKER_APP_ENV_NAME as ENV_NAME, WORKER_APP_FUNCTION_SIGNATURE as FUNCTION_SIGNATURE, SECRET_LIKE_NAME as SECRET_NAME, WORKER_APP_TABLE_NAME as TABLE_NAME, WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_CRONS_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_NO_DELETE_MAX, WORKER_APP_RESERVED_NAMES, workerAppCronProblem, } from './entry-rules.js';
 import { validateSlug } from './slug.js';
 /** The compatibility flags a Worker app may ask for. */
 export const WORKER_APP_COMPATIBILITY_FLAGS = new Set(['nodejs_compat']);
@@ -13,7 +13,7 @@ export const WORKER_APP_INSTANCE_TYPES = new Set([
 ]);
 /** The most instances one container class may scale to. */
 export const WORKER_APP_MAX_INSTANCES = 100;
-export { WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
+export { WORKER_APP_APPEND_ONLY_MAX, WORKER_APP_CRONS_MAX, WORKER_APP_GRANTS_MAX, WORKER_APP_KEYS_SECRET, WORKER_APP_NO_DELETE_MAX, WORKER_APP_RESERVED_NAMES, } from './entry-rules.js';
 export const WORKER_APP_KEYS_URL_VAR = 'KEYS_URL';
 /** True when the entry needs the org's Postgres database: a Coolify app with `database`, or a Worker app with `workerApp.database`. */
 export const entryHasDatabase = (entry) => entry.database || Boolean(entry.workerApp?.database);
@@ -52,6 +52,9 @@ const MIGRATION_TAG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const IMAGE_REPOSITORY = /^[a-z0-9]+([._-][a-z0-9]+)*(:[0-9]+)?(\/[a-z0-9]+([._-][a-z0-9]+)*)+$/;
 const COMPAT_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const VAR_MAX_LENGTH = 1000;
+/** `heldEnvRef` in `org.ts`: the ref is at most 128 characters and 52 of them are fixed. */
+const HELD_REF_MAX = 128;
+const HELD_REF_FIXED = 52;
 /**
  * Checks an artifact reference: an https URL with no userinfo, query or
  * fragment (those end up verbatim in recorded scope ids) and a lowercase hex
@@ -278,6 +281,16 @@ export function validateEntryWorkerApp(entry, hosting, names) {
             return invalid;
         if (source?.from === 'generated')
             continue;
+        if (source?.from === 'heldSecret') {
+            if (name === WORKER_APP_KEYS_SECRET) {
+                return `${at} secret '${name}' is the custody credential: declare it as keysCustody, not heldSecret`;
+            }
+            // `heldEnvRef`'s own limit (org.ts restates the ref: this file cannot import it).
+            if (HELD_REF_FIXED + entry.key.length + name.length > HELD_REF_MAX) {
+                return `${at} secret '${name}' heldSecret: the name and the entry key are too long to hold a value under (at most ${HELD_REF_MAX - HELD_REF_FIXED} characters together)`;
+            }
+            continue;
+        }
         if (source?.from !== 'keysCustody')
             return `${at} secret '${name}' has an unknown source`;
         keysSecrets++;
@@ -312,6 +325,9 @@ export function validateEntryWorkerApp(entry, hosting, names) {
             // Not a URL: nothing to check.
         }
     }
+    const invalidTriggers = validateWorkerAppTriggers(at, app);
+    if (invalidTriggers)
+        return invalidTriggers;
     const invalidDatabase = validateWorkerAppDatabase(at, app);
     if (invalidDatabase)
         return invalidDatabase;
@@ -332,11 +348,11 @@ function validateWorkerAppDatabase(at, app) {
     if (database === undefined)
         return null;
     if (typeof database !== 'object' || database === null || Array.isArray(database)) {
-        return `${at} database must be an object: { appendOnly?: string[]; grants?: string[]; migrationsSha256?: string }`;
+        return `${at} database must be an object: { appendOnly?: string[]; noDelete?: string[]; grants?: string[]; migrationsSha256?: string }`;
     }
-    const unknown = Object.keys(database).find((key) => key !== 'appendOnly' && key !== 'grants' && key !== 'migrationsSha256');
+    const unknown = Object.keys(database).find((key) => key !== 'appendOnly' && key !== 'noDelete' && key !== 'grants' && key !== 'migrationsSha256');
     if (unknown) {
-        return `${at} database.${unknown} is not a setting: only appendOnly, grants and migrationsSha256`;
+        return `${at} database.${unknown} is not a setting: only appendOnly, noDelete, grants and migrationsSha256`;
     }
     const grants = database.grants;
     if (grants !== undefined) {
@@ -357,21 +373,63 @@ function validateWorkerAppDatabase(at, app) {
     if (sha !== undefined && (typeof sha !== 'string' || !SHA256_HEX.test(sha))) {
         return `${at} database.migrationsSha256 must be 64 lowercase hex characters`;
     }
-    const appendOnly = database.appendOnly;
-    if (appendOnly === undefined)
-        return null;
-    if (!Array.isArray(appendOnly) || appendOnly.length > WORKER_APP_APPEND_ONLY_MAX) {
-        return `${at} database.appendOnly must be a list of at most ${WORKER_APP_APPEND_ONLY_MAX} table names`;
+    const appendOnly = tableList(at, 'appendOnly', WORKER_APP_APPEND_ONLY_MAX, database);
+    if (typeof appendOnly === 'string')
+        return appendOnly;
+    const noDelete = tableList(at, 'noDelete', WORKER_APP_NO_DELETE_MAX, database);
+    if (typeof noDelete === 'string')
+        return noDelete;
+    const both = noDelete.find((table) => appendOnly.includes(table));
+    if (both) {
+        return `${at} database.noDelete names '${both}', which database.appendOnly already covers (append-only is stricter): name it in one list`;
+    }
+    return null;
+}
+/** A table list (`appendOnly` or `noDelete`) of `database`: its names, or the refusal. */
+function tableList(at, key, max, database) {
+    const list = database[key];
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list) || list.length > max) {
+        return `${at} database.${key} must be a list of at most ${max} table names`;
     }
     const seen = new Set();
-    for (const table of appendOnly) {
+    for (const table of list) {
         if (typeof table !== 'string' || !TABLE_NAME.test(table)) {
-            return `${at} database.appendOnly names '${String(table).slice(0, 80)}', which is not a table name (letters, digits and '_', optionally schema.table)`;
+            return `${at} database.${key} names '${String(table).slice(0, 80)}', which is not a table name (letters, digits and '_', optionally schema.table)`;
         }
         if (seen.has(table))
-            return `${at} database.appendOnly names '${table}' twice`;
+            return `${at} database.${key} names '${table}' twice`;
         seen.add(table);
     }
+    return [...seen];
+}
+/** `triggers`: only `crons`, at most {@link WORKER_APP_CRONS_MAX}, each a standard five-field cron, each once. */
+function validateWorkerAppTriggers(at, app) {
+    const triggers = app.triggers;
+    if (triggers === undefined)
+        return null;
+    if (typeof triggers !== 'object' || triggers === null || Array.isArray(triggers)) {
+        return `${at} triggers must be an object: { crons?: string[] }`;
+    }
+    const unknown = Object.keys(triggers).find((key) => key !== 'crons');
+    if (unknown)
+        return `${at} triggers.${unknown} is not a trigger: only crons`;
+    const crons = triggers.crons;
+    if (crons === undefined)
+        return null;
+    if (!Array.isArray(crons) || crons.length > WORKER_APP_CRONS_MAX) {
+        return `${at} triggers.crons must be a list of at most ${WORKER_APP_CRONS_MAX} cron expressions (Cloudflare's limit for one Worker)`;
+    }
+    const seen = new Set();
+    for (const cron of crons) {
+        const problem = workerAppCronProblem(cron);
+        if (problem)
+            return `${at} triggers.crons: ${problem}`;
+        if (seen.has(cron))
+            return `${at} triggers.crons names '${cron}' twice`;
+        seen.add(cron);
+    }
     return null;
 }
 function validateDurableObjects(at, app, claim) {

package/dist/worker-app-migrations.d.ts

@@ -20,8 +20,10 @@ export interface WorkerAppMigrationRunner<O> {
     applyMigration(owner: O, migration: DatabaseMigration): Promise<void>;
     /**
      * Creates or updates the `runtime.user` role with `runtime.password`, grants it DML on the
-     * tables, revokes UPDATE, DELETE and TRUNCATE from it on each `appendOnly` table, and grants
-     * it EXECUTE on each `grants` function.
+     * tables, revokes UPDATE, DELETE and TRUNCATE from it on each `appendOnly` table, revokes
+     * DELETE and TRUNCATE on each `noDelete` table (`@wtfalch/db`'s `ensureRuntimeRole` takes the
+     * same two lists by those names), and grants it EXECUTE on each `grants` function. A runner
+     * that drops `noDelete` leaves the role able to delete: pass it on.
      */
     ensureRuntimeRole(input: {
         owner: O;
@@ -30,6 +32,7 @@ export interface WorkerAppMigrationRunner<O> {
             password: string;
         };
         appendOnly: string[];
+        noDelete: string[];
         grants: string[];
     }): Promise<void>;
 }
@@ -80,6 +83,7 @@ export declare function pendingPlatformMigrations(platform: readonly PlatformMig
  */
 export declare function runWorkerAppMigrations<O>(runner: WorkerAppMigrationRunner<O>, owner: O, text: string | null, want: {
     appendOnly: readonly string[];
+    noDelete?: readonly string[];
     grants?: readonly string[];
     migrationsSha256?: string;
 }, runtime: {

package/dist/worker-app-migrations.js

@@ -160,6 +160,7 @@ export async function runWorkerAppMigrations(runner, owner, text, want, runtime,
         owner,
         runtime,
         appendOnly: [...want.appendOnly],
+        noDelete: [...(want.noDelete ?? [])],
         grants: [...(want.grants ?? [])],
     }));
     return { applied: done, ran, skipped: platform.skipped };

package/package.json

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