@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/worker-app-migrations.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+export const WORKER_APP_MIGRATION_TIMEOUT_MS = 300_000;
+export const MIGRATIONS_ASSET_NAME = 'migrations.json';
+const MIGRATIONS_MAX_CHARS = 4_000_000;
+const MIGRATIONS_MAX_COUNT = 1000;
+const MIGRATION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+// ---- parsing ---------------------------------------------------------------
+/**
+ * Reads a release's `migrations.json`. `null` text is an absent file: no migrations. A file that is
+ * not a list of `{id, sql}` with unique ids is refused, naming no SQL.
+ */
+export function parseMigrations(text) {
+    if (text === null)
+        return [];
+    if (text.length > MIGRATIONS_MAX_CHARS) {
+        throw new Error(`${MIGRATIONS_ASSET_NAME} is larger than ${MIGRATIONS_MAX_CHARS} characters`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${MIGRATIONS_ASSET_NAME} is not JSON`);
+    }
+    if (!Array.isArray(parsed) || parsed.length > MIGRATIONS_MAX_COUNT) {
+        throw new Error(`${MIGRATIONS_ASSET_NAME} must be a list of at most ${MIGRATIONS_MAX_COUNT} migrations`);
+    }
+    const seen = new Set();
+    return parsed.map((item, index) => {
+        const record = item;
+        if (typeof item !== 'object' ||
+            item === null ||
+            Array.isArray(item) ||
+            Object.keys(item).some((key) => key !== 'id' && key !== 'sql') ||
+            typeof record?.id !== 'string' ||
+            !MIGRATION_ID.test(record.id) ||
+            typeof record.sql !== 'string' ||
+            record.sql.trim() === '') {
+            throw new Error(`${MIGRATIONS_ASSET_NAME} entry ${index} must be { id, sql } with an id of letters, digits, '.', '_' or '-' and a non-empty sql`);
+        }
+        if (seen.has(record.id)) {
+            throw new Error(`${MIGRATIONS_ASSET_NAME} names migration '${record.id}' twice`);
+        }
+        seen.add(record.id);
+        return { id: record.id, sql: record.sql };
+    });
+}
+/**
+ * A present `migrations.json` runs as the database owner, so its bytes must be the ones the
+ * declaration pinned. No file needs no digest; a file with no declared digest, or a different
+ * one, is refused before it is parsed. The message names neither the SQL nor the wanted digest.
+ */
+export function verifyMigrationsDigest(text, declared) {
+    if (text === null)
+        return;
+    if (!declared) {
+        throw new Error(`${MIGRATIONS_ASSET_NAME} is present and workerApp.database.migrationsSha256 is not declared`);
+    }
+    if (createHash('sha256').update(text, 'utf8').digest('hex') !== declared) {
+        throw new Error(`${MIGRATIONS_ASSET_NAME} does not match workerApp.database.migrationsSha256`);
+    }
+}
+/** The URL of `migrations.json` beside the module: the same release, another file. */
+export const migrationsUrl = (artifactUrl) => artifactUrl.slice(0, artifactUrl.lastIndexOf('/') + 1) + MIGRATIONS_ASSET_NAME;
+/**
+ * The migrations the database does not hold, in order. The applied ledger must be the first
+ * migrations of the file: a missing or reordered one is refused (migrations are append-only).
+ */
+export function unappliedDatabaseMigrations(all, applied) {
+    const appliedSet = new Set(applied);
+    const head = new Set(all.slice(0, applied.length).map((m) => m.id));
+    for (const id of appliedSet) {
+        if (!head.has(id)) {
+            throw new Error(`migration '${id}' was applied and is no longer in the same place in ${MIGRATIONS_ASSET_NAME}; migrations are append-only`);
+        }
+    }
+    return all.filter((m) => !appliedSet.has(m.id));
+}
+/** Line endings (CRLF, CR) and trailing whitespace do not make two copies of the same SQL different. */
+const normalisedSql = (sql) => sql
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map((line) => line.replace(/[ \t]+$/, ''))
+    .join('\n')
+    .trim();
+const sqlDigest = (sql) => createHash('sha256').update(normalisedSql(sql), 'utf8').digest('hex');
+/**
+ * The platform migrations still to run, in order, and the ones skipped because the release's own list carries
+ * them (same id, or the same SQL under another id: Candor ships its own copy of the audit migrations).
+ * A platform migration the database's ledger already holds is neither: it ran before. Never applies twice.
+ */
+export function pendingPlatformMigrations(platform, own, applied) {
+    const ownIds = new Set(own.map((m) => m.id));
+    const ownDigests = new Set(own.map((m) => sqlDigest(m.sql)));
+    const done = new Set(applied);
+    const pending = [];
+    const skipped = [];
+    for (const migration of platform) {
+        if (ownIds.has(migration.id))
+            skipped.push({ id: migration.id, why: 'same id' });
+        else if (ownDigests.has(sqlDigest(migration.sql))) {
+            skipped.push({ id: migration.id, why: 'same sql' });
+        }
+        else if (!done.has(migration.id))
+            pending.push(migration);
+    }
+    return { pending, skipped };
+}
+/**
+ * The build's database changes, shared by the platform apply and `@wtfalch/foundry/apps`:
+ * `text` (the release's `migrations.json`, `null` when it has none) is checked against
+ * `want.migrationsSha256`, parsed, the unapplied migrations run in order as the owner (each
+ * recorded by the runner's ledger), then the runtime role is made true. A failed migration
+ * throws; those before it stay applied. Messages start with `at` and name no SQL.
+ */
+export async function runWorkerAppMigrations(runner, owner, text, want, runtime, opts) {
+    const { at, call } = opts;
+    let migrations;
+    try {
+        verifyMigrationsDigest(text, want.migrationsSha256);
+        migrations = parseMigrations(text);
+    }
+    catch (error) {
+        // The message names the file and the entry index, never SQL.
+        throw new Error(`${at}: ${error.message}`);
+    }
+    const applied = await call('read the applied migrations', () => runner.appliedMigrationIds(owner));
+    const platformIds = new Set((opts.platform ?? []).map((m) => m.id));
+    // A release copy (another id) of a platform migration the platform already ran must not run again: the
+    // platform's one stands for it. It is counted as applied, and the log says so.
+    const platformDigests = new Set((opts.platform ?? []).filter((m) => applied.includes(m.id)).map((m) => sqlDigest(m.sql)));
+    const covered = migrations.filter((m) => !platformIds.has(m.id) && !applied.includes(m.id) && platformDigests.has(sqlDigest(m.sql)));
+    for (const m of covered) {
+        opts.log?.(`${at}: release migration '${m.id}' not run, the platform already ran the same SQL (counted as applied)`);
+    }
+    const coveredIds = new Set(covered.map((m) => m.id));
+    const releaseMigrations = migrations.filter((m) => !coveredIds.has(m.id));
+    let pending;
+    try {
+        // The ledger also holds the platform migrations; they are not part of the release's own head.
+        pending = unappliedDatabaseMigrations(releaseMigrations, applied.filter((id) => !platformIds.has(id) || migrations.some((m) => m.id === id)));
+    }
+    catch (error) {
+        throw new Error(`${at}: ${error.message}`);
+    }
+    const platform = pendingPlatformMigrations(opts.platform ?? [], migrations, applied);
+    for (const skip of platform.skipped) {
+        opts.log?.(`${at}: platform migration '${skip.id}' not applied, the release ships it (${skip.why})`);
+    }
+    const done = [...applied, ...covered.map((m) => m.id)];
+    const ran = [];
+    for (const migration of [...platform.pending, ...pending]) {
+        await call(`apply migration '${migration.id}'`, () => runner.applyMigration(owner, migration), opts.migrationTimeoutMs ?? WORKER_APP_MIGRATION_TIMEOUT_MS);
+        done.push(migration.id);
+        ran.push(migration.id);
+        await opts.onApplied?.([...done]);
+    }
+    // After the migrations, so the tables exist for the revokes.
+    await call('ensure the runtime role', () => runner.ensureRuntimeRole({
+        owner,
+        runtime,
+        appendOnly: [...want.appendOnly],
+        grants: [...(want.grants ?? [])],
+    }));
+    return { applied: done, ran, skipped: platform.skipped };
+}

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

@@ -0,0 +1,103 @@
+import { type WorkerAppConfig } from './worker-app-config.js';
+/**
+ * The pure parts of a Worker app deploy, shared by the org planner (`plan/worker-app.ts`, the
+ * platform account through edge) and `@wtfalch/foundry/apps` (a company's own account through
+ * `@wtfalch/providers/cloudflare`): what the upload carries, which Durable Object migrations are
+ * still to run, the container list, the registry rule and the call timeout. No network.
+ */
+/** The compatibility date a Worker gets when its declaration names none. */
+export declare const WORKER_COMPATIBILITY_DATE = "2026-09-12";
+export type WorkerAppBinding = {
+    type: 'durable_object_namespace';
+    name: string;
+    class_name: string;
+} | {
+    type: 'plain_text';
+    name: string;
+    text: string;
+} | {
+    type: 'hyperdrive';
+    name: string;
+    id: string;
+};
+export interface WorkerAppMigrations {
+    /** The tag the script holds now. Absent for a script with none. */
+    oldTag?: string;
+    newTag: string;
+    steps: {
+        newSqliteClasses?: string[];
+        deletedClasses?: string[];
+        renamedClasses?: {
+            from: string;
+            to: string;
+        }[];
+    }[];
+}
+export interface WorkerAppUpload {
+    name: string;
+    artifactUrl: string;
+    artifactSha256: string;
+    compatibilityDate: string;
+    compatibilityFlags: string[];
+    /** All of them: a redeploy replaces the list. Secrets survive a redeploy. */
+    bindings: WorkerAppBinding[];
+    /** Only the migrations not yet applied; absent when there are none. */
+    migrations?: WorkerAppMigrations;
+    /** Durable Object classes the upload marks container-enabled; absent when the entry declares no container. */
+    containers?: string[];
+    /** Workers Logs: always on, every request sampled. The adapter sends it as the upload metadata's `observability`. */
+    observability: {
+        enabled: true;
+        head_sampling_rate: 1;
+    };
+}
+export interface WorkerAppContainer {
+    className: string;
+    /** `<repository>@sha256:<digest>`. */
+    image: string;
+    instanceType: string;
+    maxInstances: number;
+}
+/** What a Worker app's declaration says the script is, sorted, before names, hosts and env. */
+export interface WorkerAppShape {
+    artifactUrl: string;
+    artifactSha256: string;
+    compatibilityDate: string;
+    compatibilityFlags: string[];
+    classes: {
+        binding: string;
+        className: string;
+    }[];
+    migrations: WorkerAppConfig['durableObjects']['migrations'];
+    containers: WorkerAppContainer[];
+}
+export declare function workerAppShape(app: WorkerAppConfig): WorkerAppShape;
+/** The registry prefix a container image of an account must start with. */
+export declare const workerAppRegistryPrefix: (accountId: string) => string;
+/**
+ * The first declared container whose image is not in `accountId`'s registry (or holds a `..`
+ * segment), or `undefined` when every one is. With no account id every container is stray.
+ */
+export declare function strayContainerImage(app: Pick<WorkerAppConfig, 'containers'>, accountId: string | undefined): NonNullable<WorkerAppConfig['containers']>[number] | undefined;
+/**
+ * The Durable Object migrations the live script does not hold yet, from the tag it holds. A live
+ * tag that is not in the declared list is refused: migrations are append-only.
+ */
+export declare function pendingWorkerAppMigrations(declared: WorkerAppConfig['durableObjects']['migrations'], liveTag: string | undefined): {
+    ok: true;
+    migrations?: WorkerAppMigrations;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The upload of `shape` as script `name`: Durable Object classes, then plain vars, then Hyperdrive. */
+export declare function workerAppUpload(name: string, shape: Omit<WorkerAppShape, 'migrations'>, vars: readonly (readonly [string, string])[], migrations: WorkerAppMigrations | undefined, hyperdriveId: string | undefined): WorkerAppUpload;
+/** The record a Worker route needs on a zone: Cloudflare's documented dummy, proxied. */
+export declare const WORKER_APP_DNS_RECORD: {
+    readonly type: "AAAA";
+    readonly content: "100::";
+};
+/**
+ * Races `task` against a timer. An error names the call and edge's error code, never the cause.
+ */
+export declare function withCallTimeout<T>(ms: number, label: string, task: () => Promise<T>): Promise<T>;

package/dist/worker-app-upload.js

@@ -0,0 +1,128 @@
+import { WORKER_APP_HYPERDRIVE_BINDING } from './worker-app-config.js';
+/**
+ * The pure parts of a Worker app deploy, shared by the org planner (`plan/worker-app.ts`, the
+ * platform account through edge) and `@wtfalch/foundry/apps` (a company's own account through
+ * `@wtfalch/providers/cloudflare`): what the upload carries, which Durable Object migrations are
+ * still to run, the container list, the registry rule and the call timeout. No network.
+ */
+/** The compatibility date a Worker gets when its declaration names none. */
+export const WORKER_COMPATIBILITY_DATE = '2026-09-12';
+export function workerAppShape(app) {
+    return {
+        artifactUrl: app.artifactUrl,
+        artifactSha256: app.artifactSha256,
+        compatibilityDate: app.compatibilityDate ?? WORKER_COMPATIBILITY_DATE,
+        compatibilityFlags: [...(app.compatibilityFlags ?? [])].sort(),
+        classes: Object.entries(app.durableObjects.classes)
+            .map(([binding, className]) => ({ binding, className }))
+            .sort((a, b) => a.binding.localeCompare(b.binding)),
+        migrations: app.durableObjects.migrations,
+        containers: (app.containers ?? [])
+            .map((c) => ({
+            className: c.className,
+            image: `${c.image.repository}@${c.image.digest}`,
+            instanceType: c.instanceType,
+            maxInstances: c.maxInstances,
+        }))
+            .sort((a, b) => a.className.localeCompare(b.className)),
+    };
+}
+/** The registry prefix a container image of an account must start with. */
+export const workerAppRegistryPrefix = (accountId) => `registry.cloudflare.com/${accountId}/`;
+/**
+ * The first declared container whose image is not in `accountId`'s registry (or holds a `..`
+ * segment), or `undefined` when every one is. With no account id every container is stray.
+ */
+export function strayContainerImage(app, accountId) {
+    return (app.containers ?? []).find((c) => accountId === undefined ||
+        !c.image.repository.startsWith(workerAppRegistryPrefix(accountId)) ||
+        c.image.repository.split('/').some((part) => /^\.+$/.test(part)));
+}
+/**
+ * The Durable Object migrations the live script does not hold yet, from the tag it holds. A live
+ * tag that is not in the declared list is refused: migrations are append-only.
+ */
+export function pendingWorkerAppMigrations(declared, liveTag) {
+    let appliedCount = 0;
+    if (liveTag !== undefined) {
+        const index = declared.findIndex((m) => m.tag === liveTag);
+        if (index < 0) {
+            return {
+                ok: false,
+                reason: `the live Worker holds migration '${liveTag}', which is not in the declared list; migrations are append-only and foundry will not guess`,
+            };
+        }
+        appliedCount = index + 1;
+    }
+    const pending = declared.slice(appliedCount);
+    if (pending.length === 0)
+        return { ok: true };
+    return {
+        ok: true,
+        migrations: {
+            ...(liveTag !== undefined ? { oldTag: liveTag } : {}),
+            newTag: pending[pending.length - 1]?.tag,
+            steps: pending.map((m) => ({
+                ...(m.newSqliteClasses ? { newSqliteClasses: m.newSqliteClasses } : {}),
+                ...(m.deletedClasses ? { deletedClasses: m.deletedClasses } : {}),
+                ...(m.renamedClasses ? { renamedClasses: m.renamedClasses } : {}),
+            })),
+        },
+    };
+}
+/** The upload of `shape` as script `name`: Durable Object classes, then plain vars, then Hyperdrive. */
+export function workerAppUpload(name, shape, vars, migrations, hyperdriveId) {
+    return {
+        name,
+        artifactUrl: shape.artifactUrl,
+        artifactSha256: shape.artifactSha256,
+        compatibilityDate: shape.compatibilityDate,
+        compatibilityFlags: shape.compatibilityFlags,
+        bindings: [
+            ...shape.classes.map((c) => ({
+                type: 'durable_object_namespace',
+                name: c.binding,
+                class_name: c.className,
+            })),
+            ...vars.map(([varName, text]) => ({ type: 'plain_text', name: varName, text })),
+            ...(hyperdriveId
+                ? [{ type: 'hyperdrive', name: WORKER_APP_HYPERDRIVE_BINDING, id: hyperdriveId }]
+                : []),
+        ],
+        observability: { enabled: true, head_sampling_rate: 1 },
+        ...(migrations ? { migrations } : {}),
+        ...(shape.containers.length > 0
+            ? { containers: shape.containers.map((c) => c.className) }
+            : {}),
+    };
+}
+/** The record a Worker route needs on a zone: Cloudflare's documented dummy, proxied. */
+export const WORKER_APP_DNS_RECORD = {
+    type: 'AAAA',
+    content: '100::',
+};
+/**
+ * Races `task` against a timer. An error names the call and edge's error code, never the cause.
+ */
+export function withCallTimeout(ms, label, task) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label}: no answer within ${ms} ms`)), ms);
+        task().then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            // The cause is dropped: a provider error can echo a request body. The
+            // HTTP status stays, because callers tell "already gone" by it. So does
+            // edge's error code (a fixed lower-case enum, never a secret), to say why.
+            const { status, code } = (error ?? {});
+            const known = typeof code === 'string' && /^[a-z_]{1,40}$/.test(code) ? code : undefined;
+            const failure = new Error(known ? `${label} failed (${known})` : `${label} failed`);
+            if (typeof status === 'number')
+                failure.status = status;
+            if (known)
+                failure.code = known;
+            reject(failure);
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -15,6 +15,22 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./modules": {
+      "types": "./dist/modules/index.d.ts",
+      "default": "./dist/modules/index.js"
+    },
+    "./catalogue": {
+      "types": "./dist/catalogue/index.d.ts",
+      "default": "./dist/catalogue/index.js"
+    },
+    "./audit": {
+      "types": "./dist/audit/index.d.ts",
+      "default": "./dist/audit/index.js"
+    },
+    "./apps": {
+      "types": "./dist/apps/index.d.ts",
+      "default": "./dist/apps/index.js"
+    },
     "./migrations-dir": {
       "types": "./dist/migrations-dir.d.ts",
       "default": "./dist/migrations-dir.js"
@@ -43,8 +59,9 @@
   },
   "dependencies": {
     "@wtfalch/audit": "0.6.0",
+    "@wtfalch/audit-sealing": "npm:@wtfalch/audit@0.14.0",
     "@wtfalch/auth": "^0.26.0",
-    "@wtfalch/edge": "0.15.1",
+    "@wtfalch/edge": "0.21.0",
     "@wtfalch/email": "^0.20.0",
     "@wtfalch/providers": "0.12.0",
     "ssh2": "1.17.0",