@quickback-dev/cli 0.70.19 → 0.70.23
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 +1 -1
- package/dist/skill/docs/define/bundles.md +49 -8
- package/dist/skill/docs/platform/database/neon.md +15 -0
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +17 -4
- package/package.json +1 -1
- package/src/skill/docs/define/bundles.md +49 -8
- package/src/skill/docs/platform/database/neon.md +15 -0
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +17 -4
package/dist/index.js
CHANGED
|
@@ -10,6 +10,37 @@ shaped byte-identically to the CRUD list endpoints they replace, a
|
|
|
10
10
|
hand-re-derived per-slice masking. `defineBundle` generates all of it.
|
|
11
11
|
|
|
12
12
|
```typescript
|
|
13
|
+
// features/events/guests.ts
|
|
14
|
+
import { feature, q } from "@quickback/compiler";
|
|
15
|
+
|
|
16
|
+
export default feature("guests", {
|
|
17
|
+
columns: {
|
|
18
|
+
id: q.id(),
|
|
19
|
+
eventId: q.text().required().index(),
|
|
20
|
+
status: q.text().required(),
|
|
21
|
+
displayName: q.text().required(),
|
|
22
|
+
organizationId: q.scope("organization"),
|
|
23
|
+
...q.audit(),
|
|
24
|
+
...q.softDelete(),
|
|
25
|
+
},
|
|
26
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
// features/events/supportTickets.ts
|
|
30
|
+
import { feature, q } from "@quickback/compiler";
|
|
31
|
+
|
|
32
|
+
export default feature("supportTickets", {
|
|
33
|
+
columns: {
|
|
34
|
+
id: q.id(),
|
|
35
|
+
eventId: q.text().required().index(),
|
|
36
|
+
subject: q.text().required(),
|
|
37
|
+
organizationId: q.scope("organization"),
|
|
38
|
+
...q.audit(),
|
|
39
|
+
...q.softDelete(),
|
|
40
|
+
},
|
|
41
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
42
|
+
});
|
|
43
|
+
|
|
13
44
|
// features/events/actions/getOverviewBundle.ts
|
|
14
45
|
import { z } from "zod";
|
|
15
46
|
import { defineBundle, list, custom } from "../.quickback/define-bundle";
|
|
@@ -17,17 +48,17 @@ import { defineBundle, list, custom } from "../.quickback/define-bundle";
|
|
|
17
48
|
export default defineBundle({
|
|
18
49
|
path: "/event/:eventId/overview-bundle",
|
|
19
50
|
description: "Console Overview bootstrap",
|
|
20
|
-
access: { roles: ["member", "admin"] },
|
|
21
|
-
etag: true,
|
|
22
|
-
serverTiming: "overview",
|
|
51
|
+
access: { roles: ["member", "admin"] }, // a subset of every list table's read.access
|
|
52
|
+
etag: true, // default true
|
|
53
|
+
serverTiming: "overview", // optional
|
|
23
54
|
sections: {
|
|
24
55
|
guests: list("guests", {
|
|
25
56
|
columns: ["id", "status", "modifiedAt", "createdAt", "displayName"],
|
|
26
|
-
where: { eventId: "$
|
|
57
|
+
where: { eventId: "$path.eventId" },
|
|
27
58
|
orderBy: [{ createdAt: "desc" }],
|
|
28
59
|
limit: 500,
|
|
29
60
|
}),
|
|
30
|
-
tickets: list("supportTickets", { where: { eventId: "$
|
|
61
|
+
tickets: list("supportTickets", { where: { eventId: "$path.eventId" }, orderBy: [{ modifiedAt: "desc" }], limit: 100 }),
|
|
31
62
|
counts: custom(async ({ db, ctx }) => ({ open: 0 }), { output: z.object({ open: z.number().int() }) }),
|
|
32
63
|
},
|
|
33
64
|
});
|
|
@@ -67,7 +98,11 @@ export default defineBundle({
|
|
|
67
98
|
- **`sections` filter**: omitted/empty = all. An un-wanted list section
|
|
68
99
|
returns `{ data: [], hasMore: false, nextCursor: null }` (drop-in
|
|
69
100
|
compatible with existing clients); un-wanted `custom` sections are absent.
|
|
70
|
-
- **All sections run in one `Promise.all`.**
|
|
101
|
+
- **All sections run in one `Promise.all`.** On Postgres over Hyperdrive
|
|
102
|
+
each concurrent section leases its own connection, opened cold for the
|
|
103
|
+
request — a five-section bundle reports `cold=5 tx=5` in
|
|
104
|
+
[`Server-Timing`](/platform/database/neon#measuring-database-cost-server-timing).
|
|
105
|
+
Fewer sections is the lever when that dominates.
|
|
71
106
|
- **ETag**: SHA-1 hex over `{ scopeSeed: <path params>, userId, payload }`.
|
|
72
107
|
An `ifNoneMatch` match returns `{ success: true, etag, notModified: true }`
|
|
73
108
|
with **no sections**. The digest is also exported as `sha1Hex` from
|
|
@@ -141,9 +176,15 @@ must pass the same complete-input-schema check as other actions.
|
|
|
141
176
|
- Unknown section tables error, listing candidates.
|
|
142
177
|
- `columns` / `where` / `orderBy` must name declared columns
|
|
143
178
|
(compiler-injected audit columns like `createdAt`/`modifiedAt` are allowed).
|
|
179
|
+
- `list()` options are literals, or a same-file top-level
|
|
180
|
+
`const MANY = 2000` — anything else fails with "use a literal".
|
|
144
181
|
- `where` values are literals or the strict substitution allowlist
|
|
145
|
-
(`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id
|
|
146
|
-
|
|
182
|
+
(`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`, and
|
|
183
|
+
`$path.<param>` for a param of the bundle's own `path`, e.g.
|
|
184
|
+
`path: "/projects/:projectId/overview"` with
|
|
185
|
+
`where: { projectId: "$path.projectId" }`) — always parameterized. A
|
|
186
|
+
`$path` param the path does not declare is a compile error. Anything
|
|
187
|
+
richer belongs in a `custom()` section.
|
|
147
188
|
- Section names may not shadow the response envelope
|
|
148
189
|
(`success`, `etag`, `notModified`, `sections`).
|
|
149
190
|
- **A bundle must never widen read access**: its `access.roles` must be a
|
|
@@ -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
|
|
@@ -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
|
-
|
|
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
|
|
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.
|
|
3
|
+
"version": "0.70.23",
|
|
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",
|
|
@@ -10,6 +10,37 @@ shaped byte-identically to the CRUD list endpoints they replace, a
|
|
|
10
10
|
hand-re-derived per-slice masking. `defineBundle` generates all of it.
|
|
11
11
|
|
|
12
12
|
```typescript
|
|
13
|
+
// features/events/guests.ts
|
|
14
|
+
import { feature, q } from "@quickback/compiler";
|
|
15
|
+
|
|
16
|
+
export default feature("guests", {
|
|
17
|
+
columns: {
|
|
18
|
+
id: q.id(),
|
|
19
|
+
eventId: q.text().required().index(),
|
|
20
|
+
status: q.text().required(),
|
|
21
|
+
displayName: q.text().required(),
|
|
22
|
+
organizationId: q.scope("organization"),
|
|
23
|
+
...q.audit(),
|
|
24
|
+
...q.softDelete(),
|
|
25
|
+
},
|
|
26
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
// features/events/supportTickets.ts
|
|
30
|
+
import { feature, q } from "@quickback/compiler";
|
|
31
|
+
|
|
32
|
+
export default feature("supportTickets", {
|
|
33
|
+
columns: {
|
|
34
|
+
id: q.id(),
|
|
35
|
+
eventId: q.text().required().index(),
|
|
36
|
+
subject: q.text().required(),
|
|
37
|
+
organizationId: q.scope("organization"),
|
|
38
|
+
...q.audit(),
|
|
39
|
+
...q.softDelete(),
|
|
40
|
+
},
|
|
41
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
42
|
+
});
|
|
43
|
+
|
|
13
44
|
// features/events/actions/getOverviewBundle.ts
|
|
14
45
|
import { z } from "zod";
|
|
15
46
|
import { defineBundle, list, custom } from "../.quickback/define-bundle";
|
|
@@ -17,17 +48,17 @@ import { defineBundle, list, custom } from "../.quickback/define-bundle";
|
|
|
17
48
|
export default defineBundle({
|
|
18
49
|
path: "/event/:eventId/overview-bundle",
|
|
19
50
|
description: "Console Overview bootstrap",
|
|
20
|
-
access: { roles: ["member", "admin"] },
|
|
21
|
-
etag: true,
|
|
22
|
-
serverTiming: "overview",
|
|
51
|
+
access: { roles: ["member", "admin"] }, // a subset of every list table's read.access
|
|
52
|
+
etag: true, // default true
|
|
53
|
+
serverTiming: "overview", // optional
|
|
23
54
|
sections: {
|
|
24
55
|
guests: list("guests", {
|
|
25
56
|
columns: ["id", "status", "modifiedAt", "createdAt", "displayName"],
|
|
26
|
-
where: { eventId: "$
|
|
57
|
+
where: { eventId: "$path.eventId" },
|
|
27
58
|
orderBy: [{ createdAt: "desc" }],
|
|
28
59
|
limit: 500,
|
|
29
60
|
}),
|
|
30
|
-
tickets: list("supportTickets", { where: { eventId: "$
|
|
61
|
+
tickets: list("supportTickets", { where: { eventId: "$path.eventId" }, orderBy: [{ modifiedAt: "desc" }], limit: 100 }),
|
|
31
62
|
counts: custom(async ({ db, ctx }) => ({ open: 0 }), { output: z.object({ open: z.number().int() }) }),
|
|
32
63
|
},
|
|
33
64
|
});
|
|
@@ -67,7 +98,11 @@ export default defineBundle({
|
|
|
67
98
|
- **`sections` filter**: omitted/empty = all. An un-wanted list section
|
|
68
99
|
returns `{ data: [], hasMore: false, nextCursor: null }` (drop-in
|
|
69
100
|
compatible with existing clients); un-wanted `custom` sections are absent.
|
|
70
|
-
- **All sections run in one `Promise.all`.**
|
|
101
|
+
- **All sections run in one `Promise.all`.** On Postgres over Hyperdrive
|
|
102
|
+
each concurrent section leases its own connection, opened cold for the
|
|
103
|
+
request — a five-section bundle reports `cold=5 tx=5` in
|
|
104
|
+
[`Server-Timing`](/platform/database/neon#measuring-database-cost-server-timing).
|
|
105
|
+
Fewer sections is the lever when that dominates.
|
|
71
106
|
- **ETag**: SHA-1 hex over `{ scopeSeed: <path params>, userId, payload }`.
|
|
72
107
|
An `ifNoneMatch` match returns `{ success: true, etag, notModified: true }`
|
|
73
108
|
with **no sections**. The digest is also exported as `sha1Hex` from
|
|
@@ -141,9 +176,15 @@ must pass the same complete-input-schema check as other actions.
|
|
|
141
176
|
- Unknown section tables error, listing candidates.
|
|
142
177
|
- `columns` / `where` / `orderBy` must name declared columns
|
|
143
178
|
(compiler-injected audit columns like `createdAt`/`modifiedAt` are allowed).
|
|
179
|
+
- `list()` options are literals, or a same-file top-level
|
|
180
|
+
`const MANY = 2000` — anything else fails with "use a literal".
|
|
144
181
|
- `where` values are literals or the strict substitution allowlist
|
|
145
|
-
(`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id
|
|
146
|
-
|
|
182
|
+
(`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`, and
|
|
183
|
+
`$path.<param>` for a param of the bundle's own `path`, e.g.
|
|
184
|
+
`path: "/projects/:projectId/overview"` with
|
|
185
|
+
`where: { projectId: "$path.projectId" }`) — always parameterized. A
|
|
186
|
+
`$path` param the path does not declare is a compile error. Anything
|
|
187
|
+
richer belongs in a `custom()` section.
|
|
147
188
|
- Section names may not shadow the response envelope
|
|
148
189
|
(`success`, `etag`, `notModified`, `sections`).
|
|
149
190
|
- **A bundle must never widen read access**: its `access.roles` must be a
|
|
@@ -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
|
|
@@ -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
|
-
|
|
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
|
|
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
|
|