@kuralle-syrinx/server-websocket 2.1.0

package/src/websocket-close.ts

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: MIT
+
+import { WebSocket } from "ws";
+
+const DEFAULT_TERMINATE_AFTER_MS = 250;
+
+export function closeWebSocketWithFallback(
+  socket: WebSocket,
+  code: number,
+  reason: string,
+  terminateAfterMs = DEFAULT_TERMINATE_AFTER_MS,
+): void {
+  if (socket.readyState === WebSocket.CLOSED || socket.readyState === WebSocket.CLOSING) return;
+
+  socket.close(code, reason);
+  const timer = setTimeout(() => {
+    if (socket.readyState !== WebSocket.CLOSED) {
+      socket.terminate();
+    }
+  }, terminateAfterMs);
+  timer.unref?.();
+  socket.once("close", () => {
+    clearTimeout(timer);
+  });
+}
+
+export function waitForWebSocketClose(socket: WebSocket, fallbackMs: number): Promise<void> {
+  if (socket.readyState === WebSocket.CLOSED) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    const settle = (): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      if (socket.readyState !== WebSocket.CLOSED && socket.readyState !== WebSocket.CLOSING) {
+        socket.terminate();
+      }
+      settle();
+    }, fallbackMs);
+    timer.unref?.();
+    socket.once("close", settle);
+  });
+}
+
+/**
+ * Serialize `value` to JSON and send it, enforcing the per-socket send-buffer
+ * cap. Returns false (and sends nothing) if the socket is not OPEN. If the send
+ * would push `bufferedAmount` past `maxBufferedAmountBytes`, the socket is closed
+ * 1013 (slow consumer / try-again-later) and false is returned. Canonical safe
+ * downlink-JSON write shared by every carrier adapter.
+ */
+export function sendJsonCapped(
+  socket: WebSocket,
+  value: unknown,
+  maxBufferedAmountBytes: number,
+): boolean {
+  if (socket.readyState !== WebSocket.OPEN) return false;
+  const data = JSON.stringify(value);
+  if (socket.bufferedAmount + Buffer.byteLength(data, "utf8") > maxBufferedAmountBytes) {
+    closeWebSocketWithFallback(socket, 1013, "websocket send buffer exceeded");
+    return false;
+  }
+  socket.send(data);
+  return true;
+}

package/src/websocket-lifecycle.test.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { installGracefulShutdown, type GracefulClosable } from "./websocket-lifecycle.js";
+
+describe("installGracefulShutdown", () => {
+  afterEach(() => {
+    process.removeAllListeners("SIGTERM");
+    process.removeAllListeners("SIGINT");
+  });
+
+  it("drains the server gracefully on a termination signal", async () => {
+    const closeCalls: Array<{ graceful?: boolean; drainDeadlineMs?: number }> = [];
+    const server: GracefulClosable = {
+      close: async (opts) => {
+        closeCalls.push(opts ?? {});
+      },
+    };
+    const onClosed = vi.fn();
+    installGracefulShutdown(server, { drainDeadlineMs: 7000, onClosed });
+
+    process.emit("SIGTERM");
+    await vi.waitFor(() => expect(onClosed).toHaveBeenCalledTimes(1));
+
+    expect(closeCalls).toEqual([{ graceful: true, drainDeadlineMs: 7000 }]);
+  });
+
+  it("is idempotent — a second signal during shutdown does not double-close", async () => {
+    let closeCount = 0;
+    const server: GracefulClosable = { close: async () => { closeCount += 1; } };
+    installGracefulShutdown(server, { signals: ["SIGTERM"] });
+
+    process.emit("SIGTERM");
+    process.emit("SIGTERM");
+    await vi.waitFor(() => expect(closeCount).toBe(1));
+    expect(closeCount).toBe(1);
+  });
+
+  it("the disposer removes the signal handler", async () => {
+    let closeCount = 0;
+    const server: GracefulClosable = { close: async () => { closeCount += 1; } };
+    const dispose = installGracefulShutdown(server, { signals: ["SIGINT"] });
+    dispose();
+
+    process.emit("SIGINT");
+    await new Promise((r) => setTimeout(r, 10));
+    expect(closeCount).toBe(0);
+  });
+});

