Skip to content

Commit cf28f78

Browse files
committed
docs: tighten server-side room actions prose and exports
1 parent a4f2a8e commit cf28f78

2 files changed

Lines changed: 14 additions & 15 deletions

File tree

‎docs/guide/websockets.md‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ Connections from another origin are anonymous unless that origin is in your auth
162162

163163
## Server-side actions
164164

165-
A room can declare named actions that other server code calls with typed arguments. An action runs inside the room's Durable Object, so it can close matching connections or broadcast without waiting for the next client frame.
165+
A room can declare named actions that other server code calls with typed arguments. An action runs inside the room's Durable Object, so it can close connections or broadcast without waiting for a client frame.
166166

167167
```ts
168168
// routes/relay/[accountId].ws.ts
@@ -176,7 +176,7 @@ const ServerMessage = v.object({ type: v.literal('relay.message'), text: v.strin
176176
export default defineRoom({
177177
messages: { client: ClientMessage, server: ServerMessage },
178178
onConnect(ctx) {
179-
// The session comes from the request's authenticated session, not from client input.
179+
// The id comes from the authenticated session, never from client input.
180180
const session = getSession()?.session;
181181
if (session) {
182182
ctx.connection.setState({ sessionId: session.id });
@@ -200,7 +200,7 @@ export default defineRoom({
200200
});
201201
```
202202

203-
Call the action from a route handler, an auth hook, a queue consumer or a cron job with `getRoom()` from `void/ws/server`:
203+
Call an action from a route handler, an auth hook, a queue consumer or a cron job with `getRoom()` from `void/ws/server`:
204204

205205
```ts
206206
import { getRoom } from 'void/ws/server';
@@ -210,26 +210,25 @@ const room = getRoom('/relay/[accountId]', { params: { accountId } });
210210
const { closed } = await room.actions.revokeSession(session.id, 4001);
211211
```
212212

213-
Match connections on server-verified state. Do not store a session id read from the URL, a query string or a client message: a client can send any value, so the revocation would close the wrong sockets and leave the real ones open. Derive the value from `getSession()` or your own records, and pass that same verified id from the code that revokes it.
213+
`getRoom()` addresses the same instance `connect()` reaches. Pass the route pattern and the same params, and a custom `key` is applied too.
214214

215-
- `getRoom()` addresses the same instance `connect()` reaches. Pass the route pattern and the same params; a custom `key` is applied too.
216-
- Arguments and results are typed from the definition. Annotate each action parameter, because unannotated parameters are inferred as `never`.
217-
- Actions receive `ctx.id`, `ctx.params`, `ctx.env`, `ctx.storage` and `ctx.room`. There is no `ctx.request` or `ctx.user`: the caller is other server code, so authorize the decision where it is made.
218-
- Inside an action, `ctx.room.broadcast()` and connection `send()` accept any event. The server message schema still validates the event at runtime.
219-
- Arguments cross a Durable Object boundary. Pass structured-clone data, not callbacks or class instances.
220-
- Unknown action names and handler errors reject the call. An unknown route, a `defineWebSocket()` route or a missing param throws before any Durable Object is contacted.
215+
Match connections on server-verified state. A session id read from the URL, a query string or a client message can be any value a client sends, so the revocation would close the wrong sockets. Derive the id from `getSession()` or your own records, store it in `onConnect`, and pass that same id from the code that revokes it.
216+
217+
- Annotate each action parameter. Arguments and results are typed from the definition, and an unannotated parameter is `never`.
218+
- Actions receive `ctx.id`, `ctx.params`, `ctx.env`, `ctx.storage` and `ctx.room`. There is no `ctx.request` or `ctx.user`: other server code is the caller, so authorize the decision where you make it.
219+
- `ctx.room.broadcast()` and connection `send()` accept any event inside an action. The server message schema still validates it at runtime.
220+
- Arguments cross a Durable Object boundary, so pass structured-clone data, not callbacks or class instances.
221+
- An unknown action name or a handler error rejects the call. An unknown route, a `defineWebSocket()` route or a missing param throws before any Durable Object is contacted.
221222
- Do not call an action from the same room's own hooks. Use `ctx.room` there; a call from inside the room waits on the room itself.
222223

223-
Actions are not an endpoint. They are invoked over Durable Object RPC from your Worker, so a browser request or a WebSocket message cannot call one. A room without `onRequest()` still answers ordinary HTTP requests to its path with `426 Upgrade Required`.
224+
Actions are not an endpoint. They run over Durable Object RPC from your Worker, so a browser request or a WebSocket message cannot call one.
224225

225-
`getRoom()` reads the current runtime env, so it works in any handler Void runs, including a route, a queue consumer, a cron job and an auth hook that runs inside one. In code that runs outside one, pass the bindings object you already hold:
226+
`getRoom()` reads the current runtime env, so it works in any handler Void runs. Outside one, pass the bindings object you already hold:
226227

227228
```ts
228229
getRoom('/relay/[accountId]', { params: { accountId }, env: bindings });
229230
```
230231

231-
`defineWebSocket()` routes have no actions. Actions are available in native Void apps only.
232-
233232
## Hooks
234233

235234
Both `defineRoom()` and `defineWebSocket()` support:

‎docs/reference/api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ Import Void's app-facing APIs from these paths:
4343
| `void/client` | `fetch`, `fetchStream`, `FetchError`, `auth`, `createAuthClient`, `AuthUser`, `AuthSession`, `AuthState` |
4444
| `void/client/{framework}` | Same as `void/client`, with framework-specific Better Auth clients for `react`, `vue`, `svelte`, and `solid` |
4545
| `void/ws` | `defineRoom`, `defineWebSocket`, `connect`, WebSocket context, connection and action types |
46-
| `void/ws/server` | `getRoom`, `RoomHandle`, `RoomOptions`. Server-only: call room actions from routes, auth hooks, queues and cron jobs. |
46+
| `void/ws/server` | `getRoom`, `RoomHandle`, `RoomOptions`, `RoomPath`. Server-only: call room actions from routes, auth hooks, queues and cron jobs. |
4747
| `void/durable` | `defineDurableState`, `defineDurableObject`, typed state/RPC/context/migration types |
4848
| `void/sse` | `eventStream`, `formatSse`, `formatSseText`, `getLastEventId`, `SseStreamClosedError`, SSE message and stream types |
4949
| `void/sse/client` | `connectEventStream`, browser `EventSource` wrapper types |

0 commit comments

Comments
 (0)