@quickback-dev/cli 0.10.15 → 0.10.20
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 +40 -2
- package/dist/commands/compile.js.map +1 -1
- package/dist/docs/content.js +6 -6
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/SKILL.md +142 -1051
- package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/dist/skill/docs/changelog.md +1192 -0
- package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
- package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/dist/skill/docs/compiler/config/agents.md +144 -0
- package/dist/skill/docs/compiler/config/auth.md +109 -0
- package/dist/skill/docs/compiler/config/bindings.md +176 -0
- package/dist/skill/docs/compiler/config/domains.md +149 -0
- package/dist/skill/docs/compiler/config/index.md +419 -0
- package/dist/skill/docs/compiler/config/output.md +338 -0
- package/dist/skill/docs/compiler/config/providers.md +248 -0
- package/dist/skill/docs/compiler/config/security.md +255 -0
- package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
- package/dist/skill/docs/compiler/config/variables.md +157 -0
- package/dist/skill/docs/compiler/definitions/access.md +445 -0
- package/dist/skill/docs/compiler/definitions/actions.md +884 -0
- package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
- package/dist/skill/docs/compiler/definitions/feature.md +164 -0
- package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
- package/dist/skill/docs/compiler/definitions/guards.md +241 -0
- package/dist/skill/docs/compiler/definitions/index.md +219 -0
- package/dist/skill/docs/compiler/definitions/masking.md +241 -0
- package/dist/skill/docs/compiler/definitions/read.md +220 -0
- package/dist/skill/docs/compiler/definitions/schema.md +697 -0
- package/dist/skill/docs/compiler/definitions/validation.md +35 -0
- package/dist/skill/docs/compiler/definitions/views.md +292 -0
- package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/dist/skill/docs/compiler/getting-started/index.md +192 -0
- package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
- package/dist/skill/docs/compiler/index.md +85 -0
- package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/dist/skill/docs/compiler/targets/index.md +47 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/dist/skill/docs/compiler/troubleshooting.md +120 -0
- package/dist/skill/docs/index.md +77 -0
- package/dist/skill/docs/stack/account-ui/customization.md +378 -0
- package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
- package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
- package/dist/skill/docs/stack/account-ui/index.md +147 -0
- package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
- package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/dist/skill/docs/stack/account-ui/worker.md +362 -0
- package/dist/skill/docs/stack/auth/api-keys.md +15 -0
- package/dist/skill/docs/stack/auth/device-auth.md +14 -0
- package/dist/skill/docs/stack/auth/index.md +64 -0
- package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
- package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/dist/skill/docs/stack/auth/security.md +455 -0
- package/dist/skill/docs/stack/auth/using-auth.md +39 -0
- package/dist/skill/docs/stack/cms/actions.md +199 -0
- package/dist/skill/docs/stack/cms/components.md +479 -0
- package/dist/skill/docs/stack/cms/connecting.md +199 -0
- package/dist/skill/docs/stack/cms/dashboard.md +39 -0
- package/dist/skill/docs/stack/cms/index.md +158 -0
- package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
- package/dist/skill/docs/stack/cms/pages.md +275 -0
- package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
- package/dist/skill/docs/stack/cms/schema-format.md +437 -0
- package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
- package/dist/skill/docs/stack/cms/security.md +203 -0
- package/dist/skill/docs/stack/cms/table-views.md +142 -0
- package/dist/skill/docs/stack/index.md +65 -0
- package/dist/skill/docs/stack/queues/handlers.md +317 -0
- package/dist/skill/docs/stack/queues/index.md +56 -0
- package/dist/skill/docs/stack/queues/using-queues.md +192 -0
- package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/dist/skill/docs/stack/realtime/index.md +67 -0
- package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/dist/skill/docs/stack/storage/index.md +17 -0
- package/dist/skill/docs/stack/storage/kv.md +204 -0
- package/dist/skill/docs/stack/storage/r2.md +232 -0
- package/dist/skill/docs/stack/storage/using-kv.md +70 -0
- package/dist/skill/docs/stack/storage/using-r2.md +55 -0
- package/dist/skill/docs/stack/vector/embeddings.md +554 -0
- package/dist/skill/docs/stack/vector/index.md +44 -0
- package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
- package/dist/skill/docs/stack/webhooks/index.md +36 -0
- package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
- package/package.json +1 -1
- package/src/skill/SKILL.md +142 -1051
- package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
- package/src/skill/docs/changelog.md +1192 -0
- package/src/skill/docs/compiler/claude-code-skill.md +312 -0
- package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
- package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
- package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
- package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
- package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
- package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
- package/src/skill/docs/compiler/config/agents.md +144 -0
- package/src/skill/docs/compiler/config/auth.md +109 -0
- package/src/skill/docs/compiler/config/bindings.md +176 -0
- package/src/skill/docs/compiler/config/domains.md +149 -0
- package/src/skill/docs/compiler/config/index.md +419 -0
- package/src/skill/docs/compiler/config/output.md +338 -0
- package/src/skill/docs/compiler/config/providers.md +248 -0
- package/src/skill/docs/compiler/config/security.md +255 -0
- package/src/skill/docs/compiler/config/single-tenant.md +128 -0
- package/src/skill/docs/compiler/config/variables.md +157 -0
- package/src/skill/docs/compiler/definitions/access.md +445 -0
- package/src/skill/docs/compiler/definitions/actions.md +884 -0
- package/src/skill/docs/compiler/definitions/concepts.md +52 -0
- package/src/skill/docs/compiler/definitions/feature.md +164 -0
- package/src/skill/docs/compiler/definitions/firewall.md +285 -0
- package/src/skill/docs/compiler/definitions/guards.md +241 -0
- package/src/skill/docs/compiler/definitions/index.md +219 -0
- package/src/skill/docs/compiler/definitions/masking.md +241 -0
- package/src/skill/docs/compiler/definitions/read.md +220 -0
- package/src/skill/docs/compiler/definitions/schema.md +697 -0
- package/src/skill/docs/compiler/definitions/validation.md +35 -0
- package/src/skill/docs/compiler/definitions/views.md +292 -0
- package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
- package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
- package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
- package/src/skill/docs/compiler/getting-started/index.md +192 -0
- package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
- package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
- package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
- package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
- package/src/skill/docs/compiler/getting-started/templates.md +111 -0
- package/src/skill/docs/compiler/index.md +85 -0
- package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
- package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
- package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
- package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
- package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
- package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
- package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
- package/src/skill/docs/compiler/targets/index.md +47 -0
- package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
- package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
- package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
- package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
- package/src/skill/docs/compiler/troubleshooting.md +120 -0
- package/src/skill/docs/index.md +77 -0
- package/src/skill/docs/stack/account-ui/customization.md +378 -0
- package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
- package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
- package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
- package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
- package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
- package/src/skill/docs/stack/account-ui/features/index.md +291 -0
- package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
- package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
- package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
- package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
- package/src/skill/docs/stack/account-ui/hooks.md +209 -0
- package/src/skill/docs/stack/account-ui/index.md +147 -0
- package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
- package/src/skill/docs/stack/account-ui/standalone.md +149 -0
- package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
- package/src/skill/docs/stack/account-ui/worker.md +362 -0
- package/src/skill/docs/stack/auth/api-keys.md +15 -0
- package/src/skill/docs/stack/auth/device-auth.md +14 -0
- package/src/skill/docs/stack/auth/index.md +64 -0
- package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
- package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
- package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
- package/src/skill/docs/stack/auth/plugins/index.md +228 -0
- package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
- package/src/skill/docs/stack/auth/security.md +455 -0
- package/src/skill/docs/stack/auth/using-auth.md +39 -0
- package/src/skill/docs/stack/cms/actions.md +199 -0
- package/src/skill/docs/stack/cms/components.md +479 -0
- package/src/skill/docs/stack/cms/connecting.md +199 -0
- package/src/skill/docs/stack/cms/dashboard.md +39 -0
- package/src/skill/docs/stack/cms/index.md +158 -0
- package/src/skill/docs/stack/cms/inline-editing.md +136 -0
- package/src/skill/docs/stack/cms/pages.md +275 -0
- package/src/skill/docs/stack/cms/record-layouts.md +151 -0
- package/src/skill/docs/stack/cms/schema-format.md +437 -0
- package/src/skill/docs/stack/cms/schema-registry.md +200 -0
- package/src/skill/docs/stack/cms/security.md +203 -0
- package/src/skill/docs/stack/cms/table-views.md +142 -0
- package/src/skill/docs/stack/index.md +65 -0
- package/src/skill/docs/stack/queues/handlers.md +317 -0
- package/src/skill/docs/stack/queues/index.md +56 -0
- package/src/skill/docs/stack/queues/using-queues.md +192 -0
- package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
- package/src/skill/docs/stack/realtime/index.md +67 -0
- package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
- package/src/skill/docs/stack/storage/index.md +17 -0
- package/src/skill/docs/stack/storage/kv.md +204 -0
- package/src/skill/docs/stack/storage/r2.md +232 -0
- package/src/skill/docs/stack/storage/using-kv.md +70 -0
- package/src/skill/docs/stack/storage/using-r2.md +55 -0
- package/src/skill/docs/stack/vector/embeddings.md +554 -0
- package/src/skill/docs/stack/vector/index.md +44 -0
- package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
- package/src/skill/docs/stack/webhooks/inbound.md +186 -0
- package/src/skill/docs/stack/webhooks/index.md +36 -0
- package/src/skill/docs/stack/webhooks/outbound.md +281 -0
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
# Using Realtime
|
|
2
|
+
|
|
3
|
+
This page covers connecting to the Quickback realtime system from client applications — authentication, subscribing to events, and handling messages.
|
|
4
|
+
|
|
5
|
+
## Connecting
|
|
6
|
+
|
|
7
|
+
Open a WebSocket connection to the realtime worker:
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
const ws = new WebSocket("wss://api.yourdomain.com/realtime/v1/websocket");
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Authentication
|
|
14
|
+
|
|
15
|
+
Quickback uses **ticket-based authentication** for WebSocket connections. This is a two-step process:
|
|
16
|
+
|
|
17
|
+
1. **Get a ticket** — Call the ws-ticket endpoint with your session auth
|
|
18
|
+
2. **Connect with ticket** — Pass the ticket as a URL parameter when opening the WebSocket
|
|
19
|
+
|
|
20
|
+
This approach is faster and more secure than in-band auth messages — the connection is authenticated at upgrade time with no HTTP round-trip from the Durable Object.
|
|
21
|
+
|
|
22
|
+
### Step 1: Get a WebSocket Ticket
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
const response = await fetch("/realtime/v1/ws-ticket", {
|
|
26
|
+
method: "POST",
|
|
27
|
+
headers: {
|
|
28
|
+
Authorization: `Bearer ${sessionToken}`,
|
|
29
|
+
"Content-Type": "application/json",
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
const { wsTicket, expiresIn } = await response.json();
|
|
33
|
+
// expiresIn = 60 (seconds)
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The ticket is a short-lived (60-second) HMAC-signed token containing your userId, organizationId, and roles.
|
|
37
|
+
|
|
38
|
+
### Step 2: Connect with Ticket
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
const ws = new WebSocket(
|
|
42
|
+
`wss://api.yourdomain.com/realtime/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
|
|
43
|
+
);
|
|
44
|
+
|
|
45
|
+
ws.onopen = () => {
|
|
46
|
+
console.log("Connected and authenticated!");
|
|
47
|
+
// No auth message needed — connection is pre-authenticated
|
|
48
|
+
};
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
If the ticket is invalid or expired, the WebSocket upgrade is rejected with a 401 status.
|
|
52
|
+
|
|
53
|
+
## Handling Messages
|
|
54
|
+
|
|
55
|
+
### CRUD Events
|
|
56
|
+
|
|
57
|
+
CRUD events use the `postgres_changes` type:
|
|
58
|
+
|
|
59
|
+
```typescript
|
|
60
|
+
ws.onmessage = (event) => {
|
|
61
|
+
const msg = JSON.parse(event.data);
|
|
62
|
+
|
|
63
|
+
if (msg.type === "postgres_changes") {
|
|
64
|
+
const { table, eventType, new: newRecord, old: oldRecord } = msg;
|
|
65
|
+
|
|
66
|
+
switch (eventType) {
|
|
67
|
+
case "INSERT":
|
|
68
|
+
addRecord(table, newRecord);
|
|
69
|
+
break;
|
|
70
|
+
case "UPDATE":
|
|
71
|
+
updateRecord(table, newRecord);
|
|
72
|
+
break;
|
|
73
|
+
case "DELETE":
|
|
74
|
+
removeRecord(table, oldRecord.id);
|
|
75
|
+
break;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
};
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Event payload:**
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"type": "postgres_changes",
|
|
86
|
+
"table": "applications",
|
|
87
|
+
"schema": "public",
|
|
88
|
+
"eventType": "INSERT",
|
|
89
|
+
"new": { "id": "app_123", "candidateId": "cnd_456", "stage": "interview" },
|
|
90
|
+
"old": null
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
For UPDATE events, both `new` and `old` are populated. For DELETE events, only `old` is populated.
|
|
95
|
+
|
|
96
|
+
### Custom Broadcasts
|
|
97
|
+
|
|
98
|
+
Custom events use the `broadcast` type:
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
if (msg.type === "broadcast") {
|
|
102
|
+
const { event, payload } = msg;
|
|
103
|
+
|
|
104
|
+
if (event === "screening-complete") {
|
|
105
|
+
refreshApplication(payload.applicationId);
|
|
106
|
+
} else if (event === "screening:progress") {
|
|
107
|
+
updateProgressBar(payload.percent);
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**Event payload:**
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"type": "broadcast",
|
|
117
|
+
"event": "screening-complete",
|
|
118
|
+
"payload": {
|
|
119
|
+
"applicationId": "app_123",
|
|
120
|
+
"candidateId": "cnd_456",
|
|
121
|
+
"stage": "interview"
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Custom namespaces (from `defineRealtime()`) use the format `namespace:event` — e.g., `screening:started`, `screening:progress`.
|
|
127
|
+
|
|
128
|
+
## Security
|
|
129
|
+
|
|
130
|
+
### Role-Based Filtering
|
|
131
|
+
|
|
132
|
+
Events are only delivered to users whose role matches the broadcast's `targetRoles`. If a table's realtime config specifies `requiredRoles: ["hiring-manager", "recruiter"]`, only users with those roles receive the events.
|
|
133
|
+
|
|
134
|
+
### Per-Role Masking
|
|
135
|
+
|
|
136
|
+
Field values are masked according to the subscriber's role. For example, with this masking config:
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
masking: {
|
|
140
|
+
ssn: { type: "ssn", show: { roles: ["owner"] } },
|
|
141
|
+
}
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- **Owner sees:** `{ ssn: "123-45-6789" }`
|
|
145
|
+
- **Recruiter sees:** `{ ssn: "*****6789" }`
|
|
146
|
+
|
|
147
|
+
Masking is pre-computed per-role (O(roles), not O(subscribers)) for efficiency.
|
|
148
|
+
|
|
149
|
+
### User-Specific Events
|
|
150
|
+
|
|
151
|
+
Events can target a specific user within an organization. Only that user receives the broadcast — all other connections in the org are skipped.
|
|
152
|
+
|
|
153
|
+
### Organization Isolation
|
|
154
|
+
|
|
155
|
+
Each organization has its own Durable Object instance. Users can only subscribe to events in organizations they belong to, enforced during authentication.
|
|
156
|
+
|
|
157
|
+
## Reconnection
|
|
158
|
+
|
|
159
|
+
WebSocket connections can drop due to network issues. Implement reconnection logic in your client — note that you need to fetch a fresh ticket on each reconnect since tickets expire after 60 seconds:
|
|
160
|
+
|
|
161
|
+
```typescript
|
|
162
|
+
async function connect() {
|
|
163
|
+
// Get a fresh ticket each time
|
|
164
|
+
const res = await fetch("/realtime/v1/ws-ticket", {
|
|
165
|
+
method: "POST",
|
|
166
|
+
headers: { Authorization: `Bearer ${sessionToken}` },
|
|
167
|
+
});
|
|
168
|
+
const { wsTicket } = await res.json();
|
|
169
|
+
|
|
170
|
+
const ws = new WebSocket(
|
|
171
|
+
`wss://api.yourdomain.com/realtime/v1/websocket?ws_ticket=${wsTicket}&organizationId=${activeOrgId}`
|
|
172
|
+
);
|
|
173
|
+
|
|
174
|
+
ws.onclose = () => {
|
|
175
|
+
// Reconnect after delay
|
|
176
|
+
setTimeout(connect, 2000);
|
|
177
|
+
};
|
|
178
|
+
|
|
179
|
+
ws.onmessage = (event) => {
|
|
180
|
+
const msg = JSON.parse(event.data);
|
|
181
|
+
handleMessage(msg);
|
|
182
|
+
};
|
|
183
|
+
|
|
184
|
+
return ws;
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Environment
|
|
189
|
+
|
|
190
|
+
No additional environment variables are needed for realtime. The Broadcaster Durable Object runs inline in your main worker and reuses `BETTER_AUTH_SECRET` for WebSocket ticket signing.
|
|
191
|
+
|
|
192
|
+
The compiler generates the required `wrangler.toml` bindings automatically:
|
|
193
|
+
|
|
194
|
+
```toml
|
|
195
|
+
[[durable_objects.bindings]]
|
|
196
|
+
name = "BROADCASTER"
|
|
197
|
+
class_name = "Broadcaster"
|
|
198
|
+
|
|
199
|
+
[[migrations]]
|
|
200
|
+
tag = "v1"
|
|
201
|
+
new_classes = ["Broadcaster"]
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Cloudflare Only
|
|
205
|
+
|
|
206
|
+
Realtime requires Cloudflare Durable Objects and is only available with the Cloudflare runtime.
|
|
207
|
+
|
|
208
|
+
## See Also
|
|
209
|
+
|
|
210
|
+
- [Durable Objects Setup](/stack/realtime/durable-objects) — Configuration, event formats, masking, and custom namespaces
|
|
211
|
+
- [Masking](/compiler/definitions/masking) — Field masking configuration
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Storage
|
|
2
|
+
|
|
3
|
+
The Quickback Stack uses Cloudflare's storage primitives for different use cases.
|
|
4
|
+
|
|
5
|
+
## Storage Types
|
|
6
|
+
|
|
7
|
+
| Service | Use Case | Pages |
|
|
8
|
+
|---------|----------|-------|
|
|
9
|
+
| **KV** | Sessions, caching, rate limiting | [Setup](/stack/storage/kv) · [Usage](/stack/storage/using-kv) |
|
|
10
|
+
| **R2** | File uploads, avatars, attachments | [Setup](/stack/storage/r2) · [Usage](/stack/storage/using-r2) |
|
|
11
|
+
|
|
12
|
+
## Getting Started
|
|
13
|
+
|
|
14
|
+
- **[KV Setup](/stack/storage/kv)** — Namespace and bindings configuration
|
|
15
|
+
- **[Using KV](/stack/storage/using-kv)** — Sessions, caching, rate limiting
|
|
16
|
+
- **[R2 Setup](/stack/storage/r2)** — Bucket, bindings, CORS configuration
|
|
17
|
+
- **[Using R2](/stack/storage/using-r2)** — Uploads, downloads, role-based access
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
# KV Storage
|
|
2
|
+
|
|
3
|
+
Cloudflare Workers KV is a global key-value store optimized for read-heavy workloads. Quickback uses KV for session storage, caching, and fast lookups.
|
|
4
|
+
|
|
5
|
+
## What is KV?
|
|
6
|
+
|
|
7
|
+
Workers KV is a distributed key-value store:
|
|
8
|
+
|
|
9
|
+
- **Global distribution** - Data replicated to 300+ edge locations
|
|
10
|
+
- **Low-latency reads** - Cached at the edge, sub-millisecond access
|
|
11
|
+
- **Eventually consistent** - Writes propagate globally within 60 seconds
|
|
12
|
+
- **Simple API** - Get, put, delete, list
|
|
13
|
+
|
|
14
|
+
## Use Cases in Quickback
|
|
15
|
+
|
|
16
|
+
| Use Case | Description |
|
|
17
|
+
|----------|-------------|
|
|
18
|
+
| **Sessions** | Better Auth stores sessions in KV for fast validation |
|
|
19
|
+
| **Cache** | Cache expensive database queries or API responses |
|
|
20
|
+
| **Rate Limiting** | Track request counts per user/IP |
|
|
21
|
+
| **Feature Flags** | Store configuration that changes infrequently |
|
|
22
|
+
|
|
23
|
+
## Namespace Setup
|
|
24
|
+
|
|
25
|
+
Create a KV namespace via Wrangler:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# Create namespace
|
|
29
|
+
wrangler kv namespace create "KV"
|
|
30
|
+
|
|
31
|
+
# Output:
|
|
32
|
+
# Add the following to your wrangler.toml:
|
|
33
|
+
# [[kv_namespaces]]
|
|
34
|
+
# binding = "KV"
|
|
35
|
+
# id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Setting the namespace ID in config
|
|
39
|
+
|
|
40
|
+
To have the compiler generate `wrangler.toml` with your KV namespace ID, set it in your provider config:
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
providers: {
|
|
44
|
+
storage: defineStorage("kv", {
|
|
45
|
+
namespaceId: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
|
46
|
+
}),
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The `namespaceId` can also be set as `kvId` on the auth provider config, since KV is primarily used for auth session storage. The compiler checks both locations.
|
|
51
|
+
|
|
52
|
+
## Reading and Writing Values
|
|
53
|
+
|
|
54
|
+
### Basic Operations
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
// Write a value
|
|
58
|
+
await env.CACHE.put("user:123", JSON.stringify({ name: "Alice" }));
|
|
59
|
+
|
|
60
|
+
// Read a value
|
|
61
|
+
const data = await env.CACHE.get("user:123");
|
|
62
|
+
const user = data ? JSON.parse(data) : null;
|
|
63
|
+
|
|
64
|
+
// Delete a value
|
|
65
|
+
await env.CACHE.delete("user:123");
|
|
66
|
+
|
|
67
|
+
// Check if key exists
|
|
68
|
+
const exists = await env.CACHE.get("user:123") !== null;
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### With Metadata
|
|
72
|
+
|
|
73
|
+
KV supports metadata attached to keys:
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
// Write with metadata
|
|
77
|
+
await env.CACHE.put("user:123", JSON.stringify(userData), {
|
|
78
|
+
metadata: { updatedAt: Date.now(), version: 1 },
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
// Read with metadata
|
|
82
|
+
const { value, metadata } = await env.CACHE.getWithMetadata("user:123");
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### List Keys
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
// List all keys with prefix
|
|
89
|
+
const list = await env.CACHE.list({ prefix: "user:" });
|
|
90
|
+
|
|
91
|
+
for (const key of list.keys) {
|
|
92
|
+
console.log(key.name, key.metadata);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
// Paginate through results
|
|
96
|
+
let cursor = undefined;
|
|
97
|
+
do {
|
|
98
|
+
const result = await env.CACHE.list({ prefix: "user:", cursor });
|
|
99
|
+
// Process result.keys
|
|
100
|
+
cursor = result.cursor;
|
|
101
|
+
} while (cursor);
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Expiration and TTL
|
|
105
|
+
|
|
106
|
+
Set automatic expiration on keys:
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
// Expire in 1 hour (3600 seconds)
|
|
110
|
+
await env.CACHE.put("session:abc", sessionData, {
|
|
111
|
+
expirationTtl: 3600,
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
// Expire at specific timestamp
|
|
115
|
+
await env.CACHE.put("session:abc", sessionData, {
|
|
116
|
+
expiration: Math.floor(Date.now() / 1000) + 3600,
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Common TTL patterns:
|
|
121
|
+
|
|
122
|
+
| Use Case | TTL |
|
|
123
|
+
|----------|-----|
|
|
124
|
+
| Session tokens | 24 hours (86400) |
|
|
125
|
+
| API cache | 5 minutes (300) |
|
|
126
|
+
| Rate limit counters | 1 minute (60) |
|
|
127
|
+
| Feature flags | No expiration |
|
|
128
|
+
|
|
129
|
+
## Session Storage
|
|
130
|
+
|
|
131
|
+
Better Auth uses KV for session storage in Cloudflare deployments:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
// Quickback configures this automatically
|
|
135
|
+
auth: defineAuth("better-auth", {
|
|
136
|
+
session: {
|
|
137
|
+
storage: "kv", // Uses SESSIONS namespace
|
|
138
|
+
},
|
|
139
|
+
}),
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Sessions are stored as:
|
|
143
|
+
- Key: `session:{sessionId}`
|
|
144
|
+
- Value: Serialized session object
|
|
145
|
+
- TTL: Configured session expiration
|
|
146
|
+
|
|
147
|
+
## Caching Patterns
|
|
148
|
+
|
|
149
|
+
### Cache-Aside Pattern
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
async function getUser(userId: string) {
|
|
153
|
+
// Check cache first
|
|
154
|
+
const cached = await env.CACHE.get(`user:${userId}`);
|
|
155
|
+
if (cached) {
|
|
156
|
+
return JSON.parse(cached);
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
// Fetch from database
|
|
160
|
+
const user = await db.select().from(users).where(eq(users.id, userId));
|
|
161
|
+
|
|
162
|
+
// Store in cache
|
|
163
|
+
await env.CACHE.put(`user:${userId}`, JSON.stringify(user), {
|
|
164
|
+
expirationTtl: 300, // 5 minutes
|
|
165
|
+
});
|
|
166
|
+
|
|
167
|
+
return user;
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Cache Invalidation
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
// Invalidate on update
|
|
175
|
+
async function updateUser(userId: string, data: UserUpdate) {
|
|
176
|
+
await db.update(users).set(data).where(eq(users.id, userId));
|
|
177
|
+
await env.CACHE.delete(`user:${userId}`);
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## wrangler.toml Reference
|
|
182
|
+
|
|
183
|
+
```toml
|
|
184
|
+
# Production namespace
|
|
185
|
+
[[kv_namespaces]]
|
|
186
|
+
binding = "SESSIONS"
|
|
187
|
+
id = "abc123..."
|
|
188
|
+
|
|
189
|
+
# Preview namespace (for wrangler dev)
|
|
190
|
+
[[kv_namespaces]]
|
|
191
|
+
binding = "SESSIONS"
|
|
192
|
+
id = "def456..."
|
|
193
|
+
preview_id = "ghi789..."
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Limitations
|
|
197
|
+
|
|
198
|
+
- **Value size** - Maximum 25 MB per value
|
|
199
|
+
- **Key size** - Maximum 512 bytes
|
|
200
|
+
- **Write limits** - 1 write per second per key
|
|
201
|
+
- **Eventual consistency** - Changes may take up to 60 seconds to propagate
|
|
202
|
+
- **Not for hot writes** - Use Durable Objects for high-write scenarios
|
|
203
|
+
|
|
204
|
+
KV is optimized for read-heavy workloads. For write-heavy use cases or strong consistency, consider [Durable Objects](/stack/realtime/durable-objects).
|
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
# File Storage (R2)
|
|
2
|
+
|
|
3
|
+
Quickback provides built-in file storage using Cloudflare R2, with role-based access control and a dedicated files worker for serving.
|
|
4
|
+
|
|
5
|
+
## Architecture
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
9
|
+
│ Your Application │
|
|
10
|
+
│ │
|
|
11
|
+
│ Upload/Manage Files Serve Files │
|
|
12
|
+
│ ───────────────────── ────────────── │
|
|
13
|
+
│ api.yourdomain.com files.yourdomain.com │
|
|
14
|
+
│ /storage/v1/* /* │
|
|
15
|
+
│ │
|
|
16
|
+
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
|
17
|
+
│ │ API Worker │ │ Files Worker │ │
|
|
18
|
+
│ │ │ │ │ │
|
|
19
|
+
│ │ POST /bucket │ │ GET /public/* │ │
|
|
20
|
+
│ │ GET /bucket │ │ → No auth │ │
|
|
21
|
+
│ │ POST /object/* │ │ │ │
|
|
22
|
+
│ │ DELETE /object/* │ │ GET /* │ │
|
|
23
|
+
│ │ │ │ → Session + RBAC │ │
|
|
24
|
+
│ └──────────┬──────────┘ └──────────┬──────────┘ │
|
|
25
|
+
│ │ │ │
|
|
26
|
+
│ └───────────┬───────────────────┘ │
|
|
27
|
+
│ │ │
|
|
28
|
+
│ ▼ │
|
|
29
|
+
│ ┌─────────────────────┐ │
|
|
30
|
+
│ │ R2 Bucket │ │
|
|
31
|
+
│ │ quickback-files │ │
|
|
32
|
+
│ └─────────────────────┘ │
|
|
33
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Enabling File Storage
|
|
37
|
+
|
|
38
|
+
Add the `fileStorage` provider to your `quickback.config.ts`:
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
export default {
|
|
42
|
+
name: 'my-app',
|
|
43
|
+
providers: {
|
|
44
|
+
runtime: { name: 'cloudflare' },
|
|
45
|
+
database: { name: 'cloudflare-d1' },
|
|
46
|
+
auth: { name: 'better-auth' },
|
|
47
|
+
fileStorage: {
|
|
48
|
+
name: 'cloudflare-r2',
|
|
49
|
+
config: {
|
|
50
|
+
binding: 'R2_BUCKET',
|
|
51
|
+
bucketName: 'my-app-files',
|
|
52
|
+
filesBinding: 'FILES_DB',
|
|
53
|
+
maxFileSize: 10 * 1024 * 1024, // 10MB
|
|
54
|
+
allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
|
|
55
|
+
},
|
|
56
|
+
},
|
|
57
|
+
},
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## API Endpoints
|
|
62
|
+
|
|
63
|
+
### Storage API (api.yourdomain.com/storage/v1)
|
|
64
|
+
|
|
65
|
+
| Method | Endpoint | Description |
|
|
66
|
+
|--------|----------|-------------|
|
|
67
|
+
| POST | `/bucket` | Create a bucket |
|
|
68
|
+
| GET | `/bucket` | List buckets |
|
|
69
|
+
| GET | `/bucket/:name` | Get bucket info |
|
|
70
|
+
| DELETE | `/bucket/:name` | Delete bucket (must be empty) |
|
|
71
|
+
| POST | `/object/:bucket/*path` | Upload file |
|
|
72
|
+
| GET | `/object/:bucket/*path` | Download file |
|
|
73
|
+
| HEAD | `/object/:bucket/*path` | Get file metadata |
|
|
74
|
+
| DELETE | `/object/:bucket/*path` | Delete file (soft delete) |
|
|
75
|
+
| GET | `/object` | List objects |
|
|
76
|
+
| POST | `/url` | Get file URL for serving |
|
|
77
|
+
|
|
78
|
+
### Files Worker (files.yourdomain.com)
|
|
79
|
+
|
|
80
|
+
| Method | Path | Auth Required |
|
|
81
|
+
|--------|------|---------------|
|
|
82
|
+
| GET/HEAD | `/public/*` | No |
|
|
83
|
+
| GET/HEAD | `/*` | Yes (session + RBAC) |
|
|
84
|
+
|
|
85
|
+
## Buckets
|
|
86
|
+
|
|
87
|
+
Buckets organize files and define access control policies.
|
|
88
|
+
|
|
89
|
+
### Creating a Bucket
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
POST /storage/v1/bucket
|
|
93
|
+
{
|
|
94
|
+
"name": "avatars",
|
|
95
|
+
"readScope": "organization",
|
|
96
|
+
"writeScope": "organization",
|
|
97
|
+
"readRoles": ["admin", "member"],
|
|
98
|
+
"writeRoles": ["admin"],
|
|
99
|
+
"deleteRoles": ["admin"]
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Scope Options
|
|
104
|
+
|
|
105
|
+
| Scope | Read Behavior | Write Behavior |
|
|
106
|
+
|-------|---------------|----------------|
|
|
107
|
+
| `public` | Anyone can read | N/A |
|
|
108
|
+
| `organization` | Org members only | Org members only |
|
|
109
|
+
| `user` | Owner only | Owner only |
|
|
110
|
+
|
|
111
|
+
### Role-Based Access
|
|
112
|
+
|
|
113
|
+
You can restrict operations to specific roles:
|
|
114
|
+
|
|
115
|
+
```json
|
|
116
|
+
{
|
|
117
|
+
"readRoles": ["admin", "member"],
|
|
118
|
+
"writeRoles": ["admin", "editor"],
|
|
119
|
+
"deleteRoles": ["admin"]
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
An empty array `[]` means no role restriction (all authenticated users).
|
|
124
|
+
|
|
125
|
+
## Uploading Files
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
POST /storage/v1/object/avatars/profile.jpg
|
|
129
|
+
Content-Type: image/jpeg
|
|
130
|
+
Content-Length: 12345
|
|
131
|
+
|
|
132
|
+
<binary data>
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Response:
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"id": "obj_123",
|
|
139
|
+
"key": "org_abc/avatars/profile.jpg",
|
|
140
|
+
"bucket": "avatars",
|
|
141
|
+
"name": "profile.jpg",
|
|
142
|
+
"size": 12345,
|
|
143
|
+
"mimeType": "image/jpeg",
|
|
144
|
+
"readScope": "organization"
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Serving Files
|
|
149
|
+
|
|
150
|
+
### Public Files
|
|
151
|
+
|
|
152
|
+
Files in buckets with `readScope: "public"` are stored with a `public/` prefix:
|
|
153
|
+
|
|
154
|
+
```
|
|
155
|
+
https://files.yourdomain.com/public/org_abc/avatars/logo.png
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
No authentication required.
|
|
159
|
+
|
|
160
|
+
### Private Files
|
|
161
|
+
|
|
162
|
+
Private files require a valid Better Auth session cookie:
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
https://files.yourdomain.com/org_abc/documents/report.pdf
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
The files worker:
|
|
169
|
+
1. Validates the session token
|
|
170
|
+
2. Checks the user's organization matches
|
|
171
|
+
3. Verifies role permissions (if `readRoles` configured)
|
|
172
|
+
4. Serves the file or returns 403
|
|
173
|
+
|
|
174
|
+
## Generated Files
|
|
175
|
+
|
|
176
|
+
When file storage is configured, the compiler generates:
|
|
177
|
+
|
|
178
|
+
| File | Purpose |
|
|
179
|
+
|------|---------|
|
|
180
|
+
| `src/routes/storage.ts` | Storage API routes |
|
|
181
|
+
| `src/files.ts` | Files database schema (buckets, objects) |
|
|
182
|
+
| `cloudflare-workers/files/index.ts` | Files worker for serving |
|
|
183
|
+
| `cloudflare-workers/files/wrangler.toml` | Files worker config |
|
|
184
|
+
|
|
185
|
+
## Deployment
|
|
186
|
+
|
|
187
|
+
After compiling:
|
|
188
|
+
|
|
189
|
+
1. **Create the R2 bucket:**
|
|
190
|
+
```bash
|
|
191
|
+
wrangler r2 bucket create my-app-files
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
2. **Create the files database:**
|
|
195
|
+
```bash
|
|
196
|
+
wrangler d1 create my-app-files
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
3. **Run migrations:**
|
|
200
|
+
```bash
|
|
201
|
+
wrangler d1 migrations apply my-app-files --local
|
|
202
|
+
wrangler d1 migrations apply my-app-files --remote
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
4. **Deploy the API:**
|
|
206
|
+
```bash
|
|
207
|
+
wrangler deploy
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
5. **Deploy the files worker:**
|
|
211
|
+
```bash
|
|
212
|
+
cd cloudflare-workers/files
|
|
213
|
+
wrangler deploy
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Configuration Reference
|
|
217
|
+
|
|
218
|
+
| Option | Type | Default | Description |
|
|
219
|
+
|--------|------|---------|-------------|
|
|
220
|
+
| `binding` | `string` | `R2_BUCKET` | R2 bucket binding name |
|
|
221
|
+
| `bucketName` | `string` | Required | R2 bucket name |
|
|
222
|
+
| `filesBinding` | `string` | `FILES_DB` | Files metadata D1 binding |
|
|
223
|
+
| `maxFileSize` | `number` | 10MB | Max upload size in bytes |
|
|
224
|
+
| `allowedTypes` | `string[]` | Images only | Allowed MIME types |
|
|
225
|
+
| `publicDomain` | `string` | - | Custom domain for files worker |
|
|
226
|
+
|
|
227
|
+
## Security Model
|
|
228
|
+
|
|
229
|
+
- **Upload security**: Enforced by API worker (auth middleware, org check, role check)
|
|
230
|
+
- **Serve security**: Enforced by files worker (session validation, metadata RBAC)
|
|
231
|
+
- **Soft deletes**: Files are marked deleted in metadata but retained in R2
|
|
232
|
+
- **Tenant isolation**: All files are prefixed with organization ID
|