@quickback-dev/cli 0.70.27 → 0.70.38
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/codex/AGENTS.md +290 -0
- package/dist/commands/build.d.ts +12 -0
- package/dist/commands/build.d.ts.map +1 -1
- package/dist/commands/build.js +69 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/build.test.d.ts.map +1 -0
- package/dist/commands/codex.d.ts +16 -0
- package/dist/commands/codex.d.ts.map +1 -0
- package/dist/commands/codex.js +159 -0
- package/dist/commands/codex.js.map +1 -0
- package/dist/commands/compile.d.ts +62 -0
- package/dist/commands/compile.d.ts.map +1 -0
- package/dist/commands/compile.js +830 -0
- package/dist/commands/compile.js.map +1 -0
- package/dist/commands/compile.test.d.ts.map +1 -0
- package/dist/commands/deploy.d.ts +9 -0
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/deploy.js +20 -2
- package/dist/commands/deploy.js.map +1 -1
- package/dist/commands/init.d.ts +6 -0
- package/dist/commands/init.d.ts.map +1 -0
- package/dist/commands/init.js +405 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/migrate-data.d.ts +12 -0
- package/dist/commands/migrate-data.d.ts.map +1 -0
- package/dist/commands/migrate-data.js +134 -0
- package/dist/commands/migrate-data.js.map +1 -0
- package/dist/commands/migrate.d.ts.map +1 -1
- package/dist/commands/migrate.js +11 -0
- package/dist/commands/migrate.js.map +1 -1
- package/dist/commands/migrate.test.d.ts.map +1 -0
- package/dist/commands/migrations.test.d.ts.map +1 -0
- package/dist/commands/push.test.d.ts.map +1 -0
- package/dist/commands/schema.test.d.ts.map +1 -0
- package/dist/commands/secrets.d.ts +27 -0
- package/dist/commands/secrets.d.ts.map +1 -0
- package/dist/commands/secrets.js +186 -0
- package/dist/commands/secrets.js.map +1 -0
- package/dist/docs/content.d.ts +7 -0
- package/dist/docs/content.d.ts.map +1 -0
- package/dist/docs/content.js +672 -0
- package/dist/docs/content.js.map +1 -0
- package/dist/docs/index.test.d.ts.map +1 -0
- package/dist/index.js +23 -3
- package/dist/index.js.map +1 -1
- package/dist/lib/access-manifest-diff.d.ts +87 -0
- package/dist/lib/access-manifest-diff.d.ts.map +1 -0
- package/dist/lib/access-manifest-diff.js +331 -0
- package/dist/lib/access-manifest-diff.js.map +1 -0
- package/dist/lib/action-harvest.test.d.ts.map +1 -0
- package/dist/lib/api-client.test.d.ts.map +1 -0
- package/dist/lib/artifact-routing.d.ts.map +1 -1
- package/dist/lib/artifact-routing.js +3 -0
- package/dist/lib/artifact-routing.js.map +1 -1
- package/dist/lib/artifact-routing.test.d.ts.map +1 -0
- package/dist/lib/auth.test.d.ts.map +1 -0
- package/dist/lib/compile-next-steps.test.d.ts.map +1 -0
- package/dist/lib/compiler-floor.test.d.ts.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/config-id-splice.test.d.ts.map +1 -0
- package/dist/lib/config-sync.test.d.ts.map +1 -0
- package/dist/lib/copy-public-assets.test.d.ts.map +1 -0
- package/dist/lib/copy-source-apps.test.d.ts.map +1 -0
- package/dist/lib/drizzle-meta-routing.test.d.ts.map +1 -0
- package/dist/lib/file-loader-typescript-fallback.test.d.ts.map +1 -0
- package/dist/lib/file-loader.d.ts +6 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +17 -0
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/file-loader.test.d.ts.map +1 -0
- package/dist/lib/file-writer.test.d.ts.map +1 -0
- package/dist/lib/helpers.d.ts +39 -0
- package/dist/lib/helpers.d.ts.map +1 -0
- package/dist/lib/helpers.js +299 -0
- package/dist/lib/helpers.js.map +1 -0
- package/dist/lib/migrations/drizzle-prompts.test.d.ts.map +1 -0
- package/dist/lib/migrations/drizzle.test.d.ts.map +1 -0
- package/dist/lib/migrations/executor.test.d.ts.map +1 -0
- package/dist/lib/migrations/inventory.test.d.ts.map +1 -0
- package/dist/lib/migrations/lock.test.d.ts.map +1 -0
- package/dist/lib/migrations/paths.test.d.ts.map +1 -0
- package/dist/lib/migrations/plan.test.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/index.test.d.ts.map +1 -0
- package/dist/lib/migrations/prompt-runner.test.d.ts.map +1 -0
- package/dist/lib/migrations/staging.test.d.ts.map +1 -0
- package/dist/lib/neon-canary.test.d.ts.map +1 -0
- package/dist/lib/neon-target.test.d.ts.map +1 -0
- package/dist/lib/neon.test.d.ts.map +1 -0
- package/dist/lib/ops-manifest.d.ts +76 -0
- package/dist/lib/ops-manifest.d.ts.map +1 -0
- package/dist/lib/ops-manifest.js +94 -0
- package/dist/lib/ops-manifest.js.map +1 -0
- package/dist/lib/prepare-output.test.d.ts.map +1 -0
- package/dist/lib/prepare-state-output.test.d.ts.map +1 -0
- package/dist/lib/release-and-pin.d.ts +34 -0
- package/dist/lib/release-and-pin.d.ts.map +1 -0
- package/dist/lib/release-and-pin.js +71 -0
- package/dist/lib/release-and-pin.js.map +1 -0
- package/dist/lib/schema-sync/index.test.d.ts.map +1 -0
- package/dist/lib/shell.d.ts +4 -1
- package/dist/lib/shell.d.ts.map +1 -1
- package/dist/lib/shell.js +8 -3
- package/dist/lib/shell.js.map +1 -1
- package/dist/lib/shell.test.d.ts.map +1 -0
- package/dist/lib/sweep-stale.d.ts +25 -0
- package/dist/lib/sweep-stale.d.ts.map +1 -0
- package/dist/lib/sweep-stale.js +179 -0
- package/dist/lib/sweep-stale.js.map +1 -0
- package/dist/lib/sweep-stale.test.d.ts.map +1 -0
- package/dist/lib/wrangler-resources.test.d.ts.map +1 -0
- package/dist/skill/docs/api/actions.md +2 -0
- package/dist/skill/docs/api/batch-operations.md +18 -4
- package/dist/skill/docs/api/crud.md +62 -0
- package/dist/skill/docs/api/errors.md +17 -2
- package/dist/skill/docs/configure/auth.md +49 -2
- package/dist/skill/docs/configure/bindings.md +15 -0
- package/dist/skill/docs/configure/domains.md +4 -0
- package/dist/skill/docs/configure/index.md +29 -11
- package/dist/skill/docs/configure/providers.md +1 -0
- package/dist/skill/docs/configure/tenancy.md +117 -0
- package/dist/skill/docs/define/access.md +19 -0
- package/dist/skill/docs/define/actions/access.md +76 -0
- package/dist/skill/docs/define/actions/defining.md +156 -1
- package/dist/skill/docs/define/actions/scoped-db.md +236 -9
- package/dist/skill/docs/define/areas.md +46 -0
- package/dist/skill/docs/define/authz-roles.md +10 -0
- package/dist/skill/docs/define/diagnostics.md +263 -0
- package/dist/skill/docs/define/encryption.md +34 -2
- package/dist/skill/docs/define/guards.md +13 -0
- package/dist/skill/docs/define/masking.md +77 -3
- package/dist/skill/docs/define/rate-limit.md +3 -3
- package/dist/skill/docs/define/schema.md +148 -7
- package/dist/skill/docs/define/scopes.md +79 -0
- package/dist/skill/docs/define/sealed-protocol.md +111 -9
- package/dist/skill/docs/define/transitions.md +39 -0
- package/dist/skill/docs/define/views.md +77 -3
- package/dist/skill/docs/platform/api-contract/index.md +4 -0
- package/dist/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/dist/skill/docs/platform/auth/using-auth.md +6 -0
- package/dist/skill/docs/platform/database/d1.md +47 -0
- package/dist/skill/docs/platform/database/data-migrations.md +109 -0
- package/dist/skill/docs/platform/database/index.md +1 -0
- package/dist/skill/docs/platform/database/read-replication.md +257 -0
- package/dist/skill/docs/platform/database/using-d1.md +2 -1
- package/dist/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/dist/skill/docs/platform/push/index.md +2 -0
- package/dist/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/dist/skill/docs/platform/storage/using-r2.md +135 -19
- package/dist/skill/docs/start/deploy.md +38 -0
- package/dist/skill/docs/tooling/cli.md +120 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/dist/skill/docs/tooling/output.md +70 -2
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +2 -0
- package/src/skill/docs/api/batch-operations.md +18 -4
- package/src/skill/docs/api/crud.md +62 -0
- package/src/skill/docs/api/errors.md +17 -2
- package/src/skill/docs/configure/auth.md +49 -2
- package/src/skill/docs/configure/bindings.md +15 -0
- package/src/skill/docs/configure/domains.md +4 -0
- package/src/skill/docs/configure/index.md +29 -11
- package/src/skill/docs/configure/providers.md +1 -0
- package/src/skill/docs/configure/tenancy.md +117 -0
- package/src/skill/docs/define/access.md +19 -0
- package/src/skill/docs/define/actions/access.md +76 -0
- package/src/skill/docs/define/actions/defining.md +156 -1
- package/src/skill/docs/define/actions/scoped-db.md +236 -9
- package/src/skill/docs/define/areas.md +46 -0
- package/src/skill/docs/define/authz-roles.md +10 -0
- package/src/skill/docs/define/diagnostics.md +263 -0
- package/src/skill/docs/define/encryption.md +34 -2
- package/src/skill/docs/define/guards.md +13 -0
- package/src/skill/docs/define/masking.md +77 -3
- package/src/skill/docs/define/rate-limit.md +3 -3
- package/src/skill/docs/define/schema.md +148 -7
- package/src/skill/docs/define/scopes.md +79 -0
- package/src/skill/docs/define/sealed-protocol.md +111 -9
- package/src/skill/docs/define/transitions.md +39 -0
- package/src/skill/docs/define/views.md +77 -3
- package/src/skill/docs/platform/api-contract/index.md +4 -0
- package/src/skill/docs/platform/auth/jwt-optimization.md +2 -0
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +4 -3
- package/src/skill/docs/platform/auth/using-auth.md +6 -0
- package/src/skill/docs/platform/database/d1.md +47 -0
- package/src/skill/docs/platform/database/data-migrations.md +109 -0
- package/src/skill/docs/platform/database/index.md +1 -0
- package/src/skill/docs/platform/database/read-replication.md +257 -0
- package/src/skill/docs/platform/database/using-d1.md +2 -1
- package/src/skill/docs/platform/payments/one-off-checkout.md +6 -1
- package/src/skill/docs/platform/push/index.md +2 -0
- package/src/skill/docs/platform/realtime/partyserver-rooms.md +95 -9
- package/src/skill/docs/platform/storage/using-r2.md +135 -19
- package/src/skill/docs/start/deploy.md +38 -0
- package/src/skill/docs/tooling/cli.md +120 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +13 -13
- package/src/skill/docs/tooling/output.md +70 -2
|
@@ -86,7 +86,7 @@ The compiler emits the `[[durable_objects.bindings]]` block, the `[[migrations]]
|
|
|
86
86
|
|
|
87
87
|
## Connect from the client
|
|
88
88
|
|
|
89
|
-
The `partysocket` package handles reconnection, buffering, and resilience. The `party` field is the kebab-cased binding name (`INTERVIEW_ROOM` → `interview-room`); the `room` field is
|
|
89
|
+
The `partysocket` package handles reconnection, buffering, and resilience. The `party` field is the kebab-cased binding name (`INTERVIEW_ROOM` → `interview-room`); the `room` field is an opaque ID that must be **URL-safe as stored** (letters, digits, `-`, `_`, `.`, `~`, and `:` for the multi-resource form). The gates refuse a percent-encoded room segment with `404` rather than decode it: PartyServer names the Durable Object from the raw segment, so decoding would authorise one id (`ab`) while opening another (`a%62`). Generate room ids (and `key` column values) from a URL-safe alphabet; cuid2, nanoid and UUIDs all qualify.
|
|
90
90
|
|
|
91
91
|
```ts
|
|
92
92
|
import PartySocket from 'partysocket';
|
|
@@ -109,7 +109,7 @@ socket.send(JSON.stringify({ type: 'note', body: 'asked about tenure' }));
|
|
|
109
109
|
|
|
110
110
|
## Authentication
|
|
111
111
|
|
|
112
|
-
The auto-mounted middleware is **secure by default** — anonymous WebSocket upgrades are rejected with `401 Unauthorized` before `partyserverMiddleware` sees the request. The four auth mechanisms the rest of the worker honors all unlock connections:
|
|
112
|
+
The auto-mounted middleware is **secure by default** — anonymous WebSocket upgrades are rejected with `401 Unauthorized` before `partyserverMiddleware` sees the request. A path with an empty segment (`/realtime//interview-room/abc`) is refused with `404` first, because PartyServer would route it to the same room while it matched none of the per-room gates below. The four auth mechanisms the rest of the worker honors all unlock connections:
|
|
113
113
|
|
|
114
114
|
- session cookie
|
|
115
115
|
- `Authorization: Bearer <jwt>`
|
|
@@ -118,7 +118,7 @@ The auto-mounted middleware is **secure by default** — anonymous WebSocket upg
|
|
|
118
118
|
|
|
119
119
|
(For the hand-written mount form below, you can also accept signed `?ws_ticket=` query params using the same issuer the Broadcaster exposes at `/broadcast/v1/ws-ticket`.)
|
|
120
120
|
|
|
121
|
-
The default gate only checks **whether** the caller is authenticated, not whether they're allowed in *this* room. For per-room authorization, the `access` field on the binding lets the compiler emit a path-scoped gate that runs your existing resource firewall
|
|
121
|
+
The default gate only checks **whether** the caller is authenticated, not whether they're allowed in *this* room. For per-room authorization, the `access` field on the binding lets the compiler emit a path-scoped gate that runs your existing resource firewall before the WebSocket upgrade — no hand-written code, same status semantics as `GET /api/v1/<resource>/:id`. Who may connect and who may write are declared on the binding itself with `roles` and `writeRoles` ([Room roles](#room-roles)); without them the gate falls back to the table's CRUD `read.access`.
|
|
122
122
|
|
|
123
123
|
### Per-room authorization via `access`
|
|
124
124
|
|
|
@@ -158,10 +158,15 @@ bindings: {
|
|
|
158
158
|
|
|
159
159
|
// Room keyed by a unique non-PK column. A Yjs page editor is
|
|
160
160
|
// addressed by `event_pages.yjsRoomId`, not the row id — `key` tells the
|
|
161
|
-
// gate which column the roomId matches.
|
|
161
|
+
// gate which column the roomId matches. `roles` / `writeRoles` declare
|
|
162
|
+
// the room's own audience, independent of the table's CRUD read access.
|
|
162
163
|
{
|
|
163
164
|
name: 'PageRoom', className: 'PageRoom', from: 'lib/PageRoom',
|
|
164
|
-
access: {
|
|
165
|
+
access: {
|
|
166
|
+
resource: { feature: 'event-pages', table: 'eventPages', key: 'yjsRoomId' },
|
|
167
|
+
roles: ['admin', 'member'], // who may connect
|
|
168
|
+
writeRoles: ['admin'], // who may edit; members connect read-only
|
|
169
|
+
},
|
|
165
170
|
},
|
|
166
171
|
|
|
167
172
|
// Identity-gated room — the roomId IS the caller's own id, with no backing
|
|
@@ -183,7 +188,7 @@ bindings: {
|
|
|
183
188
|
|
|
184
189
|
What the compiler emits:
|
|
185
190
|
|
|
186
|
-
- **`access: { resource: 'chats' }`** — `app.use('/realtime/chat/*', …)` that 401s anonymous, parses the URL segment as a row id, queries `chats` with the resource's `buildFirewallConditions(ctx)` and `eq(chats.id, rowId)`, and 403s when the row is invisible to the caller (out-of-org, soft-deleted, etc.). The DO's `onLoad` / `onConnect` then runs only for rows the
|
|
191
|
+
- **`access: { resource: 'chats' }`** — `app.use('/realtime/chat/*', …)` that 401s anonymous, runs the role gate (the binding's `roles`, or the table's `read.access` when `roles` is omitted) before any query, parses the URL segment as a row id, queries `chats` with the resource's `buildFirewallConditions(ctx)` and `eq(chats.id, rowId)`, and 403s when the row is invisible to the caller (out-of-org, soft-deleted, etc.). The DO's `onLoad` / `onConnect` then runs only for rows the caller's firewall admits.
|
|
187
192
|
- **`access: { resource: { feature, table } }`** — same gate, but the schema import + firewall alias are keyed off the pinned `table` instead of the feature name. Required when a feature owns more than one resourceful table; the access gate emit can't pick which table's firewall to query otherwise.
|
|
188
193
|
- **`access: { resource: { feature, table, key } }`** — same gate, but it matches the roomId against `table.<key>` instead of `table.id`. Use it when the room is addressed by a unique non-PK column — e.g. a Yjs editor keyed by `event_pages.yjsRoomId` (`ns.idFromName(row.yjsRoomId)`). `key` defaults to `'id'`, so existing pins are unchanged. The compiler validates the column exists at compile time. `key` also works inside each multi-resource branch.
|
|
189
194
|
- **Multi-resource form** — same gate but with a regex parser dispatching to per-kind firewall lookups. Unknown kinds 400 at the gate. Each `resources[kind].resource` accepts either form (string shorthand or `{ feature, table, key? }`).
|
|
@@ -191,7 +196,73 @@ What the compiler emits:
|
|
|
191
196
|
- **`access: 'public'`** — `app.use('/realtime/<kebab>/*', …)` that just passes through. Use for anonymous game lobbies / public collab pads where the room itself is the unit of access.
|
|
192
197
|
- **No `access` declared** — falls through to the catchall `/realtime/*` gate that just checks `ctx.authenticated`.
|
|
193
198
|
|
|
194
|
-
|
|
199
|
+
Every gate above compares the room segment exactly as it appears in the URL; a segment containing `%` is a `404` before any lookup (see [Connect from the client](#connect-from-the-client)).
|
|
200
|
+
|
|
201
|
+
Compile-time validation: every `resource` / `resources[].resource` value is checked against the project's feature names so typos surface as build errors, not as runtime 400s on the first WS upgrade. The string shorthand requires the feature to have exactly one resourceful table; multi-table features must use the long form `{ feature, table }` to pin a specific table. When `key` is set, the column is checked against the pinned table's schema. The resource-backed `access` objects are strict: an unknown key (a misspelled `writeRole`) is a build error, never an ignored narrowing.
|
|
202
|
+
|
|
203
|
+
### Room roles
|
|
204
|
+
|
|
205
|
+
A resource-backed room declares its own audience, independent of the backing table:
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
access: {
|
|
209
|
+
resource: { feature: 'event-pages', table: 'eventPages', key: 'yjsRoomId' },
|
|
210
|
+
roles: ['admin', 'member', 'scope:event:staff'], // connect (read)
|
|
211
|
+
writeRoles: ['admin', 'scope:event:staff'], // mutate
|
|
212
|
+
},
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
- **`roles`** gates the WebSocket upgrade. When declared it **replaces** the table's CRUD `read.access` in the gate, so you can narrow (or widen) the room without touching who may read the table. The table's firewall still runs: tenant isolation is not a role decision, and a caller still has to see the row.
|
|
216
|
+
- **`writeRoles`** gates mutations. Everyone `roles` admits may connect; callers outside `writeRoles` connect **read-only**. A writer has to be able to connect, so list writers in both: when both are role lists, a `writeRoles` entry that `roles` doesn't admit is a build error.
|
|
217
|
+
|
|
218
|
+
Both take the same role vocabulary as [resource access](/define/access): org roles, the `role+` hierarchy, pseudo-roles (`AUTHENTICATED`, `SESSION`, `SCOPED`, `SYSADMIN`), scoped roles (`scope:<kind>:<role>`, or their sugar), and declared [`authz.roles`](/define/authz-roles). They're lowered by the same expansion step as `read.access`, so `member+` means the same thing in a room and on a CRUD route. A role list is sugar for `{ roles: [...] }`; the object form adds `userRole` and `or` / `and`:
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
roles: { or: [{ roles: ['admin'] }, { userRole: ['appmanager'] }] },
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Refused at compile time, all fail-closed: an empty list, `PUBLIC` (use `access: 'public'`), `record:` predicates (put row conditions in the firewall), and anything that lowers to a `relationship:` or `fga:` arm. `roles` / `writeRoles` are accepted only on the resource-backed forms — `roomIdEquals` and `'public'` rooms have no row to firewall.
|
|
225
|
+
|
|
226
|
+
**How writes are enforced.** The gate evaluates `writeRoles` and forwards the verdict to the Durable Object as `x-quickback-room-access: write | read` (inbound copies are stripped; see [Who connected](#who-connected)). The compiler then re-exports the room class from `src/index.ts` through `withRoomWriteAccess` (`src/lib/realtime-room-access.ts`), which turns the verdict into a connection tag (tags survive hibernation) and refuses a reader's mutations:
|
|
227
|
+
|
|
228
|
+
| Room class | Reader connection |
|
|
229
|
+
|---|---|
|
|
230
|
+
| Yjs (`YServer` / `withYjs` from `y-partyserver` 2.x) | `isReadOnly(connection)` is `true`: document updates are refused, sync and awareness keep working. Custom messages never reach `onCustomMessage`. |
|
|
231
|
+
| Any other PartyServer room | Messages never reach `onMessage`. |
|
|
232
|
+
| Either kind, over HTTP (`onRequest`) | `GET`, `HEAD` and `OPTIONS` pass; any other method gets `403` unless the request carries the `write` verdict. |
|
|
233
|
+
|
|
234
|
+
To accept some reader messages (presence pings, cursors), define `onReadOnlyMessage(connection, message)` on the room; otherwise they're dropped. The HTTP counterpart is `onReadOnlyRequest(request)`, which receives a reader's unsafe request instead of the `403`. Anything other than an explicit `write` verdict is read-only, so a missing header fails closed. DO RPC methods called from an action are not affected; server code that calls the room with `stub.fetch()` directly (bypassing the Worker gate) sets `x-quickback-room-access: write` itself. The writer verdict is stored as a connection tag, so it uses one of PartyServer's tag slots: a write-gated room can return at most 8 tags of its own from `getConnectionTags` (10 per connection, including the connection id and the writer tag). A room that overrides `isReadOnly` keeps its own answer for writers; readers are always read-only. Use `isRoomWriter(connection)` from `src/lib/realtime-room-access.ts` if the room needs the verdict itself.
|
|
235
|
+
|
|
236
|
+
**The room id is masked for non-writers.** When a room with `writeRoles` is keyed by a non-PK column (`key`), that column is masked (`'redact'`) for everyone outside `writeRoles` on every read path masking covers: `GET /`, `GET /:id`, views, and auto-CRUD realtime emits. Through those generated read surfaces, a caller cannot learn a room id it cannot write to. Values your own code returns or sends are not covered: an action that returns the row, or a hand-written broadcast that includes the column, needs its own projection. The binding owns that column's audience, so a hand-written `masking.<key>` on the table is a build error, and `writeRoles` must then be a plain role list (masking audiences can't express `userRole` or `or` / `and`). A reader who is not a writer therefore needs the room id delivered some other way; rooms keyed by the row id (no `key`) mask nothing, because the id is the row's identity on every surface.
|
|
237
|
+
|
|
238
|
+
The backing table declares nothing about the room — no masking on `yjsRoomId`, and its `read.access` can stay as wide as CRUD needs:
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
// quickback/features/event-pages/event-pages.ts
|
|
242
|
+
import { feature, q } from "@quickback/compiler";
|
|
243
|
+
|
|
244
|
+
export default feature("eventPages", {
|
|
245
|
+
columns: {
|
|
246
|
+
id: q.id(),
|
|
247
|
+
title: q.text().required(),
|
|
248
|
+
yjsRoomId: q.text().required().unique(),
|
|
249
|
+
organizationId: q.scope("organization"),
|
|
250
|
+
...q.audit(),
|
|
251
|
+
...q.softDelete(),
|
|
252
|
+
},
|
|
253
|
+
read: { access: { roles: ["member", "admin"] } },
|
|
254
|
+
create: { access: { roles: ["admin"] } },
|
|
255
|
+
update: { access: { roles: ["admin"] } },
|
|
256
|
+
});
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
**Omitting them warns.** A resource-backed room with no `roles` (gated on the table's CRUD `read.access`) or no `writeRoles` (every admitted caller may write) compiles with a warning:
|
|
260
|
+
|
|
261
|
+
```
|
|
262
|
+
[quickback:authz] AUTHZ_ROOM_ACCESS_INHERITED: realtime room "PageRoom" declares no access.roles or access.writeRoles: …
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
See [Diagnostics](/define/diagnostics#authz-codes).
|
|
195
266
|
|
|
196
267
|
### Who connected
|
|
197
268
|
|
|
@@ -202,6 +273,7 @@ Every upgrade that passes the gate reaches the Durable Object with the caller's
|
|
|
202
273
|
| `x-quickback-user-id` | `ctx.userId` |
|
|
203
274
|
| `x-quickback-org-id` | `ctx.activeOrgId`, when the session has an active organization |
|
|
204
275
|
| `x-quickback-roles` | `ctx.roles` joined with `,` |
|
|
276
|
+
| `x-quickback-room-access` | `write` or `read` — only on rooms whose binding declares `writeRoles` ([Room roles](#room-roles)) |
|
|
205
277
|
|
|
206
278
|
Read them in `onConnect(connection, ctx)` or `onBeforeConnect(request)` from `ctx.request.headers` / `request.headers`. A display name or avatar is not stamped; look it up from the user id if the room needs one.
|
|
207
279
|
|
|
@@ -247,13 +319,27 @@ Add `y-partyserver` and `yjs` to `build.dependencies` alongside `partyserver`. T
|
|
|
247
319
|
|
|
248
320
|
```ts
|
|
249
321
|
import { YServer } from 'y-partyserver';
|
|
322
|
+
import * as Y from 'yjs';
|
|
250
323
|
|
|
251
324
|
export class DocumentRoom extends YServer {
|
|
252
|
-
|
|
253
|
-
|
|
325
|
+
static options = { hibernate: true };
|
|
326
|
+
|
|
327
|
+
// The Yjs doc lives on `this.document` (a Y.Doc). There is no `this.doc` —
|
|
328
|
+
// reading it returns undefined and throws on first use.
|
|
329
|
+
// Sync protocol is automatic; override `onLoad()` / `onSave()` to persist.
|
|
330
|
+
async onSave() {
|
|
331
|
+
await this.ctx.storage.put('doc', Y.encodeStateAsUpdate(this.document));
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
async onLoad() {
|
|
335
|
+
const saved = await this.ctx.storage.get<Uint8Array>('doc');
|
|
336
|
+
if (saved) Y.applyUpdate(this.document, saved);
|
|
337
|
+
}
|
|
254
338
|
}
|
|
255
339
|
```
|
|
256
340
|
|
|
341
|
+
With `writeRoles` on the binding, readers of a `YServer` room are read-only through `isReadOnly` with no code in the class ([Room roles](#room-roles)).
|
|
342
|
+
|
|
257
343
|
## Why this and not the Broadcaster
|
|
258
344
|
|
|
259
345
|
The Broadcaster is a one-DO-per-org fan-out. It can't shard by document, and it doesn't model client→client messages. PartyServer's per-room model is the right primitive for collab; the Broadcaster's per-org model is the right primitive for "tell everyone in this org that X happened." Run both.
|
|
@@ -81,41 +81,157 @@ https://files.yourdomain.com/public/org_abc/listings/3f2a9c…-hero.jpg
|
|
|
81
81
|
|
|
82
82
|
## Signed upload (large or confidential files)
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
|
|
84
|
+
Declare the key column as `q.storageKey(...)` and let `db.allocateUpload`
|
|
85
|
+
write it. Bytes go directly to R2 — the Worker only signs. The client never
|
|
86
|
+
names the key, so it can't point a row at another tenant's object.
|
|
87
|
+
|
|
88
|
+
```ts title="quickback/quickback.config.ts"
|
|
89
|
+
import { defineConfig, defineRuntime, defineDatabase, defineAuth, defineFileStorage } from "@quickback/compiler";
|
|
90
|
+
|
|
91
|
+
export default defineConfig({
|
|
92
|
+
name: "events-app",
|
|
93
|
+
template: "hono",
|
|
94
|
+
features: { organizations: true },
|
|
95
|
+
providers: {
|
|
96
|
+
runtime: defineRuntime("cloudflare"),
|
|
97
|
+
database: defineDatabase("cloudflare-d1"),
|
|
98
|
+
auth: defineAuth("better-auth", { plugins: { organization: true } }),
|
|
99
|
+
fileStorage: defineFileStorage("cloudflare-r2", { bucketName: "events-app-media" }),
|
|
100
|
+
},
|
|
101
|
+
bindings: {
|
|
102
|
+
r2Buckets: [{ binding: "MEDIA", bucketName: "events-app-media" }],
|
|
103
|
+
},
|
|
104
|
+
});
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
// quickback/features/media/media.ts
|
|
109
|
+
import { feature, q } from "@quickback/compiler";
|
|
110
|
+
|
|
111
|
+
export default feature("media", {
|
|
112
|
+
columns: {
|
|
113
|
+
id: q.id(),
|
|
114
|
+
eventId: q.text().required(),
|
|
115
|
+
title: q.text({ maxLength: 200 }).required(),
|
|
116
|
+
r2Key: q.storageKey({
|
|
117
|
+
bucket: "MEDIA",
|
|
118
|
+
key: "media/{organizationId}/{eventId}/{uuid}.{ext}",
|
|
119
|
+
mime: ["image/*", "application/pdf"],
|
|
120
|
+
maxBytes: 10_000_000,
|
|
121
|
+
}),
|
|
122
|
+
organizationId: q.scope("organization"),
|
|
123
|
+
...q.audit(),
|
|
124
|
+
},
|
|
125
|
+
read: { access: { roles: ["member"] } },
|
|
126
|
+
update: { access: { roles: ["member"] } },
|
|
127
|
+
delete: { access: { roles: ["admin"] }, mode: "hard" },
|
|
128
|
+
guards: { updatable: ["title"] },
|
|
129
|
+
});
|
|
86
130
|
|
|
87
|
-
|
|
131
|
+
// quickback/features/media/actions/upload.ts
|
|
88
132
|
import { z } from "zod";
|
|
89
133
|
import { defineAction, media } from "../.quickback/define-action";
|
|
90
134
|
|
|
91
135
|
export default defineAction({
|
|
92
|
-
description: "
|
|
93
|
-
path: "/media/
|
|
136
|
+
description: "Create a media row and sign its direct-to-R2 upload.",
|
|
137
|
+
path: "/media/upload",
|
|
94
138
|
method: "POST",
|
|
95
|
-
input: z.object({
|
|
139
|
+
input: z.object({ eventId: z.string(), title: z.string(), ext: z.string(), mime: z.string(), size: z.number().int() }),
|
|
96
140
|
access: { roles: ["member"] },
|
|
97
|
-
async execute({
|
|
98
|
-
const
|
|
99
|
-
|
|
100
|
-
contentType: input.contentType, // bound into the signature
|
|
101
|
-
contentLength: input.size, // required — bound into the signature, checked against maxFileSize
|
|
102
|
-
expiresIn: 600,
|
|
103
|
-
});
|
|
104
|
-
await db.insert(media).values({ key /* … */ });
|
|
105
|
-
return { uploadUrl: upload.url, key, headers: upload.headers };
|
|
141
|
+
async execute({ db, input }) {
|
|
142
|
+
const { row, putUrl, headers } = await db.allocateUpload(media, input);
|
|
143
|
+
return { id: row.id, putUrl, headers };
|
|
106
144
|
},
|
|
107
145
|
});
|
|
108
146
|
```
|
|
109
147
|
|
|
110
148
|
```bash
|
|
111
149
|
# 1. Ask your action for a signed URL (your auth/roles run here)
|
|
112
|
-
curl -X POST https://api.example.com/api/v1/media/
|
|
150
|
+
curl -X POST https://api.example.com/api/v1/media/upload \
|
|
113
151
|
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
|
|
114
|
-
-d '{ "
|
|
115
|
-
# → { "
|
|
152
|
+
-d '{ "eventId": "evt_1", "title": "Floor plan", "ext": "pdf", "mime": "application/pdf", "size": 48213 }'
|
|
153
|
+
# → { "id": "…", "putUrl": "https://<account>.r2.cloudflarestorage.com/events-app-media/media/org_abc/evt_1/<uuid>.pdf?…X-Amz-Signature=…", "headers": { "Content-Length": "48213", "Content-Type": "application/pdf" } }
|
|
116
154
|
|
|
117
155
|
# 2. Upload the bytes straight to R2 (replay the returned headers verbatim)
|
|
118
|
-
curl -X PUT "<
|
|
156
|
+
curl -X PUT "<putUrl>" -H "Content-Type: application/pdf" -H "Content-Length: 48213" --data-binary @plan.pdf
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
`db.allocateUpload(table, { ...rowValues, ext, mime, size }, { id?, expiresIn? })`:
|
|
160
|
+
|
|
161
|
+
1. Checks `mime` against the column's `mime` list (`415 STORAGE_UPLOAD_TYPE_REFUSED`),
|
|
162
|
+
`size` against `maxBytes` (`413 STORAGE_UPLOAD_TOO_LARGE`), and `ext`
|
|
163
|
+
(1–16 letters or digits, lower-cased).
|
|
164
|
+
2. Stamps the row exactly as the scoped `db.insert` would (`organizationId`
|
|
165
|
+
from the caller's active org), then renders the key from the template:
|
|
166
|
+
`{column}` from the row, a fresh `{uuid}`, `{ext}` from the call. A value
|
|
167
|
+
that cannot fill a whole path segment (`/`, `..`, anything outside
|
|
168
|
+
`A–Z a–z 0–9 _ -`) is a `400 STORAGE_KEY_SEGMENT_INVALID`.
|
|
169
|
+
3. Signs a PUT with `ctx.storage.signPutUrl` underneath. The `mime` and `size`
|
|
170
|
+
are bound into the signature as `Content-Type` / `Content-Length`. When the
|
|
171
|
+
project also declares `fileStorage.allowedTypes`, the type must be on that
|
|
172
|
+
list too.
|
|
173
|
+
4. Inserts the row (or, with `{ id }`, re-keys that row and deletes its
|
|
174
|
+
previous object) and returns `{ row, key, putUrl, headers, expiresAt }`.
|
|
175
|
+
|
|
176
|
+
If the table also has columns named `mime`, `size`, or `ext`, the upload's
|
|
177
|
+
values fill them.
|
|
178
|
+
|
|
179
|
+
**Reads.** `db.signDownload(table, id, { expiresIn?, downloadFilename? })` loads
|
|
180
|
+
the row through the firewall and signs a GET for its key. It refuses with
|
|
181
|
+
`403 STORAGE_KEY_OUTSIDE_PREFIX` when the stored key is not under the row's
|
|
182
|
+
own prefix.
|
|
183
|
+
|
|
184
|
+
**The prefix** is the template up to `{uuid}` with the row's values
|
|
185
|
+
substituted: `media/org_abc/evt_1/`. Every column placeholder fills a whole
|
|
186
|
+
`/`-separated segment, so "starts with the row's prefix" can't match a
|
|
187
|
+
neighbouring tenant. Reads, deletes, and [tenant purge](/configure/tenancy) all
|
|
188
|
+
refuse a key outside its row's prefix — a row whose key was tampered to name
|
|
189
|
+
another tenant's object never reaches that object.
|
|
190
|
+
|
|
191
|
+
**Deletes.** Deleting a row deletes its object:
|
|
192
|
+
|
|
193
|
+
- The generated hard `DELETE /:id` and `DELETE /batch` delete the objects of
|
|
194
|
+
the rows they erased.
|
|
195
|
+
- In an action, `db.delete(table)` on a storage-key table deletes the objects
|
|
196
|
+
of the rows it removed — from a full `.returning()`, or else by selecting
|
|
197
|
+
the matching rows through the same scoped `db` first. Inside
|
|
198
|
+
`db.transaction(...)` the objects are deleted after the outermost commit.
|
|
199
|
+
`db.batch([...])` refuses a storage-key delete, because a batch skips this
|
|
200
|
+
step.
|
|
201
|
+
- Soft deletes keep the object, because the row still exists.
|
|
202
|
+
- `unsafeDb`, schedules, and queue handlers bypass the scoped `db`. After a
|
|
203
|
+
hard delete there, call `deleteStorageObjects(env, table, deletedRows)` from
|
|
204
|
+
`src/lib/storage-keys`. It runs the same prefix check.
|
|
205
|
+
|
|
206
|
+
**What the compiler refuses** (each is a compile error):
|
|
207
|
+
|
|
208
|
+
| Code | Cause |
|
|
209
|
+
|---|---|
|
|
210
|
+
| `STORAGE_KEY_GUARDED` | The column is listed in `guards.createable` / `updatable` / `immutable` / `protected`. It is never client-writable, and no generated write body carries it. |
|
|
211
|
+
| `STORAGE_KEY_TENANT_PREFIX` | A tenant column of the table's firewall (`organizationId`, `ownerId`, a scope column) is not a placeholder before `{uuid}`. |
|
|
212
|
+
| `STORAGE_KEY_TEMPLATE` | No `{uuid}`, `{uuid}` not starting its own segment, a placeholder that isn't a column, a column after `{uuid}` (only `{ext}` may follow), `..`, or characters outside `A–Z a–z 0–9 . _ - /`. |
|
|
213
|
+
| `STORAGE_KEY_BUCKET` | `bucket` is not a `bindings.r2Buckets` binding (or the managed `fileStorage` binding), or an environment maps that binding to a different bucket name. |
|
|
214
|
+
| `STORAGE_KEY_PRESIGN` | No `providers.fileStorage: defineFileStorage("cloudflare-r2", …)` — the presigner signs the PUT. |
|
|
215
|
+
| `STORAGE_KEY_MIME` / `STORAGE_KEY_MAX_BYTES` | A malformed MIME pattern, or `maxBytes` that isn't a positive integer or exceeds `fileStorage.maxFileSize`. |
|
|
216
|
+
| `STORAGE_KEY_REQUIRED_WITH_CREATE` | The column is `.required()` and the table has a generic create route, which could never supply the key. |
|
|
217
|
+
| `STORAGE_KEY_CASCADE` | The table declares `onDelete: 'cascade'`. A cascaded delete removes rows without deleting their objects. |
|
|
218
|
+
| `STORAGE_KEY_MULTIPLE` / `STORAGE_KEY_NO_RESOURCE` | More than one storage key on a table, or a storage key on a table with no resource (no firewall to check the row against). |
|
|
219
|
+
|
|
220
|
+
In action code, writing the column directly (`db.insert(...).values({ r2Key })`,
|
|
221
|
+
`db.update(...).set({ r2Key })`, an upsert's `set`) throws
|
|
222
|
+
`STORAGE_KEY_NOT_WRITABLE`.
|
|
223
|
+
|
|
224
|
+
### Lower level: `storage.signPutUrl`
|
|
225
|
+
|
|
226
|
+
When the key does not belong to a row (a one-off export, an import staging
|
|
227
|
+
area), sign it yourself. You own the key's tenancy in that case.
|
|
228
|
+
|
|
229
|
+
```ts no-compile
|
|
230
|
+
const upload = await storage.signPutUrl(`exports/${ctx.activeOrgId}/${crypto.randomUUID()}.csv`, {
|
|
231
|
+
contentType: "text/csv",
|
|
232
|
+
contentLength: input.size, // required — bound into the signature
|
|
233
|
+
expiresIn: 600,
|
|
234
|
+
});
|
|
119
235
|
```
|
|
120
236
|
|
|
121
237
|
`storage.signPutUrl(key, { contentLength, contentType?, expiresIn?, bucket? })`
|
|
@@ -93,6 +93,44 @@ verify that the Hyperdrive origin matches the intended Neon branch, inspect
|
|
|
93
93
|
remote query caching, or apply Postgres migrations. Configure Hyperdrive with
|
|
94
94
|
query caching disabled and migrate the intended branch before deployment.
|
|
95
95
|
|
|
96
|
+
## Release stamps
|
|
97
|
+
|
|
98
|
+
{/* doc-compile: skip — excerpt of the top-level `release` key. */}
|
|
99
|
+
```ts title="quickback/quickback.config.ts"
|
|
100
|
+
release: { stampVars: true }, // optional: version: "1.4.0"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
With `stampVars` on, `quickback build` reads the release identity from your
|
|
104
|
+
repository: the version (`release.version`, else the project `package.json`
|
|
105
|
+
version), the git commit (`git rev-parse HEAD`, suffixed `-dirty` when the
|
|
106
|
+
tree has uncommitted changes), and the build time. The compiler cannot see your
|
|
107
|
+
repository, so the CLI supplies these values and the compiler validates them.
|
|
108
|
+
They are stamped as `QUICKBACK_RELEASE_VERSION`, `QUICKBACK_RELEASE_SHA` and
|
|
109
|
+
`QUICKBACK_RELEASE_AT` into `[vars]` and into every `[env.*.vars]` block.
|
|
110
|
+
Then:
|
|
111
|
+
|
|
112
|
+
- `GET /health` includes `release: { version, sha, at }`;
|
|
113
|
+
- handlers read the same values as `ctx.release`;
|
|
114
|
+
- `quickback deploy` passes `--tag <version> --message <version>@<sha>@<at>`
|
|
115
|
+
to `wrangler deploy`, so each Worker version in the Cloudflare dashboard
|
|
116
|
+
names the build it came from. It refuses to deploy if the built output
|
|
117
|
+
carries no stamp.
|
|
118
|
+
|
|
119
|
+
The three names are compiler-owned. Declaring a var with one of these names is
|
|
120
|
+
a compile error, whether or not stamping is on. The build fails if the project
|
|
121
|
+
is not a git checkout or has no version. `QUICKBACK_RELEASE_AT` changes on
|
|
122
|
+
every build, so `wrangler.toml` changes on every build too.
|
|
123
|
+
|
|
124
|
+
## Before you ship a target
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
quickback secrets check --env production # every required secret set, nothing undeclared
|
|
128
|
+
quickback migrate data --env production # dry-run pending data migrations
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
See [Check and Push Secrets](/tooling/cli#check-and-push-secrets) and
|
|
132
|
+
[Data Migrations](/platform/database/data-migrations).
|
|
133
|
+
|
|
96
134
|
## Conflicting ids
|
|
97
135
|
|
|
98
136
|
If `quickback.config.ts` already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, `quickback deploy` prints both and stops:
|
|
@@ -69,6 +69,9 @@ quickback build
|
|
|
69
69
|
> the name used throughout the docs.
|
|
70
70
|
|
|
71
71
|
|
|
72
|
+
Use `quickback build --accept-compiler` to accept a compiler other than the
|
|
73
|
+
one `compiler.pin` names (see [Pin the Compiler](#pin-the-compiler)).
|
|
74
|
+
|
|
72
75
|
Use `quickback build --verbose` when a remote build fails and you need the
|
|
73
76
|
underlying command, exit code, stderr/stdout tail, and suggested fixes.
|
|
74
77
|
|
|
@@ -96,6 +99,40 @@ explicit `wrangler ... --env <target>` deploy commands. It does not suggest a
|
|
|
96
99
|
bare deploy or the unnamed `.env.neon` / `.dev.vars` workflow for named
|
|
97
100
|
Hyperdrive environments.
|
|
98
101
|
|
|
102
|
+
#### Diff the access manifest
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
quickback build --diff quickback/reports/access-manifest.json
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`--diff <baseline.json>` compares a committed
|
|
109
|
+
[access manifest](/tooling/output#access-manifest) with the one this build
|
|
110
|
+
produces, prints a readable diff, and **exits 1 on any widening**:
|
|
111
|
+
|
|
112
|
+
- a new route or Durable Object room, or a new room kind;
|
|
113
|
+
- a weaker `auth` requirement (`session` → `public`) or room gate
|
|
114
|
+
(`resource-gated` → `authenticated`);
|
|
115
|
+
- an access tree that admits a principal the baseline did not — wider roles,
|
|
116
|
+
a new `or` arm, a dropped `and` arm, a removed gate, a new `fga` arm;
|
|
117
|
+
- wider room `roles` or effective `writeRoles`, including removal of a write
|
|
118
|
+
restriction or a change to inherited table access;
|
|
119
|
+
- a firewall arm removed from an AND, added to an `any:` group, or that lost
|
|
120
|
+
its `tenantBound` flag; a firewall that went from `scoped` to `exception`;
|
|
121
|
+
- an `unsafe` action that became `crossTenant`, `targetScope: 'all'`, or not
|
|
122
|
+
`adminOnly`;
|
|
123
|
+
- a new trusted origin, in the bundle or for any named environment.
|
|
124
|
+
|
|
125
|
+
Narrowings (removed routes, tighter roles, new AND arms) print but never fail.
|
|
126
|
+
When the comparison cannot prove a change narrows, it reports a widening.
|
|
127
|
+
Older room baselines without `connectAccess` and `writeAccess` cannot establish
|
|
128
|
+
what the room admitted: regenerate and review them before accepting a new baseline.
|
|
129
|
+
|
|
130
|
+
The baseline is read **before** the build, so `--diff` may point at the very
|
|
131
|
+
file the build overwrites — the usual setup is to commit
|
|
132
|
+
`quickback/reports/access-manifest.json` and run the line above in CI. After
|
|
133
|
+
reviewing an intended widening, commit the freshly written manifest as the new
|
|
134
|
+
baseline.
|
|
135
|
+
|
|
99
136
|
#### Generated `src/` is hermetic
|
|
100
137
|
|
|
101
138
|
Every file under `src/` carries a `Generated by quickback.dev` header and is owned by the compiler. Before each compile writes its output, the CLI:
|
|
@@ -261,6 +298,88 @@ cross-feature imports are left untouched, and unusual shapes (aliases,
|
|
|
261
298
|
multi-line imports, `import type`) are reported for manual attention instead
|
|
262
299
|
of guessed at.
|
|
263
300
|
|
|
301
|
+
### Pin the Compiler
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
quickback build --accept-compiler # accept a different compiler and rewrite the pin
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Set `compiler.pin` to the exact compiler build a project may be built by, as
|
|
308
|
+
`<version>@<gitSha>`:
|
|
309
|
+
|
|
310
|
+
{/* doc-compile: skip — excerpt of the `compiler` block; the rest of `defineConfig` is unchanged. */}
|
|
311
|
+
```ts title="quickback/quickback.config.ts"
|
|
312
|
+
compiler: {
|
|
313
|
+
pin: "0.70.36@3f9c2ab",
|
|
314
|
+
},
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
The compiler compares the pin against its own version and image sha
|
|
318
|
+
(the same values `/health` reports) **before generating anything**. Any other
|
|
319
|
+
build fails the compile and nothing is written. The sha matches by prefix, so a
|
|
320
|
+
7-character short sha is enough; the version must match exactly.
|
|
321
|
+
|
|
322
|
+
`--accept-compiler` lets the mismatch through and rewrites `compiler.pin` to
|
|
323
|
+
the compiler that answered, so the upgrade shows up as a one-line diff in
|
|
324
|
+
review. A compiler that cannot report its build sha (a local build without
|
|
325
|
+
build metadata) can neither satisfy a pin nor be accepted into one. A compiler
|
|
326
|
+
too old to know about pins is refused by the CLI.
|
|
327
|
+
|
|
328
|
+
### Check and Push Secrets
|
|
329
|
+
|
|
330
|
+
```bash
|
|
331
|
+
quickback secrets check --env staging
|
|
332
|
+
quickback secrets push --env staging # reads .env.staging
|
|
333
|
+
quickback secrets push --env staging --from ./secrets/staging.env
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Every build writes the declared secrets contract to
|
|
337
|
+
`reports/ops.manifest.json`: every secret the generated Worker reads
|
|
338
|
+
([`bindings.secrets`](/configure/bindings#secrets) plus those your providers
|
|
339
|
+
imply, such as `BETTER_AUTH_SECRET`, social-login credentials, R2 presign keys,
|
|
340
|
+
`ENCRYPTION_KEK`, Neon's `DATABASE_URL`), and which ones the boot guard refuses
|
|
341
|
+
to serve without.
|
|
342
|
+
|
|
343
|
+
- `check` runs `wrangler secret list` for the target and exits `1` when a
|
|
344
|
+
required secret is **missing** or a secret is set but **not declared**.
|
|
345
|
+
Code that reads an undeclared secret is code the compiler cannot see, so
|
|
346
|
+
that state counts as a failure.
|
|
347
|
+
- `push` sets secrets from a dotenv file with `wrangler secret put`. Values go
|
|
348
|
+
over stdin, not argv, and are never printed. If the file names an
|
|
349
|
+
undeclared secret or has an empty value, nothing is pushed. Without
|
|
350
|
+
`--from`, it reads `.env.<target>`, which the generated `.gitignore` ignores
|
|
351
|
+
(`.env.*`, keeping `*.example`).
|
|
352
|
+
|
|
353
|
+
Projects without named environments omit `--env` and pass `--from`. The build
|
|
354
|
+
also writes `.dev.vars.example` with every declared secret, for local
|
|
355
|
+
`wrangler dev`. Neon and PlanetScale keep their own template, and any declared
|
|
356
|
+
secret it lacks is appended to it.
|
|
357
|
+
|
|
358
|
+
### Run Data Migrations
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
quickback migrate data --env staging # dry run
|
|
362
|
+
quickback migrate data --env staging --apply
|
|
363
|
+
quickback migrate data --env production --apply --id 2026-10-21-backfill-slugs
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
Runs [data migrations](/platform/database/data-migrations) inside the
|
|
367
|
+
deployed Worker for that target. By default it dry-runs every pending (or
|
|
368
|
+
previously failed) migration in id order. `--apply` writes the changes and
|
|
369
|
+
records each id in that environment's ledger, so it never runs there again.
|
|
370
|
+
|
|
371
|
+
| Flag | |
|
|
372
|
+
| --- | --- |
|
|
373
|
+
| `--env <target>` | Named target (required when the project has named environments). |
|
|
374
|
+
| `--apply` | Write and record. Without it, nothing is written. |
|
|
375
|
+
| `--id <id>` | Run one migration instead of every pending one. |
|
|
376
|
+
| `--token <bearer>` | Bearer for a user whose `user.role` is in `dataMigrations.access.userRole`. Also read from `QUICKBACK_ADMIN_TOKEN`. |
|
|
377
|
+
| `--url <origin>` | Override the target's API origin (required for workers.dev-only targets). |
|
|
378
|
+
|
|
379
|
+
The route path and each target's API hostname come from
|
|
380
|
+
`reports/ops.manifest.json`. The command needs no database credentials. The
|
|
381
|
+
first failure stops the run and exits `1`.
|
|
382
|
+
|
|
264
383
|
### View Documentation
|
|
265
384
|
|
|
266
385
|
```bash
|
|
@@ -420,6 +539,7 @@ quickback build
|
|
|
420
539
|
|------|-------------|
|
|
421
540
|
| `-v, --version` | Show version number |
|
|
422
541
|
| `-h, --help` | Show help message |
|
|
542
|
+
| `build --diff <baseline>` | Fail the build on any access widening against a committed access manifest ([details](#diff-the-access-manifest)) |
|
|
423
543
|
|
|
424
544
|
## Environment Variables
|
|
425
545
|
|
|
@@ -149,23 +149,23 @@ and corrective import. If an older compiler or an already-generated project
|
|
|
149
149
|
reaches Wrangler first, apply the same fix above and rebuild Generated Backend
|
|
150
150
|
before Deploy.
|
|
151
151
|
|
|
152
|
-
The
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
152
|
+
The bundle check resolves dependencies from the compiler image first. A
|
|
153
|
+
package declared in [`build.dependencies`](/configure#custom-dependencies) that
|
|
154
|
+
the image lacks is installed from the npm registry for that compile, with
|
|
155
|
+
install scripts disabled. If that install fails, the compile stops before the
|
|
156
|
+
bundle check and names the packages:
|
|
156
157
|
|
|
157
158
|
```
|
|
158
|
-
|
|
159
|
-
|
|
159
|
+
build.dependencies could not be installed for the Worker bundle check:
|
|
160
|
+
fast-xml-parser. npm: …
|
|
160
161
|
```
|
|
161
162
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
packages
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
bundle check.
|
|
163
|
+
Check that the package name and range exist on npm. Only registry packages at
|
|
164
|
+
a semver range or dist-tag can be installed; `file:`, `git`, URL, `npm:` alias,
|
|
165
|
+
and `workspace:` specifiers fail with `build.dependencies must be npm registry
|
|
166
|
+
packages at a semver range or dist-tag`. Type-only `@types/*` packages never
|
|
167
|
+
block the check. Validation compiles (`complete=false`) still generate output
|
|
168
|
+
without running the Worker bundle check.
|
|
169
169
|
|
|
170
170
|
Store the Better Auth id as plain text:
|
|
171
171
|
|