@cosmicdrift/kumiko-framework 0.328.1 → 0.329.0

package/dist/api/index.d.ts

@@ -29,4 +29,4 @@ export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";
 export { generateToken } from "./tokens.js";
 export type { KumikoServeEnv, KumikoServerWebSocket, KumikoWebSocketData, WebSocketUpgradeServer, } from "./websocket-route.js";
-export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";
+export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";

package/dist/api/index.js

@@ -17,4 +17,4 @@ export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from ".
 export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";
 export { generateToken } from "./tokens.js";
-export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";
+export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";

package/dist/api/websocket-route.d.ts

@@ -4,6 +4,7 @@ import { type AuthSessionChecker, type TenantLifecycleStatusResolver } from "./a
 import { type RequestContextData } from "./request-context.js";
 export { WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, };
 export declare const WEBSOCKET_HEARTBEAT_INTERVAL_MS = 25000;
+export declare const WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES: number;
 export declare const WEBSOCKET_REVALIDATION_FAILURE_LIMIT = 3;
 export type KumikoWebSocketData = {
     readonly handlers: WebSocketSessionHandlers;

package/dist/api/websocket-route.js

@@ -9,6 +9,9 @@ const CLOSE_POLICY_VIOLATION = 1008;
 const CLOSE_MESSAGE_TOO_BIG = 1009;
 const CLOSE_INTERNAL_ERROR = 1011;
 const CLOSE_TRY_AGAIN_LATER = 1013;
+// Frames queue behind a slow onOpen or onMessage; without a byte cap a client
+// could grow that queue unbounded.
+export const WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES = 1024 * 1024;
 // Consecutive failed session-store checks before a socket is closed: rides out a
 // short store blip, but a socket must not stay unverified forever.
 export const WEBSOCKET_REVALIDATION_FAILURE_LIMIT = 3;
@@ -87,6 +90,7 @@ function stateOf(ws) {
             revalidating: false,
             chain: Promise.resolve(),
             closed: false,
+            pendingMessageBytes: 0,
             controller: new AbortController(),
         };
         connectionStates.set(ws.data, state);
@@ -112,22 +116,25 @@ function runInRequestContext(ws, run) {
     const { requestContextData } = ws.data;
     return requestContextData ? requestContext.run(requestContextData, run) : run();
 }
-function enqueue(ws, run) {
+function enqueue(ws, run, onSettled) {
     const state = stateOf(ws);
     // skip: the socket is gone, nothing may start after close
     if (state.closed)
         return;
     const step = async () => {
-        // skip: queued behind a slower handler and the socket closed meanwhile
-        if (state.closed)
-            return;
         try {
+            // skip: queued behind a slower handler and the socket closed meanwhile
+            if (state.closed)
+                return;
             await run();
         }
         catch (error) {
             reportHandlerFailure(error);
             ws.close(CLOSE_INTERNAL_ERROR, "internal error");
         }
+        finally {
+            onSettled?.();
+        }
     };
     state.chain = state.chain.then(() => runInRequestContext(ws, step));
 }
@@ -208,9 +215,33 @@ export function createKumikoWebSocketHandler(options = {}) {
                 });
                 return;
             }
+            const state = stateOf(ws);
+            // skip: overflowed or closed socket, late frames are dropped
+            if (state.closed)
+                return;
+            state.pendingMessageBytes += byteLength;
+            const pendingLimit = Math.max(WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, ws.data.maxMessageBytes);
+            if (state.pendingMessageBytes > pendingLimit) {
+                // Marks the socket closed right away so already-queued frames never start.
+                state.closed = true;
+                ws.close(CLOSE_TRY_AGAIN_LATER, "try again later");
+                log.warn("websocket pending buffer over cap", {
+                    pendingBytes: state.pendingMessageBytes,
+                    limitBytes: pendingLimit,
+                });
+                return;
+            }
             const { onMessage } = ws.data.handlers;
-            if (onMessage)
-                enqueue(ws, () => onMessage(toMessageData(message), toConnection(ws)));
+            if (onMessage) {
+                // Copy now: queued behind a slow handler, Bun may have reused the buffer by then.
+                const data = toMessageData(message);
+                enqueue(ws, () => onMessage(data, toConnection(ws)), () => {
+                    state.pendingMessageBytes -= byteLength;
+                });
+            }
+            else {
+                state.pendingMessageBytes -= byteLength;
+            }
         },
         close(ws, code, reason) {
             const state = stateOf(ws);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.328.1",
+  "version": "0.329.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.328.1",
-    "@cosmicdrift/kumiko-types": "0.328.1",
+    "@cosmicdrift/kumiko-http": "0.329.0",
+    "@cosmicdrift/kumiko-types": "0.329.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.328.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.329.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.329.0",
+    "type": "improvement",
+    "title": "WebSocket routes cap the bytes queued behind slow handlers",
+    "detail": "Frames that arrive while `onOpen` or an earlier `onMessage` is still running are queued in order. Their summed size is now limited to 1 MiB (`WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES`, or the route's `maxMessageBytes` if larger); beyond that the socket closes with code 1013 and the queued frames are dropped."
+  },
   {
     "version": "0.328.1",
     "type": "improvement",