crossws/docs/1.guide/3.peer.md

icon

icon
mynaui:api

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.

Note

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.

Note

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

peer.websocket

Direct access to the WebSocket instance.

Note

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

peer.context

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

Note

context data can be volatile in some runtimes.

Instance methods

peer.send(message, { compress? })

Send a message to the connected client.

peer.subscribe(channel)

Join a broadcast channel.

:read-more{to="/guide/pubsub"}

peer.unsubscribe(channel)

Leave a broadcast channel.

:read-more{to="/guide/pubsub"}

peer.publish(channel, message)

broadcast a message to the channel.

:read-more{to="/guide/pubsub"}

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()	✓	⨉	✓ 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	⨉	⨉	⨉	✓	✓	✓	⨉

---

1. pubsub is not natively handled by runtime. peers are internally tracked. ↩︎

2. close() will be used for compatibility. ↩︎

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. ↩︎

5. websocket.extensions is polyfilled using sec-websocket-extensions request header. ↩︎

6. websocket.protocol is polyfilled using sec-websocket-protocol request header. ↩︎

7. websocket.readyState is polyfilled by tracking open/close events. ↩︎

8. Some runtimes have non standard values including "nodebuffer" and "uint8array". crossws auto converts them for message.data. ↩︎