@quickback-dev/cli 0.39.1 → 0.40.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/docs/content.js +4 -4
- package/dist/docs/content.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/skill/docs/changelog.md +97 -0
- package/dist/skill/docs/stack/auth/plugins/index.md +46 -0
- package/dist/skill/docs/stack/storage/r2.md +38 -7
- package/dist/skill/docs/stack/storage/using-r2.md +58 -33
- package/package.json +1 -1
- package/src/skill/docs/changelog.md +97 -0
- package/src/skill/docs/stack/auth/plugins/index.md +46 -0
- package/src/skill/docs/stack/storage/r2.md +38 -7
- package/src/skill/docs/stack/storage/using-r2.md +58 -33
|
@@ -2,53 +2,78 @@
|
|
|
2
2
|
|
|
3
3
|
Cloudflare R2 provides S3-compatible object storage for file uploads in the Quickback Stack.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
By default `defineFileStorage("cloudflare-r2")` is **presign-only**: you get the
|
|
6
|
+
`ctx.storage` signer and nothing else. The `/storage/v1/*` endpoints shown
|
|
7
|
+
further down only exist in the [managed subsystem](/stack/storage/r2#two-modes)
|
|
8
|
+
(`managed: true`).
|
|
9
|
+
|
|
10
|
+
## Upload Flow (default — `ctx.storage`)
|
|
11
|
+
|
|
12
|
+
Write a normal `defineAction` that signs a presigned URL and stores the key in
|
|
13
|
+
**your own table**. Bytes go directly to R2 — the Worker only signs.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
export default defineAction({
|
|
17
|
+
path: "/media/sign-upload",
|
|
18
|
+
method: "POST",
|
|
19
|
+
input: z.object({ filename: z.string(), contentType: z.string() }),
|
|
20
|
+
access: { roles: ["member"] },
|
|
21
|
+
async execute({ input, ctx, db, storage }) {
|
|
22
|
+
const key = `org/${ctx.activeOrgId}/${crypto.randomUUID()}-${input.filename}`;
|
|
23
|
+
const upload = await storage.signPutUrl(key, { contentType: input.contentType, expiresIn: 600 });
|
|
24
|
+
await db.insert(media).values({ key /* … */ });
|
|
25
|
+
return { uploadUrl: upload.url, key, headers: upload.headers };
|
|
26
|
+
},
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# 1. Ask your action for a signed URL (your auth/roles run here)
|
|
32
|
+
curl -X POST https://api.example.com/api/v1/media/sign-upload \
|
|
33
|
+
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
|
|
34
|
+
-d '{ "filename": "report.pdf", "contentType": "application/pdf" }'
|
|
35
|
+
# → { "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...", "key": "...", "headers": { "Content-Type": "application/pdf" } }
|
|
36
|
+
|
|
37
|
+
# 2. Upload the bytes straight to R2 (replay the returned headers)
|
|
38
|
+
curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`storage.signPutUrl(key, { contentType?, expiresIn?, bucket? })` returns
|
|
42
|
+
`{ url, method, headers, key, expiresAt }`; `storage.signGetUrl(key, { expiresIn?, downloadFilename?, bucket? })`
|
|
43
|
+
returns a presigned GET URL. Pass `bucket` to target a bucket other than the
|
|
44
|
+
configured default.
|
|
45
|
+
|
|
46
|
+
Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
|
|
47
|
+
and `R2_SECRET_ACCESS_KEY` secrets. See [R2 Setup → Presigned uploads](/stack/storage/r2#presigned-uploads-recommended).
|
|
6
48
|
|
|
7
|
-
|
|
8
|
-
directly to R2 and never stream through your Worker:
|
|
49
|
+
## Upload Flow (managed mode — `/storage/v1/*`)
|
|
9
50
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
2. **Upload directly to R2** — Client `PUT`s the bytes to R2 (bypasses your Worker)
|
|
13
|
-
3. **Confirm** — `/storage/v1/confirm/...` reconciles the recorded size + etag
|
|
51
|
+
With `managed: true`, the generated API also exposes turnkey presigned
|
|
52
|
+
endpoints backed by the FILES_DB metadata system:
|
|
14
53
|
|
|
15
54
|
```bash
|
|
16
55
|
# 1. Request a presigned upload URL
|
|
17
56
|
curl -X POST https://api.example.com/storage/v1/presign/documents/report.pdf \
|
|
18
|
-
-H "Authorization: Bearer <token>" \
|
|
19
|
-
-H "Content-Type: application/json" \
|
|
57
|
+
-H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
|
|
20
58
|
-d '{ "contentType": "application/pdf", "size": 248000 }'
|
|
59
|
+
# → { "id": "obj_abc", "key": "...", "uploadUrl": "...", "headers": {...}, "expiresAt": "..." }
|
|
60
|
+
|
|
61
|
+
# 2. Upload directly to R2
|
|
62
|
+
curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
|
|
21
63
|
|
|
22
|
-
#
|
|
23
|
-
# {
|
|
24
|
-
# "id": "obj_abc123",
|
|
25
|
-
# "key": "org_abc/documents/report.pdf",
|
|
26
|
-
# "uploadUrl": "https://<account>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
|
|
27
|
-
# "method": "PUT",
|
|
28
|
-
# "headers": { "Content-Type": "application/pdf" },
|
|
29
|
-
# "expiresAt": "2026-06-02T12:10:00.000Z"
|
|
30
|
-
# }
|
|
31
|
-
|
|
32
|
-
# 2. Upload directly to R2 using the presigned URL (replay the returned headers)
|
|
33
|
-
curl -X PUT "<uploadUrl>" \
|
|
34
|
-
-H "Content-Type: application/pdf" \
|
|
35
|
-
--data-binary @report.pdf
|
|
36
|
-
|
|
37
|
-
# 3. Confirm the upload
|
|
64
|
+
# 3. Confirm (reconciles size + etag)
|
|
38
65
|
curl -X POST https://api.example.com/storage/v1/confirm/documents/report.pdf \
|
|
39
66
|
-H "Authorization: Bearer <token>"
|
|
40
67
|
```
|
|
41
68
|
|
|
42
|
-
Presigning needs an R2 API token — set the `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`,
|
|
43
|
-
and `R2_SECRET_ACCESS_KEY` secrets. See [R2 Setup → Presigned uploads](/stack/storage/r2#presigned-uploads-recommended).
|
|
44
|
-
|
|
45
|
-
For uploads that should land in **your own table** (with your own access rules),
|
|
46
|
-
sign the URL from inside a `defineAction` via `ctx.storage` — see
|
|
47
|
-
[Signing from your own action](/stack/storage/r2#signing-from-your-own-action).
|
|
48
|
-
|
|
49
69
|
## Download Flow
|
|
50
70
|
|
|
51
|
-
|
|
71
|
+
In **presign-only** mode, mint a short-lived download URL with
|
|
72
|
+
`storage.signGetUrl(key, { downloadFilename })` from your action and hand it to
|
|
73
|
+
the client — the bytes come straight from R2.
|
|
74
|
+
|
|
75
|
+
In **managed** mode, files are also served through the worker with security
|
|
76
|
+
checks applied:
|
|
52
77
|
|
|
53
78
|
```bash
|
|
54
79
|
# Download a file (auth + firewall enforced)
|