@quickback-dev/cli 0.70.15 → 0.70.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import pc from "picocolors";
12
12
  // Version injected at build time by scripts/inject-version.ts
13
- const CLI_VERSION = "0.70.15";
13
+ const CLI_VERSION = "0.70.22";
14
14
  function getPackageVersion() {
15
15
  return CLI_VERSION;
16
16
  }
@@ -376,7 +376,9 @@ the WebSocket for you: it mints a [ws-ticket](/platform/realtime/using-realtime)
376
376
  through the same auth lane (a fresh one for every reconnect — tickets live 60
377
377
  seconds), shares one socket between subscribers with the same `ticket` body,
378
378
  reconnects two seconds after a drop, and closes when the last subscriber
379
- unsubscribes. Frames are CloudEvents envelopes — switch on `qbframe`.
379
+ unsubscribes. A ticket refused with 401, 403 or 429 (a session mid-refresh,
380
+ a rate limit) is retried with backoff from two seconds up to thirty; any
381
+ other 4xx is final. Frames are CloudEvents envelopes — switch on `qbframe`.
380
382
 
381
383
  ```typescript
382
384
  const unsubscribe = api.realtime.subscribe((frame) => {
@@ -85,6 +85,22 @@ Set `domain` to the host where **everything is available** on a single origin:
85
85
  > Earlier compilers inferred this host as `quickback.{baseDomain}` from the first declared hostname, which emitted a `custom_domain` route in a zone the deploying account might not own and failed `wrangler deploy` after the upload. Only declared hostnames are emitted now.
86
86
 
87
87
 
88
+ ### A host another Worker owns
89
+
90
+ `domain` also emits a `custom_domain` route for itself. Whichever Worker deploys last takes a custom domain, so if a separate front-door Worker owns that host (a static app that service-binds to this API, say), a routine deploy of the API moves the host to the API. Set `domainRoute: false` to keep `domain` as the unified origin everywhere it is used (trusted origins, SPA baked URLs, CSP, cookie inference, named-environment aliases) while binding nothing:
91
+
92
+ ```typescript
93
+ export default defineConfig({
94
+ domain: "intrio.app", // the front door's host
95
+ domainRoute: false, // the API never claims it
96
+ providers: {
97
+ runtime: { name: "cloudflare", config: { routes: [{ pattern: "api.intrio.app", custom_domain: true }] } },
98
+ },
99
+ });
100
+ ```
101
+
102
+ With named environments, a `domainRoute: false` host is not a generated source, so no target has to claim it under `domains`.
103
+
88
104
  ## Configuration
89
105
 
90
106
  ```typescript title="quickback/quickback.config.ts"