package/src/websocket-lifecycle.ts

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: MIT
+
+import { WebSocket } from "ws";
+import { closeWebSocketWithFallback } from "./websocket-close.js";
+
+export class WebSocketStartupTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`websocket session startup exceeded ${String(timeoutMs)}ms`);
+    this.name = "WebSocketStartupTimeoutError";
+  }
+}
+
+export async function withWebSocketStartupTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
+  if (timeoutMs <= 0) return await promise;
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_resolve, reject) => {
+        timeout = setTimeout(() => reject(new WebSocketStartupTimeoutError(timeoutMs)), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+export function startWebSocketHeartbeat(
+  socket: WebSocket,
+  heartbeatIntervalMs: number,
+  disposers: Array<() => void>,
+): void {
+  if (heartbeatIntervalMs <= 0) return;
+  let alive = true;
+  const onPong = () => {
+    alive = true;
+  };
+  socket.on("pong", onPong);
+  const interval = setInterval(() => {
+    if (socket.readyState !== WebSocket.OPEN) return;
+    if (!alive) {
+      socket.terminate();
+      return;
+    }
+    alive = false;
+    socket.ping();
+  }, heartbeatIntervalMs);
+  disposers.push(() => {
+    clearInterval(interval);
+    socket.off("pong", onPong);
+  });
+}
+
+/** Minimal closable shape: a voice websocket server (or any server) that drains on graceful close. */
+export interface GracefulClosable {
+  close(opts?: { graceful?: boolean; drainDeadlineMs?: number }): Promise<void>;
+}
+
+/**
+ * Wire process termination signals to the server's graceful drain so a deploy/scale-down
+ * drains active calls instead of killing them (Hard Rule: "drain, don't kill"). Idempotent
+ * (a second signal during shutdown is ignored). Returns a disposer that removes the handlers.
+ *
+ * Production hosts call this once after creating the server:
+ *   installGracefulShutdown(server, { drainDeadlineMs: 10_000, onClosed: () => process.exit(0) });
+ */
+export function installGracefulShutdown(
+  server: GracefulClosable,
+  opts?: {
+    readonly drainDeadlineMs?: number;
+    readonly signals?: readonly NodeJS.Signals[];
+    readonly onClosed?: () => void;
+    readonly onError?: (err: unknown) => void;
+  },
+): () => void {
+  const drainDeadlineMs = opts?.drainDeadlineMs ?? 10_000;
+  const signals = opts?.signals ?? (["SIGTERM", "SIGINT"] as const);
+  let shuttingDown = false;
+  const handler = (): void => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    server
+      .close({ graceful: true, drainDeadlineMs })
+      .then(() => opts?.onClosed?.())
+      .catch((err: unknown) => (opts?.onError ? opts.onError(err) : opts?.onClosed?.()));
+  };
+  for (const signal of signals) process.once(signal, handler);
+  return () => {
+    for (const signal of signals) process.removeListener(signal, handler);
+  };
+}
+
+export function startWebSocketMaxSessionDuration(
+  socket: WebSocket,
+  maxSessionDurationMs: number,
+  disposers: Array<() => void>,
+  onTimeout?: () => void,
+): void {
+  if (maxSessionDurationMs <= 0) return;
+  const timeout = setTimeout(() => {
+    onTimeout?.();
+    closeWebSocketWithFallback(socket, 1000, "websocket max session duration exceeded");
+  }, maxSessionDurationMs);
+  disposers.push(() => clearTimeout(timeout));
+}

package/src/websocket-upgrade.ts

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+
+import type { IncomingMessage, Server as HttpServer } from "node:http";
+import type { Socket } from "node:net";
+import { WebSocketServer } from "ws";
+import {
+  rejectWebSocketAdmission,
+  type TransportAdmissionOptions,
+} from "./transport-host.js";
+
+export interface RoutedWebSocketServer {
+  readonly wsServer: WebSocketServer;
+  readonly detach: () => void;
+}
+
+type UpgradeHandler = (
+  request: IncomingMessage,
+  socket: Socket,
+  head: Buffer,
+) => void;
+
+interface HttpUpgradeRouter {
+  readonly handlers: Map<string, UpgradeHandler>;
+  readonly servers: Set<WebSocketServer>;
+  readonly listener: (request: IncomingMessage, socket: Socket, head: Buffer) => void;
+}
+
+const routers = new WeakMap<HttpServer, HttpUpgradeRouter>();
+
+function getOrCreateRouter(httpServer: HttpServer): HttpUpgradeRouter {
+  const existing = routers.get(httpServer);
+  if (existing) return existing;
+
+  const handlers = new Map<string, UpgradeHandler>();
+  const listener = (request: IncomingMessage, socket: Socket, head: Buffer): void => {
+    const pathname = requestPathname(request);
+    const handler = handlers.get(pathname);
+    if (handler) {
+      handler(request, socket, head);
+      return;
+    }
+    if (httpServer.listenerCount("upgrade") > 1) {
+      return;
+    }
+    socket.destroy();
+  };
+  httpServer.on("upgrade", listener);
+  const router: HttpUpgradeRouter = { handlers, servers: new Set(), listener };
+  routers.set(httpServer, router);
+  return router;
+}
+
+function requestPathname(request: IncomingMessage): string {
+  try {
+    return new URL(request.url ?? "/", "http://localhost").pathname;
+  } catch {
+    return "/";
+  }
+}
+
+export function createRoutedWebSocketServer(
+  httpServer: HttpServer,
+  path: string,
+  admission?: TransportAdmissionOptions,
+): RoutedWebSocketServer {
+  const wsServer = new WebSocketServer({
+    noServer: true,
+    perMessageDeflate: false,
+  });
+  const router = getOrCreateRouter(httpServer);
+  const handler: UpgradeHandler = (request, socket, head) => {
+    const maxConcurrentSessions = admission?.maxConcurrentSessions;
+    const scope = admission?.maxConcurrentSessionsScope ?? "path";
+    const activeSessions = scope === "server"
+      ? [...router.servers].reduce((sum, server) => sum + server.clients.size, 0)
+      : wsServer.clients.size;
+    if (
+      maxConcurrentSessions !== undefined
+      && activeSessions >= maxConcurrentSessions
+    ) {
+      admission?.onAdmissionRejected?.();
+      rejectWebSocketAdmission(wsServer, request, socket, head);
+      return;
+    }
+    wsServer.handleUpgrade(request, socket, head, (websocket) => {
+      wsServer.emit("connection", websocket, request);
+    });
+  };
+  router.handlers.set(path, handler);
+  router.servers.add(wsServer);
+  return {
+    wsServer,
+    detach: () => {
+      router.handlers.delete(path);
+      router.servers.delete(wsServer);
+      if (router.handlers.size === 0) {
+        httpServer.off("upgrade", router.listener);
+        routers.delete(httpServer);
+      }
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    fileParallelism: false,
+  },
+});