---
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](https://developer.mozilla.org/en-US/docs/Glossary/UUID)) 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](https://developer.mozilla.org/en-US/docs/Web/API/Request) interface, However interface is emulated for Node.js and sometimes unavailable. Refer to the [compatibility table](#compatibility) for more info.

### `peer.remoteAddress?`

The IP address of the client.

> [!NOTE]
> Not all adapters provide this. Refer to the [compatibility table](#compatibility) for more info.

### `peer.websocket`

Direct access to the [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) instance.

> [!NOTE]
> WebSocket properties vary across runtimes. When accessing `peer.websocket`, a lightweight proxy increases stability. Refer to the [compatibility table](#compatibility) 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][bun] | [Cloudflare][cfw] | [Cloudflare (durable)][cfd] | [Deno][deno] | [Node (ws)][nodews] | [Node (μWebSockets)][nodeuws] | [SSE][sse] |
| --------------------------- | ---------- | ----------------- | --------------------------- | ------------ | ------------------- | ----------------------------- | ---------- |
| `send()`                    | ✓          | ✓                 | ✓                           | ✓            | ✓                   | ✓                             | ✓          |
| `publish()` / `subscribe()` | ✓          | ⨉                 | ✓ [^1]                      | ✓ [^1]       | ✓ [^1]              | ✓                             | ✓ [^1]     |
| `close()`                   | ✓          | ✓                 | ✓                           | ✓            | ✓                   | ✓                             | ✓          |
| `terminate()`               | ✓          | ✓ [^2]            | ✓                           | ✓            | ✓                   | ✓                             | ✓ [^2]     |
| `request`                   | ✓          | ✓                 | ✓ [^30]                     | ✓            | ✓ [^31]             | ✓ [^31]                       | ✓          |
| `remoteAddress`             | ✓          | ⨉                 | ⨉                           | ✓            | ✓                   | ✓                             | ⨉          |
| `websocket.url`             | ✓          | ✓                 | ✓                           | ✓            | ✓                   | ✓                             | ✓          |
| `websocket.extensions`      | ✓ [^4]     | ⨉                 | ⨉                           | ✓ [^4]       | ✓ [^4]              | ✓ [^4]                        | ⨉          |
| `websocket.protocol`        | ✓ [^5]     | ✓ [^5]            | ✓ [^5]                      | [^5] ✓       | ✓ [^5]              | ✓ [^5]                        | ⨉          |
| `websocket.readyState`      | ✓          | ✓                 | ✓                           | ✓            | ✓                   | ✓ [^6]                        | ✓ [^6]     |
| `websocket.binaryType`      | ✓ [^7]     | ⨉                 | ⨉                           | ✓            | ✓ [^7]              | ✓                             | ⨉          |
| `websocket.bufferedAmount`  | ⨉          | ⨉                 | ⨉                           | ✓            | ✓                   | ✓                             | ⨉          |

[bun]: /adapters/bun
[cfw]: /adapters/cloudflare
[cfd]: /adapters/cloudflare#durable-objects
[deno]: /adapters/deno
[nodews]: /adapters/node
[nodeuws]: /adapters/node#uwebsockets
[sse]: adapters/sse

[^1]: pubsub is not natively handled by runtime. peers are internally tracked.

[^2]: `close()` will be used for compatibility.

[^30]: After durable object's hibernation, only `request.url` (and `peer.id`) remain available due to 2048 byte in-memory state limit.

[^31]: using a proxy for [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) compatible interface (`url`, `headers` only) wrapping Node.js requests.

[^4]: [`websocket.extensions`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/extensions) is polyfilled using [`sec-websocket-extensions`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism#websocket-specific_headers) request header.

[^5]: [`websocket.protocol`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/protocol) is polyfilled using [`sec-websocket-protocol`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism#websocket-specific_headers) request header.

[^6]: [`websocket.readyState`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/readyState) is polyfilled by tracking open/close events.

[^7]: Some runtimes have non standard values including `"nodebuffer"` and `"uint8array"`. crossws auto converts them for [`message.data`](/guide/message#messagedata).