@cosmicdrift/kumiko-framework 0.236.0 → 0.236.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.236.0",
+  "version": "0.236.1",
   "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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.236.0",
+    "@cosmicdrift/kumiko-types": "0.236.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.236.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.236.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/redis-sse-broker.integration.test.ts

@@ -2,7 +2,12 @@ import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test
 import { createTestRedis, type TestRedis } from "../../stack";
 import { waitFor } from "../../testing/wait-for";
 import { generateId } from "../../utils";
-import { createRedisSseBroker, type RedisSseBroker } from "../redis-sse-broker";
+import {
+  createDefaultSseBroker,
+  createRedisSseBroker,
+  isRedisSseBroker,
+  type RedisSseBroker,
+} from "../redis-sse-broker";
 import type { SseEvent } from "../sse-broker";
 
 let testRedis: TestRedis;
@@ -149,3 +154,35 @@ describe("createRedisSseBroker", () => {
     }
   });
 });
+
+describe("createDefaultSseBroker", () => {
+  test("builds a Redis-backed broker under REDIS_URL that participates in cross-pod fanout", async () => {
+    const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker({
+      REDIS_URL: testRedis.redisUrl,
+    });
+    expect(ownedRedisSseBroker).toBeDefined();
+    expect(isRedisSseBroker(sseBroker)).toBe(true);
+    if (ownedRedisSseBroker) brokers.push(ownedRedisSseBroker);
+
+    const otherPod = trackedBroker();
+    const channel = `default-broker-${generateId()}`;
+    const received: SseEvent[] = [];
+    otherPod.addClient(
+      channel,
+      (event) => received.push(event),
+      () => {},
+    );
+
+    await waitFor(() => {
+      sseBroker.pushToChannel(channel, { type: "unit.updated", data: { id: "1" } });
+      return received.length >= 1;
+    });
+    expect(received[0]).toEqual({ type: "unit.updated", data: { id: "1" } });
+  });
+
+  test("falls back to the in-memory broker without REDIS_URL", () => {
+    const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker({});
+    expect(ownedRedisSseBroker).toBeUndefined();
+    expect(isRedisSseBroker(sseBroker)).toBe(false);
+  });
+});

package/src/api/index.ts

@@ -42,7 +42,7 @@ export type { JwtHelper, JwtKeyring, JwtPayload } from "./jwt";
 export { createJwtHelper, loadJwtSecretOrKeyring } from "./jwt";
 export { patAllows, qnMatches } from "./pat-scope";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker";
-export { createRedisSseBroker } from "./redis-sse-broker";
+export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker } from "./redis-sse-broker";
 export { type RequestContextData, requestContext } from "./request-context";
 export { requestIdMiddleware } from "./request-id-middleware";
 export { createApiRoutes } from "./routes";

package/src/api/redis-sse-broker.ts

@@ -22,6 +22,34 @@ export type RedisSseBroker = SseBroker & {
   close(): Promise<void>;
 };
 
+// The one property RedisSseBroker adds over SseBroker — cheap and reliable
+// to narrow on, so callers that only hold an SseBroker (e.g. a test that
+// pulled it back out of a generic ServerOptions.sseBroker slot) can tell
+// which lifecycle they own without an unsound `as` cast.
+export function isRedisSseBroker(broker: SseBroker): broker is RedisSseBroker {
+  return "close" in broker;
+}
+
+// Single decision point for "which SseBroker should a caller default to
+// when it doesn't inject its own": REDIS_URL present → cross-replica
+// Redis-backed broker, absent → the in-memory one. Both buildServer and
+// runProdApp must funnel through this rather than each deciding on their
+// own — runProdApp doing exactly that (building an in-memory broker
+// unconditionally, then passing it in as ServerOptions.sseBroker) is why
+// fw#2625's fanout fix (fw#2630) shipped without ever taking effect in
+// production: an explicit ServerOptions.sseBroker always wins in
+// buildServer, so its own REDIS_URL-based default never ran.
+export function createDefaultSseBroker(env: Record<string, string | undefined> = process.env): {
+  readonly sseBroker: SseBroker;
+  // Present only when REDIS_URL resolved. undefined means the fallback
+  // in-memory broker was used, which has nothing to release on shutdown.
+  readonly ownedRedisSseBroker: RedisSseBroker | undefined;
+} {
+  const redisUrl = env["REDIS_URL"];
+  const ownedRedisSseBroker = redisUrl ? createRedisSseBroker({ redisUrl }) : undefined;
+  return { sseBroker: ownedRedisSseBroker ?? createSseBroker(), ownedRedisSseBroker };
+}
+
 function isSseEvent(value: unknown): value is SseEvent {
   return (
     typeof value === "object" &&

package/src/api/server.ts

@@ -57,7 +57,7 @@ import { createJwtHelper, type JwtHelper, type JwtKeyring } from "./jwt";
 import { observabilityMiddleware } from "./observability-middleware";
 import { assertOriginGuardConfig, originMiddleware } from "./origin-middleware";
 import { piiCiphertextResponseGuard } from "./pii-leak-guard";
-import { createRedisSseBroker } from "./redis-sse-broker";
+import { createDefaultSseBroker, type RedisSseBroker } from "./redis-sse-broker";
 import { requestContext } from "./request-context";
 import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware";
 import {
@@ -68,7 +68,7 @@ import {
   registerVersionRoute,
 } from "./route-registrars";
 import { createApiRoutes } from "./routes";
-import { createSseBroker, type SseBroker } from "./sse-broker";
+import type { SseBroker } from "./sse-broker";
 import { createSseRoute } from "./sse-route";
 
 export type ServerOptions = {
@@ -318,17 +318,19 @@ export function buildServer(options: ServerOptions): KumikoServer {
     options.jwtTtl ?? defaultJwtTtl,
   );
   // An explicit ServerOptions.sseBroker always wins (caller owns its
-  // lifecycle). Otherwise, REDIS_URL decides the default: without
-  // cross-replica fanout, replicas > 1 silently drops SSE/access-
-  // invalidation events for whichever pod didn't win the shared cursor
-  // (fw#2625) — the safe default has to be the correct one, not the
-  // single-process one.
-  const ownedRedisSseBroker = options.sseBroker
-    ? undefined
-    : process.env["REDIS_URL"]
-      ? createRedisSseBroker({ redisUrl: process.env["REDIS_URL"] })
-      : undefined;
-  const sseBroker = options.sseBroker ?? ownedRedisSseBroker ?? createSseBroker();
+  // lifecycle) — createDefaultSseBroker is the single decision point every
+  // other caller must funnel through instead of picking a broker on its
+  // own, so the REDIS_URL-gated cross-replica default (fw#2625) can't be
+  // silently bypassed the way runProdApp bypassed it before this existed.
+  let sseBroker: SseBroker;
+  let ownedRedisSseBroker: RedisSseBroker | undefined;
+  if (options.sseBroker) {
+    sseBroker = options.sseBroker;
+  } else {
+    const defaults = createDefaultSseBroker();
+    sseBroker = defaults.sseBroker;
+    ownedRedisSseBroker = defaults.ownedRedisSseBroker;
+  }
 
   // Resolve the per-process instance identifier. Prefer explicit
   // ServerOptions.instanceId (tests, deliberate wiring), fall back to the