@quickback-dev/cli 0.48.0 → 0.50.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/commands/compile.d.ts.map +1 -1
- package/dist/commands/compile.js +13 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/commands/migrations.d.ts +10 -0
- package/dist/commands/migrations.d.ts.map +1 -1
- package/dist/commands/migrations.js +113 -79
- package/dist/commands/migrations.js.map +1 -1
- package/dist/commands/migrations.test.js +96 -1
- package/dist/commands/migrations.test.js.map +1 -1
- package/dist/docs/content.js +9 -9
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/docs/changelog.md +84 -0
- package/dist/skill/docs/compiler/config/providers.md +23 -2
- package/dist/skill/docs/compiler/definitions/actions.md +12 -2
- package/dist/skill/docs/compiler/definitions/encryption.md +2 -0
- package/dist/skill/docs/compiler/definitions/schema.md +2 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +306 -35
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +14 -8
- package/dist/skill/docs/stack/realtime/durable-objects.md +143 -4
- package/dist/skill/docs/stack/webhooks/outbound.md +23 -0
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +84 -0
- package/src/skill/docs/compiler/config/providers.md +23 -2
- package/src/skill/docs/compiler/definitions/actions.md +12 -2
- package/src/skill/docs/compiler/definitions/encryption.md +2 -0
- package/src/skill/docs/compiler/definitions/schema.md +2 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +306 -35
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +14 -8
- package/src/skill/docs/stack/realtime/durable-objects.md +143 -4
- package/src/skill/docs/stack/webhooks/outbound.md +23 -0
|
@@ -245,9 +245,16 @@ await realtime.broadcast('screening-complete', {
|
|
|
245
245
|
applicationId: 'app_123',
|
|
246
246
|
candidateId: 'cnd_456',
|
|
247
247
|
stage: 'interview'
|
|
248
|
-
}, ctx.activeOrgId
|
|
248
|
+
}, ctx.activeOrgId!, {
|
|
249
|
+
targetRoles: ['AUTHENTICATED'],
|
|
250
|
+
});
|
|
249
251
|
```
|
|
250
252
|
|
|
253
|
+
**Every send needs an audience.** Delivery is fail-closed: a broadcast whose
|
|
254
|
+
`targetRoles` is omitted or empty reaches **nobody**. "Everyone in the room" is
|
|
255
|
+
spelled explicitly — `targetRoles: ['AUTHENTICATED']` (any authenticated
|
|
256
|
+
subscriber) or `['PUBLIC']`.
|
|
257
|
+
|
|
251
258
|
Broadcasts:
|
|
252
259
|
```json
|
|
253
260
|
{
|
|
@@ -268,7 +275,8 @@ Target a specific user instead of the entire organization:
|
|
|
268
275
|
```typescript
|
|
269
276
|
// Only this user receives the notification
|
|
270
277
|
await realtime.insert('notifications', newNotification, ctx.activeOrgId!, {
|
|
271
|
-
userId: ctx.userId
|
|
278
|
+
userId: ctx.userId,
|
|
279
|
+
targetRoles: ['AUTHENTICATED'],
|
|
272
280
|
});
|
|
273
281
|
|
|
274
282
|
// Notify a hiring manager of a new application
|
|
@@ -276,10 +284,16 @@ await realtime.broadcast('application-received', {
|
|
|
276
284
|
applicationId: 'app_123',
|
|
277
285
|
jobId: 'job_789'
|
|
278
286
|
}, ctx.activeOrgId!, {
|
|
279
|
-
userId: hiringManagerId
|
|
287
|
+
userId: hiringManagerId,
|
|
288
|
+
targetRoles: ['AUTHENTICATED'],
|
|
280
289
|
});
|
|
281
290
|
```
|
|
282
291
|
|
|
292
|
+
`userId` targeting matches the **socket identity** — the Better Auth user id, or
|
|
293
|
+
the synthetic `scope:<subjectId>` principal for sessionless scope connections. If
|
|
294
|
+
the same person can connect through either door, prefer
|
|
295
|
+
[identity-tag targeting](#identity-tag-targeting) — one send reaches both.
|
|
296
|
+
|
|
283
297
|
## Role-Based Filtering
|
|
284
298
|
|
|
285
299
|
Limit which roles receive a broadcast using `targetRoles`:
|
|
@@ -296,7 +310,132 @@ await realtime.update('applications', newRecord, oldRecord, ctx.activeOrgId!, {
|
|
|
296
310
|
});
|
|
297
311
|
```
|
|
298
312
|
|
|
299
|
-
|
|
313
|
+
**Fail-closed (v0.48+):** an omitted or empty `targetRoles` delivers to
|
|
314
|
+
**nobody** — there is no implicit "everyone" fallback. To reach every
|
|
315
|
+
authenticated subscriber in the scope, say so explicitly with
|
|
316
|
+
`targetRoles: ['AUTHENTICATED']`. UPPERCASE pseudo-roles (`PUBLIC`,
|
|
317
|
+
`AUTHENTICATED`, `USER`, `SYSADMIN`) are evaluated exactly as the REST access
|
|
318
|
+
evaluator does.
|
|
319
|
+
|
|
320
|
+
> **Migrating from pre-0.48:** custom `realtime.broadcast(...)` /
|
|
321
|
+
> `realtime.insert(...)` calls that omitted `targetRoles` used to fan out to
|
|
322
|
+
> everyone; they now silently deliver to nobody. Audit every manual send and add
|
|
323
|
+
> an explicit audience.
|
|
324
|
+
|
|
325
|
+
## Identity-Tag Targeting
|
|
326
|
+
|
|
327
|
+
Every connection carries **identity tags**, proven at ticket mint and signed
|
|
328
|
+
into the ticket (never client-supplied):
|
|
329
|
+
|
|
330
|
+
- `user:<userId>` — every Better Auth caller
|
|
331
|
+
- `scope:<kind>:<subjectId>` — when a scope subject is proven, on **either**
|
|
332
|
+
door: a sessionless scope principal's verified claim, or a Better Auth caller
|
|
333
|
+
whose matched relationship lane maps to a scope kind with
|
|
334
|
+
`subject: 'supplied' | 'both'`. Both doors stamp the **identical** tag (the
|
|
335
|
+
subject row's id), which is the point.
|
|
336
|
+
|
|
337
|
+
Target them with `targetTags`:
|
|
338
|
+
|
|
339
|
+
```typescript
|
|
340
|
+
// ONE send reaches this guest whether they're connected via their Better Auth
|
|
341
|
+
// session or a sessionless scope link — no per-identity double-send.
|
|
342
|
+
await realtime.broadcast('chat.frame', payload, { scopeKey }, {
|
|
343
|
+
targetTags: [`scope:guest:${guestId}`],
|
|
344
|
+
targetRoles: ['AUTHENTICATED'],
|
|
345
|
+
});
|
|
346
|
+
|
|
347
|
+
// Reach a person under either identity explicitly (deduped per socket):
|
|
348
|
+
await realtime.broadcast('rsvp.updated', payload, { scopeKey }, {
|
|
349
|
+
targetTags: [`scope:guest:${guestId}`, `user:${linkedUserId}`],
|
|
350
|
+
targetRoles: ['AUTHENTICATED'],
|
|
351
|
+
});
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
Semantics:
|
|
355
|
+
|
|
356
|
+
- Delivery is the **deduplicated union** of the runtime's indexed tag lookup
|
|
357
|
+
(`getWebSockets(tag)`) — no attachment scan, and a dual-identity socket
|
|
358
|
+
matches once.
|
|
359
|
+
- `targetTags` **replaces the `userId` identity arm** when present; the
|
|
360
|
+
scope/org bind and the `targetRoles` audience still apply on top.
|
|
361
|
+
- **Fail-closed:** `targetTags: []` delivers to nobody.
|
|
362
|
+
- Tags are **immutable** for a socket's lifetime (a Workers hibernation-tag
|
|
363
|
+
constraint) — an identity change requires a reconnect.
|
|
364
|
+
- Limits: at most 10 tags per connection, 256 characters per tag. The mint
|
|
365
|
+
rejects violations; it never truncates.
|
|
366
|
+
|
|
367
|
+
## Authorization Lease
|
|
368
|
+
|
|
369
|
+
The 60-second ws-ticket is verified once, at upgrade — but Durable Object
|
|
370
|
+
hibernation keeps sockets alive indefinitely. Without a lease, a ban, member
|
|
371
|
+
removal, or subject revocation (say, an organizer cancelling a guest) would
|
|
372
|
+
never affect an already-connected socket. The lease closes that gap:
|
|
373
|
+
|
|
374
|
+
- At upgrade, the connection stores `authExpiresAt = ticket.iat + lease`
|
|
375
|
+
(default **15 minutes**).
|
|
376
|
+
- The fan-out **skips expired connections** — they receive nothing — and closes
|
|
377
|
+
them with code **4401** so the client knows to re-ticket rather than blindly
|
|
378
|
+
reconnect. Inbound messages (even pings) are enforced the same way.
|
|
379
|
+
- Renewal happens at mint: `POST /broadcast/v1/ws-ticket` re-runs the full
|
|
380
|
+
authorization gate (session validity, revocation checks, relationship /
|
|
381
|
+
scope-claim probes), so a revoked principal simply can't obtain a renewal
|
|
382
|
+
ticket. Revocation propagates within one lease period with no polling.
|
|
383
|
+
|
|
384
|
+
Configure it on the realtime transport:
|
|
385
|
+
|
|
386
|
+
```typescript
|
|
387
|
+
providers: {
|
|
388
|
+
database: {
|
|
389
|
+
config: {
|
|
390
|
+
realtime: {
|
|
391
|
+
enabled: true,
|
|
392
|
+
lease: '15m', // default; also '900s', '1h', or a number of seconds
|
|
393
|
+
// lease: false // disable (discouraged — reopens the revocation gap)
|
|
394
|
+
},
|
|
395
|
+
},
|
|
396
|
+
},
|
|
397
|
+
}
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
The lease must be at least 60 seconds (the handshake-ticket TTL).
|
|
401
|
+
|
|
402
|
+
### In-place renewal (`reauth`)
|
|
403
|
+
|
|
404
|
+
Instead of reconnecting every lease period, a client can renew in place: mint a
|
|
405
|
+
fresh ticket and send it over the open socket.
|
|
406
|
+
|
|
407
|
+
```typescript
|
|
408
|
+
// On a timer comfortably inside the lease (e.g. every 10 min for a 15m lease):
|
|
409
|
+
const { wsTicket } = await mintTicket(); // POST /broadcast/v1/ws-ticket
|
|
410
|
+
ws.send(JSON.stringify({ type: 'reauth', ticket: wsTicket }));
|
|
411
|
+
|
|
412
|
+
ws.onmessage = (event) => {
|
|
413
|
+
const msg = JSON.parse(event.data);
|
|
414
|
+
if (msg.type === 'reauth_ok') {
|
|
415
|
+
scheduleNextRenewal(msg.authExpiresAt); // lease extended, roles refreshed
|
|
416
|
+
}
|
|
417
|
+
if (msg.type === 'error' && msg.code === 'REAUTH_FAILED') {
|
|
418
|
+
// Ticket invalid/expired — mint a fresh one and retry before the lease lapses.
|
|
419
|
+
}
|
|
420
|
+
};
|
|
421
|
+
|
|
422
|
+
ws.onclose = (event) => {
|
|
423
|
+
if (event.code === 4401) {
|
|
424
|
+
// Lease expired or identity drift: mint a fresh ticket and reconnect.
|
|
425
|
+
reconnectWithFreshTicket();
|
|
426
|
+
}
|
|
427
|
+
};
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Renewal is **strict**: the fresh ticket must carry the same `userId`,
|
|
431
|
+
`scopeKey`/`organizationId`, and the **exact same tag set** as the live socket
|
|
432
|
+
(tags are immutable). A renewal that matches extends the lease and refreshes
|
|
433
|
+
`role`/`roles` in place — live permission changes without socket churn. One
|
|
434
|
+
that doesn't closes the socket with 4401: reconnect fresh.
|
|
435
|
+
|
|
436
|
+
Clients that never send `reauth` still work — their socket is closed with 4401
|
|
437
|
+
once per lease and normal reconnect logic (with a fresh ticket) re-runs the
|
|
438
|
+
full gate. The lease is the server-side invariant either way.
|
|
300
439
|
|
|
301
440
|
## Per-Role Field Masking
|
|
302
441
|
|
|
@@ -275,6 +275,29 @@ database: defineDatabase("cloudflare-d1", {
|
|
|
275
275
|
|
|
276
276
|
This generates the webhook database schema, routes, queue consumer, and all supporting code.
|
|
277
277
|
|
|
278
|
+
### On Neon (Postgres)
|
|
279
|
+
|
|
280
|
+
Webhooks are supported on the `neon` provider too. `webhooksBinding` acts as a
|
|
281
|
+
pure enable flag — there is no separate webhooks database. The webhook tables
|
|
282
|
+
live in a dedicated `webhooks` Postgres schema of your single Neon database,
|
|
283
|
+
created by the standard drizzle migration set, and are locked down by an RLS
|
|
284
|
+
policy so only the Worker's internal service-role handle can touch them:
|
|
285
|
+
|
|
286
|
+
```typescript
|
|
287
|
+
database: defineDatabase("neon", {
|
|
288
|
+
connectionMode: "http", // required for webhooks
|
|
289
|
+
webhooksBinding: "WEBHOOKS_DB", // enable flag; no D1 binding is emitted
|
|
290
|
+
// queue names stay configurable on any provider:
|
|
291
|
+
webhooksQueueName: "my-app-webhooks-queue",
|
|
292
|
+
webhooksDlqName: "my-app-webhooks-dlq",
|
|
293
|
+
})
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
The D1-only keys `webhooksDatabaseId` / `webhooksDatabaseName` are rejected at
|
|
297
|
+
compile time on Neon, and webhooks require `connectionMode: 'http'` (the
|
|
298
|
+
Cloudflare default). Queue wiring (`WEBHOOKS_QUEUE`, the consumer, and the
|
|
299
|
+
dead letter queue) is identical across providers.
|
|
300
|
+
|
|
278
301
|
## See Also
|
|
279
302
|
|
|
280
303
|
- [Inbound Webhooks](/stack/webhooks/inbound) — Receive webhooks from external services
|