@wtfalch/foundry 0.43.0 → 0.44.0

package/dist/plan/worker-app-database.js

@@ -0,0 +1,424 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { REMOTE_DATABASE_PORT, mergeTcpIngress, recordedHttpIngress, recordedTcpRoutes, remoteDatabaseKeys, } from './remote-database.js';
+import { WORKER_APP_CALL_TIMEOUT_MS, withCallTimeout, workerAppSecretRef } from './worker-app.js';
+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}$/;
+const HOLD_DELIVERY_ATTEMPTS = 3;
+// ---- scope keys ------------------------------------------------------------
+/** The Hyperdrive config, `{name, id}` as JSON. No secret. */
+export const workerAppHyperdriveScopeKey = (entryKey) => `workerapp_hyperdrive_${entryKey}`;
+/** The migration ids applied, a JSON list, for the plan and the operator. The database's ledger is the fact. */
+export const workerAppMigrationsScopeKey = (entryKey) => `workerapp_dbmig_${entryKey}`;
+/** The applied route marker (`{hostname, database}`). */
+export const workerAppDbRouteMarkerScopeKey = (entryKey) => `workerapp_dbroute_${entryKey}`;
+/** The Hyperdrive config name of an entry: the Worker's script name plus `-db`. */
+export const hyperdriveName = (scriptName) => `${scriptName}-db`;
+/** The tunnel hostname of an entry's database route: `<8 hex of org id>-<key>-hd.<zone>`. */
+export const hyperdriveHostname = (org, entryKey, zone) => `${createHash('sha256').update(org.id).digest('hex').slice(0, 8)}-${entryKey}-hd.${zone}`;
+// ---- 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));
+}
+const parseHeldAccess = (raw) => {
+    if (!raw)
+        return null;
+    try {
+        const held = JSON.parse(raw);
+        return typeof held.id === 'string' &&
+            typeof held.clientId === 'string' &&
+            typeof held.clientSecret === 'string' &&
+            held.clientSecret !== ''
+            ? held
+            : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Connection parts of the owner URL; the message names nothing from it. */
+function parseOwnerUrl(url, at) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`${at}: the database reports no usable connection URL`);
+    }
+    const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
+    if (!parsed.hostname || !database || !parsed.username) {
+        throw new Error(`${at}: the database reports no usable connection URL`);
+    }
+    return {
+        host: parsed.hostname,
+        database,
+        user: decodeURIComponent(parsed.username),
+        password: decodeURIComponent(parsed.password),
+    };
+}
+/**
+ * Makes the database true and returns the Hyperdrive config id for the `HYPERDRIVE` binding.
+ * Secrets (the owner and runtime passwords, the Access service token) go only to the port and the
+ * held-key store, never into an error, a recorded id or a return value. Each outside call is
+ * bounded by a timeout; the error names the call, never the cause.
+ */
+export async function applyWorkerAppDatabase(deps, org, entry, scriptName, want, context, zoneApex) {
+    const at = `cloudflare:worker-app for ${org.slug} entry '${entry.key}' database`;
+    const ms = deps.timeoutMs ?? WORKER_APP_CALL_TIMEOUT_MS;
+    const call = (label, task, over) => withCallTimeout(over ?? ms, `${at}: ${label}`, task);
+    const { port, heldKeys } = deps;
+    if (!heldKeys?.put)
+        throw new Error(`${at}: needs a held-key store that can put`);
+    const put = heldKeys.put;
+    const keys = remoteDatabaseKeys(entry.key);
+    const databaseId = context.recordedIds()[`coolify:database:${org.id}`];
+    if (!databaseId)
+        throw new Error(`${at}: ${org.slug}'s database is not applied yet`);
+    const tunnelId = context.recordedIds()[`cloudflare:tunnel:${org.id}`];
+    if (!tunnelId)
+        throw new Error(`${at}: ${org.slug}'s Cloudflare tunnel is not applied yet`);
+    const ownerUrl = await call('read the database address', () => deps.ownerUrl(databaseId));
+    deps.secret(ownerUrl);
+    const owner = parseOwnerUrl(ownerUrl, at);
+    deps.secret(owner.password);
+    const hostname = hyperdriveHostname(org, entry.key, zoneApex);
+    // 1. The service token: minted once (rule 1), its secret held before anything else uses it.
+    const access = await ensureServiceToken(deps, org, entry, scriptName, at, call, context, put);
+    // 2. The Access gate and the route behind it.
+    const zone = await call('find the zone', () => deps.zones.findZoneByApex(zoneApex));
+    if (!zone)
+        throw new Error(`${at}: zone ${zoneApex} is not live`);
+    let accessAppId = context.recordedIds()[keys.access];
+    if (!accessAppId) {
+        const live = (await call('list Access apps', () => deps.access.listAccessApps())).find((a) => a.domain === hostname);
+        accessAppId = (live ??
+            (await call('create the Access app', () => deps.access.createAccessApp({
+                name: `${scriptName}-db-access`,
+                domain: hostname,
+                type: 'self_hosted',
+            })))).id;
+        context.recordScopeId(keys.access, accessAppId);
+        await context.persistScopeIds();
+    }
+    const appId = accessAppId;
+    const policies = await call('list Access policies', () => deps.access.listAccessPolicies(appId));
+    const hasPolicy = policies.some((p) => p.decision === 'non_identity' &&
+        (p.include ?? []).some((r) => r.service_token?.token_id === access.id));
+    if (!hasPolicy) {
+        await call('create the Access policy', () => deps.access.createAccessPolicy(appId, {
+            name: 'hyperdrive',
+            decision: 'non_identity',
+            include: [{ service_token: { token_id: access.id } }],
+        }));
+    }
+    const marker = JSON.stringify({ hostname, database: databaseId });
+    if (context.recordedIds()[workerAppDbRouteMarkerScopeKey(entry.key)] !== marker) {
+        context.recordScopeId(keys.route, JSON.stringify({ hostname, service: `tcp://${owner.host}:${REMOTE_DATABASE_PORT}` }));
+        await call('write the tunnel route', () => deps.tunnels.putTunnelConfig(tunnelId, {
+            ingress: mergeTcpIngress(recordedHttpIngress(context.recordedIds()), recordedTcpRoutes(context.recordedIds())),
+        }));
+        if ((await call('look for the DNS record', () => deps.dns.findDnsRecord(zone.name, hostname, 'CNAME'))).length === 0) {
+            await call('create the DNS record', () => deps.dns.createDnsRecord(zone.name, {
+                type: 'CNAME',
+                name: hostname,
+                content: `${tunnelId}.cfargotunnel.com`,
+                proxied: true,
+            }));
+        }
+        context.recordScopeId(workerAppDbRouteMarkerScopeKey(entry.key), marker);
+        await context.persistScopeIds();
+    }
+    // 3. The runtime password: minted once and held, so a rerun hands out the same one.
+    const runtimeUser = `${owner.database}_rt`;
+    const rtRef = workerAppSecretRef(org.id, entry.key, 'DATABASE_RT_PASSWORD');
+    let runtimePassword = (await call('read the held runtime password', () => heldKeys.resolve(rtRef))) ?? '';
+    if (!runtimePassword) {
+        runtimePassword = randomBytes(24).toString('base64url');
+        const minted = runtimePassword;
+        await call('hold the runtime password', () => put(rtRef, minted));
+    }
+    deps.secret(runtimePassword);
+    const ownerOrigin = {
+        host: hostname,
+        database: owner.database,
+        user: owner.user,
+        password: owner.password,
+        accessClientId: access.clientId,
+        accessClientSecret: access.clientSecret,
+    };
+    // 4. Migrations with the owner credentials. A failure stops the deploy; ids already applied stay.
+    const text = await call('fetch the release migrations', () => port.fetchReleaseAsset(migrationsUrl(want.artifactUrl)));
+    let migrations;
+    try {
+        verifyMigrationsDigest(text, want.database.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', () => port.appliedMigrationIds(ownerOrigin));
+    let pending;
+    try {
+        pending = unappliedDatabaseMigrations(migrations, applied);
+    }
+    catch (error) {
+        throw new Error(`${at}: ${error.message}`);
+    }
+    const done = [...applied];
+    for (const migration of pending) {
+        await call(`apply migration '${migration.id}'`, () => port.applyMigration(ownerOrigin, migration), deps.migrationTimeoutMs ?? WORKER_APP_MIGRATION_TIMEOUT_MS);
+        done.push(migration.id);
+        context.recordScopeId(workerAppMigrationsScopeKey(entry.key), JSON.stringify(done));
+        await context.persistScopeIds();
+    }
+    // 5. The runtime role, after the migrations so the tables exist for the revokes.
+    await call('ensure the runtime role', () => port.ensureRuntimeRole({
+        owner: ownerOrigin,
+        runtime: { user: runtimeUser, password: runtimePassword },
+        appendOnly: [...want.database.appendOnly],
+    }));
+    // 6. Hyperdrive, with the runtime credentials only.
+    const name = hyperdriveName(scriptName);
+    const { id } = await call('upsert the Hyperdrive config', () => port.upsertHyperdrive({
+        name,
+        origin: {
+            host: hostname,
+            database: owner.database,
+            user: runtimeUser,
+            password: runtimePassword,
+            accessClientId: access.clientId,
+            accessClientSecret: access.clientSecret,
+        },
+    }));
+    context.recordScopeId(workerAppHyperdriveScopeKey(entry.key), JSON.stringify({ name, id }));
+    await context.persistScopeIds();
+    return { hyperdriveId: id };
+}
+/**
+ * The Access service token Hyperdrive and the migration runner present. Minted once: its id is
+ * recorded under an undelivered key and persisted before the secret is held, the delivered id
+ * replaces it after the hold. A token minted and never held is never minted again.
+ */
+async function ensureServiceToken(deps, org, entry, scriptName, at, call, context, put) {
+    const keys = remoteDatabaseKeys(entry.key);
+    const ref = workerAppSecretRef(org.id, entry.key, 'HYPERDRIVE_ACCESS');
+    const heldKeys = deps.heldKeys;
+    const lost = context.recordedIds()[keys.undelivered];
+    if (lost) {
+        throw new Error(`${at}: service token ${lost} was minted and its secret never reached the held-key store; delete the token in Cloudflare and clear the recorded id before minting again`);
+    }
+    const held = parseHeldAccess(await call('read the held service token', () => heldKeys.resolve(ref)));
+    if (held) {
+        deps.secret(held.clientSecret);
+        deps.secret(held.clientId);
+        return held;
+    }
+    const recordedToken = context.recordedIds()[keys.token];
+    if (recordedToken) {
+        throw new Error(`${at}: service token ${recordedToken} is recorded and its secret is not held; delete the token in Cloudflare and clear the recorded id to mint it again`);
+    }
+    const tokenName = `${hyperdriveName(scriptName)}-access`;
+    if (await call('look for the service token', () => deps.access.findServiceTokenByName(tokenName))) {
+        throw new Error(`${at}: a service token named ${tokenName} exists and foundry holds no secret for it; delete it in Cloudflare before applying again`);
+    }
+    const minted = await call('mint the service token', () => deps.access.createServiceToken(tokenName));
+    deps.secret(minted.clientSecret);
+    deps.secret(minted.clientId);
+    context.recordScopeId(keys.undelivered, minted.id);
+    await context.persistScopeIds();
+    const value = {
+        id: minted.id,
+        clientId: minted.clientId,
+        clientSecret: minted.clientSecret,
+    };
+    let stored = false;
+    for (let attempt = 1; attempt <= HOLD_DELIVERY_ATTEMPTS && !stored; attempt++) {
+        try {
+            await call('hold the service token', () => put(ref, JSON.stringify(value)));
+            stored = true;
+        }
+        catch {
+            // Retried; the cause may echo the secret and is dropped.
+        }
+    }
+    if (!stored) {
+        throw new Error(`${at}: service token ${minted.id} could not be held after ${HOLD_DELIVERY_ATTEMPTS} attempts; delete the token in Cloudflare and clear the recorded id before minting again`);
+    }
+    context.recordScopeId(keys.token, minted.id);
+    context.recordScopeId(keys.undelivered, '');
+    await context.persistScopeIds();
+    return value;
+}
+/** Deletes the entry's Hyperdrive config, found by the recorded name, and clears the record. */
+export async function deleteWorkerAppHyperdrive(port, entryKey, recorded, context, call) {
+    const raw = recorded[workerAppHyperdriveScopeKey(entryKey)];
+    if (!raw)
+        return;
+    let name;
+    try {
+        name = JSON.parse(raw).name;
+    }
+    catch {
+        name = undefined;
+    }
+    if (!name)
+        return;
+    if (!port) {
+        throw new Error(`the Hyperdrive config ${name} is recorded and this executor was built without a WorkerAppDatabasePort; cannot delete it`);
+    }
+    const hyperdrive = name;
+    await call('delete the Hyperdrive config', () => port.deleteHyperdrive(hyperdrive));
+    if (context) {
+        context.recordScopeId(workerAppHyperdriveScopeKey(entryKey), '');
+        await context.persistScopeIds();
+    }
+}
+const isGone = (error) => error?.status === 404;
+/** Runs `task`; an answer of "already gone" (404) counts as done, so a rerun converges. */
+async function tolerateGone(task) {
+    try {
+        await task();
+    }
+    catch (error) {
+        if (!isGone(error))
+            throw error;
+    }
+}
+/**
+ * Removes the Cloudflare state the database route made, in the order that never leaves a name
+ * pointing at nothing: the DNS record, the tunnel rule (the tunnel config is rewritten without
+ * it), the Access app, the service token (also one minted and never delivered), then the held
+ * token and runtime password and the recorded ids. Each step tolerates "already gone", and the
+ * ids are cleared last, so a failed run is repeated by the next one. With `context` null (org
+ * destroy) the ids are not cleared: destroy drops them with the org.
+ */
+export async function deleteWorkerAppDatabaseRoute(database, heldKeys, orgId, entryKey, recorded, context, call) {
+    const keys = remoteDatabaseKeys(entryKey);
+    const route = recorded[keys.route];
+    const accessApp = recorded[keys.access];
+    const tokens = [recorded[keys.token], recorded[keys.undelivered]].filter((id) => Boolean(id));
+    if (!route && !accessApp && tokens.length === 0)
+        return;
+    if (!database) {
+        throw new Error('the database route is recorded and this executor was built without a WorkerAppDatabasePort; cannot delete it');
+    }
+    if (route) {
+        let hostname;
+        try {
+            hostname = JSON.parse(route).hostname;
+        }
+        catch {
+            hostname = undefined;
+        }
+        if (typeof hostname === 'string' && hostname.includes('.')) {
+            // The hostname is `<label>-hd.<zone apex>`, one label deep.
+            const zone = await call('find the zone', () => database.zones.findZoneByApex(hostname.slice(hostname.indexOf('.') + 1)));
+            if (zone) {
+                const records = await call('look for the DNS record', () => database.dns.findDnsRecord(zone.name, hostname, 'CNAME'));
+                for (const record of records) {
+                    if (!record.content.endsWith('.cfargotunnel.com'))
+                        continue;
+                    await call('delete the DNS record', () => tolerateGone(() => database.dns.deleteDnsRecord(zone.name, record.id)));
+                }
+            }
+        }
+        const tunnelId = recorded[`cloudflare:tunnel:${orgId}`];
+        if (tunnelId) {
+            const without = { ...recorded, [keys.route]: '' };
+            await call('remove the tunnel route', () => tolerateGone(() => database.tunnels.putTunnelConfig(tunnelId, {
+                ingress: mergeTcpIngress(recordedHttpIngress(without), recordedTcpRoutes(without)),
+            })));
+        }
+    }
+    if (accessApp) {
+        await call('delete the Access app', () => tolerateGone(() => database.access.deleteAccessApp(accessApp)));
+    }
+    for (const id of tokens) {
+        await call('delete the service token', () => tolerateGone(() => database.access.removeServiceToken(id)));
+    }
+    if (!context)
+        return;
+    // The store has no delete: an empty value reads as "not held", so a redeclared app mints again.
+    if (heldKeys?.put) {
+        const put = heldKeys.put;
+        for (const name of ['HYPERDRIVE_ACCESS', 'DATABASE_RT_PASSWORD']) {
+            await call('clear a held secret', () => put(workerAppSecretRef(orgId, entryKey, name), ''));
+        }
+    }
+    for (const key of [keys.route, keys.access, keys.token, keys.undelivered]) {
+        context.recordScopeId(key, '');
+    }
+    context.recordScopeId(workerAppDbRouteMarkerScopeKey(entryKey), '');
+    await context.persistScopeIds();
+}