@wtfalch/foundry 0.42.1 → 0.44.0

package/dist/worker-app-config.js

@@ -0,0 +1,438 @@
+import { createHash } from 'node:crypto';
+import { validateSlug } from './slug.js';
+/** The compatibility flags a Worker app may ask for. */
+export const WORKER_APP_COMPATIBILITY_FLAGS = new Set(['nodejs_compat']);
+export const WORKER_APP_INSTANCE_TYPES = new Set([
+    'lite',
+    'basic',
+    'standard-1',
+    'standard-2',
+    'standard-3',
+    'standard-4',
+]);
+/** The most instances one container class may scale to. */
+export const WORKER_APP_MAX_INSTANCES = 100;
+/** The secret that carries a `keysCustody` source: the custody Worker credential. */
+export const WORKER_APP_KEYS_SECRET = 'KEYS_CREDENTIAL';
+export const WORKER_APP_KEYS_URL_VAR = 'KEYS_URL';
+/**
+ * Names foundry writes into a Worker app's environment itself, so a
+ * declaration may not use them as a binding, secret or var.
+ */
+export const WORKER_APP_RESERVED_NAMES = /^(AUTH_.*|KEYS_.*|MCP_.*|HYPERDRIVE)$/;
+/** 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);
+/** The Hyperdrive binding of a Worker app with `database`. */
+export const WORKER_APP_HYPERDRIVE_BINDING = 'HYPERDRIVE';
+/** The most tables `database.appendOnly` may name, and the shape of one name (`table` or `schema.table`). */
+export const WORKER_APP_APPEND_ONLY_MAX = 100;
+const TABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,62}(\.[A-Za-z_][A-Za-z0-9_]{0,62})?$/;
+/** The custody Worker's host id shape for a derived (app) host, and its limit. */
+const HOST_ID = /^app-[a-z0-9]+(-[a-z0-9]+)*$/;
+const HOST_ID_MAX_LENGTH = 64;
+/** Hex characters of the org id's sha256 in a host id. */
+export const WORKER_APP_HOST_ID_HASH_LENGTH = 12;
+/**
+ * The custody host id of a Worker app: `app-<12 hex of sha256(org id)>-<entry key>`.
+ * It derives from the org id, never the slug, so a slug rename keeps it, and
+ * two orgs cannot share one (their hashes differ). The entry key is unique
+ * within an org. Null when the result breaks the custody pattern
+ * `^app-[a-z0-9]+(-[a-z0-9]+)*$`, 64 characters, or ends in `-next`.
+ */
+export function workerAppHostId(orgId, entryKey) {
+    const hash = createHash('sha256')
+        .update(orgId)
+        .digest('hex')
+        .slice(0, WORKER_APP_HOST_ID_HASH_LENGTH);
+    const id = `app-${hash}-${entryKey}`.toLowerCase();
+    return HOST_ID.test(id) && id.length <= HOST_ID_MAX_LENGTH && !id.endsWith('-next') ? id : null;
+}
+/** The script name ends in this; the entry key's budget against Cloudflare's 63 characters follows from it. */
+export const WORKER_APP_NAME_SUFFIX = '-app';
+const WORKER_NAME_MAX_LENGTH = 63;
+const WORKER_NAME_FIXED_LENGTH = 8 + 1 + WORKER_APP_NAME_SUFFIX.length;
+const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const RELEASE_ASSET_URL = /^https:\/\/github\.com\/wtfalch\/([A-Za-z0-9._-]+)\/releases\/download\/([A-Za-z0-9._+-]+)\/([A-Za-z0-9._+-]+)$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const ENV_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+const CLASS_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+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 SECRET_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
+const VAR_MAX_LENGTH = 1000;
+/**
+ * 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
+ * sha256. Shared by `worker` and `workerApp`.
+ */
+export function validateArtifact(at, artifactUrl, sha256, repo = null) {
+    let url;
+    try {
+        url = new URL(artifactUrl);
+    }
+    catch {
+        return `${at} artifactUrl must be an absolute URL, not a bare path or relative file`;
+    }
+    if (url.protocol !== 'https:')
+        return `${at} artifactUrl must be an https:// URL`;
+    if (url.username || url.password) {
+        return `${at} artifactUrl must not carry userinfo (a signed or credentialed URL ends up stored verbatim in recorded scope ids)`;
+    }
+    if (url.search) {
+        return `${at} artifactUrl must not carry a query string (a signed or credentialed URL ends up stored verbatim in recorded scope ids)`;
+    }
+    // `URL.hash` is '' for a bare trailing `#`, so the raw string is checked.
+    if (artifactUrl.includes('#')) {
+        return `${at} artifactUrl must not carry a fragment (refused for the same reason as a query string)`;
+    }
+    // Foundry's host fetches this URL with a GitHub token, so it names a release
+    // asset of the org's own repo and nothing else: no other host, port or path.
+    const asset = RELEASE_ASSET_URL.exec(artifactUrl);
+    const segment = (value) => value !== undefined && !/^\.+$/.test(value);
+    const declared = repo?.slice(repo.indexOf('/') + 1);
+    if (!asset || !segment(asset[1]) || !segment(asset[2]) || !segment(asset[3])) {
+        return `${at} artifactUrl must be https://github.com/wtfalch/<repo>/releases/download/<tag>/<file>: foundry fetches it with a GitHub token, so it names a release asset of a wtfalch repo and nothing else`;
+    }
+    if (declared !== undefined && declared !== '' && asset[1] !== declared) {
+        return `${at} artifactUrl must be a release asset of the entry's own repo '${repo}'`;
+    }
+    if (!SHA256_HEX.test(sha256))
+        return `${at} artifactSha256 must be 64 lowercase hex characters`;
+    return null;
+}
+/**
+ * The one exact name a Worker app is served at: `<host>.<domain>` or the apex
+ * on the org's own domain, else `<slug>-<key>.oikos.host` (one label under
+ * `oikos.host`, so the free Universal certificate covers it), and
+ * `<slug>.oikos.host` for the entry keyed `app`.
+ */
+export function workerAppHostnameOf(org, key, host) {
+    if (org.usesDomain && org.domain)
+        return host === '@' ? org.domain : `${host}.${org.domain}`;
+    return key === 'app' ? `${org.slug}.oikos.host` : `${org.slug}-${key}.oikos.host`;
+}
+/** True for a real calendar date written `YYYY-MM-DD`. */
+function isCalendarDate(value) {
+    if (!COMPAT_DATE.test(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().startsWith(value);
+}
+/**
+ * The Durable Object classes the migrations leave behind, folded in order:
+ * created, then removed, then renamed. A rename of a class that does not exist
+ * at that point is an error.
+ */
+export function foldMigrationClasses(migrations) {
+    const classes = new Set();
+    for (const migration of migrations) {
+        for (const name of migration.newSqliteClasses ?? []) {
+            if (classes.has(name)) {
+                return {
+                    error: `migration '${migration.tag}' creates class '${name}', which already exists`,
+                };
+            }
+            classes.add(name);
+        }
+        for (const name of migration.deletedClasses ?? []) {
+            if (!classes.delete(name)) {
+                return {
+                    error: `migration '${migration.tag}' deletes class '${name}', which does not exist`,
+                };
+            }
+        }
+        for (const { from, to } of migration.renamedClasses ?? []) {
+            if (!classes.delete(from)) {
+                return {
+                    error: `migration '${migration.tag}' renames class '${from}', which does not exist`,
+                };
+            }
+            if (classes.has(to)) {
+                return {
+                    error: `migration '${migration.tag}' renames '${from}' to '${to}', which already exists`,
+                };
+            }
+            classes.add(to);
+        }
+    }
+    return { classes };
+}
+/**
+ * `workerApp`: exclusive with `worker` and a Coolify repo, no Coolify-only
+ * setting, a Durable Object and container declaration Cloudflare will accept,
+ * names that cannot clash with what foundry delivers, and one exact host.
+ * `null` when valid. Whether a migration was already applied is a fact of the
+ * live system; the planner checks that (`plan/worker-app.ts`).
+ */
+export function validateEntryWorkerApp(entry, hosting, names) {
+    const app = entry.workerApp;
+    if (!app)
+        return null;
+    const at = `hosting.entries '${entry.key}' workerApp`;
+    if (!hosting.enabled)
+        return `${at} requires hosting.enabled`;
+    if (entry.worker)
+        return `${at} is exclusive with worker: declare one of them`;
+    if (entry.repo !== null) {
+        return `${at} is exclusive with a Coolify repo: an entry that declares workerApp has repo null`;
+    }
+    if (entry.hostnames.length > 0) {
+        return `${at} names its host in workerApp.host, so hostnames must be empty`;
+    }
+    if (entry.database) {
+        return `${at} has no Coolify app, so the entry cannot set database: declare workerApp.database instead`;
+    }
+    if ((entry.volumes?.length ?? 0) > 0)
+        return `${at} has no Coolify app, so it cannot declare volumes`;
+    if (entry.gates.length > 0)
+        return `${at} has no Coolify app, so it cannot declare gates`;
+    if (Object.keys(entry.env).length > 0) {
+        return `${at} has no Coolify app, so env does not apply: use workerApp.vars or workerApp.secrets`;
+    }
+    const unsupported = Object.keys(entry.uses ?? {}).find((use) => use !== 'auth');
+    if (unsupported)
+        return `${at} supports uses.auth only, not uses.${unsupported}`;
+    if (entry.key.length > WORKER_NAME_MAX_LENGTH - WORKER_NAME_FIXED_LENGTH) {
+        return `${at} entry key is too long: the deployed Worker's name (an 8-character org hash, the key, and "${WORKER_APP_NAME_SUFFIX}") must fit Cloudflare's ${WORKER_NAME_MAX_LENGTH}-character limit`;
+    }
+    const invalidArtifact = validateArtifact(at, app.artifactUrl, app.artifactSha256, entry.repo);
+    if (invalidArtifact)
+        return invalidArtifact;
+    if (app.compatibilityDate !== undefined && !isCalendarDate(app.compatibilityDate)) {
+        return `${at} compatibilityDate must be a date written YYYY-MM-DD`;
+    }
+    for (const flag of app.compatibilityFlags ?? []) {
+        if (!WORKER_APP_COMPATIBILITY_FLAGS.has(flag)) {
+            return `${at} compatibilityFlags '${flag}' is not allowed (allowed: ${[...WORKER_APP_COMPATIBILITY_FLAGS].join(', ')})`;
+        }
+    }
+    if (app.host !== '@' && !LABEL.test(app.host)) {
+        return `${at} host must be '@' or a DNS label: an exact host, never a wildcard`;
+    }
+    if (names?.domain && app.host !== '@' && names.locked.has(`${app.host}.${names.domain}`)) {
+        return `${at} host '${app.host}' is a name foundry owns: ${app.host}.${names.domain}`;
+    }
+    if (names) {
+        const domain = hosting.usesDomain ? names.domain : null;
+        if (domain && app.host === '@' && names.siteOwnsApex) {
+            return `${at} host '@' is the apex, which the org's site serves`;
+        }
+        if (names.slug !== undefined) {
+            const served = workerAppHostnameOf({
+                slug: names.slug,
+                domain: names.domain,
+                usesDomain: hosting.usesDomain,
+            }, entry.key, app.host);
+            if (names.locked.has(served))
+                return `${at} host is a name foundry owns: ${served}`;
+            // Without a domain the name is `<slug>-<key>.oikos.host`, the shape of
+            // every environment and service host of the org (`-auth`, `-agora`,
+            // `-boule`, `-stage`, `-pr-<n>`, ...). `slug.ts` already refuses a slug
+            // that ends in one of those suffixes, so the same check refuses the key.
+            if (!domain && entry.key !== 'app' && validateSlug(`${names.slug}-${entry.key}`)) {
+                return `${at} entry key '${entry.key}' would serve ${served}, a name foundry reserves for the org's own services and environments`;
+            }
+        }
+    }
+    for (const other of hosting.entries) {
+        if (other !== entry && other.workerApp?.host === app.host) {
+            return `${at} host '${app.host}' is already declared by entry '${other.key}'`;
+        }
+        if (other !== entry && other.hostnames.includes(app.host)) {
+            return `${at} host '${app.host}' is already a hostname of entry '${other.key}'`;
+        }
+    }
+    const reserved = new Set();
+    const claim = (kind, name) => {
+        if (!ENV_NAME.test(name)) {
+            return `${at} ${kind} '${name}' must be an env name of capital letters, digits and underscores`;
+        }
+        if (WORKER_APP_RESERVED_NAMES.test(name) &&
+            !(kind === 'secret' && name === WORKER_APP_KEYS_SECRET)) {
+            return `${at} ${kind} '${name}' is a name foundry writes itself (AUTH_*, KEYS_*, MCP_*, HYPERDRIVE)`;
+        }
+        if (reserved.has(name))
+            return `${at} ${kind} '${name}' is already used by another binding, secret or var`;
+        reserved.add(name);
+        return null;
+    };
+    const invalidDo = validateDurableObjects(at, app, claim);
+    if (invalidDo)
+        return invalidDo;
+    const invalidContainers = validateContainers(at, app);
+    if (invalidContainers)
+        return invalidContainers;
+    let keysSecrets = 0;
+    for (const [name, source] of Object.entries(app.secrets ?? {})) {
+        if (source?.from === 'keys') {
+            return `${at} secret '${name}': Worker apps use keysCustody for the custody Worker; issued API keys are not supported yet`;
+        }
+        const invalid = claim('secret', name);
+        if (invalid)
+            return invalid;
+        if (source?.from === 'generated')
+            continue;
+        if (source?.from !== 'keysCustody')
+            return `${at} secret '${name}' has an unknown source`;
+        keysSecrets++;
+        if (name !== WORKER_APP_KEYS_SECRET) {
+            return `${at} a keysCustody secret is delivered as ${WORKER_APP_KEYS_SECRET}, so it must be named ${WORKER_APP_KEYS_SECRET}`;
+        }
+        if (keysSecrets > 1)
+            return `${at} declares more than one keysCustody secret`;
+        // The shape does not depend on the org id, so any id checks the key.
+        if (workerAppHostId('0', entry.key) === null) {
+            return `${at} entry key '${entry.key}' cannot make a custody host id: app-<${WORKER_APP_HOST_ID_HASH_LENGTH} hex>-<key> must be lowercase letters, digits and single hyphens, at most ${HOST_ID_MAX_LENGTH} characters, and must not end in -next`;
+        }
+    }
+    if (keysSecrets > 0)
+        reserved.add(WORKER_APP_KEYS_URL_VAR);
+    for (const [name, value] of Object.entries(app.vars ?? {})) {
+        const invalid = claim('var', name);
+        if (invalid)
+            return invalid;
+        if (typeof value !== 'string' || value.length > VAR_MAX_LENGTH) {
+            return `${at} var '${name}' must be a string of at most ${VAR_MAX_LENGTH} characters`;
+        }
+        if (SECRET_NAME.test(name)) {
+            return `${at} var '${name}' looks like a secret: declare it under workerApp.secrets, not as a plain var`;
+        }
+        try {
+            if (new URL(value).password !== '') {
+                return `${at} var '${name}' carries a password in a URL: vars are plain text`;
+            }
+        }
+        catch {
+            // Not a URL: nothing to check.
+        }
+    }
+    const invalidDatabase = validateWorkerAppDatabase(at, app);
+    if (invalidDatabase)
+        return invalidDatabase;
+    if (app.authEnv !== undefined && typeof app.authEnv !== 'boolean') {
+        return `${at} authEnv must be true or false`;
+    }
+    if (app.authEnv === true && !entry.uses?.auth)
+        return `${at} authEnv needs uses.auth`;
+    // Without authEnv the broker entry is never delivered its key and stays
+    // blocked, and an MCP server gets none of its MCP_* vars.
+    if (entry.uses?.auth && app.authEnv !== true) {
+        return `${at} uses.auth needs authEnv: true: foundry delivers the sign-in env and the broker key only then`;
+    }
+    return null;
+}
+function validateWorkerAppDatabase(at, app) {
+    const database = app.database;
+    if (database === undefined)
+        return null;
+    if (typeof database !== 'object' || database === null || Array.isArray(database)) {
+        return `${at} database must be an object: { appendOnly?: string[]; migrationsSha256?: string }`;
+    }
+    const unknown = Object.keys(database).find((key) => key !== 'appendOnly' && key !== 'migrationsSha256');
+    if (unknown) {
+        return `${at} database.${unknown} is not a setting: only appendOnly and migrationsSha256`;
+    }
+    const sha = database.migrationsSha256;
+    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 seen = new Set();
+    for (const table of appendOnly) {
+        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)`;
+        }
+        if (seen.has(table))
+            return `${at} database.appendOnly names '${table}' twice`;
+        seen.add(table);
+    }
+    return null;
+}
+function validateDurableObjects(at, app, claim) {
+    const { classes, migrations } = app.durableObjects ?? {
+        classes: {},
+        migrations: [],
+    };
+    const declared = new Set();
+    for (const [binding, className] of Object.entries(classes ?? {})) {
+        const invalid = claim('durable object binding', binding);
+        if (invalid)
+            return invalid;
+        if (typeof className !== 'string' || !CLASS_NAME.test(className)) {
+            return `${at} durableObjects.classes '${binding}' must name an exported class`;
+        }
+        if (declared.has(className)) {
+            return `${at} durableObjects.classes names class '${className}' twice`;
+        }
+        declared.add(className);
+    }
+    const tags = new Set();
+    for (const migration of migrations ?? []) {
+        if (typeof migration.tag !== 'string' || !MIGRATION_TAG.test(migration.tag)) {
+            return `${at} durableObjects.migrations needs a tag of letters, digits, '.', '_' or '-'`;
+        }
+        if (tags.has(migration.tag))
+            return `${at} durableObjects.migrations tag '${migration.tag}' is used twice`;
+        tags.add(migration.tag);
+        const touched = [
+            ...(migration.newSqliteClasses ?? []),
+            ...(migration.deletedClasses ?? []),
+            ...(migration.renamedClasses ?? []).flatMap((r) => [r.from, r.to]),
+        ];
+        if (touched.length === 0)
+            return `${at} migration '${migration.tag}' changes no class`;
+        if (!touched.every((name) => typeof name === 'string' && CLASS_NAME.test(name))) {
+            return `${at} migration '${migration.tag}' names a class that is not an exported class name`;
+        }
+    }
+    const folded = foldMigrationClasses(migrations ?? []);
+    if ('error' in folded)
+        return `${at} ${folded.error}`;
+    for (const name of declared) {
+        if (!folded.classes.has(name)) {
+            return `${at} durableObjects.classes uses class '${name}', which no migration creates`;
+        }
+    }
+    for (const name of folded.classes) {
+        if (!declared.has(name)) {
+            return `${at} migrations leave class '${name}' with no durableObjects.classes binding`;
+        }
+    }
+    return null;
+}
+function validateContainers(at, app) {
+    const classNames = new Set(Object.values(app.durableObjects?.classes ?? {}));
+    const seen = new Set();
+    for (const container of app.containers ?? []) {
+        if (!classNames.has(container.className)) {
+            return `${at} containers className '${container.className}' must be a Durable Object class in durableObjects.classes`;
+        }
+        if (seen.has(container.className)) {
+            return `${at} containers names class '${container.className}' twice`;
+        }
+        seen.add(container.className);
+        if (!container.image || !DIGEST.test(container.image.digest ?? '')) {
+            return `${at} containers '${container.className}' image needs a digest (sha256:<64 hex>): a tag can move`;
+        }
+        if (!IMAGE_REPOSITORY.test(container.image.repository ?? '') ||
+            container.image.repository.split('/').some((part) => /^\.+$/.test(part))) {
+            return `${at} containers '${container.className}' image repository must be a registry path such as registry.example/name, without a tag or digest`;
+        }
+        if (!WORKER_APP_INSTANCE_TYPES.has(container.instanceType)) {
+            return `${at} containers '${container.className}' instanceType '${container.instanceType}' is not one of ${[...WORKER_APP_INSTANCE_TYPES].join(', ')}`;
+        }
+        if (!Number.isInteger(container.maxInstances) ||
+            container.maxInstances < 1 ||
+            container.maxInstances > WORKER_APP_MAX_INSTANCES) {
+            return `${at} containers '${container.className}' maxInstances must be a whole number from 1 to ${WORKER_APP_MAX_INSTANCES}`;
+        }
+    }
+    return null;
+}

package/package.json

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

package/versions.digests.json

@@ -8,5 +8,6 @@
   "hc": "sha256:aa08a61b0dcfd83f1332eab195d5cec1b595ae076eb8388cadf8a3d597114f9b",
   "alpine": "sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1",
   "busybox": "sha256:5cec3fc171c87218698e85a52af7087de727372aae264a787b8112901a5b0092",
-  "postgres": "sha256:786dab398303b8ce7cb76b407bb21ef2e4dfbbbd4c6abcf3d29b3130467ffdbc"
+  "postgres": "sha256:786dab398303b8ce7cb76b407bb21ef2e4dfbbbd4c6abcf3d29b3130467ffdbc",
+  "traefik": "sha256:575fa15b135078fe5e50aa847987d96dbddd7b093c172429618404df73f3fa7c"
 }

package/versions.json

@@ -8,5 +8,6 @@
   "hc": "v4.4",
   "alpine": "3.22.1",
   "busybox": "1.37.0-musl",
-  "postgres": "16.14-alpine3.22"
+  "postgres": "16.14-alpine3.22",
+  "traefik": "v3.7.14"
 }