Peer

When a new client connects to the server, crossws creates a peer instance that allows getting information from clients and sending messages to them.

Instance properties

peer.id

Unique random identifier (uuid v4) for the peer.

peer.request?

Access to the upgrade request info. You can use it to do authentication and access users headers and cookies.

peer.remoteAddress?

The IP address of the client.

peer.websocket

Direct access to the WebSocket instance.

peer.context

The context is an object that contains arbitrary information about the request.

You can augment the PeerContext interface types to add your properties.

declare module "crossws" {
  interface PeerContext {
    customData?: string[];
  }
}

peer.topics

All topics, this peer has been subscribed to.

peer.namespace

Peer's pubsub namespace.

peer.bufferedAmount

Number of bytes queued for transmission but not yet flushed to the client.

Use this to apply backpressure: pause sending while it grows past a high watermark and resume once it drops. This prevents a fast producer (for example a streaming async generator) from filling the adapter's send buffer faster than the client can drain it. The easiest way to wait is peer.waitForDrain().

Instance methods

peer.send(message, { compress? })

Send a message to the connected client.

peer.waitForDrain({ threshold?, pollInterval?, signal? })

Returns a promise that resolves once peer.bufferedAmount drops to or below threshold bytes (default 0), letting you await backpressure relief in a send loop:

// Throttle a fast producer to the client's pace
for (const chunk of stream) {
  peer.send(chunk);
  if (peer.bufferedAmount > 1024 * 1024 /* 1MB */) {
    await peer.waitForDrain({ threshold: 256 * 1024 /* 256KB */ });
  }
}

It resolves immediately when there is no backpressure (or on adapters that do not report bufferedAmount). Otherwise it polls every pollInterval ms (default 100) until the buffer drains, and also resolves early if the connection is no longer open so a send loop never hangs on a dropped client. Pass a signal (e.g. AbortSignal.timeout(ms)) to abort the wait — the promise then rejects with the signal's reason.

peer.subscribe(topic)

Join a broadcast topic.

peer.unsubscribe(topic)

Leave a broadcast topic.

peer.publish(topic, message)

Broadcast a message to the topic. The peer that the publish is called on itself is always excluded from the broadcast.

peer.close(code?, number?)

Gracefully closes the connection.

Here is a list of close codes:

• 1000 means "normal closure" (default)
• 1009 means a message was too big and was rejected
• 1011 means the server encountered an error
• 1012 means the server is restarting
• 1013 means the server is too busy or the client is rate-limited
• 4000 through 4999 are reserved for applications (you can use it!)

To close the connection abruptly, use peer.terminate().

peer.terminate()

Abruptly close the connection.

To gracefully close the connection, use peer.close().

peer.ping(data?)

Send an application-level WebSocket ping control frame to the client.

Pair with the pong hook — embedding a correlatable payload (e.g. a timestamp) in data — to measure round-trip latency:

import { defineHooks } from "crossws";

const hooks = defineHooks({
  message(peer, message) {
    if (message.text() === "measure-latency") {
      // Embed the send time in the ping payload; the client echoes it back
      // in the pong so it can be told apart from keepalive pongs.
      peer.ping(`rtt:${Date.now()}`);
    }
  },
  pong(peer, data) {
    const payload = new TextDecoder().decode(data);
    if (!payload.startsWith("rtt:")) return; // keepalive or unrelated pong
    const rtt = Date.now() - Number(payload.slice(4));
    console.log(`[ws] round-trip latency: ${rtt}ms`);
  },
});

Use the ping hook to observe pings the client sends unprompted (e.g. a graphql-ws style client heartbeat).

Compatibility