@quickback-dev/cli 0.66.17 → 0.66.18
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/build.d.ts.map +1 -1
- package/dist/commands/build.js +26 -20
- package/dist/commands/build.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/action-harvest.d.ts +3 -2
- package/dist/lib/action-harvest.d.ts.map +1 -1
- package/dist/lib/action-harvest.js +3 -2
- package/dist/lib/action-harvest.js.map +1 -1
- package/dist/lib/file-writer.d.ts +9 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js +30 -5
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/skill/docs/api/actions.md +10 -9
- package/dist/skill/docs/api/errors.md +14 -2
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +3 -3
- package/dist/skill/docs/configure/auth.md +8 -4
- package/dist/skill/docs/configure/index.md +1 -1
- package/dist/skill/docs/define/access.md +16 -6
- package/dist/skill/docs/define/actions/defining.md +8 -1
- package/dist/skill/docs/define/actions/scoped-db.md +69 -8
- package/dist/skill/docs/define/changesets.md +8 -3
- package/dist/skill/docs/define/encryption.md +6 -3
- package/dist/skill/docs/define/fga.md +9 -4
- package/dist/skill/docs/define/firewall.md +15 -7
- package/dist/skill/docs/define/masking.md +1 -1
- package/dist/skill/docs/define/relationships.md +6 -3
- package/dist/skill/docs/define/schema.md +27 -2
- package/dist/skill/docs/define/scopes.md +15 -1
- package/dist/skill/docs/define/transitions.md +5 -0
- package/dist/skill/docs/define/views.md +9 -0
- package/dist/skill/docs/platform/api-contract/index.md +4 -2
- package/dist/skill/docs/platform/auth/api-keys.md +10 -1
- package/dist/skill/docs/platform/auth/jwt-optimization.md +10 -4
- package/dist/skill/docs/platform/auth/plugins/aws-ses.md +11 -4
- package/dist/skill/docs/platform/auth/plugins/index.md +4 -2
- package/dist/skill/docs/platform/auth/plugins/subscriptions.md +3 -3
- package/dist/skill/docs/platform/push/index.md +31 -23
- package/dist/skill/docs/platform/storage/r2.md +36 -4
- package/dist/skill/docs/platform/vector/embeddings.md +11 -76
- package/dist/skill/docs/platform/vector/index.md +1 -1
- package/dist/skill/docs/platform/vector/using-embeddings.md +10 -73
- package/dist/skill/docs/platform/webhooks/outbound.md +12 -8
- package/dist/skill/docs/tooling/cli.md +2 -2
- package/dist/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +2 -1
- package/dist/skill/docs/tooling/cloud-compiler/index.md +18 -3
- package/dist/skill/docs/tooling/cloud-compiler/local-compiler.md +7 -4
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +1 -1
- package/dist/skill/docs/tooling/output.md +6 -2
- package/dist/skill/docs/ui/account/hooks.md +2 -2
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +10 -9
- package/src/skill/docs/api/errors.md +14 -2
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +3 -3
- package/src/skill/docs/configure/auth.md +8 -4
- package/src/skill/docs/configure/index.md +1 -1
- package/src/skill/docs/define/access.md +16 -6
- package/src/skill/docs/define/actions/defining.md +8 -1
- package/src/skill/docs/define/actions/scoped-db.md +69 -8
- package/src/skill/docs/define/changesets.md +8 -3
- package/src/skill/docs/define/encryption.md +6 -3
- package/src/skill/docs/define/fga.md +9 -4
- package/src/skill/docs/define/firewall.md +15 -7
- package/src/skill/docs/define/masking.md +1 -1
- package/src/skill/docs/define/relationships.md +6 -3
- package/src/skill/docs/define/schema.md +27 -2
- package/src/skill/docs/define/scopes.md +15 -1
- package/src/skill/docs/define/transitions.md +5 -0
- package/src/skill/docs/define/views.md +9 -0
- package/src/skill/docs/platform/api-contract/index.md +4 -2
- package/src/skill/docs/platform/auth/api-keys.md +10 -1
- package/src/skill/docs/platform/auth/jwt-optimization.md +10 -4
- package/src/skill/docs/platform/auth/plugins/aws-ses.md +11 -4
- package/src/skill/docs/platform/auth/plugins/index.md +4 -2
- package/src/skill/docs/platform/auth/plugins/subscriptions.md +3 -3
- package/src/skill/docs/platform/push/index.md +31 -23
- package/src/skill/docs/platform/storage/r2.md +36 -4
- package/src/skill/docs/platform/vector/embeddings.md +11 -76
- package/src/skill/docs/platform/vector/index.md +1 -1
- package/src/skill/docs/platform/vector/using-embeddings.md +10 -73
- package/src/skill/docs/platform/webhooks/outbound.md +12 -8
- package/src/skill/docs/tooling/cli.md +2 -2
- package/src/skill/docs/tooling/cloud-compiler/authentication.md +1 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +2 -1
- package/src/skill/docs/tooling/cloud-compiler/index.md +18 -3
- package/src/skill/docs/tooling/cloud-compiler/local-compiler.md +7 -4
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +1 -1
- package/src/skill/docs/tooling/output.md +6 -2
- package/src/skill/docs/ui/account/hooks.md +2 -2
|
@@ -100,82 +100,18 @@ onUpdate: ['description', 'title']
|
|
|
100
100
|
- The queue consumer is an internal process that executes pre-validated jobs
|
|
101
101
|
- If a user can't create a job posting, they can't trigger an embedding job
|
|
102
102
|
|
|
103
|
-
##
|
|
103
|
+
## Re-embedding a Row
|
|
104
104
|
|
|
105
|
-
|
|
105
|
+
There is no separate embeddings endpoint. To re-embed a row, **PATCH it**: the
|
|
106
|
+
generated `PATCH /api/v1/<resource>/:id` (and `PATCH /batch`) enqueues a fresh job
|
|
107
|
+
after the write passes auth, firewall, and guards. With `onUpdate: [...fields]`,
|
|
108
|
+
the PATCH must include one of the watched fields — resending the current value is
|
|
109
|
+
enough; with the default `onUpdate`, any PATCH re-embeds. The job always uses the
|
|
110
|
+
table's configured `model` and `embeddingColumn`; clients never choose either.
|
|
106
111
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
curl -X POST https://your-api.workers.dev/api/v1/embeddings \
|
|
113
|
-
-H "Content-Type: application/json" \
|
|
114
|
-
-H "Cookie: better-auth.session_token=..." \
|
|
115
|
-
-d '{
|
|
116
|
-
"content": "Text to embed",
|
|
117
|
-
"model": "@cf/baai/bge-base-en-v1.5",
|
|
118
|
-
"table": "jobs",
|
|
119
|
-
"id": "job_123"
|
|
120
|
-
}'
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
#### Request Body
|
|
124
|
-
|
|
125
|
-
| Field | Type | Required | Description |
|
|
126
|
-
|-------|------|----------|-------------|
|
|
127
|
-
| `content` | `string` | Yes | Text to generate embedding for |
|
|
128
|
-
| `model` | `string` | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
|
|
129
|
-
| `table` | `string` | No | Table to store embedding back to |
|
|
130
|
-
| `id` | `string` | Conditional | Record ID to update (required if `table` is specified) |
|
|
131
|
-
|
|
132
|
-
#### Response
|
|
133
|
-
|
|
134
|
-
```json
|
|
135
|
-
{
|
|
136
|
-
"queued": true,
|
|
137
|
-
"jobId": "550e8400-e29b-41d4-a716-446655440000",
|
|
138
|
-
"table": "jobs",
|
|
139
|
-
"id": "job_123",
|
|
140
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
141
|
-
}
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
### GET /api/v1/embeddings/tables
|
|
145
|
-
|
|
146
|
-
List tables that have embeddings configured:
|
|
147
|
-
|
|
148
|
-
```bash
|
|
149
|
-
curl https://your-api.workers.dev/api/v1/embeddings/tables \
|
|
150
|
-
-H "Cookie: better-auth.session_token=..."
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
Response:
|
|
154
|
-
|
|
155
|
-
```json
|
|
156
|
-
{
|
|
157
|
-
"tables": [
|
|
158
|
-
{
|
|
159
|
-
"name": "jobs",
|
|
160
|
-
"embeddingColumn": "embedding",
|
|
161
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
162
|
-
}
|
|
163
|
-
]
|
|
164
|
-
}
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
### Authentication & Authorization
|
|
168
|
-
|
|
169
|
-
The generic embeddings API requires authentication and uses the `activeOrgId` from the user's context to enforce organization-level isolation. Embedding jobs are scoped to the user's current organization.
|
|
170
|
-
|
|
171
|
-
### Use Cases
|
|
172
|
-
|
|
173
|
-
The generic embeddings API is useful for:
|
|
174
|
-
|
|
175
|
-
- **Batch embedding**: Embed content without going through CRUD routes
|
|
176
|
-
- **Re-embedding**: Force re-generation of embeddings for existing records
|
|
177
|
-
- **Preview embeddings**: Test embedding generation before persisting
|
|
178
|
-
- **External content**: Embed content that doesn't fit your defined schemas
|
|
112
|
+
For content that doesn't live in a table (previews, external text), call the
|
|
113
|
+
search service's [`embed()`](/platform/vector/embeddings#generate-embeddings-directly)
|
|
114
|
+
from an action — it runs under that action's own access rules.
|
|
179
115
|
|
|
180
116
|
## Generated Files
|
|
181
117
|
|
|
@@ -184,10 +120,9 @@ When embeddings are configured, the compiler generates:
|
|
|
184
120
|
| File | Purpose |
|
|
185
121
|
|------|---------|
|
|
186
122
|
| `src/queue-consumer.ts` | Queue consumer handler for processing embedding jobs |
|
|
187
|
-
| `src/routes/embeddings.ts` | Generic embeddings API routes |
|
|
188
123
|
| `wrangler.toml` | Queue producer/consumer bindings, AI binding |
|
|
189
124
|
| `src/env.d.ts` | `EMBEDDINGS_QUEUE`, `AI` types |
|
|
190
|
-
| `src/index.ts` | Exports `queue` handler
|
|
125
|
+
| `src/index.ts` | Exports the `queue` handler |
|
|
191
126
|
|
|
192
127
|
### wrangler.toml additions
|
|
193
128
|
|
|
@@ -41,4 +41,4 @@ The default embedding model is `@cf/baai/bge-base-en-v1.5` (768 dimensions). You
|
|
|
41
41
|
## Pages
|
|
42
42
|
|
|
43
43
|
- **[Automatic Embeddings](/platform/vector/embeddings)** — `defineTable()` embeddings config, queue consumer, Vectorize integration, and `defineEmbedding()` search service
|
|
44
|
-
- **[Using Embeddings](/platform/vector/using-embeddings)** —
|
|
44
|
+
- **[Using Embeddings](/platform/vector/using-embeddings)** — Re-embedding rows, semantic search, and practical usage
|
|
@@ -1,76 +1,14 @@
|
|
|
1
1
|
# Using Embeddings
|
|
2
2
|
|
|
3
|
-
This page covers the runtime API for working with embeddings —
|
|
3
|
+
This page covers the runtime API for working with embeddings — re-embedding rows, the search service, and practical usage patterns.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Re-embedding Rows
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
POST /api/v1/embeddings
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Enqueue an embedding job for arbitrary content:
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
curl -X POST https://api.example.com/api/v1/embeddings \
|
|
19
|
-
-H "Content-Type: application/json" \
|
|
20
|
-
-H "Cookie: better-auth.session_token=..." \
|
|
21
|
-
-d '{
|
|
22
|
-
"content": "Text to generate an embedding for",
|
|
23
|
-
"model": "@cf/baai/bge-base-en-v1.5",
|
|
24
|
-
"table": "jobs",
|
|
25
|
-
"id": "job_123"
|
|
26
|
-
}'
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
**Request body:**
|
|
30
|
-
|
|
31
|
-
| Field | Type | Required | Description |
|
|
32
|
-
|-------|------|----------|-------------|
|
|
33
|
-
| `content` | string | Yes | Text to embed |
|
|
34
|
-
| `model` | string | No | Embedding model (defaults to table config or `@cf/baai/bge-base-en-v1.5`) |
|
|
35
|
-
| `table` | string | No | Table to store the embedding in |
|
|
36
|
-
| `id` | string | Conditional | Record ID (required when `table` is provided) |
|
|
37
|
-
|
|
38
|
-
**Response:**
|
|
39
|
-
|
|
40
|
-
```json
|
|
41
|
-
{
|
|
42
|
-
"queued": true,
|
|
43
|
-
"jobId": "550e8400-e29b-41d4-a716-446655440000",
|
|
44
|
-
"table": "jobs",
|
|
45
|
-
"id": "job_123",
|
|
46
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
47
|
-
}
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
This endpoint is useful for:
|
|
51
|
-
- Re-embedding existing records
|
|
52
|
-
- Embedding content that doesn't go through CRUD routes
|
|
53
|
-
- Batch embedding via scripts
|
|
54
|
-
|
|
55
|
-
### List Embedding Tables
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
GET /api/v1/embeddings/tables
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
List tables that have embeddings configured:
|
|
62
|
-
|
|
63
|
-
```json
|
|
64
|
-
{
|
|
65
|
-
"tables": [
|
|
66
|
-
{
|
|
67
|
-
"name": "jobs",
|
|
68
|
-
"embeddingColumn": "embedding",
|
|
69
|
-
"model": "@cf/baai/bge-base-en-v1.5"
|
|
70
|
-
}
|
|
71
|
-
]
|
|
72
|
-
}
|
|
73
|
-
```
|
|
7
|
+
Embeddings have no endpoint of their own. Rows are embedded on INSERT and
|
|
8
|
+
re-embedded on UPDATE by the generated CRUD routes, after auth, firewall, and
|
|
9
|
+
guards pass — so **PATCH the row to re-embed** (with `onUpdate: [...fields]`,
|
|
10
|
+
include a watched field; resending its current value is enough). The job uses the
|
|
11
|
+
table's configured `model` and `embeddingColumn`.
|
|
74
12
|
|
|
75
13
|
## Search Service
|
|
76
14
|
|
|
@@ -162,14 +100,13 @@ The `metadata` fields in your `defineTable` embeddings config are automatically
|
|
|
162
100
|
|---------|-----|----------|
|
|
163
101
|
| Auto (INSERT) | Compiler enqueues after successful create | Default behavior |
|
|
164
102
|
| Auto (UPDATE) | Compiler enqueues when watched fields change | Keeps embeddings fresh |
|
|
165
|
-
|
|
|
103
|
+
| Re-embed | `PATCH` the row (or `PATCH /batch`) | Re-embedding existing records |
|
|
166
104
|
| Manual (Queue) | `env.EMBEDDINGS_QUEUE.send(...)` | Custom pipelines |
|
|
167
105
|
|
|
168
106
|
## Security
|
|
169
107
|
|
|
170
|
-
-
|
|
171
|
-
- Jobs are scoped to the
|
|
172
|
-
- Embedding jobs are only enqueued after all security checks pass (auth, firewall, guards)
|
|
108
|
+
- Embedding jobs are only enqueued by the generated write routes, after all security checks pass (auth, firewall, guards) — there is no client-facing embeddings endpoint
|
|
109
|
+
- Jobs are scoped to the writer's `activeOrgId`
|
|
173
110
|
- The queue consumer is an internal process — it trusts pre-validated jobs
|
|
174
111
|
|
|
175
112
|
## Supported Models
|
|
@@ -22,12 +22,16 @@ import { emitWebhookEvent } from '../lib/webhooks/emit';
|
|
|
22
22
|
// After creating a user
|
|
23
23
|
const newUser = await db.insert(users).values(data).returning();
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
25
|
+
// ctx.activeOrgId is `string | undefined` — narrow it first. Passing it
|
|
26
|
+
// unguarded is a type error, and an unscoped emit throws at runtime.
|
|
27
|
+
if (ctx.activeOrgId) {
|
|
28
|
+
await emitWebhookEvent(
|
|
29
|
+
"user.created",
|
|
30
|
+
newUser[0],
|
|
31
|
+
{ organizationId: ctx.activeOrgId },
|
|
32
|
+
env
|
|
33
|
+
);
|
|
34
|
+
}
|
|
31
35
|
```
|
|
32
36
|
|
|
33
37
|
**Parameters:**
|
|
@@ -36,7 +40,7 @@ await emitWebhookEvent(
|
|
|
36
40
|
|-----------|------|-------------|
|
|
37
41
|
| `eventType` | `string` | Event name (e.g., `user.created`) |
|
|
38
42
|
| `payload` | `unknown` | Event data (auto-wrapped with metadata) |
|
|
39
|
-
| `options` | `
|
|
43
|
+
| `options` | `{ organizationId: string } \| { userId: string }` | **Required.** Exactly one scope — only endpoints registered to that org or user receive the event. Neither or both throws. |
|
|
40
44
|
| `env` | `CloudflareBindings` | Cloudflare environment bindings |
|
|
41
45
|
|
|
42
46
|
**Note:** The compiler does NOT auto-emit events after CRUD operations. You must call `emitWebhookEvent()` explicitly where you want webhooks triggered.
|
|
@@ -166,7 +170,7 @@ Endpoints subscribe to events using patterns:
|
|
|
166
170
|
|
|
167
171
|
### Access Control
|
|
168
172
|
|
|
169
|
-
Endpoints are scoped by `userId` or `organizationId`. Users can only manage their own endpoints. When emitting events, only endpoints matching the event's scope receive deliveries.
|
|
173
|
+
Endpoints are scoped by `userId` or `organizationId`. Users can only manage their own endpoints. When emitting events, only endpoints matching the event's scope receive deliveries. Every emit must name exactly one scope: an unscoped emit (`{}`, or an `organizationId` that is `undefined` at runtime) throws instead of reaching every tenant's endpoints — there is no global broadcast.
|
|
170
174
|
|
|
171
175
|
### URL Validation (anti-SSRF)
|
|
172
176
|
|
|
@@ -102,7 +102,7 @@ Every file under `src/` carries a `Generated by quickback.dev` header and is own
|
|
|
102
102
|
|
|
103
103
|
1. Snapshots the existing `src/` tree to `quickback/.archives/src-<ISO-timestamp>/` (a plain recursive copy — `cp -R` semantics, no compression).
|
|
104
104
|
2. Wipes `src/` entirely.
|
|
105
|
-
3. Writes the fresh manifest from the compiler.
|
|
105
|
+
3. Writes the fresh manifest from the compiler. Every path is checked first: an absolute path, a `.` / `..` segment, or anything resolving outside the output directory fails the build before a single file is written — the CLI never trusts the compiler's response to stay inside your project.
|
|
106
106
|
|
|
107
107
|
This prevents stale output: removed features stop leaving orphan folders, deleted SPA assets with old content hashes get cleared, and `.DS_Store` files don't keep retired directories alive.
|
|
108
108
|
|
|
@@ -376,7 +376,7 @@ The CLI parses your feature files with the TypeScript compiler API, and falls ba
|
|
|
376
376
|
|
|
377
377
|
`typescript` is an optional peer dependency, supported at **`>=5.0.0 <7`** — both 5.x and 6.x expose the classic compiler API. TypeScript 7 (the native port) resolves its main entry to a module exporting only `version` — parsing moved to the explicitly-unstable `typescript/unstable/*` subpaths — so it cannot drive the AST parser, and the CLI says so by name rather than degrading quietly.
|
|
378
378
|
|
|
379
|
-
Compiled projects pin
|
|
379
|
+
Compiled projects pin `typescript` to 6.x for exactly this reason: `quickback build` runs schema sync before every compile, and a project on TypeScript 7 cannot build. Don't bump it to 7 by hand.
|
|
380
380
|
|
|
381
381
|
Set `QUICKBACK_STRICT_PARSE=1` in CI so a regex-parsed build fails the pipeline instead of shipping:
|
|
382
382
|
|
|
@@ -28,7 +28,7 @@ The API key takes precedence over stored credentials from `quickback login`.
|
|
|
28
28
|
|
|
29
29
|
## How Tokens Are Validated
|
|
30
30
|
|
|
31
|
-
The compiler-cloud worker validates authentication by forwarding your
|
|
31
|
+
The compiler-cloud worker validates authentication by forwarding your credentials to the Quickback API's Better Auth `GET /auth/v1/get-session` endpoint via a [Cloudflare service binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/). This resolves both session tokens (from `quickback login`) and API keys (from `QUICKBACK_API_KEY`, sent as `x-api-key` — `get-session` is the only Better Auth endpoint that accepts a key in place of a session).
|
|
32
32
|
|
|
33
33
|
## Credential Storage
|
|
34
34
|
|
|
@@ -35,9 +35,10 @@ The `/compile` endpoint requires either a session token (from `quickback login`)
|
|
|
35
35
|
|
|
36
36
|
The map uses project-root-relative paths and follows the same layout `quickback build` reads from disk: `quickback/quickback.config.ts`, `quickback/features/**`, `quickback/services/**`, `quickback/{lib,hooks,plugins,middlewares,email-templates}/**`, plus `quickback/drizzle/**/meta/**` and `wrangler.toml` for incremental builds.
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
Three constraints, all fail-closed:
|
|
39
39
|
|
|
40
40
|
- **The config must be fully static.** The compiler parses `quickback.config.ts` with a literals-only evaluator — it never executes user code. Object/array/string/number/boolean literals, substitution-free template literals, and the `define*` helper calls all work; variables, computed values, and imports-as-values are rejected with a 400 that names the offending construct and line.
|
|
41
|
+
- **Table files must be declarative.** Everything above `export default defineTable(...)` is checked before it reaches the generated schema that migration tooling loads — only `drizzle-orm` / `@quickback/compiler` / table-file imports and inert expressions pass ([rules](/define/schema#table-files-are-declarative)); anything else fails the compile naming the file and line.
|
|
41
42
|
- **Action input schemas are contract-sensitive.** For v1, raw-files requests may omit `actionInputSchemas` and use the compiler's lower-fidelity static parser. V2 requires one usable client-harvested `z.toJSONSchema(action.input)` entry for every authored action. The CLI reports each missing action with its local bundle or evaluation error; the API independently reports missing or invalid action keys.
|
|
42
43
|
|
|
43
44
|
Raw-files requests work with both `?complete=true` and `?complete=false`
|
|
@@ -51,9 +51,24 @@ without changing their definitions or generated output.
|
|
|
51
51
|
|
|
52
52
|
## Processing, analytics, and AI use
|
|
53
53
|
|
|
54
|
-
- Compile payloads are processed for the request. Full compiles use
|
|
55
|
-
temporary work directory that is deleted in a `finally` cleanup
|
|
56
|
-
failure; validation compiles run in memory.
|
|
54
|
+
- Compile payloads are processed for the request. Full compiles use a
|
|
55
|
+
per-request temporary work directory that is deleted in a `finally` cleanup
|
|
56
|
+
on success or failure; validation compiles run in memory.
|
|
57
|
+
- Compiles share a warm container, so the compiler limits what project source
|
|
58
|
+
can execute at all: table files must be
|
|
59
|
+
[declarative](/define/schema#table-files-are-declarative), Better Auth schema
|
|
60
|
+
generation does not load your auth hooks, email templates, or project-local
|
|
61
|
+
custom plugins, `existingFiles` may carry only migration state
|
|
62
|
+
(`quickback/drizzle/**/*.sql|json` and `wrangler.toml`), and a project file
|
|
63
|
+
(`quickback/lib/`, hooks, plugins) that lands on a generated path or under
|
|
64
|
+
`node_modules` fails the compile.
|
|
65
|
+
- The tools a full compile runs (drizzle-kit, the Better Auth CLI, wrangler's
|
|
66
|
+
dry-run bundle) run as a fresh operating-system user for each compile, with
|
|
67
|
+
no capabilities, and never reused. That user owns only its own work
|
|
68
|
+
directory (mode `0700`) while its command runs. It cannot read another
|
|
69
|
+
compile's directory, the compiler server's environment or memory, or write
|
|
70
|
+
anything a later compile loads. The hosted container has no outbound network
|
|
71
|
+
access.
|
|
57
72
|
- Quickback does not retain request source or generated output as a project
|
|
58
73
|
artifact on the compiler service.
|
|
59
74
|
- The hosted edge records operational analytics: user/organization identifiers,
|
|
@@ -84,12 +84,15 @@ curl http://localhost:3000/health
|
|
|
84
84
|
|
|
85
85
|
The Docker image includes:
|
|
86
86
|
- Pre-installed dependencies for compiled projects (`/deps/node_modules`)
|
|
87
|
-
- CMS and Account SPA
|
|
88
|
-
- Pre-installed SPA dependencies (`/spa-deps/cms/`, `/spa-deps/account/`)
|
|
87
|
+
- Generic prebuilt CMS and Account SPA bundles (`/spa-prebuilt/cms/`, `/spa-prebuilt/account/`), built once at image build
|
|
89
88
|
|
|
90
|
-
When compiling a project with `cms: true` or `account: true`, the compiler
|
|
89
|
+
When compiling a project with `cms: true` or `account: true`, the compiler copies those prebuilt bundles into the project's `src/apps/` — it never runs Vite per compile. The generated worker injects the per-project values (API URLs, feature flags) into every served SPA shell as `window.__QUICKBACK_RUNTIME`, and the SPAs read that runtime blob, so one generic bundle serves every project.
|
|
91
90
|
|
|
92
|
-
|
|
91
|
+
### Security boundary
|
|
92
|
+
|
|
93
|
+
- **Loopback only.** Local mode skips authentication, so the launcher publishes the port on `127.0.0.1` only.
|
|
94
|
+
- **No browser-driven compiles.** In local mode, a request carrying an `Origin` header whose hostname is not `localhost`, `127.0.0.1`, or `[::1]` gets `403` — checked before CORS, so a web page you visit cannot POST a compile to your machine. The CLI and `curl` send no `Origin` and are unaffected.
|
|
95
|
+
- **Unprivileged user.** The server runs as the image's `bun` user (uid 1000). `/app`, `/deps`, and `/spa-prebuilt` are root-owned and not writable by it, and each compile works in its own `0700` directory under `/tmp/quickback`, so code that runs during one compile cannot plant files a later compile loads.
|
|
93
96
|
|
|
94
97
|
## Deploying to Cloud
|
|
95
98
|
|
|
@@ -11,7 +11,7 @@ quickback login
|
|
|
11
11
|
|
|
12
12
|
## Compilation timeout
|
|
13
13
|
|
|
14
|
-
Large projects may take longer to compile. The cloud compiler
|
|
14
|
+
Large projects may take longer to compile. The cloud compiler runs in [Cloudflare Containers](https://developers.cloudflare.com/containers/). If you hit timeouts, try [running the compiler locally](/tooling/cloud-compiler/local-compiler).
|
|
15
15
|
|
|
16
16
|
## Compiler stays on loading
|
|
17
17
|
|
|
@@ -32,6 +32,9 @@ src/
|
|
|
32
32
|
│ └── {feature}.ts # Mount re-export consumed by src/index.ts
|
|
33
33
|
├── lib/
|
|
34
34
|
│ ├── auth.ts # Better Auth instance & config
|
|
35
|
+
│ ├── auth.schema-gen.ts # Copy of auth.ts with hooks/email templates stubbed — what `better-auth generate` reads
|
|
36
|
+
│ ├── firewall-registry.ts # Table → generated firewall builder for the action `db` (when used)
|
|
37
|
+
│ ├── scoped-db.ts # The action `db` — applies each table's firewall (when used)
|
|
35
38
|
│ ├── access.ts # Access control helpers
|
|
36
39
|
│ ├── types.ts # Runtime type definitions
|
|
37
40
|
│ ├── masks.ts # Field masking utilities
|
|
@@ -281,11 +284,12 @@ When any feature has `embeddings` configured:
|
|
|
281
284
|
src/
|
|
282
285
|
├── lib/
|
|
283
286
|
│ └── embeddings.ts # Embedding helpers
|
|
284
|
-
├── routes/
|
|
285
|
-
│ └── embeddings.ts # POST /api/{v1|v2}/embeddings endpoint
|
|
286
287
|
└── queue-consumer.ts # Queue handler for async embedding jobs
|
|
287
288
|
```
|
|
288
289
|
|
|
290
|
+
There is no embeddings route: jobs are enqueued only by the generated write
|
|
291
|
+
routes, after auth, firewall, and guards pass.
|
|
292
|
+
|
|
289
293
|
### File Storage (R2)
|
|
290
294
|
|
|
291
295
|
When `fileStorage` is configured, presign-only mode emits just the signer:
|
|
@@ -236,7 +236,7 @@ make project and Better Auth tables explicit.
|
|
|
236
236
|
|
|
237
237
|
## Writing hooks: use built-ins where possible
|
|
238
238
|
|
|
239
|
-
|
|
239
|
+
Hooks run in the deployed Worker, never at compile time: Better Auth schema generation reads `src/lib/auth.schema-gen.ts`, a copy of `src/lib/auth.ts` with every auth hook and email template replaced by an inert stub. The generated `package.json` does not pick up a hook's imports, though, so a hook that imports `@paralleldrive/cuid2`, `nanoid`, or any other third-party package is undeclared: it fails to resolve when the Worker is bundled (and the local `auth:schema` script, which still loads `src/lib/auth.ts`) with a "module not found" error.
|
|
240
240
|
|
|
241
241
|
Stick to runtime built-ins for ID generation, hashing, and similar primitives:
|
|
242
242
|
|
|
@@ -247,7 +247,7 @@ Stick to runtime built-ins for ID generation, hashing, and similar primitives:
|
|
|
247
247
|
| Random bytes | `crypto.getRandomValues(new Uint8Array(n))` |
|
|
248
248
|
| Time | `Date.now()`, `new Date().toISOString()` |
|
|
249
249
|
|
|
250
|
-
`drizzle-orm` is
|
|
250
|
+
`drizzle-orm` is always a dependency of the generated project, so `eq`, `and`, `inArray`, etc. are safe to import.
|
|
251
251
|
|
|
252
252
|
## Throw semantics
|
|
253
253
|
|