@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 +1 -1
- package/dist/skill/docs/api/typescript.md +3 -1
- package/dist/skill/docs/configure/domains.md +16 -0
- package/dist/skill/docs/define/bundles.md +19 -4
- package/dist/skill/docs/platform/database/neon.md +15 -0
- package/dist/skill/docs/platform/realtime/named-invalidations.md +11 -1
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +17 -4
- package/package.json +1 -1
- package/src/skill/docs/api/typescript.md +3 -1
- package/src/skill/docs/configure/domains.md +16 -0
- package/src/skill/docs/define/bundles.md +19 -4
- package/src/skill/docs/platform/database/neon.md +15 -0
- package/src/skill/docs/platform/realtime/named-invalidations.md +11 -1
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +17 -4
package/dist/index.js
CHANGED
|
@@ -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.
|
|
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
|
|
146
|
-
|
|
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
|
-
|
|
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.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.
|
|
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
|
|
146
|
-
|
|
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
|
-
|
|
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
|
|