@openclaw/voice-call 2026.3.13 → 2026.5.2-beta.1

package/src/media-stream.test.ts

@@ -1,33 +1,52 @@
-import { once } from "node:events";
-import http from "node:http";
-import { describe, expect, it } from "vitest";
-import { WebSocket } from "ws";
-import { MediaStreamHandler } from "./media-stream.js";
+import type { IncomingMessage } from "node:http";
+import net from "node:net";
 import type {
-  OpenAIRealtimeSTTProvider,
-  RealtimeSTTSession,
-} from "./providers/stt-openai-realtime.js";
-
-const createStubSession = (): RealtimeSTTSession => ({
+  RealtimeTranscriptionProviderPlugin,
+  RealtimeTranscriptionSession,
+} from "openclaw/plugin-sdk/realtime-transcription";
+import { describe, expect, it, vi } from "vitest";
+import { WebSocket } from "ws";
+import { MediaStreamHandler, sanitizeLogText } from "./media-stream.js";
+import {
+  connectWs,
+  startUpgradeWsServer,
+  waitForClose,
+  withTimeout,
+} from "./websocket-test-support.js";
+
+const createStubSession = (): RealtimeTranscriptionSession => ({
   connect: async () => {},
   sendAudio: () => {},
-  waitForTranscript: async () => "",
-  onPartial: () => {},
-  onTranscript: () => {},
-  onSpeechStart: () => {},
   close: () => {},
   isConnected: () => true,
 });
 
-const createStubSttProvider = (): OpenAIRealtimeSTTProvider =>
+const createStubSttProvider = (): RealtimeTranscriptionProviderPlugin =>
   ({
     createSession: () => createStubSession(),
-  }) as unknown as OpenAIRealtimeSTTProvider;
+    id: "openai",
+    label: "OpenAI",
+    isConfigured: () => true,
+  }) as unknown as RealtimeTranscriptionProviderPlugin;
 
 const flush = async (): Promise<void> => {
   await new Promise((resolve) => setTimeout(resolve, 0));
 };
 
