@quickback-dev/cli 0.53.0 → 0.55.0
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/docs/content.d.ts.map +1 -1
- package/dist/docs/content.js +10 -5
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +6 -2
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/skill/docs/changelog.md +20 -0
- package/dist/skill/docs/compiler/definitions/access.md +29 -5
- package/dist/skill/docs/compiler/definitions/actions.md +2 -0
- package/dist/skill/docs/compiler/definitions/scopes.md +10 -4
- package/dist/skill/docs/stack/realtime/index.md +3 -1
- package/dist/skill/docs/stack/realtime/named-invalidations.md +147 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +20 -0
- package/src/skill/docs/compiler/definitions/access.md +29 -5
- package/src/skill/docs/compiler/definitions/actions.md +2 -0
- package/src/skill/docs/compiler/definitions/scopes.md +10 -4
- package/src/skill/docs/stack/realtime/index.md +3 -1
- package/src/skill/docs/stack/realtime/named-invalidations.md +147 -0
|
@@ -56,7 +56,7 @@ delete: { access: { roles: ["owner"] } }, // owner only (no +)
|
|
|
56
56
|
The `+` suffix expands at compile time — `"member+"` becomes `["member", "admin", "owner"]` in the generated code. You can mix hierarchical and exact roles: `roles: ["member+", "finance"]` expands to `["member", "admin", "owner", "finance"]`.
|
|
57
57
|
|
|
58
58
|
- Roles without `+` are exact matches (no expansion)
|
|
59
|
-
- Pseudo-roles / reserved markers (`PUBLIC`, `AUTHENTICATED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
|
|
59
|
+
- Pseudo-roles / reserved markers (`PUBLIC`, `AUTHENTICATED`, `SESSION`, `SCOPED`, `USER`, `ADMIN`, `SYSADMIN`) cannot use the `+` suffix — they're terminal markers
|
|
60
60
|
- Using `+` with a role not in the hierarchy throws a compile error
|
|
61
61
|
- Using `+` without configuring `auth.roleHierarchy` throws a compile error
|
|
62
62
|
|
|
@@ -141,12 +141,14 @@ When `roles` and `userRole` both appear in a single `Access` node, they're combi
|
|
|
141
141
|
|
|
142
142
|
### Pseudo-roles
|
|
143
143
|
|
|
144
|
-
Quickback ships
|
|
144
|
+
Quickback ships seven reserved UPPERCASE markers. Six are real pseudo-roles handled directly by the compiler; `ADMIN` is retained only as a reserved legacy marker so the compiler can fail loudly with migration guidance. The casing carries the boundary: UPPERCASE = compiler-owned marker, lowercase = real role from a plugin's table (e.g. `members.role` from the org plugin).
|
|
145
145
|
|
|
146
146
|
| Role | Auth gate | Compile-time requirement | Runtime check |
|
|
147
147
|
|------|-----------|-------------------------|---------------|
|
|
148
148
|
| `PUBLIC` | bypassed | none — explicit opt-in for unauthenticated access | always passes (auth skipped) |
|
|
149
|
-
| `AUTHENTICATED` | required | none | `ctx.authenticated === true` |
|
|
149
|
+
| `AUTHENTICATED` | required | none | `ctx.authenticated === true` (a full session **or** a scope principal — the wrapper over `SESSION` ∪ `SCOPED`) |
|
|
150
|
+
| `SESSION` | required | none | a full Better Auth session **only** — `ctx.authenticated && !ctx.principal && !ctx.scopePrincipal` |
|
|
151
|
+
| `SCOPED` | required | none | a sessionless scope principal **only** — `ctx.authenticated && ctx.scopePrincipal === true` |
|
|
150
152
|
| `USER` | required | resource firewall **must** scope by `userId` | `ctx.authenticated` AND (`ctx.userRole` is unset OR `ctx.userRole === "user"`) |
|
|
151
153
|
| `ADMIN` | required | reserved legacy marker — compiler rejects it | `false` |
|
|
152
154
|
| `SYSADMIN` | required | `cms: { sysadmin: true }` **must** be set on the project | `ctx.authenticated && ctx.userRole === "sysadmin"` |
|
|
@@ -194,15 +196,37 @@ export default defineTable(listings, {
|
|
|
194
196
|
});
|
|
195
197
|
```
|
|
196
198
|
|
|
197
|
-
#### `AUTHENTICATED` — any
|
|
199
|
+
#### `AUTHENTICATED` — any authenticated caller (the wrapper)
|
|
198
200
|
|
|
199
|
-
Use `roles: ["AUTHENTICATED"]` for endpoints that any logged-in
|
|
201
|
+
Use `roles: ["AUTHENTICATED"]` for endpoints that any logged-in caller can hit, regardless of role or org membership. No plugin context required.
|
|
200
202
|
|
|
201
203
|
```typescript
|
|
202
204
|
// Public events feed — any signed-in user can list/read; anonymous gets 401
|
|
203
205
|
read: { access: { roles: ["AUTHENTICATED"] } }
|
|
204
206
|
```
|
|
205
207
|
|
|
208
|
+
`AUTHENTICATED` is the **wrapper over two auth flavors** — it admits both a full Better Auth session **and** a sessionless scope principal (a scope-token holder, e.g. an event attendee who isn't an org member; see [Scopes](/compiler/definitions/scopes)). It excludes only *external delegated* principals (`ctx.principal`, admitted via `principals:`). When you need to distinguish the two flavors, use `SESSION` or `SCOPED` below; when either is fine, use `AUTHENTICATED`.
|
|
209
|
+
|
|
210
|
+
#### `SESSION` — a full session only
|
|
211
|
+
|
|
212
|
+
Use `roles: ["SESSION"]` when a route must admit **only** a full Better Auth session and **not** a sessionless scope principal. This is `AUTHENTICATED` minus scope-token callers.
|
|
213
|
+
|
|
214
|
+
```typescript
|
|
215
|
+
// Account settings — a real logged-in user, never a scope-token attendee
|
|
216
|
+
read: { access: { roles: ["SESSION"] } }
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
#### `SCOPED` — a scope principal only
|
|
220
|
+
|
|
221
|
+
Use `roles: ["SCOPED"]` for a route that is specifically for **sessionless scope-token callers** (a principal-only surface — e.g. a shared event link or kiosk token with no account). It admits any scope principal regardless of *which* scope; for a **specific** scoped role, use the `scope:<kind>:<role>` form instead (e.g. `scope:event:attendee` — see [Scopes](/compiler/definitions/scopes)).
|
|
222
|
+
|
|
223
|
+
```typescript
|
|
224
|
+
// Principal-only event surface — a scope token, no account required
|
|
225
|
+
read: { access: { roles: ["SCOPED"] } }
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
> **Firewall coherence:** if an access surface admits a scope caller (`SCOPED` or a `scope:<kind>:<role>` role) but the resource firewall can't filter that caller, the compiler **fails the build** — the caller would reach the handler yet see zero rows (a silent `200 + []`). Give the firewall a way to filter them: a `ctx.scope.<kind>` arm inside an `{ any: [...] }` group (compose org **or** scope — see [Firewall](/compiler/definitions/firewall)), a `via:` relationship, or `firewall: [{ exception: true }]`.
|
|
229
|
+
|
|
206
230
|
#### `USER` — per-user records
|
|
207
231
|
|
|
208
232
|
Use `roles: ["USER"]` for resources where each user only sees their own records. **Requires the firewall to scope by `userId`** — the role marker is the access half of the pair, the firewall is the row-filter half.
|
|
@@ -1311,6 +1311,8 @@ table-level generated transition actions. See **[Transitions](/compiler/definiti
|
|
|
1311
1311
|
|
|
1312
1312
|
## After-commit hooks
|
|
1313
1313
|
|
|
1314
|
+
> For typed realtime *"this changed — refresh"* signals, use [`invalidates`](/stack/realtime/named-invalidations) — it rides this same after-commit model but delivers a versioned, targeted frame to subscribers.
|
|
1315
|
+
|
|
1314
1316
|
Secondary effects — activity feeds, notification nudges, cache warmers — must
|
|
1315
1317
|
never roll back or delay the primary write. Instead of hand-wrapping each leg
|
|
1316
1318
|
in `try/catch` + `executionCtx.waitUntil`, declare named `afterCommit` hooks:
|
|
@@ -535,10 +535,16 @@ primary key + the `where:` filter keeps it bounded and fail-closed.
|
|
|
535
535
|
nothing else. There is **no user identity**: the auth middleware builds a context
|
|
536
536
|
with **`ctx.userId` undefined**, so every user-, org-, and owner-gated path
|
|
537
537
|
**fails closed automatically** (an owner firewall compares against `undefined`
|
|
538
|
-
→ matches nothing; org-role gates see empty `ctx.roles`).
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
`
|
|
538
|
+
→ matches nothing; org-role gates see empty `ctx.roles`). `AUTHENTICATED`
|
|
539
|
+
**admits** a scope principal past the auth gate — it's the wrapper over session
|
|
540
|
+
*and* scope callers (see [Access → Pseudo-roles](/compiler/definitions/access),
|
|
541
|
+
where `SESSION` and `SCOPED` distinguish the two) — but a user/org/owner
|
|
542
|
+
**firewall** then filters it to **zero rows** (no `ctx.userId`, no `ctx.activeOrgId`),
|
|
543
|
+
so it reaches nothing it shouldn't. `USER` is likewise gate-permissive but
|
|
544
|
+
firewall-excluded: it mandates a `userId` scope the principal can't satisfy. To
|
|
545
|
+
serve a scope principal actual rows, use `scope:<kind>:<role>` gates +
|
|
546
|
+
`ctx.scope.<kind>` firewall arms (or `SCOPED` to admit any scope-token caller as
|
|
547
|
+
a tier).
|
|
542
548
|
|
|
543
549
|
Everything downstream — REST firewall, masking, scoped-role access, the realtime
|
|
544
550
|
ws-ticket — then treats the sessionless attendee **identically** to a
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Quickback ships **two parallel realtime primitives**, both backed by Cloudflare Durable Objects:
|
|
4
4
|
|
|
5
|
-
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.version` — contract-v2 projects mount the same surface at `/broadcast/v2` (no hidden v1 alias). Documented on this page.
|
|
5
|
+
- **`/broadcast/v1/*` — server fan-out.** One DO instance per subscription scope. Postgres-changes events from CRUD routes plus custom broadcast events flow out to every subscriber, with role filtering and per-role field masking applied. Best for "tell every client in this shared scope that something changed." The scope can be an organization, a specific user, or a compiler-resolved resource key like `events:evt_123`. The `/broadcast/v1` version segment tracks `contract.version` — contract-v2 projects mount the same surface at `/broadcast/v2` (no hidden v1 alias). Documented on this page. For **typed, targeted "this changed — refresh" signals** fired from an action after commit (with optional per-recipient narrowing), see [Named invalidations](/stack/realtime/named-invalidations).
|
|
6
6
|
- **`/realtime/<binding>/<room-id>` — bidirectional rooms.** One DO instance per room (per document, per interview, per game). Client↔client messages, presence, and CRDT-friendly state. Use these for collaborative editing. See [PartyServer rooms](/stack/realtime/partyserver-rooms).
|
|
7
7
|
|
|
8
8
|
Both share the same auth model and ride on the same compiled worker; they solve different problems.
|
|
@@ -154,4 +154,6 @@ missing organization column fails the build with an actionable message.
|
|
|
154
154
|
|
|
155
155
|
- **[Durable Objects Setup](/stack/realtime/durable-objects)** — Broadcaster configuration, wrangler bindings, event formats, masking, and custom namespaces
|
|
156
156
|
- **[Using Realtime](/stack/realtime/using-realtime)** — Subscribing to `/broadcast/v1/*`: WebSocket connection, ticket auth, client-side handling
|
|
157
|
+
- **[Named Invalidations](/stack/realtime/named-invalidations)** — Typed, targeted "this changed — refresh" signals fired from actions after commit, with optional per-recipient narrowing
|
|
158
|
+
- **[Live Views](/stack/realtime/live-views)** — Keep an open view's full join-surface (root + related children) live with hybrid-delta updates and resync-on-reconnect
|
|
157
159
|
- **[PartyServer Rooms](/stack/realtime/partyserver-rooms)** — Per-room collab via `/realtime/<binding>/<room-id>`: presence, live notes, room IDs
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Named Invalidations
|
|
2
|
+
|
|
3
|
+
CRUD broadcasts tell every subscriber in a scope *"a row changed."* **Named invalidations** let an action say something precise and typed: *"the mobile bundle for event `evt_1` changed — reason `document.created`"* — so clients invalidate exactly the right query or cache, and only the intended audience is notified.
|
|
4
|
+
|
|
5
|
+
They ride the same `/broadcast/v{n}` channel as CRUD broadcasts (see [Using realtime](/stack/realtime/using-realtime)), but they are:
|
|
6
|
+
|
|
7
|
+
- **Typed** — the event, its payload shape, and a contract `version` are declared once in a registry.
|
|
8
|
+
- **Named + versioned** — clients listen for a stable `wireName` (e.g. `event.mobile-bundle.changed`) and branch on a `reason`.
|
|
9
|
+
- **Targeted** — a **delivery profile** sets the maximum audience (a scope room + roles); an optional **recipient resolver** narrows it further, fail-closed.
|
|
10
|
+
- **After-commit + best-effort** — fired from inside an action's `execute`, only if the write commits.
|
|
11
|
+
|
|
12
|
+
## Enable
|
|
13
|
+
|
|
14
|
+
Set `realtime: true` on the database provider and add a registry file under `services/realtime/`:
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
// quickback.config.ts
|
|
18
|
+
database: defineDatabase("cloudflare-d1", { realtime: true }),
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## 1. The registry — `defineRealtime`
|
|
22
|
+
|
|
23
|
+
Declare the typed events. Each event has a `wireName` (what clients subscribe to), a contract `version`, one or more named **variants** (a `reason` + a **strict** Zod `payload`), and the **delivery profiles** it is allowed to use.
|
|
24
|
+
|
|
25
|
+
```typescript
|
|
26
|
+
// services/realtime/attend.ts
|
|
27
|
+
import { z } from "zod";
|
|
28
|
+
import { defineRealtime, defineRealtimeDelivery } from "@quickback/compiler";
|
|
29
|
+
|
|
30
|
+
export const attendRealtime = defineRealtime({
|
|
31
|
+
name: "attend",
|
|
32
|
+
events: {
|
|
33
|
+
mobileBundleChanged: {
|
|
34
|
+
wireName: "event.mobile-bundle.changed", // clients listen for this
|
|
35
|
+
version: 1, // contract version (baked into every frame)
|
|
36
|
+
variants: {
|
|
37
|
+
documentCreated: {
|
|
38
|
+
reason: "document.created", // clients branch on this
|
|
39
|
+
payload: z.object({ eventId: z.string(), documentId: z.string() }).strict(),
|
|
40
|
+
},
|
|
41
|
+
},
|
|
42
|
+
deliveries: ["selectedEvent", "documentWatchers"], // allow-list; profiles defined in steps 2 & 3
|
|
43
|
+
},
|
|
44
|
+
},
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The `payload` must be a **strict** Zod object — its keys are the projection boundary: only declared keys ever reach the wire. `version` and `reason` are reserved contract fields; a payload key named `version` or `reason` is rejected at compile time.
|
|
49
|
+
|
|
50
|
+
## 2. Delivery profiles — `defineRealtimeDelivery`
|
|
51
|
+
|
|
52
|
+
A profile is the **maximum audience** for an invalidation — a scope room plus the roles allowed to receive it. `access.roles` is required and non-empty (a profile is the ceiling, so *who* is not optional — fail-closed).
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
// The event room, attendees + admins.
|
|
56
|
+
export const selectedEvent = defineRealtimeDelivery({
|
|
57
|
+
target: { scopeKeyFrom: "events:{eventId}" }, // the room; {eventId} resolves from the payload
|
|
58
|
+
access: { roles: ["member", "admin"] },
|
|
59
|
+
});
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`target` is either a **scope room** (`scopeKeyFrom: "events:{eventId}"` — the `{...}` columns resolve from the invalidation payload/meta) or the **account lane** (`{ organizationId, userIdFrom }`). Fail-closed: if a template column can't be resolved at runtime, the frame goes to **nobody** — never a full-room fan-out.
|
|
63
|
+
|
|
64
|
+
## 3. Recipient narrowing — `defineRealtimeRecipients` (optional)
|
|
65
|
+
|
|
66
|
+
To deliver to *specific* people rather than the whole room+roles audience, attach a recipient resolver. It runs **post-commit on the firewalled db** and returns **identities** (never raw tags). Quickback intersects `scope ∩ roles ∩ recipient-tags` — a resolver can only **narrow**, never widen. Fail-closed: a throw or `[]` delivers to **nobody**.
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
import { defineRealtimeRecipients } from "@quickback/compiler";
|
|
70
|
+
|
|
71
|
+
export const documentWatchers = defineRealtimeDelivery({
|
|
72
|
+
target: { scopeKeyFrom: "events:{eventId}" },
|
|
73
|
+
access: { roles: ["member", "admin"] },
|
|
74
|
+
recipients: defineRealtimeRecipients({
|
|
75
|
+
input: z.object({ eventId: z.string() }).strict(), // projected from payload/meta
|
|
76
|
+
resolve: async ({ db, input, recipient }) => [
|
|
77
|
+
recipient.user("usr_1"), // a specific user
|
|
78
|
+
recipient.scope({ kind: "team", subjectId: input.eventId }), // everyone with a scope
|
|
79
|
+
],
|
|
80
|
+
}),
|
|
81
|
+
});
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The resolver gets `{ db, input, recipient }` — the scoped (firewalled) db, the projected `input`, and a `recipient` builder (`recipient.user(id)` / `recipient.scope({ kind, subjectId })`). It sees only what the acting caller could see. Resolved identities beyond a safety cap are truncated with a warning; malformed returns are dropped.
|
|
85
|
+
|
|
86
|
+
## 4. Firing from an action — `invalidates`
|
|
87
|
+
|
|
88
|
+
Bind events + profiles on the action, then call the handle inside `execute`. The binding accepts the **symbol-ref** form (imported registry members) or the string-name form:
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
// features/events/actions/createDocument.ts
|
|
92
|
+
import { z } from "zod";
|
|
93
|
+
import { defineAction } from "../.quickback/define-action";
|
|
94
|
+
import { attendRealtime, selectedEvent, documentWatchers } from "../../../services/realtime/attend";
|
|
95
|
+
|
|
96
|
+
export default defineAction({
|
|
97
|
+
path: "/events/:eventId/documents",
|
|
98
|
+
method: "POST",
|
|
99
|
+
input: z.object({ documentId: z.string() }),
|
|
100
|
+
access: { roles: ["admin", "owner"] },
|
|
101
|
+
invalidates: {
|
|
102
|
+
bundle: { event: attendRealtime.mobileBundleChanged, delivery: selectedEvent },
|
|
103
|
+
watchers: { event: attendRealtime.mobileBundleChanged, delivery: documentWatchers },
|
|
104
|
+
},
|
|
105
|
+
async execute({ input, invalidate }) {
|
|
106
|
+
// invalidate.<binding>.<variant>(payload, meta?)
|
|
107
|
+
invalidate!.bundle.documentCreated({ eventId: "evt_1", documentId: input.documentId });
|
|
108
|
+
invalidate!.watchers.documentCreated({ eventId: "evt_1", documentId: input.documentId });
|
|
109
|
+
return { success: true };
|
|
110
|
+
},
|
|
111
|
+
});
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Each `invalidate.<binding>.<variant>(payload)` call queues **one** after-commit frame. Works on every action kind — standalone, per-record (`/:id`), bulk (`/batch`), and namespace-hoisted.
|
|
115
|
+
|
|
116
|
+
## Delivery semantics
|
|
117
|
+
|
|
118
|
+
- **After-commit, best-effort.** Calls queue frames that fire only after `execute` returns successfully; a `throw` or a `dryRun` discards them (they ride the after-commit effects collector). A rolled-back batch record fires nothing.
|
|
119
|
+
- **Fail-closed targeting.** An unresolvable scope room or a missing recipient set delivers to nobody — never a broad fan-out.
|
|
120
|
+
- **Projection.** The frame payload is projected to the variant's declared keys; undeclared fields never reach the wire.
|
|
121
|
+
- **Contract fields.** `version` and `reason` are baked from the registry and always present.
|
|
122
|
+
|
|
123
|
+
## The wire frame
|
|
124
|
+
|
|
125
|
+
Clients receive a broadcast frame on `/broadcast/v{n}` (the version tracks `contract.version`):
|
|
126
|
+
|
|
127
|
+
```jsonc
|
|
128
|
+
{
|
|
129
|
+
"type": "broadcast",
|
|
130
|
+
"event": "event.mobile-bundle.changed", // the wireName
|
|
131
|
+
"payload": {
|
|
132
|
+
"version": 1, // contract version → negotiation
|
|
133
|
+
"reason": "document.created", // what changed → what to refresh
|
|
134
|
+
"eventId": "evt_1",
|
|
135
|
+
"documentId": "doc_9"
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Subscribe to the `wireName`, use `version` for contract negotiation, and branch on `reason` to decide which query/cache to invalidate. Role gating (`targetRoles`) and — when a recipient resolver is used — identity narrowing (`targetTags`) are applied by the Broadcaster before the frame reaches any socket; the client just receives the frames meant for it.
|
|
141
|
+
|
|
142
|
+
## Related
|
|
143
|
+
|
|
144
|
+
- [Using realtime](/stack/realtime/using-realtime) — the `/broadcast` channel these frames ride.
|
|
145
|
+
- [Durable Objects](/stack/realtime/durable-objects) — how `scopeKeyFrom` rooms and the broadcast frame formats work.
|
|
146
|
+
- [Scopes](/compiler/definitions/scopes) — how scope identities (attendees, vendors) are established and carried.
|
|
147
|
+
- [Actions](/compiler/definitions/actions) — the `execute` handler and the after-commit effects model.
|