Skip to content
Docs menu

@venom/harness/ws: a WebSocket server with no dependencies

The server side of RFC 6455 for a node:http server's upgrade event, as used by the browser relay and the voice tests.

View .md

@venom/harness/ws is the server side of RFC 6455 WebSockets with no dependency: the opening handshake, text and binary frames, fragmentation, ping and pong, and the closing handshake. Clients must mask their frames; the server never masks, and it refuses extensions. The client side is Node's global WebSocket (Node 22 and later).

import { createServer } from "node:http";
import { acceptWebSocket, rejectUpgrade } from "@venom/harness/ws";

const server = createServer();
server.on("upgrade", (req, socket, head) => {
  if (req.url !== "/socket") return rejectUpgrade(socket, 404, "not found");
  const conn = acceptWebSocket(req, socket, head); // undefined when the request isn't a valid upgrade (answered 400)
  conn?.onMessage((text) => conn.send(`echo: ${text}`));
});
Export What it is
acceptWebSocket(req, socket, head, opts?) completes the handshake and returns a WsConnection, or answers 400
WsConnection onMessage, onBinary, onClose, send, sendBinary, ping, close(code, reason), terminate
rejectUpgrade(socket, status, message) refuses an upgrade with a plain HTTP answer
WS_MAX_MESSAGE_BYTES the default message cap (16 MiB, opts.maxMessageBytes changes it); larger messages close with 1009
wsAccept, encodeFrame the handshake key and the frame encoder, for tests

The browser extension's relay uses it, and so do @venom/voice's in-process fakes of the orchestrator's realtime transcription endpoint.