@quickback-dev/cli 0.70.19 → 0.70.23

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/index.js CHANGED
@@ -10,7 +10,7 @@
10
10
  */
11
11
  import pc from "picocolors";
12
12
  // Version injected at build time by scripts/inject-version.ts
13
- const CLI_VERSION = "0.70.19";
13
+ const CLI_VERSION = "0.70.23";
14
14
  function getPackageVersion() {
15
15
  return CLI_VERSION;
16
16
  }
@@ -10,6 +10,37 @@ shaped byte-identically to the CRUD list endpoints they replace, a
10
10
  hand-re-derived per-slice masking. `defineBundle` generates all of it.
11
11
 
12
12
  ```typescript
13
+ // features/events/guests.ts
14
+ import { feature, q } from "@quickback/compiler";
15
+
16
+ export default feature("guests", {
17
+ columns: {
18
+ id: q.id(),
19
+ eventId: q.text().required().index(),
20
+ status: q.text().required(),
21
+ displayName: q.text().required(),
22
+ organizationId: q.scope("organization"),
23
+ ...q.audit(),
24
+ ...q.softDelete(),
25
+ },
26
+ read: { access: { roles: ["member", "admin"] } },
27
+ });
28
+
29
+ // features/events/supportTickets.ts
30
+ import { feature, q } from "@quickback/compiler";
31
+
32
+ export default feature("supportTickets", {
33
+ columns: {
34
+ id: q.id(),
35
+ eventId: q.text().required().index(),
36
+ subject: q.text().required(),
37
+ organizationId: q.scope("organization"),
38
+ ...q.audit(),
39
+ ...q.softDelete(),
40
+ },
41
+ read: { access: { roles: ["member", "admin"] } },
42
+ });
43
+
13
44
  // features/events/actions/getOverviewBundle.ts
14
45
  import { z } from "zod";
15
46
  import { defineBundle, list, custom } from "../.quickback/define-bundle";
@@ -17,17 +48,17 @@ import { defineBundle, list, custom } from "../.quickback/define-bundle";
17
48
  export default defineBundle({
18
49
  path: "/event/:eventId/overview-bundle",
19
50
  description: "Console Overview bootstrap",
20
- access: { roles: ["member", "admin"] },
21
- etag: true, // default true
22
- serverTiming: "overview", // optional
51
+ access: { roles: ["member", "admin"] }, // a subset of every list table's read.access
52
+ etag: true, // default true
53
+ serverTiming: "overview", // optional
23
54
  sections: {
24
55
  guests: list("guests", {
25
56
  columns: ["id", "status", "modifiedAt", "createdAt", "displayName"],
26
- where: { eventId: "$ctx.event.id" },
57
+ where: { eventId: "$path.eventId" },
27
58
  orderBy: [{ createdAt: "desc" }],
28
59
  limit: 500,
29
60
  }),
30
- tickets: list("supportTickets", { where: { eventId: "$ctx.event.id" }, orderBy: [{ modifiedAt: "desc" }], limit: 100 }),
61
+ tickets: list("supportTickets", { where: { eventId: "$path.eventId" }, orderBy: [{ modifiedAt: "desc" }], limit: 100 }),
31
62
  counts: custom(async ({ db, ctx }) => ({ open: 0 }), { output: z.object({ open: z.number().int() }) }),
32
63
  },
33
64
  });
@@ -67,7 +98,11 @@ export default defineBundle({
67
98
  - **`sections` filter**: omitted/empty = all. An un-wanted list section
68
99
  returns `{ data: [], hasMore: false, nextCursor: null }` (drop-in
69
100
  compatible with existing clients); un-wanted `custom` sections are absent.
70
- - **All sections run in one `Promise.all`.**
101
+ - **All sections run in one `Promise.all`.** On Postgres over Hyperdrive
102
+ each concurrent section leases its own connection, opened cold for the
103
+ request — a five-section bundle reports `cold=5 tx=5` in
104
+ [`Server-Timing`](/platform/database/neon#measuring-database-cost-server-timing).
105
+ Fewer sections is the lever when that dominates.
71
106
  - **ETag**: SHA-1 hex over `{ scopeSeed: <path params>, userId, payload }`.
72
107
  An `ifNoneMatch` match returns `{ success: true, etag, notModified: true }`
73
108
  with **no sections**. The digest is also exported as `sha1Hex` from
@@ -141,9 +176,15 @@ must pass the same complete-input-schema check as other actions.
141
176
  - Unknown section tables error, listing candidates.
142
177
  - `columns` / `where` / `orderBy` must name declared columns
143
178
  (compiler-injected audit columns like `createdAt`/`modifiedAt` are allowed).
179
+ - `list()` options are literals, or a same-file top-level
180
+ `const MANY = 2000` — anything else fails with "use a literal".
144
181
  - `where` values are literals or the strict substitution allowlist
145
- (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`) — always
146
- parameterized. Anything richer belongs in a `custom()` section.
182
+ (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`, and
183
+ `$path.<param>` for a param of the bundle's own `path`, e.g.
184
+ `path: "/projects/:projectId/overview"` with
185
+ `where: { projectId: "$path.projectId" }`) — always parameterized. A
186
+ `$path` param the path does not declare is a compile error. Anything
187
+ richer belongs in a `custom()` section.
147
188
  - Section names may not shadow the response envelope
148
189
  (`success`, `etag`, `notModified`, `sections`).
149
190
  - **A bundle must never widen read access**: its `access.roles` must be a
@@ -1329,6 +1329,21 @@ Statement text and parameters are never logged. Work the invocation defers to
1329
1329
  `waitUntil` (audit writes, after-commit effects) runs after the header is sent
1330
1330
  and is not counted.
1331
1331
 
1332
+ **`cold=5 tx=5` on every bundle request is the pool shape, not a leak.** The
1333
+ lease pool is per invocation and holds up to five connections. A
1334
+ [bundle](/define/bundles) runs its sections in one `Promise.all`, so five or
1335
+ more sections lease five connections at once; each is opened cold for this
1336
+ request and opens its own read lane (`BEGIN READ ONLY` + claims), which is
1337
+ the `tx` count. Summed `db` time exceeds wall time because those leases
1338
+ overlap. Connections cannot outlive the invocation on Workers, so there is
1339
+ nothing to warm across requests; the cost of a cold connection is the
1340
+ Hyperdrive handshake plus three round trips before its prepared statements
1341
+ are cached. Before changing a bundle's shape, run `SERVER_TIMING = "debug"`
1342
+ and read the `first` flags per lane: if most statements are `first`, the
1343
+ request is paying for connections, and fewer, larger sections (or a lower
1344
+ section count) is the lever; if few are, the cost is the statements
1345
+ themselves.
1346
+
1332
1347
  The header and log line are on by default. Set the Wrangler var
1333
1348
  `SERVER_TIMING = "0"` on a target (for example in `environments.production.vars`)
1334
1349
  to turn both off there. `SERVER_TIMING = "debug"` adds a `statements` array to
@@ -23,15 +23,16 @@ The PartyServer `Server` class extends `DurableObject`, so any in-worker DO you
23
23
 
24
24
  ```ts
25
25
  // quickback/features/interviews/lib/InterviewRoom.ts
26
- import { Server, type Connection, type WSMessage } from 'partyserver';
26
+ import { Server, type Connection, type ConnectionContext, type WSMessage } from 'partyserver';
27
27
 
28
28
  export class InterviewRoom extends Server {
29
29
  static options = { hibernate: true };
30
30
 
31
31
  presence = new Map<string, { userId?: string; name?: string }>();
32
32
 
33
- onConnect(connection: Connection) {
34
- this.presence.set(connection.id, {});
33
+ onConnect(connection: Connection, ctx: ConnectionContext) {
34
+ // Verified by the Worker gate; never sent by the client (see "Who connected").
35
+ this.presence.set(connection.id, { userId: ctx.request.headers.get("x-quickback-user-id") ?? undefined });
35
36
  this.broadcastPresence();
36
37
  }
37
38
 
@@ -192,6 +193,18 @@ What the compiler emits:
192
193
 
193
194
  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.
194
195
 
196
+ ### Who connected
197
+
198
+ Every upgrade that passes the gate reaches the Durable Object with the caller's server-resolved identity stamped on the request. The Worker strips any inbound copy of these headers first, so a client cannot forge them:
199
+
200
+ | Header | Value |
201
+ |--------|-------|
202
+ | `x-quickback-user-id` | `ctx.userId` |
203
+ | `x-quickback-org-id` | `ctx.activeOrgId`, when the session has an active organization |
204
+ | `x-quickback-roles` | `ctx.roles` joined with `,` |
205
+
206
+ 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
+
195
208
  ### Migrating a hand-rolled `onConnect` room to a declarative gate
196
209
 
197
210
  If a room currently enforces access by hand inside `onConnect` / `onBeforeConnect` — typically because the room sits on a multi-table feature and an earlier compiler refused the ambiguous string shorthand — you can almost always replace it with a declarative `access` block. The decision is just "what is the roomId?":
@@ -200,7 +213,7 @@ If a room currently enforces access by hand inside `onConnect` / `onBeforeConnec
200
213
  2. **roomId is a unique non-PK column** (a slug, a `yjsRoomId`) → add `key`: `access: { resource: { feature, table, key: 'yjsRoomId' } }`.
201
214
  3. **one DO class serves several room kinds** (e.g. `conv-<id>` / `ticket-<id>`) → the multi-resource form with a `pattern` that captures the kind and id.
202
215
  4. **access depends on membership, not just tenant** (e.g. "is this user an attendee of the event that owns this page") → you do **not** need hand-written code. Declare the pinned table's firewall with a `via:` relationship; the gate runs the table's *full* `buildFirewallConditions`, relationship subqueries included.
203
- 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from request data — a Durable Object has no session and only sees client-settable headers, so trusting an `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits.
216
+ 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from client-sent request data — a Durable Object has no session, so trusting a client's `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits; the Worker then stamps the verified identity for the room to read (see "Who connected").
204
217
 
205
218
  The declarative gate runs the exact firewall the CRUD `GET /:id` handler enforces, with the same 401/403 semantics, *before* the WebSocket upgrade — so by the time `onConnect` fires the caller is already authorized. Dropping the hand-rolled check also closes a common gap: a room with no `access` block is reachable by **any** authenticated user who can guess a room id, regardless of tenant.
206
219
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.70.19",
3
+ "version": "0.70.23",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -10,6 +10,37 @@ shaped byte-identically to the CRUD list endpoints they replace, a
10
10
  hand-re-derived per-slice masking. `defineBundle` generates all of it.
11
11
 
12
12
  ```typescript
13
+ // features/events/guests.ts
14
+ import { feature, q } from "@quickback/compiler";
15
+
16
+ export default feature("guests", {
17
+ columns: {
18
+ id: q.id(),
19
+ eventId: q.text().required().index(),
20
+ status: q.text().required(),
21
+ displayName: q.text().required(),
22
+ organizationId: q.scope("organization"),
23
+ ...q.audit(),
24
+ ...q.softDelete(),
25
+ },
26
+ read: { access: { roles: ["member", "admin"] } },
27
+ });
28
+
29
+ // features/events/supportTickets.ts
30
+ import { feature, q } from "@quickback/compiler";
31
+
32
+ export default feature("supportTickets", {
33
+ columns: {
34
+ id: q.id(),
35
+ eventId: q.text().required().index(),
36
+ subject: q.text().required(),
37
+ organizationId: q.scope("organization"),
38
+ ...q.audit(),
39
+ ...q.softDelete(),
40
+ },
41
+ read: { access: { roles: ["member", "admin"] } },
42
+ });
43
+
13
44
  // features/events/actions/getOverviewBundle.ts
14
45
  import { z } from "zod";
15
46
  import { defineBundle, list, custom } from "../.quickback/define-bundle";
@@ -17,17 +48,17 @@ import { defineBundle, list, custom } from "../.quickback/define-bundle";
17
48
  export default defineBundle({
18
49
  path: "/event/:eventId/overview-bundle",
19
50
  description: "Console Overview bootstrap",
20
- access: { roles: ["member", "admin"] },
21
- etag: true, // default true
22
- serverTiming: "overview", // optional
51
+ access: { roles: ["member", "admin"] }, // a subset of every list table's read.access
52
+ etag: true, // default true
53
+ serverTiming: "overview", // optional
23
54
  sections: {
24
55
  guests: list("guests", {
25
56
  columns: ["id", "status", "modifiedAt", "createdAt", "displayName"],
26
- where: { eventId: "$ctx.event.id" },
57
+ where: { eventId: "$path.eventId" },
27
58
  orderBy: [{ createdAt: "desc" }],
28
59
  limit: 500,
29
60
  }),
30
- tickets: list("supportTickets", { where: { eventId: "$ctx.event.id" }, orderBy: [{ modifiedAt: "desc" }], limit: 100 }),
61
+ tickets: list("supportTickets", { where: { eventId: "$path.eventId" }, orderBy: [{ modifiedAt: "desc" }], limit: 100 }),
31
62
  counts: custom(async ({ db, ctx }) => ({ open: 0 }), { output: z.object({ open: z.number().int() }) }),
32
63
  },
33
64
  });
@@ -67,7 +98,11 @@ export default defineBundle({
67
98
  - **`sections` filter**: omitted/empty = all. An un-wanted list section
68
99
  returns `{ data: [], hasMore: false, nextCursor: null }` (drop-in
69
100
  compatible with existing clients); un-wanted `custom` sections are absent.
70
- - **All sections run in one `Promise.all`.**
101
+ - **All sections run in one `Promise.all`.** On Postgres over Hyperdrive
102
+ each concurrent section leases its own connection, opened cold for the
103
+ request — a five-section bundle reports `cold=5 tx=5` in
104
+ [`Server-Timing`](/platform/database/neon#measuring-database-cost-server-timing).
105
+ Fewer sections is the lever when that dominates.
71
106
  - **ETag**: SHA-1 hex over `{ scopeSeed: <path params>, userId, payload }`.
72
107
  An `ifNoneMatch` match returns `{ success: true, etag, notModified: true }`
73
108
  with **no sections**. The digest is also exported as `sha1Hex` from
@@ -141,9 +176,15 @@ must pass the same complete-input-schema check as other actions.
141
176
  - Unknown section tables error, listing candidates.
142
177
  - `columns` / `where` / `orderBy` must name declared columns
143
178
  (compiler-injected audit columns like `createdAt`/`modifiedAt` are allowed).
179
+ - `list()` options are literals, or a same-file top-level
180
+ `const MANY = 2000` — anything else fails with "use a literal".
144
181
  - `where` values are literals or the strict substitution allowlist
145
- (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`) — always
146
- parameterized. Anything richer belongs in a `custom()` section.
182
+ (`$ctx.userId`, `$ctx.activeOrgId`, `$ctx.<scope>.id`, and
183
+ `$path.<param>` for a param of the bundle's own `path`, e.g.
184
+ `path: "/projects/:projectId/overview"` with
185
+ `where: { projectId: "$path.projectId" }`) — always parameterized. A
186
+ `$path` param the path does not declare is a compile error. Anything
187
+ richer belongs in a `custom()` section.
147
188
  - Section names may not shadow the response envelope
148
189
  (`success`, `etag`, `notModified`, `sections`).
149
190
  - **A bundle must never widen read access**: its `access.roles` must be a
@@ -1329,6 +1329,21 @@ Statement text and parameters are never logged. Work the invocation defers to
1329
1329
  `waitUntil` (audit writes, after-commit effects) runs after the header is sent
1330
1330
  and is not counted.
1331
1331
 
1332
+ **`cold=5 tx=5` on every bundle request is the pool shape, not a leak.** The
1333
+ lease pool is per invocation and holds up to five connections. A
1334
+ [bundle](/define/bundles) runs its sections in one `Promise.all`, so five or
1335
+ more sections lease five connections at once; each is opened cold for this
1336
+ request and opens its own read lane (`BEGIN READ ONLY` + claims), which is
1337
+ the `tx` count. Summed `db` time exceeds wall time because those leases
1338
+ overlap. Connections cannot outlive the invocation on Workers, so there is
1339
+ nothing to warm across requests; the cost of a cold connection is the
1340
+ Hyperdrive handshake plus three round trips before its prepared statements
1341
+ are cached. Before changing a bundle's shape, run `SERVER_TIMING = "debug"`
1342
+ and read the `first` flags per lane: if most statements are `first`, the
1343
+ request is paying for connections, and fewer, larger sections (or a lower
1344
+ section count) is the lever; if few are, the cost is the statements
1345
+ themselves.
1346
+
1332
1347
  The header and log line are on by default. Set the Wrangler var
1333
1348
  `SERVER_TIMING = "0"` on a target (for example in `environments.production.vars`)
1334
1349
  to turn both off there. `SERVER_TIMING = "debug"` adds a `statements` array to
@@ -23,15 +23,16 @@ The PartyServer `Server` class extends `DurableObject`, so any in-worker DO you
23
23
 
24
24
  ```ts
25
25
  // quickback/features/interviews/lib/InterviewRoom.ts
26
- import { Server, type Connection, type WSMessage } from 'partyserver';
26
+ import { Server, type Connection, type ConnectionContext, type WSMessage } from 'partyserver';
27
27
 
28
28
  export class InterviewRoom extends Server {
29
29
  static options = { hibernate: true };
30
30
 
31
31
  presence = new Map<string, { userId?: string; name?: string }>();
32
32
 
33
- onConnect(connection: Connection) {
34
- this.presence.set(connection.id, {});
33
+ onConnect(connection: Connection, ctx: ConnectionContext) {
34
+ // Verified by the Worker gate; never sent by the client (see "Who connected").
35
+ this.presence.set(connection.id, { userId: ctx.request.headers.get("x-quickback-user-id") ?? undefined });
35
36
  this.broadcastPresence();
36
37
  }
37
38
 
@@ -192,6 +193,18 @@ What the compiler emits:
192
193
 
193
194
  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.
194
195
 
196
+ ### Who connected
197
+
198
+ Every upgrade that passes the gate reaches the Durable Object with the caller's server-resolved identity stamped on the request. The Worker strips any inbound copy of these headers first, so a client cannot forge them:
199
+
200
+ | Header | Value |
201
+ |--------|-------|
202
+ | `x-quickback-user-id` | `ctx.userId` |
203
+ | `x-quickback-org-id` | `ctx.activeOrgId`, when the session has an active organization |
204
+ | `x-quickback-roles` | `ctx.roles` joined with `,` |
205
+
206
+ 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
+
195
208
  ### Migrating a hand-rolled `onConnect` room to a declarative gate
196
209
 
197
210
  If a room currently enforces access by hand inside `onConnect` / `onBeforeConnect` — typically because the room sits on a multi-table feature and an earlier compiler refused the ambiguous string shorthand — you can almost always replace it with a declarative `access` block. The decision is just "what is the roomId?":
@@ -200,7 +213,7 @@ If a room currently enforces access by hand inside `onConnect` / `onBeforeConnec
200
213
  2. **roomId is a unique non-PK column** (a slug, a `yjsRoomId`) → add `key`: `access: { resource: { feature, table, key: 'yjsRoomId' } }`.
201
214
  3. **one DO class serves several room kinds** (e.g. `conv-<id>` / `ticket-<id>`) → the multi-resource form with a `pattern` that captures the kind and id.
202
215
  4. **access depends on membership, not just tenant** (e.g. "is this user an attendee of the event that owns this page") → you do **not** need hand-written code. Declare the pinned table's firewall with a `via:` relationship; the gate runs the table's *full* `buildFirewallConditions`, relationship subqueries included.
203
- 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from request data — a Durable Object has no session and only sees client-settable headers, so trusting an `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits.
216
+ 5. **roomId is the caller's own identity** (a per-user gateway/presence/inbox where the room *is* `ctx.userId`, with no backing table) → `access: { roomIdEquals: 'ctx.userId' }` (or `'ctx.activeOrgId'`). Do **not** enforce this inside the DO from client-sent request data — a Durable Object has no session, so trusting a client's `x-user-id` header lets any authenticated user open another user's room. The gate belongs at the Worker edge, which is exactly what this arm emits; the Worker then stamps the verified identity for the room to read (see "Who connected").
204
217
 
205
218
  The declarative gate runs the exact firewall the CRUD `GET /:id` handler enforces, with the same 401/403 semantics, *before* the WebSocket upgrade — so by the time `onConnect` fires the caller is already authorized. Dropping the hand-rolled check also closes a common gap: a room with no `access` block is reachable by **any** authenticated user who can guess a room id, regardless of tenant.
206
219