@cosmicdrift/kumiko-framework 0.340.0 → 0.341.0

package/dist/redis/index.d.ts

@@ -1,3 +1,7 @@
+export type { CacheSyncBus, CacheSyncBusOverSignalOptions, ClosableCacheSyncBus, RedisCacheSyncBusOptions, ResolvedCacheSyncBus, } from "./cache-sync-bus.js";
+export { createCacheSyncBusOverSignal, createDefaultCacheSyncBus, createLocalCacheSyncBus, createRedisCacheSyncBus, resolveCacheSyncBus, } from "./cache-sync-bus.js";
+export type { TenantConfigSyncMessage, TierAssignmentSyncMessage } from "./cache-sync-topics.js";
+export { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage, isTierAssignmentSyncMessage, } from "./cache-sync-topics.js";
 export type { RedisClientOptions } from "./client.js";
 export { createRedisClient, redisClientOptionsFromEnv } from "./client.js";
 export type { PubSubSignal, PubSubSignalOptions } from "./pubsub-signal.js";

package/dist/redis/index.js

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

package/dist/redis/pubsub-signal.d.ts

@@ -2,6 +2,7 @@ import { type RedisClientOptions } from "./client.js";
 export type PubSubSignal = {
     publish(channel: string, payload: unknown): void;
     onMessage(listener: (channel: string, payload: unknown) => void): void;
+    onReconnect(listener: () => void): void;
     close(): Promise<void>;
 };
 export type PubSubSignalOptions = {

package/dist/redis/pubsub-signal.js

@@ -14,6 +14,7 @@ export function createRedisPubSubSignal(opts) {
     publisher.on("error", logConnectionError(opts.label, "publisher"));
     subscriber.on("error", logConnectionError(opts.label, "subscriber"));
     const listeners = new Set();
+    const reconnectListeners = new Set();
     // Sole purpose: stop close() from racing the initial psubscribe (see
     // below) and silence its logging once a shutdown is already underway —
     // not a defense against ioredis auto-reconnecting later (quit() below
@@ -56,6 +57,30 @@ export function createRedisPubSubSignal(opts) {
         // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
         console.error(`[kumiko:${opts.label}] psubscribe failed:`, err);
     });
+    // ioredis re-sends the psubscribe itself (autoResubscribe) but emits no ack
+    // event; repeating it here queues behind that one on the same connection,
+    // so its reply means the subscription is live again.
+    let hasBeenReady = false;
+    subscriber.on("ready", () => {
+        if (!hasBeenReady) {
+            hasBeenReady = true;
+            // skip: the first ready is the initial connect, not a reconnect
+            return;
+        }
+        subscriber.psubscribe(opts.channelPattern).then(() => {
+            // skip: close() ran while the resubscribe was in flight
+            if (closed)
+                return;
+            for (const listener of reconnectListeners)
+                listener();
+        }, (err) => {
+            // skip: a close() already underway intentionally quit the connection
+            if (closed)
+                return;
+            // biome-ignore lint/suspicious/noConsole: ops-visible fallback, see logConnectionError above.
+            console.error(`[kumiko:${opts.label}] resubscribe failed:`, err);
+        });
+    });
     return {
         publish(channel, payload) {
             publisher.publish(channel, JSON.stringify(payload)).catch((err) => {
@@ -70,6 +95,9 @@ export function createRedisPubSubSignal(opts) {
         onMessage(listener) {
             listeners.add(listener);
         },
+        onReconnect(listener) {
+            reconnectListeners.add(listener);
+        },
         async close() {
             closed = true;
             await initialSubscribe;

package/dist/stack/redis.d.ts

@@ -9,4 +9,9 @@ export type TestRedis = {
     cleanup: () => Promise<void>;
 };
 export declare function queueNamePrefixForTestRedis(keyPrefix: string): string;
-export declare function createTestRedis(): Promise<TestRedis>;
+export type CreateTestRedisOptions = {
+    /** Reuse another stack's keyPrefix on a fresh connection. cleanup() then only
+     *  disconnects — the owning stack flushes the namespace and its queues. */
+    readonly borrowKeyPrefix?: string;
+};
+export declare function createTestRedis(opts?: CreateTestRedisOptions): Promise<TestRedis>;

package/dist/stack/redis.js

@@ -6,13 +6,13 @@ import { requireEnv } from "./db.js";
 export function queueNamePrefixForTestRedis(keyPrefix) {
     return keyPrefix.split(":").filter(Boolean).join("-");
 }
-export async function createTestRedis() {
+export async function createTestRedis(opts = {}) {
     const Redis = (await import("ioredis")).Redis;
     const redisUrl = requireEnv("REDIS_URL");
     // Every test gets a per-file key prefix on a shared DB (no DB-pool-of-15
     // round-robin). Collisions at birthday-paradox rates are gone — the
     // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
-    const prefix = `kt:${generateId().slice(-8)}:`;
+    const prefix = opts.borrowKeyPrefix ?? `kt:${generateId().slice(-8)}:`;
     const redis = new Redis(redisUrl, { keyPrefix: prefix });
     async function deleteKeysMatching(pattern) {
         // Open a prefix-less client for the scan — ioredis' keyPrefix is applied
@@ -38,6 +38,11 @@ export async function createTestRedis() {
         keyPrefix: prefix,
         flushNamespace,
         cleanup: async () => {
+            if (opts.borrowKeyPrefix !== undefined) {
+                redis.disconnect();
+                // skip: the owning stack flushes the shared namespace and its queues
+                return;
+            }
             await flushNamespace();
             // The derived per-stack JobRunner queues sit outside the keyPrefix.
             await deleteKeysMatching(`bull:${queueNamePrefixForTestRedis(prefix)}-*`);

package/dist/stack/test-stack.d.ts

@@ -7,6 +7,7 @@ import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import { type ObservabilityProvider } from "../observability/index.js";
 import type { Dispatcher, EventDispatcher } from "../pipeline/index.js";
+import { type ClosableCacheSyncBus } from "../redis/cache-sync-bus.js";
 import type { SearchAdapter } from "../search/types.js";
 import { type EventCollector } from "./event-collector.js";
 import { type TestRedis } from "./redis.js";
@@ -17,6 +18,7 @@ export type TestStack = {
     registry: Registry;
     db: import("../db/index.js").DbConnection;
     redis: TestRedis;
+    cacheSync: ClosableCacheSyncBus;
     search: SearchAdapter;
     events: EventCollector;
     http: RequestHelper;
@@ -157,5 +159,18 @@ export type TestStackOptions = {
     /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
      *  — see there. Default 0. */
     trustedProxyHops?: number;
+    /** Second stack on the Redis namespace of `owner`: own connection, same
+     *  keyPrefix, so rate-limit buckets, locks, idempotency keys and the
+     *  cache-sync channel are shared across both. The derived
+     *  queueNamePrefix is identical too, so both stacks share BullMQ queues.
+     *  Cleanup only disconnects; the owner flushes the namespace and queues, so
+     *  clean up the borrowing stack first. The DB is NOT shared — pass the same
+     *  `dbName` + `persistentDb` for that. */
+    sharedRedisWith?: TestStack;
+    /** Publish/receive cache invalidations (tenant timezone, file providers,
+     *  tier sets) over Redis Pub/Sub, namespaced by this stack's keyPrefix.
+     *  Implied by `sharedRedisWith`; set it on the owner stack too, or its writes
+     *  never reach the borrower. Without it the stack uses a process-local bus. */
+    cacheSync?: boolean;
 };
 export declare function setupTestStack(options: TestStackOptions): Promise<TestStack>;

package/dist/stack/test-stack.js

@@ -7,6 +7,7 @@ import { createJobRunner } from "../jobs/index.js";
 import { createNoopProvider } from "../observability/index.js";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, dispatcherToWriteRef, } from "../pipeline/index.js";
 import { createRateLimitResolver } from "../rate-limit/index.js";
+import { createLocalCacheSyncBus, createRedisCacheSyncBus, } from "../redis/cache-sync-bus.js";
 import { createInMemorySearchAdapter } from "../search/index.js";
 import { createTestDb } from "./db.js";
 import { createJobFailureTracker, drainJobs } from "./drain-jobs.js";
@@ -39,7 +40,7 @@ export async function setupTestStack(options) {
             ...(options.dbName !== undefined && { dbName: options.dbName }),
             ...(options.persistentDb !== undefined && { persistent: options.persistentDb }),
         }),
-        createTestRedis(),
+        createTestRedis(options.sharedRedisWith && { borrowKeyPrefix: options.sharedRedisWith.redis.keyPrefix }),
     ]);
     // Any throw in this DDL region must still drop the just-created ephemeral
     // DB/Redis — the caller never gets the stack object back to call
@@ -103,6 +104,16 @@ export async function setupTestStack(options) {
         }
         throw error;
     }
+    // Redis only where two stacks can actually disagree (avoids two extra
+    // Pub/Sub connections); otherwise a local bus so invalidation still works
+    // inside this stack. Passing it explicitly keeps buildServer from using its
+    // REDIS_URL default (an unnamespaced channel).
+    const cacheSync = options.cacheSync || options.sharedRedisWith
+        ? createRedisCacheSyncBus({
+            redisUrl: testRedis.redisUrl,
+            channelPrefix: testRedis.keyPrefix,
+        })
+        : createLocalCacheSyncBus();
     const searchAdapter = createInMemorySearchAdapter();
     const events = createEventCollector();
     const registry = createRegistry([...options.features]);
@@ -262,6 +273,7 @@ export async function setupTestStack(options) {
             ...(options.observability ? { observability: options.observability } : {}),
             dispatcherOptions: {
                 idempotency,
+                cacheSync,
                 ...(options.effectiveFeatures && { effectiveFeatures: options.effectiveFeatures }),
                 ...(jobRunner && { jobRunner }),
             },
@@ -338,6 +350,7 @@ export async function setupTestStack(options) {
             registry,
             db: testDb.db,
             redis: testRedis,
+            cacheSync,
             search: searchAdapter,
             events,
             http,
@@ -355,6 +368,7 @@ export async function setupTestStack(options) {
                 if (eventDispatcher)
                     await eventDispatcher.stop();
                 await server.observability.shutdown();
+                await cacheSync.close();
                 await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
             },
         };
@@ -375,6 +389,12 @@ export async function setupTestStack(options) {
                 // ignore — `error` is the one that matters
             }
         }
+        try {
+            await cacheSync.close();
+        }
+        catch {
+            // ignore — `error` is the one that matters
+        }
         try {
             await testDb.cleanup();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.340.0",
+  "version": "0.341.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.340.0",
-    "@cosmicdrift/kumiko-types": "0.340.0",
+    "@cosmicdrift/kumiko-http": "0.341.0",
+    "@cosmicdrift/kumiko-types": "0.341.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.340.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.341.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,51 @@
 [
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "rowIdOf on extendEntityProjection for derived row ids",
+    "detail": "`r.extendEntityProjection` accepts `rowIdOf`, the row id the extension's applies write for events on its `sources` when that id is not the aggregate id (for example a tenant-salted `uuidv5(tenantId|aggregateId)` over workflow events). The ghost-row guard of the projection rebuild now counts a live row as backed when its id is `rowIdOf` of a source event, so such projections can be rebuilt instead of aborting. The guard stays strict: a row keyed by the raw aggregate id of a derived source still aborts the rebuild.\n`rowIdOf` requires `sources`, must not name the entity's own stream, and must return a uuid; a source shared by several extensions needs the same `rowIdOf` in all of them. Violations fail at boot. `ProjectionDefinition` carries the result as `extraSourceRowIds`, and `assertNoUnreachableLiveRows` takes it as an optional fifth parameter. New type `ProjectionRowIdOf`."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "CacheSyncBus keeps tier assignments and file providers in sync across pods",
+    "detail": "A Redis-backed CacheSyncBus (one channel, envelope with origin id, echo dropped, malformed messages ignored) now carries typed invalidation topics between pods and fires a debounced resync after a Redis reconnect. Tier assignments are published after commit and reloaded on the other pods with a per-tenant out-of-order guard; the tier cache is swapped atomically on resync. The file provider resolver drops cached providers when tenant config or secrets change on any pod. Prod, worker and dev entrypoints wire one bus per process, and TierResolverPlugin.build accepts an optional cacheSync."
+  },
+  {
+    "version": "0.341.0",
+    "type": "fix",
+    "title": "L3 rate-limit backend failure answers 503 rate_limit_unavailable instead of 500"
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "r.httpRoute rateLimit option",
+    "detail": "Per-IP limit enforced through the rate-limit resolver before the route guards; legal-pages and GET /user-export/by-token declare defaults."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "Tenant timezone cache is invalidated across processes",
+    "detail": "A config write to tenant:config:timezone now invalidates the cached value on every API and worker pod after commit, instead of letting it live until the 5 minute TTL. The signal travels over the new CacheSyncBus (Redis when REDIS_URL is set, process-local otherwise); DispatcherOptions.cacheSync overrides it and null opts out. setupTestStack gains cacheSync, implied by sharedRedisWith, to test two instances on one Redis. This replaces the earlier tenantTimezoneSync option."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "Per-recipient rate limits on payload fields (additionalRateLimits)",
+    "detail": "Write handlers can declare `additionalRateLimits: [{ per: { payloadField: \"email\" }, limit, windowSeconds }]` next to `rateLimit`. The named string field of the validated payload is trimmed, lowercased and HMAC-hashed (key derived from the server's current JWT signing secret) into the bucket key `payload+handler:<handler>:<field>:<digest>`, so one address is limited across all IPs and Redis never holds it in plaintext. The check runs after schema validation and before the handler, answers 429 `rate_limited`, behaves the same for matching and non-matching values, and is skipped for system callers. Rotating the JWT secret only resets these buckets.\nBoot rejects `additionalRateLimits` on an anonymous handler without a real ip-keyed `rateLimit` (the payload bucket only complements the IP bucket), an empty list, a `payloadField` that is not a field of the Zod object schema, and a non-positive `limit` or `windowSeconds`. A handler with `additionalRateLimits` makes `buildServer` wire the rate-limit resolver. The option exists on write handlers only and appears in the feature-ast patterns, render and patch schema.\nBehavior change: `request-contract-termination` and `signup-request` now allow 3 requests per email address per 24 hours, and each token-request endpoint (`request-password-reset`, `request-email-verification`, `request-account-unlock`) allows 5 per address per 24 hours, in addition to the existing per-IP limits. The public `/api/auth` token-request routes still answer `{ isSuccess: true }` when the limit is hit; only the mail is not sent."
+  },
+  {
+    "version": "0.341.0",
+    "type": "improvement",
+    "title": "429 bodies omit the payload bucket digest",
+    "detail": "A 429 caused by a payload bucket (`additionalRateLimits`) no longer carries the HMAC digest of the bucketed value in `details.bucket` or the error message: it reads `payload+handler`. The digest is a stable pseudonym of the address, so anyone who could guess an address could confirm it from the response. Redis keys are unchanged.\n`waitlist:write:submit` additionally limits each email address (case-insensitive) to 3 submits per day, across all IPs, so a botnet cannot flood one address with confirmation mails. `createWaitlistFeature({ emailRateLimits })` overrides it (`[]` disables). The admin notice mail now carries its `locale` (`en` or `de`) in the notify call."
+  },
+  {
+    "version": "0.341.0",
+    "type": "fix",
+    "title": "429 bodies carry only the rate-limit scope",
+    "detail": "429 bodies (`details.bucket` and the message) now carry only the bucket scope tag (`l1`, `http`, `l2`, `user`, `ip+handler`, `payload+handler`, ...) instead of IP, user/tenant id, auth target or payload digest. Fail-closed logging prints only the error message, since Redis errors can carry the bucket key. Redis keys are unchanged."
+  },
   {
     "version": "0.340.0",
     "type": "improvement",