DurabCast

DurabCast is a library for easily handling WebSockets with Cloudflare Durable Objects. It simplifies the setup and management of WebSocket connections by implementing complex configurations out of the box.

Features

• Connection Monitoring and Auto-Close

  • Monitor and close idle connections automatically.
  • interval and timeout can be configured through options.
  • Opt-out of auto-closing by setting autoClose to false.

• Client-Side Keep-Alive with pingWebSocket

  • Use the pingWebSocket function on the client side to send periodic ping messages.
  • Ensures the connection remains active when autoClose is enabled on the server.

• Message Broadcasting

  • Broadcast messages to other connected clients.
  • Override webSocketMessage to customize message handling.

• Connection Alive Check

  • Use isAliveSocket to check if a connection is still alive.

Installation

npm install durabcast

TypeScript Setup

To use DurabCast with TypeScript, you need to generate types for your Cloudflare Workers runtime environment. Instead of using the static @cloudflare/workers-types package, we recommend using wrangler types which generates types based on your specific configuration.

Generate Types

Run the following command to generate types:

npx wrangler types

This will create a worker-configuration.d.ts file in your project root, which includes:

• Types for your specific Cloudflare Workers runtime based on your compatibility date
• Types for your bindings defined in wrangler.toml
• Types for any module rules specified in your configuration

TypeScript Configuration

Make sure your tsconfig.json includes the generated types file:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "skipLibCheck": true,
    "lib": ["ESNext"]
  },
  "include": ["src/**/*", "worker-configuration.d.ts"]
}

Package Scripts

Add the type generation command to your package.json scripts:

{
  "scripts": {
    "cf-typegen": "wrangler types",
    "build": "wrangler types && your-build-command",
    "dev": "wrangler types && wrangler dev"
  }
}

It's recommended to run wrangler types before any TypeScript compilation or development commands to ensure your types are up-to-date.

Development Workflow

For local development, you can integrate type generation into your development workflow:

# Generate types and start development server
npm run cf-typegen && npm run dev

# Or create a combined script
npm run dev  # if your dev script includes wrangler types

CI/CD Integration

For Continuous Integration, you have two options:

Option 1: Commit the generated types file

Commit your worker-configuration.d.ts file to version control. This ensures consistent types across all environments:

# Generate types locally
npm run cf-typegen

# Commit the generated file
git add worker-configuration.d.ts
git commit -m "Update worker types"

Option 2: Generate types in CI

Generate types during the CI process:

# Example GitHub Actions workflow
- name: Install dependencies
  run: npm ci

- name: Generate types
  run: npm run cf-typegen

- name: Type check
  run: npm run typecheck

- name: Build
  run: npm run build

Note: Type generation typically takes only a few seconds, so either approach works well depending on your team's preferences.

Basic Usage

Here is a simple example to get started with DurabCast.

Setup Steps

1. Install the library:

   npm install durabcast

2. Generate TypeScript types for your Worker configuration:

   npx wrangler types

3. Configure your project files as shown below.

wrangler.toml

name = "sample"
main = "src/index.ts"
compatibility_date = "2024-07-18"

[[durable_objects.bindings]]
class_name = "BroadcastMessage"
name = "BROADCAST_MESSAGE"

[[migrations]]
tag = "v1"
new_classes = ["BroadcastMessage"]

index.ts

import { BroadcastMessage, type BroadcastMessageAppType } from "durabcast";
import { zValidator } from "@hono/zod-validator";
import { Hono } from "hono";
import { hc } from "hono/client";
import { z } from "zod";
import { upgrade } from "durabcast/helpers/upgrade";

type Env = {
  Bindings: {
    BROADCAST_MESSAGE: DurableObjectNamespace<BroadcastMessage>;
  };
};

const app = new Hono<Env>();

const route = app
  .get(
    "/rooms/:roomId",
    upgrade(),
    zValidator("query", z.object({ uid: z.string() })),
    async (c) => {
      const roomId = c.req.param("roomId");
      const uid = c.req.valid("query").uid;
      const id = c.env.BROADCAST_MESSAGE.idFromName(roomId);
      const stub = c.env.BROADCAST_MESSAGE.get(id);

      const baseURL = new URL("/", c.req.url);
      const client = hc<BroadcastMessageAppType>(baseURL.toString(), {
        fetch: stub.fetch.bind(stub),
      });

      const res = await client.rooms[":roomId"].$get(
        { query: { uid }, param: { roomId } },
        { init: { headers: c.req.raw.headers } },
      );

      return new Response(null, {
        webSocket: res.webSocket,
        status: res.status,
        headers: res.headers,
        statusText: res.statusText,
      });
    },
  )
  .post(
    "/rooms/:roomId/broadcast",
    zValidator("json", z.object({ message: z.string() })),
    async (c) => {
      const roomId = c.req.param("roomId");
      const id = c.env.BROADCAST_MESSAGE.idFromName(roomId);
      const stub = c.env.BROADCAST_MESSAGE.get(id);

      await stub.broadcast(c.req.valid("json").message);
      return c.json(null, 200);
    },
  );

