@prsm/keepalive-ws v0.3.8

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

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
});