Deno WebSocket Server 🔌

A WebSocket server library for Deno.

The raison d’être for this library is to provide a unified async iterator for the events of all connected WebSocket clients.

Note: This WebSocket server is not an EventEmitter (i.e. it does not use events with callbacks like websockets/ws). Instead, it specifies the asyncIterator symbol and should be used in conjunction with a for await...of loop, just like the Deno http server. The iterator return values are of

type WebSocketServerEvent = {
    event: WebSocketEvent;
    socket: WebSocket;
};

where socket is the WebSocket from which the data was received on.

Usage

Simple server

import { serve } from "https://deno.land/x/websocket_server/mod.ts";
const server = serve(":8080");
for await (const { event } of server) {
    console.log(event);
}

Simple server with handler

import { listenAndServe } from "https://deno.land/x/websocket_server/mod.ts";

listenAndServe(":8080", ({ socket, event }) => {
    console.log(socket.conn.rid, event);
});

Using an existing HTTP server

import { serve } from "https://deno.land/std/http/server.ts";
import { WebSocketServer } from "https://deno.land/x/websocket_server/mod.ts";

const httpServer = serve(":8080");
const wss = new WebSocketServer(httpServer);
for await (const { event, socket } of wss) {
    console.log(event);
    if (!socket.isClosed) {
        socket.send("Hello, I am using the HTTP server!");
    }
}

Multiple WebSocket servers sharing an existing HTTP server

import { serve } from "https://deno.land/std/http/server.ts";
import { WebSocketServer } from "https://deno.land/x/websocket_server/mod.ts";

async function serverHandler(wss: WebSocketServer, message: string) {
    for await (const { event, socket } of wss) {
        console.log(event);
        if (!socket.isClosed) {
            socket.send(message);
        }
    }
}

const httpServer = serve(":8080");
const wss1 = new WebSocketServer();
const wss2 = new WebSocketServer();
serverHandler(wss1, "Received your message on server 1.");
serverHandler(wss2, "Received your message on server 2.");

for await (const req of httpServer) {
    if (req.url === "/foo") {
        wss1.handleUpgrade(req);
    } else if (req.url === '/bar') {
        wss2.handleUpgrade(req);
    } else {
        // Do stuff with your HTTP server e.g. close the connection
        await req.respond({
            body: "You are not welcome!",
            status: 400,
        });
        req.conn.close();
    }
}

Echo / broadcast server

Check out the example echo/broadcast server.

FAQ

How do I create a WebSocket client?

This library provides a class only for WebSocket servers, not WebSocket clients, because it is straightforward to create clients with the std/ws module.

Here is a simple example:

import { connectWebSocket } from "https://deno.land/std/ws/mod.ts";
try {
    const socket = await connectWebSocket("ws://127.0.0.1:8080");
    for await (const event of socket) {
        console.log(event);
        if (typeof event === "string" && event === "Who is this?") {
            socket.send("It is me, a simple WebSocket client.");
        }
    }
} catch (err) {
    console.error(`Could not connect to WebSocket: '${err}'`);
}

Changelog

Changelog entries can be found at releases.

Acknowledgements

License

MIT