Skip to content
Miniflare
Visit Miniflare on GitHub
Set theme to dark (⇧+D)

✉️ WebSockets

Server

When using the CLI, or the createServer method, Miniflare will always upgrade Web Socket connections. The worker must then respond with a status 101 Switching Protocols response including a webSocket. For example, the worker below implements an echo WebSocket server:

export default {
fetch(request) {
const [client, server] = Object.values(new WebSocketPair());
server.accept();
server.addEventListener("message", (event) => {
server.send(event.data);
});
return new Response(null, {
status: 101,
webSocket: client,
});
},
};

When using dispatchFetch, you are responsible for handling WebSockets by using the webSocket property on Response. As an example, if the above worker script was stored in echo.mjs:

import { Miniflare } from "miniflare";
const mf = new Miniflare({
modules: true,
scriptPath: "echo.mjs",
});
const res = await mf.dispatchFetch();
const webSocket = res.webSocket;
webSocket.accept();
webSocket.addEventListener("message", (event) => {
console.log(event.data);
});
webSocket.send("Hello!"); // Above listener logs "Hello!"

Client

Miniflare also supports using workers as WebSocket clients too via fetch:

export default {
async fetch(request) {
const res = await fetch("https://echo.websocket.org", {
headers: { Upgrade: "websocket" },
});
const webSocket = res.webSocket;
webSocket.accept();
webSocket.addEventListener("message", (event) => {
console.log(event.data);
});
webSocket.send("Hello!"); // Above listener logs "Hello!"
return new Response();
},
};

All WebSockets are automatically closed when the worker is reloaded.

Validation

Like the real Workers runtime, Miniflare will throw errors when:

  • Attempting to use a WebSocket in a Response that has already been used
  • Attempting to use a WebSocket in a Response after calling accept() on it
  • Attempting to construct a WebSocket using the WebSocket constructor
  • Attempting to call WebSocket#send() or WebSocket#close() without first calling accept()
  • Attempting to call WebSocket#send() after calling close()
  • Attempting to call WebSocket#close() on an already closed WebSocket
  • Attempting to call WebSocket#close() with an invalid close code

Note Miniflare intentionally doesn't support the WebSocket#readyState property, or the open event, as these aren't yet supported by the real Workers runtime.