@quickback-dev/cli 0.72.9 → 0.72.10
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 +8 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/db-explain.d.ts +67 -0
- package/dist/commands/db-explain.d.ts.map +1 -0
- package/dist/commands/db-explain.js +141 -0
- package/dist/commands/db-explain.js.map +1 -0
- package/dist/commands/db-export.d.ts +34 -0
- package/dist/commands/db-export.d.ts.map +1 -0
- package/dist/commands/db-export.js +250 -0
- package/dist/commands/db-export.js.map +1 -0
- package/dist/commands/db-insights.d.ts +60 -0
- package/dist/commands/db-insights.d.ts.map +1 -0
- package/dist/commands/db-insights.js +106 -0
- package/dist/commands/db-insights.js.map +1 -0
- package/dist/commands/db-recovery.d.ts +98 -0
- package/dist/commands/db-recovery.d.ts.map +1 -0
- package/dist/commands/db-recovery.js +558 -0
- package/dist/commands/db-recovery.js.map +1 -0
- package/dist/commands/db-target.d.ts +27 -0
- package/dist/commands/db-target.d.ts.map +1 -0
- package/dist/commands/db-target.js +83 -0
- package/dist/commands/db-target.js.map +1 -0
- package/dist/commands/db.d.ts +3 -0
- package/dist/commands/db.d.ts.map +1 -0
- package/dist/commands/db.js +43 -0
- package/dist/commands/db.js.map +1 -0
- package/dist/commands/effects.d.ts +8 -0
- package/dist/commands/effects.d.ts.map +1 -0
- package/dist/commands/effects.js +48 -0
- package/dist/commands/effects.js.map +1 -0
- package/dist/commands/platform-budget.d.ts +143 -0
- package/dist/commands/platform-budget.d.ts.map +1 -0
- package/dist/commands/platform-budget.js +619 -0
- package/dist/commands/platform-budget.js.map +1 -0
- package/dist/commands/preview.d.ts +57 -0
- package/dist/commands/preview.d.ts.map +1 -0
- package/dist/commands/preview.js +268 -0
- package/dist/commands/preview.js.map +1 -0
- package/dist/commands/search.d.ts +20 -0
- package/dist/commands/search.d.ts.map +1 -0
- package/dist/commands/search.js +133 -0
- package/dist/commands/search.js.map +1 -0
- package/dist/index.js +35 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +4 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
- package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
- package/dist/lib/cloudflare-spend-policies.js +289 -0
- package/dist/lib/cloudflare-spend-policies.js.map +1 -0
- package/dist/lib/compiler-stubs.d.ts +2 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +2 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/d1-fingerprint.d.ts +8 -0
- package/dist/lib/d1-fingerprint.d.ts.map +1 -0
- package/dist/lib/d1-fingerprint.js +113 -0
- package/dist/lib/d1-fingerprint.js.map +1 -0
- package/dist/lib/file-loader.d.ts +12 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +27 -1
- package/dist/lib/file-loader.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 +6 -5
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +24 -12
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
- package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/search.js +160 -0
- package/dist/lib/migrations/postprocessors/search.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +7 -0
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +3 -0
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +1 -1
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +1 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/preview-lifecycle.d.ts +139 -0
- package/dist/lib/preview-lifecycle.d.ts.map +1 -0
- package/dist/lib/preview-lifecycle.js +429 -0
- package/dist/lib/preview-lifecycle.js.map +1 -0
- package/dist/lib/preview.d.ts +146 -0
- package/dist/lib/preview.d.ts.map +1 -0
- package/dist/lib/preview.js +417 -0
- package/dist/lib/preview.js.map +1 -0
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +4 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/SKILL.md +9 -3
- package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/dist/skill/docs/api/batch-operations.md +19 -0
- package/dist/skill/docs/api/caching.md +17 -0
- package/dist/skill/docs/api/crud.md +9 -0
- package/dist/skill/docs/api/errors.md +31 -2
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/changelog/index.md +1 -0
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/bindings.md +177 -1
- package/dist/skill/docs/configure/cloudflare-access.md +43 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/providers.md +5 -0
- package/dist/skill/docs/configure/tenant-databases.md +627 -14
- package/dist/skill/docs/define/access.md +26 -0
- package/dist/skill/docs/define/actions/defining.md +7 -1
- package/dist/skill/docs/define/actions/index.md +5 -0
- package/dist/skill/docs/define/actions/scoped-db.md +127 -1
- package/dist/skill/docs/define/authoring-basics.md +92 -0
- package/dist/skill/docs/define/changesets.md +8 -0
- package/dist/skill/docs/define/encryption.md +48 -2
- package/dist/skill/docs/define/feature.md +17 -2
- package/dist/skill/docs/define/guards.md +11 -3
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/invariants.md +321 -0
- package/dist/skill/docs/define/issue-tracker-example.md +225 -0
- package/dist/skill/docs/define/masking.md +3 -3
- package/dist/skill/docs/define/rate-limit.md +63 -22
- package/dist/skill/docs/define/read.md +332 -5
- package/dist/skill/docs/define/relationships.md +10 -0
- package/dist/skill/docs/define/schema.md +137 -10
- package/dist/skill/docs/define/scopes.md +1 -0
- package/dist/skill/docs/define/transitions.md +9 -0
- package/dist/skill/docs/define/triggers.md +127 -1
- package/dist/skill/docs/platform/api-contract/index.md +35 -4
- package/dist/skill/docs/platform/auth/api-keys.md +26 -3
- package/dist/skill/docs/platform/auth/index.md +5 -2
- package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +73 -1
- package/dist/skill/docs/platform/database/durable-effects.md +224 -0
- package/dist/skill/docs/platform/database/read-replication.md +9 -0
- package/dist/skill/docs/platform/database/recovery.md +292 -0
- package/dist/skill/docs/platform/database/using-d1.md +152 -2
- package/dist/skill/docs/platform/index.md +1 -0
- package/dist/skill/docs/platform/operations/budgets.md +224 -0
- package/dist/skill/docs/platform/queues/handlers.md +1 -0
- package/dist/skill/docs/platform/queues/index.md +18 -0
- package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
- package/dist/skill/docs/platform/storage/using-r2.md +13 -0
- package/dist/skill/docs/platform/vector/embeddings.md +28 -4
- package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/dist/skill/docs/platform/workflows/index.md +385 -0
- package/dist/skill/docs/start/deploy-browser.md +51 -0
- package/dist/skill/docs/start/deploy.md +97 -1
- package/dist/skill/docs/tooling/cli.md +117 -0
- package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/dist/skill/docs/ui/account/customization.md +4 -0
- package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
- package/package.json +1 -1
- package/src/skill/SKILL.md +9 -3
- package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/src/skill/docs/api/batch-operations.md +19 -0
- package/src/skill/docs/api/caching.md +17 -0
- package/src/skill/docs/api/crud.md +9 -0
- package/src/skill/docs/api/errors.md +31 -2
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/changelog/index.md +1 -0
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/bindings.md +177 -1
- package/src/skill/docs/configure/cloudflare-access.md +43 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/providers.md +5 -0
- package/src/skill/docs/configure/tenant-databases.md +627 -14
- package/src/skill/docs/define/access.md +26 -0
- package/src/skill/docs/define/actions/defining.md +7 -1
- package/src/skill/docs/define/actions/index.md +5 -0
- package/src/skill/docs/define/actions/scoped-db.md +127 -1
- package/src/skill/docs/define/authoring-basics.md +92 -0
- package/src/skill/docs/define/changesets.md +8 -0
- package/src/skill/docs/define/encryption.md +48 -2
- package/src/skill/docs/define/feature.md +17 -2
- package/src/skill/docs/define/guards.md +11 -3
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/invariants.md +321 -0
- package/src/skill/docs/define/issue-tracker-example.md +225 -0
- package/src/skill/docs/define/masking.md +3 -3
- package/src/skill/docs/define/rate-limit.md +63 -22
- package/src/skill/docs/define/read.md +332 -5
- package/src/skill/docs/define/relationships.md +10 -0
- package/src/skill/docs/define/schema.md +137 -10
- package/src/skill/docs/define/scopes.md +1 -0
- package/src/skill/docs/define/transitions.md +9 -0
- package/src/skill/docs/define/triggers.md +127 -1
- package/src/skill/docs/platform/api-contract/index.md +35 -4
- package/src/skill/docs/platform/auth/api-keys.md +26 -3
- package/src/skill/docs/platform/auth/index.md +5 -2
- package/src/skill/docs/platform/auth/plugins/index.md +1 -1
- package/src/skill/docs/platform/database/d1.md +73 -1
- package/src/skill/docs/platform/database/durable-effects.md +224 -0
- package/src/skill/docs/platform/database/read-replication.md +9 -0
- package/src/skill/docs/platform/database/recovery.md +292 -0
- package/src/skill/docs/platform/database/using-d1.md +152 -2
- package/src/skill/docs/platform/index.md +1 -0
- package/src/skill/docs/platform/operations/budgets.md +224 -0
- package/src/skill/docs/platform/queues/handlers.md +1 -0
- package/src/skill/docs/platform/queues/index.md +18 -0
- package/src/skill/docs/platform/realtime/table-changes.md +1 -0
- package/src/skill/docs/platform/storage/using-r2.md +13 -0
- package/src/skill/docs/platform/vector/embeddings.md +28 -4
- package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/src/skill/docs/platform/workflows/index.md +385 -0
- package/src/skill/docs/start/deploy-browser.md +51 -0
- package/src/skill/docs/start/deploy.md +97 -1
- package/src/skill/docs/tooling/cli.md +117 -0
- package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/src/skill/docs/ui/account/customization.md +4 -0
- package/src/skill/docs/ui/admin/record-layouts.md +3 -3
|
@@ -69,6 +69,16 @@ still reads and writes the table.
|
|
|
69
69
|
The tenant Worker declares its class with `exports` (no `[[migrations]]`) and
|
|
70
70
|
carries no binding to itself. The edge binds it with `script_name = "<name>-tenant"`. Deploy the tenant Worker
|
|
71
71
|
first: `npm run deploy` runs `npm run deploy:tenant` before the edge deploy.
|
|
72
|
+
|
|
73
|
+
On the **first** deploy into an account neither Worker exists yet, and each
|
|
74
|
+
names the other: the tenant Worker's `__QB_EDGE_OUTBOX` service binding needs
|
|
75
|
+
the edge, and the edge's `TENANT` binding needs the tenant script, so
|
|
76
|
+
`npm run deploy` fails with `Service binding '__QB_EDGE_OUTBOX' references
|
|
77
|
+
Worker '<name>' which was not found [code: 10143]`. Run `npm run deploy:first`
|
|
78
|
+
once instead: it deploys `wrangler.tenant.first.jsonc` (the tenant Worker
|
|
79
|
+
without the outbox binding), then the edge, then `wrangler.tenant.jsonc`. A project with named `environments` gets no `deploy:first` yet:
|
|
80
|
+
for each environment's first deploy, deploy the tenant Worker once with its
|
|
81
|
+
`__QB_EDGE_OUTBOX` service removed, then the edge, then the full tenant config.
|
|
72
82
|
When `providers.runtime.config.accountId` is set, the tenant Worker carries the
|
|
73
83
|
same `account_id` as the edge, so it cannot deploy into a different account.
|
|
74
84
|
|
|
@@ -129,6 +139,9 @@ All targets run the same bundle. The build emits:
|
|
|
129
139
|
target carries `main`, `exports`, that target's `account_id` (its `accountId`, or
|
|
130
140
|
`providers.runtime.config.accountId`), its `TENANT_BACKUPS` bucket
|
|
131
141
|
(`backupBucketName`), and the rate-limit namespaces from its own edge stanza.
|
|
142
|
+
`tenantWorker.durableObjects` overrides the tenant Worker's
|
|
143
|
+
[Durable Object policy](/configure/bindings#durable-object-code-updates-and-retries)
|
|
144
|
+
for that target, independently of the edge Worker's.
|
|
132
145
|
- **`package.json`**: `deploy:<key>:tenant`. Each `deploy:<key>` runs it
|
|
133
146
|
before the edge deploy. `dev:tenant` runs the `dev` target. There is no bare
|
|
134
147
|
`deploy:tenant`.
|
|
@@ -164,7 +177,7 @@ may relax it later.
|
|
|
164
177
|
The edge↔tenant contract is versioned (`TENANT_RPC_VERSION` in
|
|
165
178
|
`src/tenant/contract.ts`, the same constant in both Workers). A tenant Worker
|
|
166
179
|
answers versions from `TENANT_RPC_MIN_VERSION` up to its own and returns
|
|
167
|
-
`503 TENANT_RPC_VERSION_MISMATCH` otherwise. The current protocol is version
|
|
180
|
+
`503 TENANT_RPC_VERSION_MISMATCH` otherwise. The current protocol is version 16
|
|
168
181
|
(version 3 put dump restore under the shared restore fence and added the
|
|
169
182
|
authorization epoch; version 4 adds tenant commands and epoch-carrying restore
|
|
170
183
|
permits; version 5 adds `callJob()` for [result jobs](#result-jobs); version 6
|
|
@@ -173,7 +186,14 @@ the bounded backup read; version 8 the `callJob` epoch fence; version 9 the
|
|
|
173
186
|
backup-fenced purge; version 10 room commit permits; version 11
|
|
174
187
|
[leased outbox delivery](#outbox-delivery); version 12 `revoke` outbox entries
|
|
175
188
|
for [scope revocation](#scope-revocation); version 13 `armSchedules()` for
|
|
176
|
-
[tenant schedules](#tenant-schedules)
|
|
189
|
+
[tenant schedules](#tenant-schedules); version 14 `scheduleControl()`; version 15
|
|
190
|
+
[durable `Idempotency-Key` receipts](#atomic-batches); version 16
|
|
191
|
+
[partition-placed jobs](#partition-jobs)). Deploy the tenant Worker
|
|
192
|
+
before the edge: a version-15 edge carries its idempotency claim on every
|
|
193
|
+
write, and an older tenant Worker answers it `503 TENANT_RPC_VERSION_MISMATCH`
|
|
194
|
+
rather than ignore the claim. A version-15 tenant Worker still serves older
|
|
195
|
+
edges; their requests carry no claim and get the edge's replay cache only.
|
|
196
|
+
An edge below version 11 gets no
|
|
177
197
|
inline claims and keeps using `takeOutbox` / `ackOutbox`. An edge below
|
|
178
198
|
version 12 is never handed a `revoke` entry, by a claim or by `takeOutbox`:
|
|
179
199
|
those entries wait for the new edge, so no revocation is settled unapplied. It still
|
|
@@ -235,7 +255,9 @@ the object only when the registry vouches for it:
|
|
|
235
255
|
A tenant gets its row when it first serves a request or a job, or when an
|
|
236
256
|
operator provisions it (`POST /tenants/:id/provision`, `provisionTenantTarget`
|
|
237
257
|
in `src/lib/tenants.ts`: verified against Better Auth's organization table
|
|
238
|
-
first
|
|
258
|
+
first — `organization`, or `organizations` with the database's
|
|
259
|
+
`usePlurals: true`, like every generated import of a Better Auth table in both
|
|
260
|
+
Workers). Until one of those, a new organization's commands answer
|
|
239
261
|
`TENANT_NOT_PROVISIONED`. `denied` is kept for definitive refusals made by a command.
|
|
240
262
|
Pass only a server-verified organization id, never one taken from the request.
|
|
241
263
|
The HTTP forwarder (`tenantForward`) does not read the registry: it routes the
|
|
@@ -636,6 +658,19 @@ forwarder at the prefix. The tenant Worker mounts the namespace's gate file
|
|
|
636
658
|
namespace claims. A tenant feature's action under the prefix may sit outside
|
|
637
659
|
its feature's own path (`TENANCY_ROOT_ACTION` doesn't apply to it).
|
|
638
660
|
|
|
661
|
+
#### Actions at a table route
|
|
662
|
+
|
|
663
|
+
A tenant feature's standalone action may also sit under one of its own tables'
|
|
664
|
+
routes, outside the feature's path. The usual case is a
|
|
665
|
+
[mapped create](/define/actions#replace-a-crud-verb): `create: { action }` on
|
|
666
|
+
`clientInvoiceLines` makes the action occupy `POST /client-invoice-lines`,
|
|
667
|
+
while the feature's path is `/client-invoices`. The edge forwards that path to
|
|
668
|
+
the organization's object, and the tenant Worker mounts the feature's
|
|
669
|
+
root-actions router (`<feature>-root-actions.routes.ts`), so the action runs in
|
|
670
|
+
the object with the same gates as on a shared edge. A path under no table
|
|
671
|
+
route of the feature, and any root path on a
|
|
672
|
+
[partitioned](#partitions) feature, is still `TENANCY_ROOT_ACTION`.
|
|
673
|
+
|
|
639
674
|
The edge routes a namespace request by the prefix's first `:param`, through
|
|
640
675
|
the tenant-backed kind whose `requestField` it is:
|
|
641
676
|
|
|
@@ -857,6 +892,89 @@ access and its `guards` must be declarative: a function there fails the build
|
|
|
857
892
|
(`TENANCY_BATCH_ASYNC`), because it could await other I/O and let another
|
|
858
893
|
request's writes interleave into the transaction.
|
|
859
894
|
|
|
895
|
+
### Atomic batches
|
|
896
|
+
|
|
897
|
+
`db.batch([...], { revision, preconditions, postconditions })` in tenant code
|
|
898
|
+
runs in one `ctx.storage.transaction()`: the same
|
|
899
|
+
[native D1 contract](/api/actions), served by the object. `db.revision()`
|
|
900
|
+
reads the object's change counter (see
|
|
901
|
+
[Change signals](#change-signals-sequences-and-changesets)); revision guards,
|
|
902
|
+
pre- and postconditions and firewall gates are checked against
|
|
903
|
+
`_quickback_batch_assertions`, which every tenant object carries. Prepared
|
|
904
|
+
(`prepare: true`) before hooks on tenant tables run from the tenant trigger
|
|
905
|
+
registry, with their reads revision-guarded at commit. A SQL constraint
|
|
906
|
+
inside the transaction is a definitive rollback: `409 DB_BATCH_ROLLED_BACK`,
|
|
907
|
+
`committed: false`. A `QB_TRIGGER_REJECTED` trigger or an
|
|
908
|
+
[invariant](/define/invariants) rolls it back the same way and answers
|
|
909
|
+
`422 TRIGGER_REJECTED` with its code in `details.code`.
|
|
910
|
+
|
|
911
|
+
`Idempotency-Key` on a tenant route is claimed and cached by the edge: a
|
|
912
|
+
replay returns the first response. The edge also carries its claim to the
|
|
913
|
+
object (RPC version 15), which keeps its own receipt in the object's
|
|
914
|
+
`idempotency_keys` table. An atomic `db.batch` marks the receipt started
|
|
915
|
+
before its transaction and committed inside it, so the marker and the writes
|
|
916
|
+
commit together, and the object stores the response after the handler
|
|
917
|
+
returns. If the edge dies after the tenant transaction commits and before it
|
|
918
|
+
stores the response, the retry it forwards after its 60-second reclaim gets
|
|
919
|
+
the object's stored response (`Idempotency-Replayed: true`). If the batch
|
|
920
|
+
committed but the response could not be kept (a 5xx after commit, a cookie,
|
|
921
|
+
`Cache-Control: no-store`), the retry gets `409 IDEMPOTENCY_COMMITTED` with
|
|
922
|
+
`details.committed: true`. A receipt whose batch started but never committed
|
|
923
|
+
answers `409 IDEMPOTENCY_OUTCOME_UNKNOWN`. Neither runs the write again: the
|
|
924
|
+
same outcomes as a features-D1 route. A receipt for a request that ran no
|
|
925
|
+
batch, or whose batch SQL rolled back, is dropped when the request ends; the
|
|
926
|
+
edge's replay cache covers it. Committed receipts are part of the object's
|
|
927
|
+
backups and, like D1's, do not expire.
|
|
928
|
+
|
|
929
|
+
## Change signals, sequences and changesets
|
|
930
|
+
|
|
931
|
+
[`changes`](/platform/realtime/table-changes), scoped sequences and
|
|
932
|
+
aggregate changesets (`owns`) work on tenant tables. Each runs inside the
|
|
933
|
+
organization's object.
|
|
934
|
+
|
|
935
|
+
- **`changes.counter`.** Every tenant object holds its own `qb_change_counter`
|
|
936
|
+
table, and the counter triggers on its tenant tables bump it in the write's
|
|
937
|
+
transaction. `changeCounter(db, ctx.activeOrgId)` and `db.revision()` in
|
|
938
|
+
tenant code read the object's counter. Platform tables with an
|
|
939
|
+
organization column (`placement: { platform: true, crossTenant: true }`)
|
|
940
|
+
bump the features D1's counter, which edge code reads. The counter is part
|
|
941
|
+
of the object's backups, so a restore rewinds it with the data.
|
|
942
|
+
- **`changes.broadcast`.** A write to a tenant table records one
|
|
943
|
+
`data.changed` frame per table per request in the object's
|
|
944
|
+
[outbox](#outbox-delivery), in the write's transaction, and the edge
|
|
945
|
+
replays it through the Broadcaster. The payload and audience are the same
|
|
946
|
+
as on the edge. The frame is always addressed to the object's
|
|
947
|
+
organization: never a caller's claim or a row value. A rolled-back
|
|
948
|
+
transaction or batch records no frame. Delivery is at least once, and
|
|
949
|
+
every redelivery carries the same `publishId`.
|
|
950
|
+
- **Sequences.** `_quickback_sequences` lives in every object that holds a
|
|
951
|
+
sequenced tenant table, with the same scoping, start, gap-free allocation
|
|
952
|
+
under concurrency and never-reused numbers as on D1. Each organization
|
|
953
|
+
counts from its own `start`.
|
|
954
|
+
- **Changesets (`owns`).** The changeset engine writes the root and every
|
|
955
|
+
owned child in one `ctx.storage.transaction()`: a failing op rolls back the
|
|
956
|
+
whole changeset, the response says `meta.transactional: true`, and an
|
|
957
|
+
error carries no `ops` extension. Every owned table must share its root's
|
|
958
|
+
placement — the same tenant object (or partition) — or the build fails
|
|
959
|
+
(`TENANCY_OWNS_CROSS_OBJECT`). `afterCommit` on a tenant root is not
|
|
960
|
+
supported yet (`TENANCY_UNSUPPORTED`).
|
|
961
|
+
|
|
962
|
+
## Record invariants
|
|
963
|
+
|
|
964
|
+
[Invariants](/define/invariants) on a tenant table install in every tenant
|
|
965
|
+
object with its `sql:` triggers, and every table a rule names must be in the
|
|
966
|
+
same object (`TENANCY_TRIGGER_CROSS_OBJECT`). A `permanent`, `frozen`,
|
|
967
|
+
`lockedBy`, `restrict` or `derived` rule, and a `.references(…, { requires })`,
|
|
968
|
+
holds for every statement in the object, whoever runs it.
|
|
969
|
+
|
|
970
|
+
`balanced` is checked when a **write unit** commits. In a tenant object the
|
|
971
|
+
unit is the transaction: `db.transaction(cb)`, an atomic `db.batch`, a batch
|
|
972
|
+
route, a changeset, a command, or one statement run outside all of them. The
|
|
973
|
+
object's storage handle runs the commit check last, inside the outermost
|
|
974
|
+
transaction, so the unit rolls back whole when its lines don't balance. Each
|
|
975
|
+
object carries its own `_quickback_unbalanced` and
|
|
976
|
+
`_quickback_invariant_check` tables, created by the tenant migrations.
|
|
977
|
+
|
|
860
978
|
## Encrypted columns
|
|
861
979
|
|
|
862
980
|
`.encrypted()` and `q.secret()` columns on tenant tables behave as on the edge:
|
|
@@ -875,6 +993,313 @@ The `ctx.unmask` reveal audit rides the object's outbox into `audit_events`,
|
|
|
875
993
|
like a tenant hard delete, when the project has the security-audit database;
|
|
876
994
|
without one it is not recorded.
|
|
877
995
|
|
|
996
|
+
Edge code with no request — a webhook, a queue consumer, the edge half of a
|
|
997
|
+
tenant job — reads a **platform** table's secret with
|
|
998
|
+
[`openSecret`](/define/encryption#opensecret--reading-a-secret-outside-a-request),
|
|
999
|
+
which writes its audit row fail-closed before opening the key. It is edge-only:
|
|
1000
|
+
the tenant Worker has no `openSecret`, and tenant tables are not openable from
|
|
1001
|
+
the edge (their rows live in the object).
|
|
1002
|
+
|
|
1003
|
+
## Managed files
|
|
1004
|
+
|
|
1005
|
+
A tenant table may declare a [`q.storageKey()`](/define/schema#qstoragekey--r2-object-keys-the-compiler-owns)
|
|
1006
|
+
column once the file bridge is on. Without it the column is refused
|
|
1007
|
+
(`TENANCY_UNSUPPORTED`).
|
|
1008
|
+
|
|
1009
|
+
```ts no-compile
|
|
1010
|
+
tenancy: {
|
|
1011
|
+
isolation: 'durable-object',
|
|
1012
|
+
bridges: { files: { enabled: true, maxGrantSeconds: 600 } },
|
|
1013
|
+
},
|
|
1014
|
+
```
|
|
1015
|
+
|
|
1016
|
+
The object owns the row. The edge Worker alone holds the R2 binding and the
|
|
1017
|
+
presign secrets (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`).
|
|
1018
|
+
The tenant Worker gets neither; the import-closure check refuses
|
|
1019
|
+
`src/lib/storage-keys.ts` and `src/lib/tenant-files.ts` in tenant code, which
|
|
1020
|
+
runs against a tenant copy (`src/tenant/storage-keys.ts`) with the same key rules.
|
|
1021
|
+
Actions keep the same API as on the edge: `db.allocateUpload`,
|
|
1022
|
+
`db.signDownload`, and `db.finalizeUpload`.
|
|
1023
|
+
|
|
1024
|
+
**Upload.** `db.allocateUpload(table, { ...values, ext, mime, size })` checks the
|
|
1025
|
+
type and size, then writes the row with its rendered key. In the same SQLite
|
|
1026
|
+
commit it records a reservation in the object's `__qb_file_ops` table and a
|
|
1027
|
+
deferred `verify` entry in the outbox. It returns `{ row, key, putUrl, headers,
|
|
1028
|
+
expiresAt, uploadId, status: 'pending' }`. The object cannot sign, so `putUrl`
|
|
1029
|
+
leaves it as a marker. The response carries the reservation as a grant (a
|
|
1030
|
+
bridge envelope in a response header). Before the response leaves, the edge:
|
|
1031
|
+
|
|
1032
|
+
1. checks that the grant names the object the edge routed to, that its table,
|
|
1033
|
+
column and key match the compiled registry and template, that its type,
|
|
1034
|
+
size and lifetime fit, and that its generation is the registry's current one
|
|
1035
|
+
(no pending restore, no purge cleanup running);
|
|
1036
|
+
2. writes the key to the platform manifest (`tenant_file_manifest`, features D1) as
|
|
1037
|
+
`pending`. A key the manifest already holds for another operation, or with
|
|
1038
|
+
different identity fields, is refused;
|
|
1039
|
+
3. signs the PUT and substitutes the marker. Any refusal replaces the whole
|
|
1040
|
+
response (`TENANT_BRIDGE_*`, `TENANT_FILE_*`, `STORAGE_UPLOAD_*`): a marker
|
|
1041
|
+
never reaches the client unsigned.
|
|
1042
|
+
|
|
1043
|
+
Bytes go from the client to R2. They never cross the object or its RPC.
|
|
1044
|
+
An older edge (below `TENANT_FILE_BRIDGE_VERSION`) is refused before any row is
|
|
1045
|
+
written (`503 STORAGE_FILE_BRIDGE_EDGE_OUTDATED`). So are jobs and alarms, which
|
|
1046
|
+
have no response for the edge to sign (`STORAGE_FILE_BRIDGE_UNAVAILABLE`).
|
|
1047
|
+
|
|
1048
|
+
**Finalize.** After the PUT, `db.finalizeUpload(table, id)` loads the row through
|
|
1049
|
+
the firewall and makes its `verify` entry claimable at once. The edge applies it
|
|
1050
|
+
from the response: it HEADs the object, and when the size and `Content-Type`
|
|
1051
|
+
match the reservation, marks the manifest row `live` and settles `ready`. The
|
|
1052
|
+
object marks the file `ready` only if the row still holds that key. Call
|
|
1053
|
+
`finalizeUpload` again to read the status: `pending`, `ready`, `deleting`,
|
|
1054
|
+
`deleted`, or `unavailable`. Without a finalize, the verify runs when the grant
|
|
1055
|
+
expires plus a five-minute grace, on the object's next drain. An object that is
|
|
1056
|
+
missing then, or one that does not match, is tombstoned and deleted
|
|
1057
|
+
(`unavailable`). An expired, replaced or rejected upload can never become ready.
|
|
1058
|
+
|
|
1059
|
+
**Reads.** `db.signDownload(table, id)` loads the row through the firewall and the
|
|
1060
|
+
table's access, then grants only a `ready` file of that row in the current
|
|
1061
|
+
generation (`409 STORAGE_FILE_NOT_READY`, `details.status` otherwise). The edge
|
|
1062
|
+
signs it only for a `live` manifest row of the same object, table and key.
|
|
1063
|
+
Organization membership alone is not row access: a member the owner arm
|
|
1064
|
+
excludes gets `404`, as for any read. A signed GET is a bounded capability. It
|
|
1065
|
+
stays valid until it expires (at most `maxGrantSeconds`, default 600) even if
|
|
1066
|
+
the row is deleted or access is revoked meanwhile. Keep `maxGrantSeconds`
|
|
1067
|
+
short, or serve the bytes through your own authenticated action.
|
|
1068
|
+
|
|
1069
|
+
**Deletes and replacement.** The generated hard `DELETE /:id` and
|
|
1070
|
+
`DELETE /batch`, and `db.delete(table)` in an action, record a `delete` intent
|
|
1071
|
+
for each erased row's key. The generated routes write it in the delete's own
|
|
1072
|
+
transaction. `allocateUpload(..., { id })` gives the row a new key and records a
|
|
1073
|
+
delete for the old one. The edge tombstones the manifest row first
|
|
1074
|
+
(irreversible), then deletes the object, then marks it `deleted`. A missing
|
|
1075
|
+
object counts as deleted. Retries repeat the same idempotent steps, and a
|
|
1076
|
+
deleted key is never signed again. The object reports a delete as `deleting`
|
|
1077
|
+
until the edge settles it. `db.transaction()` is synchronous in the object, so a
|
|
1078
|
+
storage-key delete inside one is refused (`STORAGE_KEY_TX_DELETE`): delete
|
|
1079
|
+
outside it. Raw SQL that bypasses the scoped `db` records nothing. Call
|
|
1080
|
+
`deleteStorageObjects(env, table, rows)` from `src/tenant/storage-keys` after
|
|
1081
|
+
it, as on the edge.
|
|
1082
|
+
|
|
1083
|
+
**Keys.** The stored key is the column's template rendering. The edge prefixes
|
|
1084
|
+
it with an immutable namespace the object never chooses:
|
|
1085
|
+
`qbt/<project>/<environment>/<organization>/o/<stored key>`. The environment is
|
|
1086
|
+
`QUICKBACK_ENVIRONMENT`, stamped on every named environment when the bridge is
|
|
1087
|
+
on, else `default`. A grant or entry is accepted only for its own
|
|
1088
|
+
organization's namespace. Partition tables cannot hold storage keys yet
|
|
1089
|
+
(`TENANCY_UNSUPPORTED`).
|
|
1090
|
+
|
|
1091
|
+
**Restore.** R2 objects are not in tenant dumps, and a database restore cannot
|
|
1092
|
+
bring back deleted bytes. When a restore takes effect, the old generation's
|
|
1093
|
+
file entries are discarded with the rest of its outbox. Every key the restored
|
|
1094
|
+
rows hold returns to `pending` and gets an `attest` entry in the new
|
|
1095
|
+
generation. The edge marks it `ready` only if the manifest row is still `live`
|
|
1096
|
+
and the object exists. A tombstoned or missing object stays `unavailable`, with
|
|
1097
|
+
the reason in `__qb_file_ops.reason`. Restore never clears a tombstone.
|
|
1098
|
+
Reservations of the abandoned timeline that the restored rows do not hold
|
|
1099
|
+
become `unavailable`; they are not deleted. A delete the restore discarded is
|
|
1100
|
+
queued again if the restored rows no longer hold the key. A grant or outcome
|
|
1101
|
+
from the old generation changes nothing.
|
|
1102
|
+
|
|
1103
|
+
**Purge.** The purge drain applies every pending file entry. A grant that was
|
|
1104
|
+
never uploaded is cleaned up at once, not left waiting for its expiry. After
|
|
1105
|
+
the object is erased, purge fences new grants for it (`TENANT_FILES_PURGING`)
|
|
1106
|
+
and starts a bounded cleanup with a durable cursor
|
|
1107
|
+
(`tenant_file_purges`). Every manifest object is tombstoned and deleted. Once
|
|
1108
|
+
every grant ever signed for the object has expired (plus grace), the
|
|
1109
|
+
organization's R2 prefix is listed and anything without a live manifest row
|
|
1110
|
+
written after the purge began is deleted. That sweep catches late uploads of
|
|
1111
|
+
unexpired grants. `syncTenants` resumes unfinished cleanups.
|
|
1112
|
+
`cleanupTenantFiles(env, id)` (from `src/lib/tenants`) runs one step and
|
|
1113
|
+
returns `{ done, phase, deleted }`. Report the external cleanup complete only
|
|
1114
|
+
once `done` is true.
|
|
1115
|
+
|
|
1116
|
+
**Version skew.** A project with the bridge emits tenant RPC version
|
|
1117
|
+
`TENANT_FILE_BRIDGE_VERSION`. Projects without it keep their version unchanged.
|
|
1118
|
+
An older edge is never handed a `file` entry. Deploy the tenant Worker first,
|
|
1119
|
+
as always.
|
|
1120
|
+
|
|
1121
|
+
### The bridge contract
|
|
1122
|
+
|
|
1123
|
+
Every bridge message is one envelope, defined in `src/tenant/bridge.ts`, which
|
|
1124
|
+
both Workers import:
|
|
1125
|
+
|
|
1126
|
+
| Field | Meaning |
|
|
1127
|
+
|---|---|
|
|
1128
|
+
| `v` | Protocol version (`1`). |
|
|
1129
|
+
| `bridge` | `'files'` or `'embeddings'` ([Embeddings](#embeddings)). Each bridge has its own ops and payloads; the envelope, identity and outcome rules are shared. |
|
|
1130
|
+
| `op` | Files: `put` / `get` (grants); `verify` / `delete` / `attest` (outbox entries). Embeddings: `index` / `delete` (outbox entries). |
|
|
1131
|
+
| `opId` | Stable operation id, carried by every retry of the operation. |
|
|
1132
|
+
| `object` | `{ tenantId, partition }` of the object that wrote it. The edge compares it with the object it routed to or drained, and never trusts it. |
|
|
1133
|
+
| `generation` | The object's outbox / restore generation when it was written. |
|
|
1134
|
+
| `payload` | Op-specific. For files: `{ table, rowPk, column, key, ... }`. For embeddings: `{ table, rowPk, revision, configVersion, text }` (index) or `{ table, rowPk, vectorId }` (delete). |
|
|
1135
|
+
|
|
1136
|
+
The deduplication identity is (object, generation, `opId`). The edge hashes the
|
|
1137
|
+
payload's identity fields per operation (files: `table`, `rowPk`, `column`,
|
|
1138
|
+
`key`; embeddings: `table`, `rowPk`, `revision`, `configVersion`).
|
|
1139
|
+
It refuses a later message with the same `opId` and a different hash
|
|
1140
|
+
(`TENANT_BRIDGE_PAYLOAD_CONFLICT`); an outbox entry is dead-lettered, never
|
|
1141
|
+
applied. Outcomes come back in the settlement's delivery receipt:
|
|
1142
|
+
`detail.bridge = { opId, state, reason? }`. The receipt keeps the operation id
|
|
1143
|
+
in `ref`. The object applies an outcome only when the envelope's generation is
|
|
1144
|
+
its current one and the operation is still in the state that outcome moves
|
|
1145
|
+
from. A duplicate or stale receipt is harmless. Delivery is at least once, so
|
|
1146
|
+
every external transition is idempotent.
|
|
1147
|
+
|
|
1148
|
+
## Embeddings
|
|
1149
|
+
|
|
1150
|
+
A tenant table may declare [`embeddings`](/platform/vector/embeddings) once the
|
|
1151
|
+
embeddings bridge is on. Without it the declaration is refused
|
|
1152
|
+
(`TENANCY_UNSUPPORTED`). The project also needs a Vectorize index
|
|
1153
|
+
(`providers.database.config.vectorizeIndexName`).
|
|
1154
|
+
|
|
1155
|
+
```ts no-compile
|
|
1156
|
+
tenancy: {
|
|
1157
|
+
isolation: 'durable-object',
|
|
1158
|
+
bridges: { embeddings: { enabled: true, candidates: 50 } },
|
|
1159
|
+
},
|
|
1160
|
+
```
|
|
1161
|
+
|
|
1162
|
+
The object owns the row and the intent. The edge Worker alone holds the `AI`
|
|
1163
|
+
and `VECTORIZE` bindings. The tenant Worker gets neither, and the
|
|
1164
|
+
import-closure check refuses `src/lib/tenant-embeddings.ts` in tenant code.
|
|
1165
|
+
There is no embeddings queue or consumer for tenant tables, and no
|
|
1166
|
+
client-facing embeddings endpoint.
|
|
1167
|
+
|
|
1168
|
+
**Intents.** Every insert, update and delete through the scoped `db` passes the
|
|
1169
|
+
audit wrapper's write chokepoint. That covers generated CRUD and batch routes,
|
|
1170
|
+
actions, jobs and trigger hooks. For each returned row the object re-reads the
|
|
1171
|
+
row's source fields from SQLite. When the text changed, it bumps the row's
|
|
1172
|
+
revision in `__qb_embedding_ops` and writes an `embedding` outbox entry (`index`)
|
|
1173
|
+
in the same SQLite transaction. A write that rolls back leaves no intent. A
|
|
1174
|
+
write whose text did not change writes none. A delete, a soft delete, or a row
|
|
1175
|
+
whose text is now empty writes a `delete` for its current vector. `onInsert:
|
|
1176
|
+
false` and `onUpdate: false` are honored. `onUpdate: [fields]` behaves like
|
|
1177
|
+
`true`, because only a change of the embedded text re-indexes. The entry
|
|
1178
|
+
carries the text, capped so the envelope fits the shared 8 KB limit; the
|
|
1179
|
+
models truncate far below it. The write must use `.returning()` with the
|
|
1180
|
+
primary key, as for every chokepoint consumer. A `.returning()` without it is
|
|
1181
|
+
logged and skipped. Raw SQL that bypasses the scoped `db`, and `sql:`
|
|
1182
|
+
triggers, record nothing. Re-index after them with `rebuildTenantEmbeddings`.
|
|
1183
|
+
|
|
1184
|
+
**Edge execution.** The drain applies `index` entries in order, after the
|
|
1185
|
+
claim's registry fence held:
|
|
1186
|
+
|
|
1187
|
+
1. The vector id is derived here, never by the object. It is a SHA-256 of
|
|
1188
|
+
project, environment, organization, generation, table, row, revision and
|
|
1189
|
+
configuration version. Ids are immutable: a late result never overwrites
|
|
1190
|
+
newer content under the same id.
|
|
1191
|
+
2. The id goes into the platform manifest (`tenant_embedding_manifest`,
|
|
1192
|
+
features D1) as `pending` before Workers AI is called. Cleanup never depends
|
|
1193
|
+
on enumerating unknown vectors. An entry whose id the manifest holds for
|
|
1194
|
+
another operation is refused (`TENANT_BRIDGE_PAYLOAD_CONFLICT`). A newer
|
|
1195
|
+
revision of the same row already indexed skips the AI call (`obsolete`).
|
|
1196
|
+
3. Workers AI embeds the text. A vector of the wrong dimensions is refused and
|
|
1197
|
+
never stored (`TENANT_EMBEDDING_DIMENSIONS`).
|
|
1198
|
+
4. The vector is upserted into the organization's namespace. That is a hash of
|
|
1199
|
+
project, environment, organization and table, derived by the edge.
|
|
1200
|
+
5. The manifest row moves to `live` only if it is still `pending`. If a delete
|
|
1201
|
+
or a sweep tombstoned it during the call, the edge deletes what it just
|
|
1202
|
+
wrote and settles `obsolete`.
|
|
1203
|
+
|
|
1204
|
+
The object accepts a `ready` outcome only for the same operation and revision,
|
|
1205
|
+
in its current generation, while the row is still `pending`. Anything else is
|
|
1206
|
+
obsolete, and the object queues a `delete` for that vector. Delivery is at
|
|
1207
|
+
least once. A retry repeats the same id and values. An AI call may still run
|
|
1208
|
+
twice, or after the row changed; it costs a call, never correctness. The
|
|
1209
|
+
configuration version hashes `model`, `fields` and `separator`. An entry
|
|
1210
|
+
written under another configuration settles `obsolete` without an AI call.
|
|
1211
|
+
|
|
1212
|
+
**Deletes.** A `delete` entry tombstones the manifest row (irreversibly),
|
|
1213
|
+
deletes the vector, then records it `deleted`. A missing vector counts as
|
|
1214
|
+
deleted. A tombstoned id is never indexed again.
|
|
1215
|
+
|
|
1216
|
+
**Search.** `GET <collection>?similar=<text>` and
|
|
1217
|
+
`GET <collection>/views/<name>?similar=<text>` are the semantic reads. Before
|
|
1218
|
+
forwarding, the edge embeds the text (at most 1 KB) and queries the
|
|
1219
|
+
organization's namespace for `candidates` matches (default 50, 10–100). The
|
|
1220
|
+
client never chooses the namespace. The matches ride the RPC principal, not a
|
|
1221
|
+
header, so a client cannot supply them. In the object, a match resolves to a row
|
|
1222
|
+
only through that row's current `ready` vector in the current generation and
|
|
1223
|
+
configuration. The resolved rows join the read route's filter set beside the
|
|
1224
|
+
firewall, access, soft-delete and query filters. Masking and views then apply
|
|
1225
|
+
as for any read. Results come best match first unless `?sort=` is given.
|
|
1226
|
+
|
|
1227
|
+
- Rejected candidates leave no trace. There are no scores, no vector metadata,
|
|
1228
|
+
no ids and no counts.
|
|
1229
|
+
- `?similar=` cannot be combined with `?search=`, `?total=`, aggregations or
|
|
1230
|
+
cursors (400). Pages use `?offset=` / `?limit=`, and `offset + limit` may not
|
|
1231
|
+
exceed `candidates` (400).
|
|
1232
|
+
- Without matches carried in, for example from an older edge, the route answers
|
|
1233
|
+
`503 EMBEDDING_SEARCH_UNAVAILABLE`, never an unfiltered list. If the AI or
|
|
1234
|
+
Vectorize call fails, the edge answers the same.
|
|
1235
|
+
- The edge checks the registry before any AI or Vectorize call. A purged
|
|
1236
|
+
object gets `410 TENANT_PURGED`; one with a restore pending, or not active,
|
|
1237
|
+
gets `503 TENANT_RESTORE_PENDING`.
|
|
1238
|
+
- Indexing is eventual. Right after a write, a row may be missing from results
|
|
1239
|
+
until its new vector is ready. A query may return fewer than `limit` rows when
|
|
1240
|
+
candidates fail the filters. It is not an exact top-K.
|
|
1241
|
+
|
|
1242
|
+
The vector namespace is the organization. So the table's firewall may bind
|
|
1243
|
+
only its organization column, and its read access must be role-only. An owner
|
|
1244
|
+
arm, a record predicate, a relationship or FGA arm, or an access function
|
|
1245
|
+
would make the candidate universe wider than the caller's rows
|
|
1246
|
+
(`TENANCY_EMBEDDINGS_SCOPE`). Source fields must be plain columns. Masked,
|
|
1247
|
+
`.encrypted()`, `.sealed()`, `q.secret()`, `q.vaultRef()` and `q.storageKey()`
|
|
1248
|
+
columns are refused (`TENANCY_EMBEDDINGS_PROTECTED_SOURCE`). Vectors live only
|
|
1249
|
+
in Vectorize: `embeddingColumn` (`TENANCY_EMBEDDINGS_COLUMN`) and `metadata`
|
|
1250
|
+
(`TENANCY_EMBEDDINGS_METADATA`) are refused. Use ordinary query filters beside
|
|
1251
|
+
`?similar=` instead. Partition tables cannot embed yet (`TENANCY_UNSUPPORTED`).
|
|
1252
|
+
A [`defineEmbedding`](/platform/vector/embeddings#similarity-search-service)
|
|
1253
|
+
search helper over the same index is refused (`TENANCY_EMBEDDINGS_SERVICE`).
|
|
1254
|
+
It queries without a namespace and returns raw ids and scores.
|
|
1255
|
+
|
|
1256
|
+
**Models.** `@cf/baai/bge-small-en-v1.5` (384), `@cf/baai/bge-base-en-v1.5`
|
|
1257
|
+
(768, the default), `@cf/baai/bge-large-en-v1.5` (1024) and `@cf/baai/bge-m3`
|
|
1258
|
+
(1024). Every embedded tenant table shares the one index, so they must share a
|
|
1259
|
+
dimension (`TENANCY_EMBEDDINGS_MODEL`). Create the index with that dimension and
|
|
1260
|
+
cosine metric. A model or field change changes the configuration version.
|
|
1261
|
+
Until a rebuild, old vectors stop matching. A change of dimension needs a new
|
|
1262
|
+
Vectorize index (a new `vectorizeIndexName`) and a rebuild of every
|
|
1263
|
+
organization. The bridge does not build a second index side by side.
|
|
1264
|
+
|
|
1265
|
+
**Restore.** When a restore takes effect, the old generation's embedding
|
|
1266
|
+
entries are discarded with the rest of its outbox. Every restored row is
|
|
1267
|
+
re-indexed in the new generation with a new revision and vector id. Rows the
|
|
1268
|
+
restore removed are marked deleted. A vector from the old generation never
|
|
1269
|
+
resolves to a row, because the generation is checked, and a late
|
|
1270
|
+
old-generation receipt never reaches the object. The manifest is outside the
|
|
1271
|
+
rewound database. `syncTenants` sweeps vectors whose generation is not the
|
|
1272
|
+
registry's current one, once they are five minutes old, so in-flight results
|
|
1273
|
+
land first. The sweep tombstones, deletes and records them.
|
|
1274
|
+
|
|
1275
|
+
**Purge.** The purge drain settles pending `index` entries without an AI call.
|
|
1276
|
+
It still applies `delete` entries. Once the registry row is `purged`, searches
|
|
1277
|
+
are refused before any AI call, and every manifest vector of the object is an
|
|
1278
|
+
orphan. `syncTenants` deletes them in bounded, resumable steps.
|
|
1279
|
+
`cleanupTenantEmbeddings(env, id)` (from `src/lib/tenants`) runs one step and
|
|
1280
|
+
returns `{ deleted, done }`. Report the external cleanup complete only once
|
|
1281
|
+
`done` is true.
|
|
1282
|
+
|
|
1283
|
+
**Operations** (from `src/lib/tenants`; authenticate the caller and verify the
|
|
1284
|
+
tenant first):
|
|
1285
|
+
|
|
1286
|
+
| Call | Does |
|
|
1287
|
+
|---|---|
|
|
1288
|
+
| `rebuildTenantEmbeddings(env, id, table, { after?, pageSize?, maxPages? })` | Re-indexes rows in bounded pages by primary key, draining after each page. It skips rows whose current vector is ready for the same text, generation and configuration. Returns `{ queued, done, next }`; pass `next` back as `after` to resume. Use it after a configuration change, a raw SQL write, or to retry `failed` rows. |
|
|
1289
|
+
| `tenantEmbeddingStatus(env, id)` | Counts per table and state (`pending`, `ready`, `failed`, `obsolete`, `deleted`). Rows from a previous generation are counted apart. |
|
|
1290
|
+
| `cleanupTenantEmbeddings(env, id)` | One bounded orphan-cleanup step for the object. |
|
|
1291
|
+
|
|
1292
|
+
**Version skew.** A project with the bridge and an embedded tenant table emits
|
|
1293
|
+
tenant RPC version `TENANT_EMBEDDING_BRIDGE_VERSION`. Projects without it keep
|
|
1294
|
+
their version unchanged. An older edge is never handed an `embedding` entry, and
|
|
1295
|
+
the object ignores semantic matches from one. Deploy the tenant Worker first,
|
|
1296
|
+
as always.
|
|
1297
|
+
|
|
1298
|
+
Not proven by local tests: real model dimensions, Vectorize namespace limits
|
|
1299
|
+
per index, Vectorize's eventual consistency after upserts and deletes, and
|
|
1300
|
+
query latency. Verify those against a dedicated Cloudflare test account before
|
|
1301
|
+
relying on them.
|
|
1302
|
+
|
|
878
1303
|
## Hard deletes and the audit log
|
|
879
1304
|
|
|
880
1305
|
The tenant Worker has no `AUDIT_DB`. A hard `DELETE` (single or batch) on a
|
|
@@ -1217,7 +1642,7 @@ A **tenant job** is a `services/queues` handler that runs inside a tenant
|
|
|
1217
1642
|
object. Mark it `tenant: true` (implied when it imports an unpartitioned tenant
|
|
1218
1643
|
feature). A handler may not mix platform and tenant imports; a feature with no
|
|
1219
1644
|
tables (helpers only) is neither, so either kind may import it. Partitioned
|
|
1220
|
-
feature imports
|
|
1645
|
+
feature imports need an explicit partition placement — see [Partition jobs](#partition-jobs).
|
|
1221
1646
|
Inside a tenant job, `tenant` on the execute context supplies scheduling,
|
|
1222
1647
|
cancellation and outbox delivery; it is absent for platform handlers.
|
|
1223
1648
|
|
|
@@ -1396,7 +1821,9 @@ tenantRuntime(env).enqueue("COMMS_QUEUE", { type: "mail.send", guestId: row.id }
|
|
|
1396
1821
|
from the edge Worker, a message the queue refuses) is dead-lettered so it
|
|
1397
1822
|
does not block the outbox.
|
|
1398
1823
|
- **Declared bindings only.** The binding must be one of the edge Worker's
|
|
1399
|
-
queues (the primary queue and `additionalQueues
|
|
1824
|
+
queues (the primary queue and `additionalQueues`; each takes the consumer
|
|
1825
|
+
settings `maxBatchSize`, `maxBatchTimeout`, `maxRetries`, `maxConcurrency` and
|
|
1826
|
+
`deadLetterQueue` — see [Custom queues](/platform/queues#custom-queues)). The build refuses any
|
|
1400
1827
|
other name, or a name it cannot read (not a string literal), in tenant
|
|
1401
1828
|
actions, tenant jobs, JS trigger handlers and the helpers they import
|
|
1402
1829
|
(`TENANCY_QUEUE_BINDING`); at runtime the object refuses it
|
|
@@ -1417,6 +1844,53 @@ edge producers must set `tenantId` from the caller's `ctx`
|
|
|
1417
1844
|
(`ctx.activeOrgId`), never from request input. A restore discards queued `queue` entries with the other outbox
|
|
1418
1845
|
entries that are neither audit rows nor scope revocations.
|
|
1419
1846
|
|
|
1847
|
+
#### Running a message at once (inline)
|
|
1848
|
+
|
|
1849
|
+
A queue adds seconds between the response and the consumer. For a message
|
|
1850
|
+
that should not wait (a push notification for a chat message), the edge can
|
|
1851
|
+
run the handler itself as soon as the tenant's response comes back, and keep
|
|
1852
|
+
the queue as the fallback. Both sides opt in:
|
|
1853
|
+
|
|
1854
|
+
{/* doc-compile: skip — handler and producer fragments */}
|
|
1855
|
+
```ts
|
|
1856
|
+
// quickback/services/queues/sendPush.ts — an edge handler
|
|
1857
|
+
export default defineQueue<{ type: "push.send"; tenantId: string; dedupeKey: string; userIds: string[] }>({
|
|
1858
|
+
name: "sendPush",
|
|
1859
|
+
messageType: "push.send",
|
|
1860
|
+
edgeInline: true,
|
|
1861
|
+
execute: async ({ message, env }) => { /* claim message.dedupeKey, then send */ return { success: true }; },
|
|
1862
|
+
});
|
|
1863
|
+
|
|
1864
|
+
// a tenant action — the producer decides per message
|
|
1865
|
+
tenantRuntime(env).enqueue("COMMS_QUEUE", { type: "push.send", userIds }, { inline: userIds.length <= 50 });
|
|
1866
|
+
```
|
|
1867
|
+
|
|
1868
|
+
- The row is still written to the outbox with the request's writes. After the
|
|
1869
|
+
response the edge runs the handler with the same
|
|
1870
|
+
`{ ...message, tenantId, dedupeKey }` body, beside the realtime frames and
|
|
1871
|
+
beside any other inline message of that response.
|
|
1872
|
+
- **The queue is the fallback.** If the run throws, returns
|
|
1873
|
+
`success: false`, calls `retry()`, or takes longer than 15 seconds, the edge
|
|
1874
|
+
sends the message to the queue with the same `dedupeKey`. A message without
|
|
1875
|
+
`inline: true`, or whose handler does not declare `edgeInline: true`, goes
|
|
1876
|
+
to the queue as before.
|
|
1877
|
+
- **Claim `dedupeKey` first.** One row can reach the handler more than once:
|
|
1878
|
+
an inline run that timed out may still be running when the queue delivers
|
|
1879
|
+
it, and an edge that stops mid-run leaves the row to be claimed again after
|
|
1880
|
+
its lease. Claim `message.dedupeKey` (in the tenant, with a result job, or
|
|
1881
|
+
in KV) before any side effect, as for any at-least-once consumer.
|
|
1882
|
+
- **Only on the request's own response, eight at most.** A message runs
|
|
1883
|
+
inline when its row comes back with the response of the request that wrote
|
|
1884
|
+
it (up to 32 rows do). At most eight marked rows per response run inline;
|
|
1885
|
+
the rest, and every row delivered later by a drain, a sweep or a tenant
|
|
1886
|
+
job's outbox, go to the queue.
|
|
1887
|
+
- The run counts against the request's `waitUntil` time, so mark only small
|
|
1888
|
+
messages. Send large fan-outs without `inline`.
|
|
1889
|
+
- `edgeInline` must be the literal `true` on a handler that runs on the edge;
|
|
1890
|
+
a tenant job, or a project without tenant objects, fails the build
|
|
1891
|
+
(`QUEUE_EDGE_INLINE`). The delivery receipt of a message that ran inline has
|
|
1892
|
+
`detail.inline: true`.
|
|
1893
|
+
|
|
1420
1894
|
### Result jobs
|
|
1421
1895
|
|
|
1422
1896
|
Edge code sometimes needs an answer from a tenant's database: a public page
|
|
@@ -1507,8 +1981,10 @@ another way, such as a signed webhook naming the organization, put
|
|
|
1507
1981
|
`// quickback-allow-tenant-source: <reason>` on the line above the call.
|
|
1508
1982
|
|
|
1509
1983
|
The object refuses, before the job runs, a message that is not a result job,
|
|
1510
|
-
a message for another tenant, a
|
|
1511
|
-
|
|
1984
|
+
a message for another tenant, a control object, an object of the wrong
|
|
1985
|
+
placement (an organization result job in a partition object, or a
|
|
1986
|
+
[partition result job](#partition-jobs) anywhere but its partition), or a
|
|
1987
|
+
missing `runId` (`TENANT_JOB_INVALID`). It sets `tenantId` from the object's name. The
|
|
1512
1988
|
edge helper throws on the same caller bugs. Pass only a server-verified
|
|
1513
1989
|
organization id: a session's organization, or one resolved through
|
|
1514
1990
|
[`tenancy.lookups`](#lookup-indexes).
|
|
@@ -1525,6 +2001,133 @@ alarm.
|
|
|
1525
2001
|
`true`, and the handler must be a tenant job (`TENANCY_JOB_RESULT_SCHEMA`).
|
|
1526
2002
|
Result jobs need `isolation: 'durable-object'`.
|
|
1527
2003
|
|
|
2004
|
+
### Partition jobs
|
|
2005
|
+
|
|
2006
|
+
A tenant job normally runs in the organization object. A job that works on a
|
|
2007
|
+
[partition](#partitions)'s rows — a conversation's messages, a document's
|
|
2008
|
+
blocks — runs in that partition's own object instead, so it never routes
|
|
2009
|
+
through the organization's database. Declare the placement:
|
|
2010
|
+
|
|
2011
|
+
{/* doc-compile: skip — needs a conversation-partitioned messages feature */}
|
|
2012
|
+
```ts title="quickback/services/queues/conversationSummary.ts"
|
|
2013
|
+
import { defineQueue } from "@quickback/compiler";
|
|
2014
|
+
import { messages } from "../../features/messages/schema";
|
|
2015
|
+
|
|
2016
|
+
export default defineQueue<{ type: "conversation.summary"; tenantId: string; partitionKey: string }>({
|
|
2017
|
+
name: "conversationSummary",
|
|
2018
|
+
messageType: "conversation.summary",
|
|
2019
|
+
placement: { partition: "conversation" },
|
|
2020
|
+
execute: async ({ db, tenant }) => {
|
|
2021
|
+
const rows = await db.select().from(messages); // this conversation's rows only
|
|
2022
|
+
// tenant.partitionKey === the conversation id; tenant.tenantId === the organization
|
|
2023
|
+
return { success: true };
|
|
2024
|
+
},
|
|
2025
|
+
});
|
|
2026
|
+
```
|
|
2027
|
+
|
|
2028
|
+
`placement: 'tenant'` is the organization object (the same as `tenant:
|
|
2029
|
+
true`); `placement: { partition: '<kind>' }` names the project's partition
|
|
2030
|
+
kind. A partition job imports only that kind's features (plus tableless
|
|
2031
|
+
helpers) and may be a [result job](#result-jobs) too. The build refuses:
|
|
2032
|
+
|
|
2033
|
+
| Code | When |
|
|
2034
|
+
|---|---|
|
|
2035
|
+
| `TENANCY_JOB_PLACEMENT` | `placement` is not `'tenant'` or a literal `{ partition: '<kind>' }`, names a kind the project does not declare, or is combined with `tenant: true`. |
|
|
2036
|
+
| `TENANCY_QUEUE_PARTITION` | A handler imports a partitioned feature without being placed in that partition. |
|
|
2037
|
+
| `TENANCY_QUEUE_MIXED_PLACEMENT` / `TENANCY_CROSS_PARTITION` | A partition job imports, or names, an organization or platform table. |
|
|
2038
|
+
| `TENANCY_QUEUE_PARTITION_KEY` | A `{ type: '<partition job>' }` message literal has no `partitionKey` and is not passed to a target helper or `tenant.send({ key }, …)` / `tenant.schedule(…)` inside the partition. |
|
|
2039
|
+
| `TENANCY_SCHEDULE` | A partition job declares `schedule:` — [tenant schedules](#tenant-schedules) run in organization objects only. Schedule its occurrences explicitly (below). |
|
|
2040
|
+
|
|
2041
|
+
**Targets.** Every partition delivery names its exact object. The edge
|
|
2042
|
+
helpers take a `TenantJobTarget`:
|
|
2043
|
+
|
|
2044
|
+
{/* doc-compile: skip — type fragment */}
|
|
2045
|
+
```ts
|
|
2046
|
+
type TenantJobTarget =
|
|
2047
|
+
| { kind: "organization"; organizationId: string }
|
|
2048
|
+
| { kind: "partition"; organizationId: string; partition: string; key: string };
|
|
2049
|
+
```
|
|
2050
|
+
|
|
2051
|
+
| Helper | Does |
|
|
2052
|
+
|---|---|
|
|
2053
|
+
| `deliverJob(env, target, message, runId, { generation? })` | Runs the job now in the target object (queue semantics). |
|
|
2054
|
+
| `callJob(env, target, message, runId, options?)` | `callTenantJob` for a target: a partition result job runs in its partition and replays only there. |
|
|
2055
|
+
| `scheduleJob(env, target, key, at, message)` / `cancelJob(env, target, key)` | An occurrence in the target object's own alarm table. |
|
|
2056
|
+
| `enqueueTenantJob(env, binding, target, message)` | Sends the generated queue envelope; the edge consumer delivers it to the target. |
|
|
2057
|
+
|
|
2058
|
+
`callTenantJob`, `deliverTenantJob`, `scheduleTenantJob` and `cancelTenantJob`
|
|
2059
|
+
stay as the organization-object spellings (they refuse a `<orgId>:<key>`
|
|
2060
|
+
name). Inside a tenant action or job, `tenant.send({ key }, message)` and
|
|
2061
|
+
`tenant.schedule(key, at, message)` (in a partition object) target partitions
|
|
2062
|
+
the same way. Every helper stamps `tenantId` and `partitionKey` from the
|
|
2063
|
+
target and drops any the message carries. A producer that builds its own queue
|
|
2064
|
+
message must set both: `{ type, tenantId, partitionKey, … }`.
|
|
2065
|
+
|
|
2066
|
+
**Authority.** A partition job runs with system rights in its partition.
|
|
2067
|
+
`organizationId` must be server-verified exactly like `callTenantJob`'s tenant
|
|
2068
|
+
(`TENANCY_JOB_CALL_TENANT_SOURCE` checks the target literal's
|
|
2069
|
+
`organizationId`). The key only routes within that organization, so a key from
|
|
2070
|
+
the request is not authority: check that the caller may act on that partition
|
|
2071
|
+
before calling. A partition target must already be registered to that
|
|
2072
|
+
organization in `tenant_registry` (its first request registers it). A job
|
|
2073
|
+
never creates a partition object: an unknown one is `TENANT_NOT_PROVISIONED`,
|
|
2074
|
+
a purged one `TENANT_PURGED`, one mid-restore `TENANT_RESTORE_PENDING`.
|
|
2075
|
+
A [workflow](/platform/workflows#tenant-and-partition-steps) calls a result job
|
|
2076
|
+
through `step.job(name, target, message)`. That target's organization must be
|
|
2077
|
+
the run's own, and the step passes the actor authority check first.
|
|
2078
|
+
|
|
2079
|
+
**Identity and dedupe.** A job's identity is the deployment (namespace and
|
|
2080
|
+
jurisdiction), organization, partition kind, key, job type and `runId`. The
|
|
2081
|
+
same `runId` in another partition, or in another organization's partition with
|
|
2082
|
+
the same key, is a different job: each object keeps its own run markers,
|
|
2083
|
+
results and alarms. A result job's `runId` with a different message in the
|
|
2084
|
+
same object is `TENANT_JOB_RUN_CONFLICT`.
|
|
2085
|
+
|
|
2086
|
+
**Checks in the object.** Before a handler runs, the destination refuses
|
|
2087
|
+
(`TENANT_JOB_PLACEMENT`, dead-lettered from the outbox and alarms) a partition
|
|
2088
|
+
job outside a partition object, an organization job inside one, and a message
|
|
2089
|
+
whose `partitionKey` differs from the object's own name. An organization
|
|
2090
|
+
message that names a partition is refused too. Partition jobs need RPC
|
|
2091
|
+
version 16 at both ends. An older edge or tenant refuses them
|
|
2092
|
+
(`TENANT_RPC_VERSION_MISMATCH`), so nothing routes them to the organization
|
|
2093
|
+
object. Deploy the tenant Worker first, as for every version bump.
|
|
2094
|
+
|
|
2095
|
+
**Restore generations.** Queued work is fenced by the object's restore
|
|
2096
|
+
generation (`tenant_registry.outbox_generation`, advanced by every restore).
|
|
2097
|
+
`enqueueTenantJob` stamps the target's generation on the envelope
|
|
2098
|
+
(`tenantGeneration`). The consumer delivers it with that expected generation,
|
|
2099
|
+
and the object refuses any other (`TENANT_JOB_STALE_GENERATION`). The consumer
|
|
2100
|
+
then acks and logs it: work queued for a timeline that a restore replaced
|
|
2101
|
+
never runs against the restored data. `deliverJob` to a partition without an
|
|
2102
|
+
envelope generation passes the registry's current generation. A restore that
|
|
2103
|
+
has committed but not yet reconciled in the object is refused and retried.
|
|
2104
|
+
Cross-object outbox deliveries keep the source-generation fence (a restored
|
|
2105
|
+
source's old entries are never delivered). The destination stamps
|
|
2106
|
+
`tenantId` and `partitionKey` from the target name.
|
|
2107
|
+
|
|
2108
|
+
**Scheduling and cancellation.** Each object multiplexes its own scheduled
|
|
2109
|
+
rows onto its single native alarm. The same key in two partitions is two
|
|
2110
|
+
occurrences, and `cancelJob` on one never touches the other. Cancellation
|
|
2111
|
+
removes an occurrence that has not started. A handler already running
|
|
2112
|
+
finishes, and its `runId` stays the idempotency key for any side effect it
|
|
2113
|
+
made. Delivery is at least once in every lane. A restore rewinds a partition's
|
|
2114
|
+
alarm rows with its data, as for an organization.
|
|
2115
|
+
|
|
2116
|
+
{/* doc-compile: skip — action body fragment */}
|
|
2117
|
+
```ts
|
|
2118
|
+
import { deliverJob, scheduleJob } from "../../../lib/tenants";
|
|
2119
|
+
|
|
2120
|
+
const target = { kind: "partition", organizationId: ctx.activeOrgId!, partition: "conversation", key: input.conversationId } as const;
|
|
2121
|
+
// The caller's access to this conversation was checked above.
|
|
2122
|
+
await deliverJob(env, target, { type: "conversation.summary" }, "summary:" + crypto.randomUUID());
|
|
2123
|
+
await scheduleJob(env, target, "summary", Date.now() + 60_000, { type: "conversation.summary" });
|
|
2124
|
+
```
|
|
2125
|
+
|
|
2126
|
+
Plans that route other background work to partitions (workflows, managed
|
|
2127
|
+
files, embeddings) use this same `TenantJobTarget` and its checks: exact
|
|
2128
|
+
target, registered destination, placement, partition key and restore
|
|
2129
|
+
generation.
|
|
2130
|
+
|
|
1528
2131
|
Realtime broadcasts from tenant tables (`realtime: { enabled: true }`) are
|
|
1529
2132
|
recorded in the object's outbox with the write and replayed by the edge through
|
|
1530
2133
|
the Broadcaster as the response returns ([outbox delivery](#outbox-delivery)).
|
|
@@ -1537,7 +2140,7 @@ is queued as the same `broadcast('<namespace>:<event>', …)` the edge sends.
|
|
|
1537
2140
|
Everything a tenant object hands the edge goes through its outbox, a table in
|
|
1538
2141
|
the object's SQLite written in the same transaction as the writes that caused
|
|
1539
2142
|
it:
|
|
1540
|
-
- realtime frames;
|
|
2143
|
+
- realtime frames, `changes.broadcast` frames included;
|
|
1541
2144
|
- `audit_events` rows;
|
|
1542
2145
|
- lookup-index changes;
|
|
1543
2146
|
- jobs for other objects;
|
|
@@ -1957,7 +2560,9 @@ tenantRuntime(env).send("tenant", { type: "conversation.posted", conversationId:
|
|
|
1957
2560
|
```
|
|
1958
2561
|
|
|
1959
2562
|
`send("tenant", …)` targets the organization object; `send({ key }, …)` a
|
|
1960
|
-
partition object of the same organization
|
|
2563
|
+
partition object of the same organization, and only with a
|
|
2564
|
+
[partition job](#partition-jobs) (`TENANT_JOB_PLACEMENT` otherwise, at write
|
|
2565
|
+
time).
|
|
1961
2566
|
|
|
1962
2567
|
## Deleting the namespace
|
|
1963
2568
|
|
|
@@ -2288,12 +2893,12 @@ organization's object before you apply that migration.
|
|
|
2288
2893
|
| `TENANCY_ASYNC_TRANSACTION` | A tenant action, a helper it reaches, or a JS trigger handler passes an async or Promise-returning callback to `transaction()` on a db / tx handle. |
|
|
2289
2894
|
| `TENANCY_BATCH_ASYNC` | A tenant table's `create` / `update` / `upsert` access, or its `guards`, is a function. |
|
|
2290
2895
|
| `TENANCY_UNSAFE_RECREATE` | A new tenant migration recreates a referenced table or copies into an unsafe NOT NULL column. |
|
|
2291
|
-
| `TENANCY_UNSAFE_ACTION` / `TENANCY_ROOT_ACTION` / `TENANCY_CTX_UNAVAILABLE` | A tenant action is cross-tenant `unsafe` (`unsafe: true`, or an object without `crossTenant: false`) or sets `unsafe.authWrites`, mounts outside its feature's path (and outside every [tenant namespace](#tenant-namespaces) prefix), or reads `ctx.auth`, `ctx.tenancy`, `ctx.mintScope` or `ctx.seal` — or `ctx.fga` when the project declares no `authz.fga` — by property access or destructuring, including the `auth` execute param. They exist only on the edge. The `ctx` check also covers helpers tenant code imports and JS trigger handlers on tenant tables. Keep cross-tenant `unsafe` and root-path ingress in a platform feature and call a [result job](#result-jobs). `unsafe: { reason, crossTenant: false }` is allowed: see [Same-tenant unsafe actions](#same-tenant-unsafe-actions). |
|
|
2896
|
+
| `TENANCY_UNSAFE_ACTION` / `TENANCY_ROOT_ACTION` / `TENANCY_CTX_UNAVAILABLE` | A tenant action is cross-tenant `unsafe` (`unsafe: true`, or an object without `crossTenant: false`) or sets `unsafe.authWrites`, mounts outside its feature's path (and outside its tables' routes and every [tenant namespace](#tenant-namespaces) prefix; see [Actions at a table route](#actions-at-a-table-route)), or reads `ctx.auth`, `ctx.tenancy`, `ctx.mintScope` or `ctx.seal` — or `ctx.fga` when the project declares no `authz.fga` — by property access or destructuring, including the `auth` execute param. They exist only on the edge. The `ctx` check also covers helpers tenant code imports and JS trigger handlers on tenant tables. Keep cross-tenant `unsafe` and root-path ingress in a platform feature and call a [result job](#result-jobs). `unsafe: { reason, crossTenant: false }` is allowed: see [Same-tenant unsafe actions](#same-tenant-unsafe-actions). |
|
|
2292
2897
|
| `TENANCY_QUEUE_BINDING` | Tenant code (an action, a tenant job, a JS trigger handler or a helper they import) enqueues to a binding that is not one of the edge Worker's queues, or one the build cannot read. See [Platform queues](#platform-queues). |
|
|
2293
2898
|
| `TENANCY_ENV_UNAVAILABLE` | A tenant action, a tenant job's body, a helper either imports, or a JS trigger handler on a tenant table reads an `env` binding (`env.DB`, `c.env.AUTH_DB`, `const { BUCKET } = env`, …). The tenant Worker has no D1, R2, KV, queue, var or secret bindings. |
|
|
2294
2899
|
| `TENANCY_HELPER_UNRESOLVED` | A module tenant code loads imports a relative or alias path that names no file in the build, or uses a computed `import()` / `require()`. See [Helpers run where their caller runs](#helpers-run-where-their-caller-runs). |
|
|
2295
2900
|
| `TENANCY_TRIGGER_UNVERIFIABLE` | A JS `handler:` trigger on a tenant table has a source that can't be extracted as one arrow function or function expression. |
|
|
2296
|
-
| `TENANCY_JOB_CALL_TENANT_SOURCE` | `callTenantJob`'s tenant argument is not visibly server-verified (`ctx.activeOrgId` / `ctx.tenantId`, a `resolveTenant` / `resolvePrincipalTenant` result, a `forEachTenant` callback's tenant). Opt out with `// quickback-allow-tenant-source: <reason>`. See [Result jobs](#result-jobs). |
|
|
2901
|
+
| `TENANCY_JOB_CALL_TENANT_SOURCE` | `callTenantJob`'s tenant argument (or a [target helper](#partition-jobs)'s `organizationId`) is not visibly server-verified (`ctx.activeOrgId` / `ctx.tenantId`, a `resolveTenant` / `resolvePrincipalTenant` result, a `forEachTenant` callback's tenant). Opt out with `// quickback-allow-tenant-source: <reason>`. See [Result jobs](#result-jobs). |
|
|
2297
2902
|
| `TENANCY_JOB_RESULT_SCHEMA` / `TENANCY_JOB_RESULT_PRODUCER` | A result job without `resultSchema` (or a `resultSchema` without `result: true`), a `resultSchema` that is not a stripping or strict `z.object`, a `result` that is not the literal `true`, a result job that is not a tenant job or a project without `isolation: 'durable-object'`; or a result-job message built anywhere but `callTenantJob`'s message argument. See [Result jobs](#result-jobs). |
|
|
2298
2903
|
| `TENANCY_ADMISSION_DEPENDENCY` | Edge code reads a tenant-placed table: a scope kind, namespace, ws-ticket, live view, platform feature's authorization, derived JSON key, or a platform action's anchor, refs or operator target. Also a platform action, feature `lib/` file, schedule, non-tenant queue handler, or edge-loaded `quickback/lib` helper or auth hook naming a tenant table, an edge module importing a tenant feature's module or using a computed `import()` / `require()`, an ambiguous scope instance, or an unresolved instance on a kind that is also a lookup. At runtime, an edge query on a tenant table throws `TENANT_TABLE_ON_EDGE`. See [Admission tables stay on the platform](#admission-tables-stay-on-the-platform). |
|
|
2299
2904
|
| `TENANCY_ADMISSION_MIXED_PLACEMENT`, `_PARTITIONED`, `_UNRESOLVED_INSTANCE`, `_TENANT_COLUMN`, `_LOOKUP`, `_SQL_HELPER`, `_SELF`, `_HOPS` | A scope kind reads a tenant table but can't be tenant-backed. See [Which kinds can be tenant-backed](#which-kinds-can-be-tenant-backed). |
|
|
@@ -2309,13 +2914,21 @@ organization's object before you apply that migration.
|
|
|
2309
2914
|
| `REALTIME_RECIPIENT_PROVING_TABLE` | A recipients resolver's `recipient.scope` names a literal `provingTable` that is not one of the kind's proving tables (a relationship `from` of its roles). Any tenancy mode. |
|
|
2310
2915
|
| `TENANCY_REALTIME_VIEW_ROOM` | A live view is rooted on a tenant table while a scope kind is tenant-backed. View rooms are not tenant-qualified yet. |
|
|
2311
2916
|
| `TENANCY_LEGACY_SCOPE_TICKET` | `realtime.wsTicket` accepts supplied-scope principals (`acceptScope`) for a tenant room or a tenant-backed kind. A legacy scope claim carries no tenant, so its ticket cannot name a tenant room. |
|
|
2312
|
-
| `TENANCY_UNSUPPORTED` | A tenant table declares `
|
|
2917
|
+
| `TENANCY_UNSUPPORTED` | A tenant table declares `namespace`, `afterCommit`, or a `.sealed()` column; `embeddings` without `tenancy.bridges.embeddings`, or on a partition table; a `q.storageKey()` column without `tenancy.bridges.files`, or on a partition table. `.encrypted()` and `q.secret()` are supported: see [Encrypted columns](#encrypted-columns); storage keys: [Managed files](#managed-files); embeddings: [Embeddings](#embeddings). |
|
|
2918
|
+
| `TENANCY_OWNS_CROSS_OBJECT` | A table's `owns` names a table in another placement (a platform table, another partition). A changeset writes root and children in one transaction in the root's database: keep owned tables in the root's placement. |
|
|
2919
|
+
| `TENANCY_FILES_BRIDGE` | `tenancy.bridges.files` without `isolation: 'durable-object'`. |
|
|
2920
|
+
| `TENANCY_EMBEDDINGS_BRIDGE` / `_VECTORIZE` / `_AUDIT` | `tenancy.bridges.embeddings` without `isolation: 'durable-object'`; embedded tenant tables without `providers.database.config.vectorizeIndexName`; or `auditFields: false`, which removes the write chokepoint intents are recorded at. |
|
|
2921
|
+
| `TENANCY_EMBEDDINGS_SOURCE` / `_PROTECTED_SOURCE` | An embedded tenant table's `fields` is empty or names a column the table does not have, or names a masked, `.encrypted()`, `.sealed()`, `q.secret()`, `q.vaultRef()` or `q.storageKey()` column. |
|
|
2922
|
+
| `TENANCY_EMBEDDINGS_SCOPE` | An embedded tenant table's firewall binds anything besides its organization column, or its read access authorizes per row (owner, record predicates, relationships, FGA, a function). See [Embeddings](#embeddings). |
|
|
2923
|
+
| `TENANCY_EMBEDDINGS_SERVICE` | A `defineEmbedding` search helper uses the Vectorize binding tenant vectors live in. Its helper queries without an organization namespace and returns raw ids and scores. Search tenant tables with `?similar=`, or point the definition at another index. |
|
|
2924
|
+
| `TENANCY_EMBEDDINGS_MODEL` / `_COLUMN` / `_METADATA` | A model the bridge cannot size an index for, or embedded tenant tables of different dimensions; `embeddingColumn` or `metadata` on an embedded tenant table. |
|
|
2313
2925
|
| `TENANCY_TRIGGER_CROSS_OBJECT` | A tenant table's `sql:` trigger (body or `when:`) names a table outside its own object — a platform table, another partition kind, or a table no feature declares — or uses SQL the compiler does not model (a schema-qualified name, a CTE, a table-valued function other than `json_each` / `json_tree`, a statement keyword such as `DROP` / `PRAGMA`, unbalanced parentheses). Also a platform table's trigger that names a tenant table. Every violation is listed. |
|
|
2314
2926
|
| `TENANCY_BACKUP` | `tenancy.backup.bucket` is not an UPPER_SNAKE binding name, or `every` is not `<n>m` / `<n>h` / `<n>d` of at least 15 minutes. |
|
|
2315
2927
|
| `TENANCY_LOOKUP` | A lookup's table is not a tenant table, or its column is not a column of that table. |
|
|
2316
2928
|
| `TENANCY_PARTITION` / `TENANCY_PARTITION_UNSCOPED` / `TENANCY_PARTITION_KEY` / `TENANCY_PARTITION_KINDS` | A partition name is not a lowercase identifier, the table has no organization arm, the key is not a column (or differs within the feature), or the project declares more than one partition kind. |
|
|
2317
2929
|
| `TENANCY_FK_CROSS_PARTITION` / `TENANCY_CROSS_PARTITION` | A foreign key, or an action (or a helper it reaches, or a trigger handler), spans two objects. |
|
|
2318
|
-
| `TENANCY_QUEUE_PARTITION` / `TENANCY_QUEUE_MIXED_PLACEMENT` | A queue handler imports a partitioned feature or mixes database placements.
|
|
2930
|
+
| `TENANCY_QUEUE_PARTITION` / `TENANCY_QUEUE_MIXED_PLACEMENT` | A queue handler imports a partitioned feature without `placement: { partition }`, or mixes database placements. See [Partition jobs](#partition-jobs). |
|
|
2931
|
+
| `TENANCY_JOB_PLACEMENT` / `TENANCY_QUEUE_PARTITION_KEY` | A `placement` that is not a literal, names an undeclared kind or conflicts with `tenant: true`; a partition-job message literal without `partitionKey`. See [Partition jobs](#partition-jobs). |
|
|
2319
2932
|
| `TENANCY_QUEUE_TENANT_ID` / `TENANCY_QUEUE_RESERVED` | A platform action, queue handler or schedule builds a tenant-job message without `tenantId`, or a handler uses the reserved type `qb:backup`. |
|
|
2320
2933
|
| `TENANCY_NAMESPACE_DELETION` | See [Deleting the namespace](#deleting-the-namespace). |
|
|
2321
2934
|
| `TENANCY_JURISDICTION_CHANGED` / `TENANCY_JURISDICTION_UNKNOWN` | `tenancy.jurisdiction` differs from the deployed `wrangler.toml`'s `# quickback:tenancy.jurisdiction=` line, or `wrangler.toml` binds `QuickbackTenant` without that line. Add it with the jurisdiction the objects were created in. A build without `wrangler.toml` only warns. |
|
|
@@ -2323,7 +2936,7 @@ organization's object before you apply that migration.
|
|
|
2323
2936
|
| `TENANCY_TENANT_WORKER_UNKNOWN` | The existing `wrangler.toml` references `QuickbackTenant` in a form the build cannot resolve to an edge and tenant Worker. Rewrite it as plain `[[durable_objects.bindings]]` tables under a named edge table. |
|
|
2324
2937
|
| `TENANCY_TENANT_WORKER_CHANGED` | A deployed edge (per the existing `wrangler.toml`) would bind a different tenant Worker than it does now. See [Two Workers](#two-workers). |
|
|
2325
2938
|
| `TENANCY_ENVIRONMENT_WORKER` / `TENANCY_ENVIRONMENT_SHARED` / `TENANCY_ENVIRONMENT_BACKUP` | A named environment has no `tenantWorker.name`, shares a tenant Worker or backup bucket with another target, or names a tenant Worker like an edge or files Worker. A target that does not deploy as the project `name` reuses the single-target tenant Worker or bucket. A Worker takes a reserved `<name>-unselected`, `<name>-files-unselected` or `<name>-tenant-unselected` placeholder name. `backupBucketName` is missing while `tenancy.backup` is set, or set while it is not. See [Named environments](#named-environments). |
|
|
2326
|
-
| `TENANCY_PURGE_DO` / `
|
|
2939
|
+
| `TENANCY_PURGE_DO` / `TENANCY_FGA` | `tenancy.purge`, or a top-level `fga` block (declare it at `authz.fga`), together with `isolation: 'durable-object'`. |
|
|
2327
2940
|
| `TENANCY_FGA_SHARING` / `TENANCY_FGA_MEMBERSHIP` / `TENANCY_FGA_ACCESS_ARM` / `TENANCY_FGA_MIXED` | An FGA shape that would reach tuples from outside the organization object: sharing without `link` subjects, derived membership, an `fga` arm off a tenant table, `ctx.fga` off the organization object. See [FGA](#fga). |
|
|
2328
2941
|
|
|
2329
2942
|
|