@cosmicdrift/kumiko-framework 0.402.0 → 0.404.0

package/dist/redis/cache-sync-bus.js

@@ -1,5 +1,5 @@
 import { createFallbackLogger } from "../logging/utils.js";
-import { redisClientOptionsFromEnv } from "./client.js";
+import { redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "./client.js";
 import { createRedisPubSubSignal } from "./pubsub-signal.js";
 const log = createFallbackLogger("kumiko:cache-sync");
 const CACHE_SYNC_CHANNEL = "kumiko:cache-sync";
@@ -80,7 +80,10 @@ export function createCacheSyncBusOverSignal(signal, opts) {
     const resyncMinIntervalMs = opts.resyncMinIntervalMs ?? RESYNC_MIN_INTERVAL_MS;
     const now = opts.now ?? Date.now;
     const fanout = createLocalFanout();
-    signal.onMessage((_channel, payload) => {
+    signal.onMessage((channel, payload) => {
+        // skip: a wide subscribe pattern also delivers other features' channels
+        if (channel !== opts.channel)
+            return;
         // skip: foreign or malformed payload on the channel
         if (!isCacheSyncEnvelope(payload))
             return;
@@ -133,7 +136,7 @@ export function createRedisCacheSyncBus(opts) {
     const channel = `${opts.channelPrefix ?? ""}${CACHE_SYNC_CHANNEL}`;
     const signal = createRedisPubSubSignal({
         redisUrl: opts.redisUrl,
-        channelPattern: channel,
+        channelPattern: opts.channelSubscribePattern ?? channel,
         label: "cache-sync",
         ...(opts.clientOptions ? { clientOptions: opts.clientOptions } : {}),
     });
@@ -143,9 +146,15 @@ export function createRedisCacheSyncBus(opts) {
 // set it. Without it invalidation stays inside this process.
 export function createDefaultCacheSyncBus(envVars = process.env) {
     const redisUrl = envVars["REDIS_URL"];
-    return redisUrl
-        ? createRedisCacheSyncBus({ redisUrl, clientOptions: redisClientOptionsFromEnv(envVars) })
-        : createLocalCacheSyncBus();
+    if (!redisUrl)
+        return createLocalCacheSyncBus();
+    const { channelPrefix, channelSubscribePattern } = redisNamespaceFromEnv(envVars);
+    return createRedisCacheSyncBus({
+        redisUrl,
+        clientOptions: redisClientOptionsFromEnv(envVars),
+        channelPrefix,
+        ...(channelSubscribePattern !== undefined && { channelSubscribePattern }),
+    });
 }
 // An explicit bus wins (caller owns it), null opts out, undefined builds the default.
 export function resolveCacheSyncBus(explicit) {

package/dist/redis/client.d.ts

@@ -8,5 +8,17 @@ export type RedisClientOptions = {
 };
 export declare function createRedisClient(url: string, options?: RedisClientOptions): Redis;
 export declare function logRedisConnectionState(redis: Redis, logger: Pick<Logger, "warn" | "info">): void;
+export type RedisNamespace = {
+    /** ioredis keyPrefix for every non-BullMQ key; "" when unnamespaced. */
+    readonly keyPrefix: string;
+    /** BullMQ `prefix` option ("bull" is BullMQ's own default). BullMQ rejects an ioredis keyPrefix. */
+    readonly bullmqPrefix: string;
+    /** Prepended to every Pub/Sub channel (ioredis keyPrefix does not apply to Pub/Sub). */
+    readonly channelPrefix: string;
+    /** Set only with KUMIKO_REDIS_PREFIX. Redis checks PSUBSCRIBE patterns against `&` ACL rules literally,
+     *  so `P:kumiko:sse:*` is NOPERM under `&P:*`; subscribe to `P:*` and filter by channel instead. */
+    readonly channelSubscribePattern: string | undefined;
+};
+export declare function redisNamespaceFromEnv(env?: Readonly<Record<string, string | undefined>>): RedisNamespace;
 export declare function redisChannelPrefixFromEnv(env?: Readonly<Record<string, string | undefined>>): string;
 export declare function redisClientOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): RedisClientOptions;

package/dist/redis/client.js

@@ -46,12 +46,37 @@ export function logRedisConnectionState(redis, logger) {
         logger.info("redis recovered");
     });
 }
-// Redis Pub/Sub ignores the DB index and ioredis keyPrefix, so apps or environments sharing one
-// Redis instance would see each other's SSE and toggle-sync traffic. An optional prefix
-// namespaces those channels; unset keeps the unprefixed channel names.
+const BULLMQ_DEFAULT_PREFIX = "bull";
+// No ":" and no glob characters: the ACL rules `~<P>:*` / `&<P>:*` must not match a sibling app ("app-x" vs "app-x2:").
+const REDIS_PREFIX_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/;
+// KUMIKO_REDIS_PREFIX namespaces keys and channels for apps sharing one Redis behind per-app ACL users.
+// KUMIKO_REDIS_CHANNEL_PREFIX alone keeps its older channels-only behaviour.
+export function redisNamespaceFromEnv(env = process.env) {
+    const prefix = env["KUMIKO_REDIS_PREFIX"]?.trim();
+    const channelPrefix = env["KUMIKO_REDIS_CHANNEL_PREFIX"]?.trim();
+    if (!prefix) {
+        return {
+            keyPrefix: "",
+            bullmqPrefix: BULLMQ_DEFAULT_PREFIX,
+            channelPrefix: channelPrefix ? `${channelPrefix}:` : "",
+            channelSubscribePattern: undefined,
+        };
+    }
+    if (!REDIS_PREFIX_PATTERN.test(prefix)) {
+        throw new Error(`KUMIKO_REDIS_PREFIX "${prefix}" is invalid: use 1-63 characters of A-Z a-z 0-9 _ - starting with a letter or digit (no ":" or glob characters).`);
+    }
+    if (channelPrefix && channelPrefix !== prefix) {
+        throw new Error(`KUMIKO_REDIS_PREFIX "${prefix}" and KUMIKO_REDIS_CHANNEL_PREFIX "${channelPrefix}" differ; unset the channel prefix or make them equal.`);
+    }
+    return {
+        keyPrefix: `${prefix}:`,
+        bullmqPrefix: `${prefix}:${BULLMQ_DEFAULT_PREFIX}`,
+        channelPrefix: `${prefix}:`,
+        channelSubscribePattern: `${prefix}:*`,
+    };
+}
 export function redisChannelPrefixFromEnv(env = process.env) {
-    const raw = env["KUMIKO_REDIS_CHANNEL_PREFIX"]?.trim();
-    return raw ? `${raw}:` : "";
+    return redisNamespaceFromEnv(env).channelPrefix;
 }
 // Env-var reader — mirrors dbConnectionOptionsFromEnv's contract. Strict:
 // malformed values throw at boot rather than silently falling back to

package/dist/redis/index.d.ts

@@ -2,6 +2,6 @@ export type { CacheSyncBus, ClosableCacheSyncBus, } from "./cache-sync-bus.ts";
 export { createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, } from "./cache-sync-bus.ts";
 export type { TenantConfigSyncMessage, TierAssignmentSyncMessage } from "./cache-sync-topics.ts";
 export { CACHE_SYNC_TOPICS, isTierAssignmentSyncMessage, } from "./cache-sync-topics.ts";
-export type { RedisClientOptions } from "./client.ts";
-export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "./client.ts";
+export type { RedisClientOptions, RedisNamespace } from "./client.ts";
+export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "./client.ts";
 export { createRedisPubSubSignal } from "./pubsub-signal.ts";

package/dist/redis/index.js

@@ -1,4 +1,4 @@
 export { createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, } from "./cache-sync-bus.js";
 export { CACHE_SYNC_TOPICS, isTierAssignmentSyncMessage, } from "./cache-sync-topics.js";
-export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, } from "./client.js";
+export { createRedisClient, logRedisConnectionState, redisChannelPrefixFromEnv, redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "./client.js";
 export { createRedisPubSubSignal } from "./pubsub-signal.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.402.0",
+  "version": "0.404.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -203,7 +203,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.402.0",
+    "@cosmicdrift/kumiko-types": "0.404.0",
     "bullmq": "^5.76.7",
     "hono": "^4.13.14",
     "i18next": "^26.1.0",
@@ -225,7 +225,7 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.402.0",
+    "@cosmicdrift/kumiko-testing": "0.404.0",
     "bun-types": "^1.4.4",
     "fflate": "^0.8.3",
     "meilisearch": "^0.58.0",

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "Maintenance trigger and KUMIKO_MAINTENANCE_WINDOW",
+    "detail": "The job runner registers maintenance jobs as a daily UTC scheduler at JobRunnerOptions.maintenanceWindow (default 03:00), set from KUMIKO_MAINTENANCE_WINDOW by runProdApp and runWorkerApp; an invalid value aborts the boot. maintenanceWindowFromEnv is exported from the jobs barrel. files sweep-orphaned-uploads (hourly before) and the soft-delete cleanup jobs (03:00 and 03:15 before) now run in the window. A schedule stored with the old time is replaced on the next start."
+  },
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "KUMIKO_REDIS_PREFIX namespaces all Redis keys and channels",
+    "detail": "redisNamespaceFromEnv resolves keyPrefix, bullmqPrefix, channelPrefix and the subscribe pattern. Unset keeps today's layout (bull:*, unprefixed locks, rate limit, idempotency and cache keys). Set, the main ioredis client gets keyPrefix <P>:, the job runner passes prefix <P>:bull to every Queue and Worker (new JobRunnerOptions.redisNamespace, also on the entrypoint jobs block) and gives its lock client the keyPrefix, and the SSE broker, cache-sync bus and toggle signal use <P>: channels. Redis matches PSUBSCRIBE patterns literally against ACL channel rules, so with a prefix they subscribe to <P>:* and filter by channel. A value with \":\" or glob characters, or a KUMIKO_REDIS_CHANNEL_PREFIX that differs from it, aborts the boot. The cache-sync bus of runProdApp, runWorkerApp and createDefaultCacheSyncBus now also honours KUMIKO_REDIS_CHANNEL_PREFIX alone (before, only SSE and toggle channels did). JobRunner gains an optional stopConsuming(), which createJobRunner implements. The ACL rule set and the key layout for a wake-up service are in docs/reference/infra-requirements.md."
+  },
+  {
+    "version": "0.403.0",
+    "type": "improvement",
+    "title": "Entities define named list filters",
+    "detail": "createEntity takes namedFilters, a record of { access?, filters(scope) } where filters returns ListFilter conditions (sync or async). The default list query accepts namedFilter and appends the resolved conditions to filters, on the row path and the aggregate path. An unknown name is a validation error on namedFilter, a failed access rule is access_denied. resolveNamedListFilters is exported from the engine entry. The definition is function-valued and never reaches the client schema."
+  },
   {
     "version": "0.402.0",
     "type": "improvement",