@cosmicdrift/kumiko-server-runtime 0.364.0 → 0.365.1

package/dist/boot/wait-for-database.d.ts

@@ -0,0 +1,13 @@
+import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+export declare function isTransientConnectionError(error: unknown): boolean;
+export declare const WAIT_FOR_DATABASE_INITIAL_BACKOFF_MS = 1000;
+export declare const WAIT_FOR_DATABASE_MAX_BACKOFF_MS = 15000;
+export declare const WAIT_FOR_DATABASE_DEADLINE_MS = 90000;
+export type WaitForDatabaseOptions = {
+    readonly processName: string;
+    readonly log?: (line: string) => void;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly now?: () => number;
+};
+export declare function waitForDatabase(db: DbConnection, options: WaitForDatabaseOptions): Promise<void>;
+export declare function waitUntilDatabaseReachable<T>(ping: () => Promise<T>, options: WaitForDatabaseOptions): Promise<T>;

package/dist/boot/wait-for-database.js

@@ -0,0 +1,64 @@
+import { extractPgError, tableExists } from "@cosmicdrift/kumiko-framework/db";
+const TRANSIENT_CODES = new Set([
+    "53300", // too_many_connections
+    "57P03", // cannot_connect_now (startup / recovery)
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "CONNECTION_CLOSED",
+    "CONNECT_TIMEOUT",
+    "CONNECTION_DESTROYED",
+    "ERR_POSTGRES_CONNECTION_REFUSED", // Bun.SQL
+    "ERR_POSTGRES_CONNECTION_CLOSED", // Bun.SQL
+    "ERR_POSTGRES_CONNECTION_TIMEOUT", // Bun.SQL
+    "ERR_POSTGRES_CONNECTION_FAILED", // Bun.SQL
+]);
+const CONNECTION_EXCEPTION_CLASS = "08";
+export function isTransientConnectionError(error) {
+    const code = extractPgError(error)?.code;
+    if (code === undefined)
+        return false;
+    return TRANSIENT_CODES.has(code) || code.startsWith(CONNECTION_EXCEPTION_CLASS);
+}
+export const WAIT_FOR_DATABASE_INITIAL_BACKOFF_MS = 1_000;
+export const WAIT_FOR_DATABASE_MAX_BACKOFF_MS = 15_000;
+// ponytail: the kubelet liveness probe restarts a pod without an open port after ~105s anyway,
+// so waiting longer buys nothing. Upgrade: make this configurable via env once a deployment
+// needs a longer outage window (e.g. a managed-DB failover that takes minutes).
+export const WAIT_FOR_DATABASE_DEADLINE_MS = 90_000;
+function logToConsole(line) {
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+    console.log(line);
+}
+function sleepReal(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Postgres can be briefly unreachable at boot (connection slots exhausted, failover, restart).
+// Crashing makes the orchestrator restart-loop and adds connection churn; wait and retry instead.
+export async function waitForDatabase(db, options) {
+    await waitUntilDatabaseReachable(() => tableExists(db, "pg_catalog.pg_class"), options);
+}
+export async function waitUntilDatabaseReachable(ping, options) {
+    const { processName, log = logToConsole, sleep = sleepReal, now = Date.now } = options;
+    const deadline = now() + WAIT_FOR_DATABASE_DEADLINE_MS;
+    let backoffMs = WAIT_FOR_DATABASE_INITIAL_BACKOFF_MS;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await ping();
+        }
+        catch (error) {
+            if (!isTransientConnectionError(error))
+                throw error;
+            const remainingMs = deadline - now();
+            if (remainingMs <= 0)
+                throw error;
+            const waitMs = Math.min(backoffMs, remainingMs);
+            const code = extractPgError(error)?.code ?? "unknown";
+            log(`[${processName}] database not reachable (code ${code}, attempt ${attempt}), retrying in ${waitMs}ms…`);
+            await sleep(waitMs);
+            backoffMs = Math.min(backoffMs * 2, WAIT_FOR_DATABASE_MAX_BACKOFF_MS);
+        }
+    }
+}