export { BroadcastMessage };

Client-Side Keep-Alive with pingWebSocket

When the autoClose feature is enabled on the server side, the server automatically closes idle connections after a specified timeout. To ensure that the client connection remains active, you can use the pingWebSocket function on the client side to send periodic ping messages.

pingWebSocket Function

The pingWebSocket function sends a ping message to the server at regular intervals. This keeps the connection alive by resetting the idle timeout on the server side.

Usage

import { pingWebSocket } from "durabcast/helpers/client";

const ws = new WebSocket("wss://your-server.com/rooms/room123");

// Start sending ping messages every 30 seconds
const unsubscribe = pingWebSocket(ws, { interval: 30000, ping: "ping" });

// To stop sending pings, call the unsubscribe function
// unsubscribe();

Parameters

• ws: The WebSocket instance to send ping messages through.
• options (optional): An object to configure the ping behavior.
  • interval: The interval (in milliseconds) at which to send ping messages. Defaults to 10000 (10 seconds).
  • ping: The ping message to send. Defaults to 'ping'.

Benefits

• Keeps Connection Alive: Ensures that the server recognizes the connection as active.
• Prevents Unintentional Disconnections: Avoids the connection being closed by the server's auto-close mechanism due to inactivity.
• Configurable: Allows customization of the ping interval and message.

Example

import { pingWebSocket } from "durabcast/helpers/client";

const ws = new WebSocket("wss://your-server.com/rooms/room123");

ws.onopen = () => {
  // Start sending pings every 30 seconds
  const unsubscribe = pingWebSocket(ws, {
    interval: 30000,
    ping: "keep-alive",
  });

  // Handle incoming messages
  ws.onmessage = (event) => {
    console.log("Received:", event.data);
  };

  // Optionally, stop sending pings when needed
  // unsubscribe();
};

Advanced Usage

Extending the BroadcastMessage Class

You can extend the BroadcastMessage class to customize the behavior of your WebSocket connections.

import { BroadcastMessage, type BroadcastMessageOptions } from "durabcast";

class CustomBroadcastMessage extends BroadcastMessage {
  protected options: BroadcastMessageOptions = {
    interval: 30000, // Check every 30 seconds
    timeout: 60000, // Close connection if idle for 60 seconds
    autoClose: true, // Enable auto-close
    requestResponsePair: {
      request: "ping",
      response: "pong",
    },
  };

  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void {
    // Broadcast message to other clients
    this.broadcast(message, {
      excludes: [ws],
    });
  }
}

// Use CustomBroadcastMessage in your Durable Object binding

Combining with pingWebSocket

When autoClose is enabled, it's important to ensure that the client sends periodic messages to keep the connection alive. By using pingWebSocket on the client side, you can automatically send these keep-alive messages.

Server-Side Configuration

class CustomBroadcastMessage extends BroadcastMessage {
  protected options: BroadcastMessageOptions = {
    autoClose: true, // Enable auto-close
    interval: 30000, // Check every 30 seconds
    timeout: 60000, // Close if idle for 60 seconds
    requestResponsePair: {
      request: "ping",
      response: "pong",
    },
  };

  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void {
    // Handle ping-pong messages internally
    if (message === this.REQUEST_RESPONSE_PAIR.request) {
      ws.send(this.REQUEST_RESPONSE_PAIR.response);
      return;
    }

    // Broadcast other messages
    this.broadcast(message, { excludes: [ws] });
  }
}

Client-Side Usage

import { pingWebSocket } from "durabcast/helpers/client";

const ws = new WebSocket("wss://your-server.com/rooms/room123");

ws.onopen = () => {
  // Start sending pings to keep the connection alive
  const unsubscribe = pingWebSocket(ws, {
    interval: 30000, // Every 30 seconds
    ping: "ping", // Must match server's expected request
  });

  ws.onmessage = (event) => {
    // Handle incoming messages
    console.log("Received:", event.data);
  };
};

