mirror of
https://github.com/LukeHagar/crossws.git
synced 2025-12-06 04:19:26 +00:00
130 lines
6.4 KiB
Markdown
130 lines
6.4 KiB
Markdown
---
|
|
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).
|