@kuralle-syrinx/server-websocket 3.1.0 → 4.1.0

package/src/twilio.ts

@@ -22,7 +22,8 @@ import {
 } from "./json-message.js";
 import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
 import { runWebSocketConnection, type GracefulCloseOptions, type TransportAdapter, type TransportHostConfig, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { BackgroundAudioMixer, type BackgroundAudioConfig } from "./background-audio.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./outbound-playout-pipeline.js";
 import {
   decodeStrictBase64,
   nonNegativeInteger,
@@ -45,6 +46,8 @@ export interface TwilioMediaStreamServerOptions {
   readonly twilioSampleRateHz?: number;
   readonly outboundFrameDurationMs?: number;
   readonly maxQueuedOutputAudioMs?: number;
+  /** Ambient/thinking bed mixed (ducked) under assistant speech (see BackgroundAudioConfig). */
+  readonly backgroundAudio?: BackgroundAudioConfig;
   readonly heartbeatIntervalMs?: number;
   readonly startupTimeoutMs?: number;
   readonly maxSessionDurationMs?: number;
@@ -90,6 +93,8 @@ interface TwilioMediaMessage {
 interface TwilioConnectionState {
   streamSid: string;
   contextId: string;
+  contextBase: string;
+  turnCounter: number;
   started: boolean;
   stopped: boolean;
   lastInboundSequenceNumber: number | null;
@@ -148,6 +153,8 @@ export async function createTwilioMediaStreamServer(
     createState: () => ({
       streamSid: "",
       contextId: "",
+      contextBase: "",
+      turnCounter: 0,
       started: false,
       stopped: false,
       lastInboundSequenceNumber: null,
@@ -196,6 +203,7 @@ export async function createTwilioMediaStreamServer(
         disposers,
         outboundFrameDurationMs,
         maxQueuedOutputAudioMs,
+        ...(options.backgroundAudio ? { backgroundAudio: new BackgroundAudioMixer(options.backgroundAudio) } : {}),
         callbacks: {
           carrierLabel: "twilio",
           getContextId: () => state.contextId,
@@ -277,6 +285,7 @@ export async function createTwilioMediaStreamServer(
         },
       });
       state.clearPlayout = outbound.clearPlayout;
+      installTelephonyTurnRotation(session, disposers, state);
       gracefulCloseRegistry.set(socket, (deadlineMs) => outbound.drainAndClose(socket, deadlineMs));
       disposers.push(() => gracefulCloseRegistry.delete(socket));
       return (reason) => state.clearPlayout(reason);
@@ -296,6 +305,7 @@ export async function createTwilioMediaStreamServer(
         state.streamSid = start.streamSid ?? message.streamSid ?? "";
         if (!state.streamSid) throw new Error("Twilio start event is missing streamSid");
         state.contextId = contextIdFn(start);
+        state.contextBase = state.contextId;
         state.started = true;
         return;
       }

package/src/websocket-upgrade.ts

@@ -68,7 +68,7 @@ export function createRoutedWebSocketServer(
     perMessageDeflate: false,
   });
   const router = getOrCreateRouter(httpServer);
-  const handler: UpgradeHandler = (request, socket, head) => {
+  const accept = (request: IncomingMessage, socket: Socket, head: Buffer): void => {
     const maxConcurrentSessions = admission?.maxConcurrentSessions;
     const scope = admission?.maxConcurrentSessionsScope ?? "path";
     const activeSessions = scope === "server"
@@ -86,6 +86,25 @@ export function createRoutedWebSocketServer(
       wsServer.emit("connection", websocket, request);
     });
   };
+  const handler: UpgradeHandler = (request, socket, head) => {
+    if (!admission?.authorize) {
+      accept(request, socket, head);
+      return;
+    }
+    // Authorize before completing the upgrade; reject with 4401 on failure/throw.
+    void Promise.resolve()
+      .then(() => admission.authorize!(request))
+      .then((ok) => {
+        if (ok) {
+          accept(request, socket, head);
+        } else {
+          rejectWebSocketAdmission(wsServer, request, socket, head, 4401, "unauthorized");
+        }
+      })
+      .catch(() => {
+        rejectWebSocketAdmission(wsServer, request, socket, head, 4401, "unauthorized");
+      });
+  };
   router.handlers.set(path, handler);
   router.servers.add(wsServer);
   return {