@cosmicdrift/kumiko-renderer 0.403.0 → 0.404.0

package/dist/web/sse/live-events.d.ts

@@ -10,6 +10,8 @@ export type CreateEventSourceLiveEventsOptions = {
     readonly onSessionEnded?: () => void;
     /** Reconnect-timer seam; defaults to the global setTimeout/clearTimeout. */
     readonly timers?: LiveEventTimers;
+    /** Stall-watchdog timer seam; defaults to the global setTimeout/clearTimeout. */
+    readonly stallTimers?: LiveEventTimers;
     /** Jitter source in [0, 1); defaults to Math.random. */
     readonly random?: () => number;
     /** Clock for synthetic resync events; defaults to Date.now. */
@@ -21,6 +23,7 @@ export type LiveEventTimers = {
 };
 export declare const RECONNECT_BASE_DELAY_MS = 1000;
 export declare const RECONNECT_MAX_DELAY_MS = 30000;
+export declare const SSE_STALL_TIMEOUT_MS = 30000;
 export declare function reconnectDelayMs(attempt: number, random: number): number;
 /** Returns an EventSource-backed `LiveEventSubscriber`.
  *  Typically called once during app bootstrap and passed as a value to

package/dist/web/sse/live-events.js

@@ -3,6 +3,9 @@ import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { isSessionEndedError, LIVE_RESYNC_EVENT_TYPE, } from "../../index.js";
 export const RECONNECT_BASE_DELAY_MS = 1_000;
 export const RECONNECT_MAX_DELAY_MS = 30_000;
+// Two missed server heartbeats (15 s each, SSE_HEARTBEAT_INTERVAL_MS in framework sse-route.ts).
+// A KEDA interceptor can leave the stream hanging without an `error` event (kedacore/http-add-on#1803).
+export const SSE_STALL_TIMEOUT_MS = 30_000;
 const defaultTimers = {
     set: (callback, delayMs) => {
         const handle = setTimeout(callback, delayMs);
@@ -67,6 +70,7 @@ async function isSessionEndedRejection(url) {
 export function createEventSourceLiveEvents(options = {}) {
     const url = options.url ?? "/api/sse";
     const timers = options.timers ?? defaultTimers;
+    const stallTimers = options.stallTimers ?? defaultTimers;
     const random = options.random ?? Math.random;
     const now = options.now ?? Date.now;
     const subscribers = new Set();
@@ -74,6 +78,25 @@ export function createEventSourceLiveEvents(options = {}) {
     const wiredEntities = new Set();
     let cancelReconnect;
     let reconnectAttempt = 0;
+    let cancelStallWatchdog;
+    const disarmStallWatchdog = () => {
+        cancelStallWatchdog?.();
+        cancelStallWatchdog = undefined;
+    };
+    const armStallWatchdog = (connection) => {
+        // skip: a frame from a connection that is no longer the current one
+        if (source !== connection)
+            return;
+        disarmStallWatchdog();
+        cancelStallWatchdog = stallTimers.set(() => {
+            cancelStallWatchdog = undefined;
+            // skip: a late timer of a connection that was already replaced
+            if (source !== connection)
+                return;
+            connection.close();
+            scheduleReconnect();
+        }, SSE_STALL_TIMEOUT_MS);
+    };
     // `subscribers` is a flat Set across all entities — the browser-side
     // addEventListener(entityName, ...) gate below only filters which frames
     // arrive at all, not which subscriber a given frame is for. Without this
@@ -119,6 +142,7 @@ export function createEventSourceLiveEvents(options = {}) {
             return;
         connection.addEventListener(entityName, (e) => {
             const data = propertyOf(e, "data");
+            armStallWatchdog(connection);
             if (typeof data === "string")
                 handleEvent(data, entityName);
         });
@@ -142,14 +166,22 @@ export function createEventSourceLiveEvents(options = {}) {
             sessionEndedSignalled = true;
             onSessionEnded?.();
         };
+        armStallWatchdog(connection);
+        connection.addEventListener("ping", () => armStallWatchdog(connection));
         connection.addEventListener("open", () => {
+            armStallWatchdog(connection);
             reconnectAttempt = 0;
             emitResync();
         });
         connection.addEventListener(SESSION_ENDED_EVENT, (e) => {
             const code = sessionEndedFrameCode(e);
-            if (code !== undefined && isSessionEndedError({ code, httpStatus: 401 }))
+            if (code !== undefined && isSessionEndedError({ code, httpStatus: 401 })) {
+                disarmStallWatchdog();
                 signalSessionEnded();
+                // skip: a reconnect after a session end would only be refused again
+                return;
+            }
+            armStallWatchdog(connection);
         });
         connection.addEventListener("error", () => {
             // skip: CONNECTING means a dropped stream the browser retries itself;
@@ -161,10 +193,12 @@ export function createEventSourceLiveEvents(options = {}) {
                 if (source !== connection)
                     return;
                 if (sessionEnded) {
+                    disarmStallWatchdog();
                     signalSessionEnded();
                     // skip: the session ended, reconnecting would only be refused again
                     return;
                 }
+                disarmStallWatchdog();
                 scheduleReconnect();
             });
         });
@@ -196,6 +230,7 @@ export function createEventSourceLiveEvents(options = {}) {
             cancelReconnect = undefined;
         }
         reconnectAttempt = 0;
+        disarmStallWatchdog();
         // skip: already closed, nothing to close
         if (source === undefined)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.403.0",
+  "version": "0.404.0",
   "description": "React renderer for Kumiko screens. The root export holds the platform-agnostic logic (primitives contract, hooks, KumikoScreen, navigation and SSE abstractions); ./headless the DOM-free UI logic, ./live the HTTP dispatcher, ./web the browser bindings (HTML primitives, history navigation, EventSource live events, createKumikoApp).",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -48,8 +48,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.403.0",
-    "@cosmicdrift/kumiko-types": "0.403.0",
+    "@cosmicdrift/kumiko-framework": "0.404.0",
+    "@cosmicdrift/kumiko-types": "0.404.0",
     "@types/qrcode": "^1.5.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -79,8 +79,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.403.0",
-    "@cosmicdrift/kumiko-testing": "0.403.0",
+    "@cosmicdrift/kumiko-locale-de": "0.404.0",
+    "@cosmicdrift/kumiko-testing": "0.404.0",
     "@tailwindcss/cli": "^4.3.3",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.8",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "fix",
+    "title": "SSE client reconnects after a stalled stream",
+    "detail": "createEventSourceLiveEvents arms a 30 s watchdog (two missed server heartbeats) that is reset by open, ping and every entity or session-ended frame. On expiry it closes the connection and reconnects through the existing backoff path, which resyncs all listeners. The timer is cleared on close and error. The seam is the new stallTimers option."
+  },
   {
     "version": "0.403.0",
     "type": "improvement",