Peer - crossws

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.

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.

`peer.remoteAddress?`

The IP address of the client.

Not all adapters provide this. Refer to the compatibility table for more info.

`peer.websocket`

Direct access to the WebSocket instance.

WebSocket properties vary across runtimes. When accessing peer.websocket, a lightweight proxy increases stablity. Refer to the compatibility table for more info.

Instance methods

`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:

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().

Compatibility

	Bun	Cloudflare	Cloudflare (durable)	Deno	Node (ws)	Node (μWebSockets)	SSE
`send()`	✓	✓	✓	✓	✓	✓	✓
`publish()` / `subscribe()`	✓	⨉	✓ ¹	✓ ¹	✓ ¹	✓	✓ ¹
`close()`	✓	✓	✓	✓	✓	✓	✓
`terminate()`	✓	✓ ²	✓	✓	✓	✓	✓ ²
`request`	✓	✓	✓ ³	✓	✓ ⁴	✓ ⁴	✓
`remoteAddress`	✓	⨉	⨉	✓	✓	✓	⨉
`websocket.url`	✓	✓	✓	✓	✓	✓	✓
`websocket.extensions`	✓ ⁵	⨉	⨉	✓ ⁵	✓ ⁵	✓ ⁵	⨉
`websocket.protocol`	✓ ⁶	✓ ⁶	✓ ⁶	⁶ ✓	✓ ⁶	✓ ⁶	⨉
`websocket.readyState`	✓	✓	✓	✓	✓	✓ ⁷	✓ ⁷
`websocket.binaryType`	✓ ⁸	⨉	⨉	✓	✓ ⁸	✓	⨉
`websocket.bufferedAmount`	⨉	⨉	⨉	✓	✓	✓	⨉

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

Edit this page

Hooks

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

Message