@quickback-dev/cli 0.72.9 → 0.72.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +8 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/db-explain.d.ts +67 -0
- package/dist/commands/db-explain.d.ts.map +1 -0
- package/dist/commands/db-explain.js +141 -0
- package/dist/commands/db-explain.js.map +1 -0
- package/dist/commands/db-export.d.ts +34 -0
- package/dist/commands/db-export.d.ts.map +1 -0
- package/dist/commands/db-export.js +250 -0
- package/dist/commands/db-export.js.map +1 -0
- package/dist/commands/db-insights.d.ts +60 -0
- package/dist/commands/db-insights.d.ts.map +1 -0
- package/dist/commands/db-insights.js +106 -0
- package/dist/commands/db-insights.js.map +1 -0
- package/dist/commands/db-recovery.d.ts +98 -0
- package/dist/commands/db-recovery.d.ts.map +1 -0
- package/dist/commands/db-recovery.js +558 -0
- package/dist/commands/db-recovery.js.map +1 -0
- package/dist/commands/db-target.d.ts +27 -0
- package/dist/commands/db-target.d.ts.map +1 -0
- package/dist/commands/db-target.js +83 -0
- package/dist/commands/db-target.js.map +1 -0
- package/dist/commands/db.d.ts +3 -0
- package/dist/commands/db.d.ts.map +1 -0
- package/dist/commands/db.js +43 -0
- package/dist/commands/db.js.map +1 -0
- package/dist/commands/effects.d.ts +8 -0
- package/dist/commands/effects.d.ts.map +1 -0
- package/dist/commands/effects.js +48 -0
- package/dist/commands/effects.js.map +1 -0
- package/dist/commands/platform-budget.d.ts +143 -0
- package/dist/commands/platform-budget.d.ts.map +1 -0
- package/dist/commands/platform-budget.js +619 -0
- package/dist/commands/platform-budget.js.map +1 -0
- package/dist/commands/preview.d.ts +57 -0
- package/dist/commands/preview.d.ts.map +1 -0
- package/dist/commands/preview.js +268 -0
- package/dist/commands/preview.js.map +1 -0
- package/dist/commands/search.d.ts +20 -0
- package/dist/commands/search.d.ts.map +1 -0
- package/dist/commands/search.js +133 -0
- package/dist/commands/search.js.map +1 -0
- package/dist/index.js +35 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +4 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
- package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
- package/dist/lib/cloudflare-spend-policies.js +289 -0
- package/dist/lib/cloudflare-spend-policies.js.map +1 -0
- package/dist/lib/compiler-stubs.d.ts +2 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +2 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/d1-fingerprint.d.ts +8 -0
- package/dist/lib/d1-fingerprint.d.ts.map +1 -0
- package/dist/lib/d1-fingerprint.js +113 -0
- package/dist/lib/d1-fingerprint.js.map +1 -0
- package/dist/lib/file-loader.d.ts +12 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +27 -1
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts +6 -5
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +24 -12
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
- package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/search.js +160 -0
- package/dist/lib/migrations/postprocessors/search.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +7 -0
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +3 -0
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +1 -1
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +1 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/preview-lifecycle.d.ts +139 -0
- package/dist/lib/preview-lifecycle.d.ts.map +1 -0
- package/dist/lib/preview-lifecycle.js +429 -0
- package/dist/lib/preview-lifecycle.js.map +1 -0
- package/dist/lib/preview.d.ts +146 -0
- package/dist/lib/preview.d.ts.map +1 -0
- package/dist/lib/preview.js +417 -0
- package/dist/lib/preview.js.map +1 -0
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +4 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/SKILL.md +9 -3
- package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/dist/skill/docs/api/batch-operations.md +19 -0
- package/dist/skill/docs/api/caching.md +17 -0
- package/dist/skill/docs/api/crud.md +9 -0
- package/dist/skill/docs/api/errors.md +31 -2
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/changelog/index.md +1 -0
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/bindings.md +177 -1
- package/dist/skill/docs/configure/cloudflare-access.md +43 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/providers.md +5 -0
- package/dist/skill/docs/configure/tenant-databases.md +627 -14
- package/dist/skill/docs/define/access.md +26 -0
- package/dist/skill/docs/define/actions/defining.md +7 -1
- package/dist/skill/docs/define/actions/index.md +5 -0
- package/dist/skill/docs/define/actions/scoped-db.md +127 -1
- package/dist/skill/docs/define/authoring-basics.md +92 -0
- package/dist/skill/docs/define/changesets.md +8 -0
- package/dist/skill/docs/define/encryption.md +48 -2
- package/dist/skill/docs/define/feature.md +17 -2
- package/dist/skill/docs/define/guards.md +11 -3
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/invariants.md +321 -0
- package/dist/skill/docs/define/issue-tracker-example.md +225 -0
- package/dist/skill/docs/define/masking.md +3 -3
- package/dist/skill/docs/define/rate-limit.md +63 -22
- package/dist/skill/docs/define/read.md +332 -5
- package/dist/skill/docs/define/relationships.md +10 -0
- package/dist/skill/docs/define/schema.md +137 -10
- package/dist/skill/docs/define/scopes.md +1 -0
- package/dist/skill/docs/define/transitions.md +9 -0
- package/dist/skill/docs/define/triggers.md +127 -1
- package/dist/skill/docs/platform/api-contract/index.md +35 -4
- package/dist/skill/docs/platform/auth/api-keys.md +26 -3
- package/dist/skill/docs/platform/auth/index.md +5 -2
- package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +73 -1
- package/dist/skill/docs/platform/database/durable-effects.md +224 -0
- package/dist/skill/docs/platform/database/read-replication.md +9 -0
- package/dist/skill/docs/platform/database/recovery.md +292 -0
- package/dist/skill/docs/platform/database/using-d1.md +152 -2
- package/dist/skill/docs/platform/index.md +1 -0
- package/dist/skill/docs/platform/operations/budgets.md +224 -0
- package/dist/skill/docs/platform/queues/handlers.md +1 -0
- package/dist/skill/docs/platform/queues/index.md +18 -0
- package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
- package/dist/skill/docs/platform/storage/using-r2.md +13 -0
- package/dist/skill/docs/platform/vector/embeddings.md +28 -4
- package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/dist/skill/docs/platform/workflows/index.md +385 -0
- package/dist/skill/docs/start/deploy-browser.md +51 -0
- package/dist/skill/docs/start/deploy.md +97 -1
- package/dist/skill/docs/tooling/cli.md +117 -0
- package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/dist/skill/docs/ui/account/customization.md +4 -0
- package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
- package/package.json +1 -1
- package/src/skill/SKILL.md +9 -3
- package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/src/skill/docs/api/batch-operations.md +19 -0
- package/src/skill/docs/api/caching.md +17 -0
- package/src/skill/docs/api/crud.md +9 -0
- package/src/skill/docs/api/errors.md +31 -2
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/changelog/index.md +1 -0
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/bindings.md +177 -1
- package/src/skill/docs/configure/cloudflare-access.md +43 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/providers.md +5 -0
- package/src/skill/docs/configure/tenant-databases.md +627 -14
- package/src/skill/docs/define/access.md +26 -0
- package/src/skill/docs/define/actions/defining.md +7 -1
- package/src/skill/docs/define/actions/index.md +5 -0
- package/src/skill/docs/define/actions/scoped-db.md +127 -1
- package/src/skill/docs/define/authoring-basics.md +92 -0
- package/src/skill/docs/define/changesets.md +8 -0
- package/src/skill/docs/define/encryption.md +48 -2
- package/src/skill/docs/define/feature.md +17 -2
- package/src/skill/docs/define/guards.md +11 -3
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/invariants.md +321 -0
- package/src/skill/docs/define/issue-tracker-example.md +225 -0
- package/src/skill/docs/define/masking.md +3 -3
- package/src/skill/docs/define/rate-limit.md +63 -22
- package/src/skill/docs/define/read.md +332 -5
- package/src/skill/docs/define/relationships.md +10 -0
- package/src/skill/docs/define/schema.md +137 -10
- package/src/skill/docs/define/scopes.md +1 -0
- package/src/skill/docs/define/transitions.md +9 -0
- package/src/skill/docs/define/triggers.md +127 -1
- package/src/skill/docs/platform/api-contract/index.md +35 -4
- package/src/skill/docs/platform/auth/api-keys.md +26 -3
- package/src/skill/docs/platform/auth/index.md +5 -2
- package/src/skill/docs/platform/auth/plugins/index.md +1 -1
- package/src/skill/docs/platform/database/d1.md +73 -1
- package/src/skill/docs/platform/database/durable-effects.md +224 -0
- package/src/skill/docs/platform/database/read-replication.md +9 -0
- package/src/skill/docs/platform/database/recovery.md +292 -0
- package/src/skill/docs/platform/database/using-d1.md +152 -2
- package/src/skill/docs/platform/index.md +1 -0
- package/src/skill/docs/platform/operations/budgets.md +224 -0
- package/src/skill/docs/platform/queues/handlers.md +1 -0
- package/src/skill/docs/platform/queues/index.md +18 -0
- package/src/skill/docs/platform/realtime/table-changes.md +1 -0
- package/src/skill/docs/platform/storage/using-r2.md +13 -0
- package/src/skill/docs/platform/vector/embeddings.md +28 -4
- package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/src/skill/docs/platform/workflows/index.md +385 -0
- package/src/skill/docs/start/deploy-browser.md +51 -0
- package/src/skill/docs/start/deploy.md +97 -1
- package/src/skill/docs/tooling/cli.md +117 -0
- package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/src/skill/docs/ui/account/customization.md +4 -0
- package/src/skill/docs/ui/admin/record-layouts.md +3 -3
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
# Rate Limit -
|
|
1
|
+
# Rate Limit - Weighted Requests and Shared Buckets
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Approximate request throttling for CRUD endpoints and actions, with optional static weights and explicitly shared buckets. Backed by Cloudflare's native [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) — no extra storage, no third-party libraries.
|
|
4
4
|
|
|
5
5
|
## Defaults
|
|
6
6
|
|
|
7
|
-
Every resource gets these limits automatically (per
|
|
7
|
+
Every resource gets these limits automatically (per caller identity, per minute, within each Cloudflare location):
|
|
8
8
|
|
|
9
9
|
| Operation | Default |
|
|
10
10
|
|-----------|---------|
|
|
@@ -13,7 +13,7 @@ Every resource gets these limits automatically (per authenticated user, per minu
|
|
|
13
13
|
| `update` | 200 / 60s |
|
|
14
14
|
| `delete` | 200 / 60s |
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
These defaults are request-shaping thresholds, not strict quotas. Override per operation or opt out wherever they do not fit.
|
|
17
17
|
|
|
18
18
|
## Override one operation
|
|
19
19
|
|
|
@@ -84,22 +84,24 @@ export default defineConfig({
|
|
|
84
84
|
|
|
85
85
|
```typescript
|
|
86
86
|
rateLimit?: {
|
|
87
|
-
read?: { limit: number, period: 10 | 60 };
|
|
88
|
-
create?: { limit: number, period: 10 | 60 };
|
|
89
|
-
update?: { limit: number, period: 10 | 60 };
|
|
90
|
-
delete?: { limit: number, period: 10 | 60 };
|
|
87
|
+
read?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
|
|
88
|
+
create?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
|
|
89
|
+
update?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
|
|
90
|
+
delete?: { limit: number, period: 10 | 60, delta?: number, bucket?: string };
|
|
91
91
|
} | false
|
|
92
92
|
```
|
|
93
93
|
|
|
94
94
|
- `period` must be `10` or `60` (Cloudflare binding constraint — anything else is a compile-time error).
|
|
95
95
|
- `limit` is a positive integer.
|
|
96
|
-
-
|
|
96
|
+
- `delta` is an optional **positive safe integer** (`1` through `Number.MAX_SAFE_INTEGER`). Omitted means one. It is static configuration, never derived from request bodies, row counts, or callbacks.
|
|
97
|
+
- `bucket` is an optional lowercase slug of 1–64 characters matching `[a-z0-9][a-z0-9_-]*`.
|
|
98
|
+
- Omit an operation to inherit the whole project policy (or shipped default). An explicit operation policy **replaces** the inherited policy: omitted `delta` becomes one and omitted `bucket` restores the route-specific key. Individual policy fields are not merged.
|
|
97
99
|
- Set `false` at resource or project level to opt out.
|
|
98
100
|
|
|
99
101
|
## Resolution order
|
|
100
102
|
|
|
101
103
|
1. Project `rateLimit: false` → no enforcement anywhere
|
|
102
|
-
2. Resource `rateLimit: false` → no enforcement
|
|
104
|
+
2. Resource `rateLimit: false` → no CRUD enforcement or inherited action policy (an explicit record-action override still applies)
|
|
103
105
|
3. Resource per-op override
|
|
104
106
|
4. Project per-op default
|
|
105
107
|
5. Quickback shipped defaults (1000 / 200 above)
|
|
@@ -108,7 +110,7 @@ Default-using resources collapse onto two shared bindings (`RL_1000_60`, `RL_200
|
|
|
108
110
|
|
|
109
111
|
## How requests are keyed
|
|
110
112
|
|
|
111
|
-
|
|
113
|
+
Without an explicit bucket, each CRUD handler composes a key as `<resource>:<op>:<identity>`. The identity is the caller's `userId`. A sessionless scope-only principal (for example an event pass, which has no `userId`) is keyed on its verified JWT subject, `scope:<kind>:<subjectId>`, so every pass holder gets their own bucket even when many of them share one network. Callers with neither, including unauthenticated requests later rejected by a private handler, fall back to the client's `cf-connecting-ip` header, then to the literal `'anon'` if that header is absent too.
|
|
112
114
|
|
|
113
115
|
This means:
|
|
114
116
|
|
|
@@ -134,7 +136,11 @@ simple = { limit = 200, period = 60 }
|
|
|
134
136
|
|
|
135
137
|
`namespace_id` is a stable per-tuple integer (`1000 + period * 1_000_000 + limit`), so it survives resource reordering and never drifts across recompiles.
|
|
136
138
|
|
|
137
|
-
|
|
139
|
+
The platform auth middleware verifies credentials and populates `ctx` before resource routes run. CRUD rate-limit middleware runs before the handler's authentication requirement and access checks; action checks run near handler entry, also before those gates. Earlier platform or namespace middleware can reject a request before it reaches a limiter. This feature does not move any auth middleware.
|
|
140
|
+
|
|
141
|
+
The generated check makes one native `.limit({ key, delta })` call; a policy with no weight uses the native default of one. A successful check is not refunded if later authorization, validation, or execution fails. Missing bindings skip the check, including a Cloudflare environment where the binding is absent.
|
|
142
|
+
|
|
143
|
+
A rejected check returns:
|
|
138
144
|
|
|
139
145
|
```http
|
|
140
146
|
HTTP/1.1 429 Too Many Requests
|
|
@@ -144,16 +150,18 @@ Content-Type: application/json
|
|
|
144
150
|
{ "error": "Rate limit exceeded", "code": "RATE_LIMITED", "retryAfter": 60 }
|
|
145
151
|
```
|
|
146
152
|
|
|
153
|
+
`Retry-After` and `retryAfter` are conservative period hints, not an exact reset time. The 429 response shape is unchanged.
|
|
154
|
+
|
|
147
155
|
## Batch endpoints
|
|
148
156
|
|
|
149
|
-
Batch routes (`POST /batch`, `PATCH /batch`, `DELETE /batch`, `PUT /batch`)
|
|
157
|
+
Batch routes (`POST /batch`, `PATCH /batch`, `DELETE /batch`, `PUT /batch`) charge their operation's static `delta` **once per request**, regardless of row count. With no weight configured, a batch of 100 records consumes one unit.
|
|
150
158
|
|
|
151
159
|
## Actions
|
|
152
160
|
|
|
153
161
|
Custom actions (record-based and standalone) inherit rate limits without configuration:
|
|
154
162
|
|
|
155
|
-
- **Record-based actions** (e.g. `POST /api/v1/claims/:id/approve`) inherit the resource's `update` (
|
|
156
|
-
- **Standalone actions** (e.g. `POST /api/v1/twilioIncoming`) inherit the project-default `update`
|
|
163
|
+
- **Record-based actions** (e.g. `POST /api/v1/claims/:id/approve`) inherit the resource's `update` policy (limit, period, weight, and optional shared bucket). Without an explicit bucket they still use their own action counter; exhausting CRUD `update` does not exhaust `approve`.
|
|
164
|
+
- **Standalone actions** (e.g. `POST /api/v1/twilioIncoming`) inherit the project-default `update` policy — they don't belong to a resource.
|
|
157
165
|
|
|
158
166
|
Override either with the action's `rateLimit` field:
|
|
159
167
|
|
|
@@ -189,7 +197,7 @@ export default defineAction({
|
|
|
189
197
|
|
|
190
198
|
Set `rateLimit: false` to opt the action out of enforcement entirely.
|
|
191
199
|
|
|
192
|
-
**Key composition
|
|
200
|
+
**Key composition without `bucket`** — actions get their own keyspace:
|
|
193
201
|
|
|
194
202
|
| Action kind | Key shape |
|
|
195
203
|
|-------------|-----------|
|
|
@@ -198,7 +206,37 @@ Set `rateLimit: false` to opt the action out of enforcement entirely.
|
|
|
198
206
|
|
|
199
207
|
The `:action:` infix is what keeps `update` (resource bucket) and `approve` (action bucket) from sharing counters when they happen to land on the same binding name.
|
|
200
208
|
|
|
201
|
-
A record action's bulk variant (`POST /<resource>/batch/<action>`) shares its single-record sibling's key exactly
|
|
209
|
+
A record action's bulk variant (`POST /<resource>/batch/<action>`) shares its single-record sibling's key exactly and charges the configured static `delta` once. Action routes are exempted from the surrounding CRUD limiter, including actions with `rateLimit: false`, so there is no second CRUD charge.
|
|
210
|
+
|
|
211
|
+
## Weighted requests and shared buckets
|
|
212
|
+
|
|
213
|
+
These policies combine inexpensive reads and an expensive export for the same caller:
|
|
214
|
+
|
|
215
|
+
```typescript
|
|
216
|
+
// In defineTable(...):
|
|
217
|
+
rateLimit: {
|
|
218
|
+
read: { limit: 100, period: 60, delta: 1, bucket: 'catalog' },
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
```typescript
|
|
223
|
+
// In defineAction(...):
|
|
224
|
+
rateLimit: { limit: 100, period: 60, delta: 10, bucket: 'catalog' }
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
The shared key is `qb:bucket:<project-name>:<bucket>:<identity>`. Project name and bucket come from validated configuration; identity uses the same verified user ID, verified scope subject, then IP/`anon` fallback described above. Request-supplied bucket names, weights, user IDs, or tenant IDs cannot select this key. A bucket combines selected request classes **per identity**, not all users or an entire organization.
|
|
228
|
+
|
|
229
|
+
Every declaration of a bucket in a compiled Worker, including project defaults, must agree on `(limit, period)`. Weights may differ. Conflicts fail compilation with both config paths. Different weights do not create additional bindings.
|
|
230
|
+
|
|
231
|
+
Cloudflare decides from the count **before** a call. A call below the threshold succeeds even when its weight takes the count over the threshold. A rejected call does not increment the count. Counts are approximate and eventually consistent within a location; other Cloudflare locations keep separate counts. Awaiting every call does not make the allowance exact. See [Cloudflare's weighted request contract](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/#weighted-requests).
|
|
232
|
+
|
|
233
|
+
Use `db.ledger` for strict balances, reservations, and finalization; weighted throttling is not billing, a strict business quota, or accounting. There are no refunds, reservations, dynamic weights, or post-execution adjustments in this API.
|
|
234
|
+
|
|
235
|
+
### Projects, environments, and existing counters
|
|
236
|
+
|
|
237
|
+
Named environments retain their explicitly configured rate-limit namespace IDs. Use distinct namespaces per environment; the shared key intentionally includes the project name, not the environment name. Different project names separate explicit bucket keys, but deliberately reusing an account-level namespace **and the same key** can share counters across Workers. Legacy route keys remain unchanged and do not gain a project prefix.
|
|
238
|
+
|
|
239
|
+
Adding `bucket` selects a different counter; removing it returns to the route-specific counter. Changing a weight changes future consumption without migrating data. This feature does not reset account counters. Recompile and update generated project dependencies before local use. Weighted local development requires Wrangler **4.157.0+** and workers-types **5.20261106.1+**; Quickback's generated lower bounds are **4.157.0** and **5.20261118.1**, respectively. Wrangler requires **Node 22+**. No compatibility-date change is implied.
|
|
202
240
|
|
|
203
241
|
## Cardinality — how many bindings ship
|
|
204
242
|
|
|
@@ -207,22 +245,22 @@ Cloudflare bindings are sized at compile time (limit + period are baked in), so
|
|
|
207
245
|
| Configuration | Bindings emitted |
|
|
208
246
|
|---------------|------------------|
|
|
209
247
|
| All defaults | 2 (`RL_1000_60` for reads, `RL_200_60` for writes) |
|
|
210
|
-
| One project-wide read override (`read: { limit: 500, period: 60 }`) |
|
|
248
|
+
| One project-wide read override (`read: { limit: 500, period: 60 }`) | 2 (`RL_500_60`, `RL_200_60`); a third only if a resource explicitly declares another tuple |
|
|
211
249
|
| Five resources tightening `delete` to `{ limit: 5, period: 60 }` | 3 (defaults + `RL_5_60` shared) |
|
|
212
250
|
| Ten distinct per-action overrides at unique tuples | 12 (defaults + ten action buckets) |
|
|
213
251
|
|
|
214
252
|
**Practical caps.** Cloudflare workers have generous binding limits (hundreds), so this is unlikely to be a real ceiling — but it's the reason every distinct `(limit, period)` you write on a `rateLimit` config widens the binding set, even when the same resource declares the same tuple multiple times. Resource-level configs that share a tuple share a binding and simply produce different runtime keys.
|
|
215
253
|
|
|
216
|
-
**Key cardinality is separate.** Each binding holds an independent counter per key. A binding called via `claims:read:user_123` and `applications:read:user_123` consumes two separate counters in the same binding — fan-out cost lives in Cloudflare's distributed counter store, not in your binding count.
|
|
254
|
+
**Key cardinality is separate.** Each binding holds an independent counter per key. A binding called via `claims:read:user_123` and `applications:read:user_123` consumes two separate counters in the same binding — fan-out cost lives in Cloudflare's distributed counter store, not in your binding count. Without `bucket`, the allowance is per `(resource, op, identity)`. With `bucket`, selected operations use the shared key for that identity.
|
|
217
255
|
|
|
218
256
|
## Runtime support
|
|
219
257
|
|
|
220
258
|
| Runtime | Rate limiting |
|
|
221
259
|
|---------|---------------|
|
|
222
260
|
| `cloudflare` | Backed by Cloudflare's native [Rate Limiting binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) |
|
|
223
|
-
| non-Cloudflare (`bun`, `node`) |
|
|
261
|
+
| non-Cloudflare (`bun`, `node`) | No enforcement — the check no-ops when the binding is absent from `c.env` |
|
|
224
262
|
|
|
225
|
-
Every generated rate-limit call site — CRUD middleware and custom actions alike — first looks up `c.env.RL_<limit>_<period>` and only calls
|
|
263
|
+
Every generated rate-limit call site — CRUD middleware and custom actions alike — first looks up `c.env.RL_<limit>_<period>` and only calls the native limiter when the binding is present. Cloudflare configuration normally provisions it. If a binding is absent, the request proceeds without enforcement; this fail-open fallback also applies to non-Cloudflare runtimes. Do not use it as a strict quota guarantee.
|
|
226
264
|
|
|
227
265
|
**Roadmap — Bun in-process shim.** An in-memory fixed-window shim (`src/lib/rate-limit-memory.ts`) that backs the same `c.env.RL_*.limit({ key })` call site with a process-memory token bucket is planned but **not yet emitted**. Until it lands, non-Cloudflare deployments that need enforcement should sit behind a Cloudflare WAF rule or an upstream rate limiter. A multi-instance Bun shim would additionally need sticky sessions (same user → same instance → same bucket), since a process-memory counter can't coordinate across processes.
|
|
228
266
|
|
|
@@ -232,7 +270,10 @@ The compiler errors on:
|
|
|
232
270
|
|
|
233
271
|
1. `period` other than `10` or `60`
|
|
234
272
|
2. Non-integer or non-positive `limit`
|
|
235
|
-
3. Unknown
|
|
273
|
+
3. Unknown operations or policy fields (e.g. `list` instead of `read`)
|
|
274
|
+
4. A `delta` that is not a positive safe integer
|
|
275
|
+
5. A malformed or overlong `bucket`
|
|
276
|
+
6. Conflicting `(limit, period)` declarations for the same shared bucket
|
|
236
277
|
|
|
237
278
|
## Disabling vs. tightening — when to use which
|
|
238
279
|
|
|
@@ -91,11 +91,19 @@ interface ReadConfig {
|
|
|
91
91
|
// `firewall` block is used (the common case).
|
|
92
92
|
firewall?: FirewallConfig;
|
|
93
93
|
|
|
94
|
-
//
|
|
95
|
-
// Hyperdrive
|
|
96
|
-
//
|
|
97
|
-
//
|
|
98
|
-
|
|
94
|
+
// Read caching — two independent engines:
|
|
95
|
+
// - "hyperdrive": Cloudflare Hyperdrive's query cache (Postgres over
|
|
96
|
+
// Hyperdrive only). Public, tenant-free data: requires
|
|
97
|
+
// `firewall: { exception: true }`, a roles-only access admitting PUBLIC,
|
|
98
|
+
// and the HYPERDRIVE_CACHED binding. See Neon → Cached public reads.
|
|
99
|
+
// - { engine: "workers", scope: "user", ttlSeconds }: user-scoped Workers
|
|
100
|
+
// Cache for authenticated D1 reads. See "Workers Cache" below.
|
|
101
|
+
cache?: "hyperdrive" | {
|
|
102
|
+
engine: "workers";
|
|
103
|
+
scope: "user"; // required; the only scope
|
|
104
|
+
ttlSeconds: number; // 1–300
|
|
105
|
+
consistency?: "committed";
|
|
106
|
+
};
|
|
99
107
|
|
|
100
108
|
// Pagination for the collection GET and every view (one setting per
|
|
101
109
|
// resource). `?limit=` above maxPageSize is clamped to it; OpenAPI
|
|
@@ -111,6 +119,16 @@ interface ReadConfig {
|
|
|
111
119
|
// Mount the generated read routes (GET /, GET /:id, GET /views/*).
|
|
112
120
|
// Default true. See "Tables only your actions read" below.
|
|
113
121
|
routes?: boolean;
|
|
122
|
+
|
|
123
|
+
// Full-text `?search=` with SQLite FTS5 (cloudflare-d1, including tenant
|
|
124
|
+
// SQLite objects). See "Full-text search" below.
|
|
125
|
+
search?: {
|
|
126
|
+
engine: "fts5";
|
|
127
|
+
fields: { [column: string]: { weight?: number } }; // weight: integer 1–100, default 1
|
|
128
|
+
tokenizer?: "unicode61";
|
|
129
|
+
match?: "all";
|
|
130
|
+
ranking?: "field-match";
|
|
131
|
+
};
|
|
114
132
|
}
|
|
115
133
|
|
|
116
134
|
interface ViewConfig {
|
|
@@ -121,6 +139,194 @@ interface ViewConfig {
|
|
|
121
139
|
}
|
|
122
140
|
```
|
|
123
141
|
|
|
142
|
+
## Workers Cache
|
|
143
|
+
|
|
144
|
+
`read.cache: { engine: "workers", scope: "user", ttlSeconds }` caches a
|
|
145
|
+
resource's `GET /`, `GET /:id` and `GET /views/:name` responses **per
|
|
146
|
+
caller** in [Workers Cache](https://developers.cloudflare.com/workers/cache/).
|
|
147
|
+
It is for authenticated reads on Cloudflare D1. There is no public,
|
|
148
|
+
tenant-wide or shared mode.
|
|
149
|
+
|
|
150
|
+
{/* doc-compile: skip — config + resource fragments; the full defineConfig wrapper is shown in /configure. */}
|
|
151
|
+
```typescript
|
|
152
|
+
// quickback.config.ts
|
|
153
|
+
database: defineDatabase("cloudflare-d1", {
|
|
154
|
+
readCache: { enabled: true },
|
|
155
|
+
}),
|
|
156
|
+
|
|
157
|
+
// features/docs/docs.ts
|
|
158
|
+
read: {
|
|
159
|
+
access: { roles: ["owner", "admin", "member"] },
|
|
160
|
+
cache: { engine: "workers", scope: "user", ttlSeconds: 60 },
|
|
161
|
+
},
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### How a request is served
|
|
165
|
+
|
|
166
|
+
The Worker gets two entrypoints. The default entrypoint is the
|
|
167
|
+
**gateway**, and Workers Cache is off for it. `QuickbackReadCache` is a
|
|
168
|
+
private **inner** entrypoint with Workers Cache on. No route reaches it.
|
|
169
|
+
|
|
170
|
+
1. The gateway runs the normal middleware on **every** request, hits
|
|
171
|
+
included. The session is re-read from Better Auth, the member row is
|
|
172
|
+
re-read from `AUTH_DB`, and the feature rate limiter counts the request.
|
|
173
|
+
2. The gateway reads the features database's **data epoch**: one row
|
|
174
|
+
holding a random token, read on the primary. Every write the Worker
|
|
175
|
+
commits to the features database replaces the token with a new one (see
|
|
176
|
+
[The data epoch](#the-data-epoch)).
|
|
177
|
+
3. The gateway signs an HMAC over the caller's authority snapshot, the
|
|
178
|
+
data epoch, the route, a policy fingerprint, the host
|
|
179
|
+
and the path + query. It then fetches the inner entrypoint with these
|
|
180
|
+
values as `ctx.props`. Workers Cache keys entries on path + query,
|
|
181
|
+
entrypoint, `ctx.props` and Worker version, so an entry is only reachable
|
|
182
|
+
with the same signed values. Cookies, `Authorization`, conditional and
|
|
183
|
+
`Range` headers are never forwarded.
|
|
184
|
+
4. On a **miss**, the inner entrypoint verifies the signature and restores
|
|
185
|
+
the snapshot into `ctx`. It runs the **same** route handler on the
|
|
186
|
+
primary, so firewall, access and masking all run again. It then re-reads
|
|
187
|
+
the epoch. The response is stored only if nothing committed in between.
|
|
188
|
+
5. The gateway renders the body through the normal ETag path. `ETag`, `304`
|
|
189
|
+
and `Cache-Control: private, no-cache` are byte-for-byte what an uncached
|
|
190
|
+
read returns. The platform cache never sees a `Set-Cookie`, request ID or
|
|
191
|
+
D1 bookmark.
|
|
192
|
+
|
|
193
|
+
Masking runs before caching. The cached body is the masked representation,
|
|
194
|
+
and the key contains every role, org and identity input masking reads. The
|
|
195
|
+
alternative was caching pre-mask rows and re-masking on every hit. That
|
|
196
|
+
would store unmasked data in a shared platform cache and depend on the hit
|
|
197
|
+
path re-masking correctly, so it was rejected.
|
|
198
|
+
|
|
199
|
+
### What is in the key
|
|
200
|
+
|
|
201
|
+
| Dimension | Source |
|
|
202
|
+
|---|---|
|
|
203
|
+
| User, session | `ctx.userId`, `ctx.sessionId`. Two sessions of one user never share an entry. |
|
|
204
|
+
| Organization, roles | `ctx.activeOrgId`, `roles`, `orgRole`, `userRole`, `tierRoles`, `activeTeamId` |
|
|
205
|
+
| Data version | The data epoch token (`_quickback_data_epoch`) |
|
|
206
|
+
| Policy | Compile-time fingerprint of the resource's firewall, read access, views and masking, plus the Worker version |
|
|
207
|
+
| Request | Host, path and query string, in the order sent |
|
|
208
|
+
| Environment | Each named environment and Preview is its own Worker version. The optional `QB_READ_CACHE_NAMESPACE` var is in the key too. |
|
|
209
|
+
|
|
210
|
+
### What is never cached
|
|
211
|
+
|
|
212
|
+
These take the ordinary uncached path:
|
|
213
|
+
|
|
214
|
+
- every lane except a Better Auth **session**: JWT bearer (its claims are not re-read per request), API keys, scope tokens, delegated principals, Cloudflare Access, share links and anonymous requests;
|
|
215
|
+
- requests carrying the read-replication bookmark header, `Cache-Control: no-cache` / `no-store`, or `Range`;
|
|
216
|
+
- any non-`200` answer. The gateway then re-runs the ordinary handler, so error bodies and status codes are unchanged;
|
|
217
|
+
- bodies over 1 MiB;
|
|
218
|
+
- requests where the D1 primary is unreachable, and every read before the first write mints an epoch token. Missing cache metadata falls back to an uncached authorized read. It never produces a stale hit.
|
|
219
|
+
|
|
220
|
+
The compiler refuses `engine: "workers"` on:
|
|
221
|
+
|
|
222
|
+
- any provider except `cloudflare-d1`;
|
|
223
|
+
- auth other than Better Auth;
|
|
224
|
+
- function-form access, and `relationship` / `permission` / `principal` arms;
|
|
225
|
+
- FK display columns and `include` (not supported yet);
|
|
226
|
+
- encrypted or derived-key columns;
|
|
227
|
+
- tenant Durable Object features (not supported yet).
|
|
228
|
+
|
|
229
|
+
`readCache: { enabled: true }` itself is refused next to any class the runtime
|
|
230
|
+
builds with the raw `env`: user Durable Objects (`bindings.durableObjects`),
|
|
231
|
+
service entrypoints (`bindings.serviceEntrypoints`) and the tenant Durable
|
|
232
|
+
Object. A D1 write there would commit without moving the data epoch.
|
|
233
|
+
|
|
234
|
+
### The data epoch
|
|
235
|
+
|
|
236
|
+
`_quickback_data_epoch` is a compiler-owned table in the features database
|
|
237
|
+
with one row: a random 128-bit token stored as hex text. The generated D1 write wrapper (the one
|
|
238
|
+
[D1 recovery](/platform/database/recovery) uses for admission) is installed
|
|
239
|
+
on the features binding whenever `readCache` is on. Every write it sends goes
|
|
240
|
+
out as a native D1 batch, and the wrapper appends one statement to that batch:
|
|
241
|
+
|
|
242
|
+
```sql
|
|
243
|
+
INSERT INTO _quickback_data_epoch (id, epoch) VALUES (1, lower(hex(randomblob(16))))
|
|
244
|
+
ON CONFLICT(id) DO UPDATE SET epoch = excluded.epoch
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
The bump commits or rolls back with the write. Each token is minted once, so
|
|
248
|
+
it names exactly one state of the database: the state its write produced. A reader therefore never sees
|
|
249
|
+
new data under an old epoch. The gateway reads the epoch before it builds the
|
|
250
|
+
key, and the inner entrypoint reads it again after a fill. A write that
|
|
251
|
+
commits in between changes the second read, so the response is served but not
|
|
252
|
+
stored.
|
|
253
|
+
|
|
254
|
+
Covered, because they all reach the database through the wrapper:
|
|
255
|
+
|
|
256
|
+
- generated CRUD, batch and view routes, and actions, including `unsafe` ones;
|
|
257
|
+
- raw SQL through `prepare()` or `batch()`, including on a `withSession()` session;
|
|
258
|
+
- queue, cron and inbound-email handlers, durable-effect dispatch and data migrations;
|
|
259
|
+
- statements prepared on another handle and passed to `batch()`. They cannot be classified, so they count as writes.
|
|
260
|
+
|
|
261
|
+
Anything that is not provably read-only counts as a write, so the cache may
|
|
262
|
+
miss more than it has to, but never less. `exec()` is unavailable on the
|
|
263
|
+
wrapped binding because it cannot carry the bump.
|
|
264
|
+
|
|
265
|
+
Not covered: writers outside this Worker. That means `wrangler d1 execute`,
|
|
266
|
+
the dashboard console, another Worker bound to the same database, and schema
|
|
267
|
+
migrations. Their writes stay invisible to cached reads until the TTL
|
|
268
|
+
expires, unless the same command also mints a new token:
|
|
269
|
+
|
|
270
|
+
```sql
|
|
271
|
+
UPDATE _quickback_data_epoch SET epoch = lower(hex(randomblob(16))) WHERE id = 1;
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Changing `QB_READ_CACHE_NAMESPACE` does the same for every entry. A deploy
|
|
275
|
+
changes the Worker version, which also starts a fresh cache. Never write a
|
|
276
|
+
token you made up or copied from elsewhere: only a freshly minted token is
|
|
277
|
+
guaranteed never to have addressed other data.
|
|
278
|
+
|
|
279
|
+
**Cost.** Each write batch on the features database carries one extra
|
|
280
|
+
single-row upsert. That is one more row written per batch, not per row, and
|
|
281
|
+
no extra round trip. D1 runs one writer per database, so writes are already
|
|
282
|
+
serialized. The shared row adds no lock beyond that, but every write does
|
|
283
|
+
update it. Reads cost one primary `SELECT` of the row per request, plus
|
|
284
|
+
one more after a fill. Writes without the table fail: apply the migration
|
|
285
|
+
that creates `_quickback_data_epoch` before deploying the Worker that bumps
|
|
286
|
+
it.
|
|
287
|
+
|
|
288
|
+
**Restores.** A D1 Time Travel restore rewinds the token with the data, back
|
|
289
|
+
to the token the restored state was written under. Entries under that token
|
|
290
|
+
were filled from exactly that state, so a hit after the restore is correct.
|
|
291
|
+
Every write after the restore mints a token that has never existed, so an
|
|
292
|
+
entry filled before the restore from a now-discarded later state can never be
|
|
293
|
+
hit. This holds however you restore, with or without
|
|
294
|
+
[recovery](/platform/database/recovery); the read path never consults the
|
|
295
|
+
control object.
|
|
296
|
+
|
|
297
|
+
**Upgrading from the counter epoch.** Earlier versions kept an integer
|
|
298
|
+
counter, which a restore could rewind and later writes then reuse. The
|
|
299
|
+
compiler now emits the column as `TEXT`, so the next migration rebuilds the
|
|
300
|
+
table and carries the old number over as text. A value that is not a minted
|
|
301
|
+
token is never used as a key: reads stay uncached until the first write after
|
|
302
|
+
the migration mints one.
|
|
303
|
+
|
|
304
|
+
### Operations
|
|
305
|
+
|
|
306
|
+
| Control | Effect |
|
|
307
|
+
|---|---|
|
|
308
|
+
| `QB_READ_CACHE = "off"` (var) | Kill switch: no lookups, every read uncached. |
|
|
309
|
+
| `QB_READ_CACHE_NAMESPACE` (var) | Change it to orphan every existing entry before re-enabling. |
|
|
310
|
+
|
|
311
|
+
A hit still costs the gateway's authentication and one primary read of the
|
|
312
|
+
epoch row. It skips the resource query and render. A miss adds the inner
|
|
313
|
+
fetch and a second epoch read. Whether that saves anything depends on how
|
|
314
|
+
expensive the read is, so measure.
|
|
315
|
+
|
|
316
|
+
`readCache` still emits the operational-control Durable Object
|
|
317
|
+
(`QuickbackControl`, binding `QB_CONTROL`) even without recovery or durable
|
|
318
|
+
effects. Earlier versions read their restore generation from it, so
|
|
319
|
+
deployments already carry the class in their Durable Object migrations, and
|
|
320
|
+
removing it would need a `deleted_classes` migration. Nothing on the read path
|
|
321
|
+
calls it.
|
|
322
|
+
|
|
323
|
+
> Native Workers Cache does not run under local Vitest or Miniflare. The
|
|
324
|
+
> generated logic is tested against a controlled cache adapter. Check hits
|
|
325
|
+
> (`Cf-Cache-Status: HIT`) on a Preview or a deployed test Worker before you
|
|
326
|
+
> rely on them. If the platform never caches, every read still returns the
|
|
327
|
+
> correct authorized answer, just uncached.
|
|
328
|
+
|
|
329
|
+
|
|
124
330
|
## Tables only your actions read (`routes: false`)
|
|
125
331
|
|
|
126
332
|
`read: { routes: false }` keeps `read.access` declared but mounts **no**
|
|
@@ -303,6 +509,9 @@ export default defineTable(notes, {
|
|
|
303
509
|
});
|
|
304
510
|
```
|
|
305
511
|
|
|
512
|
+
An owned child can also be a soft-delete cascade target. The generated reader and
|
|
513
|
+
cascade share their schema import; no duplicate table definition or alias is needed.
|
|
514
|
+
|
|
306
515
|
Both kinds land in the top-level `included` map keyed by the include token,
|
|
307
516
|
then row PK, and both inherit the **target's full security surface** — its
|
|
308
517
|
`read.access` (pre-record-evaluable only, compile-enforced), its firewall
|
|
@@ -393,6 +602,124 @@ GET /jobs?status.in=open,draft # IN clause
|
|
|
393
602
|
| Pattern match | `?field.like=value` | `WHERE field LIKE '%value%'` |
|
|
394
603
|
| In list | `?field.in=a,b,c` | `WHERE field IN ('a','b','c')` |
|
|
395
604
|
|
|
605
|
+
### JSON projection queries
|
|
606
|
+
|
|
607
|
+
[Declare a JSON projection](/define/schema#indexed-json-projections-sqlite) to filter or sort a stored scalar without exposing a new row field:
|
|
608
|
+
|
|
609
|
+
```text
|
|
610
|
+
GET /companies?industry=software
|
|
611
|
+
GET /companies?industry.in=software,finance&score.gte=80
|
|
612
|
+
GET /companies?sort=-score,id&limit=25&offset=25
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
Only declared operators are accepted: `eq` supports equality and `.ne`; `in` adds comma-separated `.in`; `range` adds numeric inequalities. Strings remain strings. Numeric values must be complete, finite JSON numbers (no empty values, trailing text, hexadecimal or `Infinity`); booleans must be exactly `true` or `false`. Invalid operators, values or view capabilities return 400. Missing/null/wrong-type stored values are SQL NULL and do not match comparisons. There is no null operator or escaping of commas inside `.in` values; use equality for strings containing commas.
|
|
616
|
+
|
|
617
|
+
Views may list aliases in `query.filterable` or `query.sortable`, but cannot grant a capability the projection did not declare. A sortable alias may appear in `query.defaultSort`. Any sort containing an alias, including a default or mixed sort, uses **offset pagination**: `cursor`, `starting_after` and `ending_before` return 400, and both response cursors are null, even on an empty result. Duplicate and NULL sort values use the existing physical `id` tie-breaker. Filtering by an alias while sorting only physical columns retains ordinary cursor pagination.
|
|
618
|
+
|
|
619
|
+
Aliases are query-only. They cannot appear in `fields`, view output fields, create/update bodies, `searchable`, aggregates, group-by or rollup definitions. Responses still return the JSON source column under its normal field policy. Aggregate-only views can filter by an alias before computing aggregates of physical columns. Firewall, record access and soft-delete conditions constrain the rows, totals and aggregates together; a projection never grants access to another row or tenant.
|
|
620
|
+
|
|
621
|
+
OpenAPI and MCP advertise the permitted alias parameters per view. MCP forwards these arguments through the same authenticated HTTP routes. The schema registry carries separate `queryProjections` metadata; aliases are not editable CMS columns and do not imply a new CMS control.
|
|
622
|
+
|
|
623
|
+
## Full-text search (`read.search`)
|
|
624
|
+
|
|
625
|
+
Without a declaration, `?search=` is an escaped substring `LIKE` over the
|
|
626
|
+
view's searchable columns. Declare `read.search` to switch the resource to
|
|
627
|
+
**SQLite FTS5 token matching** — a deliberate behavior change, never applied
|
|
628
|
+
silently to an existing resource:
|
|
629
|
+
|
|
630
|
+
```typescript title="quickback/features/articles/articles.ts"
|
|
631
|
+
import { feature, q } from "@quickback/compiler";
|
|
632
|
+
|
|
633
|
+
export default feature("articles", {
|
|
634
|
+
columns: {
|
|
635
|
+
id: q.id(),
|
|
636
|
+
organizationId: q.scope("organization"),
|
|
637
|
+
title: q.text().required(),
|
|
638
|
+
body: q.text().optional(),
|
|
639
|
+
status: q.enum(["draft", "published"]).optional(),
|
|
640
|
+
...q.audit(),
|
|
641
|
+
...q.softDelete(),
|
|
642
|
+
},
|
|
643
|
+
guards: { createable: ["title", "body", "status"], updatable: ["title", "body", "status"] },
|
|
644
|
+
read: {
|
|
645
|
+
access: { roles: ["member"] },
|
|
646
|
+
search: {
|
|
647
|
+
engine: "fts5",
|
|
648
|
+
fields: { title: { weight: 3 }, body: { weight: 1 }, status: {} },
|
|
649
|
+
},
|
|
650
|
+
defaultView: "all",
|
|
651
|
+
views: {
|
|
652
|
+
all: { fields: ["id", "title", "body", "status"] },
|
|
653
|
+
// A view may NARROW the indexed fields; it can never widen them.
|
|
654
|
+
headlines: { fields: ["id", "title"], query: { searchable: ["title"] } },
|
|
655
|
+
},
|
|
656
|
+
},
|
|
657
|
+
create: { access: { roles: ["member"] } },
|
|
658
|
+
update: { access: { roles: ["member"] } },
|
|
659
|
+
delete: { access: { roles: ["member"] }, mode: "soft" },
|
|
660
|
+
});
|
|
661
|
+
```
|
|
662
|
+
|
|
663
|
+
```text
|
|
664
|
+
GET /articles?search=quarterly budget # every term must match
|
|
665
|
+
GET /articles/views/headlines?search=budget # title only
|
|
666
|
+
GET /articles?search=budget&sort=-createdAt # explicit physical sort, cursors allowed
|
|
667
|
+
```
|
|
668
|
+
|
|
669
|
+
**Matching.** The input is split on whitespace into at most 16 literal terms
|
|
670
|
+
(256 bytes). Each term is quoted and bound as data: clients cannot send FTS
|
|
671
|
+
operators, column filters, prefixes or SQL. Every term must occur in at least
|
|
672
|
+
one of the view's eligible fields; terms may match different fields. The
|
|
673
|
+
`unicode61` tokenizer folds case and Latin diacritics (`cafe` matches
|
|
674
|
+
`Café`) and matches whole tokens, not substrings (`caf` does not match
|
|
675
|
+
`Café`); a term with punctuation inside (`budget-2026`) is a phrase of its
|
|
676
|
+
tokens. Queries are NFC-normalized. This is not a language analyzer — there is
|
|
677
|
+
no stemming or synonym support. Empty or whitespace-only input means no
|
|
678
|
+
search; input with no letter or digit is a 400.
|
|
679
|
+
|
|
680
|
+
**Ranking.** Without `?sort=`, results are ordered by **field-match
|
|
681
|
+
relevance**: the sum of the weights of the caller's eligible fields that
|
|
682
|
+
contain at least one term, then `id`. It looks only at the matching row
|
|
683
|
+
itself — no corpus statistics (not BM25) — so rows of other tenants, other
|
|
684
|
+
users or soft-deleted rows can never change your order. Relevance order uses
|
|
685
|
+
**offset pagination**: `cursor`, `starting_after` and `ending_before` return
|
|
686
|
+
400 and both response cursors are `null`. An explicit `?sort=` keeps its
|
|
687
|
+
normal meaning, including keyset cursors. Responses carry no scores or
|
|
688
|
+
snippets.
|
|
689
|
+
|
|
690
|
+
**Authorization.** The match is a predicate on the base table combined with
|
|
691
|
+
the firewall, access (including record arms), soft-delete and filter
|
|
692
|
+
predicates **before** pagination, so rows, `?total=true` and a view's
|
|
693
|
+
aggregations all describe the same authorized set. Aggregate-only views ignore
|
|
694
|
+
`?search=`, as before.
|
|
695
|
+
|
|
696
|
+
**Fields.** Only plain `text`, `url` and `enum` columns of a q-DSL table with
|
|
697
|
+
an `id` primary key. Masked (declared or auto-detected), encrypted, sealed,
|
|
698
|
+
secret, vault/storage-reference, JSON and array columns are compile errors —
|
|
699
|
+
even when some role can reveal the value — because matching runs for every
|
|
700
|
+
caller. Adding such a policy to an indexed field later fails the next compile.
|
|
701
|
+
`snippet`, `highlight`, `rank`/score output and other tokenizers are rejected.
|
|
702
|
+
Other database providers fail compilation; use [custom SQL](/define/escape-hatches)
|
|
703
|
+
for provider-native search there.
|
|
704
|
+
|
|
705
|
+
**Index lifecycle.** The index is derived state: an FTS5 external-content
|
|
706
|
+
table plus `AFTER INSERT / UPDATE OF <fields> / DELETE` triggers, so every
|
|
707
|
+
write — generated CRUD, batch, actions and raw SQL — maintains it in the same
|
|
708
|
+
transaction. Each declaration change appends one
|
|
709
|
+
`NNNN_quickback_search_<hash>.sql` migration that drops the previous index
|
|
710
|
+
generation, recreates it, rebuilds it from the table and verifies it before
|
|
711
|
+
creating the triggers; unchanged declarations append nothing, and removing
|
|
712
|
+
`read.search` appends a migration that drops only the owned index objects.
|
|
713
|
+
Applied migrations are never edited. See
|
|
714
|
+
[D1 → Full-text search](/platform/database/d1#full-text-search-readsearch) for
|
|
715
|
+
rebuilds, recovery and limits. Until this build's index migration is applied,
|
|
716
|
+
searches return **503 `SEARCH_INDEX_UNAVAILABLE`** — never a silent `LIKE`
|
|
717
|
+
fallback.
|
|
718
|
+
|
|
719
|
+
OpenAPI advertises the engine, eligible fields, weights and the relevance
|
|
720
|
+
pagination contract per route (`x-search`); MCP list tools inherit the same
|
|
721
|
+
route contract.
|
|
722
|
+
|
|
396
723
|
## Sorting & Pagination
|
|
397
724
|
|
|
398
725
|
```
|
|
@@ -111,6 +111,16 @@ export default defineConfig({
|
|
|
111
111
|
|
|
112
112
|
Resource definitions reference declared roles by name in `roles: [...]` arrays exactly like BA roles or pseudo-roles. The compiler rewrites the access tree at build time so the runtime route does an inline relationship lookup against the declared table.
|
|
113
113
|
|
|
114
|
+
> **The consuming row must carry the same resource column**
|
|
115
|
+
>
|
|
116
|
+
> `resource: { column: "issueId" }` compares the relationship's `issueId` to
|
|
117
|
+
> `record.issueId`, not `record.id`. It does not infer an FK-to-primary-key mapping.
|
|
118
|
+
> For issues keyed by `id` and assignment rows keyed by `issueId`, use the
|
|
119
|
+
> [scoped update action example](/define/issue-tracker-example) to preserve both
|
|
120
|
+
> reporter and assignee editing. Test the assignee branch over HTTP; a valid
|
|
121
|
+
> compile alone does not prove this join is mapped correctly.
|
|
122
|
+
|
|
123
|
+
|
|
114
124
|
#### Supported relationship-role surfaces
|
|
115
125
|
|
|
116
126
|
| Surface | Status | Notes |
|