@quickback-dev/cli 0.70.43 → 0.72.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +10 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +7 -1
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +6 -5
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +6 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -1
- package/dist/lib/access-manifest-diff.js +10 -0
- package/dist/lib/access-manifest-diff.js.map +1 -1
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +36 -0
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/api-client.d.ts +8 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/deployment-target.d.ts +13 -0
- package/dist/lib/deployment-target.d.ts.map +1 -1
- package/dist/lib/deployment-target.js +4 -0
- package/dist/lib/deployment-target.js.map +1 -1
- package/dist/lib/file-loader.d.ts +22 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +80 -18
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-writer.js +9 -0
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +10 -0
- package/dist/lib/harness.d.ts.map +1 -1
- package/dist/lib/harness.js +31 -0
- package/dist/lib/harness.js.map +1 -1
- package/dist/lib/migrations/executor.js +5 -1
- package/dist/lib/migrations/executor.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +23 -2
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts +30 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js +109 -0
- package/dist/lib/migrations/postprocessors/tenant-bundle.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +13 -1
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +33 -2
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +2 -2
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +3 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/wrangler-resources.d.ts +14 -1
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +29 -7
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/docs/api/actions.md +73 -2
- package/dist/skill/docs/api/batch-operations.md +2 -0
- package/dist/skill/docs/api/caching.md +5 -2
- package/dist/skill/docs/api/crud.md +13 -0
- package/dist/skill/docs/api/errors.md +111 -10
- package/dist/skill/docs/api/index.md +24 -0
- package/dist/skill/docs/api/openapi.md +8 -0
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/configure/agents.md +79 -2
- package/dist/skill/docs/configure/auth.md +10 -2
- package/dist/skill/docs/configure/bindings.md +55 -0
- package/dist/skill/docs/configure/cloudflare-access.md +191 -0
- package/dist/skill/docs/configure/domains.md +14 -1
- package/dist/skill/docs/configure/index.md +4 -2
- package/dist/skill/docs/configure/providers.md +2 -1
- package/dist/skill/docs/configure/tenancy.md +3 -0
- package/dist/skill/docs/configure/tenant-databases.md +2407 -0
- package/dist/skill/docs/define/access.md +33 -1
- package/dist/skill/docs/define/actions/defining.md +118 -1
- package/dist/skill/docs/define/actions/scoped-db.md +32 -8
- package/dist/skill/docs/define/areas.md +145 -2
- package/dist/skill/docs/define/diagnostics.md +160 -21
- package/dist/skill/docs/define/encryption.md +13 -2
- package/dist/skill/docs/define/fga.md +320 -42
- package/dist/skill/docs/define/firewall.md +4 -0
- package/dist/skill/docs/define/index.md +1 -0
- package/dist/skill/docs/define/read.md +39 -0
- package/dist/skill/docs/define/relationships.md +30 -12
- package/dist/skill/docs/define/schema.md +2 -0
- package/dist/skill/docs/define/scopes.md +393 -9
- package/dist/skill/docs/define/sealed-protocol.md +67 -12
- package/dist/skill/docs/define/transitions.md +4 -1
- package/dist/skill/docs/define/triggers.md +55 -1
- package/dist/skill/docs/platform/api-contract/index.md +4 -2
- package/dist/skill/docs/platform/auth/jwt-optimization.md +16 -1
- package/dist/skill/docs/platform/auth/using-auth.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +112 -3
- package/dist/skill/docs/platform/database/data-migrations.md +3 -1
- package/dist/skill/docs/platform/database/neon.md +10 -2
- package/dist/skill/docs/platform/queues/handlers.md +48 -16
- package/dist/skill/docs/platform/queues/using-queues.md +16 -0
- package/dist/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/dist/skill/docs/platform/realtime/index.md +9 -6
- package/dist/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/dist/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/dist/skill/docs/platform/schedules/index.md +1 -1
- package/dist/skill/docs/platform/storage/r2.md +10 -1
- package/dist/skill/docs/platform/storage/using-r2.md +42 -1
- package/dist/skill/docs/tooling/output.md +9 -2
- package/dist/skill/docs/ui/account/features/admin.md +5 -3
- package/dist/skill/docs/ui/account/hooks.md +9 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/package.json +7 -7
- package/src/skill/docs/api/actions.md +73 -2
- package/src/skill/docs/api/batch-operations.md +2 -0
- package/src/skill/docs/api/caching.md +5 -2
- package/src/skill/docs/api/crud.md +13 -0
- package/src/skill/docs/api/errors.md +111 -10
- package/src/skill/docs/api/index.md +24 -0
- package/src/skill/docs/api/openapi.md +8 -0
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/configure/agents.md +79 -2
- package/src/skill/docs/configure/auth.md +10 -2
- package/src/skill/docs/configure/bindings.md +55 -0
- package/src/skill/docs/configure/cloudflare-access.md +191 -0
- package/src/skill/docs/configure/domains.md +14 -1
- package/src/skill/docs/configure/index.md +4 -2
- package/src/skill/docs/configure/providers.md +2 -1
- package/src/skill/docs/configure/tenancy.md +3 -0
- package/src/skill/docs/configure/tenant-databases.md +2407 -0
- package/src/skill/docs/define/access.md +33 -1
- package/src/skill/docs/define/actions/defining.md +118 -1
- package/src/skill/docs/define/actions/scoped-db.md +32 -8
- package/src/skill/docs/define/areas.md +145 -2
- package/src/skill/docs/define/diagnostics.md +160 -21
- package/src/skill/docs/define/encryption.md +13 -2
- package/src/skill/docs/define/fga.md +320 -42
- package/src/skill/docs/define/firewall.md +4 -0
- package/src/skill/docs/define/index.md +1 -0
- package/src/skill/docs/define/read.md +39 -0
- package/src/skill/docs/define/relationships.md +30 -12
- package/src/skill/docs/define/schema.md +2 -0
- package/src/skill/docs/define/scopes.md +393 -9
- package/src/skill/docs/define/sealed-protocol.md +67 -12
- package/src/skill/docs/define/transitions.md +4 -1
- package/src/skill/docs/define/triggers.md +55 -1
- package/src/skill/docs/platform/api-contract/index.md +4 -2
- package/src/skill/docs/platform/auth/jwt-optimization.md +16 -1
- package/src/skill/docs/platform/auth/using-auth.md +1 -1
- package/src/skill/docs/platform/database/d1.md +112 -3
- package/src/skill/docs/platform/database/data-migrations.md +3 -1
- package/src/skill/docs/platform/database/neon.md +10 -2
- package/src/skill/docs/platform/queues/handlers.md +48 -16
- package/src/skill/docs/platform/queues/using-queues.md +16 -0
- package/src/skill/docs/platform/realtime/durable-objects.md +285 -17
- package/src/skill/docs/platform/realtime/index.md +9 -6
- package/src/skill/docs/platform/realtime/named-invalidations.md +3 -1
- package/src/skill/docs/platform/realtime/using-realtime.md +28 -3
- package/src/skill/docs/platform/schedules/index.md +1 -1
- package/src/skill/docs/platform/storage/r2.md +10 -1
- package/src/skill/docs/platform/storage/using-r2.md +42 -1
- package/src/skill/docs/tooling/output.md +9 -2
- package/src/skill/docs/ui/account/features/admin.md +5 -3
- package/src/skill/docs/ui/account/hooks.md +9 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/dist/codex/AGENTS.md +0 -290
- package/dist/commands/build.test.d.ts.map +0 -1
- package/dist/commands/codex.d.ts +0 -16
- package/dist/commands/codex.d.ts.map +0 -1
- package/dist/commands/codex.js +0 -159
- package/dist/commands/codex.js.map +0 -1
- package/dist/commands/compile.d.ts +0 -62
- package/dist/commands/compile.d.ts.map +0 -1
- package/dist/commands/compile.js +0 -830
- package/dist/commands/compile.js.map +0 -1
- package/dist/commands/compile.test.d.ts.map +0 -1
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.d.ts.map +0 -1
- package/dist/commands/init.js +0 -405
- package/dist/commands/init.js.map +0 -1
- package/dist/commands/migrate.test.d.ts.map +0 -1
- package/dist/commands/migrations.test.d.ts.map +0 -1
- package/dist/commands/push.test.d.ts.map +0 -1
- package/dist/commands/schema.test.d.ts.map +0 -1
- package/dist/docs/content.d.ts +0 -7
- package/dist/docs/content.d.ts.map +0 -1
- package/dist/docs/content.js +0 -672
- package/dist/docs/content.js.map +0 -1
- package/dist/docs/index.test.d.ts.map +0 -1
- package/dist/lib/action-harvest.test.d.ts.map +0 -1
- package/dist/lib/api-client.test.d.ts.map +0 -1
- package/dist/lib/artifact-routing.test.d.ts.map +0 -1
- package/dist/lib/auth.test.d.ts.map +0 -1
- package/dist/lib/compile-next-steps.test.d.ts.map +0 -1
- package/dist/lib/compiler-floor.test.d.ts.map +0 -1
- package/dist/lib/config-id-splice.test.d.ts.map +0 -1
- package/dist/lib/config-sync.test.d.ts.map +0 -1
- package/dist/lib/copy-public-assets.test.d.ts.map +0 -1
- package/dist/lib/copy-source-apps.test.d.ts.map +0 -1
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +0 -1
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +0 -1
- package/dist/lib/file-loader.test.d.ts.map +0 -1
- package/dist/lib/file-writer.test.d.ts.map +0 -1
- package/dist/lib/helpers.d.ts +0 -39
- package/dist/lib/helpers.d.ts.map +0 -1
- package/dist/lib/helpers.js +0 -299
- package/dist/lib/helpers.js.map +0 -1
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +0 -1
- package/dist/lib/migrations/drizzle.test.d.ts.map +0 -1
- package/dist/lib/migrations/executor.test.d.ts.map +0 -1
- package/dist/lib/migrations/inventory.test.d.ts.map +0 -1
- package/dist/lib/migrations/lock.test.d.ts.map +0 -1
- package/dist/lib/migrations/paths.test.d.ts.map +0 -1
- package/dist/lib/migrations/plan.test.d.ts.map +0 -1
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +0 -1
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +0 -1
- package/dist/lib/migrations/staging.test.d.ts.map +0 -1
- package/dist/lib/neon-canary.test.d.ts.map +0 -1
- package/dist/lib/neon-target.test.d.ts.map +0 -1
- package/dist/lib/neon.test.d.ts.map +0 -1
- package/dist/lib/prepare-output.test.d.ts.map +0 -1
- package/dist/lib/prepare-state-output.test.d.ts.map +0 -1
- package/dist/lib/schema-sync/index.test.d.ts.map +0 -1
- package/dist/lib/shell.test.d.ts.map +0 -1
- package/dist/lib/sweep-stale.d.ts +0 -25
- package/dist/lib/sweep-stale.d.ts.map +0 -1
- package/dist/lib/sweep-stale.js +0 -179
- package/dist/lib/sweep-stale.js.map +0 -1
- package/dist/lib/sweep-stale.test.d.ts.map +0 -1
- package/dist/lib/wrangler-resources.test.d.ts.map +0 -1
|
@@ -0,0 +1,2407 @@
|
|
|
1
|
+
# Database per Tenant
|
|
2
|
+
|
|
3
|
+
Set `tenancy.isolation: 'durable-object'` to give every organization its own
|
|
4
|
+
SQLite database. Organization-scoped tables move out of the shared features D1
|
|
5
|
+
into one Durable Object per organization. Each tenant's reads and writes land
|
|
6
|
+
on its own object, not on one central database.
|
|
7
|
+
|
|
8
|
+
```ts title="quickback/quickback.config.ts"
|
|
9
|
+
import { defineConfig, defineRuntime, defineDatabase, defineAuth } from "@quickback/compiler";
|
|
10
|
+
|
|
11
|
+
export default defineConfig({
|
|
12
|
+
name: "events-app",
|
|
13
|
+
template: "hono",
|
|
14
|
+
features: { organizations: true },
|
|
15
|
+
providers: {
|
|
16
|
+
runtime: defineRuntime("cloudflare"),
|
|
17
|
+
database: defineDatabase("cloudflare-d1"),
|
|
18
|
+
auth: defineAuth("better-auth", { plugins: { organization: true } }),
|
|
19
|
+
},
|
|
20
|
+
tenancy: {
|
|
21
|
+
isolation: "durable-object",
|
|
22
|
+
key: "organization",
|
|
23
|
+
jurisdiction: "eu", // optional: pin every tenant object to a jurisdiction
|
|
24
|
+
backup: { bucket: "TENANT_BACKUPS", every: "6h", retainDays: 90 },
|
|
25
|
+
lookups: { inviteCode: { table: "invites", column: "code", hash: true } },
|
|
26
|
+
},
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
| Option | Default | Effect |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| `isolation` | `'shared'` | `'shared'`: one features D1 with `organization_id` on every row. `'durable-object'`: one SQLite Durable Object per organization. |
|
|
33
|
+
| `key` | `'organization'` | The tenant key. Only the active organization is supported. |
|
|
34
|
+
| `jurisdiction` | none | `'eu'` or `'fedramp'`. Every tenant object is created in that jurisdiction. Fixed once deployed: changing it fails the build (`TENANCY_JURISDICTION_CHANGED`), because the new value addresses a different, empty namespace. |
|
|
35
|
+
| `backup` | none | Alarm-driven dumps of every tenant object to R2: `bucket` (the tenant Worker's R2 binding, default `TENANT_BACKUPS`), `bucketName` (default `<name>-tenant-backups`), `every` (`30m` / `6h` / `1d`, at least 15 minutes, default `6h`; or `'off'`: no scheduled dumps — point-in-time recovery is the routine backup, and the bucket only serves operator backups, dump restores and moves), `retainDays` (default 30). See [Backups and restore](#backups-and-restore). |
|
|
36
|
+
| `lookups` | none | Platform lookup indexes: `name → { table, column, hash? }` on a tenant table. `hash: true` stores a keyed hash, never the value (credentials). See [Lookup indexes](#lookup-indexes). |
|
|
37
|
+
| `outbox` | `{ receipts: { retainDays: 7, maxRows: 50000 } }` | Delivery receipts: one row per outbox entry the edge delivered or failed, kept `retainDays` and at most `maxRows` per object. `receipts: false` keeps none. See [Outbox delivery](#outbox-delivery). |
|
|
38
|
+
| `allowNamespaceDeletion` | `false` | Permit deleting the tenant class. See [Deleting the namespace](#deleting-the-namespace). |
|
|
39
|
+
| `vars` | none | Non-secret Worker vars tenant code may read as `env.<NAME>`. See [Vars in tenant code](#vars-in-tenant-code). |
|
|
40
|
+
| `operator.http` | unset (every route, with a warning) | `false`: no generated operator routes at all; `{ allow: [...] }`: only the named routes. See [Operator routes](#operator-routes). |
|
|
41
|
+
| `operator.purge` | deprecated — use `operator.http` | `true`, or `false` when your code imports `purgeTenant`: mount the raw `POST /tenants/:id/purge`. Refused beside `operator.http`. |
|
|
42
|
+
|
|
43
|
+
Nothing changes for projects that leave `isolation` unset.
|
|
44
|
+
|
|
45
|
+
## Two Workers
|
|
46
|
+
|
|
47
|
+
The build emits two Workers from one project.
|
|
48
|
+
|
|
49
|
+
| Worker | Config | Holds |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| Edge | `wrangler.toml`, `src/index.ts` | Better Auth, routing, the features D1 (platform tables + `tenant_registry`), the CMS and Account SPAs |
|
|
52
|
+
| Tenant | `wrangler.tenant.jsonc`, `src/tenant/index.ts` | `QuickbackTenant`, a SQLite-backed Durable Object running the tenant routes. No Better Auth, no D1, no auth secrets. |
|
|
53
|
+
|
|
54
|
+
Both Workers use the project's `providers.runtime.config.compatibilityDate` (default `2025-01-01`); below `2025-11-17` the tenant Worker also gets the `enable_ctx_exports` flag. Set the newest date your installed wrangler's `workerd` supports.
|
|
55
|
+
|
|
56
|
+
The edge authenticates the request, resolves the tenant (the active
|
|
57
|
+
organization, or a [lookup](#lookup-indexes) for scope tokens), and calls
|
|
58
|
+
`TENANT.getByName(organizationId).handle(request, principal, version)` over
|
|
59
|
+
RPC. The object runs the generated CRUD, batch and action handlers on a
|
|
60
|
+
db built over its own `ctx.storage` (`drizzle-orm/durable-sqlite`). The firewall
|
|
61
|
+
still applies inside the object, and the object refuses a principal for another
|
|
62
|
+
organization (`403 TENANT_MISMATCH`).
|
|
63
|
+
|
|
64
|
+
A tenant table with no routes left (`routes: false` on read, create, update and
|
|
65
|
+
delete) gets no routes module, no mount on either Worker and no OpenAPI path
|
|
66
|
+
items: its paths answer `404` to every caller, signed in or not. Server code
|
|
67
|
+
still reads and writes the table.
|
|
68
|
+
|
|
69
|
+
The tenant Worker declares its class with `exports` (no `[[migrations]]`) and
|
|
70
|
+
carries no binding to itself. The edge binds it with `script_name = "<name>-tenant"`. Deploy the tenant Worker
|
|
71
|
+
first: `npm run deploy` runs `npm run deploy:tenant` before the edge deploy.
|
|
72
|
+
When `providers.runtime.config.accountId` is set, the tenant Worker carries the
|
|
73
|
+
same `account_id` as the edge, so it cannot deploy into a different account.
|
|
74
|
+
|
|
75
|
+
The build refuses to change which tenant Worker a deployed edge binds
|
|
76
|
+
(`TENANCY_TENANT_WORKER_CHANGED`). It reads every `QuickbackTenant` binding in
|
|
77
|
+
the existing `wrangler.toml` (top level and `[env.*]`, in any key order or
|
|
78
|
+
quoting) and compares it with the new config. If a binding cannot be read —
|
|
79
|
+
an inline table, a binding without `script_name`, an edge table with no
|
|
80
|
+
`name`, or a table declared twice — the build fails with
|
|
81
|
+
`TENANCY_TENANT_WORKER_UNKNOWN` instead of skipping the check. Two cases are refused:
|
|
82
|
+
|
|
83
|
+
- a deployed edge script would bind a different tenant script;
|
|
84
|
+
- a tenant script bound today is no longer bound by any target. This covers
|
|
85
|
+
renaming a target's edge and tenant Worker together, and dropping a target.
|
|
86
|
+
|
|
87
|
+
A different tenant script name addresses a new, empty namespace, so every
|
|
88
|
+
tenant would look wiped. To move on purpose, migrate the tenants first, then
|
|
89
|
+
remove the old `TENANT` binding from `wrangler.toml` and rebuild. A build
|
|
90
|
+
without `wrangler.toml` cannot run this check, and warns.
|
|
91
|
+
|
|
92
|
+
### Named environments
|
|
93
|
+
|
|
94
|
+
With [named environments](/platform/database/d1#named-cloudflare-deployment-environments), every
|
|
95
|
+
target deploys its own pair: its edge Worker (`environments.<key>.name`) and
|
|
96
|
+
its own tenant Worker (`environments.<key>.tenantWorker.name`). The tenant
|
|
97
|
+
Worker's script name owns the `QuickbackTenant` namespace, which holds every
|
|
98
|
+
organization's database. Like `name`, it is required on every target and never
|
|
99
|
+
derived.
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
environments: {
|
|
103
|
+
dev: {
|
|
104
|
+
name: 'events-app-dev',
|
|
105
|
+
tenantWorker: { name: 'events-app-tenant-dev', backupBucketName: 'events-app-tenant-backups-dev' },
|
|
106
|
+
/* worker, bindings, domains … */
|
|
107
|
+
},
|
|
108
|
+
production: {
|
|
109
|
+
name: 'events-app',
|
|
110
|
+
tenantWorker: { name: 'events-app-tenant', backupBucketName: 'events-app-tenant-backups' },
|
|
111
|
+
/* … */
|
|
112
|
+
},
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
All targets run the same bundle. The build emits:
|
|
117
|
+
|
|
118
|
+
- **`wrangler.toml`**: one `[[env.<key>.durable_objects.bindings]]` per
|
|
119
|
+
target, with `script_name` set to that target's tenant Worker. Durable Object
|
|
120
|
+
bindings do not inherit, and the top level emits no tenant binding, so no
|
|
121
|
+
target can reach another target's tenant databases.
|
|
122
|
+
- **`wrangler.tenant.jsonc`**: no top-level `main` or `exports`, so a bare
|
|
123
|
+
`wrangler deploy -c wrangler.tenant.jsonc` fails with *Missing entry-point*.
|
|
124
|
+
The top-level `name` is an inert placeholder, `<name>-tenant-unselected`.
|
|
125
|
+
A positional entry (`wrangler deploy -c wrangler.tenant.jsonc
|
|
126
|
+
src/tenant/index.ts`) deploys an unbound Worker under that name. Without the
|
|
127
|
+
placeholder, Wrangler would take the `package.json` name (the production
|
|
128
|
+
edge) and deploy tenant code over it. No target may use the placeholder. One `env.<key>` block per
|
|
129
|
+
target carries `main`, `exports`, that target's `account_id` (its `accountId`, or
|
|
130
|
+
`providers.runtime.config.accountId`), its `TENANT_BACKUPS` bucket
|
|
131
|
+
(`backupBucketName`), and the rate-limit namespaces from its own edge stanza.
|
|
132
|
+
- **`package.json`**: `deploy:<key>:tenant`. Each `deploy:<key>` runs it
|
|
133
|
+
before the edge deploy. `dev:tenant` runs the `dev` target. There is no bare
|
|
134
|
+
`deploy:tenant`.
|
|
135
|
+
|
|
136
|
+
The tenant registry, lookups and outbox live in each target's own features D1
|
|
137
|
+
(`worker.bindings.d1.features`). Jobs ride each target's own queues
|
|
138
|
+
(`worker.bindings.queues`).
|
|
139
|
+
|
|
140
|
+
The build refuses:
|
|
141
|
+
|
|
142
|
+
- a target without `tenantWorker.name`;
|
|
143
|
+
- two targets with the same tenant Worker;
|
|
144
|
+
- a backup bucket that is another target's bucket, or one of the same target's
|
|
145
|
+
`worker.bindings.r2Buckets` (the same per-target R2 uniqueness rule as every
|
|
146
|
+
other bucket);
|
|
147
|
+
- a tenant Worker named like an edge or files Worker, or like the top-level
|
|
148
|
+
project `name`;
|
|
149
|
+
- `backupBucketName` missing while `tenancy.backup` is set, or set while it
|
|
150
|
+
is not.
|
|
151
|
+
|
|
152
|
+
Only the target that deploys as the project `name` may reuse the single-target
|
|
153
|
+
`<name>-tenant` script and `<name>-tenant-backups` bucket. Set them on that
|
|
154
|
+
target when you adopt environments in a deployed project, so it keeps its
|
|
155
|
+
tenant databases. The continuity check above refuses any other name for it.
|
|
156
|
+
A `tenantWorker` is also refused when `tenancy.isolation` is not
|
|
157
|
+
`'durable-object'`.
|
|
158
|
+
|
|
159
|
+
The sharing refusals apply even when two targets deploy into different
|
|
160
|
+
Cloudflare accounts (`accountId`), where the same names would not collide.
|
|
161
|
+
This is deliberately conservative. Per-client accounts (one target per client)
|
|
162
|
+
may relax it later.
|
|
163
|
+
|
|
164
|
+
The edge↔tenant contract is versioned (`TENANT_RPC_VERSION` in
|
|
165
|
+
`src/tenant/contract.ts`, the same constant in both Workers). A tenant Worker
|
|
166
|
+
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 13
|
|
168
|
+
(version 3 put dump restore under the shared restore fence and added the
|
|
169
|
+
authorization epoch; version 4 adds tenant commands and epoch-carrying restore
|
|
170
|
+
permits; version 5 adds `callJob()` for [result jobs](#result-jobs); version 6
|
|
171
|
+
adds `queue` outbox entries for [platform queues](#platform-queues); version 7
|
|
172
|
+
the bounded backup read; version 8 the `callJob` epoch fence; version 9 the
|
|
173
|
+
backup-fenced purge; version 10 room commit permits; version 11
|
|
174
|
+
[leased outbox delivery](#outbox-delivery); version 12 `revoke` outbox entries
|
|
175
|
+
for [scope revocation](#scope-revocation); version 13 `armSchedules()` for
|
|
176
|
+
[tenant schedules](#tenant-schedules)). An edge below version 11 gets no
|
|
177
|
+
inline claims and keeps using `takeOutbox` / `ackOutbox`. An edge below
|
|
178
|
+
version 12 is never handed a `revoke` entry, by a claim or by `takeOutbox`:
|
|
179
|
+
those entries wait for the new edge, so no revocation is settled unapplied. It still
|
|
180
|
+
accepts version-2 to version-5 edges: no method those edges
|
|
181
|
+
call changed meaning, so deploying the tenant Worker first opens no 503 window.
|
|
182
|
+
An edge older than version 6 is handed no outbox entries from the first
|
|
183
|
+
`queue` entry on, so it never acknowledges a message it would not send; those
|
|
184
|
+
entries wait, in order, for the new edge,
|
|
185
|
+
and a version-2 edge's dump restore fails closed until the edge is deployed.
|
|
186
|
+
A percentage (gradual) deploy of the tenant Worker is safe from version 3
|
|
187
|
+
to 4. While it runs, some tenant objects and their control objects use the old
|
|
188
|
+
code and some the new, and both directions work. A control object answers an
|
|
189
|
+
older holder's permit request with the plain token string that holder expects,
|
|
190
|
+
and the holder releases it as before. A version-4 holder whose control object
|
|
191
|
+
still runs version 3 gets a version-mismatch refusal before anything is
|
|
192
|
+
written, then retries at `TENANT_RPC_MIN_VERSION` with the old protocol. Its
|
|
193
|
+
permit then carries no authorization epoch, so `command()` answers
|
|
194
|
+
`unavailable` / `TENANT_RPC_VERSION_MISMATCH` until that control object is
|
|
195
|
+
upgraded. `handle()`, jobs and alarms keep serving, and the restore fence is
|
|
196
|
+
the same permit table either way. `command()` itself accepts only version 4
|
|
197
|
+
(`TENANT_PERMIT_VERSION`). Upgrading from version 1 requires both Workers to
|
|
198
|
+
be deployed. Old edge
|
|
199
|
+
calls fail closed while the tenant Worker is upgraded first.
|
|
200
|
+
|
|
201
|
+
### Tenant commands
|
|
202
|
+
|
|
203
|
+
Besides `handle()`, the object has one more entry point for trusted edge code:
|
|
204
|
+
`command(version, request)`. It runs a **compiler-owned** program inside the
|
|
205
|
+
object. Callers pick a command by name and pass its fields. They never send
|
|
206
|
+
SQL, callbacks, method names or credentials, and app code cannot add commands.
|
|
207
|
+
Every name is reserved under `qb.*`.
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
import { tenantCommand } from './lib/tenants';
|
|
211
|
+
|
|
212
|
+
const res = await tenantCommand(env, organizationId, { name: 'qb.epoch' });
|
|
213
|
+
if (res.status === 'ok') res.reply.authEpoch; // { tenantId, authEpoch, lifecycle: { state, schemaVersion } }
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
| Command | Mode | Reply |
|
|
217
|
+
|---|---|---|
|
|
218
|
+
| `qb.epoch` | read | `{ tenantId, authEpoch, lifecycle: { state: 'active', schemaVersion } }`: the [authorization epoch](#authorization-epoch) |
|
|
219
|
+
| `qb.admitScope` | read | Registered only when a scope kind is [tenant-backed](#tenant-admission-qbadmitscope). `{ kind, instanceId, tenantId, authEpoch, roles, subjectId, provingTable, subKeys }`, or `denied` with `SCOPE_EPOCH`, `SCOPE_NOT_FOUND`, `SCOPE_NO_ROLE`, `SCOPE_WRONG_SUBJECT` or `SCOPE_AMBIGUOUS` |
|
|
220
|
+
| `qb.scopeGrantRead` | read | Registered only when a tenant-backed kind declares [`oauth.serverGrant`](#server-issued-grants). `{ kind, instanceId, subjectId, tenantId, authEpoch, linkedUserId, roles, subject, instance }` (identity and instance projections as JSON), or `denied` with `SCOPE_NOT_FOUND` or `SCOPE_GRANT_SUBJECT_DENIED` |
|
|
221
|
+
| `qb.scopeGrantLink` | write | Same registration. `{ kind, instanceId, subjectId, tenantId, authEpoch, outcome: 'linked' \| 'unchanged' }`, or `denied` with `SCOPE_EPOCH`, `SCOPE_NOT_FOUND`, `SCOPE_GRANT_SUBJECT_DENIED` or `SCOPE_GRANT_LINK_CONFLICT` |
|
|
222
|
+
| `qb.roomAccess` | read | Registered only when a resource-backed realtime room is on a tenant table ([Tenant rooms](/platform/realtime/durable-objects#tenant-rooms)). `{ room }` when the room's row passes the table firewall for a member of this organization, else `denied` with `ROOM_ACCESS_DENIED` |
|
|
223
|
+
|
|
224
|
+
`tenantCommand` first reads the organization's `tenant_registry` row, and wakes
|
|
225
|
+
the object only when the registry vouches for it:
|
|
226
|
+
|
|
227
|
+
| Registry row | Result |
|
|
228
|
+
|---|---|
|
|
229
|
+
| None: the platform has never served the tenant, or its first report is still in flight | `unavailable` / `TENANT_NOT_PROVISIONED` (retryable). The object is not woken, so no empty tenant database is created. |
|
|
230
|
+
| `purged` | `unavailable` / `TENANT_PURGED`, without waking the object |
|
|
231
|
+
| Written under another `tenancy.jurisdiction` | `unavailable` / `TENANT_JURISDICTION_MISMATCH` |
|
|
232
|
+
| Registry read fails | `unavailable` / `TENANT_UNAVAILABLE` |
|
|
233
|
+
| Any other state | The object decides (archived, migration and restore are checked there) |
|
|
234
|
+
|
|
235
|
+
A tenant gets its row when it first serves a request or a job, or when an
|
|
236
|
+
operator provisions it (`POST /tenants/:id/provision`, `provisionTenantTarget`
|
|
237
|
+
in `src/lib/tenants.ts`: verified against Better Auth's organization table
|
|
238
|
+
first). Until one of those, a new organization's commands answer
|
|
239
|
+
`TENANT_NOT_PROVISIONED`. `denied` is kept for definitive refusals made by a command.
|
|
240
|
+
Pass only a server-verified organization id, never one taken from the request.
|
|
241
|
+
The HTTP forwarder (`tenantForward`) does not read the registry: it routes the
|
|
242
|
+
authenticated principal's organization, so it adds no D1 read per request.
|
|
243
|
+
|
|
244
|
+
The object then checks each request in this order:
|
|
245
|
+
|
|
246
|
+
1. The RPC version. `command()` accepts only version 4 or later
|
|
247
|
+
(`TENANT_PERMIT_VERSION`). Then `TENANT_COMMAND_FINGERPRINT`, a hash of the
|
|
248
|
+
command registry that both Workers carry in `src/tenant/contract.ts`. It is
|
|
249
|
+
checked before the name, so a split deploy reports itself as one. Then the
|
|
250
|
+
command name and the exact request shape: unknown fields are refused, and
|
|
251
|
+
string fields are capped at 512 characters. Then the target: the request's
|
|
252
|
+
`tenantId` must be this object's name. Partition objects and control objects
|
|
253
|
+
serve no commands. Each failure throws (`TENANT_RPC_VERSION_MISMATCH`,
|
|
254
|
+
`TENANT_COMMAND_FINGERPRINT_MISMATCH`, `TENANT_COMMAND_INVALID`) before the
|
|
255
|
+
command reads any tenant data. As with every RPC, waking the object still
|
|
256
|
+
runs its own [migrate on wake](#migrations) first.
|
|
257
|
+
2. The [restore permit](#restore-quarantine). The permit also carries the
|
|
258
|
+
authorization epoch, and no restore can begin while it is held. A pending
|
|
259
|
+
restore answers `unavailable` / `TENANT_RESTORE_PENDING`.
|
|
260
|
+
3. Archived, purged and unmigrated objects answer `unavailable`
|
|
261
|
+
(`TENANT_ARCHIVED`, `TENANT_PURGED`, `TENANT_MIGRATION_FAILED`).
|
|
262
|
+
4. The body runs in one `ctx.storage.transactionSync`, with no `await`. A write
|
|
263
|
+
command marks the object dirty inside that transaction, so the next backup
|
|
264
|
+
includes it, and the backup is scheduled after the transaction commits.
|
|
265
|
+
|
|
266
|
+
`tenantCommand(env, tenantId, request)` returns
|
|
267
|
+
`{ status: 'ok', reply } | { status: 'denied', code } | { status: 'unavailable', code }`.
|
|
268
|
+
It checks the reply against the command's schema; a reply of the wrong shape
|
|
269
|
+
becomes `unavailable` / `TENANT_COMMAND_REPLY_INVALID`. Read commands are
|
|
270
|
+
retried once after an object reset or a retryable RPC error. Write commands are
|
|
271
|
+
sent once, and overloaded objects are never retried. Failures carry codes only:
|
|
272
|
+
`TENANT_UNAVAILABLE`, `TENANT_OVERLOADED`, `TENANT_DEPTH_EXCEEDED`,
|
|
273
|
+
`TENANT_RESTORE_PENDING`, the registry codes above, or one of the refusal codes above. A version or
|
|
274
|
+
fingerprint mismatch is `unavailable`, not `denied`: it is deploy skew, not a
|
|
275
|
+
policy decision. For a write command, `unavailable` means the outcome is
|
|
276
|
+
unknown: the write may have committed before the failure. Logs record the
|
|
277
|
+
command name and code, never the request or the error text. A malformed (or
|
|
278
|
+
`null`) request, an unknown command, or an organization id that is reserved, contains
|
|
279
|
+
`:` or is longer than 512 characters throws.
|
|
280
|
+
|
|
281
|
+
Commands do not carry the wake report or the outbox signal that `handle()`
|
|
282
|
+
responses do. A command write that queues outbox entries (lookup, audit,
|
|
283
|
+
realtime, jobs) is applied on the object's next drain: the next proxied request
|
|
284
|
+
that reports a non-empty outbox, the object's next alarm (which asks the edge to
|
|
285
|
+
drain it), `syncTenants(env)`, or `drainTenantOutbox`.
|
|
286
|
+
|
|
287
|
+
## Placement
|
|
288
|
+
|
|
289
|
+
The firewall decides where each table lives. A table with an organization arm
|
|
290
|
+
**anywhere** in its firewall is a **tenant** table: at the top level
|
|
291
|
+
(`q.scope("organization")`), inside `all:`, inside `any:`, or `optional`. So
|
|
292
|
+
"org staff OR the attendee of one event" is a tenant table too. An `exception`
|
|
293
|
+
firewall never is. Every other table is a **platform** table, served by the
|
|
294
|
+
edge from the features D1. Every compile prints the resolved table:
|
|
295
|
+
|
|
296
|
+
```text
|
|
297
|
+
[quickback] tenancy: durable-object — table placement
|
|
298
|
+
table placement why
|
|
299
|
+
attendees tenant organization arm (any:)
|
|
300
|
+
notes platform no organization firewall
|
|
301
|
+
projects tenant organization firewall
|
|
302
|
+
tasks tenant organization firewall
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
### Tenant ownership
|
|
306
|
+
|
|
307
|
+
Inside the object, a tenant table's effective firewall is the authored one
|
|
308
|
+
behind a **tenant pin**:
|
|
309
|
+
|
|
310
|
+
```text
|
|
311
|
+
organizationId = ctx.tenantId AND (<the firewall you wrote>)
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
`ctx.tenantId` is the organization the object serves. The object sets it from
|
|
315
|
+
its own name on every request and job, overwriting whatever the caller sent;
|
|
316
|
+
the edge strips it before forwarding. Three things follow:
|
|
317
|
+
|
|
318
|
+
- **Reads.** Every read is pinned to the object's organization, including
|
|
319
|
+
`skipTenantScopes` relationship probes and the sysadmin escape. A row
|
|
320
|
+
naming another organization — a bad copy or restore — is invisible to
|
|
321
|
+
everyone.
|
|
322
|
+
- **Writes.** Every insert stamps `organizationId` from `ctx.tenantId`: CRUD
|
|
323
|
+
create, changesets, upserts, batch and the action `db`. An attendee with no
|
|
324
|
+
active organization creates rows in the right tenant.
|
|
325
|
+
- **Who sees what is still the authored firewall.** `any: [{ field:
|
|
326
|
+
'organizationId', equals: 'ctx.activeOrgId' }, { field: 'eventId', equals:
|
|
327
|
+
'ctx.scope.event' }]` lowers to *tenant AND (org member OR attendee of this
|
|
328
|
+
event)*. The org arm means org membership. A relationship or scope caller
|
|
329
|
+
never gets `ctx.activeOrgId` from its relationship row, so it reads its own
|
|
330
|
+
event's rows, never the organization's. An org-only table is for members
|
|
331
|
+
only: a non-member's list or create gets `403 ORG_REQUIRED`, and a read by
|
|
332
|
+
id finds nothing. The pin itself never satisfies that check — creates on a
|
|
333
|
+
members-only table still need the caller's own `ctx.activeOrgId`, while an
|
|
334
|
+
org-OR-scope table's creates are bounded by the
|
|
335
|
+
[firewall-on-write check](/define/firewall#firewall-on-write).
|
|
336
|
+
|
|
337
|
+
`ctx.tenantId` is compiler-owned: the build adds the pin for you, and a
|
|
338
|
+
firewall that names `ctx.tenantId` itself is a compile error, in either
|
|
339
|
+
isolation mode.
|
|
340
|
+
|
|
341
|
+
A tenant object holds one organization, pinned through one column. A firewall
|
|
342
|
+
whose org arms bind two different organization columns (a buyer and a seller
|
|
343
|
+
org on one row) fails with `TENANCY_ORG_COLUMNS`. An `any: [org, owner]` table
|
|
344
|
+
that moves into tenant objects prints a warning: each request reaches one
|
|
345
|
+
object, so an owner without an active organization no longer reaches their
|
|
346
|
+
rows across organizations.
|
|
347
|
+
|
|
348
|
+
The pin does not change the edge↔tenant contract, so `TENANT_RPC_VERSION`
|
|
349
|
+
stays the same. The pin is compiled into the tenant Worker's own code, the
|
|
350
|
+
tenant object sets `ctx.tenantId` itself, and the edge strips any forwarded
|
|
351
|
+
value. A mixed rollout is therefore safe in both directions: an older edge
|
|
352
|
+
cannot supply a tenant, and an older tenant Worker never reads one.
|
|
353
|
+
|
|
354
|
+
### Placement changes on deployed tables
|
|
355
|
+
|
|
356
|
+
Once a project runs with `isolation: 'durable-object'`, its features D1 holds
|
|
357
|
+
only platform tables. So a table that is in the deployed features D1 (the
|
|
358
|
+
`quickback/drizzle/features` snapshot) and that the firewall places in tenant
|
|
359
|
+
objects is moving — a shared project switching to `'durable-object'`, or an
|
|
360
|
+
`any:` / optional organization arm that the old rule placed on the platform.
|
|
361
|
+
Without a declared placement it fails the build with
|
|
362
|
+
`TENANCY_PLACEMENT_MOVED`: deploying would leave
|
|
363
|
+
its rows in D1 while each tenant object serves an empty table. Declare
|
|
364
|
+
`placement: 'tenant'` once its rows are copied into each organization's object,
|
|
365
|
+
or `placement: { platform: true, crossTenant: true }` to keep it where it is.
|
|
366
|
+
|
|
367
|
+
`quickback build` sends the deployed table list as
|
|
368
|
+
`migration.priorState.existingFeaturesTables` (an older CLI does not). A build
|
|
369
|
+
with no deployed-schema facts at all — no `existingFeaturesTables` and no
|
|
370
|
+
features history, or a latest snapshot that does not parse — cannot tell, so every table whose placement derives
|
|
371
|
+
`tenant` only from an `any:` / optional organization arm fails with
|
|
372
|
+
`TENANCY_PLACEMENT_UNCONFIRMED` until it declares its placement (or the build
|
|
373
|
+
runs with a current CLI). A project with no migration history at all is
|
|
374
|
+
greenfield: the CLI sends an empty list, and a raw-files validate compile
|
|
375
|
+
treats missing history the same way.
|
|
376
|
+
|
|
377
|
+
Override it per table with `placement`. An organization-scoped table kept on
|
|
378
|
+
the platform must say so, because every tenant's rows then share one database:
|
|
379
|
+
|
|
380
|
+
{/* doc-compile: skip — fragment of a feature() resource config */}
|
|
381
|
+
```ts
|
|
382
|
+
placement: { platform: true, crossTenant: true },
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
All features sharing a partition kind must use the same key column.
|
|
386
|
+
All tables in one feature share a placement, because they share one schema
|
|
387
|
+
file and one route file. To shard a high-volume feature further, see
|
|
388
|
+
[Partitions](#partitions).
|
|
389
|
+
|
|
390
|
+
Every compile warns when a tenant table's `organizationId` or a foreign-key
|
|
391
|
+
column has no index: each request filters, and each FK check reads, on it.
|
|
392
|
+
|
|
393
|
+
### Admission tables stay on the platform
|
|
394
|
+
|
|
395
|
+
Only a [tenant-backed scope kind](#tenant-backed-scope-kinds), its
|
|
396
|
+
[tenant namespaces](#tenant-namespaces) and its tickets admit inside tenant
|
|
397
|
+
objects. Every other admission and request-time authorization path runs on the
|
|
398
|
+
edge Worker and reads its tables from the platform D1. If a tenant object held
|
|
399
|
+
one of those tables, the D1 copy would be missing. Or, during a migration, it
|
|
400
|
+
would be a stale copy whose rows keep admitting subjects the tenant has
|
|
401
|
+
already revoked. So the build fails with `TENANCY_ADMISSION_DEPENDENCY` when
|
|
402
|
+
any of them reads a tenant or partition table. A scope kind that reads a
|
|
403
|
+
tenant table but can't be tenant-backed fails with the planner's own codes
|
|
404
|
+
instead (see [Which kinds can be tenant-backed](#which-kinds-can-be-tenant-backed)),
|
|
405
|
+
and a namespace with `TENANCY_NAMESPACE_*`:
|
|
406
|
+
|
|
407
|
+
| Surface | Tables checked | Paths named in the error |
|
|
408
|
+
|---|---|---|
|
|
409
|
+
| `authz.scopes.<kind>` | each role's relationship tables (`from` and any `hops`), each role's `self.table`, and the instance table | `POST /scope/v1/enter` (when a role is `subject: 'user' \| 'both'`), `ctx.mintScope` (when a role is `'supplied' \| 'both'`), instance-bound OAuth (authorize, code exchange, refresh, `issueScopeGrant`, bound namespace and ws-ticket checks), the `ctx.self` recheck on every action route, and the scope refresh / `mintScope` of each namespace using the kind's relationships |
|
|
410
|
+
| `authz.namespaces.<name>` | relationship lanes' tables and the `loads` table | namespace gate and hydration |
|
|
411
|
+
| `realtime.wsTicket` | `scopeTable`, the tables behind `role` / `access.authzRole`, and the `namespace` lanes | ws-ticket mint |
|
|
412
|
+
| A platform feature | every relationship its CRUD, read, view, masking and action `access`, and its `firewall` arms, resolve: `authz.roles` relationship roles, `authz.rules`, `authz.permissions` (including `arrows` `from` / `to`) and direct `via` arms, with `hops` and `loads` | request-time authorization |
|
|
413
|
+
| A platform action with `anchor` | the relationship's tables and its `reach` tables | anchored transaction |
|
|
414
|
+
| A platform action's `refs` and `operator` | each ref's `table`, each `ownedVia.junction`, and `operator.target.table` | loaded and firewalled before `execute` |
|
|
415
|
+
| A platform table's derived JSON keys | each `derivedFrom.table` | CRUD reads and action `requires:` |
|
|
416
|
+
| A live view (`defineView`) | `root` and every project-table `include` | the view materializer (`GET /views/...`, ws-ticket view lane) |
|
|
417
|
+
|
|
418
|
+
The error names the surface, the paths that depend on it, and each tenant
|
|
419
|
+
table with its placement. A scope kind whose instance table is ambiguous also
|
|
420
|
+
fails: set `authz.scopes.<kind>.instance`. A kind with no resolvable instance
|
|
421
|
+
table loads no instance, so only its relationship tables are checked, unless
|
|
422
|
+
the kind is also a `tenancy.lookups` key. Then its tokens are routed by an
|
|
423
|
+
instance id that no table binds to a tenant, so the build fails until you set
|
|
424
|
+
`instance`.
|
|
425
|
+
|
|
426
|
+
The table above is what the compiler names in friendly messages. Three more
|
|
427
|
+
checks stand behind it:
|
|
428
|
+
|
|
429
|
+
- **Platform action source.** A platform action or feature `lib/` file that
|
|
430
|
+
names a tenant table fails the build. So does a schedule
|
|
431
|
+
(`services/schedules`), a queue handler that is not a tenant job, and any
|
|
432
|
+
`quickback/lib` helper, auth hook (`quickback/hooks`), middleware
|
|
433
|
+
(`quickback/middlewares`) or Better Auth plugin (`quickback/plugins`) the
|
|
434
|
+
edge Worker loads (scanned per module). That covers its export name as an identifier, its SQL name as a
|
|
435
|
+
string (an inline `sqliteTable("projects", …)`), and `FROM` / `JOIN` /
|
|
436
|
+
`INTO` / `UPDATE` / `TABLE <name>` in any string or template (in actions,
|
|
437
|
+
only with `allowRawSql`). The scan is conservative: a local variable that
|
|
438
|
+
only shares a tenant table's name is refused too, so rename it. Instead of a
|
|
439
|
+
cron sweep, declare a [tenant schedule](#tenant-schedules) (each object runs
|
|
440
|
+
its own work on its own alarm) or have the edge arm a tenant job
|
|
441
|
+
(`scheduleTenantJob`); to read a tenant's data from the edge, call a
|
|
442
|
+
[result job](#result-jobs).
|
|
443
|
+
- **The emitted edge bundle.** After all files are generated, the compiler
|
|
444
|
+
walks the edge Worker's runtime imports from `src/index.ts`. It follows
|
|
445
|
+
relative imports, `tsconfig.json` `paths` aliases such as `~/`,
|
|
446
|
+
`export … from`, and literal `import()` / `require()`. Type-only imports are
|
|
447
|
+
skipped. The build fails if an edge module imports a tenant feature's module
|
|
448
|
+
(its schema, table, resource or routes), or calls `import()` / `require()`
|
|
449
|
+
with a computed path the walk can't follow.
|
|
450
|
+
- **At runtime.** `src/lib/firewall-registry.ts` is the one edge module allowed
|
|
451
|
+
to import tenant modules. It maps every table to its firewall for the scoped
|
|
452
|
+
`db`. Only its tenant imports are exempt; its other imports are still walked.
|
|
453
|
+
Its tenant entries throw `TENANT_TABLE_ON_EDGE` outside the tenant Worker, so
|
|
454
|
+
an edge query that slips past the compile-time checks fails instead of
|
|
455
|
+
reading D1. A raw SQL string that never goes through the scoped `db` is caught
|
|
456
|
+
only by the compile-time scan.
|
|
457
|
+
|
|
458
|
+
To fix it, keep those tables on the platform. An organization-scoped one needs
|
|
459
|
+
`placement: { platform: true, crossTenant: true }`. A platform table can't
|
|
460
|
+
hold a foreign key into a tenant table (`TENANCY_FK_PLATFORM_TO_TENANT`), so
|
|
461
|
+
move the tables it references with it, or drop the reference. Or remove the
|
|
462
|
+
dependency.
|
|
463
|
+
|
|
464
|
+
### Tenant-backed scope kinds
|
|
465
|
+
|
|
466
|
+
An instance-bound OAuth kind (`authz.scopes.<kind>.oauth`) whose whole
|
|
467
|
+
admission program reads one organization object is **tenant-backed**: its
|
|
468
|
+
admission, its namespaces and its tickets run in that object, and its tables
|
|
469
|
+
never exist in the platform D1. Every compile decides this from the
|
|
470
|
+
requirements in [Which kinds can be tenant-backed](#which-kinds-can-be-tenant-backed);
|
|
471
|
+
there is no switch. A tenant-backed kind gets this identity contract:
|
|
472
|
+
|
|
473
|
+
- **Pinned grant references.** An instance-bound OAuth grant stores
|
|
474
|
+
`qb2:<kind>:<tenantId>:<instanceId>:<mode>:<epoch>[:<ceiling>]` instead of
|
|
475
|
+
`<kind>:<id>`. `mode` is `discover` (the authorize flow: any of the kind's
|
|
476
|
+
roles) or `exact` (`issueScopeGrant`: only the URI-encoded `{ roles,
|
|
477
|
+
subjectId, provingTable }` ceiling). A reference parses only in its one
|
|
478
|
+
canonical spelling. An exact reference without `provingTable` fails
|
|
479
|
+
refresh with `invalid_grant` (reauthorize); the table is never guessed. An older unpinned grant for the kind fails refresh with
|
|
480
|
+
`invalid_grant`, so the user reauthorizes. The compiler never guesses a
|
|
481
|
+
tenant for it.
|
|
482
|
+
- **Where the tenant comes from.** At authorize it comes from the kind's
|
|
483
|
+
[lookup](#lookup-indexes) (`tenancy.lookups.<kind>`), never from the caller's
|
|
484
|
+
active organization or the request. If the lookup matches several
|
|
485
|
+
organizations, the request fails with `invalid_request`. If it has no row
|
|
486
|
+
yet, the request fails with `temporarily_unavailable` (retry).
|
|
487
|
+
`issueScopeGrant` also accepts a `tenantHint`, the organization that trusted
|
|
488
|
+
server code read from the credential row. The hint is used only while the
|
|
489
|
+
lookup has no row. A lookup that disagrees with it refuses. Once issued, a
|
|
490
|
+
grant always routes to its pinned tenant, even if the lookup changes later.
|
|
491
|
+
- **Authorization epoch.** The grant pins the tenant's
|
|
492
|
+
[authorization epoch](#authorization-epoch), read with the `qb.epoch`
|
|
493
|
+
[tenant command](#tenant-commands). Every code exchange and refresh compares
|
|
494
|
+
it with the current epoch. After a restore they differ, and the grant fails
|
|
495
|
+
with `invalid_grant`, so the user signs in again.
|
|
496
|
+
- **v2 claims.** The `qb_scope` claim gains `v: 2`, `tenantId` and `epoch`
|
|
497
|
+
(and `provingTable` from admission). The bound lane refuses a token for a
|
|
498
|
+
tenant-backed kind without them (`401`). `ctx.oauth.boundTo` becomes
|
|
499
|
+
`{ kind, id, tenantId, epoch }`, and the edge routes the request to
|
|
500
|
+
`boundTo.tenantId`. It never uses a lookup or `activeOrgId` for that token.
|
|
501
|
+
- **Revocation.** For a tenant-backed kind, `revokeScopeGrant` requires the
|
|
502
|
+
`tenantId` the grant pins. It deletes the user's pinned grants for that
|
|
503
|
+
instance in both modes, at every epoch and under any tenant. Instance ids are
|
|
504
|
+
collision-resistant, so this also catches a grant pinned through a wrong
|
|
505
|
+
hint. User-wide revocation (ban, sign-out everywhere) deletes the kind's
|
|
506
|
+
pinned and unpinned grants.
|
|
507
|
+
- **Kind names.** `qb2` is reserved as a scope kind name in every project. A
|
|
508
|
+
tenant-backed kind's name must be an identifier, because it is a segment of
|
|
509
|
+
its grant references.
|
|
510
|
+
- **Realtime.** Rooms on tenant tables become `t1:<tenant>:<key>`, and the
|
|
511
|
+
kind's identity tags become
|
|
512
|
+
`t1:<tenant>:scope:<kind>:<provingTable>:<subjectId>`. See
|
|
513
|
+
[Durable Objects → Tenant rooms](/platform/realtime/durable-objects#tenant-rooms).
|
|
514
|
+
- **Id contract.** The kind's instance table and each role's proving table
|
|
515
|
+
need server-generated, collision-resistant ids across every tenant object.
|
|
516
|
+
The build fails with `TENANCY_ADMISSION_ID_STRATEGY` when the table has
|
|
517
|
+
`generateId: false | 'short' | 'serial'`, `allowClientIds: true`, or a
|
|
518
|
+
numeric primary key.
|
|
519
|
+
|
|
520
|
+
#### Which kinds can be tenant-backed
|
|
521
|
+
|
|
522
|
+
The compiler plans each scope kind's admission program: the instance read plus
|
|
523
|
+
one probe per user-provable role, in the kind's declared
|
|
524
|
+
[precedence](/define/scopes#subject-precedence). An OAuth kind can run that
|
|
525
|
+
program, and every other path it has, inside its tenant object only when all
|
|
526
|
+
of these hold. The first five are permanent: those paths never run in a tenant
|
|
527
|
+
object. A kind reading a tenant table that misses any of them fails the build
|
|
528
|
+
with each missing requirement under its own code:
|
|
529
|
+
|
|
530
|
+
| Code | Requirement |
|
|
531
|
+
|---|---|
|
|
532
|
+
| `TENANCY_LEGACY_SCOPE_ENTER` | The kind declares `oauth`. `POST /scope/v1/enter` runs on the edge against D1 and pins no tenant, so a kind admitted only through it can't read tenant tables. |
|
|
533
|
+
| `TENANCY_LEGACY_SCOPE_MINT` | Every role is `subject: 'user'`. A `'supplied'` / `'both'` role can be minted by `ctx.mintScope` on the edge, with no tenant. |
|
|
534
|
+
| `TENANCY_ADMISSION_SELF` | No role declares `self: { table }`. The `ctx.self` recheck runs on every edge action route. |
|
|
535
|
+
| `TENANCY_ADMISSION_HOPS` | No role proves through a relationship with `hops`. Tenant admission proves the relationship's own table. |
|
|
536
|
+
| `TENANCY_NAMESPACE_MINT` | No namespace on the kind's `:param` declares `mintScope` or `acceptScope`. A legacy scope token carries no tenant. |
|
|
537
|
+
| `TENANCY_ADMISSION_MIXED_PLACEMENT` | Every table the kind reads (instance, relationship tables and `hops`, `self.table`) lives in the tenant object. None on the platform. |
|
|
538
|
+
| `TENANCY_ADMISSION_PARTITIONED` | None of them lives in a [partition](#partitions). |
|
|
539
|
+
| `TENANCY_ADMISSION_UNRESOLVED_INSTANCE` | The instance table resolves to exactly one table. Set `authz.scopes.<kind>.instance`. |
|
|
540
|
+
| `TENANCY_ADMISSION_TENANT_COLUMN` | The instance table and every proving table have an organization column. |
|
|
541
|
+
| `TENANCY_ADMISSION_LOOKUP` | `tenancy.lookups.<kind>` indexes the instance table's primary key: `{ table: '<instance>', column: '<pk>' }`. |
|
|
542
|
+
| `TENANCY_ADMISSION_SQL_HELPER` | No role proves through a SQL helper (Postgres). |
|
|
543
|
+
|
|
544
|
+
Every error lists all the violations at once. A kind that meets them all is
|
|
545
|
+
tenant-backed in every compile.
|
|
546
|
+
|
|
547
|
+
#### Tenant admission (`qb.admitScope`)
|
|
548
|
+
|
|
549
|
+
For a tenant-backed kind, the edge never reads the kind's tables. Every
|
|
550
|
+
admission (authorize, code exchange, refresh, `issueScopeGrant`, the bound
|
|
551
|
+
ws-ticket mint) goes through the generated dispatcher `src/lib/scope-admission.ts`.
|
|
552
|
+
Platform kinds keep their D1 evaluator there. A tenant-backed kind sends one
|
|
553
|
+
`qb.admitScope` [command](#tenant-commands) to the pinned tenant. The object
|
|
554
|
+
runs `admitLocal` (`src/tenant/scope-admission.ts`) in one synchronous SQLite
|
|
555
|
+
read, under the restore permit:
|
|
556
|
+
|
|
557
|
+
1. The request's epoch must equal the permit's epoch (`SCOPE_EPOCH`).
|
|
558
|
+
2. The instance row, read through its own firewall with tenant scopes stripped
|
|
559
|
+
(soft deletes still apply), must exist once and belong to this tenant
|
|
560
|
+
(`SCOPE_NOT_FOUND`).
|
|
561
|
+
3. Each user-provable role is probed in precedence order, with the same
|
|
562
|
+
predicates the D1 evaluator uses. An exact ceiling probes only its own roles
|
|
563
|
+
on its own proving table, with `id = subjectId`. A row whose organization is
|
|
564
|
+
not the tenant never matches, even if it was copied in.
|
|
565
|
+
4. The first role with any match chooses the subject `(provingTable, id)`. Two
|
|
566
|
+
rows on that role deny the admission (`SCOPE_AMBIGUOUS`). Every later role
|
|
567
|
+
probes only the chosen row, so a later role's duplicate rows never deny. The
|
|
568
|
+
reply carries only that subject's roles and sub-keys, plus `provingTable`.
|
|
569
|
+
It never unions roles across subjects.
|
|
570
|
+
|
|
571
|
+
The edge checks every reply field against the request: kind, instance,
|
|
572
|
+
tenant, epoch, known roles on one proving table, the ceiling's subject, roles
|
|
573
|
+
and table, and declared sub-keys only. A reply that disagrees is treated as
|
|
574
|
+
`unavailable`, never as an admission. Errors map like this:
|
|
575
|
+
|
|
576
|
+
| Outcome | At authorize | At code exchange / refresh | ws-ticket (bound or session) |
|
|
577
|
+
|---|---|---|---|
|
|
578
|
+
| denied | `access_denied` | `invalid_grant` | `403` |
|
|
579
|
+
| unavailable (archived, purged, restoring, migrating, unreachable) | `temporarily_unavailable` (503) | `temporarily_unavailable` (503) | `503 TENANT_ADMISSION_UNAVAILABLE` |
|
|
580
|
+
|
|
581
|
+
The admission policy (kinds, precedence, predicates, sub-keys) is part of the
|
|
582
|
+
command fingerprint, so two Workers built from different policies refuse each
|
|
583
|
+
other. Adding `qb.admitScope` does not change the RPC version: the fingerprint
|
|
584
|
+
covers the whole command registry. So while the two Workers deploy, an edge
|
|
585
|
+
on the previous build gets `unavailable` (`TENANT_COMMAND_FINGERPRINT_MISMATCH`)
|
|
586
|
+
from every command, `qb.epoch` included, until it is deployed too. Bound
|
|
587
|
+
tokens of tenant-backed kinds answer `temporarily_unavailable` in that window.
|
|
588
|
+
Nothing is admitted from a mismatched registry. The tenant bundle imports no Better Auth, no `drizzle-orm/d1` and no
|
|
589
|
+
`scope-oauth`. The legacy `POST /scope/v1/enter` never serves a tenant-backed
|
|
590
|
+
kind; when no other kind remains, the route isn't emitted at all. None of
|
|
591
|
+
these paths reads the platform D1.
|
|
592
|
+
|
|
593
|
+
#### Server-issued grants
|
|
594
|
+
|
|
595
|
+
A tenant-backed kind that declares
|
|
596
|
+
[`oauth.serverGrant`](/define/scopes#server-issued-grants-issuescopegrant)
|
|
597
|
+
gets two more commands. They are reached only through the generated
|
|
598
|
+
`readScopeGrantSubject` and `linkScopeGrantSubject` (in `src/lib/scope-oauth.ts`),
|
|
599
|
+
which the edge action calls with the subject its own credential row names;
|
|
600
|
+
no edge code reads or writes the guest table itself.
|
|
601
|
+
|
|
602
|
+
- **`qb.scopeGrantRead`** selects the instance row and the subject row inside
|
|
603
|
+
one synchronous transaction: object tenant = instance tenant column =
|
|
604
|
+
subject tenant column, subject resource column = the instance id, neither
|
|
605
|
+
row soft-deleted, the subject admittable (the OR of the ceiling roles'
|
|
606
|
+
`where`). It writes nothing.
|
|
607
|
+
- **`qb.scopeGrantLink`** re-runs those checks, returns `unchanged` when the
|
|
608
|
+
subject is already linked to the user, and otherwise runs one conditional
|
|
609
|
+
`UPDATE … SET <user column> = :userId WHERE <all of the above> AND
|
|
610
|
+
(<user column> IS NULL OR <user column> = :replaces) RETURNING id`. Anything
|
|
611
|
+
but exactly one row is `SCOPE_GRANT_LINK_CONFLICT` (still live, linked to
|
|
612
|
+
someone else) or `SCOPE_GRANT_SUBJECT_DENIED`, with nothing written. On a
|
|
613
|
+
link it puts the audit row (`event_kind: 'scope_grant_link'`, a
|
|
614
|
+
`credential-mediated` actor envelope) in the object's outbox in the same
|
|
615
|
+
transaction; the edge drains it to `audit_events`. The request's epoch must
|
|
616
|
+
equal the permit's: a restore between the read and the link denies.
|
|
617
|
+
|
|
618
|
+
Routing follows the kind's lookup; the action's `tenantHint` (the
|
|
619
|
+
organization on its credential row) is used only while the lookup has no
|
|
620
|
+
row, and the object's own equality checks make a wrong hint admit nobody.
|
|
621
|
+
While the object is held, archived, restoring, moving or migrating, both
|
|
622
|
+
commands answer `unavailable`, so the action answers `503` and its credential
|
|
623
|
+
is untouched: nothing spends it before the action's own consume, after
|
|
624
|
+
`issueScopeGrant`. Like `qb.admitScope`, adding these commands does not
|
|
625
|
+
change the RPC version: the command fingerprint covers them (and the
|
|
626
|
+
server-grant program), so a split deploy refuses before any write.
|
|
627
|
+
|
|
628
|
+
#### Tenant namespaces
|
|
629
|
+
|
|
630
|
+
A namespace (`authz.namespaces.<name>`) whose relationship lanes, `loads`
|
|
631
|
+
tables and claimed routes all live in the organization object runs in the
|
|
632
|
+
tenant Worker. Claimed routes are the standalone actions whose `path` is under
|
|
633
|
+
its prefix and the generated table routers mounted there. The edge mounts a
|
|
634
|
+
forwarder at the prefix. The tenant Worker mounts the namespace's gate file
|
|
635
|
+
(`src/routes/__namespace-<name>.routes.ts`) and, behind it, every route the
|
|
636
|
+
namespace claims. A tenant feature's action under the prefix may sit outside
|
|
637
|
+
its feature's own path (`TENANCY_ROOT_ACTION` doesn't apply to it).
|
|
638
|
+
|
|
639
|
+
The edge routes a namespace request by the prefix's first `:param`, through
|
|
640
|
+
the tenant-backed kind whose `requestField` it is:
|
|
641
|
+
|
|
642
|
+
| Caller | Tenant |
|
|
643
|
+
|---|---|
|
|
644
|
+
| Instance-bound token of the kind | The tenant it pins (`ctx.oauth.boundTo.tenantId`). No lookup. A token for another instance: `403`. |
|
|
645
|
+
| Anyone else | `tenancy.lookups.<kind>` for the id. Several organizations: `409 TENANT_AMBIGUOUS`. No row: the same `403 ACCESS_ROLE_REQUIRED` the gate gives a caller who proves no lane, so an unknown id and an id you can't reach look alike. A new instance is indexed after its write, so it can answer that `403` briefly; retry. A failed lookup read: `503 TENANT_UNAVAILABLE`. |
|
|
646
|
+
|
|
647
|
+
The edge matches the prefix on the percent-decoded path Hono routes on, and
|
|
648
|
+
the bound-token confinement uses the same path, so an encoded variant
|
|
649
|
+
(`/api/v1/%65vent/…`) is routed and confined exactly like the plain one. A
|
|
650
|
+
request that reaches the namespace mount but matches no namespace is `404`; it
|
|
651
|
+
never falls through to active-organization routing. An encoded `/` (`%2F`)
|
|
652
|
+
stays encoded and is never an instance id. The caller's active organization
|
|
653
|
+
never routes a namespace request. A caller
|
|
654
|
+
whose active organization is a different one loses its organization seat and
|
|
655
|
+
its organization and team roles before the request is forwarded. Inside the
|
|
656
|
+
object, an organization firewall arm then matches only a member of this
|
|
657
|
+
organization; everyone else gets the rows their relationship proves.
|
|
658
|
+
|
|
659
|
+
In the object, the gate re-proves an instance-bound token with `admitLocal`,
|
|
660
|
+
the same program `qb.admitScope` runs. It uses the raw tenant SQLite, the
|
|
661
|
+
request's restore permit epoch, and the token's exact subject and proving
|
|
662
|
+
table. No RPC and no D1 read. The token's tenant must be the object's, and
|
|
663
|
+
its epoch the permit's: a token issued before a restore gets `403`, so the
|
|
664
|
+
user reauthorizes. A session caller passes a lane only as the subject
|
|
665
|
+
admission would choose: after the lane matches, the gate runs `admitLocal` in
|
|
666
|
+
discover mode and requires the same row. So the kind's precedence decides,
|
|
667
|
+
and two rows on the choosing role deny (`403`), exactly as at authorize. Then the relationship lanes, `loads` hydration (through the
|
|
668
|
+
loaded table's firewall) and the per-lane scope refresh run against tenant
|
|
669
|
+
SQLite exactly as on a single Worker. A namespace request costs one RPC (the
|
|
670
|
+
forward) plus, for a session caller, one lookup read in D1.
|
|
671
|
+
|
|
672
|
+
A claimed table's [legacy forward](/define/areas#keeping-the-old-url-legacy)
|
|
673
|
+
(`legacy`) is not a namespace route. The edge routes its old URL
|
|
674
|
+
(`/api/v1/locations`) by **active organization**, exactly as it routed the
|
|
675
|
+
table before the claim: a caller with no organization gets `400 TENANT_REQUIRED`
|
|
676
|
+
at the edge, and the organization object is always the caller's own, so the
|
|
677
|
+
§2a strip never applies. The forward runs in the tenant Worker
|
|
678
|
+
(`src/routes/__legacy-<feature>.routes.ts`, mounted beside the namespace),
|
|
679
|
+
requires `ctx.activeOrgId === ctx.tenantId`, reads the instance and any row from
|
|
680
|
+
tenant SQLite, and dispatches in-process to the namespace route: no second RPC.
|
|
681
|
+
|
|
682
|
+
A namespace that can't run in one place fails the build:
|
|
683
|
+
|
|
684
|
+
| Code | Cause |
|
|
685
|
+
|---|---|
|
|
686
|
+
| `TENANCY_NAMESPACE_SPLIT` | Its lanes, `loads` tables or claimed routes mix tenant and platform. |
|
|
687
|
+
| `TENANCY_NAMESPACE_PARTITIONED` | One of them is in a [partition](#partitions) object. |
|
|
688
|
+
| `TENANCY_NAMESPACE_UNROUTED` | It runs in tenant objects, but its `:param` is no scope kind's `requestField`, or a platform kind's, so a request can't name its organization. |
|
|
689
|
+
| `TENANCY_NAMESPACE_MINT` | It declares `mintScope` or `acceptScope` for a tenant-backed kind. |
|
|
690
|
+
|
|
691
|
+
#### Edge namespace actions
|
|
692
|
+
|
|
693
|
+
A tenant namespace's routes run in the tenant Worker, which has no `env`
|
|
694
|
+
bindings, secrets or Better Auth. An action under the prefix that needs them
|
|
695
|
+
(presigning an R2 upload, creating a Better Auth user, sending email) declares
|
|
696
|
+
`edge: true`. It keeps its URL and runs on the edge Worker:
|
|
697
|
+
|
|
698
|
+
{/* doc-compile: skip — needs a tenant namespace, a result job and a secret */}
|
|
699
|
+
```ts title="quickback/features/uploads/actions/uploadUrl.ts"
|
|
700
|
+
import { z } from "zod";
|
|
701
|
+
import { defineAction, ActionError } from "../.quickback/define-action";
|
|
702
|
+
import { callTenantJob } from "../../../lib/tenants";
|
|
703
|
+
|
|
704
|
+
export default defineAction({
|
|
705
|
+
description: "A presigned upload URL for one event.",
|
|
706
|
+
path: "/event/:eventId/upload-url",
|
|
707
|
+
method: "POST",
|
|
708
|
+
edge: true,
|
|
709
|
+
input: z.object({ filename: z.string().min(1).max(200) }),
|
|
710
|
+
access: { roles: ["scope:event:staff", "scope:event:attendee"] },
|
|
711
|
+
async execute({ ctx, env, input }) {
|
|
712
|
+
const eventId = ctx.admittedInstance?.kind === "event" ? ctx.admittedInstance.id : undefined;
|
|
713
|
+
if (!eventId || !ctx.tenantId) throw new ActionError("No admitted event", "BAD_REQUEST", 400);
|
|
714
|
+
// Tenant data only through a result job, in the tenant the gate admitted.
|
|
715
|
+
const res = await callTenantJob<{ name: string }>(env, ctx.tenantId, { type: "event.name", eventId }, "event-name:" + crypto.randomUUID());
|
|
716
|
+
if (res.status !== "ok") throw new ActionError("Try again shortly", "EVENT_UNAVAILABLE", 503);
|
|
717
|
+
return { url: await presign(env.UPLOAD_SIGNING_KEY, `${ctx.tenantId}/${eventId}/${input.filename}`), event: res.result.name };
|
|
718
|
+
},
|
|
719
|
+
});
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
The edge mounts these actions at the namespace prefix ahead of the forwarder,
|
|
723
|
+
each behind a gate on its own route. Every other route under the prefix is
|
|
724
|
+
forwarded as before. The gate reads no table. One `qb.admitScope` in the
|
|
725
|
+
instance's tenant decides:
|
|
726
|
+
|
|
727
|
+
| Caller | Admission |
|
|
728
|
+
|---|---|
|
|
729
|
+
| Instance-bound token of the kind | Exact admission of its subject in the tenant and epoch it pins. A revoked subject, or a token issued before a restore, gets `403`. A token for another instance gets `403`. |
|
|
730
|
+
| Session | The tenant from `tenancy.lookups.<kind>`, never the active organization, then discover admission under that tenant's current epoch: the namespace's relationship lanes, chosen by the kind's precedence. |
|
|
731
|
+
| Session, `{ roles }` lane | A member of that organization holding one of the lane's roles, when the tenant confirms the instance exists there and the user proves no row (`SCOPE_NO_ROLE`). Members of other organizations never qualify. |
|
|
732
|
+
|
|
733
|
+
Every denial, including an unknown or not-yet-indexed id, is the namespace's
|
|
734
|
+
`403 ACCESS_ROLE_REQUIRED`. A tenant that can't answer is `503` with
|
|
735
|
+
`Retry-After`, never a denial. On success `ctx.tenantId` is the admitted
|
|
736
|
+
tenant and `ctx.admittedInstance` is `{ kind, id }` for the admitted instance.
|
|
737
|
+
This routing metadata grants no scoped roles. Relationship admission also sets
|
|
738
|
+
`ctx.scope.<kind>` to the admitted entry (`id`, `roles`, `subjectId`,
|
|
739
|
+
`provingTable`); the organization-role lane clears that scope entry. A caller who isn't a member of that organization loses its
|
|
740
|
+
organization seat and roles, as on forwarded requests. Then the action's own
|
|
741
|
+
`access` runs against that `ctx`.
|
|
742
|
+
|
|
743
|
+
An edge action is a platform action:
|
|
744
|
+
|
|
745
|
+
- It lives in a platform feature. A feature with no tables is simplest. The
|
|
746
|
+
file location doesn't change its URL. In a tenant feature the build fails
|
|
747
|
+
with `TENANCY_EDGE_ACTION_PLACEMENT`.
|
|
748
|
+
- Its `db` is the platform D1. It reads tenant data through [result
|
|
749
|
+
jobs](#result-jobs) called with `ctx.tenantId`. Naming a tenant table, or
|
|
750
|
+
importing a tenant feature's module, fails the build
|
|
751
|
+
(`TENANCY_ADMISSION_DEPENDENCY`).
|
|
752
|
+
- The namespace's `loads` hydration never runs on the edge. Reading
|
|
753
|
+
`ctx.<exposeAs>` fails the build (`TENANCY_EDGE_ACTION_CTX`). Use
|
|
754
|
+
`ctx.scope.<kind>`, or read the row with a result job.
|
|
755
|
+
- Its path must be under a tenant namespace's prefix
|
|
756
|
+
(`TENANCY_EDGE_ACTION_NAMESPACE`). Without `edge: true`, a platform action
|
|
757
|
+
there splits the namespace (`TENANCY_NAMESPACE_SPLIT`).
|
|
758
|
+
|
|
759
|
+
Security notes:
|
|
760
|
+
|
|
761
|
+
- The gate proves the caller holds a role on the instance when the request
|
|
762
|
+
starts. A result job runs later, with system rights, in a separate
|
|
763
|
+
transaction. A revocation can land between the two. When a write must be
|
|
764
|
+
authorized atomically with the authorization, recheck the subject inside the
|
|
765
|
+
job (its message carries `ctx.scope.<kind>.subjectId`), or keep the write in
|
|
766
|
+
a tenant action behind the tenant gate.
|
|
767
|
+
- The job's tenant must be `ctx.tenantId`. Never use an id from the request
|
|
768
|
+
(`TENANCY_JOB_CALL_TENANT_SOURCE`). Scope any job input by the admitted
|
|
769
|
+
instance (`ctx.scope.<kind>.id`).
|
|
770
|
+
- Each request costs one `qb.admitScope` RPC, plus a lookup read and a
|
|
771
|
+
`qb.epoch` RPC for a session caller.
|
|
772
|
+
|
|
773
|
+
In shared mode (no `isolation: 'durable-object'`), `edge` has no effect. The
|
|
774
|
+
namespace already runs on the edge.
|
|
775
|
+
|
|
776
|
+
## Requests
|
|
777
|
+
|
|
778
|
+
| Request | Result |
|
|
779
|
+
|---|---|
|
|
780
|
+
| Tenant route, active organization set | Forwarded to that organization's object |
|
|
781
|
+
| Tenant route, no active organization | Resolved through a [lookup](#lookup-indexes) named after the token's scope kind; otherwise `400 TENANT_REQUIRED`. Several matching organizations: `409 TENANT_AMBIGUOUS`. |
|
|
782
|
+
| [Tenant namespace](#tenant-namespaces) route | A bound token: the tenant it pins. Anyone else: the kind's lookup for the `:param` (`409 TENANT_AMBIGUOUS`; an unknown id gets the gate's own `403`). Never the active organization. |
|
|
783
|
+
| Partitioned route | Forwarded to the partition's object; see [Partitions](#partitions) for `PARTITION_KEY_REQUIRED` / `PARTITION_KEY_MISMATCH` |
|
|
784
|
+
| Tenant route, unauthenticated | `401 AUTH_MISSING` |
|
|
785
|
+
| Platform route | Served by the edge from D1 |
|
|
786
|
+
| Tenant object whose migration failed | `503 TENANT_MIGRATION_FAILED` with the migration tag and SQLite error in `details.error` (never the SQL) |
|
|
787
|
+
| Archived tenant | `423 TENANT_ARCHIVED` (checked inside the object, no D1 read) |
|
|
788
|
+
| Purged tenant | `410 TENANT_PURGED` |
|
|
789
|
+
| Body larger than 1 MiB (`Content-Length`) | `413 PAYLOAD_TOO_LARGE` at the edge |
|
|
790
|
+
| Tenant object reset, or a retryable RPC error | `GET` / `HEAD`: retried once on a fresh stub. Anything else is sent once. Then `503 TENANT_UNAVAILABLE` with `Retry-After`. The registry is not touched. |
|
|
791
|
+
| Tenant object overloaded | `503 TENANT_OVERLOADED` with `Retry-After`. Never retried. |
|
|
792
|
+
| Subrequest depth limit exceeded | `508 TENANT_DEPTH_EXCEEDED` |
|
|
793
|
+
| Any other RPC error | `503 TENANT_UNAVAILABLE`; rows without an ordered health report become `migrating` with the error. An existing ordered health report is preserved. |
|
|
794
|
+
|
|
795
|
+
### Same-tenant unsafe actions
|
|
796
|
+
|
|
797
|
+
A tenant feature may declare `unsafe: { reason, crossTenant: false }`. The
|
|
798
|
+
action runs in the tenant object like any other, with the same access checks
|
|
799
|
+
and security wrapper as on the edge:
|
|
800
|
+
|
|
801
|
+
- `unsafeDb` is the object's own SQLite, without the firewall. It can't reach
|
|
802
|
+
the D1, the auth database or another organization: those are not in the
|
|
803
|
+
object.
|
|
804
|
+
- `unsafeDb.scopeTo({ organizationId })` accepts only the object's own
|
|
805
|
+
organization. Any other throws `TENANT_SCOPE_MISMATCH` (403).
|
|
806
|
+
- Cross-tenant `unsafe` (`unsafe: true`, or an object without
|
|
807
|
+
`crossTenant: false`) and `unsafe.authWrites` are refused
|
|
808
|
+
(`TENANCY_UNSAFE_ACTION`). The `ctx` and `env` checks still apply
|
|
809
|
+
(`TENANCY_CTX_UNAVAILABLE`, `TENANCY_ENV_UNAVAILABLE`).
|
|
810
|
+
|
|
811
|
+
## Transactions
|
|
812
|
+
|
|
813
|
+
Inside a tenant object, `db.transaction(cb)` is
|
|
814
|
+
`ctx.storage.transactionSync()`. Only statements that run before `cb` returns
|
|
815
|
+
are in the transaction. Every action helper of a tenant feature types `db` and
|
|
816
|
+
`unsafeDb` as that synchronous handle: `define-action.ts`, the per-table
|
|
817
|
+
`define-action.<table>.ts` and the namespace `define-action.<scope>.ts`.
|
|
818
|
+
Do all I/O first, then pass a synchronous callback:
|
|
819
|
+
|
|
820
|
+
{/* doc-compile: skip — action body fragment */}
|
|
821
|
+
```ts
|
|
822
|
+
const rows = await db.select().from(projects);
|
|
823
|
+
await db.transaction((tx) => {
|
|
824
|
+
for (const row of rows) {
|
|
825
|
+
tx.update(projects).set({ name: "x-" + row.name }).where(eq(projects.id, row.id)).run();
|
|
826
|
+
}
|
|
827
|
+
});
|
|
828
|
+
```
|
|
829
|
+
|
|
830
|
+
The callback's return type is checked: returning a PromiseLike is a type
|
|
831
|
+
error — an `async` callback, a Promise, a union containing one
|
|
832
|
+
(`flag ? work(tx) : undefined`), or a query builder not yet executed (builders
|
|
833
|
+
are thenable; end every statement in `.run()`, `.all()`, `.get()` or
|
|
834
|
+
`.values()`). Returning `any` is refused too, because it can hide a Promise:
|
|
835
|
+
annotate the helper's return type. An awaited body runs after the transaction
|
|
836
|
+
has committed, so nothing after the first `await` would roll back.
|
|
837
|
+
|
|
838
|
+
The build backs the type for code that casts it away (`(db as any)`): on a
|
|
839
|
+
`transaction(...)` call on a db or tx handle, an `async` callback, or one that
|
|
840
|
+
returns or starts a Promise (`await`, `Promise.*`, `.then`), fails with
|
|
841
|
+
`TENANCY_ASYNC_TRANSACTION`. Put `// quickback-allow-transaction` on the call's
|
|
842
|
+
line, or the line above, to opt one call out.
|
|
843
|
+
|
|
844
|
+
Batch handlers on tenant tables are transactional. `PATCH /batch` and
|
|
845
|
+
`PUT /batch` with `failFast: true` run in `ctx.storage.transaction()` and roll
|
|
846
|
+
back every write on failure (`meta.transactional: true`). See
|
|
847
|
+
[Batch operations](/api/batch-operations#transactional-semantics). That loop
|
|
848
|
+
awaits only tenant SQLite, so a tenant table's `create` / `update` / `upsert`
|
|
849
|
+
access and its `guards` must be declarative: a function there fails the build
|
|
850
|
+
(`TENANCY_BATCH_ASYNC`), because it could await other I/O and let another
|
|
851
|
+
request's writes interleave into the transaction.
|
|
852
|
+
|
|
853
|
+
## Hard deletes and the audit log
|
|
854
|
+
|
|
855
|
+
The tenant Worker has no `AUDIT_DB`. A hard `DELETE` (single or batch) on a
|
|
856
|
+
tenant table writes its `audit_events` row to the object's outbox — in the
|
|
857
|
+
object's own SQLite, in one transaction with the delete, so a failed delete
|
|
858
|
+
leaves no audit row — and the response tells the edge to drain it. The edge
|
|
859
|
+
sets each row's `target_org_id` and `actor_org_id` to the object's organization
|
|
860
|
+
(tenant code cannot attribute a row to another one; a mismatch is logged and
|
|
861
|
+
kept in `metadata.tenantClaimed`), writes the rows to the audit database
|
|
862
|
+
(idempotent by id), then acknowledges them. Unacknowledged rows are retried
|
|
863
|
+
after the object's next response. A malformed audit payload moves to the
|
|
864
|
+
object's `__qb_outbox_dead` table instead of blocking the queue, and
|
|
865
|
+
`tenant_registry.outbox_dead_letters` counts them. Database failures leave rows
|
|
866
|
+
queued for retry; error messages never classify them as permanently invalid.
|
|
867
|
+
Purge first drains pending rows and copies dead letters into the audit database.
|
|
868
|
+
If either step fails, or pending rows remain, purge refuses to erase the object.
|
|
869
|
+
Purge is exclusive. It takes the control object's maintenance fence, which is
|
|
870
|
+
refused (`TENANT_BUSY`) while any request, job or alarm holds a permit,
|
|
871
|
+
including one waiting on I/O, so nothing writes into the object after it is
|
|
872
|
+
erased. `deleteAll()` erases any marker the object keeps itself, so purge then
|
|
873
|
+
turns that fence into a permanent `purged` marker in the object's control
|
|
874
|
+
object (`__qb_control__:<name>`, outside the tenant's storage). Only then does
|
|
875
|
+
it call `deleteAlarm()` and `deleteAll()`, and mark its own storage `purged`.
|
|
876
|
+
A reset anywhere in between leaves a tenant that is still purged, never a live
|
|
877
|
+
empty one:
|
|
878
|
+
|
|
879
|
+
- Every request, command, job, alarm and schedule takes a permit from the
|
|
880
|
+
control object, and the permit carries the marker. The object answers
|
|
881
|
+
`410 TENANT_PURGED`, and commands answer `unavailable` / `TENANT_PURGED`,
|
|
882
|
+
even while its own storage still says `archived`.
|
|
883
|
+
- On wake, an archived object asks its control object, and so does any object
|
|
884
|
+
that has not yet had one successful check. If the marker is there, the object
|
|
885
|
+
does not migrate: it marks itself `purged` and reports `tenant purged`. If the
|
|
886
|
+
control object cannot be read, the object migrates as usual and asks again
|
|
887
|
+
on its next wake. It still serves nothing, because its permits carry the
|
|
888
|
+
marker.
|
|
889
|
+
- Archive, unarchive, restore, cancel-restore, retry-migration, backups,
|
|
890
|
+
scheduling and lookup rebuilds all refuse a purged tenant.
|
|
891
|
+
|
|
892
|
+
`tenant_registry` still says `archived` after an interrupted purge. To recover,
|
|
893
|
+
retry `POST /tenants/:id/purge`. Purge is resumable: once the marker exists it
|
|
894
|
+
needs no fence, erases whatever is left, and marks the registry `purged`. The
|
|
895
|
+
retry keeps `last_purge_bookmark` from the first attempt and never records a
|
|
896
|
+
bookmark taken after the erase.
|
|
897
|
+
|
|
898
|
+
The marker is a control-object operation, not just a flag. Workers built before
|
|
899
|
+
it already refuse every permit and restore while an operation is set, so a mixed
|
|
900
|
+
deploy fails closed on it. Limits:
|
|
901
|
+
|
|
902
|
+
- During a gradual deploy, a control object still on the previous Worker cannot
|
|
903
|
+
record the marker. Purge then releases its fence and fails before it erases
|
|
904
|
+
anything; retry it once the deploy finishes.
|
|
905
|
+
- Do not purge while a tenant Worker rollout is in progress. An edge Worker on
|
|
906
|
+
the previous build reaching a tenant object on the previous build runs the
|
|
907
|
+
old, unmarked purge.
|
|
908
|
+
- Rolling the tenant Worker back to a build from before the purge marker
|
|
909
|
+
un-protects interrupted purges. The marker still refuses permits there, but
|
|
910
|
+
that build's `POST /tenants/:id/cancel-restore` treats it as an uncertain
|
|
911
|
+
restore and can clear it.
|
|
912
|
+
|
|
913
|
+
## Migrations
|
|
914
|
+
|
|
915
|
+
Tenant tables have their own migrations in `quickback/drizzle/tenant/`. The
|
|
916
|
+
build bundles them into `quickback/drizzle/tenant/migrations.ts`, and each
|
|
917
|
+
object applies pending migrations when it wakes:
|
|
918
|
+
|
|
919
|
+
1. Inside `blockConcurrencyWhile`, so no request runs against an old schema.
|
|
920
|
+
2. All pending migrations in one transaction, recorded in `__qb_tenant_migrations`.
|
|
921
|
+
3. A point-in-time-recovery bookmark is taken first and reported to
|
|
922
|
+
`tenant_registry.last_pre_migration_bookmark`.
|
|
923
|
+
4. A failure never throws from the constructor. The object records it and
|
|
924
|
+
answers `503 TENANT_MIGRATION_FAILED` with the real SQLite error
|
|
925
|
+
(`0001_x: UNIQUE constraint failed: …`). The failing statement goes to the
|
|
926
|
+
logs and `tenant_registry.last_error`, never to the client. Other tenants
|
|
927
|
+
keep serving.
|
|
928
|
+
5. Before migrating, the object records which migrations it is attempting
|
|
929
|
+
and flushes that record (`storage.sync()`). A wake that finds the same
|
|
930
|
+
attempt unfinished was preceded by a reset mid-migration — the 30 s
|
|
931
|
+
`blockConcurrencyWhile` limit, but also eviction, a deploy or a failover —
|
|
932
|
+
so it retries. After 3 resets of the same pending set the object marks
|
|
933
|
+
itself failed instead of retrying on every request. A different migration
|
|
934
|
+
set starts a fresh count; `POST <api>/tenants/:id/retry-migration` clears
|
|
935
|
+
the count and migrates again.
|
|
936
|
+
|
|
937
|
+
SQL triggers on tenant tables — your [`sql:` triggers](/define/triggers#tenant-databases)
|
|
938
|
+
and the compiler's own (the FK `match` checks) — install in the same wake, after
|
|
939
|
+
the migrations, whenever their content hash changes or a migration ran (a table
|
|
940
|
+
recreate drops its triggers). They never reach the features D1. A dump restore
|
|
941
|
+
drops every table with its triggers, loads the rows with no trigger firing, then
|
|
942
|
+
runs this same wake, so the triggers come back; a point-in-time restore rewinds
|
|
943
|
+
the triggers together with the data.
|
|
944
|
+
|
|
945
|
+
Keep wake work well under 30 s. The object never sets an alarm while
|
|
946
|
+
recovering, so a failing wake cannot reset the platform's alarm retry budget.
|
|
947
|
+
|
|
948
|
+
Restoring the bookmark discards writes made after it. It recovers a failed
|
|
949
|
+
migration; it is not a rollback.
|
|
950
|
+
|
|
951
|
+
The build refuses drizzle-kit table-recreate migrations on tenant tables
|
|
952
|
+
(`TENANCY_UNSAFE_RECREATE`) when the table is referenced by another table, or
|
|
953
|
+
when the copy targets a NOT NULL column that was nullable or has no DEFAULT.
|
|
954
|
+
Inside the migration transaction `PRAGMA foreign_keys=OFF` is a no-op, so the
|
|
955
|
+
recreate's `DROP TABLE` cascade-deletes child rows in every tenant. No
|
|
956
|
+
migration is written. Make the change additive (a new nullable column or a new
|
|
957
|
+
table, backfilled by a data migration) and rebuild.
|
|
958
|
+
|
|
959
|
+
Keep tenant schemas additive across one release: during a rollout, objects
|
|
960
|
+
still on the previous Worker version read the same tables.
|
|
961
|
+
|
|
962
|
+
## Backups and restore
|
|
963
|
+
|
|
964
|
+
With `tenancy.backup` set, every tenant object backs itself up to R2 on its own
|
|
965
|
+
alarm. A write marks the object dirty and schedules the next backup `every`
|
|
966
|
+
later; an object nobody writes to runs no alarm and takes no backup. With
|
|
967
|
+
`every: 'off'` no dump is ever scheduled (a running one finishes and pending
|
|
968
|
+
ones are dropped on the next wake): point-in-time recovery (30 days) is then
|
|
969
|
+
the routine backup, and the bucket serves only operator backups, dump restores
|
|
970
|
+
and moving an organization between objects. A purge deletes the purged object's
|
|
971
|
+
dumps (the receipt-fenced one it was admitted with included): no copy outlives
|
|
972
|
+
the object except point-in-time recovery.
|
|
973
|
+
|
|
974
|
+
A backup is one NDJSON object at `<objectId>/<startedAt>-<uuid>.ndjson`: a header (the
|
|
975
|
+
object, its applied migrations, its tables), one line per row
|
|
976
|
+
(`{"t": table, "r": row}`, BLOBs as `{"$b64": …}`), and a footer with the row
|
|
977
|
+
count and the rows per table (`{"qb": "end", "rows": n, "counts": { table: n }}`;
|
|
978
|
+
every table in the header appears, empty ones as `0`). A dump restore checks
|
|
979
|
+
them before it touches anything: per-table counts that disagree with the rows
|
|
980
|
+
(either way) or do not add up to `rows` refuse the dump. Dumps written
|
|
981
|
+
before this footer gained `counts` have only `rows`. It streams in steps: each alarm reads tables in `rowid` order, uploads
|
|
982
|
+
R2 multipart parts of exactly 5 MiB (only the last part is smaller), and keeps
|
|
983
|
+
the leftover bytes and the `(table, rowid)` cursor in object-local storage, so
|
|
984
|
+
the next step resumes where the last stopped. When it finishes, the edge
|
|
985
|
+
records `tenant_registry.last_backup_at` / `last_backup_key` from the object's
|
|
986
|
+
outbox, and dumps older than `retainDays` are deleted.
|
|
987
|
+
|
|
988
|
+
An active tenant’s backup is **not a point-in-time snapshot**: rows written while it runs may
|
|
989
|
+
or may not be in it. For an exact copy, restore a point-in-time bookmark.
|
|
990
|
+
|
|
991
|
+
| Operator route | Effect |
|
|
992
|
+
|---|---|
|
|
993
|
+
| `POST /tenants/:id/backup` | Take a full backup now; returns `{ key, rows, counts, bytes, parts, startedAt, finishedAt, generation, archived }` |
|
|
994
|
+
| `GET /tenants/:id/backups` | List the object's dumps |
|
|
995
|
+
| `GET /tenants/:id/backups/counts?key=<key>` | One dump's footer, `{ key, rows, counts }`, from a single bounded read of the dump's last 256 KiB (the dump is never loaded). `counts` is `null` for a dump written before footers carried it. A key of another object is refused (`400 TENANT_BACKUP_READ_INVALID`), a missing dump is `404 TENANT_BACKUP_NOT_FOUND`. A tenant Worker older than this route answers `TENANT_RPC_VERSION_MISMATCH`: deploy the tenant Worker first. Also `tenantBackupCounts(env, id, key)` in `src/lib/tenants.ts`. |
|
|
996
|
+
| `GET /tenants/:id/bookmark` | The object's exact current point-in-time bookmark, `{ bookmark, observedAt }`. Record it before a risky change; restoring `{ "bookmark": "…" }` returns to exactly this point (never restore `{ at: observedAt }`, which is approximate). Refused for a purged object, or one whose purge is under way (its last bookmark is `tenant_registry.last_purge_bookmark`). |
|
|
997
|
+
| `GET /tenants/:id/outbox-receipts` | [Delivery receipts](#delivery-receipts): `?since=&limit=&outcome=` |
|
|
998
|
+
| `POST /tenants/:id/schedules/arm` `{ "types"?: [...] }` | Re-arm the organization's [tenant schedules](#tenant-schedules) (all, or the given job types); each runs after its debounce unless due sooner. Registered organization objects only. Returns `{ armed }`. `POST /tenants/schedules/arm-all` does every registered organization (bounded concurrency) — a manual one-off after a deploy, never a cron. |
|
|
999
|
+
| `POST /tenants/lookups/migrate` `{ "limit"?: n }` | With a [hashed lookup](#hashed-lookups): convert one page of pre-hash rows across objects. Returns `{ rekeyed, remaining }`; repeat until `remaining` is false. |
|
|
1000
|
+
| `POST /tenants/:id/rebuild-lookups` | Delete the object's platform lookup rows and re-publish every current key from its rows, under the primary `TENANT_LOOKUP_KEY` (after a [rotation](#hashed-lookups)). Its keys may not resolve until the drain finishes. Returns `{ applied }`. |
|
|
1001
|
+
| `POST /tenants/:id/restore` `{ "backupKey": "…" }` | Archived objects only. Restore a dump: drop every tenant table, re-create the schema at the dump's migrations, load its rows (one transaction), then apply the migrations added since. An old dump comes forward to the current schema. Refuses a dump from another object, a truncated dump, or one taken at migrations this Worker does not know. Returns `{ kind: "dump", backupKey, rows, pending: true }`; the object restarts and stays archived. Pending scheduled jobs are dropped (see [restore quarantine](#restore-quarantine)). |
|
|
1002
|
+
| `POST /tenants/:id/restore` `{ "bookmark": "…" }` or `{ "at": <ms or ISO> }` | Archived objects only. Point-in-time recovery (30 days): `onNextSessionRestoreBookmark`, then the object restarts. Writes after the bookmark are discarded. Returns `{ kind: "pitr", bookmark, undoBookmark, pending: true }`. A bookmark is exact. `at` is resolved with `getBookmarkForTime`, which Cloudflare documents as *approximate*: on a real deployment, writes made a few seconds before `at` were missing after the restore. For a precise target use `GET /tenants/:id/bookmark` beforehand, or the `undoBookmark` of an earlier restore. |
|
|
1003
|
+
|
|
1004
|
+
An operator backup on an **archived** organization acquires exclusive maintenance
|
|
1005
|
+
admission before scanning. It refuses with `TENANT_BUSY` while older requests,
|
|
1006
|
+
jobs or alarms still hold permits, abandons an unfinished active scan, and
|
|
1007
|
+
starts a fresh one while blocking unarchive, restore and purge. Its completed
|
|
1008
|
+
receipt has `archived: true` and the current `generation`. Active and scheduled
|
|
1009
|
+
backups have `archived: false` and retain the incremental behavior above.
|
|
1010
|
+
|
|
1011
|
+
### Reading a completed backup in operator application code
|
|
1012
|
+
|
|
1013
|
+
`readTenantBackup` from `src/lib/tenants.ts` transports the latest completed,
|
|
1014
|
+
quiescent backup through the tenant Worker. The backup bucket remains bound
|
|
1015
|
+
only to that Worker. No download HTTP route, arbitrary SQL, archived tenant-job
|
|
1016
|
+
admission or edge bucket access is added. Call this helper only after your
|
|
1017
|
+
application verifies the operator and target organization; it does not perform
|
|
1018
|
+
HTTP authentication itself, like the other operator helpers.
|
|
1019
|
+
|
|
1020
|
+
After `archiveTenant` and `backupTenant`, pass only the receipt's `key`,
|
|
1021
|
+
`generation` and `bytes` to
|
|
1022
|
+
`readTenantBackup(env, organizationId, { key, generation, bytes })`.
|
|
1023
|
+
The result is `{ key, generation, bytes, etag, data }`, with `data` an
|
|
1024
|
+
`ArrayBuffer` of the original encoded NDJSON. Use `new TextDecoder().decode(data)`
|
|
1025
|
+
only after the helper succeeds, then validate and project the application data
|
|
1026
|
+
you intend to retain. Keep raw dumps private; a dump contains all tenant tables.
|
|
1027
|
+
|
|
1028
|
+
The hard whole-buffer limit is **8 MiB of encoded bytes**. Optional `maxBytes`
|
|
1029
|
+
may lower that limit, never raise it. A larger dump fails with
|
|
1030
|
+
`TENANT_BACKUP_READ_TOO_LARGE`; it is not truncated. Do not purge a tenant when
|
|
1031
|
+
retention fails. Larger exports need a future bounded streaming protocol.
|
|
1032
|
+
|
|
1033
|
+
The helper requires the exact latest completed receipt, an archived organization,
|
|
1034
|
+
a matching current generation, and no writes since that backup. Old receipts,
|
|
1035
|
+
active backups, foreign keys, partition/control objects, changed byte lengths
|
|
1036
|
+
and malformed replies refuse. Legacy receipts without the new fields require a
|
|
1037
|
+
fresh archived backup. The tenant checks R2 metadata and the actual stream length,
|
|
1038
|
+
then returns binary bytes rather than base64 or a result-job JSON payload.
|
|
1039
|
+
Exclusive maintenance remains held through the body read: pending restore or
|
|
1040
|
+
purge refuses the read, and restore, purge or unarchive cannot begin during it.
|
|
1041
|
+
The edge checks the registry before and after the RPC; application workflows must
|
|
1042
|
+
still recheck their maintenance fingerprint before a later destructive operation.
|
|
1043
|
+
|
|
1044
|
+
This helper needs tenant RPC version 7. Deploy the tenant Worker before the edge
|
|
1045
|
+
Worker; an older tenant Worker cannot supply the new operation. A failed or
|
|
1046
|
+
ambiguous maintenance release keeps the existing recovery fence, requiring
|
|
1047
|
+
operator reconciliation rather than silently reopening admission.
|
|
1048
|
+
|
|
1049
|
+
The same operations are `backupTenant`, `listTenantBackups` and `restoreTenant`
|
|
1050
|
+
in `src/lib/tenants.ts`. Dump restore has an **8 MiB encoded NDJSON limit**
|
|
1051
|
+
(`413 TENANT_RESTORE_TOO_LARGE`), checked before reading the body or changing
|
|
1052
|
+
any table. Larger dumps need PITR until streaming restore is implemented.
|
|
1053
|
+
Restore cancels any in-progress multipart upload, clears its cursor and carry,
|
|
1054
|
+
and schedules a fresh backup. Both restore kinds and migration retry acquire exclusive
|
|
1055
|
+
admission before reading R2 or changing data. They refuse with `TENANT_BUSY`
|
|
1056
|
+
while previously admitted HTTP handlers, deferred `waitUntil` work (including
|
|
1057
|
+
nonblocking after-commit hooks and `effects.enqueue` callbacks), jobs, alarms or
|
|
1058
|
+
backup work remain in flight. HTTP responses return before nonblocking effects
|
|
1059
|
+
settle; their admission permits remain held through nested deferred work and
|
|
1060
|
+
release after success or rejection. Retry after that work finishes. New work is quarantined while the
|
|
1061
|
+
operation runs; a known success or failure releases its matching gate. An
|
|
1062
|
+
ambiguous operation or failed release retains quarantine for explicit operator
|
|
1063
|
+
recovery. Backup and restore operations are serialized.
|
|
1064
|
+
|
|
1065
|
+
Use `effects.enqueue`, nonblocking `afterCommit` hooks or
|
|
1066
|
+
`c.executionCtx.waitUntil(...)` for deferred tenant work. Authored access to the
|
|
1067
|
+
raw `waitUntil` export of `cloudflare:workers` is refused with
|
|
1068
|
+
`TENANCY_UNTRACKED_BACKGROUND` in tenant modules and their statically named
|
|
1069
|
+
relative authored dependencies, including aliases and helper re-exports that
|
|
1070
|
+
bypass the request's tracker. This includes a dynamic import's ordinary
|
|
1071
|
+
fulfillment callback reading the namespace through implicit `arguments[0]`,
|
|
1072
|
+
even when its declared parameter is unused or the access is in a nested arrow.
|
|
1073
|
+
Uninspectable argument or namespace escapes fail closed. Unrelated Cloudflare
|
|
1074
|
+
exports remain available when their access is explicit. External packages, path
|
|
1075
|
+
aliases and computed module names are outside this source-level check. Keep
|
|
1076
|
+
unrelated Cloudflare imports; use the
|
|
1077
|
+
tracked context instead of importing `waitUntil`. Await database work that must
|
|
1078
|
+
finish before the response. Arbitrary promises or timers launched without
|
|
1079
|
+
`await` or a tracked scheduler are outside this lifetime contract; do not retain
|
|
1080
|
+
a tenant database handle in them.
|
|
1081
|
+
A failed upload keeps its checkpoint and retries; writes during a backup
|
|
1082
|
+
schedule another backup after it completes.
|
|
1083
|
+
|
|
1084
|
+
### Restore quarantine
|
|
1085
|
+
|
|
1086
|
+
Every restore, dump or point-in-time, follows the same steps:
|
|
1087
|
+
|
|
1088
|
+
1. `POST /tenants/:id/archive`. A restore of an object that is not archived is
|
|
1089
|
+
refused (`tenancy: archive before restore`), as is a restore while an
|
|
1090
|
+
earlier one is pending (`TENANT_RESTORE_PENDING`).
|
|
1091
|
+
2. `POST /tenants/:id/restore`. It returns `pending: true`; the object restarts.
|
|
1092
|
+
3. `POST /tenants/:id/sync` reconciles the restore under a new outbox
|
|
1093
|
+
generation. The object is still archived.
|
|
1094
|
+
4. Inspect it, then `POST /tenants/:id/unarchive`. Nothing serves a restored
|
|
1095
|
+
object before this explicit step. Unarchive refuses
|
|
1096
|
+
(`TENANT_RESTORE_PENDING`) until step 3 has reconciled the restore, or while
|
|
1097
|
+
an unconfirmed restore or stranded maintenance fence is open — clear those
|
|
1098
|
+
with `POST /tenants/:id/cancel-restore`.
|
|
1099
|
+
|
|
1100
|
+
A dump carries no schedule: dump restore drops the object's pending scheduled
|
|
1101
|
+
jobs (`scheduleTenantJob`), its job-run dedupe records and its queued non-audit
|
|
1102
|
+
outbox entries in the same transaction as the load, so nothing scheduled
|
|
1103
|
+
against the replaced rows fires against the restored ones. Reschedule
|
|
1104
|
+
recurring work after unarchive. PITR instead rewinds the schedule to the
|
|
1105
|
+
bookmark with the rest of the database.
|
|
1106
|
+
|
|
1107
|
+
Restore first acquires an external admission
|
|
1108
|
+
gate: a small control object in the existing tenant namespace, under a reserved
|
|
1109
|
+
`__qb_control__:` name. The gate is outside the database being rewound. It
|
|
1110
|
+
refuses restore while requests or outbound jobs are in flight, then quarantines
|
|
1111
|
+
handlers, jobs and alarms until reconciliation. Control objects use the class's
|
|
1112
|
+
implicit `ctx.exports` namespace; no extra namespace or binding is provisioned.
|
|
1113
|
+
A tenant object does not ask its control object per request: it keeps the
|
|
1114
|
+
permit it was last granted as a lease and admits its own requests, jobs and
|
|
1115
|
+
alarms under it with no control RPC. The lease is an ordinary permit, so the
|
|
1116
|
+
gate still refuses restore while it is held. Restore, purge, migration retry
|
|
1117
|
+
and archived backups first revoke it: refused (`TENANT_BUSY`) while any work
|
|
1118
|
+
admitted under it (deferred callbacks included) is still running; otherwise
|
|
1119
|
+
the lease is released, and none is granted again until the fence is released.
|
|
1120
|
+
A lease admits work for at most 30 seconds; the next admission after that
|
|
1121
|
+
re-validates with the control object. An idle lease stays registered until it
|
|
1122
|
+
is revoked or replaced, so a control object reports `TENANT_BUSY` to any
|
|
1123
|
+
caller that skips the object's own revocation. A restart or eviction leaves
|
|
1124
|
+
its permit behind; the object's next admission, or the next restore's prune,
|
|
1125
|
+
removes it. Cross-object work (an outbox job from another
|
|
1126
|
+
object) still takes and releases the source object's permit per delivery.
|
|
1127
|
+
|
|
1128
|
+
Restore fences the old outbox generation and removes platform lookup rows.
|
|
1129
|
+
After a confirmed restore restarts the object, call `POST /tenants/:id/sync` to
|
|
1130
|
+
rebuild lookups under the new generation. Reconciliation discards the queued
|
|
1131
|
+
outbox entries other than audit rows and scope revocations, because they
|
|
1132
|
+
describe writes the restore replaced (a dump restore already dropped them with
|
|
1133
|
+
the load). A queued revocation is kept: rolling data back never un-revokes a
|
|
1134
|
+
claim. A dump restore is confirmed once its load commits; a dump that is
|
|
1135
|
+
refused (too large, truncated, another object's) changes nothing and releases
|
|
1136
|
+
quarantine like a rejected PITR prepare. `TENANT_RESTORE_PENDING` means the
|
|
1137
|
+
operation is unconfirmed or the old session has not restarted. A rejected
|
|
1138
|
+
prepare releases quarantine and restores its old lookup index. An unrelated
|
|
1139
|
+
restart never turns an unconfirmed prepare into a successful restore.
|
|
1140
|
+
|
|
1141
|
+
For an uncertain operation, inspect the current state and explicitly call
|
|
1142
|
+
`POST /tenants/:id/cancel-restore` with `{ "confirm": "<objectId>" }`. If the
|
|
1143
|
+
old session is still running, this first restarts it and returns pending; repeat
|
|
1144
|
+
the explicit recovery call after restart. Recovery keeps the current database
|
|
1145
|
+
and queued work, rebuilds lookups, and stays archived. A failed pre-invocation
|
|
1146
|
+
rollback resumes its recorded cleanup instead. Recovery owns one persisted
|
|
1147
|
+
mode so delayed cleanup cannot race abandonment. Once abandonment is claimed a
|
|
1148
|
+
restore can no longer be armed, but one that took effect anyway (a PITR
|
|
1149
|
+
bookmark is irreversible once scheduled; a dump load committed) is recorded in
|
|
1150
|
+
the control object: abandonment then discards queued non-audit outbox entries
|
|
1151
|
+
like a confirmed restore and returns `applied` (`{ bookmark, undoBookmark }` or
|
|
1152
|
+
`{ backupKey, rows }`; `null` when nothing applied). A restore whose arming RPC
|
|
1153
|
+
was lost before it reached the control object cannot be recorded; such an
|
|
1154
|
+
abandonment keeps queued work. A completed restore also stays archived;
|
|
1155
|
+
inspect it before `POST /tenants/:id/unarchive`. Never automatically retry the
|
|
1156
|
+
restore write.
|
|
1157
|
+
|
|
1158
|
+
### Authorization epoch
|
|
1159
|
+
|
|
1160
|
+
The control object also holds an **authorization epoch**, a counter that no
|
|
1161
|
+
restore can rewind. It is per object name: an organization object and each of
|
|
1162
|
+
its partition objects have their own. Every restore, dump or PITR, advances it
|
|
1163
|
+
when the restore begins, and keeps it across success, rollback and abandonment.
|
|
1164
|
+
Read it with `tenantAuthorizationEpoch(env, objectId)` in `src/lib/tenants.ts`
|
|
1165
|
+
(or the object's `authorizationEpoch` RPC), or with the
|
|
1166
|
+
[`qb.epoch` command](#tenant-commands), which reads it under the restore permit.
|
|
1167
|
+
|
|
1168
|
+
The epoch is exposed for admission checks; nothing enforces it yet. Enforcement
|
|
1169
|
+
arrives with tenant admission (plan 032): credentials pinned to an earlier
|
|
1170
|
+
epoch will then be refused, so a restore forces re-login even when restored
|
|
1171
|
+
rows would grant the old access again. Restore does not call `/oauth2/revoke`.
|
|
1172
|
+
|
|
1173
|
+
Point-in-time recovery does not run under local `wrangler dev`. The staging
|
|
1174
|
+
account drill remains an open release gate: write A, note time T, write B,
|
|
1175
|
+
archive, restore to T, sync after restart, and verify A remains, B is gone,
|
|
1176
|
+
lookup entries match the restored rows, and scheduled work resumes safely.
|
|
1177
|
+
Do not treat the local reconciliation simulation as a completed PITR drill. The R2 dump/restore drill runs locally in the
|
|
1178
|
+
`tenant-do` output-matrix fixture.
|
|
1179
|
+
|
|
1180
|
+
## Background work
|
|
1181
|
+
|
|
1182
|
+
Per-tenant alarms replace global "every minute, scan every organization"
|
|
1183
|
+
sweeps. Each object has one alarm, shared by backups and tenant jobs, driven by
|
|
1184
|
+
a schedule table: a due row is moved to its retry time before the work runs,
|
|
1185
|
+
and a finished occurrence is recorded before its row is removed, so a crash
|
|
1186
|
+
retries the same occurrence up to five attempts. Handlers must make external
|
|
1187
|
+
side effects idempotent. Canceling or replacing a due occurrence prevents its
|
|
1188
|
+
stale snapshot from running; rescheduling at the same time creates a new
|
|
1189
|
+
occurrence. Unarchiving re-arms suspended work.
|
|
1190
|
+
|
|
1191
|
+
A **tenant job** is a `services/queues` handler that runs inside a tenant
|
|
1192
|
+
object. Mark it `tenant: true` (implied when it imports an unpartitioned tenant
|
|
1193
|
+
feature). A handler may not mix platform and tenant imports; a feature with no
|
|
1194
|
+
tables (helpers only) is neither, so either kind may import it. Partitioned
|
|
1195
|
+
feature imports are refused until explicit partition queue routing is supported.
|
|
1196
|
+
Inside a tenant job, `tenant` on the execute context supplies scheduling,
|
|
1197
|
+
cancellation and outbox delivery; it is absent for platform handlers.
|
|
1198
|
+
|
|
1199
|
+
{/* doc-compile: skip — needs a reminders feature */}
|
|
1200
|
+
```ts title="quickback/services/queues/reminderDue.ts"
|
|
1201
|
+
import { eq } from "drizzle-orm";
|
|
1202
|
+
import { defineQueue } from "@quickback/compiler";
|
|
1203
|
+
import { reminders } from "../../features/reminders/schema";
|
|
1204
|
+
|
|
1205
|
+
export default defineQueue<{ type: "reminder.due"; tenantId: string; reminderId: string }>({
|
|
1206
|
+
name: "reminderDue",
|
|
1207
|
+
messageType: "reminder.due",
|
|
1208
|
+
tenant: true,
|
|
1209
|
+
execute: async ({ message, db }) => {
|
|
1210
|
+
db.update(reminders).set({ sentAt: new Date().toISOString() }).where(eq(reminders.id, message.reminderId)).run();
|
|
1211
|
+
return { success: true };
|
|
1212
|
+
},
|
|
1213
|
+
});
|
|
1214
|
+
```
|
|
1215
|
+
|
|
1216
|
+
The same handler runs three ways:
|
|
1217
|
+
|
|
1218
|
+
| Trigger | How |
|
|
1219
|
+
|---|---|
|
|
1220
|
+
| Queue | A producer sends `{ type, tenantId, … }`; the edge consumer routes it to that tenant's object (`runJob`). A message literal for a tenant job without `tenantId` fails the build (`TENANCY_QUEUE_TENANT_ID`); at runtime one without it is retried into the dead-letter queue. |
|
|
1221
|
+
| Alarm | `tenantRuntime(env).schedule(key, at, message)` from a tenant action or job, or `scheduleTenantJob(env, tenantId, key, at, message)` on the edge. One pending occurrence per key; a job reschedules its own key for the next due item. |
|
|
1222
|
+
| Outbox | `tenantRuntime(env).send(target, message)` — see [Partitions](#partitions). |
|
|
1223
|
+
| Platform queue | A tenant action or job calls `tenantRuntime(env).enqueue(binding, message)`; the edge sends it to a platform queue and that queue's consumer routes it — see [Platform queues](#platform-queues). |
|
|
1224
|
+
|
|
1225
|
+
Tenant actions import `tenantRuntime` from their `define-action` helper:
|
|
1226
|
+
|
|
1227
|
+
{/* doc-compile: skip — action body fragment */}
|
|
1228
|
+
```ts
|
|
1229
|
+
await tenantRuntime(env).schedule("reminder:" + row.id, Date.parse(row.remindAt), { type: "reminder.due", reminderId: row.id });
|
|
1230
|
+
```
|
|
1231
|
+
|
|
1232
|
+
`schedule`, `send` and the edge helpers stamp `tenantId`. Each run gets a
|
|
1233
|
+
`runId`, stable per occurrence or message: use it as the idempotency key for
|
|
1234
|
+
external side effects (email, SMS, payments).
|
|
1235
|
+
Concurrent deliveries of one `runId` share an in-flight execution in the live
|
|
1236
|
+
object. Completion is recorded only on success. A crash after an external effect
|
|
1237
|
+
but before durable completion can repeat that effect: delivery remains
|
|
1238
|
+
at-least-once, so handlers must use that idempotency key externally.
|
|
1239
|
+
|
|
1240
|
+
Tenant jobs honor `ack()` and `retry()` for queues, alarms and outbox delivery.
|
|
1241
|
+
`retry()` is sticky and wins over a later `ack()` or a successful return; no
|
|
1242
|
+
completion marker is recorded for that attempt.
|
|
1243
|
+
|
|
1244
|
+
After an alarm, the object asks its edge to drain what the alarm left in the
|
|
1245
|
+
outbox (queue sends, realtime, lookups) through the edge's
|
|
1246
|
+
`QuickbackTenantOutbox` entrypoint — the tenant Worker binds it as
|
|
1247
|
+
`__QB_EDGE_OUTBOX` (generated in `wrangler.tenant.jsonc`, each target its own
|
|
1248
|
+
edge). While entries remain (the edge unreachable, entries backing off), an
|
|
1249
|
+
internal alarm asks again — after 30 s, doubling to an hour while a drain
|
|
1250
|
+
makes no progress — so delivery never waits for the tenant's next request and
|
|
1251
|
+
no cron sweeps the objects. Without the binding it does not poll: the next
|
|
1252
|
+
request or operator sync drains. A named entrypoint is reachable only through
|
|
1253
|
+
a service binding, never over HTTP; tenant app code does not see the binding,
|
|
1254
|
+
and the edge drains only registered objects (an unknown name is refused, never
|
|
1255
|
+
woken). Keys starting `qb:` (`qb:backup`, `qb:outbox-flush`,
|
|
1256
|
+
`qb:schedule:<type>`) belong to the runtime: `schedule` / `cancel` and the edge
|
|
1257
|
+
helpers refuse them (`TENANT_JOB_INVALID`).
|
|
1258
|
+
|
|
1259
|
+
An alarm that throws retries the same occurrence with backoff (10 s, doubling,
|
|
1260
|
+
capped at an hour). After five attempts it is a **dead letter**: a `failed`
|
|
1261
|
+
[delivery receipt](#delivery-receipts) of kind `alarm` (`target` the key,
|
|
1262
|
+
`method` the job type, `reason` `TENANT_ALARM_DEAD_LETTER: …` with the last
|
|
1263
|
+
error). A one-off occurrence is then dropped; a [tenant
|
|
1264
|
+
schedule](#tenant-schedules) runs again an hour later, and writes to its
|
|
1265
|
+
watched tables do not bring that retry forward.
|
|
1266
|
+
|
|
1267
|
+
### Tenant schedules
|
|
1268
|
+
|
|
1269
|
+
A **tenant schedule** is recurring per-tenant work with no cron and no global
|
|
1270
|
+
scan: a tenant job with `schedule:`, run on each organization's own alarm. It
|
|
1271
|
+
runs when it is due and returns `next` — when it is due again (ms or a
|
|
1272
|
+
`Date`), or `null` to sleep. An organization with nothing due never wakes.
|
|
1273
|
+
|
|
1274
|
+
{/* doc-compile: skip — needs a reminders feature */}
|
|
1275
|
+
```ts title="quickback/services/queues/remindersTick.ts"
|
|
1276
|
+
import { and, eq, isNull, lte, min } from "drizzle-orm";
|
|
1277
|
+
import { defineQueue } from "@quickback/compiler";
|
|
1278
|
+
import { reminders } from "../../features/reminders/schema";
|
|
1279
|
+
|
|
1280
|
+
export default defineQueue<{ type: "reminders.tick"; tenantId: string }>({
|
|
1281
|
+
name: "remindersTick",
|
|
1282
|
+
messageType: "reminders.tick",
|
|
1283
|
+
tenant: true,
|
|
1284
|
+
// Writes to these tables (any request, job or alarm) re-arm it.
|
|
1285
|
+
schedule: { watch: ["reminders"], debounceSeconds: 5 },
|
|
1286
|
+
execute: async ({ db, tenant, runId, schedule }) => {
|
|
1287
|
+
const now = new Date().toISOString();
|
|
1288
|
+
for (const r of await db.select().from(reminders).where(and(isNull(reminders.sentAt), lte(reminders.dueAt, now)))) {
|
|
1289
|
+
db.update(reminders).set({ sentAt: now }).where(eq(reminders.id, r.id)).run();
|
|
1290
|
+
tenant!.enqueue("EMAIL_QUEUE", { type: "reminder.send", reminderId: r.id });
|
|
1291
|
+
}
|
|
1292
|
+
const [next] = await db.select({ at: min(reminders.dueAt) }).from(reminders).where(isNull(reminders.sentAt));
|
|
1293
|
+
return { success: true, next: next?.at ? Date.parse(next.at) : null };
|
|
1294
|
+
},
|
|
1295
|
+
});
|
|
1296
|
+
```
|
|
1297
|
+
|
|
1298
|
+
- **Re-arming.** SQL triggers on the `watch`ed tables (tenant tables of the
|
|
1299
|
+
organization object, by export or SQL name) mark the schedule in the write's
|
|
1300
|
+
own transaction, so every write path counts — actions, jobs, bulk
|
|
1301
|
+
statements. After each request, job or alarm the object re-arms marked
|
|
1302
|
+
schedules `debounceSeconds` later (default 5, 0–3600), unless one is already
|
|
1303
|
+
due sooner or is backing off after a failure: a re-arm never postpones a run
|
|
1304
|
+
or resets a retry budget. The schedule's own writes never mark it (no
|
|
1305
|
+
self-re-arm loop). A request (its deferred work included), command or job
|
|
1306
|
+
that overlapped the run while a watched table was written (an unmuted
|
|
1307
|
+
per-schedule write counter) brings the next run forward to the debounce —
|
|
1308
|
+
at most one extra run per overlapping operation, since the counter also
|
|
1309
|
+
sees the run's own writes. A watched name that resolves to no table is
|
|
1310
|
+
skipped and logged (`tenant.schedule.table_unresolved`).
|
|
1311
|
+
- **From the edge.** `armTenantSchedules(env, tenantId, types?)` re-arms an
|
|
1312
|
+
organization's schedules (all, or the given job types) for a change its
|
|
1313
|
+
writes cannot see — an edge-side row, a deploy. A deploy that adds or changes
|
|
1314
|
+
a schedule marks it on each organization's next wake; operators can arm
|
|
1315
|
+
everyone at once with `POST /tenants/schedules/arm-all` (a manual, bounded
|
|
1316
|
+
one-off — never a cron) or one organization with
|
|
1317
|
+
`POST /tenants/:id/schedules/arm`. An explicit arm also cuts a dead-letter
|
|
1318
|
+
cooldown short (after deploying a fix); a write does not.
|
|
1319
|
+
- **At least once.** A run is an alarm occurrence: `runId` is stable for it, a
|
|
1320
|
+
throw retries it with backoff and a dead letter is recorded as above; the
|
|
1321
|
+
schedule itself never stops. Completion is recorded only after the next
|
|
1322
|
+
occurrence is written; an occurrence found already complete is evaluated
|
|
1323
|
+
again after the debounce, never dropped.
|
|
1324
|
+
- **Restores.** A point-in-time restore rewinds the schedule rows, the marks
|
|
1325
|
+
and the data together, so they stay consistent; the platform alarm is re-armed
|
|
1326
|
+
from the rows when the object serves again, and every schedule is marked for
|
|
1327
|
+
one fresh evaluation. Work due between the restore target and the restore
|
|
1328
|
+
may have run on the abandoned timeline and runs again: `schedule.restoredAt`
|
|
1329
|
+
(the last restore, ms, or null) on the execute context lets a handler skip
|
|
1330
|
+
external side effects for it. A dump restore keeps the alarm rows (they are
|
|
1331
|
+
not tenant tables) and marks every schedule the same way.
|
|
1332
|
+
- **Placement.** Schedules run in organization objects only. `schedule:`
|
|
1333
|
+
needs `tenant: true`, is refused on a result job, on a `qb:`-prefixed type,
|
|
1334
|
+
and in shared tenancy (`TENANCY_SCHEDULE`); it must be `true` or a literal
|
|
1335
|
+
object.
|
|
1336
|
+
|
|
1337
|
+
### Platform queues
|
|
1338
|
+
|
|
1339
|
+
Tenant code has no queue bindings (`TENANCY_ENV_UNAVAILABLE`). To hand work to
|
|
1340
|
+
the edge — email, push, webhooks — it sends a message to one of the edge
|
|
1341
|
+
Worker's queue bindings through the object's outbox:
|
|
1342
|
+
|
|
1343
|
+
{/* doc-compile: skip — action body fragment */}
|
|
1344
|
+
```ts
|
|
1345
|
+
import { defineAction, tenantRuntime } from "../.quickback/define-action";
|
|
1346
|
+
// …
|
|
1347
|
+
tenantRuntime(env).enqueue("COMMS_QUEUE", { type: "mail.send", guestId: row.id });
|
|
1348
|
+
```
|
|
1349
|
+
|
|
1350
|
+
- **Same write.** The call writes an outbox row with the request's writes. The
|
|
1351
|
+
edge drains the outbox after the response and calls
|
|
1352
|
+
`env.COMMS_QUEUE.send({ ...message, tenantId, dedupeKey })`. The row is
|
|
1353
|
+
written at the call: it is not dropped if `execute` later throws or returns
|
|
1354
|
+
a dry run. To send only after a successful `execute`, use
|
|
1355
|
+
`effects.enqueue(binding, message)`.
|
|
1356
|
+
- **`tenantId` comes from the object.** The edge stamps the tenant from the
|
|
1357
|
+
object's name. A message that sets `tenantId` or `dedupeKey` itself throws
|
|
1358
|
+
(`TENANT_QUEUE_MESSAGE`); nothing is written.
|
|
1359
|
+
- **At least once.** A failed send keeps the entry queued and it is retried
|
|
1360
|
+
with backoff ([outbox delivery](#outbox-delivery)), so a consumer can see a
|
|
1361
|
+
message twice. `dedupeKey` (a UUID fixed when the row is written) is the same
|
|
1362
|
+
on every delivery: use it as the consumer's idempotency key.
|
|
1363
|
+
- **Receipts.** `enqueue(binding, message, { ref })` records `ref` (1–200
|
|
1364
|
+
characters) on the row's [delivery receipt](#delivery-receipts). Point it at
|
|
1365
|
+
your own per-send row, such as a `comms_log` id, instead of copying that row
|
|
1366
|
+
into the receipt. The receipt also carries the `dedupeKey`, so a consumer that
|
|
1367
|
+
stores `dedupeKey` on its row links the two the other way.
|
|
1368
|
+
- **Size.** A message over 120 KiB of JSON, or one that is not
|
|
1369
|
+
JSON-serializable, throws at the call (`TENANT_QUEUE_MESSAGE_TOO_LARGE`,
|
|
1370
|
+
`TENANT_QUEUE_MESSAGE`). A row the edge can never send (a binding missing
|
|
1371
|
+
from the edge Worker, a message the queue refuses) is dead-lettered so it
|
|
1372
|
+
does not block the outbox.
|
|
1373
|
+
- **Declared bindings only.** The binding must be one of the edge Worker's
|
|
1374
|
+
queues (the primary queue and `additionalQueues`). The build refuses any
|
|
1375
|
+
other name, or a name it cannot read (not a string literal), in tenant
|
|
1376
|
+
actions, tenant jobs, JS trigger handlers and the helpers they import
|
|
1377
|
+
(`TENANCY_QUEUE_BINDING`); at runtime the object refuses it
|
|
1378
|
+
(`TENANT_QUEUE_UNKNOWN`), and the drain dead-letters a row naming an
|
|
1379
|
+
unknown binding.
|
|
1380
|
+
- A tenant job uses `tenant.enqueue(binding, message)`, the same call.
|
|
1381
|
+
`effects.enqueue(binding, message)` and table-level transition
|
|
1382
|
+
`onEnter.enqueue` steps in tenant features route through it too, after
|
|
1383
|
+
`execute` succeeds and before the response. A refusal there
|
|
1384
|
+
(`TENANT_QUEUE_*`) fails the response.
|
|
1385
|
+
|
|
1386
|
+
The consumer is a platform queue handler: it runs on the edge, with the
|
|
1387
|
+
platform D1. If it needs the tenant's data, it calls a
|
|
1388
|
+
[result job](#result-jobs) with `message.tenantId`. That value is
|
|
1389
|
+
authoritative only for messages from a tenant outbox (the edge stamped it). A
|
|
1390
|
+
queue that edge code also produces to carries whatever that producer wrote:
|
|
1391
|
+
edge producers must set `tenantId` from the caller's `ctx`
|
|
1392
|
+
(`ctx.activeOrgId`), never from request input. A restore discards queued `queue` entries with the other outbox
|
|
1393
|
+
entries that are neither audit rows nor scope revocations.
|
|
1394
|
+
|
|
1395
|
+
### Result jobs
|
|
1396
|
+
|
|
1397
|
+
Edge code sometimes needs an answer from a tenant's database: a public page
|
|
1398
|
+
showing an organization's data, or a platform action that reads tenant state.
|
|
1399
|
+
Edge code can't query tenant tables (`TENANCY_ADMISSION_DEPENDENCY`), and
|
|
1400
|
+
cross-tenant `unsafe` or root-path actions can't move into a tenant feature
|
|
1401
|
+
(`TENANCY_UNSAFE_ACTION`, `TENANCY_ROOT_ACTION`). They stay on the edge, in a
|
|
1402
|
+
platform feature, and call a **result job**: a tenant job declared with
|
|
1403
|
+
`result: true` and a `resultSchema`.
|
|
1404
|
+
|
|
1405
|
+
{/* doc-compile: skip — needs a reminders feature */}
|
|
1406
|
+
```ts title="quickback/services/queues/reminderCount.ts"
|
|
1407
|
+
import { z } from "zod";
|
|
1408
|
+
import { eq } from "drizzle-orm";
|
|
1409
|
+
import { defineQueue } from "@quickback/compiler";
|
|
1410
|
+
import { reminders } from "../../features/reminders/schema";
|
|
1411
|
+
|
|
1412
|
+
export default defineQueue<{ type: "reminder.count"; tenantId: string; ownerId: string }>({
|
|
1413
|
+
name: "reminderCount",
|
|
1414
|
+
messageType: "reminder.count",
|
|
1415
|
+
tenant: true,
|
|
1416
|
+
result: true,
|
|
1417
|
+
resultSchema: z.object({ open: z.number().int() }),
|
|
1418
|
+
execute: async ({ message, db }) => {
|
|
1419
|
+
const rows = await db.select().from(reminders).where(eq(reminders.ownerId, message.ownerId));
|
|
1420
|
+
return { success: true, result: { open: rows.filter((r) => !r.sentAt).length } };
|
|
1421
|
+
},
|
|
1422
|
+
});
|
|
1423
|
+
```
|
|
1424
|
+
|
|
1425
|
+
{/* doc-compile: skip — action body fragment */}
|
|
1426
|
+
```ts
|
|
1427
|
+
import { callTenantJob, resolveTenant } from "../../../lib/tenants";
|
|
1428
|
+
|
|
1429
|
+
const tenantId = await resolveTenant(env, "inviteCode", input.code); // or ctx.activeOrgId
|
|
1430
|
+
if (!tenantId) throw new ActionError("Unknown code", "NOT_FOUND", 404);
|
|
1431
|
+
// The edge action is the only authorization gate: check here that this caller may ask this question.
|
|
1432
|
+
const runId = "reminder-count:" + crypto.randomUUID(); // built on the server, never from the request
|
|
1433
|
+
const res = await callTenantJob<{ open: number }>(env, tenantId, { type: "reminder.count", ownerId: input.ownerId }, runId);
|
|
1434
|
+
if (res.status === "unavailable") throw new ActionError("Try again shortly", res.code, 503);
|
|
1435
|
+
if (res.status === "failed") throw new ActionError("Lookup failed", "LOOKUP_FAILED", 422); // res.error stays server-side
|
|
1436
|
+
return res.result;
|
|
1437
|
+
```
|
|
1438
|
+
|
|
1439
|
+
`callTenantJob(env, tenantId, message, runId)` returns
|
|
1440
|
+
`{ status: 'ok', result } | { status: 'failed', error } | { status: 'unavailable', code }`:
|
|
1441
|
+
|
|
1442
|
+
| Result | When |
|
|
1443
|
+
|---|---|
|
|
1444
|
+
| `ok` | The handler returned `{ success: true, result }`. The object validated `result` against `resultSchema` and checked that it serializes to at most **256 KiB**, then recorded it with the run marker in one transaction. |
|
|
1445
|
+
| `failed` | The handler returned `{ success: false, error }` (that `error`, capped at 200 characters), threw (`TENANT_JOB_FAILED`; the error text is never returned, only logged as the job type and code), called `retry()`, or its result failed the schema (`TENANT_JOB_RESULT_INVALID`) or the size cap (`TENANT_JOB_RESULT_TOO_LARGE`). Also `TENANT_JOB_RUN_CONFLICT`, below. Nothing is recorded, so the same `runId` runs again. Writes the handler made are kept: key them by `runId`. |
|
|
1446
|
+
| `unavailable` | The registry gate shared with [tenant commands](#tenant-commands) (`TENANT_NOT_PROVISIONED`, `TENANT_PURGED`, `TENANT_JURISDICTION_MISMATCH`, `TENANT_UNAVAILABLE`), an archived, purged or unmigrated object (`TENANT_ARCHIVED`, `TENANT_PURGED`, `TENANT_MIGRATION_FAILED`), a pending restore, an RPC failure (`TENANT_OVERLOADED`, …), version skew, or a malformed reply (`TENANT_JOB_REPLY_INVALID`). The job may or may not have run. |
|
|
1447
|
+
|
|
1448
|
+
`resultSchema` must be `z.object({ … })`, which strips unknown keys, or a
|
|
1449
|
+
strict object (`z.strictObject`, `.strict()`), which refuses them, written
|
|
1450
|
+
inline or as a top-level const. A passthrough, loose or catchall schema fails
|
|
1451
|
+
the build (`TENANCY_JOB_RESULT_SCHEMA`).
|
|
1452
|
+
|
|
1453
|
+
A repeated `runId` with the same message replays the recorded result without
|
|
1454
|
+
running the handler again, for seven days; after that the `runId` runs again.
|
|
1455
|
+
`resultTtlSeconds` (a number literal, 60 to 604800) shortens that for one job:
|
|
1456
|
+
a result older than that is gone (with its run marker) the next time its
|
|
1457
|
+
`runId` is called, and expired results are deleted whenever a result is
|
|
1458
|
+
recorded or the object's alarm runs. Use it for read-only pulls, such as an
|
|
1459
|
+
export that reads pages of the tenant's data, whose results should not sit in
|
|
1460
|
+
the tenant's SQLite for a week. The 60-second floor keeps `callTenantJob`'s
|
|
1461
|
+
own resend after an object reset (same `runId`) a replay rather than a second
|
|
1462
|
+
run. Anything else (a non-literal, out of range, or without `result: true`)
|
|
1463
|
+
fails the build (`TENANCY_JOB_RESULT_TTL`).
|
|
1464
|
+
The result is bound to a hash of the canonical message (sorted keys): the same
|
|
1465
|
+
`runId` with any other field is `failed` / `TENANT_JOB_RUN_CONFLICT`, never
|
|
1466
|
+
the earlier caller's result. Calls have their own run-id space (`call:` on the
|
|
1467
|
+
object; `runJob` and `deliverTenantJob` refuse run ids with that prefix), so a
|
|
1468
|
+
call never replays a queue, alarm or outbox run. Concurrent calls with one
|
|
1469
|
+
`runId` and one message share one execution. Build the `runId` on the server
|
|
1470
|
+
(a fresh id, or one from your own idempotency record), never from request
|
|
1471
|
+
input. The call is retried once after an object reset or a retryable RPC
|
|
1472
|
+
error, and drains the object's outbox after an `ok`.
|
|
1473
|
+
|
|
1474
|
+
**Authorization.** A result job runs with system rights in the tenant's object:
|
|
1475
|
+
no caller, no firewall, no access rules. The edge code that calls it is the
|
|
1476
|
+
only authorization gate, so check there that this caller may ask this
|
|
1477
|
+
question. The build requires the tenant argument to be visibly server-verified
|
|
1478
|
+
(`TENANCY_JOB_CALL_TENANT_SOURCE`): `ctx.activeOrgId` / `ctx.tenantId`, a
|
|
1479
|
+
`resolveTenant(...)` or `resolvePrincipalTenant(...)` result (directly or
|
|
1480
|
+
through a `const`), or a `forEachTenant` callback's tenant. If it is verified
|
|
1481
|
+
another way, such as a signed webhook naming the organization, put
|
|
1482
|
+
`// quickback-allow-tenant-source: <reason>` on the line above the call.
|
|
1483
|
+
|
|
1484
|
+
The object refuses, before the job runs, a message that is not a result job,
|
|
1485
|
+
a message for another tenant, a partition or control object, or a missing
|
|
1486
|
+
`runId` (`TENANT_JOB_INVALID`). It sets `tenantId` from the object's name. The
|
|
1487
|
+
edge helper throws on the same caller bugs. Pass only a server-verified
|
|
1488
|
+
organization id: a session's organization, or one resolved through
|
|
1489
|
+
[`tenancy.lookups`](#lookup-indexes).
|
|
1490
|
+
|
|
1491
|
+
A result job is only ever called. A `{ type: '<result job>' }` message literal
|
|
1492
|
+
anywhere but `callTenantJob`'s message argument fails the build
|
|
1493
|
+
(`TENANCY_JOB_RESULT_PRODUCER`), and at runtime `runJob`, `schedule`, `send`,
|
|
1494
|
+
`deliverTenantJob` and `scheduleTenantJob` refuse it (`TENANT_JOB_CALL_ONLY`).
|
|
1495
|
+
One that reaches a queue anyway is retried into the dead-letter queue. An
|
|
1496
|
+
outbox entry or a scheduled alarm for a job that has since become a result job
|
|
1497
|
+
is dropped as a dead letter (logged), so it never blocks the outbox or the
|
|
1498
|
+
alarm.
|
|
1499
|
+
`resultSchema` is required with `result: true`, `result` must be the literal
|
|
1500
|
+
`true`, and the handler must be a tenant job (`TENANCY_JOB_RESULT_SCHEMA`).
|
|
1501
|
+
Result jobs need `isolation: 'durable-object'`.
|
|
1502
|
+
|
|
1503
|
+
Realtime broadcasts from tenant tables (`realtime: { enabled: true }`) are
|
|
1504
|
+
recorded in the object's outbox with the write and replayed by the edge through
|
|
1505
|
+
the Broadcaster as the response returns ([outbox delivery](#outbox-delivery)).
|
|
1506
|
+
`createRealtime` in tenant code has the
|
|
1507
|
+
edge's shape, `defineRealtime` namespaces included: `realtime.<namespace>.<event>(…)`
|
|
1508
|
+
is queued as the same `broadcast('<namespace>:<event>', …)` the edge sends.
|
|
1509
|
+
|
|
1510
|
+
### Outbox delivery
|
|
1511
|
+
|
|
1512
|
+
Everything a tenant object hands the edge goes through its outbox, a table in
|
|
1513
|
+
the object's SQLite written in the same transaction as the writes that caused
|
|
1514
|
+
it:
|
|
1515
|
+
- realtime frames;
|
|
1516
|
+
- `audit_events` rows;
|
|
1517
|
+
- lookup-index changes;
|
|
1518
|
+
- jobs for other objects;
|
|
1519
|
+
- platform queue messages;
|
|
1520
|
+
- scope revocations ([`revocationCheck: 'kv'`](#scope-revocation)).
|
|
1521
|
+
|
|
1522
|
+
The edge delivers each entry at least once, even if the request's `waitUntil`
|
|
1523
|
+
is cut off.
|
|
1524
|
+
|
|
1525
|
+
- **Claimed, never shared.** An entry is claimed before anything applies it:
|
|
1526
|
+
the object reads it and leases it to that claimer for 30 seconds in one
|
|
1527
|
+
synchronous turn. Two drains, two responses, or a response and a sweep never
|
|
1528
|
+
hold the same entry, so a frame is not broadcast twice.
|
|
1529
|
+
- **In the response.** A `handle()` response carries what it claimed: at most
|
|
1530
|
+
32 entries, or 32 KiB of them, in the `x-quickback-tenant-outbox-claim`
|
|
1531
|
+
header, which the edge strips. The edge does not call the object again to
|
|
1532
|
+
fetch them. Entries over those caps stay claimable. The response says how
|
|
1533
|
+
many remain, and the edge claims them with `claimOutbox`.
|
|
1534
|
+
- **Realtime first.** The edge publishes the claimed realtime frames before
|
|
1535
|
+
the response leaves it, in seq order within a claim, one Broadcaster call at
|
|
1536
|
+
a time. No D1 read or write happens before them. The registry report and
|
|
1537
|
+
the D1 bookkeeping run beside the frames, never in front of them.
|
|
1538
|
+
- **Revocations beside realtime.** `revoke` entries are stamped into the
|
|
1539
|
+
edge's revocation KV as soon as a claim arrives, beside the realtime frames
|
|
1540
|
+
and never behind the D1 bookkeeping or the restore fence. Like the frames,
|
|
1541
|
+
the write starts before the response leaves the edge, and for a kind the
|
|
1542
|
+
tenant admits (a tenant-backed scope kind) the response does not wait for
|
|
1543
|
+
it. Every lane that admits such a claim (the namespace gate, edge actions,
|
|
1544
|
+
tickets, refresh and authorize) re-proves it against the tenant's own rows,
|
|
1545
|
+
which the same write changed, so the removed subject is refused on its very
|
|
1546
|
+
next request, whatever KV says. A revocation of any other kind (a manual
|
|
1547
|
+
`revokeScopeTokens` on a platform kind, whose claims are proven against the
|
|
1548
|
+
platform database) has no such check, so a response carrying one returns
|
|
1549
|
+
once the KV is written (waiting at most 2 seconds). That makes the
|
|
1550
|
+
revocation visible at once in the location that wrote it; elsewhere it
|
|
1551
|
+
arrives within KV's propagation time (up to about a minute). Each
|
|
1552
|
+
(subject, kind, instance) is written once per claim. A KV failure or a
|
|
1553
|
+
missing `KV` binding retries the entry; a revocation is never dropped. An
|
|
1554
|
+
entry whose request ended before it was written is claimed again by the
|
|
1555
|
+
next response or drain for that object once its 30-second lease lapses.
|
|
1556
|
+
- **Ordered lane.** Lookup and registry entries go to D1 in one batch, guarded
|
|
1557
|
+
by `tenant_registry.outbox_seq` and the restore fence
|
|
1558
|
+
(`outbox_generation`, `restore_session`), which the batch reads back.
|
|
1559
|
+
Only one claim holding them is in flight at a time, and a later one is never
|
|
1560
|
+
claimed before an earlier one, so the index sees them in order. Audit rows,
|
|
1561
|
+
jobs and queue messages are applied only when that fence holds; otherwise
|
|
1562
|
+
they are released for the reconciling drain.
|
|
1563
|
+
- **Settled, with a receipt.** The edge reports each entry back as one of:
|
|
1564
|
+
- `delivered`: the row is deleted.
|
|
1565
|
+
- `retry`: the row is kept and released with backoff (1 s doubling to
|
|
1566
|
+
60 s). A realtime frame is retried three times, then recorded failed.
|
|
1567
|
+
- `failed`: the row is dead-lettered (`__qb_outbox_dead`, counted in
|
|
1568
|
+
`tenant_registry.outbox_dead_letters`), or dropped for realtime.
|
|
1569
|
+
|
|
1570
|
+
Settlements ride on the edge's next request to that object from the same
|
|
1571
|
+
isolate. Only if a settlement is still waiting a second later does one
|
|
1572
|
+
`settleOutbox` call carry everything pending, in calls of at most 64.
|
|
1573
|
+
Failures, fence releases, and a claim that holds later lookup or registry
|
|
1574
|
+
rows back settle at once. Any other claim holding lookup or registry rows
|
|
1575
|
+
waits only 50 ms for a request to carry it. Until it settles, the lane is
|
|
1576
|
+
blocked, and an isolate that dies inside that window leaves the lane blocked
|
|
1577
|
+
until the lease expires and the next response or sweep claims the rows. A settlement that never arrives changes nothing:
|
|
1578
|
+
its entries are claimed again after the lease, so delivery stays at least
|
|
1579
|
+
once. That covers an isolate that died, an object that refused the
|
|
1580
|
+
settlement, or a request answered `503 TENANT_RPC_VERSION_MISMATCH` before
|
|
1581
|
+
the settlement it carried was read.
|
|
1582
|
+
- **First request.** On an object's first request the report write (which
|
|
1583
|
+
registers it in `tenant_registry`) finishes before the claim's lookups,
|
|
1584
|
+
audit rows, jobs and queue sends are applied. Realtime does not wait for it.
|
|
1585
|
+
- **Oversized rows.** A row too large for the inline header is claimed by
|
|
1586
|
+
`claimOutbox`, which always hands over the oldest claimable row, whatever its
|
|
1587
|
+
size.
|
|
1588
|
+
- **Operator drains.** `sync` and `backup` drain an active object normally.
|
|
1589
|
+
For an archived object (and during purge, restore and unarchive) they also
|
|
1590
|
+
take entries another claim holds, and a failed realtime replay is not
|
|
1591
|
+
retried. An archived object serves no requests, so nothing else would
|
|
1592
|
+
deliver them.
|
|
1593
|
+
- **Chained jobs.** A job delivered to another object of the organization
|
|
1594
|
+
drains that object's outbox too (up to 4 levels deep), after the claim that
|
|
1595
|
+
carried the job is settled.
|
|
1596
|
+
- **When a claimer dies.** Its entries stay leased until the lease expires,
|
|
1597
|
+
then the next response or sweep claims them again. A realtime frame keeps
|
|
1598
|
+
the `publishId` written with the row, so the Broadcaster drops a repeat it
|
|
1599
|
+
remembers, and the frame `id` (`evt_<publishId>`) lets clients drop the rest.
|
|
1600
|
+
Other kinds were already idempotent: audit rows by id, jobs by run id, queue
|
|
1601
|
+
messages by `dedupeKey`.
|
|
1602
|
+
- **Order.** Realtime frames are ordered within one claim. Across concurrent
|
|
1603
|
+
requests they are not, as before. Realtime no longer waits for the jobs and
|
|
1604
|
+
queue sends of the same claim.
|
|
1605
|
+
|
|
1606
|
+
#### Delivery receipts
|
|
1607
|
+
|
|
1608
|
+
Each settled entry leaves a row in the object's `__qb_outbox_receipts` table:
|
|
1609
|
+
- `generation` and `seq`;
|
|
1610
|
+
- `kind`;
|
|
1611
|
+
- `method`: the realtime method or event, or the job or queue message type;
|
|
1612
|
+
- `target`: the Broadcaster shard, job target, queue binding, audit row id or
|
|
1613
|
+
lookup name;
|
|
1614
|
+
- `ref`;
|
|
1615
|
+
- `createdAt` and `sentAt` (ms);
|
|
1616
|
+
- `attempts`;
|
|
1617
|
+
- `outcome` (`delivered`, `retrying` or `failed`) and `reason`;
|
|
1618
|
+
- `detail`: `{ publishId, matched, duplicate }` for realtime, where `matched`
|
|
1619
|
+
is the number of sockets the Broadcaster sent to; `{ dedupeKey }` for queue
|
|
1620
|
+
messages; `{ runId }` for jobs.
|
|
1621
|
+
|
|
1622
|
+
A receipt moves to `delivered` and stays there. Receipts are written in the
|
|
1623
|
+
same object turn as the settlement, so they cost no extra request.
|
|
1624
|
+
|
|
1625
|
+
- **Retention.** Receipts older than `tenancy.outbox.receipts.retainDays`
|
|
1626
|
+
(default 7), and the oldest beyond `maxRows` (default 50 000), are pruned on
|
|
1627
|
+
the object's alarm, on the first settlement after each wake, and after every
|
|
1628
|
+
256 settled entries.
|
|
1629
|
+
- **Backups and restore.** Receipts are not tenant data. Dumps skip them, and
|
|
1630
|
+
a dump restore keeps them, because restoring data does not undo what was
|
|
1631
|
+
already sent. A point-in-time restore rewinds the whole object, so it rewinds
|
|
1632
|
+
receipts and outbox rows (with their leases) to the bookmark as well. The
|
|
1633
|
+
reconciling sync then moves to a new outbox generation, drops the rewound
|
|
1634
|
+
non-audit rows and releases every lease. Settlements still in flight for the
|
|
1635
|
+
old generation write their receipts but touch no row. Purge erases receipts
|
|
1636
|
+
with the object.
|
|
1637
|
+
- **Reading them.** `GET <api>/tenants/:id/outbox-receipts?since=<ms or ISO>&limit=<1-1000>&outcome=delivered|retrying|failed`
|
|
1638
|
+
(sysadmin, oldest first). It returns `{ receipts, next }`; pass `next` as
|
|
1639
|
+
`since` for the next page. In code, call
|
|
1640
|
+
`listTenantOutboxReceipts(env, name, { since, limit, outcome })` from
|
|
1641
|
+
`src/lib/tenants.ts`.
|
|
1642
|
+
- **Push and email.** These already keep a per-send row in your own tenant
|
|
1643
|
+
table (for example `comms_log`). Pass that row's id as `ref` when enqueueing
|
|
1644
|
+
instead of duplicating it.
|
|
1645
|
+
|
|
1646
|
+
### Vars in tenant code
|
|
1647
|
+
|
|
1648
|
+
The tenant Worker has no bindings of the edge's, vars included, so tenant code
|
|
1649
|
+
that reads `env.<NAME>` fails the build (`TENANCY_ENV_UNAVAILABLE`). List the
|
|
1650
|
+
plain vars it needs in `tenancy.vars`:
|
|
1651
|
+
|
|
1652
|
+
```ts
|
|
1653
|
+
tenancy: {
|
|
1654
|
+
isolation: "durable-object",
|
|
1655
|
+
vars: ["ATTENDEE_APP_URL"],
|
|
1656
|
+
},
|
|
1657
|
+
environments: {
|
|
1658
|
+
dev: { /* … */ worker: { vars: { ATTENDEE_APP_URL: "https://app-dev.example.com" }, /* … */ } },
|
|
1659
|
+
},
|
|
1660
|
+
```
|
|
1661
|
+
|
|
1662
|
+
Each target's tenant Worker gets the value its own edge has (`[env.<name>.vars]`,
|
|
1663
|
+
or the top-level `[vars]` without environments), so tenant code reads
|
|
1664
|
+
`env.ATTENDEE_APP_URL` like edge code does; a target that does not set it gets
|
|
1665
|
+
none. Only plain vars qualify: a declared secret (`bindings.secrets`, a target's
|
|
1666
|
+
`requiredSecrets`, a `secrets.required` name of the edge) or a name that reads
|
|
1667
|
+
like one (`*SECRET*`, `*TOKEN*`, `*PASSWORD*`, `*_PASS`/`_PW`/`_PWD`,
|
|
1668
|
+
`*PRIVATE*`, `*CREDENTIAL*`, `*APIKEY*`, `*SALT*`, `*_SIGNING*`, `*_HMAC*`,
|
|
1669
|
+
`*PEPPER*`, `*BASIC_AUTH*`, `*_DSN`, database / Redis / Mongo `*_URL*` and
|
|
1670
|
+
`*_URI*`, `*CONNECTION_STRING*`, `*_PEM`, and `*_KEY(S)` / `*_KEK(S)` other
|
|
1671
|
+
than `*_PUBLIC_KEY(S)`, `*_SITE_KEY(S)` and `*_PUBLISHABLE_KEY(S)`) fails
|
|
1672
|
+
the build (`TENANCY_VARS_SECRET`), as does a
|
|
1673
|
+
name no target defines as a string var (`TENANCY_VARS_UNDECLARED`). Every other
|
|
1674
|
+
`env.*` read in tenant code still fails.
|
|
1675
|
+
|
|
1676
|
+
### Edge-only modules in tenant code
|
|
1677
|
+
|
|
1678
|
+
`lib/realtime` (needs the Broadcaster), `lib/security-audit` (needs the audit
|
|
1679
|
+
database) and `lib/auth` (Better Auth) do not run in the tenant Worker. Loading
|
|
1680
|
+
one there would drop its side effect silently, so the compiler guarantees:
|
|
1681
|
+
|
|
1682
|
+
- **Rewritten.** In tenant feature files and tenant queue handlers, a value
|
|
1683
|
+
import of `lib/realtime` or `lib/security-audit` is pointed at the tenant
|
|
1684
|
+
version, which records the event in the object's outbox. This covers
|
|
1685
|
+
`import`/`export … from` in either quote style, `import "…"`, and
|
|
1686
|
+
`import("…")`/`require("…")` with a literal path (quotes or a backtick with
|
|
1687
|
+
no `${}`). The path is resolved against the importing file, so only paths
|
|
1688
|
+
that land on the project's `lib/` change. `import { createAuth } from
|
|
1689
|
+
"…/lib/auth"`, optionally aliased and with `type` names alongside, becomes a
|
|
1690
|
+
stand-in that throws: read the caller from `ctx` instead.
|
|
1691
|
+
- **Refused.** The build then walks every module the tenant Worker loads from
|
|
1692
|
+
`src/tenant/index.ts` (again after provider build hooks, so a file a hook
|
|
1693
|
+
adds or rewrites is checked too) and fails (`TENANCY_EDGE_IMPORT_IN_TENANT`, with the
|
|
1694
|
+
import chain) on any value reference to one of those modules that remains:
|
|
1695
|
+
a shared `quickback/lib` helper or a platform feature that imports
|
|
1696
|
+
`./realtime`, any other import from `lib/auth`, or a string that resolves
|
|
1697
|
+
to one of them (a relative path, or one starting `@/`, `~/` or `src/` — so
|
|
1698
|
+
`"src/lib/auth"` itself is refused). It also refuses every `import()` or
|
|
1699
|
+
`require()` whose argument is not a plain string literal (`+`, a template
|
|
1700
|
+
with `${}`, a variable, `.join()`): the compiler cannot check it, and the
|
|
1701
|
+
bundler includes every file such a pattern could match. Shared modules are not rewritten
|
|
1702
|
+
because the edge Worker uses them too: import `lib/realtime` from the tenant
|
|
1703
|
+
feature itself, or keep the helper free of it.
|
|
1704
|
+
- **Allowed.** `import type`, `type` specifiers, `typeof import("…")`, comments
|
|
1705
|
+
and ordinary strings.
|
|
1706
|
+
|
|
1707
|
+
### Helpers run where their caller runs
|
|
1708
|
+
|
|
1709
|
+
A helper a tenant action, tenant job or JS trigger handler imports runs inside
|
|
1710
|
+
the tenant object too. After all files are generated, the compiler walks each
|
|
1711
|
+
of them through its runtime imports, resolving relative imports and
|
|
1712
|
+
`tsconfig.json` `paths` aliases the way the edge-bundle walk does. Every
|
|
1713
|
+
authored module it reaches, such as a feature `lib/` file, another feature's
|
|
1714
|
+
file or a `quickback/lib` helper, gets the checks a tenant action gets:
|
|
1715
|
+
|
|
1716
|
+
- edge-only `ctx` members and `env` bindings (`TENANCY_CTX_UNAVAILABLE`,
|
|
1717
|
+
`TENANCY_ENV_UNAVAILABLE`);
|
|
1718
|
+
- async `transaction()` callbacks (`TENANCY_ASYNC_TRANSACTION`);
|
|
1719
|
+
- tables of another object (`TENANCY_CROSS_PARTITION`);
|
|
1720
|
+
- inserts that choose the id of a scope instance or proving table
|
|
1721
|
+
(`TENANCY_ADMISSION_ID_STRATEGY`).
|
|
1722
|
+
|
|
1723
|
+
A tenant job's own body (its top-level constants and `execute`) gets the same
|
|
1724
|
+
checks. The checks are per module, not per function: a helper file is scanned
|
|
1725
|
+
whole once anything imports it, including exports the caller never uses.
|
|
1726
|
+
|
|
1727
|
+
The error names the helper and the entry point that reached it. Compiler-
|
|
1728
|
+
generated modules are not expanded, and package imports are allowed. A relative
|
|
1729
|
+
or alias import that names no file in the build, or a computed `import()` /
|
|
1730
|
+
`require()`, fails with `TENANCY_HELPER_UNRESOLVED`: the compiler can't check
|
|
1731
|
+
code it can't find. A helper nothing in the tenant Worker imports is not checked.
|
|
1732
|
+
|
|
1733
|
+
JS `handler:` triggers on tenant tables run in the object as well. Each
|
|
1734
|
+
handler's source gets the same checks as an action body, and its imports are
|
|
1735
|
+
walked like a helper's. A handler receives the `env` a tenant action gets (a
|
|
1736
|
+
copy of the tenant Worker's bindings without the backup bucket, which holds
|
|
1737
|
+
every organization's dumps; `tenancy.backup.bucket` may not double as any
|
|
1738
|
+
app, provider or queue binding), so
|
|
1739
|
+
whatever it passes `env` to records into the object's outbox in the same way:
|
|
1740
|
+
`createRealtime(env)` broadcasts, `tenantRuntime(env).enqueue(…)` queue
|
|
1741
|
+
messages and the tenant `revokeScopeTokens(env, …)`. The tenant
|
|
1742
|
+
`createRealtime` logs `tenant.realtime.no_outbox` (an error) when it is given
|
|
1743
|
+
an `env` without the outbox, instead of dropping the call silently. A handler whose source can't be extracted as one arrow
|
|
1744
|
+
function or function expression fails with `TENANCY_TRIGGER_UNVERIFIABLE`.
|
|
1745
|
+
|
|
1746
|
+
## Scope revocation
|
|
1747
|
+
|
|
1748
|
+
With `auth.jwt.revocationCheck: 'kv'`, changing a scope-conferring row revokes
|
|
1749
|
+
the carried scope claims that row backed (revoke-on-touch): the subject's
|
|
1750
|
+
`qbrev:scope:<subject>:<kind>:<instance>` keys are stamped in the edge's `KV`
|
|
1751
|
+
namespace. The tenant Worker has no `KV`, so for a tenant table the object
|
|
1752
|
+
records the revocation in its outbox and the edge stamps it:
|
|
1753
|
+
|
|
1754
|
+
- **In the write's transaction.** Every scope-conferring tenant table (the
|
|
1755
|
+
`from` table of a relationship a scope role is granted `via`) carries SQL
|
|
1756
|
+
triggers that write a `revoke` outbox entry on every `DELETE` and on every
|
|
1757
|
+
`UPDATE` that changes a column the row confers through (soft deletes
|
|
1758
|
+
included), naming the row's id and subject column and its resource
|
|
1759
|
+
(instance) column. Those columns are the subject and resource columns, each
|
|
1760
|
+
relationship's `where:` columns, every scope role's `subKeys`, every field
|
|
1761
|
+
the table's firewall names (its soft-delete column included), the tenant
|
|
1762
|
+
column and the primary key, so a backfill or data migration of other
|
|
1763
|
+
columns revokes nothing. When the compiler cannot resolve one of them, the
|
|
1764
|
+
trigger fires on every `UPDATE`. An update that moves the row to another subject or instance also
|
|
1765
|
+
revokes the new pair. Being SQL triggers, they fire for every write path in
|
|
1766
|
+
the object: CRUD routes, actions, `unsafeDb`, jobs, trigger handlers,
|
|
1767
|
+
foreign-key cascades and compiler commands. A write that rolls back leaves
|
|
1768
|
+
no revocation. `INSERT OR REPLACE` deletes a conflicting row without firing
|
|
1769
|
+
the `DELETE` trigger (SQLite's `recursive_triggers` stays off, so authored
|
|
1770
|
+
SQL triggers keep their semantics): the build refuses `INSERT OR REPLACE` /
|
|
1771
|
+
`REPLACE INTO` on a conferring table in tenant actions and trigger bodies
|
|
1772
|
+
(`TENANCY_REVOCATION_REPLACE`). Change a conferring row with an `UPDATE`
|
|
1773
|
+
(or `onConflictDoUpdate`).
|
|
1774
|
+
- **Stamped by the edge**, at least once, beside the realtime frames (see
|
|
1775
|
+
[Outbox delivery](#outbox-delivery)), at the time the edge applies the entry,
|
|
1776
|
+
like every edge revocation: a later stamp only revokes more (a token proven
|
|
1777
|
+
between the write and the stamp re-proves), and no stale read can lower it.
|
|
1778
|
+
The entry keeps its write time for the receipt. The edge accepts a `revoke`
|
|
1779
|
+
entry only for a declared `authz.scopes` kind; one whose instance the
|
|
1780
|
+
platform lookup index places in another organization is logged
|
|
1781
|
+
(`tenant.revoke.foreign_instance`) and still applied, since a wrong
|
|
1782
|
+
revocation only forces a re-prove.
|
|
1783
|
+
- **Restores and purges.** A dump restore drops the tables, and a purge erases
|
|
1784
|
+
the database, without firing a trigger; a point-in-time restore rewinds the
|
|
1785
|
+
outbox with the data. So a dump restore first queues a revocation for every
|
|
1786
|
+
conferring row it replaces, in the load's transaction. A point-in-time
|
|
1787
|
+
restore hands the current conferring rows and any queued revocations to the
|
|
1788
|
+
control object before scheduling the rewind. Every reconcile
|
|
1789
|
+
(`POST /tenants/:id/sync`, abandon) and every cancel queues them again, and
|
|
1790
|
+
only a reconcile drops them once its requeue committed (an orphaned stash is
|
|
1791
|
+
pruned after a week). A purge queues them once per archive, then drains them
|
|
1792
|
+
in rounds, at most 300 rows per request (each row costs up to two KV writes,
|
|
1793
|
+
and a Worker invocation gets about 1000 KV operations). While any remain it
|
|
1794
|
+
answers `409 TENANT_PURGE_DRAINING` with `details: { remaining, more }` and
|
|
1795
|
+
`Retry-After`: retry the purge until it completes; nothing is queued twice. An edge older
|
|
1796
|
+
than version 12 cannot purge while revocations are queued. Rows that exist
|
|
1797
|
+
again after a restore simply re-prove.
|
|
1798
|
+
- **Your own revocations.** In tenant code, `revokeScopeTokens(env, subject, kind, instanceId)`
|
|
1799
|
+
(an import of `lib/jwt-revocation` in a tenant feature is re-pointed at the
|
|
1800
|
+
tenant version) records a `revoke` entry with your write. It takes the `env`
|
|
1801
|
+
your action, job or trigger handler received, never `env.KV`, and throws
|
|
1802
|
+
`TENANT_REVOCATION_UNAVAILABLE` without the outbox. The other exports of
|
|
1803
|
+
`lib/jwt-revocation` (`revokeUserTokens`, `revokeMemberTokens`,
|
|
1804
|
+
`revokeSessionTokens`, `checkTokenRevocation`) are edge-only: in a tenant
|
|
1805
|
+
feature a call fails the build, its parameter type naming the reason.
|
|
1806
|
+
- **Admission.** A revoked claim stops riding on tokens; admission itself
|
|
1807
|
+
re-reads the row. [Tenant scope admission](#tenant-backed-scope-kinds)
|
|
1808
|
+
requires the proving row's conditions (`where:`) and excludes soft-deleted
|
|
1809
|
+
rows through the table's firewall (`deleted_at IS NULL`).
|
|
1810
|
+
|
|
1811
|
+
## Lookup indexes
|
|
1812
|
+
|
|
1813
|
+
Some lookups start from a value, not an organization: an invite code, a public
|
|
1814
|
+
slug, an SES message id, a phone number. Declare them in `tenancy.lookups`:
|
|
1815
|
+
|
|
1816
|
+
{/* doc-compile: skip — fragment of quickback.config.ts */}
|
|
1817
|
+
```ts
|
|
1818
|
+
lookups: {
|
|
1819
|
+
inviteCode: { table: "invites", column: "code", hash: true },
|
|
1820
|
+
event: { table: "events", column: "id" },
|
|
1821
|
+
},
|
|
1822
|
+
```
|
|
1823
|
+
|
|
1824
|
+
SQL triggers in every tenant object record each insert, update and delete of
|
|
1825
|
+
the column (soft-deleted rows count as deleted) in the object's outbox. The
|
|
1826
|
+
edge applies them to the platform `tenant_lookups` table after the response, in
|
|
1827
|
+
order (`tenant_registry.outbox_seq` drops a stale batch). Read it on the edge:
|
|
1828
|
+
|
|
1829
|
+
{/* doc-compile: skip — generated-project code */}
|
|
1830
|
+
```ts
|
|
1831
|
+
import { resolveTenant, resolveTenants } from "../lib/tenants";
|
|
1832
|
+
|
|
1833
|
+
const tenantId = await resolveTenant(env, "inviteCode", code); // null, or throws if several
|
|
1834
|
+
const phoneTenants = await resolveTenants(env, "phone", phone);
|
|
1835
|
+
```
|
|
1836
|
+
|
|
1837
|
+
A lookup named after a scope kind resolves tokens: an instance-bound token
|
|
1838
|
+
(`ctx.oauth.boundTo`) or a scope-only principal (`ctx.scope.<kind>.id`) reaches
|
|
1839
|
+
the organization whose rows hold that id. Without a matching lookup those
|
|
1840
|
+
principals get `400 TENANT_REQUIRED`. A token for a
|
|
1841
|
+
[tenant-backed kind](#tenant-backed-scope-kinds) is the exception:
|
|
1842
|
+
it routes to the tenant it pins, and the lookup is used only to issue it.
|
|
1843
|
+
|
|
1844
|
+
The index converges, it is not transactional with the write: it lags until
|
|
1845
|
+
the edge drains the object's outbox (after that object's next response, or
|
|
1846
|
+
`syncTenants(env)`). Adding a lookup re-sends every current key on each
|
|
1847
|
+
object's next wake.
|
|
1848
|
+
|
|
1849
|
+
### Hashed lookups
|
|
1850
|
+
|
|
1851
|
+
Every organization's lookup rows share one D1. A lookup whose values are
|
|
1852
|
+
credentials (invite tokens, share-link tokens, sign-in codes) should not sit
|
|
1853
|
+
there in plaintext: set `hash: true`. The row's key is then `h1:` followed by
|
|
1854
|
+
`HMAC-SHA256(TENANT_LOOKUP_KEY, "<name>\0<value>")` as 64 lowercase hex. The
|
|
1855
|
+
`h1:` marker tells a hash from a value that is itself hex, so a row written
|
|
1856
|
+
before hashing is always recognisable. The lookup name separates domains, so
|
|
1857
|
+
the same value in two lookups gets two unrelated keys. A lookup column whose name reads like a credential (`token`,
|
|
1858
|
+
`code`, `secret`, `key`, `password`) and is not hashed draws a
|
|
1859
|
+
`TENANCY_LOOKUP_PLAINTEXT` compile warning. Ids and slugs are fine in plaintext.
|
|
1860
|
+
|
|
1861
|
+
- **The secret.** `TENANT_LOOKUP_KEY` is required on the edge Worker (it joins
|
|
1862
|
+
the generated secret inventory and the boot guard): one or more 64-hex keys
|
|
1863
|
+
(`openssl rand -hex 32`), comma-separated, primary first. The tenant Worker
|
|
1864
|
+
never holds it. Its outbox carries the value to the edge, which hashes before
|
|
1865
|
+
anything reaches D1. A missing or malformed key refuses: the outbox entries
|
|
1866
|
+
retry, and resolution fails, so nothing is ever written in plaintext.
|
|
1867
|
+
- **Unchanged API.** `resolveTenant(env, name, value)` takes the value and
|
|
1868
|
+
hashes it. Receipts record the lookup name only. A dead-lettered lookup row
|
|
1869
|
+
copied to the audit database at purge has its value withheld.
|
|
1870
|
+
- **Rotation.** Resolution tries every key and re-keys a row it finds under an
|
|
1871
|
+
older one; writes use the first. Rotate in two deploys, so no isolate still
|
|
1872
|
+
on the old list writes a row the others cannot clean up: (1) append the new
|
|
1873
|
+
key (`old,new`) and deploy; (2) promote it (`new,old`) and deploy; (3) run
|
|
1874
|
+
`POST /tenants/:id/rebuild-lookups` on every organization, which re-publishes
|
|
1875
|
+
each object's rows under the new key; (4) drop the old key.
|
|
1876
|
+
- **Turning it off.** Removing `hash: true` (or rolling the edge back past it)
|
|
1877
|
+
leaves the hashed rows unresolvable: rebuild every organization's lookups
|
|
1878
|
+
afterwards.
|
|
1879
|
+
- **Adopting `hash: true` on an existing lookup.** Rows written before it hold
|
|
1880
|
+
the value. Resolution also matches the plaintext row (never a value shaped
|
|
1881
|
+
like a stored hash) and re-keys it. Every outbox drain of an object (a request,
|
|
1882
|
+
a job call, an alarm's drain request, an operator call) and its wake report
|
|
1883
|
+
convert up to 100 of that object's plaintext rows in place first, once per
|
|
1884
|
+
object per isolate. For organizations that do not wake, run
|
|
1885
|
+
`POST /tenants/lookups/migrate` (or `syncTenants(env)`, which also converts
|
|
1886
|
+
up to 200 rows across objects) until it reports none remaining — manually,
|
|
1887
|
+
not on a cron. Any write
|
|
1888
|
+
of a key replaces its plaintext row. Set the secret first, then deploy the
|
|
1889
|
+
tenant Worker, then the edge.
|
|
1890
|
+
|
|
1891
|
+
## Partitions
|
|
1892
|
+
|
|
1893
|
+
One object per organization puts a busy organization on one thread. Shard a
|
|
1894
|
+
high-volume, naturally partitioned feature by its unit of contention:
|
|
1895
|
+
|
|
1896
|
+
{/* doc-compile: skip — fragment of a feature() resource config */}
|
|
1897
|
+
```ts
|
|
1898
|
+
placement: { partition: "conversation", key: "conversationId" },
|
|
1899
|
+
```
|
|
1900
|
+
|
|
1901
|
+
Each `(organization, key)` gets its own object, named `<orgId>:<key>`, so the
|
|
1902
|
+
object name alone says which tenant it serves. The table stays
|
|
1903
|
+
organization-scoped (the firewall still applies) and every table in the feature
|
|
1904
|
+
uses the same key.
|
|
1905
|
+
|
|
1906
|
+
| Request | Result |
|
|
1907
|
+
|---|---|
|
|
1908
|
+
| Key from `?conversationId=`, the `x-quickback-partition-key` header, or the JSON body field | Forwarded to `<orgId>:<key>`; the query parameter is consumed |
|
|
1909
|
+
| No key | `400 PARTITION_KEY_REQUIRED` |
|
|
1910
|
+
| Two different keys in one request | `400 PARTITION_KEY_MISMATCH` |
|
|
1911
|
+
| A row whose key differs from its object's | Refused by a trigger in the object (`400 PARTITION_KEY_MISMATCH`) |
|
|
1912
|
+
|
|
1913
|
+
Partition objects carry the same schema and migrations as organization
|
|
1914
|
+
objects (their organization tables stay empty), take their own backups, and
|
|
1915
|
+
appear in `tenant_registry` with `partition_key`. One partition kind per
|
|
1916
|
+
project (`TENANCY_PARTITION_KINDS`).
|
|
1917
|
+
|
|
1918
|
+
No foreign key and no action crosses partitions: the build refuses
|
|
1919
|
+
`TENANCY_FK_CROSS_PARTITION` and `TENANCY_CROSS_PARTITION`. Store the other
|
|
1920
|
+
side's id without `.references()` (opt it out of the reference diagnostic with
|
|
1921
|
+
`references: { projectId: { references: false, reason } }`) and send the update
|
|
1922
|
+
through the outbox — delivered by the edge after the response, at least once,
|
|
1923
|
+
to a tenant job in the target object:
|
|
1924
|
+
|
|
1925
|
+
{/* doc-compile: skip — action body fragment */}
|
|
1926
|
+
```ts
|
|
1927
|
+
const [row] = await db.insert(messages).values({ conversationId: input.conversationId, body: input.body }).returning();
|
|
1928
|
+
tenantRuntime(env).send("tenant", { type: "conversation.posted", conversationId: input.conversationId });
|
|
1929
|
+
```
|
|
1930
|
+
|
|
1931
|
+
`send("tenant", …)` targets the organization object; `send({ key }, …)` a
|
|
1932
|
+
partition object of the same organization.
|
|
1933
|
+
|
|
1934
|
+
## Deleting the namespace
|
|
1935
|
+
|
|
1936
|
+
A `deleted` tombstone for `QuickbackTenant` destroys every tenant database.
|
|
1937
|
+
The build refuses a `bindings.durableObjectMigrations` entry that deletes or
|
|
1938
|
+
renames the class (`TENANCY_NAMESPACE_DELETION`) unless
|
|
1939
|
+
`tenancy.allowNamespaceDeletion: true` is set **and** no table still lives in
|
|
1940
|
+
a tenant object. Then the tenant Worker's exports carry
|
|
1941
|
+
`{ "state": "deleted" }` and the edge no longer binds the class.
|
|
1942
|
+
|
|
1943
|
+
## Registry
|
|
1944
|
+
|
|
1945
|
+
`tenant_registry` in the features D1 inventories tenant names and application
|
|
1946
|
+
state; Cloudflare's object listing does not include those fields. Beside it,
|
|
1947
|
+
`tenant_operations` holds one receipt per lifecycle operation
|
|
1948
|
+
([Lifecycle operations](#lifecycle-operations)). The edge
|
|
1949
|
+
upserts a row from the object's wake report. The object repeats the
|
|
1950
|
+
report on later responses until the edge acknowledges a successful registry
|
|
1951
|
+
write, so a transient D1 outage does not lose inventory or migration failures.
|
|
1952
|
+
|
|
1953
|
+
Each report carries a generation and a strictly increasing sequence, stored
|
|
1954
|
+
atomically with the report in the object's local KV. The sequence advances on
|
|
1955
|
+
every wake and migration retry, including pre-migration progress markers, even
|
|
1956
|
+
when timestamps are identical. The edge updates an existing row only when its
|
|
1957
|
+
generation matches and the report sequence is higher. Delayed or repeated
|
|
1958
|
+
reports cannot replace newer health, schema versions, or errors. An
|
|
1959
|
+
acknowledgement consumes only the exact current report, including its generation
|
|
1960
|
+
and sequence. Unordered RPC failures preserve rows that already have an ordered
|
|
1961
|
+
health report. PITR installs a fresh report generation together with the outbox
|
|
1962
|
+
fence; reconciliation republishes the recovered object's health under that
|
|
1963
|
+
generation. Dump restore installs the same fresh generation. Failed preparation
|
|
1964
|
+
restores the previous report fence, and explicit abandonment republishes current
|
|
1965
|
+
health under its recovery generation.
|
|
1966
|
+
|
|
1967
|
+
| Column | Meaning |
|
|
1968
|
+
|---|---|
|
|
1969
|
+
| `state` | `active`, `migrating`, `failed`, `frozen`, `archived`, `purged`. Wake reports never overwrite `frozen`, `archived` or `purged`. |
|
|
1970
|
+
| `schema_version` | Applied tenant migrations |
|
|
1971
|
+
| `report_generation`, `report_sequence` | Report ordering fence (initially `initial`) and last accepted sequence (initially `0`) |
|
|
1972
|
+
| `last_pre_migration_bookmark` | PITR bookmark taken before the last migration |
|
|
1973
|
+
| `last_error` | The last migration error, or null |
|
|
1974
|
+
| `tenant_id`, `partition_key` | The organization, and the partition key for partition objects (`id` is the object name) |
|
|
1975
|
+
| `last_backup_at`, `last_backup_key` | The last finished backup |
|
|
1976
|
+
| `outbox_seq` | The last ordered-lane outbox entry (lookup, registry) the edge applied |
|
|
1977
|
+
| `jurisdiction` | The objects' jurisdiction |
|
|
1978
|
+
|
|
1979
|
+
Fan out over every object with `forEachTenant` from `src/lib/tenants.ts`;
|
|
1980
|
+
`syncTenants(env)` drains every object's outbox with it — an operator or manual
|
|
1981
|
+
sweep: nothing needs it on a schedule, since every alarm asks the edge to drain
|
|
1982
|
+
its own object. It skips `archived` and
|
|
1983
|
+
`purged` tenants, runs at most `concurrency` at a time (default 4), and
|
|
1984
|
+
reports each tenant's failure instead of throwing:
|
|
1985
|
+
|
|
1986
|
+
{/* doc-compile: skip — generated-project code */}
|
|
1987
|
+
```ts
|
|
1988
|
+
import { forEachTenant } from "../lib/tenants";
|
|
1989
|
+
|
|
1990
|
+
const results = await forEachTenant(env, async (tenantId, stub) => {
|
|
1991
|
+
return tenantId;
|
|
1992
|
+
}, { concurrency: 8 });
|
|
1993
|
+
```
|
|
1994
|
+
|
|
1995
|
+
## Operator routes
|
|
1996
|
+
|
|
1997
|
+
The edge mounts tenant operations at `<api>/tenants` (e.g. `/api/v1/tenants`).
|
|
1998
|
+
They are plain Hono routes: they are not in the OpenAPI document or the MCP
|
|
1999
|
+
tool list.
|
|
2000
|
+
|
|
2001
|
+
**`tenancy.operator.http`** decides which of them exist. Generating the
|
|
2002
|
+
lifecycle helpers never implies exposing them over HTTP:
|
|
2003
|
+
|
|
2004
|
+
```ts
|
|
2005
|
+
tenancy: {
|
|
2006
|
+
isolation: 'durable-object',
|
|
2007
|
+
// No generated operator routes. Your own `operator:` actions call the
|
|
2008
|
+
// helpers in src/lib/tenants.ts (archiveTenant, restoreTenant, purgeTenant, …).
|
|
2009
|
+
operator: { http: false },
|
|
2010
|
+
}
|
|
2011
|
+
```
|
|
2012
|
+
|
|
2013
|
+
```ts
|
|
2014
|
+
tenancy: {
|
|
2015
|
+
isolation: 'durable-object',
|
|
2016
|
+
// Only these routes are mounted; nothing else answers under <api>/tenants.
|
|
2017
|
+
operator: { http: { allow: ['archive', 'unarchive', 'sync', 'retry-migration'] } },
|
|
2018
|
+
}
|
|
2019
|
+
```
|
|
2020
|
+
|
|
2021
|
+
Route names are the path segments below: `retry-migration`, `archive`,
|
|
2022
|
+
`unarchive`, `purge`, `sync`, `rebuild-lookups`, `schedules` (the GET plus
|
|
2023
|
+
`arm`, `hold` and `arm-all`), `lookups-migrate`, `outbox-receipts`, `backup`,
|
|
2024
|
+
`backups` (the list plus `backups/counts`), `bookmark`, `restore`,
|
|
2025
|
+
`cancel-restore`. An unknown name, an empty list, or `http` set beside the
|
|
2026
|
+
deprecated `operator.purge` fails the build (`TENANCY_OPERATOR_HTTP`). An
|
|
2027
|
+
allowlist that mounts any mutation (every name but `backups`, `bookmark`,
|
|
2028
|
+
`outbox-receipts`) needs `auth.cloudflareAccess` covering `<api>/tenants`;
|
|
2029
|
+
without it the build fails (`TENANCY_OPERATOR_AUTH`): a sysadmin session cookie
|
|
2030
|
+
is not enough authority for a lifecycle mutation. With
|
|
2031
|
+
`http: false` no `src/tenant/admin.ts` is generated and `src/index.ts` mounts
|
|
2032
|
+
nothing at `<api>/tenants`; `src/lib/tenants.ts` is unchanged. Leaving `http`
|
|
2033
|
+
unset mounts every route and warns: the default becomes `false` in the next
|
|
2034
|
+
breaking release.
|
|
2035
|
+
Every route needs a sysadmin (`user.role === 'sysadmin'`, Better Auth admin
|
|
2036
|
+
plugin). With `auth.cloudflareAccess` configured, the caller must also come
|
|
2037
|
+
through Cloudflare Access, and the build fails (`TENANCY_ADMIN_NOT_BEHIND_ACCESS`)
|
|
2038
|
+
unless an Access application covers both the path and the API host (the
|
|
2039
|
+
hostnames in `providers.runtime.config.routes` and `domain`; with none
|
|
2040
|
+
configured, only an application without `hosts` covers it).
|
|
2041
|
+
|
|
2042
|
+
| Route | Effect |
|
|
2043
|
+
|---|---|
|
|
2044
|
+
| `POST /tenants/:id/retry-migration` | Clear the reset count and migrate the object again; records the new report |
|
|
2045
|
+
| `GET /tenants/operations/:operationId` | The durable receipt of a lifecycle operation, settled from the object's receipt or the registry when it was left `requested` / `uncertain`. See [Lifecycle operations](#lifecycle-operations). |
|
|
2046
|
+
| `POST /tenants/:id/provision` | The only route that creates a tenant object. Refuses an id that is not a Better Auth organization (`404 TENANT_ORGANIZATION_UNKNOWN`) and a partition name; wakes the organization's object so it migrates and reports, registers it from that report, returns the registry row. Idempotent: a registered organization is returned as is. Use it to move an existing organization into a tenant object (provision, then `archive`, `backup`, `restore`, `sync`, `unarchive`). Partition objects are created by their first request, never here. |
|
|
2047
|
+
| `POST /tenants/:id/archive` | The object answers `423 TENANT_ARCHIVED`; `tenant_registry.state` → `archived` (`forEachTenant` skips it). Data is kept. Refuses a purged object, and refuses an unknown id (`TENANT_NOT_PROVISIONED`) **without waking it**: no lifecycle operation but `provision` creates an object. If archive fails after the object archived (for example the registry write failed), retry it: it re-records the object's own report, which says archived. The other operator routes (`unarchive`, `sync`, `backup`, `backups`, `retry-migration`, `restore`) likewise act on registered objects only. When the edge drains queued work from an object it has not registered, it records the state the object reports, `archived` included, never `active` by default. |
|
|
2048
|
+
| `POST /tenants/:id/unarchive` | Serve again; state → `active`. Registered objects only: an unknown id is refused (`TENANT_NOT_PROVISIONED`) without waking it, as is a purged one. Refuses (`TENANT_RESTORE_PENDING`) while a restore is pending or not yet reconciled by `POST /tenants/:id/sync`, or while an unconfirmed restore or stranded maintenance fence awaits `POST /tenants/:id/cancel-restore` — the explicit last step of [restore quarantine](#restore-quarantine). |
|
|
2049
|
+
| `POST /tenants/:id/purge` | Body `{ "confirm": "<id>" }`. `archived` tenants only: records the current point-in-time bookmark in `tenant_registry.last_purge_bookmark`, records the durable purge marker in the control object, erases the object (`deleteAlarm()`, then `deleteAll()`), marks it `purged`; the object answers `410 TENANT_PURGED` from then on. Resumable: after an error, retry it ([interrupted purges](#hard-deletes-and-the-audit-log)). Any other state, or a wrong `confirm`, answers `409`. |
|
|
2050
|
+
|
|
2051
|
+
**`tenancy.operator.purge`** (deprecated: name `'purge'` in `operator.http.allow`,
|
|
2052
|
+
or leave it out). When your own code imports `purgeTenant` from
|
|
2053
|
+
`lib/tenants` (an organization-delete flow that archives, cleans up platform
|
|
2054
|
+
rows and storage, then erases the object; a named import, `export *` or a
|
|
2055
|
+
named re-export, or a namespace / dynamic import of `lib/tenants` in a file that
|
|
2056
|
+
names `purgeTenant`; type-only imports and comments do not count),
|
|
2057
|
+
the raw purge route is **not mounted**: an operator could otherwise erase an object behind your flow's back.
|
|
2058
|
+
It does not exist at all then (`404`), and `purgeTenant` stays available to your
|
|
2059
|
+
code. Set `tenancy.operator: { purge: true }` to mount it anyway, or
|
|
2060
|
+
`{ purge: false }` to leave it out when nothing imports `purgeTenant`. An
|
|
2061
|
+
`operator.http.allow` list that names `'purge'` mounts it regardless of what
|
|
2062
|
+
your code imports: the list is the explicit opt-in.
|
|
2063
|
+
|
|
2064
|
+
Purge is not immediate erasure: Durable Object point-in-time recovery keeps
|
|
2065
|
+
the data for 30 days after `deleteAll()`. Purge is still final as far as these
|
|
2066
|
+
routes go. No route brings a purged tenant back: restore and unarchive refuse it,
|
|
2067
|
+
and the marker is never cleared. `tenant_registry.last_purge_bookmark` records
|
|
2068
|
+
the bookmark from just before the purge. Getting the data back means restoring
|
|
2069
|
+
that bookmark and clearing the control object's marker in your own code; no
|
|
2070
|
+
generated route does either.
|
|
2071
|
+
|
|
2072
|
+
The same operations are functions in `src/lib/tenants.ts`: `provisionTenantTarget`,
|
|
2073
|
+
`retryTenantMigration`, `archiveTenant`, `unarchiveTenant`, `purgeTenant`.
|
|
2074
|
+
|
|
2075
|
+
### Lifecycle operations
|
|
2076
|
+
|
|
2077
|
+
Every mutation above runs through one executor, `runTenantOperatorOperation`
|
|
2078
|
+
in `src/lib/tenants.ts`, against one registry, `TENANT_OPERATIONS`. The
|
|
2079
|
+
registry is the state machine: which `tenant_registry.state` an operation may
|
|
2080
|
+
start from, what it leaves, and whether the caller must confirm.
|
|
2081
|
+
|
|
2082
|
+
| Operation | From | To | Confirm |
|
|
2083
|
+
|---|---|---|---|
|
|
2084
|
+
| `provision` | no row | the object's own report (`active`, `migrating`, `failed`) | |
|
|
2085
|
+
| `archive` | `active`, `migrating`, `failed`, `frozen` | `archived` | |
|
|
2086
|
+
| `unarchive` | `archived` | `active` | |
|
|
2087
|
+
| `purge` | `archived` | `purged` | `{ confirm: "<id>" }` |
|
|
2088
|
+
| `restore` | `archived` | `archived` (pending) | |
|
|
2089
|
+
| `cancel-restore` | `archived` | `archived` | `{ confirm: "<id>" }` |
|
|
2090
|
+
| `retry-migration`, `sync`, `rebuild-lookups`, `backup`, `schedules.arm`, `schedules.hold` | any registered state but `purged` | unchanged | |
|
|
2091
|
+
| `schedules.arm-all`, `lookups.migrate` | not bound to one tenant | | |
|
|
2092
|
+
| `backups`, `bookmark`, `outbox-receipts`, `schedules.status` | reads: registered, not `purged` | | |
|
|
2093
|
+
|
|
2094
|
+
The executor runs, in order: the registry read and the transition check
|
|
2095
|
+
(`409 TENANT_INVALID_TRANSITION`, `404 TENANT_NOT_PROVISIONED`), the
|
|
2096
|
+
confirmation (`409 TENANT_CONFIRM_REQUIRED`), the `begin` audit row (a failed
|
|
2097
|
+
write is `503 TENANT_AUDIT_UNAVAILABLE` and **nothing runs**), the operation,
|
|
2098
|
+
then the outcome row. All of that happens before the tenant object is woken, so
|
|
2099
|
+
an invalid transition never creates or touches an object. Reads skip the audit.
|
|
2100
|
+
|
|
2101
|
+
Every mutation has an **operation id** and a **durable receipt**. Send yours as
|
|
2102
|
+
`X-Quickback-Operation-Id` (8–128 characters of `[A-Za-z0-9_-]`, else
|
|
2103
|
+
`400 TENANT_OPERATION_ID_INVALID`) or let the route mint one; the response
|
|
2104
|
+
carries it as `operationId`. The receipt is a `tenant_operations` row in the
|
|
2105
|
+
features D1, written `requested` before the object is touched and settled
|
|
2106
|
+
`completed` or `failed` after, with the operation's parameters hash, actor,
|
|
2107
|
+
`actorAuthMethod`, `fromState`, `resultingState`, error code and the recorded
|
|
2108
|
+
response (≤ 4000 characters). Every audit row of the operation carries the same
|
|
2109
|
+
`operationId` in `metadata`, with `phase: requested | completed | failed |
|
|
2110
|
+
uncertain`. If the outcome cannot be recorded after the operation ran, the
|
|
2111
|
+
receipt says `uncertain`, never a false `completed`.
|
|
2112
|
+
|
|
2113
|
+
Repeating an id **with the same parameters** replays the recorded outcome
|
|
2114
|
+
without running again (`replayed: true` in the response; a recorded failure is
|
|
2115
|
+
thrown again). The same id with different parameters is `409
|
|
2116
|
+
TENANT_OPERATION_ID_CONFLICT`; an id whose receipt is still `requested` or
|
|
2117
|
+
`uncertain` is `409 TENANT_OPERATION_PENDING` until it is reconciled.
|
|
2118
|
+
|
|
2119
|
+
`GET /tenants/operations/:operationId` (also `reconcileTenantOperation(env,
|
|
2120
|
+
id)` in `src/lib/tenants.ts`) returns the receipt and settles a `requested` or
|
|
2121
|
+
`uncertain` one from durable evidence: the object's own last-operation receipt
|
|
2122
|
+
(archive and unarchive record the operation id atomically with their change),
|
|
2123
|
+
else the registry state the operation leaves (`resultingState`; an open
|
|
2124
|
+
`restore_session` for a restore). A settled receipt records `reconciledBy` and
|
|
2125
|
+
gains its missing `completed` audit row with `reconciled: true`. Without
|
|
2126
|
+
evidence the receipt is returned unchanged (`evidence: 'none'`) for a human to
|
|
2127
|
+
decide.
|
|
2128
|
+
|
|
2129
|
+
Your own `operator:` action uses the same executor, so an authored control
|
|
2130
|
+
plane and the generated routes cannot drift:
|
|
2131
|
+
|
|
2132
|
+
{/* doc-compile: skip — generated-project code */}
|
|
2133
|
+
```ts
|
|
2134
|
+
import { archiveTenant, runTenantOperatorOperation } from "../../../lib/tenants";
|
|
2135
|
+
|
|
2136
|
+
export default defineAction({
|
|
2137
|
+
path: "/ops/archive-org",
|
|
2138
|
+
method: "POST",
|
|
2139
|
+
input: z.object({ organizationId: z.string(), operationId: z.string().optional() }),
|
|
2140
|
+
access: { userRole: ["sysadmin"], authMethod: ["cloudflare-access"] },
|
|
2141
|
+
operator: { target: { table: "organizations", by: "input.organizationId" } },
|
|
2142
|
+
async execute({ env, ctx, input }) {
|
|
2143
|
+
return runTenantOperatorOperation({
|
|
2144
|
+
env, ctx,
|
|
2145
|
+
tenantId: input.organizationId,
|
|
2146
|
+
operation: "archive",
|
|
2147
|
+
operationId: input.operationId,
|
|
2148
|
+
execute: ({ operationId }) => archiveTenant(env, input.organizationId, { operationId }),
|
|
2149
|
+
});
|
|
2150
|
+
},
|
|
2151
|
+
});
|
|
2152
|
+
```
|
|
2153
|
+
|
|
2154
|
+
With `tenancy.operator.http: false` this is the only way lifecycle mutations
|
|
2155
|
+
happen, and it carries the same transition check, confirmation, audit rows and
|
|
2156
|
+
operation id as the generated routes would.
|
|
2157
|
+
|
|
2158
|
+
**Target resolvers.** Three functions in `src/lib/tenants.ts` separate naming a
|
|
2159
|
+
tenant from creating one, so no ordinary operation can wake an object for an
|
|
2160
|
+
identifier nobody owns:
|
|
2161
|
+
|
|
2162
|
+
| Function | Admits | Never |
|
|
2163
|
+
|---|---|---|
|
|
2164
|
+
| `resolveTenantTarget(env, id)` | A registered, unpurged object (`404 TENANT_NOT_PROVISIONED`, `410 TENANT_PURGED` otherwise) | Creates state or wakes the object |
|
|
2165
|
+
| `provisionTenantTarget(env, organizationId)` | An organization that exists in Better Auth (`404 TENANT_ORGANIZATION_UNKNOWN`); wakes and registers it; idempotent | A partition name; an id Better Auth does not know |
|
|
2166
|
+
| `resolveRecoveryTarget(env, id)` | A registered row **including purged** (with `lastPurgeBookmark`), for your own exceptional recovery action | An unknown id |
|
|
2167
|
+
|
|
2168
|
+
A partition name `<orgId>:<key>` is trusted through the registry's own
|
|
2169
|
+
ownership columns, not by parsing the name: a row registered to another
|
|
2170
|
+
organization is `409 TENANT_TARGET_MISMATCH`. `runTenantOperatorOperation`
|
|
2171
|
+
applies the same check to every operation.
|
|
2172
|
+
|
|
2173
|
+
## FGA
|
|
2174
|
+
|
|
2175
|
+
With [`authz.fga`](/define/fga), `fga_tuples` is a table of every organization's
|
|
2176
|
+
object. It is not in the platform D1.
|
|
2177
|
+
|
|
2178
|
+
- `ctx.fga` (`check`, `listObjects`, `expand`, `read`, `write`) exists in the
|
|
2179
|
+
actions of tenant features. It reads and writes that organization's tuples
|
|
2180
|
+
in the object, for a caller who is a member of the organization. A delete
|
|
2181
|
+
is visible to the next check.
|
|
2182
|
+
- The edge hydrates no `ctx.fga`. It forwards `/fga/v1/*` to the caller's
|
|
2183
|
+
organization object, like a tenant route (no organization: `400 TENANT_REQUIRED`).
|
|
2184
|
+
- Tuples never cross organizations. Two organizations can hold tuples for the
|
|
2185
|
+
same object id, and each sees only its own.
|
|
2186
|
+
|
|
2187
|
+
These shapes are refused, because each would read or write tuples from
|
|
2188
|
+
somewhere other than the organization object:
|
|
2189
|
+
|
|
2190
|
+
| Code | Cause |
|
|
2191
|
+
|---|---|
|
|
2192
|
+
| `TENANCY_FGA_SHARING` | `authz.fga.sharing` is set. Share tokens and links are opened on the edge without a session. You can still write a `user:*` tuple with `ctx.fga` in a tenant action, but only members of that organization can read it: `/fga/v1` needs a signed-in member, and platform actions have no `ctx.fga`. A public page must read the app's own tables instead, such as a share-token table. |
|
|
2193
|
+
| `TENANCY_FGA_MEMBERSHIP` | `authz.fga.membership` is set. Those tuples are written from Better Auth hooks on the edge. Write the tuples from a tenant action instead. |
|
|
2194
|
+
| `TENANCY_FGA_ACCESS_ARM` | A table, action, room binding or `realtime.wsTicket` declares an `access: { fga }` arm. Call `ctx.fga.check(...)` in a tenant action instead. |
|
|
2195
|
+
| `TENANCY_FGA_MIXED` | A platform feature's action, or an action in a [partitioned](#partitions) feature, reads `ctx.fga`. A partition object's database holds no tuples. |
|
|
2196
|
+
|
|
2197
|
+
Moving to `'durable-object'` does not copy the tuples already in the features
|
|
2198
|
+
D1. `fga_tuples` leaves the platform schema, so the next generated D1
|
|
2199
|
+
migration may drop it. If you need the existing tuples, copy them into each
|
|
2200
|
+
organization's object before you apply that migration.
|
|
2201
|
+
|
|
2202
|
+
## What the compiler refuses
|
|
2203
|
+
|
|
2204
|
+
| Code | Cause |
|
|
2205
|
+
|---|---|
|
|
2206
|
+
| `TENANT_ORGANIZATION_UNKNOWN` / `TENANT_TARGET_MISMATCH` / `TENANT_PURGED` | Runtime: `provision` of an id Better Auth does not know; a partition name the registry attributes to another organization; a normal operation on a purged row (recovery uses `resolveRecoveryTarget`). |
|
|
2207
|
+
| `TENANT_OPERATION_ID_CONFLICT` / `TENANT_OPERATION_PENDING` | Runtime: a repeated operation id with different parameters; a repeated id whose receipt is not yet settled (reconcile it with `GET /tenants/operations/:id`). |
|
|
2208
|
+
| `TENANT_INVALID_TRANSITION` / `TENANT_CONFIRM_REQUIRED` / `TENANT_OPERATION_ID_INVALID` | Runtime, not compile: a lifecycle operation refused by the state machine, without its confirmation, or with a malformed operation id. See [Lifecycle operations](#lifecycle-operations). |
|
|
2209
|
+
| `TENANCY_OPERATOR_AUTH` | `tenancy.operator.http.allow` names a mutation route but `auth.cloudflareAccess` is not configured. Configure Access, allow only `backups` / `bookmark` / `outbox-receipts`, or set `http: false`. |
|
|
2210
|
+
| `TENANCY_OPERATOR_HTTP` | `tenancy.operator.http` is neither `false` nor `{ allow: [...] }` naming at least one known route, or it is set beside the deprecated `tenancy.operator.purge`. See [Operator routes](#operator-routes). |
|
|
2211
|
+
| `TENANCY_RUNTIME` / `TENANCY_PROVIDER` | The runtime is not Cloudflare, or the database is not `cloudflare-d1`. Postgres schemas, RLS and migrations do not port to Durable Object SQLite. |
|
|
2212
|
+
| `TENANCY_ORGANIZATIONS` | The Better Auth organization plugin is off. |
|
|
2213
|
+
| `TENANCY_PLACEMENT_CROSS_TENANT` | An organization-scoped table declares `placement: 'platform'`. Use `{ platform: true, crossTenant: true }`. |
|
|
2214
|
+
| `TENANCY_PLACEMENT_UNSCOPED` | A table declares `placement: 'tenant'` but no arm of its firewall — top level, `all:`, `any:` or `optional` — binds an organization column. The tenant pin needs one. |
|
|
2215
|
+
| `TENANCY_PLACEMENT_UNCONFIRMED` | The build carries no deployed-schema facts (an older CLI, or an unreadable latest snapshot), and a table derives `tenant` from an `any:` / optional organization arm. Declare its placement. |
|
|
2216
|
+
| `TENANCY_ORG_COLUMNS` | A tenant table's firewall binds more than one organization column. Keep it on the platform (`{ platform: true, crossTenant: true }`). |
|
|
2217
|
+
| `TENANCY_PLACEMENT_MOVED` | A table in the deployed features D1 derives `tenant` from its firewall (a shared project switching to `'durable-object'`, or an `any:` / optional organization arm). Declare `placement: 'tenant'` after copying its rows, or `{ platform: true, crossTenant: true }`. See [Placement changes on deployed tables](#placement-changes-on-deployed-tables). |
|
|
2218
|
+
| `TENANCY_PLACEMENT_MIXED_FEATURE` | One feature mixes tenant and platform tables. |
|
|
2219
|
+
| `TENANCY_FK_TENANT_TO_PLATFORM` | A tenant table references a platform table. References to Better Auth tables (`user`) are ids without a foreign key and are allowed. |
|
|
2220
|
+
| `TENANCY_FK_PLATFORM_TO_TENANT` | A platform table references a tenant table. |
|
|
2221
|
+
| `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. |
|
|
2222
|
+
| `TENANCY_BATCH_ASYNC` | A tenant table's `create` / `update` / `upsert` access, or its `guards`, is a function. |
|
|
2223
|
+
| `TENANCY_UNSAFE_RECREATE` | A new tenant migration recreates a referenced table or copies into an unsafe NOT NULL column. |
|
|
2224
|
+
| `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). |
|
|
2225
|
+
| `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). |
|
|
2226
|
+
| `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. |
|
|
2227
|
+
| `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). |
|
|
2228
|
+
| `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. |
|
|
2229
|
+
| `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). |
|
|
2230
|
+
| `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). |
|
|
2231
|
+
| `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). |
|
|
2232
|
+
| `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). |
|
|
2233
|
+
| `TENANCY_LEGACY_SCOPE_ENTER`, `TENANCY_LEGACY_SCOPE_MINT` | A scope kind reading a tenant table is admitted through `POST /scope/v1/enter` only, or has a `subject: 'supplied' \| 'both'` role. Permanent: use instance-bound OAuth with `subject: 'user'` roles. |
|
|
2234
|
+
| `TENANCY_NAMESPACE_SPLIT`, `_PARTITIONED`, `_UNROUTED`, `_MINT` | See [Tenant namespaces](#tenant-namespaces). |
|
|
2235
|
+
| `TENANCY_EDGE_ACTION_PLACEMENT`, `_NAMESPACE`, `_CTX` | An `edge: true` action is in a tenant feature, is not under a tenant namespace prefix, or reads `ctx.<exposeAs>`. See [Edge namespace actions](#edge-namespace-actions). |
|
|
2236
|
+
| `TENANCY_TICKET_GATE_UNSUPPORTED` | A `realtime.wsTicket` session gate on a tenant room isn't the tenant-backed kind's own admission, plus at most one `{ roles }` lane of plain organization roles. See [Durable Objects → Tenant rooms](/platform/realtime/durable-objects#tenant-rooms). |
|
|
2237
|
+
| `TENANCY_ROOM_LOOKUP` | A resource-backed realtime room (`bindings.durableObjects[].access.resource`) on a tenant table has no `tenancy.lookups` entry on its room key column. See [Durable Objects → Tenant rooms](/platform/realtime/durable-objects#tenant-rooms). |
|
|
2238
|
+
| `TENANCY_ROOM_UNSUPPORTED` | A realtime room on a tenant table uses a form the tenant gate can't run: multi-resource `access.resources`, a partitioned table, or an inherited `read.access` with a `record:` predicate. |
|
|
2239
|
+
| `TENANCY_ADMISSION_ID_STRATEGY` | A tenant-backed scope kind's instance or proving table has `generateId: false \| 'short' \| 'serial'`, `allowClientIds: true`, or a numeric primary key (see [Tenant-backed scope kinds](#tenant-backed-scope-kinds)). Or tenant code (an action, a helper it reaches, or a trigger handler) inserts into a scope instance or proving table with an explicit `id`, a spread that may carry one, or a row it can't inspect. Omit `id`; `// quickback-allow-id` is honored only for `crypto.randomUUID()` / `generateId(…)`. |
|
|
2240
|
+
| `TENANCY_REALTIME_PLATFORM_ROOM` | With a tenant-backed scope kind, a tenant table's CRUD broadcasts (`realtime.scopeTable` / `scopeKeyFrom`) target a room that is not on a tenant table, or the ws-ticket's bound kind is tenant-backed but its `scopeTable` is a platform table. A tenant object can address only rooms on its own tables. |
|
|
2241
|
+
| `TENANCY_REALTIME_TAG_AMBIGUOUS` | A tenant-backed kind proves subjects from more than one table, and a recipients resolver calls `recipient.scope({ kind, subjectId })` for it (or with a `kind` the compiler can't read) without `provingTable`, so the tenant tag can't name the proving table. The error lists each call's file and line. Pass `provingTable`. |
|
|
2242
|
+
| `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. |
|
|
2243
|
+
| `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. |
|
|
2244
|
+
| `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. |
|
|
2245
|
+
| `TENANCY_UNSUPPORTED` | A tenant table declares `embeddings`, `namespace`, `owns`, an `.encrypted()` / `.sealed()` column, or a `q.storageKey()` column. |
|
|
2246
|
+
| `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. |
|
|
2247
|
+
| `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. |
|
|
2248
|
+
| `TENANCY_LOOKUP` | A lookup's table is not a tenant table, or its column is not a column of that table. |
|
|
2249
|
+
| `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. |
|
|
2250
|
+
| `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. |
|
|
2251
|
+
| `TENANCY_QUEUE_PARTITION` / `TENANCY_QUEUE_MIXED_PLACEMENT` | A queue handler imports a partitioned feature or mixes database placements. Split the job into supported handlers. |
|
|
2252
|
+
| `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`. |
|
|
2253
|
+
| `TENANCY_NAMESPACE_DELETION` | See [Deleting the namespace](#deleting-the-namespace). |
|
|
2254
|
+
| `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. |
|
|
2255
|
+
| `TENANCY_ROUTE_RESERVED` / `TENANCY_ADMIN_NOT_BEHIND_ACCESS` | A feature mounts at `/tenants`, or Access is configured and no application covers the operator routes. |
|
|
2256
|
+
| `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. |
|
|
2257
|
+
| `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). |
|
|
2258
|
+
| `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). |
|
|
2259
|
+
| `TENANCY_PURGE_DO` / `TENANCY_CHANGES` / `TENANCY_FGA` | `tenancy.purge`, `changes`, or a top-level `fga` block (declare it at `authz.fga`) together with `isolation: 'durable-object'`. |
|
|
2260
|
+
| `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. See [FGA](#fga). |
|
|
2261
|
+
|
|
2262
|
+
|
|
2263
|
+
### Fence a result job to an authorization epoch
|
|
2264
|
+
|
|
2265
|
+
`callTenantJob(env, tenantId, message, runId, { expectedAuthorizationEpoch })`
|
|
2266
|
+
optionally requires a safe nonnegative integer epoch. The tenant compares it
|
|
2267
|
+
with its live admission permit before executing **or replaying** a result. A
|
|
2268
|
+
mismatch returns `{ status: 'unavailable', code: 'TENANT_AUTHORIZATION_EPOCH_CHANGED' }`.
|
|
2269
|
+
The expected epoch also participates in the durable run hash: reusing a run ID
|
|
2270
|
+
with a different fence produces `TENANT_JOB_RUN_CONFLICT` once admitted.
|
|
2271
|
+
|
|
2272
|
+
Result handlers receive readonly `authorizationEpoch?: number` from that same
|
|
2273
|
+
permit, including ordinary four-argument calls. This value never comes from the
|
|
2274
|
+
message. Preserve it in a server-owned proof when subsequent work must be
|
|
2275
|
+
invalidated by restore. Other queue handlers may omit it. This does not change
|
|
2276
|
+
archive, restore or purge admission. RPC version 8 is required; deploy the tenant
|
|
2277
|
+
worker before the edge worker. Older workers fail closed on the new contract.
|
|
2278
|
+
|
|
2279
|
+
|
|
2280
|
+
### Fence purge to a retained backup
|
|
2281
|
+
|
|
2282
|
+
Operators retaining records before erasure can use
|
|
2283
|
+
`purgeTenant(env, tenantId, tenantId, { expectedBackup: { key, generation, bytes } })`.
|
|
2284
|
+
Pass the completed archived backup receipt whose contents were retained. The
|
|
2285
|
+
options and receipt accept exactly those keys. The receipt must name this
|
|
2286
|
+
organization's backup and contain a positive safe integer byte count. This
|
|
2287
|
+
fence does not download bytes and has no backup-download size cap.
|
|
2288
|
+
|
|
2289
|
+
Under exclusive control admission, before permanent purge marking, the tenant
|
|
2290
|
+
requires that receipt to match its latest completed archived backup, current
|
|
2291
|
+
generation and clean state. A completed restore, subsequent writes after
|
|
2292
|
+
unarchive, or a replacement backup refuse with `TENANT_PURGE_BACKUP_STALE`.
|
|
2293
|
+
Nothing is erased and a known rejected fence is released. In-flight work or
|
|
2294
|
+
restore continues to refuse under the existing maintenance contract.
|
|
2295
|
+
|
|
2296
|
+
The permanent purge marker retains the receipt identity outside erased tenant
|
|
2297
|
+
storage. A retry with that same receipt can finish after an interrupted erase;
|
|
2298
|
+
a different receipt, or a fenced retry of an originally unfenced purge, refuses.
|
|
2299
|
+
The original three-argument trusted-operator API remains available, including
|
|
2300
|
+
finishing an already marked purge without supplying a receipt. It cannot alter
|
|
2301
|
+
the permanent receipt or re-enable the tenant. Applications requiring retention
|
|
2302
|
+
must consistently supply the fourth argument before their first irreversible
|
|
2303
|
+
purge. RPC version 9 is required: deploy the tenant worker before the edge worker;
|
|
2304
|
+
older workers fail closed. No room-deletion callback or general maintenance
|
|
2305
|
+
callback is exposed by this API.
|
|
2306
|
+
|
|
2307
|
+
|
|
2308
|
+
### Hold admission through a resource room's native commit
|
|
2309
|
+
|
|
2310
|
+
Result jobs and outbox delivery do not keep a permit around their consumer's
|
|
2311
|
+
later native Durable Object commit. For a declared, locally authored room on a
|
|
2312
|
+
non-partitioned tenant resource, call `acquireTenantRoomPermit` **inside the
|
|
2313
|
+
actual room operation**, while holding its own work gate:
|
|
2314
|
+
|
|
2315
|
+
```ts no-compile
|
|
2316
|
+
import { tenantRoomSession } from "../../../lib/tenant-room-session";
|
|
2317
|
+
import { acquireTenantRoomPermit, releaseTenantRoomPermit } from "../../../lib/tenants";
|
|
2318
|
+
|
|
2319
|
+
// Method on the existing room class. No FIFO, admission, name initialization,
|
|
2320
|
+
// or native storage I/O here: control calls back while this actor awaits it.
|
|
2321
|
+
getTenantRoomSession(version: number) {
|
|
2322
|
+
return tenantRoomSession(this.ctx, version);
|
|
2323
|
+
}
|
|
2324
|
+
|
|
2325
|
+
// Inside the actual authorized room operation, after taking its work gate:
|
|
2326
|
+
const permit = await acquireTenantRoomPermit(this.env, verifiedTenantId, this.ctx, {
|
|
2327
|
+
binding: "PAGE_ROOM",
|
|
2328
|
+
key: roomKey,
|
|
2329
|
+
operationId, // stable server-owned id for THIS operation's exact retries
|
|
2330
|
+
expectedAuthorizationEpoch,
|
|
2331
|
+
});
|
|
2332
|
+
// All SQL authority reads, binary checks and native transaction retries must
|
|
2333
|
+
// settle here. Keep the existing resource-pointer/native CAS checks.
|
|
2334
|
+
await commitNativeCheckpoint();
|
|
2335
|
+
await this.ctx.storage.sync();
|
|
2336
|
+
await releaseTenantRoomPermit(this.env, this.ctx, permit);
|
|
2337
|
+
```
|
|
2338
|
+
|
|
2339
|
+
Do not put release in an unconditional `finally`: a timeout, failed sync or
|
|
2340
|
+
unsettled continuation is not proof that no native commit can still happen.
|
|
2341
|
+
An ambiguous acquire/release retains quarantine; retry that exact operation or
|
|
2342
|
+
prove the actual room actor was replaced. A new operation must have its own ID.
|
|
2343
|
+
Released/denied identities remain terminal in individual durable records; the
|
|
2344
|
+
shared index contains only active operations. Delayed acquisition cannot
|
|
2345
|
+
resurrect them. Exact concurrent retries share the final ownership outcome;
|
|
2346
|
+
late failed cleanup cannot release a grant another retry already received.
|
|
2347
|
+
Duplicate requests wait on their own bounded timer, never another request's
|
|
2348
|
+
I/O promise. Timing out does not release admission.
|
|
2349
|
+
|
|
2350
|
+
The tenant verifies the live actor session through the declared existing room
|
|
2351
|
+
namespace, the current epoch/generation, and exactly one undeleted resource row
|
|
2352
|
+
using its parsed organization/key/deletion columns. It returns captured
|
|
2353
|
+
`authorizationEpoch`, `generation` and the permit token. This is ownership and
|
|
2354
|
+
restore admission, not user authorization: keep the application's operator/user
|
|
2355
|
+
checks and resource-pointer CAS. Ordinary admitted jobs can still change a
|
|
2356
|
+
resource while this permit is held; the permit blocks exclusive restore, purge
|
|
2357
|
+
and backup maintenance, not ordinary application edits.
|
|
2358
|
+
|
|
2359
|
+
The public helper takes the actual native `DurableObjectState` and derives its
|
|
2360
|
+
private session; it does not accept a supplied session string. An edge caller
|
|
2361
|
+
with a made-up object gets a different UUID and cannot borrow the live room
|
|
2362
|
+
session merely by reading the callback. Release also requires that same actual
|
|
2363
|
+
state/session. A session is private to that actor instance, never persisted or
|
|
2364
|
+
a module-wide UUID shared by rooms. `tenantRoomSession` uses a WeakMap keyed by
|
|
2365
|
+
its actual DurableObjectState and performs no I/O. Pruning compares the live
|
|
2366
|
+
room session, not the tenant actor's session. Tenant/control restart, elapsed
|
|
2367
|
+
time, a missing method or a probe error never retire a live room permit. An
|
|
2368
|
+
actual room replacement proves that its old continuation cannot access native
|
|
2369
|
+
storage. It may still finish external I/O; immutable R2/artifact safety remains
|
|
2370
|
+
a separate application protocol. See [DO shutdown semantics](https://developers.cloudflare.com/durable-objects/concepts/durable-object-lifecycle/)
|
|
2371
|
+
and [storage sync/output gates](https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/).
|
|
2372
|
+
|
|
2373
|
+
Room records and an armed compatibility guard are stored atomically outside
|
|
2374
|
+
the tenant's restored database. Older control code sees a non-purge operation
|
|
2375
|
+
with an unknown recovery kind and refuses restore, purge and recovery. It cannot
|
|
2376
|
+
prune the separate room records. Only the room-aware release or a proven room
|
|
2377
|
+
restart clears the last active record and its guard together. Unknown or
|
|
2378
|
+
inconsistent state blocks admission and exclusive maintenance. RPC version 10
|
|
2379
|
+
is required; room permit calls never fall back to an older protocol. Rolling
|
|
2380
|
+
back while a room permit is held intentionally retains quarantine.
|
|
2381
|
+
|
|
2382
|
+
The compiler adds private tenant-worker bindings to **existing edge room
|
|
2383
|
+
classes**, with the matching edge script for each named environment. It adds no
|
|
2384
|
+
room class, namespace or migration. External-script rooms, partitioned resource
|
|
2385
|
+
rooms and rooms without a provable parsed organization column cannot use this
|
|
2386
|
+
API. Authored tenant handlers still cannot read the private bindings. Deploying
|
|
2387
|
+
a tenant that references a previously undeployed edge class may require the
|
|
2388
|
+
existing edge class to be deployed first. For an upgrade, a compatibility phase
|
|
2389
|
+
can add the zero-I/O `getTenantRoomSession` method using a private per-instance
|
|
2390
|
+
UUID to the **already existing** edge room class before introducing the tenant's
|
|
2391
|
+
reverse binding or the full room-permit configuration. Then the room-aware
|
|
2392
|
+
tenant can bind that existing class, followed by the full edge configuration. The full room class must then use
|
|
2393
|
+
the same generated WeakMap helper for both its callback and acquisition; a
|
|
2394
|
+
compatibility-only private UUID must not remain a different identity source.
|
|
2395
|
+
This is an artifact/rollout plan, not a deployment performed by compilation.
|
|
2396
|
+
|
|
2397
|
+
A completely fresh pair has circular edge `TENANT` and tenant `ROOM` references.
|
|
2398
|
+
Its account bootstrap/provisioning order needs a separate account-stage drill;
|
|
2399
|
+
local generation and Wrangler dry-run do not prove that one deployment creates
|
|
2400
|
+
such a pair without extra setup. Named-environment bindings must target that
|
|
2401
|
+
specific environment's existing edge Worker/class, and the deployment must
|
|
2402
|
+
verify those physical namespaces before enabling room commits. No raw SQL
|
|
2403
|
+
opener or arbitrary callback bridge is added.
|
|
2404
|
+
Local fault-adapter tests can drop an RPC reply before helper validation or
|
|
2405
|
+
reject an application acknowledgement after native `storage.sync()` completed.
|
|
2406
|
+
Those seams do not establish physical network loss or a native storage engine
|
|
2407
|
+
failure; the corresponding native/account failure drills remain open.
|