@cosmicdrift/kumiko-server-runtime 0.403.0 → 0.404.1

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

@@ -9,13 +9,15 @@ import { assertRowLevelSecurityBootState, configureEntityFieldEncryption, knownT
 import { createRegistry, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
 import { createWorkerEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { DEFAULT_ROW_LEVEL_SECURITY_MODE } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
+import { maintenanceWindowFromEnv } from "@cosmicdrift/kumiko-framework/jobs";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
-import { createRedisCacheSyncBus, redisClientOptionsFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
+import { createRedisCacheSyncBus, redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
 import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { Redis } from "ioredis";
+import { readShutdownDrainTimeoutMs } from "../boot-options/process-signals.js";
 import { composeFeatures } from "../compose-features.js";
 import { assertPiiBootInvariants } from "../pii-boot-gate.js";
 import { readEnv, requireEnv } from "../require-env.js";
@@ -64,6 +66,9 @@ export async function bootWorkerProcess(options, envSource, profile) {
     await ensureTemporalPolyfill();
     const databaseUrl = requireEnv("DATABASE_URL", envSource, processName);
     const redisUrl = requireEnv("REDIS_URL", envSource, processName);
+    const redisNamespace = redisNamespaceFromEnv(envSource);
+    const maintenanceWindow = maintenanceWindowFromEnv(envSource);
+    const shutdownDrainTimeoutMs = readShutdownDrainTimeoutMs(envSource);
     const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
     const rowLevelSecurity = options.rowLevelSecurity ?? DEFAULT_ROW_LEVEL_SECURITY_MODE;
     // MUST be composed with the same `includeBundled` as the API process.
@@ -102,10 +107,17 @@ export async function bootWorkerProcess(options, envSource, profile) {
         await waitForKmsHealthy(options.kms, processName, databaseWaitDeadline, options.databaseWait);
     }
     const { db, closeDb, outsideTransactionDb, closeOutsideTransactionDb } = openDatabasePools(databaseUrl, envSource, rowLevelSecurity);
-    const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    const redis = new Redis(redisUrl, {
+        maxRetriesPerRequest: null,
+        keyPrefix: redisNamespace.keyPrefix,
+    });
     const cacheSync = createRedisCacheSyncBus({
         redisUrl,
         clientOptions: redisClientOptionsFromEnv(envSource),
+        channelPrefix: redisNamespace.channelPrefix,
+        ...(redisNamespace.channelSubscribePattern !== undefined && {
+            channelSubscribePattern: redisNamespace.channelSubscribePattern,
+        }),
     });
     try {
         await waitForDatabase(db, {
@@ -195,6 +207,8 @@ export async function bootWorkerProcess(options, envSource, profile) {
         eventDedup,
         ...(options.observability && { observability: options.observability }),
         redisUrl,
+        redisNamespace,
+        maintenanceWindow,
         ...jobLogger,
         ...(options.jobs?.queueNamePrefix !== undefined && {
             queueNamePrefix: options.jobs.queueNamePrefix,
@@ -225,7 +239,7 @@ export async function bootWorkerProcess(options, envSource, profile) {
         ...(isSecretsContext(extraContext["secrets"]) && { secrets: extraContext["secrets"] }),
         ...(bootCrypto.configCipher && { configCipher: bootCrypto.configCipher }),
         close: async () => {
-            await entrypoint.stop();
+            await entrypoint.stop(shutdownDrainTimeoutMs !== undefined ? { drainTimeoutMs: shutdownDrainTimeoutMs } : {});
             await closeDb();
             await closeOutsideTransactionDb();
             redis.disconnect();

package/dist/boot-options/process-signals.d.ts

@@ -5,6 +5,12 @@ export type SignalsOption = false | {
     readonly drainTimeoutMs?: number;
 };
 export declare const DEFAULT_DRAIN_TIMEOUT_MS = 25000;
+export declare const SHUTDOWN_DRAIN_TIMEOUT_ENV = "KUMIKO_SHUTDOWN_DRAIN_TIMEOUT_MS";
+/** Shared apps scaled to zero by KEDA need the drain to outlast their longest job. Unset: undefined.
+ *  An invalid value fails the boot instead of silently shortening the drain. */
+export declare function readShutdownDrainTimeoutMs(env: Readonly<Record<string, string | undefined>>): number | undefined;
+/** Explicit `signals.drainTimeoutMs` wins over the env variable, which wins over the default. */
+export declare function resolveDrainTimeoutMs(explicit: number | undefined, fromEnv: number | undefined): number;
 export type SignalProcess = {
     on(signal: ShutdownSignal, listener: () => void): unknown;
     off(signal: ShutdownSignal, listener: () => void): unknown;

package/dist/boot-options/process-signals.js

@@ -1,6 +1,23 @@
 // Kubernetes sends SIGKILL after terminationGracePeriodSeconds (default 30 s).
 // Draining 25 s leaves room for the exit and the final log line before that.
 export const DEFAULT_DRAIN_TIMEOUT_MS = 25_000;
+export const SHUTDOWN_DRAIN_TIMEOUT_ENV = "KUMIKO_SHUTDOWN_DRAIN_TIMEOUT_MS";
+/** Shared apps scaled to zero by KEDA need the drain to outlast their longest job. Unset: undefined.
+ *  An invalid value fails the boot instead of silently shortening the drain. */
+export function readShutdownDrainTimeoutMs(env) {
+    const raw = env[SHUTDOWN_DRAIN_TIMEOUT_ENV]?.trim();
+    if (raw === undefined || raw === "")
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`[env] ${SHUTDOWN_DRAIN_TIMEOUT_ENV}="${raw}" must be a positive integer`);
+    }
+    return parsed;
+}
+/** Explicit `signals.drainTimeoutMs` wins over the env variable, which wins over the default. */
+export function resolveDrainTimeoutMs(explicit, fromEnv) {
+    return explicit ?? fromEnv ?? DEFAULT_DRAIN_TIMEOUT_MS;
+}
 /** Registers SIGTERM/SIGINT: the first signal drains via `stop()` and exits
  *  0, a drain that fails or outlives the timeout exits 1. Returns the
  *  uninstall function so `stop()` can drop the listeners again. */

package/dist/run-prod-app-config.d.ts

@@ -1,7 +1,9 @@
 import { loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
 import type { RowLevelSecurityMode } from "@cosmicdrift/kumiko-framework/db";
 import { type FeatureDefinition, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { type MaintenanceWindow } from "@cosmicdrift/kumiko-framework/jobs";
 import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
+import { type RedisNamespace } from "@cosmicdrift/kumiko-framework/redis";
 import { resolveBootCrypto } from "./boot/boot-crypto.ts";
 import { type BootOptionWiring } from "./boot-options/resolve-boot-options.ts";
 import { resolveRateLimit } from "./rate-limit-defaults.ts";
@@ -18,6 +20,9 @@ export type ProdBootConfig = {
     readonly databaseUrl: string;
     readonly rowLevelSecurity: RowLevelSecurityMode;
     readonly redisUrl: string;
+    readonly redisNamespace: RedisNamespace;
+    readonly maintenanceWindow: MaintenanceWindow;
+    readonly shutdownDrainTimeoutMs: number | undefined;
     readonly jwtSecret: string;
     readonly jwtSecretOrKeyring: ReturnType<typeof loadJwtSecretOrKeyring>;
     readonly jwtIssuer: string | undefined;

package/dist/run-prod-app-config.js

@@ -3,9 +3,12 @@ import { SESSIONS_FEATURE } from "@cosmicdrift/kumiko-bundled-features/sessions"
 import { loadJwtSecretOrKeyring, TRUSTED_PROXY_HOPS_ENV } from "@cosmicdrift/kumiko-framework/api";
 import { createRegistry, } from "@cosmicdrift/kumiko-framework/engine";
 import { DEFAULT_ROW_LEVEL_SECURITY_MODE } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
+import { maintenanceWindowFromEnv, } from "@cosmicdrift/kumiko-framework/jobs";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { redisNamespaceFromEnv } from "@cosmicdrift/kumiko-framework/redis";
 import { resolveBootCrypto } from "./boot/boot-crypto.js";
 import { composeAppFeatures, validateComposedFeatures, withEnvDefaults, } from "./boot/shared-boot-steps.js";
+import { readShutdownDrainTimeoutMs } from "./boot-options/process-signals.js";
 import { resolveBootOptionWiring, } from "./boot-options/resolve-boot-options.js";
 import { assertStackBootRequirements } from "./boot-options/stack-boot-requirements.js";
 import { assertPiiBootInvariants } from "./pii-boot-gate.js";
@@ -61,6 +64,9 @@ export async function resolveProdBootConfig(options, decryptedEnvSource, log, re
     // configured.
     const databaseUrl = requireEnv("DATABASE_URL", envSource);
     const redisUrl = requireEnv("REDIS_URL", envSource);
+    const redisNamespace = redisNamespaceFromEnv(envSource);
+    const maintenanceWindow = maintenanceWindowFromEnv(envSource);
+    const shutdownDrainTimeoutMs = readShutdownDrainTimeoutMs(envSource);
     // JWT_SECRET stays mandatory (also the resolveAuthMail hmacSecret
     // fallback below — a separate, non-rotating HMAC token family, not the
     // session JWT). jwtSecretOrKeyring is the OPTIONAL upgrade: set
@@ -103,6 +109,9 @@ export async function resolveProdBootConfig(options, decryptedEnvSource, log, re
         databaseUrl,
         rowLevelSecurity: options.rowLevelSecurity ?? DEFAULT_ROW_LEVEL_SECURITY_MODE,
         redisUrl,
+        redisNamespace,
+        maintenanceWindow,
+        shutdownDrainTimeoutMs,
         jwtSecret,
         jwtSecretOrKeyring,
         jwtIssuer,

package/dist/run-prod-app-connections.d.ts

@@ -1,6 +1,6 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
-import { createRedisCacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
+import { createRedisCacheSyncBus, type RedisNamespace } from "@cosmicdrift/kumiko-framework/redis";
 import { Redis } from "ioredis";
 import { type DatabaseWaitClock } from "./boot/wait-for-database.ts";
 import type { RunProdAppOptions } from "./run-prod-app.ts";
@@ -11,6 +11,7 @@ export type ProdConnections = {
     readonly outsideTransactionDb: DbConnection;
     readonly closeOutsideTransactionDb: () => Promise<void>;
     readonly redis: Redis;
+    readonly redisNamespace: RedisNamespace;
     readonly cacheSync: ReturnType<typeof createRedisCacheSyncBus>;
 };
 export declare function connectProdDependencies(config: ProdBootConfig, log: Logger, registerAbortCleanup: RegisterBootAbortCleanup, databaseWait?: DatabaseWaitClock): Promise<ProdConnections>;

package/dist/run-prod-app-connections.js

@@ -8,7 +8,7 @@ import { WAIT_FOR_DATABASE_DEADLINE_MS, waitForDatabase, } from "./boot/wait-for
 // immediately. `new Redis(...)` connects eagerly, so this must stay AFTER the
 // boot-mode exit.
 export async function connectProdDependencies(config, log, registerAbortCleanup, databaseWait) {
-    const { bootKms, databaseUrl, redisUrl, envSource, rowLevelSecurity } = config;
+    const { bootKms, databaseUrl, redisUrl, redisNamespace, envSource, rowLevelSecurity } = config;
     // KMS health gate: an app configured for crypto-shredding must not boot
     // against an unreachable key store — a silent start would answer every
     // PII read with 503. Runs BEFORE connections so an abort leaks nothing.
@@ -17,7 +17,10 @@ export async function connectProdDependencies(config, log, registerAbortCleanup,
         await waitForKmsHealthy(bootKms.kms, "runProdApp", databaseWaitDeadline, databaseWait);
     }
     const pools = openDatabasePools(databaseUrl, envSource, rowLevelSecurity);
-    const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+    const redis = new Redis(redisUrl, {
+        maxRetriesPerRequest: null,
+        keyPrefix: redisNamespace.keyPrefix,
+    });
     registerAbortCleanup(pools.closeDb);
     registerAbortCleanup(pools.closeOutsideTransactionDb);
     registerAbortCleanup(() => redis.disconnect());
@@ -32,8 +35,12 @@ export async function connectProdDependencies(config, log, registerAbortCleanup,
     const cacheSync = createRedisCacheSyncBus({
         redisUrl,
         clientOptions: redisClientOptionsFromEnv(envSource),
+        channelPrefix: redisNamespace.channelPrefix,
+        ...(redisNamespace.channelSubscribePattern !== undefined && {
+            channelSubscribePattern: redisNamespace.channelSubscribePattern,
+        }),
     });
-    return { ...pools, redis, cacheSync };
+    return { ...pools, redis, redisNamespace, cacheSync };
 }
 // Schema-drift gate (without drizzle, using kumiko/migrations). `kumiko
 // schema apply` runs as a deploy step before container rollout. Boot only

package/dist/run-prod-app-entrypoint.js

@@ -54,10 +54,12 @@ export function buildProdEntrypointOptions(options, config, composed, connection
         }),
     };
 }
-function prodJobOptions(options, composed, connections) {
+function prodJobOptions(options, composed, connections, config) {
     const queueNamePrefix = options.jobs?.queueNamePrefix;
     return {
         ...jobRunLoggerCallbacks(composed.registry, connections.db),
+        redisNamespace: connections.redisNamespace,
+        maintenanceWindow: config.maintenanceWindow,
         ...(queueNamePrefix !== undefined && { queueNamePrefix }),
         ...(options.jobs?.getActiveTenantIds !== undefined && {
             getActiveTenantIds: options.jobs.getActiveTenantIds,
@@ -76,7 +78,7 @@ function prodJobOptions(options, composed, connections) {
 export function createProdEntrypoint(options, config, composed, connections, entrypointOptions) {
     const runSingleInstance = options.runSingleInstance ?? options.eventDispatcher?.disabled !== true;
     const hasJobs = composed.registry.getAllJobs().size > 0;
-    const jobOptions = prodJobOptions(options, composed, connections);
+    const jobOptions = prodJobOptions(options, composed, connections, config);
     const dispatcherTunables = options.eventDispatcher?.pollIntervalMs !== undefined
         ? { pollIntervalMs: options.eventDispatcher.pollIntervalMs }
         : {};

package/dist/run-prod-app-handle.js

@@ -1,6 +1,6 @@
 import { assertNoActiveRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/db";
 import { flushEscapeHatchAudits } from "@cosmicdrift/kumiko-framework/pipeline";
-import { installShutdownSignals } from "./boot-options/process-signals.js";
+import { installShutdownSignals, resolveDrainTimeoutMs } from "./boot-options/process-signals.js";
 import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options.js";
 import { installFatalErrorHandlers } from "./fatal-error-handlers.js";
 import { uninstallProcessLogger } from "./process-logger.js";
@@ -49,6 +49,10 @@ export function createProdAppHandle(input) {
     // Same read-only demo gate as fetchHandler: upgrade requests are GETs, but the socket then writes.
     const securedUpgradeFetch = withSecurityHeaders(config.bootOptionWiring.wrapFetch(async (req, env) => stripNoRouteMatchHeader(await entrypoint.app.fetch(req, env))), options.securityHeaders, cspScriptHashes);
     const webSocketUpgradeFetch = async (req, env) => securedUpgradeFetch(req, env);
+    const explicitDrainTimeoutMs = options.signals === false ? undefined : options.signals?.drainTimeoutMs;
+    const drainTimeoutMs = resolveDrainTimeoutMs(explicitDrainTimeoutMs, config.shutdownDrainTimeoutMs);
+    // Without a configured budget the lifecycle keeps its own default for programmatic stop().
+    const jobDrainTimeoutMs = explicitDrainTimeoutMs ?? config.shutdownDrainTimeoutMs;
     let uninstallShutdownSignals;
     let uninstallFatalHandlers;
     const handle = {
@@ -75,9 +79,7 @@ export function createProdAppHandle(input) {
                 uninstallShutdownSignals?.();
                 uninstallShutdownSignals = installShutdownSignals({
                     stop: () => handle.stop(),
-                    ...(options.signals?.drainTimeoutMs !== undefined && {
-                        drainTimeoutMs: options.signals.drainTimeoutMs,
-                    }),
+                    drainTimeoutMs,
                 });
                 uninstallFatalHandlers?.();
                 uninstallFatalHandlers = installFatalErrorHandlers({
@@ -90,7 +92,8 @@ export function createProdAppHandle(input) {
         stop: async () => {
             uninstallFatalHandlers?.();
             uninstallFatalHandlers = undefined;
-            await entrypoint.stop();
+            // Jobs finish before the HTTP grace period, the DB and Redis close (all below this line).
+            await entrypoint.stop(jobDrainTimeoutMs !== undefined ? { drainTimeoutMs: jobDrainTimeoutMs } : {});
             if (handle.server)
                 await stopServerGracefully(handle.server);
             await flushEscapeHatchAudits();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.403.0",
+  "version": "0.404.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 tooling.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -96,12 +96,12 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.403.0",
-    "@cosmicdrift/kumiko-framework": "0.403.0",
-    "@cosmicdrift/kumiko-renderer": "0.403.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.403.0",
-    "@cosmicdrift/kumiko-types": "0.403.0",
-    "ioredis": "^5.10.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.404.1",
+    "@cosmicdrift/kumiko-framework": "0.404.1",
+    "@cosmicdrift/kumiko-renderer": "0.404.1",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.404.1",
+    "@cosmicdrift/kumiko-types": "0.404.1",
+    "ioredis": "^5.11.1",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.6.7"
   },
@@ -109,7 +109,7 @@
     "bun-types": "^1.4.4"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.403.0",
+    "@cosmicdrift/kumiko-testing": "0.404.1",
     "bun-types": "^1.4.4"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "runProdApp and runWorkerApp use the Redis prefix and drain running jobs on SIGTERM",
+    "detail": "Both boots pass the namespace to the Redis client, the cache-sync bus and the job runner, so enqueuer and consumer share one key space. KUMIKO_SHUTDOWN_DRAIN_TIMEOUT_MS (positive integer, invalid aborts the boot) sets the drain budget; signals.drainTimeoutMs wins, the default stays 25 s. Entrypoint stop() now stops every job lane fetching first, then waits for active jobs up to that budget before the database and Redis close; before, the lifecycle's fixed 40 s cut the wait short."
+  },
   {
     "version": "0.399.0",
     "type": "fix",