@@ -67,7 +67,11 @@ export default defineBundle({
67
67
  - **`sections` filter**: omitted/empty = all. An un-wanted list section
68
68
  returns `{ data: [], hasMore: false, nextCursor: null }` (drop-in
69
69
  compatible with existing clients); un-wanted `custom` sections are absent.
70
- - **All sections run in one `Promise.all`.**
70
+ - **All sections run in one `Promise.all`.** On Postgres over Hyperdrive
71
+ each concurrent section leases its own connection, opened cold for the
72
+ request — a five-section bundle reports `cold=5 tx=5` in
73
+ [`Server-Timing`](/platform/database/neon#measuring-database-cost-server-timing).
74
+ Fewer sections is the lever when that dominates.
71
75
  - **ETag**: SHA-1 hex over `{ scopeSeed: <path params>, userId, payload }`.
72
76
  An `ifNoneMatch` match returns `{ success: true, etag, notModified: true }`
73
77
  with **no sections**. The digest is also exported as `sha1Hex` from
@@ -141,11 +145,22 @@ must pass the same complete-input-schema check as other actions.
141
145
  - Unknown section tables error, listing candidates.
142
146
  - `columns` / `where` / `orderBy` must name declared columns
143
147
  (compiler-injected audit columns like `createdAt`/`modifiedAt` are allowed).
148
+ - `list()` options are literals, or a same-file top-level
149
+ `const MANY = 2000` — anything else fails with "use a literal".
144
150
  - `where` values are literals or the strict substitution allowlist
145
- (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`) — always
146
- parameterized. Anything richer belongs in a `custom()` section.
151
+ (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`, and
152
+ `$path.<param>` for a param of the bundle's own `path`, e.g.
153
+ `path: "/projects/:projectId/overview"` with
154
+ `where: { projectId: "$path.projectId" }`) — always parameterized. A
155
+ `$path` param the path does not declare is a compile error. Anything
156
+ richer belongs in a `custom()` section.
147
157
  - Section names may not shadow the response envelope
148
158
  (`success`, `etag`, `notModified`, `sections`).
149
159
  - **A bundle must never widen read access**: its `access.roles` must be a
150
160
  subset of every list section table's `read.access` roles — a violation is
151
- a compile error, not a warning.
161
+ a compile error, not a warning. Both sides are compared after lowering:
162
+ `admin+` through `auth.roleHierarchy` and declared `authz.roles` aliases
163
+ through their members, so `["projectAccess"]` and
164
+ `["member", "admin", "owner"]` are the same people. A declared role with a
165
+ relationship or `userRole` arm is not a set; the check skips it with a
166
+ warning.
@@ -1329,6 +1329,21 @@ Statement text and parameters are never logged. Work the invocation defers to
1329
1329
  `waitUntil` (audit writes, after-commit effects) runs after the header is sent
1330
1330
  and is not counted.
1331
1331
 
1332
+ **`cold=5 tx=5` on every bundle request is the pool shape, not a leak.** The
1333
+ lease pool is per invocation and holds up to five connections. A
1334
+ [bundle](/define/bundles) runs its sections in one `Promise.all`, so five or
1335
+ more sections lease five connections at once; each is opened cold for this
1336
+ request and opens its own read lane (`BEGIN READ ONLY` + claims), which is
1337
+ the `tx` count. Summed `db` time exceeds wall time because those leases
1338
+ overlap. Connections cannot outlive the invocation on Workers, so there is
1339
+ nothing to warm across requests; the cost of a cold connection is the
1340
+ Hyperdrive handshake plus three round trips before its prepared statements
1341
+ are cached. Before changing a bundle's shape, run `SERVER_TIMING = "debug"`
1342
+ and read the `first` flags per lane: if most statements are `first`, the
1343
+ request is paying for connections, and fewer, larger sections (or a lower
1344
+ section count) is the lever; if few are, the cost is the statements
1345
+ themselves.
1346
+
1332
1347
  The header and log line are on by default. Set the Wrangler var
1333
1348
  `SERVER_TIMING = "0"` on a target (for example in `environments.production.vars`)
1334
1349
  to turn both off there. `SERVER_TIMING = "debug"` adds a `statements` array to
@@ -59,7 +59,15 @@ export const selectedEvent = defineRealtimeDelivery({
59
59
  });
60
60
  ```
61
61
 
62
- `target` is either a **scope room** (`scopeKeyFrom: "events:{eventId}"` — the `{...}` columns resolve from the invalidation payload/meta) or the **account lane** (`{ organizationId, userIdFrom }`). Fail-closed: if a template column can't be resolved at runtime, the frame goes to **nobody** — never a full-room fan-out.
62
+ `target` is either a **scope room** (`scopeKeyFrom: "events:{eventId}"` — the `{...}` columns resolve from the invalidation payload/meta) or the **account lane** (`{ organizationId, userIdFrom }`). Account-lane values are references or literals: `ctx.activeOrgId` / `ctx.userId` resolve from the acting request, `payload.<key>` / `meta.<key>` from the invalidation call, anything else is a literal id (`userIdFrom` also accepts a bare key). Fail-closed: if a template column or reference can't be resolved at runtime, the frame goes to **nobody** — never a full-room fan-out.
63
+
64
+ ```typescript
65
+ // Everyone in the acting org, addressed one user at a time.
66
+ export const orgMember = defineRealtimeDelivery({
67
+ target: { organizationId: "ctx.activeOrgId", userIdFrom: "payload.userId" },
68
+ access: { roles: ["member", "admin"] },
69
+ });
70
+ ```
63
71
 
64
72
  ## 3. Recipient narrowing — `defineRealtimeRecipients` (optional)
65
73
 
@@ -81,6 +89,8 @@ export const documentWatchers = defineRealtimeDelivery({
81
89
  });
82
90
  ```
83
91
 
92
+ When `recipients` is a reference to a resolver declared elsewhere (`recipients: watchers`), the compiler cannot read its `input` keys, so the resolver receives the variant's declared payload plus `meta` instead of a projection.
93
+
84
94
  The resolver gets `{ db, input, recipient }` — the scoped (firewalled) db, the projected `input`, and a `recipient` builder (`recipient.user(id)` / `recipient.scope({ kind, subjectId })`). It sees only what the acting caller could see. Resolved identities beyond a safety cap are truncated with a warning; malformed returns are dropped.
85
95
 
86
96
  ## 4. Firing from an action — `invalidates`
@@ -23,15 +23,16 @@ The PartyServer `Server` class extends `DurableObject`, so any in-worker DO you
23
23
 
24
24
  ```ts
25
25
  // quickback/features/interviews/lib/InterviewRoom.ts
26
- import { Server, type Connection, type WSMessage } from 'partyserver';
26
+ import { Server, type Connection, type ConnectionContext, type WSMessage } from 'partyserver';
27
27
 
28
28
  export class InterviewRoom extends Server {
29
29
  static options = { hibernate: true };
30
30
 
31
31
  presence = new Map<string, { userId?: string; name?: string }>();
32
32
 
33
- onConnect(connection: Connection) {
34
- this.presence.set(connection.id, {});
33
+ onConnect(connection: Connection, ctx: ConnectionContext) {
34
+ // Verified by the Worker gate; never sent by the client (see "Who connected").
35
+ this.presence.set(connection.id, { userId: ctx.request.headers.get("x-quickback-user-id") ?? undefined });
35
36
  this.broadcastPresence();
36
37
  }
37
38
 
@@ -192,6 +193,18 @@ What the compiler emits:
192
193
 
193
194
  Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table. When `key` is set, the column is checked against the pinned table's schema.
194
195
 
196
+ ### Who connected
197
+
198
+ Every upgrade that passes the gate reaches the Durable Object with the caller's server-resolved identity stamped on the request. The Worker strips any inbound copy of these headers first, so a client cannot forge them:
199
+
200
+ | Header | Value |
201
+ |--------|-------|
202
+ | `x-quickback-user-id` | `ctx.userId` |
203
+ | `x-quickback-org-id` | `ctx.activeOrgId`, when the session has an active organization |
204
+ | `x-quickback-roles` | `ctx.roles` joined with `,` |
205
+
206
+ Read them in `onConnect(connection, ctx)` or `onBeforeConnect(request)` from `ctx.request.headers` / `request.headers`. A display name or avatar is not stamped; look it up from the user id if the room needs one.
207
+
195
208
  ### Migrating a hand-rolled `onConnect` room to a declarative gate
196
209
 
197
210
  If a room currently enforces access by hand inside `onConnect` / `onBeforeConnect` — typically because the room sits on a multi-table feature and an earlier compiler refused the ambiguous string shorthand — you can almost always replace it with a declarative `access` block. The decision is just "what is the roomId?":
@@ -200,7 +213,7 @@ If a room currently enforces access by hand inside `onConnect` / `onBeforeConnec
200
213
  2. **roomId is a unique non-PK column** (a slug, a `yjsRoomId`) → add `key`: `access: { resource: { feature, table, key: 'yjsRoomId' } }`.
201
214
  3. **one DO class serves several room kinds** (e.g. `conv-<id>` / `ticket-<id>`) → the multi-resource form with a `pattern` that captures the kind and id.
202
215
  4. **access depends on membership, not just tenant** (e.g. "is this user an attendee of the event that owns this page") → you do **not** need hand-written code. Declare the pinned table's firewall with a `via:` relationship; the gate runs the table's *full* `buildFirewallConditions`, relationship subqueries included.
203
- 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from request data — a Durable Object has no session and only sees client-settable headers, so trusting an `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits.
216
+ 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from client-sent request data — a Durable Object has no session, so trusting a client's `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits; the Worker then stamps the verified identity for the room to read (see "Who connected").
204
217
 
205
218
  The declarative gate runs the exact firewall the CRUD `GET /:id` handler enforces, with the same 401/403 semantics, *before* the WebSocket upgrade — so by the time `onConnect` fires the caller is already authorized. Dropping the hand-rolled check also closes a common gap: a room with no `access` block is reachable by **any** authenticated user who can guess a room id, regardless of tenant.
206
219
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.70.15",
3
+ "version": "0.70.22",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -376,7 +376,9 @@ the WebSocket for you: it mints a [ws-ticket](/platform/realtime/using-realtime)
376
376
  through the same auth lane (a fresh one for every reconnect — tickets live 60
377
377
  seconds), shares one socket between subscribers with the same `ticket` body,
378
378
  reconnects two seconds after a drop, and closes when the last subscriber
379
- unsubscribes. Frames are CloudEvents envelopes — switch on `qbframe`.
379
+ unsubscribes. A ticket refused with 401, 403 or 429 (a session mid-refresh,
380
+ a rate limit) is retried with backoff from two seconds up to thirty; any
381
+ other 4xx is final. Frames are CloudEvents envelopes — switch on `qbframe`.
380
382
 
381
383
  ```typescript
382
384
  const unsubscribe = api.realtime.subscribe((frame) => {
@@ -85,6 +85,22 @@ Set `domain` to the host where **everything is available** on a single origin:
85
85
  > Earlier compilers inferred this host as `quickback.{baseDomain}` from the first declared hostname, which emitted a `custom_domain` route in a zone the deploying account might not own and failed `wrangler deploy` after the upload. Only declared hostnames are emitted now.
86
86
 
87
87
 
88
+ ### A host another Worker owns
89
+
90
+ `domain` also emits a `custom_domain` route for itself. Whichever Worker deploys last takes a custom domain, so if a separate front-door Worker owns that host (a static app that service-binds to this API, say), a routine deploy of the API moves the host to the API. Set `domainRoute: false` to keep `domain` as the unified origin everywhere it is used (trusted origins, SPA baked URLs, CSP, cookie inference, named-environment aliases) while binding nothing:
91
+
92
+ ```typescript
93
+ export default defineConfig({
94
+ domain: "intrio.app", // the front door's host
95
+ domainRoute: false, // the API never claims it
96
+ providers: {
97
+ runtime: { name: "cloudflare", config: { routes: [{ pattern: "api.intrio.app", custom_domain: true }] } },
98
+ },
99
+ });
100
+ ```
101
+
102
+ With named environments, a `domainRoute: false` host is not a generated source, so no target has to claim it under `domains`.
103
+
88
104
  ## Configuration
89
105
 
90
106
  ```typescript title="quickback/quickback.config.ts"
@@ -67,7 +67,11 @@ export default defineBundle({
67
67
  - **`sections` filter**: omitted/empty = all. An un-wanted list section
68
68
  returns `{ data: [], hasMore: false, nextCursor: null }` (drop-in
69
69
  compatible with existing clients); un-wanted `custom` sections are absent.
70
- - **All sections run in one `Promise.all`.**
70
+ - **All sections run in one `Promise.all`.** On Postgres over Hyperdrive
71
+ each concurrent section leases its own connection, opened cold for the
72
+ request — a five-section bundle reports `cold=5 tx=5` in
73
+ [`Server-Timing`](/platform/database/neon#measuring-database-cost-server-timing).
74
+ Fewer sections is the lever when that dominates.
71
75
  - **ETag**: SHA-1 hex over `{ scopeSeed: <path params>, userId, payload }`.
72
76
  An `ifNoneMatch` match returns `{ success: true, etag, notModified: true }`
73
77
  with **no sections**. The digest is also exported as `sha1Hex` from
@@ -141,11 +145,22 @@ must pass the same complete-input-schema check as other actions.
141
145
  - Unknown section tables error, listing candidates.
142
146
  - `columns` / `where` / `orderBy` must name declared columns
143
147
  (compiler-injected audit columns like `createdAt`/`modifiedAt` are allowed).
148
+ - `list()` options are literals, or a same-file top-level
149
+ `const MANY = 2000` — anything else fails with "use a literal".
144
150
  - `where` values are literals or the strict substitution allowlist
145
- (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`) — always
146
- parameterized. Anything richer belongs in a `custom()` section.
151
+ (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`, and
152
+ `$path.<param>` for a param of the bundle's own `path`, e.g.
153
+ `path: "/projects/:projectId/overview"` with
154
+ `where: { projectId: "$path.projectId" }`) — always parameterized. A
155
+ `$path` param the path does not declare is a compile error. Anything
156
+ richer belongs in a `custom()` section.
147
157
  - Section names may not shadow the response envelope
148
158
  (`success`, `etag`, `notModified`, `sections`).
149
159
  - **A bundle must never widen read access**: its `access.roles` must be a
150
160
  subset of every list section table's `read.access` roles — a violation is
151
- a compile error, not a warning.
161
+ a compile error, not a warning. Both sides are compared after lowering:
162
+ `admin+` through `auth.roleHierarchy` and declared `authz.roles` aliases
163
+ through their members, so `["projectAccess"]` and
164
+ `["member", "admin", "owner"]` are the same people. A declared role with a
165
+ relationship or `userRole` arm is not a set; the check skips it with a
166
+ warning.
@@ -1329,6 +1329,21 @@ Statement text and parameters are never logged. Work the invocation defers to
1329
1329
  `waitUntil` (audit writes, after-commit effects) runs after the header is sent
1330
1330
  and is not counted.
1331
1331
 
1332
+ **`cold=5 tx=5` on every bundle request is the pool shape, not a leak.** The
1333
+ lease pool is per invocation and holds up to five connections. A
1334
+ [bundle](/define/bundles) runs its sections in one `Promise.all`, so five or
1335
+ more sections lease five connections at once; each is opened cold for this
1336
+ request and opens its own read lane (`BEGIN READ ONLY` + claims), which is
1337
+ the `tx` count. Summed `db` time exceeds wall time because those leases
1338
+ overlap. Connections cannot outlive the invocation on Workers, so there is
1339
+ nothing to warm across requests; the cost of a cold connection is the
1340
+ Hyperdrive handshake plus three round trips before its prepared statements
1341
+ are cached. Before changing a bundle's shape, run `SERVER_TIMING = "debug"`
1342
+ and read the `first` flags per lane: if most statements are `first`, the
1343
+ request is paying for connections, and fewer, larger sections (or a lower
1344
+ section count) is the lever; if few are, the cost is the statements
1345
+ themselves.
1346
+
1332
1347
  The header and log line are on by default. Set the Wrangler var
1333
1348
  `SERVER_TIMING = "0"` on a target (for example in `environments.production.vars`)
1334
1349
  to turn both off there. `SERVER_TIMING = "debug"` adds a `statements` array to
@@ -59,7 +59,15 @@ export const selectedEvent = defineRealtimeDelivery({
59
59
  });
60
60
  ```
61
61
 
62
- `target` is either a **scope room** (`scopeKeyFrom: "events:{eventId}"` — the `{...}` columns resolve from the invalidation payload/meta) or the **account lane** (`{ organizationId, userIdFrom }`). Fail-closed: if a template column can't be resolved at runtime, the frame goes to **nobody** — never a full-room fan-out.
62
+ `target` is either a **scope room** (`scopeKeyFrom: "events:{eventId}"` — the `{...}` columns resolve from the invalidation payload/meta) or the **account lane** (`{ organizationId, userIdFrom }`). Account-lane values are references or literals: `ctx.activeOrgId` / `ctx.userId` resolve from the acting request, `payload.<key>` / `meta.<key>` from the invalidation call, anything else is a literal id (`userIdFrom` also accepts a bare key). Fail-closed: if a template column or reference can't be resolved at runtime, the frame goes to **nobody** — never a full-room fan-out.
63
+
64
+ ```typescript
65
+ // Everyone in the acting org, addressed one user at a time.
66
+ export const orgMember = defineRealtimeDelivery({
67
+ target: { organizationId: "ctx.activeOrgId", userIdFrom: "payload.userId" },
68
+ access: { roles: ["member", "admin"] },
69
+ });
70
+ ```
63
71
 
64
72
  ## 3. Recipient narrowing — `defineRealtimeRecipients` (optional)
65
73
 
@@ -81,6 +89,8 @@ export const documentWatchers = defineRealtimeDelivery({
81
89
  });
82
90
  ```
83
91
 
92
+ When `recipients` is a reference to a resolver declared elsewhere (`recipients: watchers`), the compiler cannot read its `input` keys, so the resolver receives the variant's declared payload plus `meta` instead of a projection.
93
+
84
94
  The resolver gets `{ db, input, recipient }` — the scoped (firewalled) db, the projected `input`, and a `recipient` builder (`recipient.user(id)` / `recipient.scope({ kind, subjectId })`). It sees only what the acting caller could see. Resolved identities beyond a safety cap are truncated with a warning; malformed returns are dropped.
85
95
 
86
96
  ## 4. Firing from an action — `invalidates`
@@ -23,15 +23,16 @@ The PartyServer `Server` class extends `DurableObject`, so any in-worker DO you
23
23
 
24
24
  ```ts
25
25
  // quickback/features/interviews/lib/InterviewRoom.ts
26
- import { Server, type Connection, type WSMessage } from 'partyserver';
26
+ import { Server, type Connection, type ConnectionContext, type WSMessage } from 'partyserver';
27
27
 
28
28
  export class InterviewRoom extends Server {
29
29
  static options = { hibernate: true };
30
30
 
31
31
  presence = new Map<string, { userId?: string; name?: string }>();
32
32
 
33
- onConnect(connection: Connection) {
34
- this.presence.set(connection.id, {});
33
+ onConnect(connection: Connection, ctx: ConnectionContext) {
34
+ // Verified by the Worker gate; never sent by the client (see "Who connected").
35
+ this.presence.set(connection.id, { userId: ctx.request.headers.get("x-quickback-user-id") ?? undefined });
35
36
  this.broadcastPresence();
36
37
  }
37
38
 
@@ -192,6 +193,18 @@ What the compiler emits:
192
193
 
193
194
  Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table. When `key` is set, the column is checked against the pinned table's schema.
194
195
 
196
+ ### Who connected
197
+
198
+ Every upgrade that passes the gate reaches the Durable Object with the caller's server-resolved identity stamped on the request. The Worker strips any inbound copy of these headers first, so a client cannot forge them:
199
+
200
+ | Header | Value |
201
+ |--------|-------|
202
+ | `x-quickback-user-id` | `ctx.userId` |
203
+ | `x-quickback-org-id` | `ctx.activeOrgId`, when the session has an active organization |
204
+ | `x-quickback-roles` | `ctx.roles` joined with `,` |
205
+
206
+ Read them in `onConnect(connection, ctx)` or `onBeforeConnect(request)` from `ctx.request.headers` / `request.headers`. A display name or avatar is not stamped; look it up from the user id if the room needs one.
207
+
195
208
  ### Migrating a hand-rolled `onConnect` room to a declarative gate
196
209
 
197
210
  If a room currently enforces access by hand inside `onConnect` / `onBeforeConnect` — typically because the room sits on a multi-table feature and an earlier compiler refused the ambiguous string shorthand — you can almost always replace it with a declarative `access` block. The decision is just "what is the roomId?":
@@ -200,7 +213,7 @@ If a room currently enforces access by hand inside `onConnect` / `onBeforeConnec
200
213
  2. **roomId is a unique non-PK column** (a slug, a `yjsRoomId`) → add `key`: `access: { resource: { feature, table, key: 'yjsRoomId' } }`.
201
214
  3. **one DO class serves several room kinds** (e.g. `conv-<id>` / `ticket-<id>`) → the multi-resource form with a `pattern` that captures the kind and id.
202
215
  4. **access depends on membership, not just tenant** (e.g. "is this user an attendee of the event that owns this page") → you do **not** need hand-written code. Declare the pinned table's firewall with a `via:` relationship; the gate runs the table's *full* `buildFirewallConditions`, relationship subqueries included.
203
- 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from request data — a Durable Object has no session and only sees client-settable headers, so trusting an `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits.
216
+ 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from client-sent request data — a Durable Object has no session, so trusting a client's `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits; the Worker then stamps the verified identity for the room to read (see "Who connected").
204
217
 
205
218
  The declarative gate runs the exact firewall the CRUD `GET /:id` handler enforces, with the same 401/403 semantics, *before* the WebSocket upgrade — so by the time `onConnect` fires the caller is already authorized. Dropping the hand-rolled check also closes a common gap: a room with no `access` block is reachable by **any** authenticated user who can guess a room id, regardless of tenant.
206
219