package/dist/boot/worker-boot-core.js

@@ -6,7 +6,7 @@
 import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
 import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
-import { createRegistry, findTierResolverUsage, isTierResolverPlugin, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createWorkerEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
@@ -20,6 +20,7 @@ import { requireEnv } from "../run-prod-app.js";
 import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, } from "../run-prod-app-boot-context.js";
 import { resolveBootCrypto } from "./boot-crypto.js";
 import { jobRunLoggerCallbacks } from "./job-run-logger.js";
+import { waitForDatabase, waitUntilDatabaseReachable } from "./wait-for-database.js";
 import { assertWorkerMetricsOptions } from "./worker-metrics-server.js";
 function isSecretsContext(value) {
     if (typeof value !== "object" || value === null)
@@ -39,11 +40,7 @@ async function buildTierEffectiveFeatures(features, db, registry, cacheSync) {
     const tierResolverUsage = findTierResolverUsage(features);
     if (!tierResolverUsage)
         return undefined;
-    const plugin = tierResolverUsage.options;
-    if (!isTierResolverPlugin(plugin)) {
-        throw new Error("tier-resolver registration options must provide a build() factory");
-    }
-    return plugin.build({ db, registry, cacheSync });
+    return requireTierResolverPlugin(tierResolverUsage).build({ db, registry, cacheSync });
 }
 async function assertWorkerSchemaCurrent(db, migrationsDir, processName) {
     const dir = migrationsDir ?? "./kumiko/migrations";
@@ -100,7 +97,10 @@ export async function bootWorkerProcess(options, envSource, profile) {
     }
     // Before the connections, so an abort leaks nothing.
     if (options.kms) {
-        const kmsHealth = await options.kms.health();
+        const kms = options.kms;
+        const kmsHealth = await waitUntilDatabaseReachable(() => kms.health(), {
+            processName: processName,
+        });
         if (!kmsHealth.ok) {
             throw new Error(`[${processName}] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
         }
@@ -112,6 +112,16 @@ export async function bootWorkerProcess(options, envSource, profile) {
         redisUrl,
         clientOptions: redisClientOptionsFromEnv(envSource),
     });
+    try {
+        await waitForDatabase(db, { processName });
+    }
+    catch (err) {
+        await closeDb();
+        await closeOutsideTransactionDb();
+        redis.disconnect();
+        await cacheSync.close();
+        throw err;
+    }
     const resolvedEffectiveFeatures = options.effectiveFeatures ??
         (await buildTierEffectiveFeatures(features, db, registry, cacheSync));
     if (options.migrations !== false) {

package/dist/compose-features.js

@@ -15,16 +15,15 @@
 import { AUTH_SELF_REGISTRATION_FEATURE, createAuthEmailPasswordFeature, createAuthSelfRegistrationToggleFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
 import { AUTH_MFA_FEATURE, mfaStatusCheckerFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
-import { createFilesTenantDataFeature } from "@cosmicdrift/kumiko-bundled-features/files-tenant-data";
+import { createFilesTenantDataFeature, FILES_TENANT_DATA_FEATURE, } from "@cosmicdrift/kumiko-bundled-features/files-tenant-data";
 import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
 import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import { collectAssignableAppRoles, createTenantFeature, } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { TENANT_LIFECYCLE_FEATURE } from "@cosmicdrift/kumiko-bundled-features/tenant-lifecycle";
 import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
 import { dedupeFeatures } from "@cosmicdrift/kumiko-framework/engine";
+import { FILES_FEATURE } from "@cosmicdrift/kumiko-framework/files";
 import { createRendererMailHtmlFeature } from "@cosmicdrift/kumiko-renderer-mail-html";
-const FILES_FEATURE = "files";
-const FILES_TENANT_DATA_FEATURE = "files-tenant-data";
 export function composeFeatures(appFeatures, options) {
     // ponytail: includeBundled:false skips the auth-mfa auto-wiring below —
     // an app composing its own foundation and mounting auth-mfa itself is

package/dist/run-bootstrap.d.ts

@@ -9,5 +9,7 @@ export type RunBootstrapOptions = Omit<RunWorkerAppOptions, "wireComponents" | "
 };
 /** Returns the report, or undefined in KUMIKO_DRY_RUN_ENV=boot mode. Without
  *  an injected `envSource` (a real process) it exits the process when done,
- *  so a k8s Job never hangs on a leftover socket. */
+ *  so a k8s Job never hangs on a leftover socket. A SystemAdmin invite that
+ *  came out `role-mismatch` or `cancelled` fails the run (exit code 1, or a
+ *  thrown error with an injected `envSource`). */
 export declare function runBootstrap(options: RunBootstrapOptions): Promise<BootstrapReport | undefined>;

package/dist/run-bootstrap.js

@@ -19,6 +19,12 @@ function maskEmailForLog(email) {
     const at = email.indexOf("@");
     return at <= 0 ? "***" : `${email[0]}***${email.slice(at)}`;
 }
+// An admin invite that can never grant its global role leaves the first deployment without
+// a SystemAdmin; a green Job would hide that.
+function unprovisionedGlobalRoleInvites(report) {
+    return report.invites.filter((invite) => invite.globalRoles.length > 0 &&
+        (invite.outcome === "role-mismatch" || invite.outcome === "cancelled"));
+}
 function logBootstrapReport(report) {
     for (const tenant of report.tenants) {
         // biome-ignore lint/suspicious/noConsole: the report IS the deliverable of a one-shot process
@@ -32,7 +38,9 @@ function logBootstrapReport(report) {
 }
 /** Returns the report, or undefined in KUMIKO_DRY_RUN_ENV=boot mode. Without
  *  an injected `envSource` (a real process) it exits the process when done,
- *  so a k8s Job never hangs on a leftover socket. */
+ *  so a k8s Job never hangs on a leftover socket. A SystemAdmin invite that
+ *  came out `role-mismatch` or `cancelled` fails the run (exit code 1, or a
+ *  thrown error with an injected `envSource`). */
 export async function runBootstrap(options) {
     const envSource = await resolveWorkerEnvSource(options, PROCESS_NAME);
     const jwtSecret = requireEnv("JWT_SECRET", envSource, PROCESS_NAME);
@@ -68,6 +76,15 @@ export async function runBootstrap(options) {
         await boot.close();
     }
     logBootstrapReport(report);
+    const unprovisioned = unprovisionedGlobalRoleInvites(report);
+    if (unprovisioned.length > 0) {
+        const message = `[${PROCESS_NAME}] ${unprovisioned.length} invite(s) cannot grant their global role (${unprovisioned.map((invite) => `${maskEmailForLog(invite.email)}: ${invite.outcome}`).join(", ")})`;
+        if (options.envSource !== undefined)
+            throw new Error(message);
+        // biome-ignore lint/suspicious/noConsole: the failure reason of a one-shot process
+        console.error(message);
+        process.exit(1);
+    }
     // biome-ignore lint/suspicious/noConsole: boot-time progress hint
     console.log(`[${PROCESS_NAME}] done.`);
     if (options.envSource === undefined) {

package/dist/run-prod-app-boot-context.js

@@ -115,15 +115,22 @@ function createBootConfigResolver(registry, envSource, crypto) {
         ...(crypto.configCipher && { cipher: crypto.configCipher }),
     });
 }
+// The delivery service reads tenant config too (tenant name/locale in mail
+// layouts), so apps without auth still get a resolver for it; the ctx entry
+// stays auth-only.
+function resolveDeliveryConfigResolver(opts, hasDeliveryFeature, crypto) {
+    return opts.hasAuth || hasDeliveryFeature
+        ? createBootConfigResolver(opts.registry, opts.envSource, crypto)
+        : undefined;
+}
 export function buildBootExtraContext(opts) {
     const crypto = opts.crypto ?? resolveBootCrypto(opts.envSource, opts.masterKey);
     const hasDeliveryFeature = opts.features.some((f) => f.name === DELIVERY_FEATURE);
     const hasTenantFeature = opts.features.some((f) => f.name === TENANT_FEATURE);
     const escapeHatchAuditSink = resolveEscapeHatchAuditSink(opts.features, opts.db);
     const secrets = resolveBootSecrets(opts.db, opts.features, crypto, opts.registry);
-    const configResolver = opts.hasAuth
-        ? createBootConfigResolver(opts.registry, opts.envSource, crypto)
-        : undefined;
+    const bootConfigResolver = resolveDeliveryConfigResolver(opts, hasDeliveryFeature, crypto);
+    const configResolver = opts.hasAuth ? bootConfigResolver : undefined;
     return {
         templateResolver: createTemplateResolverApi(opts.db),
         ...(opts.kms && { kms: opts.kms }),
@@ -138,7 +145,7 @@ export function buildBootExtraContext(opts) {
                 ...(escapeHatchAuditSink && { escapeHatchAuditSink }),
                 ...(opts.log && { log: opts.log }),
                 ...(hasTenantFeature && { tenantUserIdsQuery: TenantQueries.resolveUserIds }),
-                configResolver,
+                configResolver: bootConfigResolver,
                 deliverQueuedInline: opts.deliverQueuedInline,
             }),
         }),

package/dist/run-prod-app.js

@@ -48,10 +48,10 @@ import { SECRETS_MASTER_KEK_ENV_KEYS } from "@cosmicdrift/kumiko-bundled-feature
 import { SESSIONS_FEATURE } from "@cosmicdrift/kumiko-bundled-features/sessions";
 import { TenantQueries } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import { UserQueries } from "@cosmicdrift/kumiko-bundled-features/user";
-import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, } from "@cosmicdrift/kumiko-framework/api";
+import { createDefaultSseBroker, createRedisLoginRateLimiter, loadJwtSecretOrKeyring, parseTrustedProxyHopsEnv, TRUSTED_PROXY_HOPS_ENV, withFileProviderResolver, } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
 import { configureEntityFieldEncryption, createDbConnection, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/db";
-import { collectWriteHandlerQns, createRegistry, findTierResolverUsage, isTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { collectWriteHandlerQns, createRegistry, findTierResolverUsage, requireTierResolverPlugin, validateAppCustomScreenWriteQns, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createAllInOneEntrypoint, createApiEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { KumikoBootError, kmsSlotsOf, parseEnv, withOptionalEnvKeys, } from "@cosmicdrift/kumiko-framework/env";
 import { renderDryRun } from "@cosmicdrift/kumiko-framework/env/dry-run";
@@ -67,6 +67,7 @@ import { resolveBootCrypto } from "./boot/boot-crypto.js";
 import { jobRunLoggerCallbacks } from "./boot/job-run-logger.js";
 import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
 import { recordAppStartedOnBoot } from "./boot/record-app-started-on-boot.js";
+import { waitForDatabase, waitUntilDatabaseReachable } from "./boot/wait-for-database.js";
 import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options.js";
 import { buildComposeAuthOptions, composeFeatures } from "./compose-features.js";
 import { makeDispatchSystemWrite } from "./extra-routes-deps.js";
@@ -336,7 +337,10 @@ export async function runProdApp(options) {
     // against an unreachable key store — a silent start would answer every
     // PII read with 503. Runs BEFORE connections so an abort leaks nothing.
     if (options.kms) {
-        const kmsHealth = await options.kms.health();
+        const kms = options.kms;
+        const kmsHealth = await waitUntilDatabaseReachable(() => kms.health(), {
+            processName: "runProdApp",
+        });
         if (!kmsHealth.ok) {
             throw new Error(`[runProdApp] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`);
         }
@@ -344,6 +348,7 @@ export async function runProdApp(options) {
     const { db, close: closeDb } = createDbConnection(databaseUrl, dbConnectionOptionsFromEnv(envSource));
     const { db: outsideTransactionDb, close: closeOutsideTransactionDb } = createDbConnection(databaseUrl, outsideTransactionPoolOptionsFromEnv(envSource));
     const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    await waitForDatabase(db, { processName: "runProdApp" });
     // Sprint-8a Tier-Composition auto-wire: scan features for a
     // tenantTierResolver-extension. If found AND user didn't supply own
     // effectiveFeatures, build the resolver here (db + registry are
@@ -359,11 +364,11 @@ export async function runProdApp(options) {
     if (resolvedEffectiveFeatures === undefined) {
         const tierResolverUsage = findTierResolverUsage(features);
         if (tierResolverUsage) {
-            const plugin = tierResolverUsage.options;
-            if (!isTierResolverPlugin(plugin)) {
-                throw new Error("tier-resolver registration options must provide a build() factory");
-            }
-            resolvedEffectiveFeatures = await plugin.build({ db, registry, cacheSync });
+            resolvedEffectiveFeatures = await requireTierResolverPlugin(tierResolverUsage).build({
+                db,
+                registry,
+                cacheSync,
+            });
         }
     }
     // 5. Schema-Drift-Gate (drizzle-frei, kumiko/migrations). `kumiko schema
@@ -469,6 +474,11 @@ export async function runProdApp(options) {
     // über die auth-routes.
     // Secure-by-default (#1372): sessionStore provider → resolveSessionStore.
     const mfaFeature = features.find((f) => f.name === AUTH_MFA_FEATURE);
+    if (mfaFeature && registry.getWriteHandler(AuthHandlers.switchTenantMfaGate) === undefined) {
+        throw new Error(`[runProdApp] auth-mfa is mounted but ${AuthHandlers.switchTenantMfaGate} is not registered: ` +
+            "createAuthEmailPasswordFeature registers it only when mfaStatusChecker is set, and without it " +
+            "POST /auth/switch-tenant would mint sessions without the second factor");
+    }
     // Hoisted above buildProdSessionAuth: that call also wires MFA-enable/
     // disable → PAT-revoke (bindRevokeAllPatTokensFromFeature), so it needs
     // patFeature too.
@@ -692,7 +702,7 @@ export async function runProdApp(options) {
         ...(bootCrypto.configCipher && { cipher: bootCrypto.configCipher }),
     });
     const seedDispatcher = (options.seeds?.length ?? 0) > 0 || options.seedsDir !== undefined
-        ? createDispatcher(registry, { db, redis, entityCache, registry, ...extraContext })
+        ? createDispatcher(registry, withFileProviderResolver(registry, { db, redis, entityCache, registry, ...extraContext }, cacheSync))
         : undefined;
     if (seedDispatcher) {
         for (const seed of options.seeds ?? []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.364.0",
+  "version": "0.365.1",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -84,12 +84,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.364.0",
-    "@cosmicdrift/kumiko-framework": "0.364.0",
-    "@cosmicdrift/kumiko-headless": "0.364.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.364.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.364.0",
-    "@cosmicdrift/kumiko-types": "0.364.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.365.1",
+    "@cosmicdrift/kumiko-framework": "0.365.1",
+    "@cosmicdrift/kumiko-headless": "0.365.1",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.365.1",
+    "@cosmicdrift/kumiko-renderer-web": "0.365.1",
+    "@cosmicdrift/kumiko-types": "0.365.1",
     "bun-types": "^1.3.13",
     "ioredis": "^5.10.1",
     "temporal-polyfill": "^0.3.2"

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Bootstrap fails when a global-role invite cannot be provisioned; delivery notify works without auth",
+    "detail": "runBootstrap now fails with a non-zero exit when an invite with global roles ends role-mismatch or cancelled. The delivery notify factory gets a config resolver also when the app has no auth feature."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Seeds can create fileRefs through handlers that use createFileRefFromBytes",
+    "detail": "The seed dispatcher built its handler context without the file provider resolver, so a write handler invoked via systemWriteAs failed with \"createFileRefFromBytes: ctx.files is unavailable\". The seed context now carries the same file provider as the HTTP path."
+  },
   {
     "version": "0.363.0",
     "type": "improvement",