@quickback-dev/cli 0.70.45 → 0.72.3
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/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +10 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +7 -1
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +6 -5
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +6 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -1
- package/dist/lib/access-manifest-diff.js +10 -0
- package/dist/lib/access-manifest-diff.js.map +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +36 -0
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +13 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +4 -0
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/file-loader.d.ts +22 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +80 -18
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.js +9 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +10 -0
- package/dist/lib/harness.d.ts.map +1 -1
- package/dist/lib/harness.js +31 -0
- package/dist/lib/harness.js.map +1 -1
- package/dist/lib/migrations/executor.js +5 -1
- package/dist/lib/migrations/executor.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +23 -2
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +13 -1
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +33 -2
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +2 -2
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +3 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +14 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +29 -7
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/SKILL.md +64 -0
- package/dist/skill/docs/api/actions.md +73 -2
- package/dist/skill/docs/api/batch-operations.md +2 -0
- package/dist/skill/docs/api/caching.md +2 -2
- package/dist/skill/docs/api/crud.md +13 -0
- package/dist/skill/docs/api/errors.md +111 -10
- package/dist/skill/docs/api/index.md +24 -0
- package/dist/skill/docs/api/openapi.md +8 -0
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/configure/agents.md +73 -1
- package/dist/skill/docs/configure/auth.md +7 -1
- package/dist/skill/docs/configure/bindings.md +55 -0
- package/dist/skill/docs/configure/cloudflare-access.md +191 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/index.md +4 -2
- package/dist/skill/docs/configure/providers.md +2 -1
- package/dist/skill/docs/configure/tenancy.md +3 -0
- package/dist/skill/docs/configure/tenant-databases.md +2407 -0
- package/dist/skill/docs/define/access.md +33 -1
- package/dist/skill/docs/define/actions/defining.md +118 -1
- package/dist/skill/docs/define/actions/scoped-db.md +32 -8
- package/dist/skill/docs/define/areas.md +145 -2
- package/dist/skill/docs/define/diagnostics.md +160 -21
- package/dist/skill/docs/define/encryption.md +13 -2
- package/dist/skill/docs/define/fga.md +320 -42
- package/dist/skill/docs/define/firewall.md +4 -0
- package/dist/skill/docs/define/index.md +1 -0
- package/dist/skill/docs/define/read.md +46 -5
- package/dist/skill/docs/define/relationships.md +30 -12
- package/dist/skill/docs/define/schema.md +2 -0
- package/dist/skill/docs/define/scopes.md +393 -9
- package/dist/skill/docs/define/sealed-protocol.md +67 -12
- package/dist/skill/docs/define/transitions.md +4 -1
- package/dist/skill/docs/define/triggers.md +55 -1
- package/dist/skill/docs/platform/api-contract/index.md +9 -3
- package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/dist/skill/docs/platform/auth/using-auth.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +112 -3
- package/dist/skill/docs/platform/database/data-migrations.md +3 -1
- package/dist/skill/docs/platform/database/neon.md +10 -2
- package/dist/skill/docs/platform/queues/handlers.md +48 -16
- package/dist/skill/docs/platform/queues/using-queues.md +16 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +294 -17
- package/dist/skill/docs/platform/realtime/index.md +9 -6
- package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/r2.md +10 -1
- package/dist/skill/docs/platform/storage/using-r2.md +42 -1
- package/dist/skill/docs/tooling/output.md +9 -2
- package/dist/skill/docs/ui/account/features/admin.md +5 -3
- package/dist/skill/docs/ui/account/hooks.md +9 -2
- package/dist/skill/docs/ui/admin/connecting.md +3 -3
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/package.json +1 -1
- package/src/skill/SKILL.md +64 -0
- package/src/skill/docs/api/actions.md +73 -2
- package/src/skill/docs/api/batch-operations.md +2 -0
- package/src/skill/docs/api/caching.md +2 -2
- package/src/skill/docs/api/crud.md +13 -0
- package/src/skill/docs/api/errors.md +111 -10
- package/src/skill/docs/api/index.md +24 -0
- package/src/skill/docs/api/openapi.md +8 -0
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/configure/agents.md +73 -1
- package/src/skill/docs/configure/auth.md +7 -1
- package/src/skill/docs/configure/bindings.md +55 -0
- package/src/skill/docs/configure/cloudflare-access.md +191 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/index.md +4 -2
- package/src/skill/docs/configure/providers.md +2 -1
- package/src/skill/docs/configure/tenancy.md +3 -0
- package/src/skill/docs/configure/tenant-databases.md +2407 -0
- package/src/skill/docs/define/access.md +33 -1
- package/src/skill/docs/define/actions/defining.md +118 -1
- package/src/skill/docs/define/actions/scoped-db.md +32 -8
- package/src/skill/docs/define/areas.md +145 -2
- package/src/skill/docs/define/diagnostics.md +160 -21
- package/src/skill/docs/define/encryption.md +13 -2
- package/src/skill/docs/define/fga.md +320 -42
- package/src/skill/docs/define/firewall.md +4 -0
- package/src/skill/docs/define/index.md +1 -0
- package/src/skill/docs/define/read.md +46 -5
- package/src/skill/docs/define/relationships.md +30 -12
- package/src/skill/docs/define/schema.md +2 -0
- package/src/skill/docs/define/scopes.md +393 -9
- package/src/skill/docs/define/sealed-protocol.md +67 -12
- package/src/skill/docs/define/transitions.md +4 -1
- package/src/skill/docs/define/triggers.md +55 -1
- package/src/skill/docs/platform/api-contract/index.md +9 -3
- package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
- package/src/skill/docs/platform/auth/using-auth.md +1 -1
- package/src/skill/docs/platform/database/d1.md +112 -3
- package/src/skill/docs/platform/database/data-migrations.md +3 -1
- package/src/skill/docs/platform/database/neon.md +10 -2
- package/src/skill/docs/platform/queues/handlers.md +48 -16
- package/src/skill/docs/platform/queues/using-queues.md +16 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +294 -17
- package/src/skill/docs/platform/realtime/index.md +9 -6
- package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/r2.md +10 -1
- package/src/skill/docs/platform/storage/using-r2.md +42 -1
- package/src/skill/docs/tooling/output.md +9 -2
- package/src/skill/docs/ui/account/features/admin.md +5 -3
- package/src/skill/docs/ui/account/hooks.md +9 -2
- package/src/skill/docs/ui/admin/connecting.md +3 -3
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/dist/codex/AGENTS.md +0 -290
- package/dist/commands/build.test.d.ts.map +0 -1
- package/dist/commands/codex.d.ts +0 -16
- package/dist/commands/codex.d.ts.map +0 -1
- package/dist/commands/codex.js +0 -159
- package/dist/commands/codex.js.map +0 -1
- package/dist/commands/compile.d.ts +0 -62
- package/dist/commands/compile.d.ts.map +0 -1
- package/dist/commands/compile.js +0 -830
- package/dist/commands/compile.js.map +0 -1
- package/dist/commands/compile.test.d.ts.map +0 -1
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/commands/migrate.test.d.ts.map +0 -1
- package/dist/commands/migrations.test.d.ts.map +0 -1
- package/dist/commands/push.test.d.ts.map +0 -1
- package/dist/commands/schema.test.d.ts.map +0 -1
- package/dist/docs/content.d.ts +0 -7
- package/dist/docs/content.d.ts.map +0 -1
- package/dist/docs/content.js +0 -672
- package/dist/docs/content.js.map +0 -1
- package/dist/docs/index.test.d.ts.map +0 -1
- package/dist/lib/action-harvest.test.d.ts.map +0 -1
- package/dist/lib/api-client.test.d.ts.map +0 -1
- package/dist/lib/artifact-routing.test.d.ts.map +0 -1
- package/dist/lib/auth.test.d.ts.map +0 -1
- package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
- package/dist/lib/compiler-floor.test.d.ts.map +0 -1
- package/dist/lib/config-id-splice.test.d.ts.map +0 -1
- package/dist/lib/config-sync.test.d.ts.map +0 -1
- package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
- package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
- package/dist/lib/file-loader.test.d.ts.map +0 -1
- package/dist/lib/file-writer.test.d.ts.map +0 -1
- package/dist/lib/helpers.d.ts +0 -39
- package/dist/lib/helpers.d.ts.map +0 -1
- package/dist/lib/helpers.js +0 -299
- package/dist/lib/helpers.js.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
- package/dist/lib/migrations/executor.test.d.ts.map +0 -1
- package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
- package/dist/lib/migrations/lock.test.d.ts.map +0 -1
- package/dist/lib/migrations/paths.test.d.ts.map +0 -1
- package/dist/lib/migrations/plan.test.d.ts.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/staging.test.d.ts.map +0 -1
- package/dist/lib/neon-canary.test.d.ts.map +0 -1
- package/dist/lib/neon-target.test.d.ts.map +0 -1
- package/dist/lib/neon.test.d.ts.map +0 -1
- package/dist/lib/prepare-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
- package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
- package/dist/lib/shell.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
|
@@ -102,12 +102,19 @@ realtime: {
|
|
|
102
102
|
`/broadcast/v1/ws-ticket` now runs the **same first-match-wins gate** the
|
|
103
103
|
namespace uses, and issues the ticket for whichever lane matched:
|
|
104
104
|
|
|
105
|
-
| Caller matched via | Ticket
|
|
106
|
-
|
|
107
|
-
| `attendeeOf` (relationship lane) | `attendee` |
|
|
108
|
-
| `organizerOf` | `organizer` |
|
|
109
|
-
| `contractorOf` | `contractor` |
|
|
110
|
-
| `{ roles: ["admin","owner"] }` (bulk lane) | the caller's **org/membership roles** — no scope role |
|
|
105
|
+
| Caller matched via | Ticket `roles` | Ticket `scopeRoles` |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| `attendeeOf` (relationship lane) | `attendee` | `scope:event:attendee` |
|
|
108
|
+
| `organizerOf` | `organizer` | `scope:event:organizer` |
|
|
109
|
+
| `contractorOf` | `contractor` | `scope:event:contractor` |
|
|
110
|
+
| `{ roles: ["admin","owner"] }` (bulk lane) | the caller's **org/membership roles** | none — no scope role |
|
|
111
|
+
|
|
112
|
+
`scopeRoles` holds the proven roles qualified with their kind. The Broadcaster
|
|
113
|
+
matches `scope:<kind>:<role>` audiences and masking show-roles **only** against
|
|
114
|
+
it, never against `roles`. Every lane that proves a scope role signs it — the
|
|
115
|
+
namespace lanes, the tenant session lane, instance-bound OAuth tickets and
|
|
116
|
+
sessionless scope principals. When two kinds share the `requestField`, each
|
|
117
|
+
contributes its own `scope:<kind>:<role>` entry.
|
|
111
118
|
|
|
112
119
|
This closes the gap where the single-`role` form denied (`403`) an org admin who
|
|
113
120
|
could legitimately reach the room through the bulk lane but isn't a confirmed
|
|
@@ -132,6 +139,127 @@ Such consumers are listed in `quickback/authz-manifest.json` under the owning ar
|
|
|
132
139
|
> that column instead.) Use a tenant-scoped `scopeTable`.
|
|
133
140
|
|
|
134
141
|
|
|
142
|
+
### Instance-bound OAuth tokens
|
|
143
|
+
|
|
144
|
+
A caller holding only an [instance-bound OAuth token](/define/scopes#instance-bound-oauth-tokens) can mint a ticket when the ticket's `requestField` is the `requestField` of a scope kind with `oauth` (for example both `eventId`). The bound token reaches `POST /broadcast/v1/ws-ticket` and no other broadcast path, and the mint is confined to the token's own instance:
|
|
145
|
+
|
|
146
|
+
- The body's `requestField` must equal the token's `qb_scope.id`. Any other instance is `403`, even one the user has a relationship to.
|
|
147
|
+
- The mint rechecks the exact subject's current admission and intersects the token's roles with the configured ticket gate. Invitee/applicant roles do not enter an attendee/crew-only room.
|
|
148
|
+
- The ticket has no organization or account-wide identity: `scopeKey: '<scopeTable>:<id>'`, synthetic `userId: 'scope:<kind>:<subjectId>'`, and only that scope identity tag. It cannot receive account-user-targeted or `USER`-audience frames.
|
|
149
|
+
- View tickets (`{ view, rootId }`) and the personal fallback room are refused.
|
|
150
|
+
|
|
151
|
+
Every fresh ticket mint rechecks admission, so a removed guest cannot mint another ticket. Renewal needs a fresh ticket to extend authorization. The mint reads the clock **before** that admission check and checks the remaining lifetime again after it, so a slow admission never moves the 180-second cap later, and a ticket with no lifetime left is `403`. For a [tenant-backed kind](/configure/tenant-databases#tenant-admission-qbadmitscope) the recheck runs in the pinned tenant object (`qb.admitScope`) for the token's exact subject and proving table, and a tenant that cannot answer is `503 TENANT_ADMISSION_UNAVAILABLE`. The handshake ticket lasts at most 60 seconds and never beyond the source token expiry. The established socket cannot deliver after the source token expires (at most 180 seconds), even when ordinary leases are disabled; expiry closes it on traffic or the coalesced lease alarm. A bound token of a kind on a different `requestField` gets `403` from the mint.
|
|
152
|
+
|
|
153
|
+
### Tenant rooms
|
|
154
|
+
|
|
155
|
+
With [`tenancy.isolation: 'durable-object'`](/configure/tenant-databases), an
|
|
156
|
+
instance-bound OAuth kind whose tables live in tenant objects is
|
|
157
|
+
[tenant-backed](/configure/tenant-databases#tenant-backed-scope-kinds).
|
|
158
|
+
For such a kind, every realtime identity names its tenant:
|
|
159
|
+
|
|
160
|
+
- A room on a tenant table is `t1:<tenant>:<key>`, for example
|
|
161
|
+
`t1:org_a:events:evt_1`. Rooms of two organizations never collide, even
|
|
162
|
+
when their row ids do.
|
|
163
|
+
- The kind's identity tag is
|
|
164
|
+
`t1:<tenant>:scope:<kind>:<provingTable>:<subjectId>`. It names the proving
|
|
165
|
+
table because subjects proven by different tables can share an id.
|
|
166
|
+
- The ws-ticket mint derives the same keys, and the tenant admits every
|
|
167
|
+
ticket. A bound token uses the tenant it pins and `qb.admitScope` for its
|
|
168
|
+
exact subject. A session ticket routes the body's instance id through the
|
|
169
|
+
kind's lookup (`409 TENANT_AMBIGUOUS`; an unknown id is the same `403` as an
|
|
170
|
+
instance you can't prove; a failed lookup read `503 TENANT_UNAVAILABLE`),
|
|
171
|
+
never the active organization, and is admitted by `qb.admitScope` in that
|
|
172
|
+
tenant under its current epoch, as at authorize. Admission picks the user's
|
|
173
|
+
highest role in the kind's precedence, so the gate's lanes must confer a
|
|
174
|
+
prefix of that precedence (every role ranked above the ones they confer), or
|
|
175
|
+
a user holding a higher role would get `403`; otherwise the build fails
|
|
176
|
+
(`TENANCY_TICKET_GATE_UNSUPPORTED`). The room and the subject tag use
|
|
177
|
+
the tenant the object answered for; the ticket carries no organization. The
|
|
178
|
+
edge reads no tenant table. So a session gate on a tenant room must be the
|
|
179
|
+
kind's own admission: `realtime.wsTicket.namespace` naming a namespace whose
|
|
180
|
+
relationship lanes each confer roles of the kind. The namespace may also have
|
|
181
|
+
one `{ roles }` lane of plain organization roles (for example
|
|
182
|
+
`{ roles: ['member', 'admin', 'owner'] }`). That lane is checked first, as in
|
|
183
|
+
the namespace gate. It admits a caller at the edge, without reading the
|
|
184
|
+
tenant, only when the caller's verified active organization **is** the
|
|
185
|
+
tenant the lookup returned and the caller holds one of those roles. The
|
|
186
|
+
ticket is an organization-role ticket: room
|
|
187
|
+
`t1:<tenant>:<scopeTable>:<id>`, `organizationId` set to the tenant, the
|
|
188
|
+
caller's membership roles, and only the `user:<userId>` tag. The lane trusts
|
|
189
|
+
the lookup and reads no row, so after an instance is deleted, members of the
|
|
190
|
+
same organization can still mint its ticket until the lookup row is removed.
|
|
191
|
+
Other organizations can't. A caller whose active organization is another
|
|
192
|
+
organization falls through to the relationship lanes in the tenant. Unknown ids, ambiguous ids and failed
|
|
193
|
+
lookup reads get the same answers as above. An org-role (`access`), team,
|
|
194
|
+
FGA or single-probe gate fails the build (`TENANCY_TICKET_GATE_UNSUPPORTED`).
|
|
195
|
+
So does a `{ team }` lane, or a `{ roles }` lane naming a pseudo-role, a
|
|
196
|
+
`scope:` role or `role+` hierarchy. An open socket's revocation
|
|
197
|
+
bound differs by credential: a bound-token ticket is capped at the source
|
|
198
|
+
token's expiry (at most 180 seconds); a session ticket gets the ordinary
|
|
199
|
+
[authorization lease](#authorization-lease) (default 15 minutes), after which
|
|
200
|
+
a reconnect or renewal re-runs tenant admission. A `realtime.wsTicket` that
|
|
201
|
+
also accepts supplied-scope principals fails too
|
|
202
|
+
(`TENANCY_LEGACY_SCOPE_TICKET`), because a legacy scope claim carries no
|
|
203
|
+
tenant.
|
|
204
|
+
- A [resource-backed room](/platform/realtime/partyserver-rooms) whose
|
|
205
|
+
`access.resource` is a tenant table can't be checked against the platform D1,
|
|
206
|
+
because the row isn't there. Its room key column needs a lookup:
|
|
207
|
+
`tenancy.lookups.<name>: { table, column: <key> }`. Without one, the build
|
|
208
|
+
fails (`TENANCY_ROOM_LOOKUP`). The room's role gate (`access.roles`, or the
|
|
209
|
+
table's `read.access`) runs on the edge before any read. Then the edge
|
|
210
|
+
resolves the room id through the lookup and requires the caller's verified
|
|
211
|
+
active organization to be that tenant. The table firewall and room-key match
|
|
212
|
+
then run in that organization's object (`qb.roomAccess`), with the caller's
|
|
213
|
+
user id, organization roles and active team, so a team-scoped row admits the
|
|
214
|
+
same callers as `GET /:id`. An unknown,
|
|
215
|
+
ambiguous or denied id, or one in another organization, gets `403`. A failed
|
|
216
|
+
lookup read or an unavailable tenant gets `503`. Only organization members of
|
|
217
|
+
the row's tenant can open such a room. Several forms fail the build
|
|
218
|
+
(`TENANCY_ROOM_UNSUPPORTED`): multi-resource rooms (`access.resources`) that
|
|
219
|
+
reach a tenant table, rooms on partitioned tables, and an inherited
|
|
220
|
+
`read.access` with a `record:` predicate. The room class runs in the edge
|
|
221
|
+
Worker, so keep it outside tenant feature folders.
|
|
222
|
+
- Broadcasts from a tenant object reach the edge through its outbox. The edge
|
|
223
|
+
replays them with `createRealtime(env, { tenantId })`, taking the tenant from
|
|
224
|
+
the object's own name, never from tenant code. The one send step every helper
|
|
225
|
+
ends in qualifies them: CRUD broadcasts, `scopeKeyFrom` deliveries, action
|
|
226
|
+
`emit`, changesets, invalidations, custom namespaces and raw sends. A room key
|
|
227
|
+
on a tenant table moves under `t1:<tenant>:`. The send throws, and nothing is
|
|
228
|
+
sent, when a tenant object addresses a room that is not on a tenant table
|
|
229
|
+
(`TENANT_REALTIME_PLATFORM_ROOM`, refused at build time where the room is
|
|
230
|
+
declared), another tenant's room, or another organization
|
|
231
|
+
(`TENANT_REALTIME_CROSS_TENANT`). The drain logs the error.
|
|
232
|
+
- Tags are qualified the same way. Because a tag only narrows a send, a tag
|
|
233
|
+
that cannot be qualified is dropped and logged, not the whole send. That covers
|
|
234
|
+
another tenant's tag, or `scope:<kind>:<subjectId>` for a kind with several
|
|
235
|
+
proving tables and none named. A send whose tags are all dropped reaches
|
|
236
|
+
nobody. `scope:<kind>:<subjectId>` qualifies when the kind has one proving
|
|
237
|
+
table, and `scope:<kind>:<provingTable>:<subjectId>` qualifies when it names
|
|
238
|
+
one of them. A recipients resolver names the proving table with
|
|
239
|
+
`recipient.scope({ kind, subjectId, provingTable })`, which becomes
|
|
240
|
+
`scope:<kind>:<provingTable>:<subjectId>`. It may leave `provingTable` out
|
|
241
|
+
for a kind with one proving table. For a kind with several, a call the
|
|
242
|
+
compiler can see that leaves it out fails the build
|
|
243
|
+
(`TENANCY_REALTIME_TAG_AMBIGUOUS`, with the call's file and line), and an
|
|
244
|
+
identity that reaches the send without it is dropped. A literal
|
|
245
|
+
`provingTable` that is not one of the kind's fails the build in any mode
|
|
246
|
+
(`REALTIME_RECIPIENT_PROVING_TABLE`). Tenant code can build keys itself with
|
|
247
|
+
`tenantRoomKey` / `tenantScopeTag`, exported by `src/tenant/realtime.ts`.
|
|
248
|
+
- On the edge, `createRealtime(env)` throws `TENANT_REALTIME_UNQUALIFIED`,
|
|
249
|
+
before sending, for an unqualified key that names a tenant table or a view
|
|
250
|
+
rooted on one. Build the key with `tenantRoomKey(tenantId, key)` from
|
|
251
|
+
`src/lib/realtime.ts`. A tenant-backed kind's tag without a tenant is dropped.
|
|
252
|
+
Sends run after the write commits, so this throw doesn't undo the write: the
|
|
253
|
+
write stands, and the send doesn't happen.
|
|
254
|
+
- A tenant object can still send a `userId`-only message to any user's personal
|
|
255
|
+
`user-<id>` room, as edge code can. That room belongs to the user, not to an
|
|
256
|
+
organization. Tenant code is your application's own code, so this is intended.
|
|
257
|
+
|
|
258
|
+
Organization rooms (`organizationId`) and personal `user-<id>` rooms keep
|
|
259
|
+
their names. View rooms on tenant tables are still refused at build time,
|
|
260
|
+
because the view materializer runs on the edge (`TENANCY_ADMISSION_DEPENDENCY`,
|
|
261
|
+
and `TENANCY_REALTIME_VIEW_ROOM` while a kind is tenant-backed).
|
|
262
|
+
|
|
135
263
|
## When auto-broadcast fires (and when you call it manually)
|
|
136
264
|
|
|
137
265
|
Quickback emits auto-broadcasts in **only one place**: the generated CRUD route handlers (`POST /` create, `PATCH /:id` update, `DELETE /:id` delete) for resources that **explicitly declare** a `realtime.enabled` block. The project-level `dbConfig.realtime` switch wires the *transport* (Broadcaster DO + ws-ticket route) but does **not** auto-enable broadcasting on any resource — broadcasting is opt-in per resource, like CRUD. Those handlers wrap each successful write with a `realtime.insert / update / delete` call before responding.
|
|
@@ -142,7 +270,9 @@ audience (or the deprecated `requiredRoles` alias) becomes the broadcast's
|
|
|
142
270
|
`PUBLIC`/`USER` evaluated at fanout exactly as REST evaluates them), and the
|
|
143
271
|
table's effective masking config —
|
|
144
272
|
declared plus auto-detected sensitive columns — is applied per subscriber
|
|
145
|
-
role at fanout, matching what the HTTP routes mask
|
|
273
|
+
role at fanout, matching what the HTTP routes mask: a `scope:<kind>:<role>`
|
|
274
|
+
show-role reveals only to a socket that proved that role, and a bare show-role
|
|
275
|
+
never reveals to a scope ticket. A `type: 'custom'` mask
|
|
146
276
|
function can't be replicated by the Broadcaster, so those columns broadcast
|
|
147
277
|
as `[REDACTED]` (fail closed). Tables that declare neither broadcast openly,
|
|
148
278
|
as before.
|
|
@@ -160,6 +290,30 @@ Everywhere else — action handlers, queue consumers, scheduled jobs, custom Hon
|
|
|
160
290
|
|
|
161
291
|
The rule of thumb: opt the table into `realtime: { emitFromActions: true }` (or give the action an `emit:` block for the pre-bound `emitCrud(row, oldRow?)` helper) and the frames take care of themselves; otherwise, if your code calls `db.insert(...)` directly, you also call `realtime.insert(...)` directly on the next line.
|
|
162
292
|
|
|
293
|
+
An action `emit:` — record-bound, standalone, root-mounted or claimed by a
|
|
294
|
+
namespace — inherits the emitting table's realtime spec:
|
|
295
|
+
|
|
296
|
+
| | Default | `emit.target` override |
|
|
297
|
+
|---|---|---|
|
|
298
|
+
| Room | The table's row-derived room: `<scopeTable>:<row[scopeField]>`, or the organization room when the table has no `scopeField` | `target.scopeKey` (a `"prefix:{column}"` template; columns must be declared on the table) |
|
|
299
|
+
| Audience | The table's `realtime.access.roles` | `target.targetRoles` |
|
|
300
|
+
| Masking | The table's effective masking config, whenever the table masks | None — masking always rides the frame |
|
|
301
|
+
|
|
302
|
+
{/* doc-compile: skip — defineAction excerpt; the body is elided */}
|
|
303
|
+
```typescript
|
|
304
|
+
export default defineAction({
|
|
305
|
+
path: "/event/:eventId/locations",
|
|
306
|
+
access: { roles: ["owner", "scope:event:organizer"] },
|
|
307
|
+
emit: { table: "locations" }, // events:{row.eventId}, the table's audience, its masking
|
|
308
|
+
async execute({ db, input, emitCrud }) { /* … */ },
|
|
309
|
+
});
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
`emit.table` must name the action's own feature table. With no table audience
|
|
313
|
+
and no `target.targetRoles`, the build fails. A namespace-claimed action whose
|
|
314
|
+
table has no `scopeField` warns: its frames go to the organization room, which
|
|
315
|
+
sockets admitted through the namespace's relationship lanes never join.
|
|
316
|
+
|
|
163
317
|
Two capture caveats: inserts that skip `.returning()` emit the values as written (DB-default columns absent), and updates/deletes cost one extra pre-select on the same WHERE — it replaces the hand-written read every manual emit needed anyway. Capture covers the feature's own table on record-bound and bulk routes; standalone actions and cross-feature writes use `emit:`/`emitCrud` or the raw `realtime.*` API.
|
|
164
318
|
|
|
165
319
|
## Generated Helper
|
|
@@ -347,7 +501,9 @@ await realtime.broadcast('application-received', {
|
|
|
347
501
|
```
|
|
348
502
|
|
|
349
503
|
`userId` targeting matches the **socket identity** — the Better Auth user id, or
|
|
350
|
-
the synthetic `scope:<subjectId>` principal for sessionless scope
|
|
504
|
+
the synthetic `scope:<kind>:<subjectId>` principal for sessionless scope and
|
|
505
|
+
instance-bound OAuth connections. These exact-subject credentials never carry
|
|
506
|
+
the linked account identity. If
|
|
351
507
|
the same person can connect through either door, prefer
|
|
352
508
|
[identity-tag targeting](#identity-tag-targeting) — one send reaches both.
|
|
353
509
|
|
|
@@ -374,6 +530,19 @@ authenticated subscriber in the scope, say so explicitly with
|
|
|
374
530
|
`AUTHENTICATED`, `USER`, `SYSADMIN`) are evaluated exactly as the REST access
|
|
375
531
|
evaluator does.
|
|
376
532
|
|
|
533
|
+
Address scope roles in their qualified form. `scope:<kind>:<role>` reaches only
|
|
534
|
+
sockets whose ticket proved that role of that kind:
|
|
535
|
+
|
|
536
|
+
```typescript
|
|
537
|
+
// Event organizers and the org's owners — not a booth's organizers.
|
|
538
|
+
await realtime.update('locations', newRow, oldRow, { scopeKey: 'events:' + newRow.eventId }, {
|
|
539
|
+
targetRoles: ['owner', 'scope:event:organizer', 'scope:event:organizer_full'],
|
|
540
|
+
});
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
A bare name matches org membership roles and, as deprecated legacy behavior, a
|
|
544
|
+
scope ticket's bare role names from any kind.
|
|
545
|
+
|
|
377
546
|
> **Migrating from pre-0.48:** custom `realtime.broadcast(...)` /
|
|
378
547
|
> `realtime.insert(...)` calls that omitted `targetRoles` used to fan out to
|
|
379
548
|
> everyone; they now silently deliver to nobody. Audit every manual send and add
|
|
@@ -384,9 +553,10 @@ evaluator does.
|
|
|
384
553
|
Every connection carries **identity tags**, proven at ticket mint and signed
|
|
385
554
|
into the ticket (never client-supplied):
|
|
386
555
|
|
|
387
|
-
- `user:<userId>` —
|
|
556
|
+
- `user:<userId>` — full Better Auth sessions and ordinary OAuth callers; never an instance-bound OAuth or sessionless scope credential
|
|
388
557
|
- `scope:<kind>:<subjectId>` — when a scope subject is proven, on **either**
|
|
389
|
-
door: a sessionless scope principal's verified claim,
|
|
558
|
+
door: a sessionless scope principal's verified claim, an instance-bound OAuth
|
|
559
|
+
credential's exact subject, or a full Better Auth caller
|
|
390
560
|
whose matched relationship lane maps to a scope kind with
|
|
391
561
|
`subject: 'supplied' | 'both'`. Both doors stamp the **identical** tag (the
|
|
392
562
|
subject row's id), which is the point.
|
|
@@ -432,7 +602,13 @@ never affect an already-connected socket. The lease closes that gap:
|
|
|
432
602
|
(default **15 minutes**).
|
|
433
603
|
- The fan-out **skips expired connections** — they receive nothing — and closes
|
|
434
604
|
them with code **4401** so the client knows to re-ticket rather than blindly
|
|
435
|
-
reconnect. Inbound messages
|
|
605
|
+
reconnect. Inbound messages are enforced the same way. Heartbeat pings are
|
|
606
|
+
answered by the runtime without waking the object (see
|
|
607
|
+
[Heartbeats](#heartbeats)), so they no longer carry the enforcement. Instead,
|
|
608
|
+
a Durable Object alarm sweeps idle sockets. Sweeps are coalesced into
|
|
609
|
+
60-second buckets, so an idle socket is closed up to a minute after its
|
|
610
|
+
lease lapses, and a room wakes at most once per bucket in which some lease
|
|
611
|
+
lapses.
|
|
436
612
|
- Renewal happens at mint: `POST /broadcast/v1/ws-ticket` re-runs the full
|
|
437
613
|
authorization gate (session validity, revocation checks, relationship /
|
|
438
614
|
scope-claim probes), so a revoked principal simply can't obtain a renewal
|
|
@@ -454,7 +630,35 @@ providers: {
|
|
|
454
630
|
}
|
|
455
631
|
```
|
|
456
632
|
|
|
457
|
-
The lease must be at least 60 seconds (the handshake-ticket TTL).
|
|
633
|
+
The configured lease must be at least 60 seconds (the handshake-ticket TTL).
|
|
634
|
+
|
|
635
|
+
Scope-only tickets (including legacy scope kinds without `oauth`) also honor the
|
|
636
|
+
configured ticket gate. Only supplied-reachable roles (`subject: 'supplied'` or
|
|
637
|
+
`'both'`) whose relationship is admitted by that gate, or whose exact
|
|
638
|
+
`scope:<kind>:<role>` grant appears in the namespace, can mint a ticket. Roles
|
|
639
|
+
are intersected per kind: sharing `requestField` or a role name cannot admit a
|
|
640
|
+
foreign kind, invitee, or applicant. Mixed claims retain only admitted roles.
|
|
641
|
+
Organization-role and user-based FGA gates do not accept scope-only claims as
|
|
642
|
+
proof. Full sessions continue to use their configured account gates.
|
|
643
|
+
Scope-only tickets carry only their own kind/subject identity and cannot receive
|
|
644
|
+
account-tag, account-userId, or `USER`-audience deliveries.
|
|
645
|
+
|
|
646
|
+
Instance-bound OAuth tickets recheck relationship admission on every mint and
|
|
647
|
+
intersect the current roles with the configured ticket gate's relationship
|
|
648
|
+
lanes. A namespace that admits attendee and crew relationships does not issue
|
|
649
|
+
room tickets to invitee or applicant roles declared elsewhere on the same
|
|
650
|
+
scope kind. Org-role, team, and FGA grants require full account authority and
|
|
651
|
+
cannot authorize a bound credential.
|
|
652
|
+
|
|
653
|
+
A bound ticket identifies only `scope:<kind>:<subjectId>`: both its synthetic
|
|
654
|
+
`userId` and its sole identity tag use that value. It never carries
|
|
655
|
+
`user:<accountId>` and cannot receive account-targeted frames through tags or
|
|
656
|
+
`userId`. `USER` audiences exclude these exact-subject credentials;
|
|
657
|
+
`AUTHENTICATED` still matches, and so does a `scope:<kind>:<role>` audience
|
|
658
|
+
naming one of their admitted roles (the ticket's `scopeRoles`). Full sessions
|
|
659
|
+
keep their account identity and `USER` behavior.
|
|
660
|
+
|
|
661
|
+
Their handshake expiry and socket authorization lease cannot outlive the source access token (at most 180 seconds), even with `lease: false`. Revoked relationships cannot mint another ticket; after the cap, the next delivery or inbound message closes the socket with 4401 without delivering data. Renewal requires a fresh admitted ticket.
|
|
458
662
|
|
|
459
663
|
### In-place renewal (`reauth`)
|
|
460
664
|
|
|
@@ -487,7 +691,9 @@ ws.onclose = (event) => {
|
|
|
487
691
|
Renewal is **strict**: the fresh ticket must carry the same `userId`,
|
|
488
692
|
`scopeKey`/`organizationId`, and the **exact same tag set** as the live socket
|
|
489
693
|
(tags are immutable). A renewal that matches extends the lease and refreshes
|
|
490
|
-
`role`/`roles` in place — live permission changes without socket
|
|
694
|
+
`role`/`roles`/`scopeRoles` in place — live permission changes without socket
|
|
695
|
+
churn; a renewal that drops a scope role drops its audiences and reveals at
|
|
696
|
+
once. One
|
|
491
697
|
that doesn't closes the socket with 4401: reconnect fresh.
|
|
492
698
|
|
|
493
699
|
Clients that never send `reauth` still work — their socket is closed with 4401
|
|
@@ -512,7 +718,10 @@ await realtime.insert('candidates', newCandidate, ctx.activeOrgId!, {
|
|
|
512
718
|
- Each subscriber receives a payload masked according to their role
|
|
513
719
|
- Roles in the `show.roles` array see unmasked values
|
|
514
720
|
- All other roles see the masked version
|
|
515
|
-
-
|
|
721
|
+
- A `scope:<kind>:<role>` entry reveals only to a socket whose ticket proved that role of that kind
|
|
722
|
+
- A bare entry never reveals to a scope ticket (its bare roles are scope names; REST tests `ctx.roles`)
|
|
723
|
+
- A socket with no roles sees every rule masked
|
|
724
|
+
- Each distinct masking variant (the subscriber's role sets — bare and scope — plus whether they own the row) is built and serialized **once per publish** and reused for every subscriber in that variant — a room of 1,000 members holding three role sets serializes three frames, not 1,000
|
|
516
725
|
|
|
517
726
|
**Available mask types:**
|
|
518
727
|
| Type | Example Output |
|
|
@@ -620,10 +829,20 @@ name = "BROADCASTER"
|
|
|
620
829
|
class_name = "Broadcaster"
|
|
621
830
|
|
|
622
831
|
[[migrations]]
|
|
623
|
-
tag = "
|
|
624
|
-
|
|
832
|
+
tag = "qb-do-Broadcaster"
|
|
833
|
+
new_sqlite_classes = ["Broadcaster"]
|
|
625
834
|
```
|
|
626
835
|
|
|
836
|
+
With [`bindings.durableObjectLifecycle: "exports"`](/configure/bindings#durableobjectlifecycle) the migration becomes an `exports` entry:
|
|
837
|
+
|
|
838
|
+
```toml
|
|
839
|
+
[exports.Broadcaster]
|
|
840
|
+
type = "durable-object"
|
|
841
|
+
storage = "sqlite"
|
|
842
|
+
```
|
|
843
|
+
|
|
844
|
+
A project first deployed with the older `tag = "v1"` / `new_classes` shape keeps that entry, and its `exports` entry is `storage = "legacy-kv"`.
|
|
845
|
+
|
|
627
846
|
## Architecture
|
|
628
847
|
|
|
629
848
|
```
|
|
@@ -641,9 +860,67 @@ new_classes = ["Broadcaster"]
|
|
|
641
860
|
```
|
|
642
861
|
|
|
643
862
|
1. **Client gets a ticket** — `POST /broadcast/v1/ws-ticket` on the main API (session-authenticated). Returns a 60-second HMAC-signed ticket.
|
|
644
|
-
2. **Client connects** — Opens WebSocket with `?ws_ticket=<ticket>`. The Durable Object
|
|
863
|
+
2. **Client connects** — Opens WebSocket with `?ws_ticket=<ticket>`. The Worker verifies the ticket's HMAC and expiry **before** it touches a Durable Object, so an invalid ticket gets `401` without waking any room. It then routes to the room named by the verified ticket only (`scopeKey`, else `organizationId`). Query parameters never pick the room. The Durable Object verifies the ticket again and attaches the socket to the ticket's scope. Each Broadcaster instance *is* one room (its `ctx.id.name`), and it refuses with **403** a valid ticket for a different room. If the runtime doesn't expose `ctx.id.name` (wrangler/workerd older than March 2026), upgrades fail with **500** and a log line telling you to update wrangler.
|
|
645
864
|
3. **API broadcasts** — After CRUD ops, or from custom handlers, the API calls the Broadcaster DO directly via its binding (in-process, no network hop) using the same target model.
|
|
646
865
|
|
|
866
|
+
## Delivery and Failure Handling
|
|
867
|
+
|
|
868
|
+
Sends are **awaited** and best-effort: a failed publish never fails the
|
|
869
|
+
request that emitted it. The generated helper follows Cloudflare's
|
|
870
|
+
[Rules of Durable Objects](https://developers.cloudflare.com/durable-objects/best-practices/rules-of-durable-objects/)
|
|
871
|
+
for stub errors:
|
|
872
|
+
|
|
873
|
+
| Error | Behavior |
|
|
874
|
+
|-------|----------|
|
|
875
|
+
| `durableObjectReset` (the object restarted) | Retried **once** on a fresh stub |
|
|
876
|
+
| `retryable` (and not `overloaded`) | Retried **once** on a fresh stub |
|
|
877
|
+
| `overloaded` | **Not retried** (a retry feeds the overload). Logged as a structured warning, `{"event":"durable_object.dropped","reason":"overloaded","drops":N,…}`, where `drops` counts per isolate |
|
|
878
|
+
| `Subrequest depth limit exceeded` | Not retried; logged as `durable_object.failed` |
|
|
879
|
+
| anything else | Not retried; logged as `durable_object.failed` |
|
|
880
|
+
|
|
881
|
+
Every call into the Broadcaster (the publish including its one retry, the
|
|
882
|
+
live-view `seq` read, and in separate-Worker mode the service-binding fetch)
|
|
883
|
+
also races a **5-second deadline**. A stalled Broadcaster therefore costs the
|
|
884
|
+
emitting request at most 5 seconds, not the client's whole timeout, even
|
|
885
|
+
though the write has already committed. An expired call is logged like any other
|
|
886
|
+
failed publish (`durable_object.failed` for the inline stub), and the tenant
|
|
887
|
+
outbox treats it as retryable. If the
|
|
888
|
+
first attempt lands late, the publish id dedupes it.
|
|
889
|
+
|
|
890
|
+
Every send carries one **publish id**, and a retry reuses it. The Broadcaster
|
|
891
|
+
remembers its 64 most recent ids. When a retry arrives for a first attempt that
|
|
892
|
+
actually landed (only the reply was lost), it is acknowledged without a second
|
|
893
|
+
fan-out or a new live-view `seq`. So a retry can never make a concurrent update
|
|
894
|
+
look older than it is. Webhook bodies carry the same value as `id`, so
|
|
895
|
+
receivers can dedupe too. A dropped frame is never redelivered. Live views
|
|
896
|
+
heal the gap through `qbseq`: a jump in the sequence triggers a resync (see
|
|
897
|
+
[Live Views](/platform/realtime/live-views)). For table changes and broadcasts,
|
|
898
|
+
refetch on reconnect. In `separate` mode the broadcast Worker applies the same
|
|
899
|
+
retry and answers an overloaded publish with **503**, which the helper counts
|
|
900
|
+
as the same drop.
|
|
901
|
+
|
|
902
|
+
### Heartbeats
|
|
903
|
+
|
|
904
|
+
Send exactly `{"type":"ping"}` (no whitespace) and the runtime answers
|
|
905
|
+
`{"type":"pong"}` through `setWebSocketAutoResponse`, **without waking a
|
|
906
|
+
hibernated Broadcaster**. No duration is billed per socket per beat. A ping
|
|
907
|
+
serialized any other way still gets the same pong, but it wakes the object.
|
|
908
|
+
Protocol-level WebSocket pings, such as OkHttp's `pingInterval` or
|
|
909
|
+
`URLSessionWebSocketTask.sendPing`, are also answered without a wake.
|
|
910
|
+
|
|
911
|
+
Neither kind of ping enforces the [authorization lease](#authorization-lease).
|
|
912
|
+
An alarm closes lapsed sockets with 4401 instead.
|
|
913
|
+
|
|
914
|
+
### Scaling a room
|
|
915
|
+
|
|
916
|
+
Fan-out is O(sockets in the room) per publish, and one Durable Object handles
|
|
917
|
+
roughly **1,000 simple requests per second**. Each Broadcaster is one room: the
|
|
918
|
+
`scopeKey` you target, else the organization. When a single organization gets
|
|
919
|
+
very large, or one surface publishes very frequently, target a **finer
|
|
920
|
+
`scopeKey`** (for example per event or per channel instead of per org) so that
|
|
921
|
+
each room holds fewer sockets and receives fewer publishes. Live views already
|
|
922
|
+
shard this way: each `view:<name>:<rootId>` surface is its own object.
|
|
923
|
+
|
|
647
924
|
## Best Practices
|
|
648
925
|
|
|
649
926
|
### Broadcast After Commit
|
|
@@ -75,8 +75,9 @@ export default feature("applications", {
|
|
|
75
75
|
// Audience — WHO may receive these live rows. Same { roles } shape as
|
|
76
76
|
// read.access / crud.*.access. MANDATORY and fail-closed: a broadcast
|
|
77
77
|
// reaches every subscriber in the room, so the audience is not optional.
|
|
78
|
-
// Omit it (or leave it empty) and compilation fails. Roles may be
|
|
79
|
-
// membership
|
|
78
|
+
// Omit it (or leave it empty) and compilation fails. Roles may be org
|
|
79
|
+
// membership roles, qualified scope roles (scope:<kind>:<role>, matched
|
|
80
|
+
// only against the kind the ticket proved) or UPPERCASE pseudo-roles.
|
|
80
81
|
access: { roles: ["recruiter", "hiring-manager"] },
|
|
81
82
|
fields: ["id", "candidateId", "stage"],
|
|
82
83
|
},
|
|
@@ -223,8 +224,10 @@ realtime: {
|
|
|
223
224
|
|
|
224
225
|
Writes to the table through the scoped `db` inside record-bound and bulk
|
|
225
226
|
actions emit frames byte-compatible with auto-CRUD (same envelope, masking,
|
|
226
|
-
audience), after commit, best-effort. For projections
|
|
227
|
-
|
|
228
|
-
`emitCrud(row, oldRow?)` helper
|
|
229
|
-
the
|
|
227
|
+
audience), after commit, best-effort. For projections and standalone or
|
|
228
|
+
namespace-claimed actions, declare an action-level `emit:` to get a pre-bound
|
|
229
|
+
`emitCrud(row, oldRow?)` helper; it inherits the table's room, audience and
|
|
230
|
+
masking. `emit.table` must be the action's own feature table — emit to another
|
|
231
|
+
feature's table with the raw `realtime.*` API. Full details and the capture
|
|
232
|
+
caveats live in the [realtime docs](/platform/realtime/durable-objects).
|
|
230
233
|
|
|
@@ -91,7 +91,9 @@ export const documentWatchers = defineRealtimeDelivery({
|
|
|
91
91
|
|
|
92
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
93
|
|
|
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.
|
|
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, provingTable? })`). It sees only what the acting caller could see. Resolved identities beyond a safety cap are truncated with a warning; malformed returns are dropped.
|
|
95
|
+
|
|
96
|
+
`provingTable` names the table that proves the subject, a relationship `from` of the kind's roles. A literal one that isn't fails the build (`REALTIME_RECIPIENT_PROVING_TABLE`). With shared tenancy the tag stays `scope:<kind>:<subjectId>`, so the table does not change who receives the send. For a [tenant-backed kind](/platform/realtime/durable-objects#tenant-rooms) the tag is `scope:<kind>:<provingTable>:<subjectId>`, and a kind with several proving tables requires it.
|
|
95
97
|
|
|
96
98
|
## 4. Firing from an action — `invalidates`
|
|
97
99
|
|
|
@@ -151,7 +151,17 @@ Custom namespaces (from `defineRealtime()`) use the format `namespace:event` —
|
|
|
151
151
|
|
|
152
152
|
### Role-Based Filtering
|
|
153
153
|
|
|
154
|
-
Events are only delivered to subscribers who fall within the broadcast's audience. A broadcasting table's realtime config **must** declare `access: { roles: [...] }` — e.g. `access: { roles: ["hiring-manager", "recruiter"] }` delivers only to those roles.
|
|
154
|
+
Events are only delivered to subscribers who fall within the broadcast's audience. A broadcasting table's realtime config **must** declare `access: { roles: [...] }` — e.g. `access: { roles: ["hiring-manager", "recruiter"] }` delivers only to those roles. This is **fail-closed**: an empty or omitted audience delivers to no one (and is a compile error for a broadcasting resource). Applies to generated CRUD broadcasts, action `emit:` frames and [live view](/platform/realtime/live-views) `view_changes` deltas alike.
|
|
155
|
+
|
|
156
|
+
Each audience entry is matched against the socket's ws-ticket:
|
|
157
|
+
|
|
158
|
+
| Entry | Delivers to |
|
|
159
|
+
|---|---|
|
|
160
|
+
| `PUBLIC`, `AUTHENTICATED`, `USER`, `SYSADMIN` | Same pseudo-role semantics as REST (`PUBLIC` = everyone in the room). |
|
|
161
|
+
| `scope:<kind>:<role>` | Sockets whose ticket **proved** that role **of that kind** (the ticket's `scopeRoles`). A `scope:event:organizer` audience never reaches a `booth` organizer, and never an org member whose role string happens to read `scope:…`. |
|
|
162
|
+
| bare `name` | Sockets whose ticket `roles` contain `name` — org membership roles. **Deprecated legacy:** a scope ticket's bare role names also match, from any kind. The compiler warns (`REALTIME_BARE_SCOPE_ROLE_AUDIENCE`) when a bare name is a declared scope role; write `scope:<kind>:<role>`. |
|
|
163
|
+
|
|
164
|
+
Realtime has no row firewall: every socket in the audience receives every change in the room. The compiler warns (`REALTIME_SCOPE_AUDIENCE_WIDER_THAN_READ`) when the audience names a `scope:` role that a plain role-list `read.access` does not admit — drop it from the audience or admit it in `read`.
|
|
155
165
|
|
|
156
166
|
### Named rules and gates in `requiredRoles`
|
|
157
167
|
|
|
@@ -174,7 +184,13 @@ masking: {
|
|
|
174
184
|
- **Owner sees:** `{ ssn: "123-45-6789" }`
|
|
175
185
|
- **Recruiter sees:** `{ ssn: "*****6789" }`
|
|
176
186
|
|
|
177
|
-
|
|
187
|
+
`show.roles` is evaluated against the socket's ticket with the same split as REST:
|
|
188
|
+
|
|
189
|
+
- `scope:<kind>:<role>` reveals only to a ticket that proved that role of that kind.
|
|
190
|
+
- A bare name reveals only to a membership ticket. A scope ticket **never** satisfies a bare show-role — REST tests `ctx.roles`, which a scope-only caller does not hold.
|
|
191
|
+
- A socket with no roles reveals nothing.
|
|
192
|
+
|
|
193
|
+
Masking is pre-computed per role set (O(role sets), not O(subscribers)) for efficiency. A `type: 'custom'` mask function can't run inside the Broadcaster — those columns broadcast as `[REDACTED]` (fail closed).
|
|
178
194
|
|
|
179
195
|
### User-Specific Events
|
|
180
196
|
|
|
@@ -182,7 +198,7 @@ Events can target a specific user lane. Only that user receives the broadcast
|
|
|
182
198
|
|
|
183
199
|
### Scope Isolation
|
|
184
200
|
|
|
185
|
-
Each WebSocket connection is attached to exactly one resolved scope: `scopeKey`, `organizationId`, or `userId`. Users can only subscribe to the scope stamped into their ws ticket, enforced during authentication and ticket minting.
|
|
201
|
+
Each WebSocket connection is attached to exactly one resolved scope: `scopeKey`, `organizationId`, or `userId`. Users can only subscribe to the scope stamped into their ws ticket, enforced during authentication and ticket minting. The Broadcaster instance re-checks this at upgrade: a valid ticket presented to a different room is refused with **403**.
|
|
186
202
|
|
|
187
203
|
There is **no shared fallback room**. A signed-in caller with no active
|
|
188
204
|
organization (a self-registered account, an attendee-only account, external
|
|
@@ -194,6 +210,8 @@ read, and a broadcast target that names no room is refused.
|
|
|
194
210
|
|
|
195
211
|
## Reconnection
|
|
196
212
|
|
|
213
|
+
For a heartbeat, send exactly `{"type":"ping"}`. The runtime answers `{"type":"pong"}` without waking a hibernated Broadcaster (see [Heartbeats](/platform/realtime/durable-objects#heartbeats)).
|
|
214
|
+
|
|
197
215
|
WebSocket connections can drop due to network issues. Implement reconnection logic in your client — note that you need to fetch a fresh ticket on each reconnect since tickets expire after 60 seconds:
|
|
198
216
|
|
|
199
217
|
```typescript
|
|
@@ -256,6 +274,13 @@ either path.
|
|
|
256
274
|
| `postgres_changes` | `dev.quickback.<project>.<table>.<insert\|update\|delete>` | `{ table, schema, eventType, new, old }` | `qbframe: "postgres_changes"` |
|
|
257
275
|
| `view_changes` | `dev.quickback.<project>.view.<viewName>.changed` | `{ view, rootId, delta }` | `qbframe: "view_changes"`, `qbseq` (the per-surface monotonic seq — your reconnect/gap-detection contract) |
|
|
258
276
|
|
|
277
|
+
**`id` identifies the logical send.** It is `evt_<publishId>`: the same on
|
|
278
|
+
every socket the send reached and on every redelivery of it. The Broadcaster
|
|
279
|
+
drops a repeated publish it still remembers (its last 64 ids). A send from a
|
|
280
|
+
[tenant object](/configure/tenant-databases#outbox-delivery) can still arrive
|
|
281
|
+
twice in a rare crash case, after its lease expires. So treat `id` as the
|
|
282
|
+
dedupe key: keep the ids you applied recently and drop a repeat.
|
|
283
|
+
|
|
259
284
|
**Discriminate frames on the `qbframe` extension.** Never on `type`, whose
|
|
260
285
|
shape is not a stable contract, and never on payload keys — named-invalidation
|
|
261
286
|
payloads are author-supplied maps, so a broadcast whose payload happens to
|
|
@@ -40,7 +40,7 @@ Two `../` — up from `services/schedules/` to `quickback/`, then down into `fea
|
|
|
40
40
|
## What the compiler emits
|
|
41
41
|
|
|
42
42
|
1. **`scheduled(event, env, ctx)`** in the Worker's default export, dispatching to every schedule whose cron matches `event.cron`. Multiple schedules can share a cron; a failure in one is isolated from the others.
|
|
43
|
-
2. **`[triggers] crons = [...]`** in `wrangler.toml` — one deduped, sorted list across all schedules.
|
|
43
|
+
2. **`[triggers] crons = [...]`** in `wrangler.toml` — one deduped, sorted list across all schedules. With [named environments](/platform/database/d1#named-cloudflare-deployment-environments), the list is emitted per target as `[env.<name>.triggers]` instead. The top level is an inert placeholder there and carries no `[triggers]`.
|
|
44
44
|
3. **`src/lib/schedules.ts`** — the generated runner. Regenerated on every `quickback build`, so there's nothing to hand-maintain.
|
|
45
45
|
|
|
46
46
|
## Execute context
|
|
@@ -381,7 +381,7 @@ export default defineAction({
|
|
|
381
381
|
|
|
382
382
|
| Method | Returns | Use |
|
|
383
383
|
|--------|---------|-----|
|
|
384
|
-
| `signPutUrl(key, { contentLength, contentType?, expiresIn? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 — size (and type) are signed and checked against `maxFileSize` / `allowedTypes` |
|
|
384
|
+
| `signPutUrl(key, { contentLength, contentType?, expiresIn?, ifMatch?, customMetadata? })` | `{ url, method, headers, key, expiresAt }` | Client uploads directly to R2 — size (and type) are signed and checked against `maxFileSize` / `allowedTypes` |
|
|
385
385
|
| `signGetUrl(key, { expiresIn?, downloadFilename? })` | `string` | Client downloads directly from R2 |
|
|
386
386
|
|
|
387
387
|
This is the supported replacement for streaming a raw binary body through an
|
|
@@ -600,3 +600,12 @@ Both paths answer `413` with the actual and permitted byte counts.
|
|
|
600
600
|
([Response headers](#response-headers)).
|
|
601
601
|
- **Soft deletes**: Files are marked deleted in metadata but retained in R2
|
|
602
602
|
- **Tenant isolation**: All files are prefixed with organization ID
|
|
603
|
+
|
|
604
|
+
|
|
605
|
+
For conditional native uploads, `signPutUrl` also accepts `ifMatch` (one strong
|
|
606
|
+
quoted ETag) and bounded `customMetadata`. Both become signed required PUT
|
|
607
|
+
headers, returned in `upload.headers`; clients must replay that map. R2 checks
|
|
608
|
+
`If-Match` atomically when committing the object. The application owns the
|
|
609
|
+
placeholder/key lifecycle. See [conditional uploads and owned metadata](/platform/storage/using-r2#conditional-uploads-and-owned-metadata)
|
|
610
|
+
for validation limits and the lease boundary. Existing calls and managed
|
|
611
|
+
storage routes retain their behavior when the options are omitted.
|
|
@@ -234,7 +234,7 @@ const upload = await storage.signPutUrl(`exports/${ctx.activeOrgId}/${crypto.ran
|
|
|
234
234
|
});
|
|
235
235
|
```
|
|
236
236
|
|
|
237
|
-
`storage.signPutUrl(key, { contentLength, contentType?, expiresIn?, bucket? })`
|
|
237
|
+
`storage.signPutUrl(key, { contentLength, contentType?, expiresIn?, bucket?, ifMatch?, customMetadata? })`
|
|
238
238
|
returns `{ url, method, headers, key, expiresAt }`;
|
|
239
239
|
`storage.signGetUrl(key, { expiresIn?, downloadFilename?, bucket? })` returns a
|
|
240
240
|
presigned GET URL. Pass `bucket` to target a bucket other than the configured
|
|
@@ -250,6 +250,47 @@ PUT that does not replay the returned `headers` verbatim is rejected by R2. A
|
|
|
250
250
|
project that declares neither limit gets no ceiling and no allowlist — the
|
|
251
251
|
signature is still size-bound.
|
|
252
252
|
|
|
253
|
+
#### Conditional uploads and owned metadata
|
|
254
|
+
|
|
255
|
+
Pass `ifMatch` to bind the PUT to one existing object ETag, and
|
|
256
|
+
`customMetadata` to sign application-owned metadata alongside the upload:
|
|
257
|
+
|
|
258
|
+
```ts no-compile
|
|
259
|
+
const upload = await storage.signPutUrl(key, {
|
|
260
|
+
contentLength: input.size,
|
|
261
|
+
contentType: input.contentType,
|
|
262
|
+
ifMatch: placeholder.httpEtag, // single strong quoted ETag
|
|
263
|
+
customMetadata: { "tenant-id": verifiedTenantId, "upload-lease": leaseId },
|
|
264
|
+
});
|
|
265
|
+
// The native client must replay upload.headers on its PUT, including If-Match
|
|
266
|
+
// and every x-amz-meta-* header; do not reconstruct this header map.
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
R2 evaluates the condition atomically against committed state when the PUT
|
|
270
|
+
commits. A missing or different current ETag refuses the write, including when
|
|
271
|
+
a placeholder was deleted before a delayed upload commits. The application
|
|
272
|
+
owns the placeholder, key and lease protocol: do not recreate that key with
|
|
273
|
+
the same ETag while an older signed upload can still arrive. The signer does
|
|
274
|
+
not create a placeholder or infer tenant ownership from a client-supplied key.
|
|
275
|
+
See [R2 conditional operations](https://developers.cloudflare.com/r2/api/s3/api/)
|
|
276
|
+
and [S3 conditional writes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html).
|
|
277
|
+
|
|
278
|
+
`ifMatch` accepts one strong quoted ETag of at most 256 printable ASCII
|
|
279
|
+
characters; wildcard, weak tags, lists and control characters are rejected.
|
|
280
|
+
Metadata accepts at most 16 own data properties on a plain record (a null
|
|
281
|
+
prototype is also allowed). Keys must match `[a-z0-9][a-z0-9_-]{0,63}`; values
|
|
282
|
+
must be printable ASCII strings of at most 256 characters without surrounding
|
|
283
|
+
whitespace. Combined metadata header-name and value bytes must not exceed
|
|
284
|
+
2048. Invalid input refuses before signing. Keys stay lowercase; values are
|
|
285
|
+
returned unchanged in the required `x-amz-meta-*` headers.
|
|
286
|
+
|
|
287
|
+
The generated `SignUploadOptions` type exposes both optional fields. They
|
|
288
|
+
are signed with `allHeaders: true` and returned in `upload.headers`; deleting
|
|
289
|
+
or altering them invalidates the signature. Browser clients also need a bucket
|
|
290
|
+
CORS policy permitting `If-Match` and the metadata headers. Omitting these
|
|
291
|
+
options preserves the existing PUT result and signing behavior. Managed
|
|
292
|
+
storage endpoints do not opt into a lease protocol automatically.
|
|
293
|
+
|
|
253
294
|
Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
|
|
254
295
|
and `R2_SECRET_ACCESS_KEY` secrets. A [browser deploy](/start/deploy-browser)
|
|
255
296
|
refuses the project until those exist; it cannot mint them. Create the token in
|