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
1000
means "normal closure" (default)1009
means a message was too big and was rejected1011
means the server encountered an error1012
means the server is restarting1013
means the server is too busy or the client is rate-limited4000
through4999
are reserved for applications (you can use it!)
To close the connection abruptly, use peer.terminate()
.
Compatibility
Bun | Cloudflare | Cloudflare (durable) | Deno | Node (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 | ✓ 6 | 6 ✓ | ✓ 6 | ✓ 6 | ⨉ |
websocket.readyState | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ 7 | ✓ 7 |
websocket.binaryType | ✓ 8 | ⨉ | ⨉ | ✓ | ✓ 8 | ✓ | ⨉ |
websocket.bufferedAmount | ⨉ | ⨉ | ⨉ | ✓ | ✓ | ✓ | ⨉ |
Footnotes
- pubsub is not natively handled by runtime. peers are internally tracked. ↩ ↩2 ↩3 ↩4
close()
will be used for compatibility. ↩ ↩2- After durable object's hibernation, only
request.url
(andpeer.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. ↩ ↩2 websocket.extensions
is polyfilled usingsec-websocket-extensions
request header. ↩ ↩2 ↩3 ↩4websocket.protocol
is polyfilled usingsec-websocket-protocol
request header. ↩ ↩2 ↩3 ↩4 ↩5 ↩6websocket.readyState
is polyfilled by tracking open/close events. ↩ ↩2- Some runtimes have non standard values including
"nodebuffer"
and"uint8array"
. crossws auto converts them formessage.data
. ↩ ↩2