@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.
Files changed (232) hide show
  1. package/dist/commands/build.d.ts.map +1 -1
  2. package/dist/commands/build.js +10 -1
  3. package/dist/commands/build.js.map +1 -1
  4. package/dist/commands/deploy.d.ts.map +1 -1
  5. package/dist/commands/deploy.js +7 -1
  6. package/dist/commands/deploy.js.map +1 -1
  7. package/dist/commands/mcp.d.ts.map +1 -1
  8. package/dist/commands/mcp.js +6 -5
  9. package/dist/commands/mcp.js.map +1 -1
  10. package/dist/index.js +1 -1
  11. package/dist/index.js.map +1 -1
  12. package/dist/lib/access-manifest-diff.d.ts +6 -0
  13. package/dist/lib/access-manifest-diff.d.ts.map +1 -1
  14. package/dist/lib/access-manifest-diff.js +10 -0
  15. package/dist/lib/access-manifest-diff.js.map +1 -1
  16. package/dist/lib/action-harvest.d.ts.map +1 -1
  17. package/dist/lib/action-harvest.js +36 -0
  18. package/dist/lib/action-harvest.js.map +1 -1
  19. package/dist/lib/api-client.d.ts +8 -0
  20. package/dist/lib/api-client.d.ts.map +1 -1
  21. package/dist/lib/api-client.js.map +1 -1
  22. package/dist/lib/deployment-target.d.ts +13 -0
  23. package/dist/lib/deployment-target.d.ts.map +1 -1
  24. package/dist/lib/deployment-target.js +4 -0
  25. package/dist/lib/deployment-target.js.map +1 -1
  26. package/dist/lib/file-loader.d.ts +22 -0
  27. package/dist/lib/file-loader.d.ts.map +1 -1
  28. package/dist/lib/file-loader.js +80 -18
  29. package/dist/lib/file-loader.js.map +1 -1
  30. package/dist/lib/file-writer.js +9 -0
  31. package/dist/lib/file-writer.js.map +1 -1
  32. package/dist/lib/harness.d.ts +10 -0
  33. package/dist/lib/harness.d.ts.map +1 -1
  34. package/dist/lib/harness.js +31 -0
  35. package/dist/lib/harness.js.map +1 -1
  36. package/dist/lib/migrations/executor.js +5 -1
  37. package/dist/lib/migrations/executor.js.map +1 -1
  38. package/dist/lib/migrations/plan.js +3 -0
  39. package/dist/lib/migrations/plan.js.map +1 -1
  40. package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
  41. package/dist/lib/migrations/postprocessors/index.js +23 -2
  42. package/dist/lib/migrations/postprocessors/index.js.map +1 -1
  43. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
  44. package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
  45. package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
  46. package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
  47. package/dist/lib/migrations/prior-state.d.ts +13 -1
  48. package/dist/lib/migrations/prior-state.d.ts.map +1 -1
  49. package/dist/lib/migrations/prior-state.js +33 -2
  50. package/dist/lib/migrations/prior-state.js.map +1 -1
  51. package/dist/lib/migrations/types.d.ts +2 -2
  52. package/dist/lib/migrations/types.d.ts.map +1 -1
  53. package/dist/lib/migrations/types.js +3 -0
  54. package/dist/lib/migrations/types.js.map +1 -1
  55. package/dist/lib/wrangler-resources.d.ts +14 -1
  56. package/dist/lib/wrangler-resources.d.ts.map +1 -1
  57. package/dist/lib/wrangler-resources.js +29 -7
  58. package/dist/lib/wrangler-resources.js.map +1 -1
  59. package/dist/skill/SKILL.md +64 -0
  60. package/dist/skill/docs/api/actions.md +73 -2
  61. package/dist/skill/docs/api/batch-operations.md +2 -0
  62. package/dist/skill/docs/api/caching.md +2 -2
  63. package/dist/skill/docs/api/crud.md +13 -0
  64. package/dist/skill/docs/api/errors.md +111 -10
  65. package/dist/skill/docs/api/index.md +24 -0
  66. package/dist/skill/docs/api/openapi.md +8 -0
  67. package/dist/skill/docs/api/query-params.md +6 -0
  68. package/dist/skill/docs/configure/agents.md +73 -1
  69. package/dist/skill/docs/configure/auth.md +7 -1
  70. package/dist/skill/docs/configure/bindings.md +55 -0
  71. package/dist/skill/docs/configure/cloudflare-access.md +191 -0
  72. package/dist/skill/docs/configure/domains.md +1 -1
  73. package/dist/skill/docs/configure/index.md +4 -2
  74. package/dist/skill/docs/configure/providers.md +2 -1
  75. package/dist/skill/docs/configure/tenancy.md +3 -0
  76. package/dist/skill/docs/configure/tenant-databases.md +2407 -0
  77. package/dist/skill/docs/define/access.md +33 -1
  78. package/dist/skill/docs/define/actions/defining.md +118 -1
  79. package/dist/skill/docs/define/actions/scoped-db.md +32 -8
  80. package/dist/skill/docs/define/areas.md +145 -2
  81. package/dist/skill/docs/define/diagnostics.md +160 -21
  82. package/dist/skill/docs/define/encryption.md +13 -2
  83. package/dist/skill/docs/define/fga.md +320 -42
  84. package/dist/skill/docs/define/firewall.md +4 -0
  85. package/dist/skill/docs/define/index.md +1 -0
  86. package/dist/skill/docs/define/read.md +46 -5
  87. package/dist/skill/docs/define/relationships.md +30 -12
  88. package/dist/skill/docs/define/schema.md +2 -0
  89. package/dist/skill/docs/define/scopes.md +393 -9
  90. package/dist/skill/docs/define/sealed-protocol.md +67 -12
  91. package/dist/skill/docs/define/transitions.md +4 -1
  92. package/dist/skill/docs/define/triggers.md +55 -1
  93. package/dist/skill/docs/platform/api-contract/index.md +9 -3
  94. package/dist/skill/docs/platform/auth/jwt-optimization.md +13 -1
  95. package/dist/skill/docs/platform/auth/using-auth.md +1 -1
  96. package/dist/skill/docs/platform/database/d1.md +112 -3
  97. package/dist/skill/docs/platform/database/data-migrations.md +3 -1
  98. package/dist/skill/docs/platform/database/neon.md +10 -2
  99. package/dist/skill/docs/platform/queues/handlers.md +48 -16
  100. package/dist/skill/docs/platform/queues/using-queues.md +16 -0
  101. package/dist/skill/docs/platform/realtime/durable-objects.md +294 -17
  102. package/dist/skill/docs/platform/realtime/index.md +9 -6
  103. package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
  104. package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
  105. package/dist/skill/docs/platform/schedules/index.md +1 -1
  106. package/dist/skill/docs/platform/storage/r2.md +10 -1
  107. package/dist/skill/docs/platform/storage/using-r2.md +42 -1
  108. package/dist/skill/docs/tooling/output.md +9 -2
  109. package/dist/skill/docs/ui/account/features/admin.md +5 -3
  110. package/dist/skill/docs/ui/account/hooks.md +9 -2
  111. package/dist/skill/docs/ui/admin/connecting.md +3 -3
  112. package/dist/skill/docs/ui/admin/index.md +1 -1
  113. package/package.json +1 -1
  114. package/src/skill/SKILL.md +64 -0
  115. package/src/skill/docs/api/actions.md +73 -2
  116. package/src/skill/docs/api/batch-operations.md +2 -0
  117. package/src/skill/docs/api/caching.md +2 -2
  118. package/src/skill/docs/api/crud.md +13 -0
  119. package/src/skill/docs/api/errors.md +111 -10
  120. package/src/skill/docs/api/index.md +24 -0
  121. package/src/skill/docs/api/openapi.md +8 -0
  122. package/src/skill/docs/api/query-params.md +6 -0
  123. package/src/skill/docs/configure/agents.md +73 -1
  124. package/src/skill/docs/configure/auth.md +7 -1
  125. package/src/skill/docs/configure/bindings.md +55 -0
  126. package/src/skill/docs/configure/cloudflare-access.md +191 -0
  127. package/src/skill/docs/configure/domains.md +1 -1
  128. package/src/skill/docs/configure/index.md +4 -2
  129. package/src/skill/docs/configure/providers.md +2 -1
  130. package/src/skill/docs/configure/tenancy.md +3 -0
  131. package/src/skill/docs/configure/tenant-databases.md +2407 -0
  132. package/src/skill/docs/define/access.md +33 -1
  133. package/src/skill/docs/define/actions/defining.md +118 -1
  134. package/src/skill/docs/define/actions/scoped-db.md +32 -8
  135. package/src/skill/docs/define/areas.md +145 -2
  136. package/src/skill/docs/define/diagnostics.md +160 -21
  137. package/src/skill/docs/define/encryption.md +13 -2
  138. package/src/skill/docs/define/fga.md +320 -42
  139. package/src/skill/docs/define/firewall.md +4 -0
  140. package/src/skill/docs/define/index.md +1 -0
  141. package/src/skill/docs/define/read.md +46 -5
  142. package/src/skill/docs/define/relationships.md +30 -12
  143. package/src/skill/docs/define/schema.md +2 -0
  144. package/src/skill/docs/define/scopes.md +393 -9
  145. package/src/skill/docs/define/sealed-protocol.md +67 -12
  146. package/src/skill/docs/define/transitions.md +4 -1
  147. package/src/skill/docs/define/triggers.md +55 -1
  148. package/src/skill/docs/platform/api-contract/index.md +9 -3
  149. package/src/skill/docs/platform/auth/jwt-optimization.md +13 -1
  150. package/src/skill/docs/platform/auth/using-auth.md +1 -1
  151. package/src/skill/docs/platform/database/d1.md +112 -3
  152. package/src/skill/docs/platform/database/data-migrations.md +3 -1
  153. package/src/skill/docs/platform/database/neon.md +10 -2
  154. package/src/skill/docs/platform/queues/handlers.md +48 -16
  155. package/src/skill/docs/platform/queues/using-queues.md +16 -0
  156. package/src/skill/docs/platform/realtime/durable-objects.md +294 -17
  157. package/src/skill/docs/platform/realtime/index.md +9 -6
  158. package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
  159. package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
  160. package/src/skill/docs/platform/schedules/index.md +1 -1
  161. package/src/skill/docs/platform/storage/r2.md +10 -1
  162. package/src/skill/docs/platform/storage/using-r2.md +42 -1
  163. package/src/skill/docs/tooling/output.md +9 -2
  164. package/src/skill/docs/ui/account/features/admin.md +5 -3
  165. package/src/skill/docs/ui/account/hooks.md +9 -2
  166. package/src/skill/docs/ui/admin/connecting.md +3 -3
  167. package/src/skill/docs/ui/admin/index.md +1 -1
  168. package/dist/codex/AGENTS.md +0 -290
  169. package/dist/commands/build.test.d.ts.map +0 -1
  170. package/dist/commands/codex.d.ts +0 -16
  171. package/dist/commands/codex.d.ts.map +0 -1
  172. package/dist/commands/codex.js +0 -159
  173. package/dist/commands/codex.js.map +0 -1
  174. package/dist/commands/compile.d.ts +0 -62
  175. package/dist/commands/compile.d.ts.map +0 -1
  176. package/dist/commands/compile.js +0 -830
  177. package/dist/commands/compile.js.map +0 -1
  178. package/dist/commands/compile.test.d.ts.map +0 -1
  179. package/dist/commands/init.d.ts +0 -6
  180. package/dist/commands/init.d.ts.map +0 -1
  181. package/dist/commands/init.js +0 -405
  182. package/dist/commands/init.js.map +0 -1
  183. package/dist/commands/migrate.test.d.ts.map +0 -1
  184. package/dist/commands/migrations.test.d.ts.map +0 -1
  185. package/dist/commands/push.test.d.ts.map +0 -1
  186. package/dist/commands/schema.test.d.ts.map +0 -1
  187. package/dist/docs/content.d.ts +0 -7
  188. package/dist/docs/content.d.ts.map +0 -1
  189. package/dist/docs/content.js +0 -672
  190. package/dist/docs/content.js.map +0 -1
  191. package/dist/docs/index.test.d.ts.map +0 -1
  192. package/dist/lib/action-harvest.test.d.ts.map +0 -1
  193. package/dist/lib/api-client.test.d.ts.map +0 -1
  194. package/dist/lib/artifact-routing.test.d.ts.map +0 -1
  195. package/dist/lib/auth.test.d.ts.map +0 -1
  196. package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
  197. package/dist/lib/compiler-floor.test.d.ts.map +0 -1
  198. package/dist/lib/config-id-splice.test.d.ts.map +0 -1
  199. package/dist/lib/config-sync.test.d.ts.map +0 -1
  200. package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
  201. package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
  202. package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
  203. package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
  204. package/dist/lib/file-loader.test.d.ts.map +0 -1
  205. package/dist/lib/file-writer.test.d.ts.map +0 -1
  206. package/dist/lib/helpers.d.ts +0 -39
  207. package/dist/lib/helpers.d.ts.map +0 -1
  208. package/dist/lib/helpers.js +0 -299
  209. package/dist/lib/helpers.js.map +0 -1
  210. package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
  211. package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
  212. package/dist/lib/migrations/executor.test.d.ts.map +0 -1
  213. package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
  214. package/dist/lib/migrations/lock.test.d.ts.map +0 -1
  215. package/dist/lib/migrations/paths.test.d.ts.map +0 -1
  216. package/dist/lib/migrations/plan.test.d.ts.map +0 -1
  217. package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
  218. package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
  219. package/dist/lib/migrations/staging.test.d.ts.map +0 -1
  220. package/dist/lib/neon-canary.test.d.ts.map +0 -1
  221. package/dist/lib/neon-target.test.d.ts.map +0 -1
  222. package/dist/lib/neon.test.d.ts.map +0 -1
  223. package/dist/lib/prepare-output.test.d.ts.map +0 -1
  224. package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
  225. package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
  226. package/dist/lib/shell.test.d.ts.map +0 -1
  227. package/dist/lib/sweep-stale.d.ts +0 -25
  228. package/dist/lib/sweep-stale.d.ts.map +0 -1
  229. package/dist/lib/sweep-stale.js +0 -179
  230. package/dist/lib/sweep-stale.js.map +0 -1
  231. package/dist/lib/sweep-stale.test.d.ts.map +0 -1
  232. 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 role |
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. A `type: 'custom'` 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 connections. If
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>` — every Better Auth caller
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, or a Better Auth caller
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 (even pings) are enforced the same way.
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 churn. One
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
- - Masking is pre-computed per-role (O(roles) not O(subscribers))
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 = "v1"
624
- new_classes = ["Broadcaster"]
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 verifies the ticket cryptographically at upgrade and attaches the socket to the ticket's `scopeKey`, `organizationId`, or `userId`.
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 concrete
79
- // membership/scope roles or UPPERCASE pseudo-roles.
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, standalone actions, or
227
- cross-feature targets, declare an action-level `emit:` to get a pre-bound
228
- `emitCrud(row, oldRow?)` helper. Full details and the capture caveats live in
229
- the [realtime docs](/platform/realtime/durable-objects).
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. The audience is evaluated at fanout with the same uppercase pseudo-role semantics as REST (`PUBLIC` = everyone in the room, `AUTHENTICATED`, `USER`, `SYSADMIN`), plus concrete membership/scope 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 and to [live view](/platform/realtime/live-views) `view_changes` deltas alike.
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
- Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency. A `type: 'custom'` mask function can't run inside the Broadcaster — those columns broadcast as `[REDACTED]` (fail closed).
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