crossws logocrossws
Guide

Peer

Peer object allows easily interacting with connected clients.

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.send(message, { compress? })

Send a message to the connected client.

peer.subscribe(channel)

Join a broadcast channel.

peer.unsubscribe(channel)

Leave a broadcast channel.

peer.publish(channel, message)

broadcast a message to the channel.

peer.close(code?, number?)

Gracefully closes the connection.

Here is a list of close codes:

peer.terminate()

Abruptly close the connection.

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

This property is compatible with web Request interface, However interface is emulated for Node.js and sometimes unavailable. Refer to the compatibility table for more info.
Not all adapters provide this. Refer to the compatibility table for more info.
WebSocket properties vary across runtimes. When accessing peer.websocket, a lightweight proxy increases stablity. Refer to the compatibility table for more info.

Instance methods

Read more in Guide > Pubsub.
Read more in Guide > Pubsub.
Read more in Guide > Pubsub.
  • 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().

Compatibility

BunCloudflareCloudflare (durable)DenoNode (ws)Node (μWebSockets)SSE
send()✓✓✓✓✓✓✓
publish() / subscribe()✓⨉✓ 1✓ 1✓ 1✓✓ 1
close()✓✓✓✓✓✓✓
terminate()✓✓ 2✓✓✓✓✓ 2
request✓✓✓ 3✓✓ 4✓ 4✓
remoteAddress✓⨉⨉✓✓✓⨉
websocket.url✓✓✓✓✓✓✓
websocket.extensions✓ 5⨉⨉✓ 5✓ 5✓ 5⨉
websocket.protocol✓ 6✓ 6✓ 66 ✓✓ 6✓ 6⨉
websocket.readyState✓✓✓✓✓✓ 7✓ 7
websocket.binaryType✓ 8⨉⨉✓✓ 8✓⨉
websocket.bufferedAmount⨉⨉⨉✓✓✓⨉

Footnotes

  1. pubsub is not natively handled by runtime. peers are internally tracked. ↩ ↩2 ↩3 ↩4
  2. close() will be used for compatibility. ↩ ↩2
  3. After durable object's hibernation, only request.url (and peer.id) remain available due to 2048 byte in-memory state limit. ↩
  4. using a proxy for Request compatible interface (url, headers only) wrapping Node.js requests. ↩ ↩2
  5. websocket.extensions is polyfilled using sec-websocket-extensions request header. ↩ ↩2 ↩3 ↩4
  6. websocket.protocol is polyfilled using sec-websocket-protocol request header. ↩ ↩2 ↩3 ↩4 ↩5 ↩6
  7. websocket.readyState is polyfilled by tracking open/close events. ↩ ↩2
  8. Some runtimes have non standard values including "nodebuffer" and "uint8array". crossws auto converts them for message.data. ↩ ↩2
Edit this page

Hooks

Using hooks, you can define a WebSocket server that works across runtimes with the same syntax.

Message