@prsm/keepalive-ws
v0.3.8
Published
For a TCP-based, node-only solution with a similar API, see [duplex](https://github.com/node-prism/duplex).
Downloads
8
Readme
For a TCP-based, node-only solution with a similar API, see duplex.
keepalive-ws
A command server and client for simplified WebSocket communication, with builtin ping and latency messaging.
Built for grove, but works anywhere.
Server
For node.
import { KeepAliveServer, WSContext } from "@prsm/keepalive-ws/server";
const ws = new KeepAliveServer({
// Where to mount this server and listen to messages.
path: "/",
// How often to send ping messages to connected clients.
pingInterval: 30_000,
// Calculate round-trip time and send latency updates
// to clients every 5s.
latencyInterval: 5_000,
});
ws.registerCommand(
"authenticate",
async (c: WSContext<{ token: string >}) => {
const { token } = c.payload;
// use c.payload to authenticate c.connection
return { ok: true, token };
},
);
ws.registerCommand(
"throws",
async (c: WSContext<unknown>) => {
throw new Error("oops");
},
);
Extended API:
Rooms
It can be useful to collect connections into rooms.
addToRoom(roomName: string, connection: Connection): void
removeFromRoom(roomName: string, connection: Connection): void
getRoom(roomName: string): Connection[]
clearRoom(roomName: string): void
Command middleware
Broadcasting to:
- all
broadcast(command: string, payload: any, connections?: Connection[]): void
- all connections that share the same IP
broadcastRemoteAddress(c: Connection, command: string, payload: any): void
- rooms
broadcastRoom(roomName: string, command: string, payload: any): void
- all
Client
For the browser.
import { KeepAliveClient } from "@prsm/keepalive-ws/client";
const opts = {
// After 30s (+ maxLatency) of no ping, assume we've disconnected and attempt a
// reconnection if shouldReconnect is true.
// This number should be coordinated with the pingInterval from KeepAliveServer.
pingTimeout: 30_000,
// Try to reconnect whenever we are disconnected.
shouldReconnect: true,
// This number, added to pingTimeout, is the maximum amount of time
// that can pass before the connection is considered closed.
// In this case, 32s.
maxLatency: 2_000,
// How often to try and connect during reconnection phase.
reconnectInterval: 2_000,
// How many times to try and reconnect before giving up.
maxReconnectAttempts: Infinity,
};
const ws = new KeepAliveClient("ws://localhost:8080", opts);
const { ok, token } = await ws.command("authenticate", {
username: "user",
password: "pass",
});
const result = await ws.command("throws", {});
// result is: { error: "oops" }
ws.on("latency", (e: CustomEvent<{ latency: number }>) => {
// e.detail.latency is round-trip time in ms
});