@kuralle-syrinx/server-websocket 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@kuralle-syrinx/server-websocket",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./edge": "./src/edge.ts",
+    "./edge-twilio": "./src/edge-twilio.ts",
+    "./session-store": "./src/session-store.ts"
+  },
+  "dependencies": {
+    "@evan/opus": "1.0.3",
+    "ws": "^8.18.0",
+    "@kuralle-syrinx/core": "2.1.0",
+    "@kuralle-syrinx/ws": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --fileParallelism=false"
+  }
+}

package/src/admission-control.test.ts

@@ -0,0 +1,247 @@
+// SPDX-License-Identifier: MIT
+
+import { createServer } from "node:http";
+import { describe, expect, it } from "vitest";
+import WebSocket, { WebSocketServer } from "ws";
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+import {
+  createSmartPbxMediaStreamServer,
+  createTelnyxMediaStreamServer,
+  createTwilioMediaStreamServer,
+  createVoiceWebSocketServer,
+} from "./index.js";
+import { TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
+import {
+  openBrowserSocketReady,
+  openSocket,
+  registerHttpServer,
+  registerServer,
+  registerSocket,
+  setupTransportTestCleanup,
+  waitForClose,
+  waitForCondition,
+} from "./test-helpers.js";
+
+setupTransportTestCleanup();
+
+function websocketUrl(port: number): string {
+  return `ws://127.0.0.1:${port}/ws`;
+}
+
+describe("WT-08 admission control and upgrade routing", () => {
+  it("rejects connections beyond maxConcurrentSessions with 1013 and transport.admission_rejected", async () => {
+    const metrics: string[] = [];
+    const server = registerServer(await createVoiceWebSocketServer({
+      port: 0,
+      maxConcurrentSessions: 2,
+      onTransportMetric: (name) => metrics.push(name),
+      createSession: () => new VoiceAgentSession({ plugins: {} }),
+    }));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const first = await openBrowserSocketReady(websocketUrl(address.port));
+    const second = await openBrowserSocketReady(websocketUrl(address.port));
+    expect(server.wsServer.clients.size).toBe(2);
+
+    const rejected = registerSocket(new WebSocket(websocketUrl(address.port)));
+    await new Promise<void>((resolveOpen, reject) => {
+      rejected.once("open", resolveOpen);
+      rejected.once("error", reject);
+    });
+    const closeCode = await waitForClose(rejected);
+
+    expect(closeCode).toBe(1013);
+    expect(metrics).toContain(TRANSPORT_ADMISSION_REJECTED_METRIC);
+
+    first.close();
+    second.close();
+    await server.close();
+  });
+
+  it("allows a new connection after an admitted session disconnects", async () => {
+    const server = registerServer(await createVoiceWebSocketServer({
+      port: 0,
+      maxConcurrentSessions: 1,
+      createSession: () => new VoiceAgentSession({ plugins: {} }),
+    }));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const first = await openBrowserSocketReady(websocketUrl(address.port));
+    first.close();
+    await waitForCondition(() => server.wsServer.clients.size === 0);
+
+    const second = await openBrowserSocketReady(websocketUrl(address.port));
+    expect(second.readyState).toBe(WebSocket.OPEN);
+
+    second.close();
+    await server.close();
+  });
+
+  it("destroys sockets on unmatched upgrade paths when this router is the sole upgrade handler", async () => {
+    const httpServer = registerHttpServer(createServer());
+    const server = registerServer(await createVoiceWebSocketServer({
+      server: httpServer,
+      createSession: () => new VoiceAgentSession({ plugins: {} }),
+    }));
+    await new Promise<void>((resolveListen, reject) => {
+      httpServer.once("error", reject);
+      httpServer.listen(0, "127.0.0.1", () => {
+        httpServer.off("error", reject);
+        resolveListen();
+      });
+    });
+    const address = httpServer.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const unknownPathClient = registerSocket(
+      new WebSocket(`ws://127.0.0.1:${String(address.port)}/unknown-path`),
+    );
+    const closeCode = await waitForClose(unknownPathClient);
+    expect(closeCode).toBe(1006);
+
+    const registered = await openBrowserSocketReady(websocketUrl(address.port));
+    expect(registered.readyState).toBe(WebSocket.OPEN);
+
+    registered.close();
+    await server.close();
+    await new Promise<void>((resolveClose) => httpServer.close(() => resolveClose()));
+  });
+
+  it("leaves unmatched upgrade paths for co-registered upgrade listeners on a shared HTTP server", async () => {
+    const httpServer = registerHttpServer(createServer());
+    const server = registerServer(await createVoiceWebSocketServer({
+      server: httpServer,
+      createSession: () => new VoiceAgentSession({ plugins: {} }),
+    }));
+    const foreignPath = "/foreign-ws";
+    const foreignConnections: WebSocket[] = [];
+    const foreignListener = (
+      request: import("node:http").IncomingMessage,
+      socket: import("node:net").Socket,
+      head: Buffer,
+    ): void => {
+      if (new URL(request.url ?? "/", "http://localhost").pathname !== foreignPath) return;
+      const foreignServer = new WebSocketServer({ noServer: true });
+      foreignServer.handleUpgrade(request, socket, head, (websocket) => {
+        foreignConnections.push(websocket);
+        foreignServer.emit("connection", websocket, request);
+      });
+    };
+    httpServer.on("upgrade", foreignListener);
+    await new Promise<void>((resolveListen, reject) => {
+      httpServer.once("error", reject);
+      httpServer.listen(0, "127.0.0.1", () => {
+        httpServer.off("error", reject);
+        resolveListen();
+      });
+    });
+    const address = httpServer.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const foreignClient = await openSocket(`ws://127.0.0.1:${String(address.port)}${foreignPath}`, {
+      perMessageDeflate: false,
+    });
+    expect(foreignClient.readyState).toBe(WebSocket.OPEN);
+    expect(foreignConnections).toHaveLength(1);
+
+    foreignClient.close();
+    await server.close();
+    httpServer.off("upgrade", foreignListener);
+    await new Promise<void>((resolveClose) => httpServer.close(() => resolveClose()));
+  });
+
+  it("routes multiple provider websocket paths on a shared HTTP server without handshake cross-talk", async () => {
+    const httpServer = registerHttpServer(createServer());
+    const [twilio, telnyx, smartpbx] = await Promise.all([
+      registerServer(await createTwilioMediaStreamServer({
+        server: httpServer,
+        createSession: () => new VoiceAgentSession({ plugins: {} }),
+      })),
+      registerServer(await createTelnyxMediaStreamServer({
+        server: httpServer,
+        createSession: () => new VoiceAgentSession({ plugins: {} }),
+      })),
+      registerServer(await createSmartPbxMediaStreamServer({
+        server: httpServer,
+        createSession: () => new VoiceAgentSession({ plugins: {} }),
+      })),
+    ]);
+    await new Promise<void>((resolveListen, reject) => {
+      httpServer.once("error", reject);
+      httpServer.listen(0, "127.0.0.1", () => {
+        httpServer.off("error", reject);
+        resolveListen();
+      });
+    });
+    const address = httpServer.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const clients = await Promise.all([
+      openSocket(`ws://127.0.0.1:${String(address.port)}/twilio`, { perMessageDeflate: false }),
+      openSocket(`ws://127.0.0.1:${String(address.port)}/telnyx`, { perMessageDeflate: false }),
+      openSocket(`ws://127.0.0.1:${String(address.port)}/media-stream`, { perMessageDeflate: false }),
+    ]);
+    expect(clients.map((client) => client.readyState)).toEqual([
+      WebSocket.OPEN,
+      WebSocket.OPEN,
+      WebSocket.OPEN,
+    ]);
+
+    const scanner = registerSocket(
+      new WebSocket(`ws://127.0.0.1:${String(address.port)}/random-scanner-path`),
+    );
+    expect(await waitForClose(scanner)).toBe(1006);
+
+    for (const client of clients) client.close();
+    await Promise.all([twilio.close(), telnyx.close(), smartpbx.close()]);
+    await new Promise<void>((resolveClose) => httpServer.close(() => resolveClose()));
+  });
+
+  it("enforces a global shared-server cap when maxConcurrentSessionsScope is server", async () => {
+    const httpServer = registerHttpServer(createServer());
+    const metrics: string[] = [];
+    const [twilio, telnyx] = await Promise.all([
+      registerServer(await createTwilioMediaStreamServer({
+        server: httpServer,
+        maxConcurrentSessions: 1,
+        maxConcurrentSessionsScope: "server",
+        onTransportMetric: (name) => metrics.push(name),
+        createSession: () => new VoiceAgentSession({ plugins: {} }),
+      })),
+      registerServer(await createTelnyxMediaStreamServer({
+        server: httpServer,
+        maxConcurrentSessions: 1,
+        maxConcurrentSessionsScope: "server",
+        onTransportMetric: (name) => metrics.push(name),
+        createSession: () => new VoiceAgentSession({ plugins: {} }),
+      })),
+    ]);
+    await new Promise<void>((resolveListen, reject) => {
+      httpServer.once("error", reject);
+      httpServer.listen(0, "127.0.0.1", () => {
+        httpServer.off("error", reject);
+        resolveListen();
+      });
+    });
+    const address = httpServer.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const first = await openSocket(`ws://127.0.0.1:${String(address.port)}/twilio`, { perMessageDeflate: false });
+    expect(first.readyState).toBe(WebSocket.OPEN);
+
+    const second = registerSocket(new WebSocket(`ws://127.0.0.1:${String(address.port)}/telnyx`));
+    await new Promise<void>((resolveOpen, reject) => {
+      second.once("open", resolveOpen);
+      second.once("error", reject);
+    });
+    const closeCode = await waitForClose(second);
+    expect(closeCode).toBe(1013);
+    expect(metrics).toContain(TRANSPORT_ADMISSION_REJECTED_METRIC);
+
+    first.close();
+    await Promise.all([twilio.close(), telnyx.close()]);
+    await new Promise<void>((resolveClose) => httpServer.close(() => resolveClose()));
+  });
+});

package/src/browser-opus.test.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { Decoder as OpusDecoder, Encoder as OpusEncoder } from "@evan/opus";
+import { pcm16BytesToSamples, pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
+import { BROWSER_OPUS_FRAME_DURATION_MS, createBrowserOpusCodec } from "./browser-opus.js";
+
+describe("browser opus codec", () => {
+  it("produces non-empty opus frames and decodes them back to PCM16 bytes", () => {
+    const pcm = new Int16Array(960);
+    pcm[0] = 1000;
+    pcm[3] = -1000;
+    const encoder = new OpusEncoder({ channels: 1, sample_rate: 48000, application: "voip" });
+    const decoder = new OpusDecoder({ channels: 1, sample_rate: 48000 });
+    const opus = encoder.encode(pcm16SamplesToBytes(pcm));
+    expect(opus.byteLength).toBeGreaterThan(0);
+    const decoded = pcm16BytesToSamples(decoder.decode(opus));
+    expect(decoded.length).toBeGreaterThan(0);
+
+    const codec = createBrowserOpusCodec(48000);
+    const wire = codec.encodePcm16Frame(pcm, true)[0]!;
+    expect(wire.byteLength).toBeGreaterThan(0);
+    expect(codec.decodeOpusFrame(wire).length).toBeGreaterThan(0);
+  });
+
+  it("does not zero-pad partial PCM until explicitly requested", () => {
+    const codec = createBrowserOpusCodec(48000);
+    const quarter = new Int16Array(Math.round((48000 * BROWSER_OPUS_FRAME_DURATION_MS) / 4000));
+    expect(codec.encodePcm16Frame(quarter, false)).toEqual([]);
+    expect(codec.encodePcm16Frame(quarter, false)).toEqual([]);
+    expect(codec.encodePcm16Frame(new Int16Array(0), true).length).toBeGreaterThan(0);
+  });
+
+  it("accumulates partial PCM before emitting a complete opus frame", () => {
+    const codec = createBrowserOpusCodec(48000);
+    const half = new Int16Array(Math.round((48000 * BROWSER_OPUS_FRAME_DURATION_MS) / 2000));
+    expect(codec.encodePcm16Frame(half, false)).toEqual([]);
+    const full = codec.encodePcm16Frame(half, true);
+    expect(full.length).toBeGreaterThan(0);
+  });
+});

package/src/browser-opus.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+
+import { Decoder as OpusDecoder, Encoder as OpusEncoder } from "@evan/opus";
+import { pcm16BytesToSamples, pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
+
+export const BROWSER_OPUS_SAMPLE_RATE_HZ = 48_000;
+export const BROWSER_OPUS_FRAME_DURATION_MS = 20;
+
+export type BrowserOpusCodec = {
+  readonly sampleRateHz: number;
+  readonly frameSamples: number;
+  encodePcm16Frame(samples: Int16Array, flush?: boolean): Uint8Array[];
+  decodeOpusFrame(wire: Uint8Array): Int16Array;
+  reset(): void;
+};
+
+export function createBrowserOpusCodec(sampleRateHz = BROWSER_OPUS_SAMPLE_RATE_HZ): BrowserOpusCodec {
+  const encoder = new OpusEncoder({ channels: 1, sample_rate: sampleRateHz as 48000, application: "voip" });
+  const decoder = new OpusDecoder({ channels: 1, sample_rate: sampleRateHz as 48000 });
+  const frameSamples = Math.max(1, Math.round((sampleRateHz * BROWSER_OPUS_FRAME_DURATION_MS) / 1000));
+  let encodeRemainder = new Int16Array(0);
+
+  return {
+    sampleRateHz,
+    frameSamples,
+    reset() {
+      encodeRemainder = new Int16Array(0);
+    },
+    decodeOpusFrame(wire: Uint8Array): Int16Array {
+      return pcm16BytesToSamples(decoder.decode(wire));
+    },
+    encodePcm16Frame(samples: Int16Array, flush = false): Uint8Array[] {
+      const pending = new Int16Array(encodeRemainder.length + samples.length);
+      pending.set(encodeRemainder);
+      pending.set(samples, encodeRemainder.length);
+      const completeFrames = Math.floor(pending.length / frameSamples);
+      const frames: Uint8Array[] = [];
+      for (let index = 0; index < completeFrames; index += 1) {
+        const frame = pending.subarray(index * frameSamples, (index + 1) * frameSamples);
+        frames.push(encoder.encode(pcm16SamplesToBytes(frame)));
+      }
+      const consumed = completeFrames * frameSamples;
+      const remainder = pending.subarray(consumed);
+      if (flush && remainder.length > 0) {
+        const padded = new Int16Array(frameSamples);
+        padded.set(remainder);
+        frames.push(encoder.encode(pcm16SamplesToBytes(padded)));
+        encodeRemainder = new Int16Array(0);
+      } else {
+        encodeRemainder = new Int16Array(remainder);
+      }
+      return frames;
+    },
+  };
+}
+
+export function decodeBrowserOpusToPcm16Bytes(wire: Uint8Array, codec: BrowserOpusCodec): Uint8Array {
+  return pcm16SamplesToBytes(codec.decodeOpusFrame(wire));
+}