bun-ws-inspect

WebSocket inspection lib for Bun.

Allows for metrics tracking (currently very basic metrics are being tracked, but it would be easy to track pretty much whatever), Emitting events that your app can subscribe to for different things - like if you need better observability in the io flow of the ws but dont want 700 log calls in the actual ws handler code Typesafe events, decent dx, and very "out of the way" - which was one of the requirements i had for it myself. zero deps ofc, as all we do is implement events on existing bun builtins

Install

bun add bun-ws-inspect

Usage

Handler (server)

import { InspectedWebSocketClient, InspectedWebSocketHandler } from "bun-ws-inspect";
const log = {
    client: (...data: unknown[]) => console.log("[client]", ...data),
    server: (...data: unknown[]) => console.log("[server]", ...data)
}

const inspector = new InspectedWebSocketHandler({
    /* Here you put everything you normally would've put in the websocket prop in Serve.Options */
    open(ws) {
        log.server("WebSocket opened");
        ws.sendText("six")
    },
    message(ws, message) {
        log.server("Received message", message)
    },
});

// Hook into the events emitted by the inspector (Check src for avaible events)
inspector.on("open", ({ metrics }) => {
    log.server(`Active connections: ${metrics.activeConnections}`);
});

inspector.on("metricsUpdate", (metrics) => {
    log.server("Metrics:", metrics);
});

inspector.on("message", ({ message, metrics }) => {
    log.server("Received:", message, "Total received:", metrics.messagesReceived);
});

Bun.serve({
    port: 3000,
    fetch(req, server) {
        if (server.upgrade(req)) {
            return;
        }
        return new Response("WebSocket server");
    },
    websocket: inspector,
});

Client

import { InspectedWebSocketClient, InspectedWebSocketHandler } from "bun-ws-inspect";
const log = {
    client: (...data: unknown[]) => console.log("[client]", ...data),
    server: (...data: unknown[]) => console.log("[server]", ...data)
}

const ws = new InspectedWebSocketClient("ws://localhost:3000")

// normal Bun WebSocket client calls work
ws.onmessage = (event) => {
    log.client(event.data)
}

// but also - Make sure to look at the src to see avaible events,
ws.on("message", ({ data, metrics }) => {
    log.client("got data:", data) // <-- same as onmessage (event) => event.data
    log.client("metrics", metrics)

    // Reply to the server
    ws.send("seven")
})

Development

bun run example.ts