@quickback-dev/cli 0.72.9 → 0.72.10
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 +8 -1
- package/dist/commands/build.js.map +1 -1
- package/dist/commands/db-explain.d.ts +67 -0
- package/dist/commands/db-explain.d.ts.map +1 -0
- package/dist/commands/db-explain.js +141 -0
- package/dist/commands/db-explain.js.map +1 -0
- package/dist/commands/db-export.d.ts +34 -0
- package/dist/commands/db-export.d.ts.map +1 -0
- package/dist/commands/db-export.js +250 -0
- package/dist/commands/db-export.js.map +1 -0
- package/dist/commands/db-insights.d.ts +60 -0
- package/dist/commands/db-insights.d.ts.map +1 -0
- package/dist/commands/db-insights.js +106 -0
- package/dist/commands/db-insights.js.map +1 -0
- package/dist/commands/db-recovery.d.ts +98 -0
- package/dist/commands/db-recovery.d.ts.map +1 -0
- package/dist/commands/db-recovery.js +558 -0
- package/dist/commands/db-recovery.js.map +1 -0
- package/dist/commands/db-target.d.ts +27 -0
- package/dist/commands/db-target.d.ts.map +1 -0
- package/dist/commands/db-target.js +83 -0
- package/dist/commands/db-target.js.map +1 -0
- package/dist/commands/db.d.ts +3 -0
- package/dist/commands/db.d.ts.map +1 -0
- package/dist/commands/db.js +43 -0
- package/dist/commands/db.js.map +1 -0
- package/dist/commands/effects.d.ts +8 -0
- package/dist/commands/effects.d.ts.map +1 -0
- package/dist/commands/effects.js +48 -0
- package/dist/commands/effects.js.map +1 -0
- package/dist/commands/platform-budget.d.ts +143 -0
- package/dist/commands/platform-budget.d.ts.map +1 -0
- package/dist/commands/platform-budget.js +619 -0
- package/dist/commands/platform-budget.js.map +1 -0
- package/dist/commands/preview.d.ts +57 -0
- package/dist/commands/preview.d.ts.map +1 -0
- package/dist/commands/preview.js +268 -0
- package/dist/commands/preview.js.map +1 -0
- package/dist/commands/search.d.ts +20 -0
- package/dist/commands/search.d.ts.map +1 -0
- package/dist/commands/search.js +133 -0
- package/dist/commands/search.js.map +1 -0
- package/dist/index.js +35 -1
- package/dist/index.js.map +1 -1
- package/dist/lib/api-client.d.ts +4 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/cloudflare-spend-policies.d.ts +92 -0
- package/dist/lib/cloudflare-spend-policies.d.ts.map +1 -0
- package/dist/lib/cloudflare-spend-policies.js +289 -0
- package/dist/lib/cloudflare-spend-policies.js.map +1 -0
- package/dist/lib/compiler-stubs.d.ts +2 -0
- package/dist/lib/compiler-stubs.d.ts.map +1 -1
- package/dist/lib/compiler-stubs.js +2 -0
- package/dist/lib/compiler-stubs.js.map +1 -1
- package/dist/lib/d1-fingerprint.d.ts +8 -0
- package/dist/lib/d1-fingerprint.d.ts.map +1 -0
- package/dist/lib/d1-fingerprint.js +113 -0
- package/dist/lib/d1-fingerprint.js.map +1 -0
- package/dist/lib/file-loader.d.ts +12 -0
- package/dist/lib/file-loader.d.ts.map +1 -1
- package/dist/lib/file-loader.js +27 -1
- package/dist/lib/file-loader.js.map +1 -1
- package/dist/lib/migrations/plan.js +3 -0
- package/dist/lib/migrations/plan.js.map +1 -1
- package/dist/lib/migrations/postprocessors/index.d.ts +6 -5
- package/dist/lib/migrations/postprocessors/index.d.ts.map +1 -1
- package/dist/lib/migrations/postprocessors/index.js +24 -12
- package/dist/lib/migrations/postprocessors/index.js.map +1 -1
- package/dist/lib/migrations/postprocessors/search.d.ts +49 -0
- package/dist/lib/migrations/postprocessors/search.d.ts.map +1 -0
- package/dist/lib/migrations/postprocessors/search.js +160 -0
- package/dist/lib/migrations/postprocessors/search.js.map +1 -0
- package/dist/lib/migrations/prior-state.d.ts +7 -0
- package/dist/lib/migrations/prior-state.d.ts.map +1 -1
- package/dist/lib/migrations/prior-state.js +3 -0
- package/dist/lib/migrations/prior-state.js.map +1 -1
- package/dist/lib/migrations/types.d.ts +1 -1
- package/dist/lib/migrations/types.d.ts.map +1 -1
- package/dist/lib/migrations/types.js +1 -0
- package/dist/lib/migrations/types.js.map +1 -1
- package/dist/lib/preview-lifecycle.d.ts +139 -0
- package/dist/lib/preview-lifecycle.d.ts.map +1 -0
- package/dist/lib/preview-lifecycle.js +429 -0
- package/dist/lib/preview-lifecycle.js.map +1 -0
- package/dist/lib/preview.d.ts +146 -0
- package/dist/lib/preview.d.ts.map +1 -0
- package/dist/lib/preview.js +417 -0
- package/dist/lib/preview.js.map +1 -0
- package/dist/lib/wrangler-resources.d.ts.map +1 -1
- package/dist/lib/wrangler-resources.js +4 -2
- package/dist/lib/wrangler-resources.js.map +1 -1
- package/dist/skill/SKILL.md +9 -3
- package/dist/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/dist/skill/docs/api/batch-operations.md +19 -0
- package/dist/skill/docs/api/caching.md +17 -0
- package/dist/skill/docs/api/crud.md +9 -0
- package/dist/skill/docs/api/errors.md +31 -2
- package/dist/skill/docs/api/query-params.md +6 -0
- package/dist/skill/docs/changelog/index.md +1 -0
- package/dist/skill/docs/configure/agents.md +1 -1
- package/dist/skill/docs/configure/bindings.md +177 -1
- package/dist/skill/docs/configure/cloudflare-access.md +43 -0
- package/dist/skill/docs/configure/domains.md +1 -1
- package/dist/skill/docs/configure/providers.md +5 -0
- package/dist/skill/docs/configure/tenant-databases.md +627 -14
- package/dist/skill/docs/define/access.md +26 -0
- package/dist/skill/docs/define/actions/defining.md +7 -1
- package/dist/skill/docs/define/actions/index.md +5 -0
- package/dist/skill/docs/define/actions/scoped-db.md +127 -1
- package/dist/skill/docs/define/authoring-basics.md +92 -0
- package/dist/skill/docs/define/changesets.md +8 -0
- package/dist/skill/docs/define/encryption.md +48 -2
- package/dist/skill/docs/define/feature.md +17 -2
- package/dist/skill/docs/define/guards.md +11 -3
- package/dist/skill/docs/define/index.md +1 -1
- package/dist/skill/docs/define/invariants.md +321 -0
- package/dist/skill/docs/define/issue-tracker-example.md +225 -0
- package/dist/skill/docs/define/masking.md +3 -3
- package/dist/skill/docs/define/rate-limit.md +63 -22
- package/dist/skill/docs/define/read.md +332 -5
- package/dist/skill/docs/define/relationships.md +10 -0
- package/dist/skill/docs/define/schema.md +137 -10
- package/dist/skill/docs/define/scopes.md +1 -0
- package/dist/skill/docs/define/transitions.md +9 -0
- package/dist/skill/docs/define/triggers.md +127 -1
- package/dist/skill/docs/platform/api-contract/index.md +35 -4
- package/dist/skill/docs/platform/auth/api-keys.md +26 -3
- package/dist/skill/docs/platform/auth/index.md +5 -2
- package/dist/skill/docs/platform/auth/plugins/index.md +1 -1
- package/dist/skill/docs/platform/database/d1.md +73 -1
- package/dist/skill/docs/platform/database/durable-effects.md +224 -0
- package/dist/skill/docs/platform/database/read-replication.md +9 -0
- package/dist/skill/docs/platform/database/recovery.md +292 -0
- package/dist/skill/docs/platform/database/using-d1.md +152 -2
- package/dist/skill/docs/platform/index.md +1 -0
- package/dist/skill/docs/platform/operations/budgets.md +224 -0
- package/dist/skill/docs/platform/queues/handlers.md +1 -0
- package/dist/skill/docs/platform/queues/index.md +18 -0
- package/dist/skill/docs/platform/realtime/table-changes.md +1 -0
- package/dist/skill/docs/platform/storage/using-r2.md +13 -0
- package/dist/skill/docs/platform/vector/embeddings.md +28 -4
- package/dist/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/dist/skill/docs/platform/workflows/index.md +385 -0
- package/dist/skill/docs/start/deploy-browser.md +51 -0
- package/dist/skill/docs/start/deploy.md +97 -1
- package/dist/skill/docs/tooling/cli.md +117 -0
- package/dist/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/dist/skill/docs/ui/account/customization.md +4 -0
- package/dist/skill/docs/ui/admin/record-layouts.md +3 -3
- package/package.json +1 -1
- package/src/skill/SKILL.md +9 -3
- package/src/skill/agents/quickback-specialist/AGENT.md +9 -11
- package/src/skill/docs/api/batch-operations.md +19 -0
- package/src/skill/docs/api/caching.md +17 -0
- package/src/skill/docs/api/crud.md +9 -0
- package/src/skill/docs/api/errors.md +31 -2
- package/src/skill/docs/api/query-params.md +6 -0
- package/src/skill/docs/changelog/index.md +1 -0
- package/src/skill/docs/configure/agents.md +1 -1
- package/src/skill/docs/configure/bindings.md +177 -1
- package/src/skill/docs/configure/cloudflare-access.md +43 -0
- package/src/skill/docs/configure/domains.md +1 -1
- package/src/skill/docs/configure/providers.md +5 -0
- package/src/skill/docs/configure/tenant-databases.md +627 -14
- package/src/skill/docs/define/access.md +26 -0
- package/src/skill/docs/define/actions/defining.md +7 -1
- package/src/skill/docs/define/actions/index.md +5 -0
- package/src/skill/docs/define/actions/scoped-db.md +127 -1
- package/src/skill/docs/define/authoring-basics.md +92 -0
- package/src/skill/docs/define/changesets.md +8 -0
- package/src/skill/docs/define/encryption.md +48 -2
- package/src/skill/docs/define/feature.md +17 -2
- package/src/skill/docs/define/guards.md +11 -3
- package/src/skill/docs/define/index.md +1 -1
- package/src/skill/docs/define/invariants.md +321 -0
- package/src/skill/docs/define/issue-tracker-example.md +225 -0
- package/src/skill/docs/define/masking.md +3 -3
- package/src/skill/docs/define/rate-limit.md +63 -22
- package/src/skill/docs/define/read.md +332 -5
- package/src/skill/docs/define/relationships.md +10 -0
- package/src/skill/docs/define/schema.md +137 -10
- package/src/skill/docs/define/scopes.md +1 -0
- package/src/skill/docs/define/transitions.md +9 -0
- package/src/skill/docs/define/triggers.md +127 -1
- package/src/skill/docs/platform/api-contract/index.md +35 -4
- package/src/skill/docs/platform/auth/api-keys.md +26 -3
- package/src/skill/docs/platform/auth/index.md +5 -2
- package/src/skill/docs/platform/auth/plugins/index.md +1 -1
- package/src/skill/docs/platform/database/d1.md +73 -1
- package/src/skill/docs/platform/database/durable-effects.md +224 -0
- package/src/skill/docs/platform/database/read-replication.md +9 -0
- package/src/skill/docs/platform/database/recovery.md +292 -0
- package/src/skill/docs/platform/database/using-d1.md +152 -2
- package/src/skill/docs/platform/index.md +1 -0
- package/src/skill/docs/platform/operations/budgets.md +224 -0
- package/src/skill/docs/platform/queues/handlers.md +1 -0
- package/src/skill/docs/platform/queues/index.md +18 -0
- package/src/skill/docs/platform/realtime/table-changes.md +1 -0
- package/src/skill/docs/platform/storage/using-r2.md +13 -0
- package/src/skill/docs/platform/vector/embeddings.md +28 -4
- package/src/skill/docs/platform/vector/using-embeddings.md +17 -0
- package/src/skill/docs/platform/workflows/index.md +385 -0
- package/src/skill/docs/start/deploy-browser.md +51 -0
- package/src/skill/docs/start/deploy.md +97 -1
- package/src/skill/docs/tooling/cli.md +117 -0
- package/src/skill/docs/tooling/cloud-compiler/index.md +15 -0
- package/src/skill/docs/ui/account/customization.md +4 -0
- package/src/skill/docs/ui/admin/record-layouts.md +3 -3
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
# Workflows
|
|
2
|
+
|
|
3
|
+
A workflow is a persisted sequence of steps that can sleep for days, wait for
|
|
4
|
+
an approval, and resume after a failure without re-running completed work.
|
|
5
|
+
Quickback compiles each `defineWorkflow` version into a native
|
|
6
|
+
[Cloudflare Workflow](https://developers.cloudflare.com/workflows/) and adds
|
|
7
|
+
four things around it:
|
|
8
|
+
|
|
9
|
+
- **Durable starts and events.** A start, event or control is a row in the run
|
|
10
|
+
registry written in the **same D1 batch** as its
|
|
11
|
+
[durable effect](/platform/database/durable-effects) intent. It exists if
|
|
12
|
+
and only if its dispatch does.
|
|
13
|
+
- **Current authority.** Before **every** step attempt, the initiating actor
|
|
14
|
+
is reloaded from the auth database. A workflow never keeps acting with a
|
|
15
|
+
role the actor has since lost.
|
|
16
|
+
- **Authorized controls.** Start, status, events, cancel, pause, resume and
|
|
17
|
+
retry routes check the caller's current role and the run's owner on every
|
|
18
|
+
call.
|
|
19
|
+
- **Version pinning.** Each version is its own native Workflow. A run finishes
|
|
20
|
+
on the version it started on.
|
|
21
|
+
|
|
22
|
+
A workflow orchestrates work across resources. It is **not** a distributed SQL
|
|
23
|
+
transaction, and it does not make external side effects happen exactly once.
|
|
24
|
+
|
|
25
|
+
## Enable
|
|
26
|
+
|
|
27
|
+
Workflows need:
|
|
28
|
+
|
|
29
|
+
| Requirement | Why |
|
|
30
|
+
|---|---|
|
|
31
|
+
| Cloudflare runtime | Native Cloudflare Workflows run the steps. |
|
|
32
|
+
| `cloudflare-d1` features database | The run registry and event inbox commit with their intents in one native batch. |
|
|
33
|
+
| [`durableEffects: { enabled: true }`](/platform/database/durable-effects) and a queue | Starts, events and controls are durable intents. |
|
|
34
|
+
| Better Auth `organization` plugin | Every run belongs to an organization actor. |
|
|
35
|
+
|
|
36
|
+
With more than one queue, name the one that carries workflow intents:
|
|
37
|
+
|
|
38
|
+
{/* doc-compile: skip — config fragment; the full defineConfig wrapper is shown in /configure. */}
|
|
39
|
+
```typescript
|
|
40
|
+
database: defineDatabase("cloudflare-d1", {
|
|
41
|
+
additionalQueues: [
|
|
42
|
+
{ name: "my-app-jobs", binding: "JOBS_QUEUE" },
|
|
43
|
+
{ name: "my-app-mail", binding: "MAIL_QUEUE" },
|
|
44
|
+
],
|
|
45
|
+
durableEffects: { enabled: true, workflowQueue: "JOBS_QUEUE" },
|
|
46
|
+
}),
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The compiler refuses each missing requirement. There is no degraded mode.
|
|
50
|
+
|
|
51
|
+
## Define a workflow
|
|
52
|
+
|
|
53
|
+
Put one definition per file under `quickback/services/workflows/`:
|
|
54
|
+
|
|
55
|
+
{/* doc-compile: skip — needs an accounts feature */}
|
|
56
|
+
```ts title="quickback/services/workflows/onboarding-v1.ts"
|
|
57
|
+
import { z } from "zod";
|
|
58
|
+
import { eq } from "drizzle-orm";
|
|
59
|
+
import { defineWorkflow } from "@quickback/compiler";
|
|
60
|
+
import { accounts } from "../../features/accounts/accounts";
|
|
61
|
+
|
|
62
|
+
export default defineWorkflow({
|
|
63
|
+
name: "onboarding",
|
|
64
|
+
version: 1,
|
|
65
|
+
input: z.object({ accountId: z.string() }),
|
|
66
|
+
result: z.object({ activated: z.boolean() }),
|
|
67
|
+
events: { approval: z.object({ approved: z.boolean() }) },
|
|
68
|
+
access: {
|
|
69
|
+
start: { roles: ["admin"] },
|
|
70
|
+
read: { roles: ["admin", "member"], scope: "organization" },
|
|
71
|
+
},
|
|
72
|
+
run: async ({ input, step }) => {
|
|
73
|
+
await step.run("prepare", async ({ db }) => {
|
|
74
|
+
await db.update(accounts).set({ status: "provisioning" }).where(eq(accounts.id, input.accountId));
|
|
75
|
+
});
|
|
76
|
+
const approval = await step.wait("approval", { timeout: "7 days" });
|
|
77
|
+
await step.run("activate", async ({ db, idempotencyKey }) => {
|
|
78
|
+
await db.update(accounts).set({ status: approval.approved ? "active" : "rejected" }).where(eq(accounts.id, input.accountId));
|
|
79
|
+
// Pass idempotencyKey to external APIs: it is stable across retries.
|
|
80
|
+
});
|
|
81
|
+
return { activated: approval.approved };
|
|
82
|
+
},
|
|
83
|
+
});
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Everything that becomes a persisted identity is a literal the compiler checks:
|
|
87
|
+
the `name` (camelCase), the `version` (a positive integer), event names and step
|
|
88
|
+
names. Files starting with `_` are helpers. Any other file in that directory
|
|
89
|
+
must call `defineWorkflow`.
|
|
90
|
+
|
|
91
|
+
| Field | Meaning |
|
|
92
|
+
|---|---|
|
|
93
|
+
| `name`, `version` | Required. Each `(name, version)` is defined once. |
|
|
94
|
+
| `input`, `result` | Zod schemas. Starts are validated against `input`. The return value is validated against `result` before it is stored. |
|
|
95
|
+
| `events` | Zod schema per event name. |
|
|
96
|
+
| `access` | Required. See [Routes and access](#routes-and-access). |
|
|
97
|
+
| `retired` | `true` stops new starts on this version. In-flight runs finish on it. |
|
|
98
|
+
| `retention` | How long a finished run's registry row and result are kept (default `"30 days"`, 1 hour to 365 days). |
|
|
99
|
+
| `authority` | Only `{ mode: "actor" }`, the default. See [Authority](#authority). |
|
|
100
|
+
|
|
101
|
+
## Steps
|
|
102
|
+
|
|
103
|
+
`run` receives `{ input, step, runId }`. It must destructure its parameter, and
|
|
104
|
+
`step` may only be called directly. Passing, storing or destructuring `step` is
|
|
105
|
+
a compile error, because steps are recorded only through those calls.
|
|
106
|
+
|
|
107
|
+
| Call | Does |
|
|
108
|
+
|---|---|
|
|
109
|
+
| `step.run(name, fn, options?)` | A persisted, side-effecting step. A completed step replays its stored result and never runs again. |
|
|
110
|
+
| `step.sleep(name, duration)` / `step.sleepUntil(name, at)` | A durable sleep. Durations look like `"30 seconds"` or `"7 days"`, or are milliseconds. |
|
|
111
|
+
| `step.wait(event, { key?, timeout? })` | Waits for a declared event and returns its validated payload. |
|
|
112
|
+
| `step.job(name, target, message)` | Calls a tenant [result job](/configure/tenant-databases#result-jobs) in an organization or partition object. |
|
|
113
|
+
|
|
114
|
+
Step names are unique within a version. Repeated work, such as a loop or a
|
|
115
|
+
`map` callback, needs a stable item key: `step.run("charge", fn, { key: invoiceId })`.
|
|
116
|
+
A `run` or `wait` inside a loop without a `key` is a compile error.
|
|
117
|
+
|
|
118
|
+
`fn` receives **fresh handles for each attempt**. Nothing persists between
|
|
119
|
+
attempts except the step's JSON result:
|
|
120
|
+
|
|
121
|
+
| Handle | Is |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `db` | A scoped database for the actor, built exactly like an action's: the same firewall, audit stamps and atomic [`db.batch`](/define/actions/scoped-db#atomic-d1-batches-and-concurrency), including `effects`. |
|
|
124
|
+
| `ctx` | `{ authMethod: "workflow", userId, activeOrgId, roles, orgRole, userRole, workflowRunId }`, reloaded for this attempt. |
|
|
125
|
+
| `env`, `services` | The Worker bindings and services. |
|
|
126
|
+
| `idempotencyKey` | `<runId>:run:<name>[#key]`, stable across attempts. |
|
|
127
|
+
| `attempt` | The 1-based attempt number. |
|
|
128
|
+
|
|
129
|
+
A step's result must be JSON and at most 128 KiB. `undefined` comes back as
|
|
130
|
+
`undefined`.
|
|
131
|
+
|
|
132
|
+
### Retries and timeouts
|
|
133
|
+
|
|
134
|
+
Native Workflows retries are the **only** retry layer for steps. Quickback adds
|
|
135
|
+
no retry loop of its own.
|
|
136
|
+
|
|
137
|
+
| Option | Default | Bounds |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| `retries.limit` | `3` | 0–10 |
|
|
140
|
+
| `retries.delay` | `"10 seconds"` | 1 second – 1 hour |
|
|
141
|
+
| `retries.backoff` | `"exponential"` | `constant`, `linear`, `exponential` |
|
|
142
|
+
| `timeout` | `"5 minutes"` | 1 second – 30 minutes |
|
|
143
|
+
|
|
144
|
+
A step can run more than once: after a crash, a timeout, or a lost
|
|
145
|
+
acknowledgement. Make writes idempotent, and pass `idempotencyKey` to external
|
|
146
|
+
APIs. An external request that was already running when a run was cancelled or
|
|
147
|
+
blocked may still complete.
|
|
148
|
+
|
|
149
|
+
## Authority
|
|
150
|
+
|
|
151
|
+
A run stores its **actor**: the user ID and the organization of the caller who
|
|
152
|
+
started it. It stores no token, session, role snapshot or database handle.
|
|
153
|
+
|
|
154
|
+
Before **every** attempt of a `run` or `job` step, the engine:
|
|
155
|
+
|
|
156
|
+
1. checks the run is still runnable. A cancelled run, or one being cancelled, stops here;
|
|
157
|
+
2. reloads the user. The user must exist and not be banned;
|
|
158
|
+
3. reloads the user's membership in the run's organization;
|
|
159
|
+
4. expands the membership role through `auth.roleHierarchy`, the same way a request does;
|
|
160
|
+
5. evaluates `access.execute.roles` (default: `access.start.roles`) with the project's access evaluator.
|
|
161
|
+
|
|
162
|
+
If any check fails, the run becomes **`blocked`** with error `AUTHORITY_REVOKED`,
|
|
163
|
+
and the step does not run. The block is durable and does not retry. The run
|
|
164
|
+
never continues as a system identity or as anyone else. A run that loses
|
|
165
|
+
authority while sleeping or waiting blocks at its next `run` or `job` step.
|
|
166
|
+
Sleeps and waits have no side effects, so they are not checked.
|
|
167
|
+
|
|
168
|
+
[Retry](#controls) resumes a blocked run only when the **original** actor holds
|
|
169
|
+
the execute roles again.
|
|
170
|
+
|
|
171
|
+
Subscription tier roles (`tier_*`) are not re-resolved for steps. A rule that
|
|
172
|
+
names one fails closed. Service authority (`authority: { mode: "service" }`, a
|
|
173
|
+
named, revocable service grant) is not supported yet and is a compile error.
|
|
174
|
+
|
|
175
|
+
## Routes and access
|
|
176
|
+
|
|
177
|
+
Routes live under the API prefix:
|
|
178
|
+
|
|
179
|
+
| Route | Operation | Response |
|
|
180
|
+
|---|---|---|
|
|
181
|
+
| `POST /api/v1/workflows/<name>/runs` | `start` | `202` + run status. Needs `Idempotency-Key`. |
|
|
182
|
+
| `GET /api/v1/workflows/<name>/runs/<runId>` | `read` | `200` + run status. |
|
|
183
|
+
| `POST …/runs/<runId>/events/<event>` | `signal` | `202`. `Idempotency-Key` is the event ID. |
|
|
184
|
+
| `POST …/runs/<runId>/cancel` | `cancel` | `202` + status. |
|
|
185
|
+
| `POST …/runs/<runId>/pause` · `resume` · `retry` | `control` | `202` + status. |
|
|
186
|
+
|
|
187
|
+
Each `access` rule is `{ roles, scope? }`. `start` is required. `read`, `signal`
|
|
188
|
+
and `cancel` default to `start`, and `control` defaults to `cancel`. `PUBLIC` is
|
|
189
|
+
not allowed.
|
|
190
|
+
|
|
191
|
+
| `scope` | Who can act on a run |
|
|
192
|
+
|---|---|
|
|
193
|
+
| `"actor"` (default) | Only the run's actor, while holding the roles. |
|
|
194
|
+
| `"organization"` | Any member of the run's organization holding the roles. |
|
|
195
|
+
|
|
196
|
+
Every call reloads the caller's membership from the auth database. A cached JWT
|
|
197
|
+
role is not enough. Only a signed-in user with an active organization can call
|
|
198
|
+
these routes. Delegated principals, scope-only principals and share links get
|
|
199
|
+
`403 WORKFLOW_ACTOR_REQUIRED`. A caller without the operation's role on any
|
|
200
|
+
version gets `403`. A run in another organization, a run owned by another actor
|
|
201
|
+
under `"actor"` scope, or an unknown run ID all return the same `404`. Knowing
|
|
202
|
+
a run ID grants nothing.
|
|
203
|
+
|
|
204
|
+
The routes are listed in the generated [OpenAPI](/api/openapi) spec under the
|
|
205
|
+
`Workflows` tag.
|
|
206
|
+
|
|
207
|
+
## Durable starts and events
|
|
208
|
+
|
|
209
|
+
**Start.** The route validates the input and derives an opaque run ID from the
|
|
210
|
+
project, workflow, organization, actor and `Idempotency-Key`. In **one** D1
|
|
211
|
+
batch it writes the registry row and a `qb.workflow.start` intent. The
|
|
212
|
+
[global idempotency layer](/platform/api-contract#idempotency-key) replays a repeated request with
|
|
213
|
+
the same key. A key reused with a different input is refused.
|
|
214
|
+
|
|
215
|
+
**Dispatch.** The generated queue consumer admits the intent, like every
|
|
216
|
+
durable effect, then creates the native instance **with the run ID as its
|
|
217
|
+
instance ID**. If an earlier create succeeded but its reply was lost, the
|
|
218
|
+
dispatcher finds the instance and does not create a second one. If the Worker
|
|
219
|
+
dies after the commit and before dispatch, the effects sweep delivers the
|
|
220
|
+
intent later.
|
|
221
|
+
|
|
222
|
+
**Events** go to the run's **inbox**: one row per `(runId, eventId)`, written in
|
|
223
|
+
the same batch as a `qb.workflow.event` intent. The native `sendEvent` is only a
|
|
224
|
+
wakeup. A wait first claims the oldest pending matching event from the inbox,
|
|
225
|
+
so an event sent before the run reaches its wait is not lost. Unknown events
|
|
226
|
+
(`400 WORKFLOW_EVENT_UNKNOWN`), invalid payloads, payloads over 64 KiB, events
|
|
227
|
+
for a finished run (`409 WORKFLOW_TERMINAL`) and more than 1,000 unconsumed
|
|
228
|
+
events (`429 WORKFLOW_INBOX_FULL`) are refused.
|
|
229
|
+
|
|
230
|
+
`Idempotency-Key` values are scoped to the caller across the whole API. Use a
|
|
231
|
+
fresh key for every start and every event.
|
|
232
|
+
|
|
233
|
+
## Status and errors
|
|
234
|
+
|
|
235
|
+
Status responses contain registry facts only:
|
|
236
|
+
`{ runId, workflow, version, status, createdAt, updatedAt, result?, error? }`.
|
|
237
|
+
They never include the persisted input or native internals.
|
|
238
|
+
|
|
239
|
+
| Status | Meaning |
|
|
240
|
+
|---|---|
|
|
241
|
+
| `starting` | Recorded. The native instance may not exist yet. |
|
|
242
|
+
| `running` | The instance exists. |
|
|
243
|
+
| `paused` | Paused on request. |
|
|
244
|
+
| `blocked` | Stopped for review. See `error.code`. |
|
|
245
|
+
| `cancelling` → `cancelled` | Cancellation recorded, then the native instance terminated. |
|
|
246
|
+
| `completed` | Finished. `result` is the validated return value, at most 64 KiB. |
|
|
247
|
+
| `failed` | A step exhausted its retries, a wait timed out, or validation failed. |
|
|
248
|
+
|
|
249
|
+
`error.code` is a stored code: an error's `code` property, or its message when
|
|
250
|
+
that looks like a code (`CARD_DECLINED`). Anything else becomes
|
|
251
|
+
`WORKFLOW_FAILED`, so error messages with user data are never stored.
|
|
252
|
+
|
|
253
|
+
| Code | Status | Cause |
|
|
254
|
+
|---|---|---|
|
|
255
|
+
| `AUTHORITY_REVOKED` | `blocked` | The actor lost the execute roles or the membership. |
|
|
256
|
+
| `VERSION_MISMATCH` / `VERSION_UNAVAILABLE` | `blocked` | The run's version is not the code or binding asked to run it. |
|
|
257
|
+
| `TENANT_*` | `blocked` | A tenant object is permanently unavailable to a `step.job`: purged, archived, restore pending or not provisioned. |
|
|
258
|
+
| `WORKFLOW_RESULT_TOO_LARGE`, `WORKFLOW_STEP_OUTPUT_TOO_LARGE` | `failed` | Size limits. |
|
|
259
|
+
|
|
260
|
+
## Controls
|
|
261
|
+
|
|
262
|
+
- **Cancel** records `cancelling` and a revision fence **before** it asks the
|
|
263
|
+
platform to terminate the instance. Every new step checks the fence. A step
|
|
264
|
+
already in flight may finish, so the status stays `cancelling` until the
|
|
265
|
+
dispatcher records `cancelled`. Nothing is compensated automatically. Write
|
|
266
|
+
explicit, idempotent cleanup steps when you need them.
|
|
267
|
+
- **Pause** and **resume** apply to `running` and `paused` runs. You can call
|
|
268
|
+
them back to back: each records its status at once, and the dispatcher drives
|
|
269
|
+
the native instance to the latest recorded status, so a pause still in flight
|
|
270
|
+
never undoes the resume that followed it. A paused run keeps its completed
|
|
271
|
+
steps; resume continues from where it stopped.
|
|
272
|
+
- **Retry** applies to `blocked` and `failed` runs. It restarts the native
|
|
273
|
+
instance **from the step that blocked or failed**. Earlier completed steps keep
|
|
274
|
+
their results and do not run again. A run that did not stop at a step, such
|
|
275
|
+
as a version mismatch or a failed result validation, returns
|
|
276
|
+
`409 WORKFLOW_NOT_RETRYABLE`: a restart from the beginning would run completed
|
|
277
|
+
steps again. Start a new run instead.
|
|
278
|
+
|
|
279
|
+
Each control increments the run's revision in the same batch as its intent. The
|
|
280
|
+
dispatcher applies only the latest revision, so a stale or duplicate control
|
|
281
|
+
does nothing.
|
|
282
|
+
|
|
283
|
+
## Versions
|
|
284
|
+
|
|
285
|
+
Versions are immutable. `onboarding` version 2 is a new file with
|
|
286
|
+
`version: 2`. Each version compiles to its own class, binding and native
|
|
287
|
+
Workflow: `QbWorkflowOnboardingV2`, `QB_WF_ONBOARDING_V2` and
|
|
288
|
+
`<app>-onboarding-v2`. New starts use the highest version that is not retired.
|
|
289
|
+
A run always executes the version recorded in its registry row.
|
|
290
|
+
|
|
291
|
+
Immutable is your contract, not the platform's. Cloudflare does not pin a
|
|
292
|
+
native instance to the Worker deployment it started on. If you edit a deployed
|
|
293
|
+
version's file in place and deploy, its in-flight runs execute the edited code
|
|
294
|
+
from their next step: a sleeping or waiting run wakes on the new deployment.
|
|
295
|
+
An invocation already running may finish on the old code for a short grace
|
|
296
|
+
period first, so one run can mix both. To change steps, add a new version.
|
|
297
|
+
|
|
298
|
+
To retire a version:
|
|
299
|
+
|
|
300
|
+
1. Set `retired: true` on it and deploy. It accepts no new starts.
|
|
301
|
+
2. Wait until no run references it:
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
wrangler d1 execute <features-db> --remote --command \
|
|
305
|
+
"SELECT count(*) FROM _quickback_workflow_runs WHERE workflow = 'onboarding' AND version = 1 AND status NOT IN ('completed','failed','cancelled')"
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
3. Delete the file.
|
|
309
|
+
|
|
310
|
+
The compiler reads the deployed `wrangler.toml` and refuses to remove a
|
|
311
|
+
version that was deployed without `retired: true`
|
|
312
|
+
(`WORKFLOW_VERSION_REMOVED`). It cannot see the registry, so step 2 is yours to
|
|
313
|
+
check. A run whose version binding is gone is marked `blocked`
|
|
314
|
+
(`VERSION_UNAVAILABLE`). It never runs on another version.
|
|
315
|
+
|
|
316
|
+
## Tenant and partition steps
|
|
317
|
+
|
|
318
|
+
`step.job` calls a tenant [result job](/configure/tenant-databases#result-jobs)
|
|
319
|
+
using the partition-job destination contract
|
|
320
|
+
([Partition jobs](/configure/tenant-databases#partition-jobs)):
|
|
321
|
+
|
|
322
|
+
{/* doc-compile: skip — needs a tenant result job */}
|
|
323
|
+
```ts
|
|
324
|
+
const summary = await step.job("summarize", {
|
|
325
|
+
kind: "partition", organizationId: input.organizationId, partition: "conversation", key: input.conversationId,
|
|
326
|
+
}, { type: "conversation.summary" });
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
The step first passes the authority check. `target.organizationId` must be the
|
|
330
|
+
run's organization. The job's run ID is `wf:<runId>:job:<name>`, so a retried
|
|
331
|
+
step replays the job's recorded result in that same object. A purged, archived,
|
|
332
|
+
restore-pending or unprovisioned object blocks the run instead of retrying. The
|
|
333
|
+
edge's registry fences apply to workflows exactly as they apply to everything
|
|
334
|
+
else. `step.job` needs `tenancy.isolation: 'durable-object'`.
|
|
335
|
+
|
|
336
|
+
## Named environments
|
|
337
|
+
|
|
338
|
+
Wrangler does not inherit Workflows into environments. Each
|
|
339
|
+
[environment](/configure/domains#named-environments) target declares its own native
|
|
340
|
+
Workflows under environment-qualified names (`<app>-<env>-onboarding-v2`), and
|
|
341
|
+
keeps its registry in its own features database. Runs never cross targets.
|
|
342
|
+
|
|
343
|
+
## Data and retention
|
|
344
|
+
|
|
345
|
+
| Stored | Where | Kept |
|
|
346
|
+
|---|---|---|
|
|
347
|
+
| Run identity, version, organization, actor, status, revision, input, result, error code | `_quickback_workflow_runs` (features D1) | Until `retention` after a run finishes. Unfinished runs are never pruned. |
|
|
348
|
+
| Events | `_quickback_workflow_events` | Deleted with their run. |
|
|
349
|
+
| Step results, sleeps, waits | Native Workflow instance state | Cloudflare's instance retention. |
|
|
350
|
+
|
|
351
|
+
The effects sweep cron also deletes expired runs, in batches of 200.
|
|
352
|
+
|
|
353
|
+
## Limits and guarantees
|
|
354
|
+
|
|
355
|
+
- Delivery is at least once at every boundary: intents, dispatch, events and steps.
|
|
356
|
+
- Nothing is exactly once, and nothing is compensated automatically.
|
|
357
|
+
- Each start, event and control costs one D1 batch, one durable effect and one queue message. Each step attempt adds two auth-database reads and one registry read.
|
|
358
|
+
- Native Workflows limits apply: step count, payload sizes, concurrency and pricing. See [Cloudflare Workflows limits](https://developers.cloudflare.com/workflows/reference/limits/).
|
|
359
|
+
|
|
360
|
+
The generated runtime is tested under Miniflare's local Workflows engine:
|
|
361
|
+
durable starts, the inbox, registry and step state across a process restart,
|
|
362
|
+
pause and resume, revocation and retry, cancellation, and two versions running
|
|
363
|
+
at once. The local engine keeps sleep timers in memory, so after a restart it
|
|
364
|
+
does not wake a sleeping run by itself; the test re-invokes the run through
|
|
365
|
+
pause and resume and checks that completed steps replay. On a deployed
|
|
366
|
+
account (2026-11-19): a run sleeping across a redeploy woke and completed;
|
|
367
|
+
pause, back-to-back pause and resume, cancel, revocation to `blocked`,
|
|
368
|
+
restart-from-step retry, idempotent start and event delivery behaved as
|
|
369
|
+
described here.
|
|
370
|
+
|
|
371
|
+
## Compile errors
|
|
372
|
+
|
|
373
|
+
| Code | When |
|
|
374
|
+
|---|---|
|
|
375
|
+
| `WORKFLOW_RUNTIME` / `WORKFLOW_DATABASE` | The runtime is not Cloudflare, or the features database is not D1. |
|
|
376
|
+
| `WORKFLOW_DURABLE_EFFECTS_REQUIRED` | `durableEffects` is not enabled. |
|
|
377
|
+
| `WORKFLOW_ORGANIZATIONS_REQUIRED` | The organization plugin is off. |
|
|
378
|
+
| `WORKFLOW_QUEUE` | Several queues and no `workflowQueue`, or an unknown `workflowQueue`. |
|
|
379
|
+
| `WORKFLOW_TENANT_JOB_UNAVAILABLE` | `step.job` without durable-object tenancy. |
|
|
380
|
+
| `WORKFLOW_NAME` / `WORKFLOW_VERSION` / `WORKFLOW_DUPLICATE_VERSION` | Invalid or repeated identity. |
|
|
381
|
+
| `WORKFLOW_ACCESS` / `WORKFLOW_AUTHORITY` / `WORKFLOW_AUTHORITY_SERVICE_UNSUPPORTED` | Invalid policy or authority mode. |
|
|
382
|
+
| `WORKFLOW_STEP_NAME_LITERAL` / `WORKFLOW_STEP_DUPLICATE` / `WORKFLOW_STEP_LOOP_KEY` | A step name that is not a literal, is repeated, or runs in a loop without a key. |
|
|
383
|
+
| `WORKFLOW_STEP_ESCAPES` / `WORKFLOW_STEP_HANDLE` / `WORKFLOW_STEP_EVENT` / `WORKFLOW_STEP_OPTIONS` | Misuse of `step`, an undeclared event, or out-of-bounds options. |
|
|
384
|
+
| `WORKFLOW_NATIVE_NAME` | A native name longer than 64 characters. |
|
|
385
|
+
| `WORKFLOW_VERSION_REMOVED` | A deployed, unretired version was deleted. |
|
|
@@ -7,6 +7,33 @@ This page covers the browser flow. For local projects, or anything the browser f
|
|
|
7
7
|
> Browser deployment is new. The hosted deploy service sits behind a kill switch, and provisioning is rate-limited to 5 deploys per minute per user — enough to stop a runaway retry loop, not something a normal deploy will ever hit. `quickback deploy` works for everyone today.
|
|
8
8
|
|
|
9
9
|
|
|
10
|
+
## If the hosted builder is at capacity
|
|
11
|
+
|
|
12
|
+
When hosted AI generation capacity is exhausted, Start offers the hosted-builder
|
|
13
|
+
waitlist and a way to continue in your own IDE or coding agent. The
|
|
14
|
+
[AI tools setup guide](/tooling/claude-code) covers the Claude Code skill,
|
|
15
|
+
Cursor rules, and the MCP server for compatible agents. Your agent uses its own
|
|
16
|
+
model access.
|
|
17
|
+
|
|
18
|
+
Existing chat history and definitions stay in your browser. If definitions have
|
|
19
|
+
already been created, use **Download your existing definitions** to continue
|
|
20
|
+
locally. The capacity panel pauses new chat submissions; **Try the hosted
|
|
21
|
+
builder again** makes an explicit retry when you want to check availability.
|
|
22
|
+
Other builder errors keep their normal error and retry controls.
|
|
23
|
+
|
|
24
|
+
## If definition generation stops responding
|
|
25
|
+
|
|
26
|
+
Chat and completed definition writes are saved in your browser. After 45 seconds
|
|
27
|
+
without progress, Start offers **Stop safely** and **Reload saved chat**. A slow
|
|
28
|
+
compile may still be working, so you can also keep waiting. Stopping cancels
|
|
29
|
+
the active request; a normal page reload does not automatically resume it.
|
|
30
|
+
|
|
31
|
+
Use **Continue from saved work** after stopping or reloading an interrupted
|
|
32
|
+
generation. Start keeps completed tool results and removes incomplete calls
|
|
33
|
+
before continuing with your original requirements and existing definitions.
|
|
34
|
+
Incomplete file writes are not treated as saved definitions. Use the same
|
|
35
|
+
browser and keep its site data to retain your saved chat.
|
|
36
|
+
|
|
10
37
|
## The three-stage workspace
|
|
11
38
|
|
|
12
39
|
Start keeps authoring, building, and deployment separate:
|
|
@@ -17,6 +44,8 @@ Start keeps authoring, building, and deployment separate:
|
|
|
17
44
|
|
|
18
45
|
All three tabs remain selectable before a build, so the later stages can explain what they need. Editing a definition after a successful build marks Generated Backend **stale** and blocks Cloudflare deployment until you rebuild. This guarantees that the source being deployed matches the revision you inspected.
|
|
19
46
|
|
|
47
|
+
A successful build does not verify application behavior. Review custom actions before deployment: a hand-written action without [compiler-applied transition writes](/define/transitions#action-level-extensions) must perform its database write in `execute`. A handler that only returns `{ success: true }` can compile without changing the record. Generated table-level transitions already include the state update.
|
|
48
|
+
|
|
20
49
|
## Start from an OpenAPI spec
|
|
21
50
|
|
|
22
51
|
Already have an API? On the empty-chat screen, choose **Start from an OpenAPI spec** and upload an OpenAPI 3 file (JSON or YAML, up to 200 operations). Start converts it in your browser before the agent sees it:
|
|
@@ -217,3 +246,25 @@ For ongoing CLI management, keep the same project name and deploy through the sa
|
|
|
217
246
|
- The blocked resources listed above.
|
|
218
247
|
|
|
219
248
|
These all work — or will work first — through [`quickback deploy`](/start/deploy).
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
### Tested examples and validation checkpoints
|
|
252
|
+
|
|
253
|
+
For a new project matching a complete tested example, Start can copy the current
|
|
254
|
+
canonical files directly into Quickback Definitions and validate them in the
|
|
255
|
+
same operation, before the agent can rewrite them. The files remain ordinary,
|
|
256
|
+
editable project source. Copying refuses to overwrite an existing project and
|
|
257
|
+
does not deploy or create Cloudflare resources. The issue-tracker example includes
|
|
258
|
+
reporter-or-assignee editing, validated assignments, organization-safe references,
|
|
259
|
+
admin workflow transitions, role-specific views, realtime, and sysadmin CMS.
|
|
260
|
+
|
|
261
|
+
Start parses TypeScript writes before saving them, catching syntax errors and
|
|
262
|
+
duplicate imports while retaining the last valid file. This is a syntax check,
|
|
263
|
+
not a generated-project typecheck or a runtime permission test.
|
|
264
|
+
|
|
265
|
+
The agent can validate an incomplete skeleton with
|
|
266
|
+
`compile_project({ intent: "checkpoint" })`. A successful final validation closes
|
|
267
|
+
file edits for that response so the agent can summarize the result rather than
|
|
268
|
+
continue rewriting working files. A subsequent user request can make further
|
|
269
|
+
changes. Definition validation, complete compilation, generated TypeScript, and
|
|
270
|
+
runtime acceptance remain distinct checks.
|
|
@@ -18,7 +18,8 @@ cd my-app && quickback deploy
|
|
|
18
18
|
- **D1 databases** — auth, features, files, webhooks, and audit databases (whichever your project's features pull in; split-database projects get one entry each)
|
|
19
19
|
- **KV namespace** — the `KV` binding used for rate limiting and session overflow
|
|
20
20
|
- **R2 buckets** — file-storage buckets (R2 is referenced by name, so buckets are simply ensured to exist)
|
|
21
|
-
4. **Creates what's missing** — `wrangler d1 create <name>`, `wrangler kv namespace create <BINDING>`, `wrangler r2 bucket create <name>`. Resources are named from your project name exactly the way the compiler names them (`my-app-auth`, `my-app-features`, `my-app-files`, `my-app-KV`, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.
|
|
21
|
+
4. **Creates what's missing** — `wrangler d1 create <name>`, `wrangler kv namespace create <project>-<BINDING>`, `wrangler r2 bucket create <name>`. Resources are named from your project name exactly the way the compiler names them (`my-app-auth`, `my-app-features`, `my-app-files`, `my-app-KV`, …). If a resource with the expected name already exists in your account, its id is reused instead of creating a duplicate.
|
|
22
|
+
Wrangler takes the namespace name literally: the CLI passes the full app-specific title (for example `my-app-KV`), while the Worker binding remains `KV`. A namespace titled only `KV` is not reused for an app-specific resource.
|
|
22
23
|
5. **Writes ids back into quickback.config.ts** — a surgical, formatting-preserving edit of your `providers.database.config` (and `providers.storage.config` for the KV id when you declare a `cloudflare-kv` storage provider). Comments, indentation, and every other key are left untouched. Works with both authoring styles:
|
|
23
24
|
|
|
24
25
|
```ts
|
|
@@ -131,6 +132,101 @@ quickback migrate data --env production # dry-run pending data migrations
|
|
|
131
132
|
See [Check and Push Secrets](/tooling/cli#check-and-push-secrets) and
|
|
132
133
|
[Data Migrations](/platform/database/data-migrations).
|
|
133
134
|
|
|
135
|
+
## Ephemeral previews
|
|
136
|
+
|
|
137
|
+
`quickback preview` stands up a short-lived, fully isolated copy of the built
|
|
138
|
+
project for review, and tears down exactly what it created:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
quickback preview plan --name pr-123 # read-only: what would be created or refused
|
|
142
|
+
quickback preview up --name pr-123 --seed preview.seed.json --ttl 72
|
|
143
|
+
quickback preview status
|
|
144
|
+
quickback preview down --name pr-123 # review only
|
|
145
|
+
quickback preview down --name pr-123 --apply # delete
|
|
146
|
+
quickback preview gc --apply # tear down every expired preview
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
**Template.** A preview copies the selected deployment target — the base
|
|
150
|
+
config, or a named environment with `--env <target>` — from the generated
|
|
151
|
+
`wrangler.toml` and `quickback.deploy.json`. Run `quickback build` first. The
|
|
152
|
+
target must name its account explicitly (`providers.runtime.config.accountId`
|
|
153
|
+
or `environments.<target>.accountId`); every Wrangler call is pinned to it.
|
|
154
|
+
|
|
155
|
+
**Isolation.** Each preview gets its own Worker, its own D1 databases (with the
|
|
156
|
+
project's existing migration history applied), KV namespaces and R2 buckets.
|
|
157
|
+
Bindings that share one D1 database still share one preview database. Durable
|
|
158
|
+
Objects are bound to the preview Worker, so their state is local to it.
|
|
159
|
+
Rate-limit counters get a fresh `namespace_id`. Physical names are
|
|
160
|
+
`qbp-<project-hash>-<generation>[-<binding>]`: a random generation per preview,
|
|
161
|
+
never the preview name. The committed config, `wrangler.toml`, migration
|
|
162
|
+
history and target ids are never edited. The scratch config and ownership
|
|
163
|
+
record live under `.quickback/previews/<name>/`, which ignores itself in git.
|
|
164
|
+
|
|
165
|
+
**Secrets.** Secrets are never copied. `BETTER_AUTH_SECRET` and other
|
|
166
|
+
compiler-generated secrets are minted fresh and sent over stdin after a private
|
|
167
|
+
first upload, so the Worker has no public URL until its secrets exist. When the
|
|
168
|
+
project uses Better Auth, `BETTER_AUTH_URL` is set to the preview's `workers.dev`
|
|
169
|
+
origin and the Worker is redeployed. This happens whether or not `[vars]` sets
|
|
170
|
+
it, because without it Better Auth would reject the preview's own origin. The
|
|
171
|
+
preview is `ready` only after `/health` answers 200.
|
|
172
|
+
|
|
173
|
+
**Synthetic seed.** `--seed <file>` (relative to `quickback/`, which it cannot
|
|
174
|
+
escape) takes `{ "version": 1, "datasets": [{ "binding", "table", "rows" }] }`.
|
|
175
|
+
Tables must be created by that binding's migrations. Framework tables
|
|
176
|
+
(`d1_migrations`, `_`-prefixed) and `AUTH_DB` credential tables are refused.
|
|
177
|
+
Values must be strings, numbers, booleans or null, with up to 1,000 rows per
|
|
178
|
+
dataset and 5,000 in total. Rows go in with `INSERT OR IGNORE`, so give each
|
|
179
|
+
row its primary key and a retried seed stays idempotent. A changed seed is
|
|
180
|
+
refused; tear the preview down and recreate it. Seed data is published on a
|
|
181
|
+
public URL. Never put production data in it.
|
|
182
|
+
|
|
183
|
+
**Supported graph (v1).** A single generated Worker using D1, KV, R2,
|
|
184
|
+
same-Worker Durable Objects and rate limits. `plan` and `up` refuse, before any
|
|
185
|
+
account call:
|
|
186
|
+
|
|
187
|
+
- custom domains or routes: the generated Worker only answers on its configured
|
|
188
|
+
hostnames, so a `workers.dev` preview would 404
|
|
189
|
+
- queue producers or consumers, including generated webhook and outbox consumers
|
|
190
|
+
- cron triggers, service bindings, cross-Worker Durable Objects, Workflows,
|
|
191
|
+
Hyperdrive/Postgres, Vectorize, Workers AI, real email (`send_email`),
|
|
192
|
+
Containers, pipelines, dispatch namespaces, mTLS, Secrets Store, VPC and
|
|
193
|
+
Analytics Engine
|
|
194
|
+
- files, tenant or separate-realtime Workers (multi-Worker topologies)
|
|
195
|
+
- any required secret a human supplies (payments, push, SES, webhooks), and
|
|
196
|
+
Cloudflare owner login
|
|
197
|
+
- any Wrangler table or key Quickback does not classify
|
|
198
|
+
|
|
199
|
+
Nothing is silently removed to make a preview deploy.
|
|
200
|
+
|
|
201
|
+
**Ownership and teardown.** `.quickback/previews/<name>/ledger.json` is the
|
|
202
|
+
only proof of ownership. Intent is recorded before each create and the
|
|
203
|
+
returned id after it. An "already exists" error is a collision, never adoption.
|
|
204
|
+
`down --apply` first tombstones the generation. It then deletes the Worker, R2
|
|
205
|
+
buckets, KV namespaces and D1 databases in that order. Before **each** delete it
|
|
206
|
+
re-checks that the name belongs to this generation and that no generated
|
|
207
|
+
config (any target, any Worker) references the resource. It also checks that
|
|
208
|
+
the live account still maps the name to the recorded id. Production, foreign
|
|
209
|
+
and unconfirmed resources are reported and left in place. A resource that is
|
|
210
|
+
already gone counts as deleted, so `down --apply` is safe to re-run until it
|
|
211
|
+
exits 0. A tombstoned generation is never redeployed. The next `up` mints a new
|
|
212
|
+
generation with new physical names.
|
|
213
|
+
|
|
214
|
+
**Expiry.** `--ttl <hours>` (1–720, default 72) sets `expiresAt`. An expired
|
|
215
|
+
preview is never redeployed. `gc` reviews the expired previews in this
|
|
216
|
+
checkout's records, and `gc --apply` tears them down in batches (`--limit`,
|
|
217
|
+
default 10). It exits non-zero while any cleanup is unresolved, so schedule it.
|
|
218
|
+
|
|
219
|
+
**Recovery.** `up` and `down --apply` resume from the ledger after any failure.
|
|
220
|
+
An R2 bucket that still holds objects fails to delete and stays retryable;
|
|
221
|
+
empty it, then re-run. If a create was interrupted after Cloudflare accepted
|
|
222
|
+
it, the resource is reported as unconfirmed. Verify and delete it by hand, then
|
|
223
|
+
remove its entry from the ledger. Losing the ledger leaks resources but never
|
|
224
|
+
deletes anything, because nothing is deleted without a ledger entry.
|
|
225
|
+
|
|
226
|
+
> Ownership records are local to the checkout. Running previews from CI needs a
|
|
227
|
+
> durable `.quickback/previews/` (artifact or cache) between the up, close and
|
|
228
|
+
> gc jobs; a shared registry and a CI template are not part of v1.
|
|
229
|
+
|
|
134
230
|
## Conflicting ids
|
|
135
231
|
|
|
136
232
|
If `quickback.config.ts` already carries a real id for a resource and Cloudflare reports a different one for the same-named resource, `quickback deploy` prints both and stops:
|