+const createDeferred = (): {
+  promise: Promise<void>;
+  resolve: () => void;
+  reject: (error: Error) => void;
+} => {
+  let resolve!: () => void;
+  let reject!: (error: Error) => void;
+  const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+};
+
 const waitForAbort = (signal: AbortSignal): Promise<void> =>
   new Promise((resolve) => {
     if (signal.aborted) {
@@ -37,74 +56,24 @@ const waitForAbort = (signal: AbortSignal): Promise<void> =>
     signal.addEventListener("abort", () => resolve(), { once: true });
   });
 
-const withTimeout = async <T>(promise: Promise<T>, timeoutMs = 2000): Promise<T> => {
-  let timer: ReturnType<typeof setTimeout> | null = null;
-  const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
-  });
-
-  try {
-    return await Promise.race([promise, timeout]);
-  } finally {
-    if (timer) {
-      clearTimeout(timer);
-    }
-  }
-};
-
 const startWsServer = async (
   handler: MediaStreamHandler,
 ): Promise<{
   url: string;
   close: () => Promise<void>;
-}> => {
-  const server = http.createServer();
-  server.on("upgrade", (request, socket, head) => {
-    handler.handleUpgrade(request, socket, head);
-  });
-
-  await new Promise<void>((resolve) => {
-    server.listen(0, "127.0.0.1", resolve);
-  });
-
-  const address = server.address();
-  if (!address || typeof address === "string") {
-    throw new Error("Failed to resolve test server address");
-  }
-
-  return {
-    url: `ws://127.0.0.1:${address.port}/voice/stream`,
-    close: async () => {
-      await new Promise<void>((resolve, reject) => {
-        server.close((err) => (err ? reject(err) : resolve()));
-      });
+}> =>
+  startUpgradeWsServer({
+    urlPath: "/voice/stream",
+    onUpgrade: (request, socket, head) => {
+      handler.handleUpgrade(request, socket, head);
     },
-  };
-};
-
-const connectWs = async (url: string): Promise<WebSocket> => {
-  const ws = new WebSocket(url);
-  await withTimeout(once(ws, "open") as Promise<[unknown]>);
-  return ws;
-};
-
-const waitForClose = async (
-  ws: WebSocket,
-): Promise<{
-  code: number;
-  reason: string;
-}> => {
-  const [code, reason] = (await withTimeout(once(ws, "close") as Promise<[number, Buffer]>)) ?? [];
-  return {
-    code,
-    reason: Buffer.isBuffer(reason) ? reason.toString() : String(reason || ""),
-  };
-};
+  });
 
 describe("MediaStreamHandler TTS queue", () => {
   it("serializes TTS playback and resolves in order", async () => {
     const handler = new MediaStreamHandler({
-      sttProvider: createStubSttProvider(),
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
     });
     const started: number[] = [];
     const finished: number[] = [];
@@ -137,7 +106,8 @@ describe("MediaStreamHandler TTS queue", () => {
 
   it("cancels active playback and clears queued items", async () => {
     const handler = new MediaStreamHandler({
-      sttProvider: createStubSttProvider(),
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
     });
 
     let queuedRan = false;
@@ -147,7 +117,7 @@ describe("MediaStreamHandler TTS queue", () => {
       started.push("active");
       await waitForAbort(signal);
     });
-    void handler.queueTts("stream-1", async () => {
+    const queued = handler.queueTts("stream-1", async () => {
       queuedRan = true;
     });
 
@@ -156,18 +126,134 @@ describe("MediaStreamHandler TTS queue", () => {
 
     handler.clearTtsQueue("stream-1");
     await active;
+    await withTimeout(queued);
     await flush();
 
     expect(queuedRan).toBe(false);
   });
+
+  it("resolves pending queued playback during stream teardown", async () => {
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
+    });
+
+    let queuedRan = false;
+    const active = handler.queueTts("stream-1", async (signal) => {
+      await waitForAbort(signal);
+    });
+    const queued = handler.queueTts("stream-1", async () => {
+      queuedRan = true;
+    });
+
+    await flush();
+    (
+      handler as unknown as {
+        clearTtsState(streamSid: string): void;
+      }
+    ).clearTtsState("stream-1");
+
+    await withTimeout(active);
+    await withTimeout(queued);
+    expect(queuedRan).toBe(false);
+  });
 });
 
 describe("MediaStreamHandler security hardening", () => {
+  it("fails sends and closes stream when buffered bytes already exceed the cap", () => {
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
+    });
+    const ws = {
+      readyState: WebSocket.OPEN,
+      bufferedAmount: 2 * 1024 * 1024,
+      send: vi.fn(),
+      close: vi.fn(),
+    } as unknown as WebSocket;
+    (
+      handler as unknown as {
+        sessions: Map<
+          string,
+          {
+            callId: string;
+            streamSid: string;
+            ws: WebSocket;
+            sttSession: RealtimeTranscriptionSession;
+          }
+        >;
+      }
+    ).sessions.set("MZ-backpressure", {
+      callId: "CA-backpressure",
+      streamSid: "MZ-backpressure",
+      ws,
+      sttSession: createStubSession(),
+    });
+
+    const result = handler.sendAudio("MZ-backpressure", Buffer.alloc(160, 0xff));
+
+    expect(result.sent).toBe(false);
+    expect(ws.send).not.toHaveBeenCalled();
+    expect(ws.close).toHaveBeenCalledWith(1013, "Backpressure: send buffer exceeded");
+  });
+
+  it("fails sends when buffered bytes exceed cap after enqueueing a frame", () => {
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
+    });
+    const ws = {
+      readyState: WebSocket.OPEN,
+      bufferedAmount: 0,
+      send: vi.fn(() => {
+        (
+          ws as unknown as {
+            bufferedAmount: number;
+          }
+        ).bufferedAmount = 2 * 1024 * 1024;
+      }),
+      close: vi.fn(),
+    } as unknown as WebSocket;
+    (
+      handler as unknown as {
+        sessions: Map<
+          string,
+          {
+            callId: string;
+            streamSid: string;
+            ws: WebSocket;
+            sttSession: RealtimeTranscriptionSession;
+          }
+        >;
+      }
+    ).sessions.set("MZ-overflow", {
+      callId: "CA-overflow",
+      streamSid: "MZ-overflow",
+      ws,
+      sttSession: createStubSession(),
+    });
+
+    const result = handler.sendMark("MZ-overflow", "mark-1");
+
+    expect(ws.send).toHaveBeenCalledTimes(1);
+    expect(result.sent).toBe(false);
+    expect(ws.close).toHaveBeenCalledWith(1013, "Backpressure: send buffer exceeded");
+  });
+
+  it("sanitizes websocket close reason before logging", () => {
+    const reason = sanitizeLogText("forged\nline\r\tentry", 120);
+    expect(reason).not.toContain("\n");
+    expect(reason).not.toContain("\r");
+    expect(reason).not.toContain("\t");
+    expect(reason).toContain("forged line entry");
+  });
+
   it("closes idle pre-start connections after timeout", async () => {
     const shouldAcceptStreamCalls: Array<{ callId: string; streamSid: string; token?: string }> =
       [];
     const handler = new MediaStreamHandler({
-      sttProvider: createStubSttProvider(),
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
       preStartTimeoutMs: 40,
       shouldAcceptStream: (params) => {
         shouldAcceptStreamCalls.push(params);
@@ -190,7 +276,8 @@ describe("MediaStreamHandler security hardening", () => {
 
   it("enforces pending connection limits", async () => {
     const handler = new MediaStreamHandler({
-      sttProvider: createStubSttProvider(),
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
       preStartTimeoutMs: 5_000,
       maxPendingConnections: 1,
       maxPendingConnectionsPerIp: 1,
@@ -213,9 +300,46 @@ describe("MediaStreamHandler security hardening", () => {
     }
   });
 
+  it("uses resolved client IPs for per-IP pending limits", async () => {
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
+      preStartTimeoutMs: 5_000,
+      maxPendingConnections: 10,
+      maxPendingConnectionsPerIp: 1,
+      resolveClientIp: (request) => String(request.headers["x-forwarded-for"] ?? ""),
+    });
+    const server = await startWsServer(handler);
+
+    try {
+      const first = new WebSocket(server.url, {
+        headers: { "x-forwarded-for": "198.51.100.10" },
+      });
+      await withTimeout(new Promise((resolve) => first.once("open", resolve)));
+
+      const second = new WebSocket(server.url, {
+        headers: { "x-forwarded-for": "203.0.113.20" },
+      });
+      await withTimeout(new Promise((resolve) => second.once("open", resolve)));
+
+      expect(first.readyState).toBe(WebSocket.OPEN);
+      expect(second.readyState).toBe(WebSocket.OPEN);
+
+      const firstClosed = waitForClose(first);
+      const secondClosed = waitForClose(second);
+      first.close();
+      second.close();
+      await firstClosed;
+      await secondClosed;
+    } finally {
+      await server.close();
+    }
+  });
+
   it("rejects upgrades when max connection cap is reached", async () => {
     const handler = new MediaStreamHandler({
-      sttProvider: createStubSttProvider(),
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
       preStartTimeoutMs: 5_000,
       maxConnections: 1,
       maxPendingConnections: 10,
@@ -228,7 +352,7 @@ describe("MediaStreamHandler security hardening", () => {
       const secondError = await withTimeout(
         new Promise<Error>((resolve) => {
           const ws = new WebSocket(server.url);
-          ws.once("error", (err) => resolve(err as Error));
+          ws.once("error", (err) => resolve(err));
         }),
       );
 
@@ -241,9 +365,132 @@ describe("MediaStreamHandler security hardening", () => {
     }
   });
 
+  it("counts in-flight upgrades against the max connection cap", () => {
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
+      maxConnections: 2,
+      maxPendingConnections: 10,
+      maxPendingConnectionsPerIp: 10,
+    });
+
+    const fakeWss = {
+      clients: new Set([{}]),
+      handleUpgrade: vi.fn(),
+      emit: vi.fn(),
+      on: vi.fn(),
+    };
+    let upgradeCallback: ((ws: WebSocket) => void) | null = null;
+    fakeWss.handleUpgrade.mockImplementation(
+      (
+        _request: IncomingMessage,
+        _socket: unknown,
+        _head: Buffer,
+        callback: (ws: WebSocket) => void,
+      ) => {
+        upgradeCallback = callback;
+      },
+    );
+
+    (
+      handler as unknown as {
+        wss: typeof fakeWss;
+      }
+    ).wss = fakeWss;
+
+    const firstSocket = {
+      once: vi.fn(),
+      removeListener: vi.fn(),
+      write: vi.fn(),
+      destroy: vi.fn(),
+    };
+    handler.handleUpgrade(
+      { socket: { remoteAddress: "127.0.0.1" } } as IncomingMessage,
+      firstSocket as never,
+      Buffer.alloc(0),
+    );
+
+    const secondSocket = {
+      once: vi.fn(),
+      removeListener: vi.fn(),
+      write: vi.fn(),
+      destroy: vi.fn(),
+    };
+    handler.handleUpgrade(
+      { socket: { remoteAddress: "127.0.0.1" } } as IncomingMessage,
+      secondSocket as never,
+      Buffer.alloc(0),
+    );
+
+    expect(fakeWss.handleUpgrade).toHaveBeenCalledTimes(1);
+    expect(secondSocket.write).toHaveBeenCalledOnce();
+    expect(secondSocket.destroy).toHaveBeenCalledOnce();
+
+    expect(upgradeCallback).not.toBeNull();
+    const completeUpgrade = upgradeCallback as ((ws: WebSocket) => void) | null;
+    if (!completeUpgrade) {
+      throw new Error("Expected upgrade callback to be registered");
+    }
+    completeUpgrade({} as WebSocket);
+    expect(fakeWss.emit).toHaveBeenCalledWith(
+      "connection",
+      expect.anything(),
+      expect.objectContaining({ socket: { remoteAddress: "127.0.0.1" } }),
+    );
+  });
+
+  it("releases in-flight reservations when ws rejects a malformed upgrade before the callback", async () => {
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
+      preStartTimeoutMs: 5_000,
+      maxConnections: 1,
+      maxPendingConnections: 10,
+      maxPendingConnectionsPerIp: 10,
+    });
+    const server = await startWsServer(handler);
+    const serverUrl = new URL(server.url);
+
+    try {
+      await withTimeout(
+        new Promise<void>((resolve, reject) => {
+          const socket = net.createConnection(
+            { host: serverUrl.hostname, port: Number(serverUrl.port) },
+            () => {
+              socket.write(
+                [
+                  "GET /voice/stream HTTP/1.1",
+                  `Host: ${serverUrl.host}`,
+                  "Upgrade: websocket",
+                  "Connection: Upgrade",
+                  "Sec-WebSocket-Version: 13",
+                  "",
+                  "",
+                ].join("\r\n"),
+              );
+            },
+          );
+          socket.once("error", reject);
+          socket.once("data", () => {
+            socket.end();
+          });
+          socket.once("close", () => resolve());
+        }),
+      );
+
+      const ws = await connectWs(server.url);
+      expect(ws.readyState).toBe(WebSocket.OPEN);
+      ws.close();
+      await waitForClose(ws);
+    } finally {
+      await server.close();
+    }
+  });
+
   it("clears pending state after valid start", async () => {
     const handler = new MediaStreamHandler({
-      sttProvider: createStubSttProvider(),
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
       preStartTimeoutMs: 40,
       shouldAcceptStream: () => true,
     });
@@ -268,4 +515,254 @@ describe("MediaStreamHandler security hardening", () => {
       await server.close();
     }
   });
+
+  it("keeps accepted streams alive while STT readiness exceeds the pre-start timeout", async () => {
+    const sttReady = createDeferred();
+    const sttConnectStarted = createDeferred();
+    const transcriptionReady = createDeferred();
+    const events: string[] = [];
+
+    const session: RealtimeTranscriptionSession = {
+      connect: async () => {
+        events.push("stt-connect-start");
+        sttConnectStarted.resolve();
+        await sttReady.promise;
+        events.push("stt-connect-ready");
+      },
+      sendAudio: () => {},
+      close: () => {},
+      isConnected: () => false,
+    };
+
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: {
+        createSession: () => session,
+        id: "openai",
+        label: "OpenAI",
+        isConfigured: () => true,
+      },
+      providerConfig: {},
+      preStartTimeoutMs: 40,
+      shouldAcceptStream: () => true,
+      onConnect: () => {
+        events.push("onConnect");
+      },
+      onTranscriptionReady: () => {
+        events.push("onTranscriptionReady");
+        transcriptionReady.resolve();
+      },
+    });
+    const server = await startWsServer(handler);
+
+    try {
+      const ws = await connectWs(server.url);
+      ws.send(
+        JSON.stringify({
+          event: "start",
+          streamSid: "MZ-slow-stt",
+          start: { callSid: "CA-slow-stt" },
+        }),
+      );
+
+      await withTimeout(sttConnectStarted.promise);
+      await new Promise((resolve) => setTimeout(resolve, 80));
+      expect(ws.readyState).toBe(WebSocket.OPEN);
+      expect(events).toEqual(["onConnect", "stt-connect-start"]);
+
+      sttReady.resolve();
+      await withTimeout(transcriptionReady.promise);
+      expect(events).toEqual([
+        "onConnect",
+        "stt-connect-start",
+        "stt-connect-ready",
+        "onTranscriptionReady",
+      ]);
+
+      ws.close();
+      await waitForClose(ws);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("forwards early Twilio media into the STT session before readiness", async () => {
+    const sttReady = createDeferred();
+    const sttConnectStarted = createDeferred();
+    const transcriptionReady = createDeferred();
+    const audioReceived = createDeferred();
+    const receivedAudio: Buffer[] = [];
+    let onConnectCalls = 0;
+    let onTranscriptionReadyCalls = 0;
+
+    const session: RealtimeTranscriptionSession = {
+      connect: async () => {
+        sttConnectStarted.resolve();
+        await sttReady.promise;
+      },
+      sendAudio: (audio) => {
+        receivedAudio.push(Buffer.from(audio));
+        audioReceived.resolve();
+      },
+      close: () => {},
+      isConnected: () => false,
+    };
+
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: {
+        createSession: () => session,
+        id: "openai",
+        label: "OpenAI",
+        isConfigured: () => true,
+      },
+      providerConfig: {},
+      shouldAcceptStream: () => true,
+      onConnect: () => {
+        onConnectCalls += 1;
+      },
+      onTranscriptionReady: () => {
+        onTranscriptionReadyCalls += 1;
+        transcriptionReady.resolve();
+      },
+    });
+    const server = await startWsServer(handler);
+    let ws: WebSocket | undefined;
+
+    try {
+      ws = await connectWs(server.url);
+      ws.send(
+        JSON.stringify({
+          event: "start",
+          streamSid: "MZ-early-media",
+          start: { callSid: "CA-early-media" },
+        }),
+      );
+
+      await withTimeout(sttConnectStarted.promise);
+      ws.send(
+        JSON.stringify({
+          event: "media",
+          streamSid: "MZ-early-media",
+          media: { payload: Buffer.from("early").toString("base64") },
+        }),
+      );
+      await withTimeout(audioReceived.promise);
+
+      expect(Buffer.concat(receivedAudio).toString()).toBe("early");
+      expect(onConnectCalls).toBe(1);
+      expect(onTranscriptionReadyCalls).toBe(0);
+
+      sttReady.resolve();
+      await withTimeout(transcriptionReady.promise);
+      expect(onConnectCalls).toBe(1);
+      expect(onTranscriptionReadyCalls).toBe(1);
+    } finally {
+      sttReady.resolve();
+      if (ws) {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.close();
+        }
+        if (ws.readyState !== WebSocket.CLOSED) {
+          await waitForClose(ws).catch(() => {});
+        }
+      }
+      await server.close();
+    }
+  });
+
+  it("closes the media stream and disconnects once when STT readiness fails", async () => {
+    const sttConnectStarted = createDeferred();
+    const onDisconnectReady = createDeferred();
+    const onConnect = vi.fn();
+    const onTranscriptionReady = vi.fn();
+    const onDisconnect = vi.fn(() => {
+      onDisconnectReady.resolve();
+    });
+
+    const session: RealtimeTranscriptionSession = {
+      connect: async () => {
+        sttConnectStarted.resolve();
+        throw new Error("provider unavailable");
+      },
+      sendAudio: () => {},
+      close: vi.fn(),
+      isConnected: () => false,
+    };
+
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: {
+        createSession: () => session,
+        id: "openai",
+        label: "OpenAI",
+        isConfigured: () => true,
+      },
+      providerConfig: {},
+      shouldAcceptStream: () => true,
+      onConnect,
+      onTranscriptionReady,
+      onDisconnect,
+    });
+    const server = await startWsServer(handler);
+
+    try {
+      const ws = await connectWs(server.url);
+      ws.send(
+        JSON.stringify({
+          event: "start",
+          streamSid: "MZ-stt-fail",
+          start: { callSid: "CA-stt-fail" },
+        }),
+      );
+
+      await withTimeout(sttConnectStarted.promise);
+      const closed = await waitForClose(ws);
+      await withTimeout(onDisconnectReady.promise);
+
+      expect(closed.code).toBe(1011);
+      expect(closed.reason).toBe("STT connection failed");
+      expect(onConnect).toHaveBeenCalledTimes(1);
+      expect(onConnect).toHaveBeenCalledWith("CA-stt-fail", "MZ-stt-fail");
+      expect(onTranscriptionReady).not.toHaveBeenCalled();
+      expect(onDisconnect).toHaveBeenCalledTimes(1);
+      expect(onDisconnect).toHaveBeenCalledWith("CA-stt-fail", "MZ-stt-fail");
+      expect(session.close).toHaveBeenCalledTimes(1);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("rejects oversized pre-start frames at the websocket maxPayload guard before validation runs", async () => {
+    const shouldAcceptStreamCalls: Array<{ callId: string; streamSid: string; token?: string }> =
+      [];
+    const handler = new MediaStreamHandler({
+      transcriptionProvider: createStubSttProvider(),
+      providerConfig: {},
+      preStartTimeoutMs: 1_000,
+      shouldAcceptStream: (params) => {
+        shouldAcceptStreamCalls.push(params);
+        return true;
+      },
+    });
+    const server = await startWsServer(handler);
+
+    try {
+      const ws = await connectWs(server.url);
+      ws.send(
+        JSON.stringify({
+          event: "start",
+          streamSid: "MZ-oversized",
+          start: {
+            callSid: "CA-oversized",
+            customParameters: { token: "token-oversized", padding: "A".repeat(256 * 1024) },
+          },
+        }),
+      );
+
+      const closed = await waitForClose(ws);
+
+      expect(closed.code).toBe(1009);
+      expect(shouldAcceptStreamCalls).toEqual([]);
+    } finally {
+      await server.close();
+    }
+  });
 });