Why Use pingWebSocket with autoClose

• Seamless Integration: pingWebSocket is designed to work with the server's autoClose feature, ensuring connections remain active as needed.
• Resource Optimization: By automatically closing idle connections, the server conserves resources, and pingWebSocket ensures that active clients are not disconnected.
• Consistency: Using standardized ping messages simplifies the client-server communication protocol.

API

Connection Monitoring and Auto-Close

The library monitors connections and can automatically close idle ones based on the configured interval and timeout. This behavior can be turned off by setting autoClose to false in the options.

Example

import { BroadcastMessage, type BroadcastMessageOptions } from "durabcast";

class CustomBroadcastMessage extends BroadcastMessage {
  protected options: BroadcastMessageOptions = {
    interval: 30000, // Check every 30 seconds
    timeout: 60000, // Close connection if idle for 60 seconds
    autoClose: true, // Enable auto-close
    requestResponsePair: {
      request: "ping",
      response: "pong",
    },
  };

  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void {
    // Handle ping-pong messages internally
    if (message === this.REQUEST_RESPONSE_PAIR.request) {
      ws.send(this.REQUEST_RESPONSE_PAIR.response);
      return;
    }

    // Broadcast other messages
    this.broadcast(message, {
      excludes: [ws],
    });
  }
}

// In your Durable Object binding, use CustomBroadcastMessage
export { CustomBroadcastMessage as BroadcastMessage };

Message Broadcasting

Messages can be broadcasted to other connected clients. You can override the webSocketMessage method to customize how messages are handled.

class CustomBroadcastMessage extends BroadcastMessage {
  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void {
    // Custom message handling logic
    this.broadcast(message, {
      excludes: [ws],
    });
  }
}

Connection Alive Check

The isAliveSocket method checks if a connection is still alive.

const isAlive = this.isAliveSocket(ws);
if (!isAlive) {
  ws.close();
}

Extending the BroadcastMessage Class

When extending the BroadcastMessage class, you can access and modify the options field to customize the behavior of your WebSocket connections.

options

The options field allows you to configure the behavior of your WebSocket connections. It is a protected field, meaning it can be accessed and modified within any class that extends BroadcastMessage.

Fields

• interval: The interval (in milliseconds) at which to check for idle connections.
• timeout: The timeout (in milliseconds) after which idle connections are closed.
• autoClose: A boolean indicating whether to automatically close idle connections. Set to false to opt out of this behavior.
• requestResponsePair: An object containing request and response strings used for ping-pong style connection checks.

Protected Methods and Fields

These protected methods and fields are available within any class that extends BroadcastMessage:

• AUTO_CLOSE: Returns the value of options.autoClose, defaulting to true if not set.
• INTERVAL: Returns the value of options.interval, defaulting to 30000 (30 seconds) if not set.
• TIMEOUT: Returns the value of options.timeout, defaulting to 60000 (60 seconds) if not set.
• REQUEST_RESPONSE_PAIR: Returns a WebSocketRequestResponsePair object using the options.requestResponsePair values, defaulting to 'ping' and 'pong' if not set.
• sessions: A set of active WebSocket sessions.

Example

class CustomBroadcastMessage extends BroadcastMessage {
  protected options: BroadcastMessageOptions = {
    interval: 30000, // Check every 30 seconds
    timeout: 60000, // Close connection if idle for 60 seconds
    autoClose: true, // Enable auto-close
    requestResponsePair: {
      request: "ping",
      response: "pong",
    },
  };

  protected get AUTO_CLOSE() {
    return this.options.autoClose ?? true;
  }

  protected get INTERVAL() {
    return this.options.interval ?? 30000;
  }

  protected get TIMEOUT() {
    return this.options.timeout ?? 60000;
  }

  protected get REQUEST_RESPONSE_PAIR() {
    return new WebSocketRequestResponsePair(
      this.options.requestResponsePair?.request ?? "ping",
      this.options.requestResponsePair?.response ?? "pong",
    );
  }

  protected sessions = new Set<WebSocket>();

  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): void {
    // Handle ping-pong messages
    if (message === this.REQUEST_RESPONSE_PAIR.request) {
      ws.send(this.REQUEST_RESPONSE_PAIR.response);
      return;
    }

    // Custom message handling logic
    this.broadcast(message, {
      excludes: [ws],
    });
  }
}

License

MIT License. See LICENSE for more information.