---
title: "@venom/harness/ws: a WebSocket server with no dependencies"
description: The server side of RFC 6455 for a node:http server's upgrade event, as used by the browser relay and the voice tests.
section: harness
order: 40
audience: [builder]
sources: [packages/harness/src/browser/ws.ts]
features: [harness.ws]
---

`@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).

```ts
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.
