@wtfalch/foundry 0.43.0 → 0.44.1

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

@@ -0,0 +1,320 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import { type WorkerAppConfig } from '../worker-app-config.js';
+import type { DraftStep, StepAction } from './diff.js';
+import type { DnsPort } from './edge-dns.js';
+import type { ZonePort } from './edge-zones.js';
+import type { StepExecutionContext } from './plan-apply.js';
+import { type WorkerAppDatabaseDeps } from './worker-app-database.js';
+/**
+ * ADR 0002: a hosting entry that declares `workerApp` runs as one Cloudflare
+ * Worker with Durable Objects and Containers on the platform account. One step
+ * per entry, `cloudflare:worker-app`, keyed `<orgId>:<entryKey>`; its resource
+ * id is the script name. The module is fetched, checked and uploaded behind
+ * {@link WorkerAppPort}; foundry builds and checks out nothing.
+ *
+ * Order on apply, so a failure at any point leaves a state the next apply
+ * repairs and the Worker is never routed before it can serve:
+ * trace -> upload (bindings, vars, only the unapplied migrations) -> secrets ->
+ * containers -> DNS record (own domain only) -> route -> applied marker.
+ * The marker is written last, so a run that fails anywhere is planned again.
+ */
+export declare const workerAppAppliedScopeKey: (entryKey: string) => string;
+/** The script name, recorded and persisted before the upload, so a crash mid-deploy leaves a trail to it. */
+export declare const workerAppUploadedScopeKey: (entryKey: string) => string;
+/** The migration tags applied, as a JSON list, recorded after the upload that carried them. */
+export declare const workerAppTagsScopeKey: (entryKey: string) => string;
+/** Secret name -> delivered version, as JSON. Versions only, never a value. */
+export declare const workerAppSecretsScopeKey: (entryKey: string) => string;
+/** The delivered custody credential, as `{hostId, credentialId, expiresAt}` JSON. Never the credential. */
+export declare const workerAppKeysScopeKey: (entryKey: string) => string;
+/** Class name -> `{id, image, instanceType, maxInstances}` of its container application, as JSON. */
+export declare const workerAppContainersScopeKey: (entryKey: string) => string;
+/** The route: `{zoneId, apex, pattern, id}` as JSON. */
+export declare const workerAppRouteScopeKey: (entryKey: string) => string;
+/** A route about to be created, same shape without `id`; recorded and persisted before `createRoute`. */
+export declare const workerAppRoutePendingScopeKey: (entryKey: string) => string;
+/** The proxied record in the org's zone: `{zone, id, name}` as JSON. */
+export declare const workerAppDnsScopeKey: (entryKey: string) => string;
+/** The script name retired, once a retire step is done. */
+export declare const workerAppRetiredScopeKey: (entryKey: string) => string;
+/** Every per-entry scope key that marks something deployed, half deployed or handled. */
+export declare const workerAppTraceScopeKeys: (entryKey: string) => string[];
+/** The recorded id of the step: the script name. */
+export declare const workerAppResourceKey: (stepKey: string) => string;
+export declare const WORKER_APP_ORG_HASH_LENGTH = 8;
+/** `${8 hex of the org id's sha256}-${entry key}-app`. */
+export declare const workerAppName: (org: DeclaredOrg, entry: HostingEntry) => string;
+/** The zone that holds the routes of an org with no domain of its own. */
+export declare const WORKER_APP_OIKOS_ZONE = "oikos.host";
+/** The record a Worker route needs on the org's own zone: Cloudflare's documented dummy, proxied. */
+export declare const WORKER_APP_DNS_RECORD: {
+    readonly type: "AAAA";
+    readonly content: "100::";
+};
+/** True once the Worker app holds the broker key (`authEnv` delivered it). */
+export declare const brokerKeyDelivered: (recorded: Readonly<Record<string, string>>, entryKey: string) => boolean;
+/**
+ * The broker key of a Worker app with `authEnv`, read from the held-key store
+ * (it was put there before it was delivered to the Worker). Throws, naming no
+ * value, when it is missing or shorter than the broker accepts.
+ */
+export declare function heldBrokerKey(heldKeys: {
+    resolve(ref: string): Promise<string | null | undefined>;
+} | undefined, org: DeclaredOrg, entryKey: string): Promise<string>;
+/** The foundry-written secret the broker entry shares with the app when `authEnv` is on. */
+export declare const WORKER_APP_AUTH_KEY_SECRET = "AUTH_APP_KEY";
+/**
+ * Where foundry keeps a generated secret (the held-key store), so the value
+ * is minted once and delivered again unchanged after a crash. The entry key
+ * and name are hashed: a held ref is at most 128 characters.
+ */
+export declare const workerAppSecretRef: (orgId: string, entryKey: string, name: string) => string;
+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;
+}
+export interface WorkerAppContainer {
+    className: string;
+    /** `<repository>@sha256:<digest>`. */
+    image: string;
+    instanceType: string;
+    maxInstances: number;
+}
+/**
+ * The Cloudflare calls a Worker app needs. Edge 0.13.0 has none of the Durable
+ * Object, migration or container calls, so no adapter ships with this port yet
+ * (`createEdgeWorkers` cannot satisfy it); a host without one gets every Worker
+ * app reported blocked. Every method is idempotent.
+ */
+export interface WorkerAppPort {
+    scriptExists(name: string): Promise<boolean>;
+    /** The script name bound to `pattern` in `zoneId`, or `undefined`. */
+    findRoute(zoneId: string, pattern: string): Promise<{
+        id: string;
+        script?: string;
+    } | undefined>;
+    createRoute(zoneId: string, pattern: string, script?: string): Promise<{
+        id: string;
+    }>;
+    /** A no-op when the route is gone. */
+    deleteRoute(zoneId: string, routeId: string): Promise<void>;
+    /** A no-op when the script is gone. Deleting it removes its secrets. */
+    deleteScript(name: string): Promise<void>;
+    /** Fetches the module, verifies the sha256 and uploads it with the metadata. */
+    uploadWorkerApp(input: WorkerAppUpload): Promise<void>;
+    /** The migration tag the live script holds, or `undefined` for none or no script. */
+    liveMigrationTag(name: string): Promise<string | undefined>;
+    /** A secret whose `version` the script already holds is skipped. */
+    setSecrets(name: string, secrets: readonly {
+        name: string;
+        value: string;
+        version: string;
+    }[]): Promise<void>;
+    /** A no-op when the secret is gone. */
+    deleteSecret(name: string, secretName: string): Promise<void>;
+    /** Creates or updates the container application of `className` on the script; returns its id. */
+    ensureContainerApplication(input: WorkerAppContainer & {
+        scriptName: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** A no-op when it is gone. */
+    deleteContainerApplication(id: string): Promise<void>;
+}
+/** What the custody Worker returns for a minted derived credential. */
+export interface MintedCustodyCredential {
+    credentialId: string;
+    /** The secret value. Held and delivered, never printed or recorded. */
+    credential: string;
+    /** When the credential stops working: an ISO 8601 date-time. */
+    expiresAt: string;
+}
+/**
+ * The keys custody Worker, for a `keysCustody` secret (ADR 0002). The host
+ * wires it to `POST /v1/derived/credential` with the credential of a host in
+ * the custody Worker's DERIVE_MINTERS (archon, which runs foundry).
+ */
+export interface KeysCustodyPort {
+    /** The custody Worker's public URL, delivered as `KEYS_URL`. */
+    readonly url: string;
+    /** Mints a wrap+unwrap credential (365 days) for the derived host id. */
+    mintDerivedCredential(hostId: string): Promise<MintedCustodyCredential>;
+}
+/** Foundry mints a new credential this long before the held one expires. */
+export declare const WORKER_APP_CREDENTIAL_RENEW_BEFORE_MS: number;
+/**
+ * True when the delivered custody credential is within 30 days of expiry (or
+ * its record is unreadable), so the plan renews it.
+ */
+export declare function custodyRenewalDue(recorded: Readonly<Record<string, string>>, entryKey: string, now: Date): boolean;
+export interface WorkerAppWant {
+    name: string;
+    artifactUrl: string;
+    artifactSha256: string;
+    compatibilityDate: string;
+    compatibilityFlags: string[];
+    /** The full hostname the Worker is served at. */
+    host: string;
+    /** The zone the route and record live in. */
+    apex: string;
+    classes: {
+        binding: string;
+        className: string;
+    }[];
+    migrations: WorkerAppConfig['durableObjects']['migrations'];
+    containers: WorkerAppContainer[];
+    /** Plain vars, sorted: declared, `authEnv`, and `KEYS_URL`. */
+    vars: [string, string][];
+    /** `workerApp.database`: the Hyperdrive binding and the tables the runtime role may only append to, sorted. */
+    database?: {
+        appendOnly: string[];
+        migrationsSha256?: string;
+    };
+    /** Secret names and where each comes from, sorted. */
+    secrets: {
+        name: string;
+        source: 'generated' | 'keysCustody';
+        hostId?: string;
+    }[];
+}
+/** The zone apex the entry's route lives in. */
+export declare const workerAppApex: (org: DeclaredOrg) => string;
+/**
+ * What the Worker must look like, or the inputs still missing (names only).
+ * `issuer` is the sign-in issuer the plan read; `keysUrl` the custody Worker.
+ */
+export declare function wantedWorkerApp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, input: {
+    issuer: string | null;
+    keysUrl?: string;
+}): {
+    want: WorkerAppWant;
+} | {
+    missing: string[];
+};
+/**
+ * The migration tags the recorded list says are applied must be the first tags
+ * of the declared list, in order. `null` when they are; else the refusal.
+ */
+export declare function migrationPrefixError(applied: readonly string[], declared: readonly string[]): string | null;
+/** The unapplied migrations after the last tag in `applied`. */
+export declare const unappliedMigrations: (declared: WorkerAppConfig["durableObjects"]["migrations"], applied: readonly string[]) => WorkerAppConfig["durableObjects"]["migrations"];
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+export interface WorkerAppPlanInput {
+    /** The host supplied a {@link WorkerAppPort}. */
+    available: boolean;
+    /** The custody Worker address, when the host supplied a {@link KeysCustodyPort}. */
+    keysUrl?: string;
+    /** The clock for credential renewal. Defaults to now. */
+    now?: Date;
+    /** The host can hold and read secrets (a held-key store that can put). */
+    canHoldSecrets: boolean;
+    /** The sign-in issuer for `authEnv`. */
+    issuer: string | null;
+    /** The platform's Cloudflare account id: a container image must live in its registry. */
+    registryAccountId?: string;
+    /**
+     * `workerApp.database`: what the host and the plan have. Absent: the host has no
+     * `WorkerAppDatabasePort`, so an entry with `database` is reported blocked.
+     */
+    database?: {
+        /** The org's `coolify:database` step is recorded or planned in this run. */
+        databaseReady: boolean;
+        /** The org's Cloudflare tunnel is recorded or planned in this run. */
+        tunnelReady: boolean;
+        /** The executor has Access, tunnel, DNS and zone ports. */
+        accessReady: boolean;
+    };
+}
+/** The registry prefix a container image of this platform must start with. */
+export declare const workerAppRegistryPrefix: (accountId: string) => string;
+/** Every entry key with a deployed or half-deployed Worker app recorded. */
+export declare function liveWorkerApps(orgId: string, recordedIds: Readonly<Record<string, string>>): Map<string, string>;
+/**
+ * One step per Worker app whose declaration or inputs changed, plus a retire
+ * step per recorded Worker app no longer declared. Blocked, not planned
+ * (`CLAUDE.md` platform rule 2), while the host lacks a port or a value, while
+ * the declared migrations contradict the applied ones, and for each input the
+ * Worker needs that does not exist yet. A migration that deletes or renames a
+ * class makes the step `destroys` or `migrates`, so the org's name must be typed
+ * to apply it.
+ */
+export declare function planWorkerApps(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, input: WorkerAppPlanInput): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+/** What `applyWorkerApp` needs beyond the context. Each call below is bounded by {@link WORKER_APP_CALL_TIMEOUT_MS}. */
+export interface WorkerAppDeps {
+    workers: WorkerAppPort;
+    keys?: KeysCustodyPort;
+    /** Test hook: the clock for credential renewal. */
+    now?: () => Date;
+    zones: ZonePort;
+    dns: DnsPort;
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null | undefined>;
+        put?(ref: string, value: string): Promise<void>;
+    };
+    /** `workerApp.database`: the Hyperdrive port and the route's Cloudflare ports. */
+    database?: WorkerAppDatabaseDeps;
+    /** Test hook: the timeout, in ms. */
+    timeoutMs?: number;
+}
+/** An outside call that has not answered in this long fails the step; the next apply repairs it. */
+export declare const WORKER_APP_CALL_TIMEOUT_MS = 120000;
+export declare const WORKER_APP_KEYS_DELIVERY_ATTEMPTS = 3;
+/**
+ * Races `task` against a timer. An error names the call, never the cause.
+ */
+export declare function withCallTimeout<T>(ms: number, label: string, task: () => Promise<T>): Promise<T>;
+/**
+ * Makes the Worker app true. Throws a fixed message on a failure, naming the
+ * step and never a value or a provider's cause for anything that carried a
+ * secret. Every recorded id is persisted before the call that could lose it.
+ */
+export declare function applyWorkerApp(deps: WorkerAppDeps, org: DeclaredOrg, action: StepAction, context: StepExecutionContext): Promise<{
+    resourceId?: string;
+}>;
+/**
+ * Tears a Worker app down in the order that never leaves a route to nothing:
+ * route, record, containers, then the script (its secrets go with it).
+ * Held generated secrets stay, so redeclaring reuses them. Used by retire and
+ * by org destroy.
+ */
+export declare function teardownWorkerApp(deps: WorkerAppDeps, entryKey: string, scriptName: string | undefined, recorded: Readonly<Record<string, string>>, call: <T>(label: string, task: () => Promise<T>) => Promise<T>, orgId: string, context?: Pick<StepExecutionContext, 'recordScopeId' | 'persistScopeIds'> | null): Promise<void>;
+export {};