fix(realtime-transcription): bound inbound websocket payloads (#102443)

sunlit-deng · steipete · web-flow · commit e635cdbbe941 · 2026-07-09T11:39:22.000+01:00
* fix(realtime-transcription): bound inbound websocket payloads

* test(realtime-transcription): tighten payload cap proof

---------

Co-authored-by: Peter Steinberger &lt;steipete@gmail.com&gt;
diff --git a/src/realtime-transcription/websocket-session.test.ts b/src/realtime-transcription/websocket-session.test.ts
@@ -4,7 +4,10 @@ import type { AddressInfo } from "node:net";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type WebSocket from "ws";
 import { WebSocketServer } from "ws";
-import { createRealtimeTranscriptionWebSocketSession } from "./websocket-session.js";
+import {
+  createRealtimeTranscriptionWebSocketSession,
+  REALTIME_TRANSCRIPTION_WS_MAX_PAYLOAD_BYTES,
+} from "./websocket-session.js";
 
 let cleanup: (() => Promise<void>) | undefined;
 
@@ -403,4 +406,64 @@ describe("createRealtimeTranscriptionWebSocketSession", () => {
     expect(closeError).toBeInstanceOf(Error);
     expect(closeError.message).toBe("test realtime transcription connection closed before ready");
   });
+
+  it("delivers a legitimate large inbound message below the payload cap", async () => {
+    // Well above any real transcript message yet far under the 16 MiB cap: proves
+    // the bound does not reject legitimate large provider traffic.
+    const largeText = "x".repeat(2 * 1024 * 1024);
+    const server = await createRealtimeServer({
+      initialEvent: { type: "transcript", text: largeText },
+    });
+    const onMessage = vi.fn();
+    const session = createRealtimeTranscriptionWebSocketSession<{ type?: string; text?: string }>({
+      providerId: "test",
+      callbacks: {},
+      url: server.url,
+      readyOnOpen: true,
+      onMessage,
+      sendAudio: (audio, transport) => {
+        transport.sendBinary(audio);
+      },
+    });
+
+    await session.connect();
+    await vi.waitFor(() => {
+      expect(onMessage).toHaveBeenCalledTimes(1);
+    });
+    const event = requireFirstMockArg(onMessage, "large inbound message");
+    expect(event).toEqual({ type: "transcript", text: largeText });
+    session.close();
+  });
+
+  it("drops an oversized inbound message before it reaches the provider parser", async () => {
+    // ws rejects a message above maxPayload with an error + 1009 close, so an
+    // oversized upstream message never reaches onMessage/JSON parse.
+    const oversized = "x".repeat(REALTIME_TRANSCRIPTION_WS_MAX_PAYLOAD_BYTES + 1);
+    const server = await createRealtimeServer({ initialText: oversized });
+    const onError = vi.fn();
+    const onMessage = vi.fn(() => {
+      throw new Error("oversized frame should not reach provider handler");
+    });
+    const session = createRealtimeTranscriptionWebSocketSession({
+      providerId: "test",
+      callbacks: { onError },
+      url: server.url,
+      readyOnOpen: true,
+      onMessage,
+      sendAudio: (audio, transport) => {
+        transport.sendBinary(audio);
+      },
+    });
+
+    await session.connect();
+    await vi.waitFor(() => {
+      expect(onError).toHaveBeenCalledTimes(1);
+    });
+    expect(onMessage).not.toHaveBeenCalled();
+    const overflowError = requireFirstMockArg(onError, "oversized inbound message error");
+    expect(overflowError).toBeInstanceOf(Error);
+    expect(overflowError).toHaveProperty("code", "WS_ERR_UNSUPPORTED_MESSAGE_LENGTH");
+    expect(overflowError.message).toMatch(/max payload/i);
+    session.close();
+  });
 });
diff --git a/src/realtime-transcription/websocket-session.ts b/src/realtime-transcription/websocket-session.ts
@@ -50,6 +50,10 @@ const DEFAULT_CLOSE_TIMEOUT_MS = 5_000;
 const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
 const DEFAULT_RECONNECT_DELAY_MS = 1000;
 const DEFAULT_MAX_QUEUED_BYTES = 2 * 1024 * 1024;
+// Bound inbound messages before ws buffers them for JSON parsing. The 16 MiB cap
+// matches realtime voice; ws rejects larger messages with close 1009 before
+// they reach onMessage, replacing its 100 MiB client default.
+export const REALTIME_TRANSCRIPTION_WS_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
 
 function rawWsDataToBuffer(data: RawData): Buffer {
   if (Buffer.isBuffer(data)) {
@@ -249,6 +253,7 @@ class WebSocketRealtimeTranscriptionSession<Event> implements RealtimeTranscript
         try {
           this.ws = new WebSocket(this.currentUrl, {
             headers: connection.headers,
+            maxPayload: REALTIME_TRANSCRIPTION_WS_MAX_PAYLOAD_BYTES,
             ...(proxyAgent ? { agent: proxyAgent } : {}),
           });
         } catch (error) {
