crossws

crossws provides a native pub-sub API that allows peers to subscribe to named topics and broadcast messages to those topics.

Key Behaviors:

• Subscription: A peer joins a topic using peer.subscribe(<name>).
• Publishing: A peer sends a message to a topic using peer.publish(<name>, <message>).
• Self-Exclusion: The peer that performs the publish() operation is automatically excluded from the broadcast and will not receive its own message. This behavior is consistent across all adapters.
• Unsubscribing: Use peer.unsubscribe(<name>) to stop receiving messages for a topic.

To scale pub-sub across multiple server instances (a cluster), you must use a sync adapter to relay messages over a shared backplane.

import { defineHooks } from "crossws";

const hooks = defineHooks({
  open(peer) {
    // Join new client to the "chat" topic
    peer.subscribe("chat");

    // Notify every other connected client
    peer.publish("chat", `[system] ${peer} joined!`);
  },

  message(peer, message) {
    // The server re-broadcasts incoming messages to everyone
    peer.publish("chat", `[${peer}] ${message}`);
  },

  close(peer) {
    peer.publish("chat", `[system] ${peer} has left the chat!`);
    peer.unsubscribe("chat");
  },
});

Cross-instance relaying is best-effort and fire-and-forget. When designing your topics, keep the following in mind:

• At-most-once and unordered: Messages may arrive at most once and ordering across different instances is not guaranteed. Use sequence numbers in your payloads if ordering is critical.
• No replay or buffering: If an instance is disconnected or hasn't finished subscribing during startup, it will miss messages published during that window.
• Local delivery is independent: peer.publish() always reaches local subscribers synchronously, even if the backplane is down.
• Failures are isolated: Backplane errors will not throw into your publish() call. To monitor the health of your backplane, use the onError option in your adapter configuration.

const ws = nodeAdapter({
  hooks,
  sync: redis({ client: new Redis(), channel: "my-app" }),
  onError(error, { stage }) {
    // stage: "subscribe" (initial connect) | "publish" (relay out) | "delivery" (fan-in)
    metrics.increment(`crossws.sync.error.${stage}`);
    console.error("[crossws] sync error", stage, error);
  },
});

The Peer instance exposes several properties to inspect the connection:

• peer.id: A unique UUID v4 identifier for the peer.
• peer.request?: Access to the upgrade request (headers, cookies, etc.). Note: This is emulated in Node.js and may be unavailable in some runtimes.
• peer.remoteAddress?: The client's IP address (availability depends on the adapter).
• peer.websocket: Direct access to the underlying WebSocket instance (wrapped in a proxy for stability).
• peer.context: An object containing arbitrary request information. You can extend the PeerContext type to add custom properties.
• peer.topics: A list of all topics the peer is currently subscribed to.
• peer.namespace: The pubsub namespace of the peer.
• peer.bufferedAmount: The number of bytes queued for transmission but not yet flushed. Use this to monitor backpressure.

// Extending PeerContext with custom data
declare module "crossws" {
  interface PeerContext {
    customData?: string[];
  }
}

On Cloudflare, the need for a sync backplane depends on how you distribute connections across Durable Objects:

1. Single Durable Object (Default): If all connections land on the same Durable Object instance (e.g., using the default crossws instance name), peer.publish() is cluster-global by default. No sync backplane is required.
2. Sharded Durable Objects: If you distribute connections across multiple instances (e.g., one Durable Object per room via resolveDurableStub), you must provide a sync backplane to bridge them.

Important Caveats for Cloudflare Sync:

• Inbound Delivery: Delivery into a Durable Object is best-effort. If a Durable Object is hibernated or evicted, it may lose the in-memory peer map, causing it to miss some sockets even if they survive via ctx.getWebSockets().
• Outbound Delivery: peer.publish() calls originating from a Durable Object and reaching the backplane are reliable.
• Drivers: Do not use built-in redis or pgsql drivers, as they require persistent connections not supported by workerd. Instead, implement a custom SyncAdapter using Cloudflare-native transports like Queues, a coordinator Durable Object, or fetch-based pub/sub.

import crossws from "crossws/adapters/cloudflare";
import type { SyncAdapter } from "crossws";

const ws = crossws({
  hooks,
  sync: myBackplane, // a custom SyncAdapter
});

By default, crossws pub/sub is in-memory and local to a single instance. If you run multiple instances (multiple processes, replicas, or regions), a peer.publish() call only reaches subscribers on that specific instance.

A sync adapter (or backplane) bridges this gap by relaying messages between instances over a shared medium (like Redis or Postgres). This allows subscribe and publish to work across your entire cluster without changing your existing hooks.

Key Lifecycle Note: When you call await ws.close(), crossws closes all connected peers and tears down the backplane automatically. However, any external clients you passed in (like a Redis or Postgres client) are not closed by crossws; you are responsible for managing their lifecycle.

import nodeAdapter from "crossws/adapters/node";
import { redis } from "crossws/sync";
import Redis from "ioredis";

const ws = nodeAdapter({
  hooks,
  sync: redis({ client: new Redis(), channel: "my-app" }),
});