cloudrop 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +115 -0
- package/README.md +34 -4
- package/dist/adapters/drizzle.d.ts +1 -1
- package/dist/adapters/drizzle.js +3 -3
- package/dist/adapters/drizzle.js.map +1 -1
- package/dist/adapters/prisma.d.ts +1 -1
- package/dist/adapters/prisma.js +1 -1
- package/dist/adapters/sql.d.ts +4 -1
- package/dist/adapters/sql.js +8 -1
- package/dist/adapters/sql.js.map +1 -1
- package/dist/cli.js +2045 -0
- package/dist/{client-Dj6ON4MN.d.ts → client-CP_ajLF4.d.ts} +43 -25
- package/dist/{client-Y1zUEbCj.js → client-DxP3uv8V.js} +172 -44
- package/dist/client-DxP3uv8V.js.map +1 -0
- package/dist/client.d.ts +3 -3
- package/dist/client.js +1 -1
- package/dist/errors-CUxMmFAe.js.map +1 -1
- package/dist/index.d.ts +92 -7
- package/dist/index.js +432 -152
- package/dist/index.js.map +1 -1
- package/dist/next.d.ts +1 -1
- package/dist/node.d.ts +1 -1
- package/dist/react.d.ts +18 -4
- package/dist/react.js +23 -3
- package/dist/react.js.map +1 -1
- package/dist/{route-CspI1Ypt.js → route-C8-YjzdY.js} +3 -2
- package/dist/{route-CspI1Ypt.js.map → route-C8-YjzdY.js.map} +1 -1
- package/dist/{store-BfCJejGh.d.ts → store-B539nY3J.d.ts} +41 -3
- package/dist/testing.d.ts +81 -0
- package/dist/testing.js +1243 -0
- package/dist/testing.js.map +1 -0
- package/dist/{transactional-DnvnGsVH.js → transactional-CiNwMiDb.js} +215 -105
- package/dist/transactional-CiNwMiDb.js.map +1 -0
- package/dist/{types-BrAx3dA4.d.ts → types-CFfMw-n_.d.ts} +1 -1
- package/docs/README.md +30 -0
- package/docs/bucket-setup.md +226 -0
- package/docs/client.md +386 -0
- package/docs/command.md +129 -0
- package/docs/deployment.md +169 -0
- package/docs/errors.md +150 -0
- package/docs/hono.md +276 -0
- package/docs/react.md +508 -0
- package/docs/resume.md +253 -0
- package/docs/server.md +603 -0
- package/docs/store.md +804 -0
- package/docs/testing-your-app.md +328 -0
- package/docs/troubleshooting.md +176 -0
- package/package.json +16 -8
- package/dist/client-Y1zUEbCj.js.map +0 -1
- package/dist/transactional-DnvnGsVH.js.map +0 -1
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
# Testing your app
|
|
2
|
+
|
|
3
|
+
`cloudrop/testing` runs your upload server and the real client in one process, in your own test runner, with no
|
|
4
|
+
bucket, browser or network. Your tests call `client.upload()` as your page does, and then read what landed in the
|
|
5
|
+
bucket. Use it to test what is yours: who `authorize` lets in, the metadata your schema takes, your quotas, what
|
|
6
|
+
`onComplete` returns, and how a large file goes through.
|
|
7
|
+
|
|
8
|
+
It works in Vitest, Node's `node:test` and Bun's test runner; the examples below are Vitest. They are the
|
|
9
|
+
repository's own tests (`packages/cloudrop/src/testing.guide.test.ts`), so they run as written. This page is for
|
|
10
|
+
testing an app that uses cloudrop; for the lanes that test cloudrop itself, see [Testing](https://github.com/vcode-sh/cloudrop/blob/main/docs/guide/testing.md).
|
|
11
|
+
|
|
12
|
+
## Set up
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm i -D vitest
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Three functions do the work:
|
|
19
|
+
|
|
20
|
+
- `testBucket()` is an in-process bucket with R2's measured rules: equal part sizes, the 7-day limit on presigned URLs,
|
|
21
|
+
create-only writes. It checks every request's signature, so a request signed for another bucket, after its expiry
|
|
22
|
+
or with changed headers is refused. Pass `bucket.storage` to `createCloudrop`.
|
|
23
|
+
- `testClient(cloudrop, { bucket })` is the real `cloudrop/client` client, wired to `cloudrop.handler` and the bucket.
|
|
24
|
+
`headers` stands in for the session a browser's cookies would carry.
|
|
25
|
+
- `memoryStore()` is an in-memory [database store](store.md), for an app that uses `owner`, `quota`, `afterComplete`
|
|
26
|
+
or `replace`.
|
|
27
|
+
|
|
28
|
+
The examples share these imports and this setup. `signedIn` stands in for your app's session lookup: in your tests,
|
|
29
|
+
import your real routes instead. A route built with your database store's `store.route` belongs to that store; see
|
|
30
|
+
[`memoryStore`](#memorystoreoptions) for those.
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import { expect, test } from "vitest";
|
|
34
|
+
import { createCloudrop, route, type StandardSchema, unauthorized } from "cloudrop";
|
|
35
|
+
import { memoryStore, testBucket, testClient } from "cloudrop/testing";
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
const secret = "a-test-secret-of-at-least-32-characters";
|
|
40
|
+
|
|
41
|
+
// Your app's session lookup; here the user is whoever the "session" cookie names.
|
|
42
|
+
function signedIn({ request }: { request: Request }) {
|
|
43
|
+
const userId = /(?:^|; )session=(\w+)/.exec(request.headers.get("cookie") ?? "")?.[1];
|
|
44
|
+
return userId ? { userId } : unauthorized("Sign in to upload.");
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const avatar = route(
|
|
48
|
+
{ accept: "image/*", maxSize: "1MB", authorize: signedIn },
|
|
49
|
+
{ prefix: ({ userId }) => `users/${userId}/avatars` },
|
|
50
|
+
);
|
|
51
|
+
|
|
52
|
+
const png = (name: string, bytes = 100) => new File([new Uint8Array(bytes)], name, { type: "image/png" });
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## `authorize`: who may upload
|
|
56
|
+
|
|
57
|
+
A signed-in user's file lands under the folder the route's `prefix` builds:
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
test("stores a signed-in user's avatar under their folder", async () => {
|
|
61
|
+
const bucket = testBucket();
|
|
62
|
+
const cloudrop = createCloudrop({ storage: bucket.storage, secret, routes: { avatar } });
|
|
63
|
+
const client = testClient(cloudrop, { bucket, headers: { cookie: "session=alice" } });
|
|
64
|
+
|
|
65
|
+
const { data, error } = await client.upload("avatar", png("me.png", 512));
|
|
66
|
+
|
|
67
|
+
expect(error).toBeNull();
|
|
68
|
+
expect(data?.file.key).toMatch(/^users\/alice\/avatars\/\w+\.png$/);
|
|
69
|
+
expect(bucket.object(data?.file.key ?? "")?.size).toBe(512);
|
|
70
|
+
});
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
A request without a session is refused with the message your `unauthorized()` gave, and nothing reaches the bucket:
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
test("refuses a signed-out user and stores nothing", async () => {
|
|
77
|
+
const bucket = testBucket();
|
|
78
|
+
const cloudrop = createCloudrop({ storage: bucket.storage, secret, routes: { avatar } });
|
|
79
|
+
const client = testClient(cloudrop, { bucket }); // no session cookie
|
|
80
|
+
|
|
81
|
+
const { error } = await client.upload("avatar", png("me.png"));
|
|
82
|
+
|
|
83
|
+
expect(error?.code).toBe("UNAUTHORIZED");
|
|
84
|
+
expect(error?.message).toBe("Sign in to upload.");
|
|
85
|
+
expect(bucket.keys()).toEqual([]);
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Metadata
|
|
90
|
+
|
|
91
|
+
The route's schema checks the metadata the client sends. A real app passes a zod, valibot or arktype schema; the
|
|
92
|
+
example writes a small Standard Schema by hand so that it needs no library:
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
// Any Standard Schema: in your app, z.object({ albumId: z.string().min(1) }) from zod, or valibot's or arktype's.
|
|
96
|
+
const album: StandardSchema<{ albumId: string }> = {
|
|
97
|
+
"~standard": {
|
|
98
|
+
version: 1,
|
|
99
|
+
vendor: "example",
|
|
100
|
+
validate: (value) => {
|
|
101
|
+
const albumId = (value as { albumId?: unknown } | undefined)?.albumId;
|
|
102
|
+
return typeof albumId === "string" && albumId !== ""
|
|
103
|
+
? { value: { albumId } }
|
|
104
|
+
: { issues: [{ message: "Choose an album.", path: ["albumId"] }] };
|
|
105
|
+
},
|
|
106
|
+
},
|
|
107
|
+
};
|
|
108
|
+
const photo = route(
|
|
109
|
+
{ accept: "image/*", maxSize: "1MB", metadata: album, authorize: signedIn },
|
|
110
|
+
{ prefix: ({ userId, metadata }) => `users/${userId}/albums/${metadata.albumId}` },
|
|
111
|
+
);
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
test("refuses a photo without an album", async () => {
|
|
116
|
+
const bucket = testBucket();
|
|
117
|
+
const cloudrop = createCloudrop({ storage: bucket.storage, secret, routes: { photo } });
|
|
118
|
+
const client = testClient(cloudrop, { bucket, headers: { cookie: "session=alice" } });
|
|
119
|
+
|
|
120
|
+
const { error } = await client.upload("photo", png("cat.png"), { metadata: { albumId: "" } });
|
|
121
|
+
|
|
122
|
+
expect(error?.code).toBe("INVALID_METADATA");
|
|
123
|
+
expect(error?.message).toBe("The metadata is not valid: Choose an album. (at albumId). Correct it and try again.");
|
|
124
|
+
expect(bucket.keys()).toEqual([]);
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## A quota, with a store
|
|
129
|
+
|
|
130
|
+
`memoryStore()` keeps rows and usage the way the shipped adapters do, so `quota`, `owner` and `cloudrop.api.usage`
|
|
131
|
+
behave as with your database:
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
test("refuses a file that would take a user past their quota", async () => {
|
|
135
|
+
const bucket = testBucket();
|
|
136
|
+
const cloudrop = createCloudrop({
|
|
137
|
+
storage: bucket.storage,
|
|
138
|
+
secret,
|
|
139
|
+
store: memoryStore(),
|
|
140
|
+
quota: () => 1000, // bytes per owner
|
|
141
|
+
routes: {
|
|
142
|
+
files: route(
|
|
143
|
+
{ accept: "*/*", maxSize: "1MB", authorize: signedIn },
|
|
144
|
+
{ prefix: ({ userId }) => `users/${userId}/files`, owner: ({ userId }) => userId },
|
|
145
|
+
),
|
|
146
|
+
},
|
|
147
|
+
});
|
|
148
|
+
const client = testClient(cloudrop, { bucket, headers: { cookie: "session=alice" } });
|
|
149
|
+
const file = (name: string) => new File([new Uint8Array(600)], name, { type: "application/pdf" });
|
|
150
|
+
|
|
151
|
+
expect((await client.upload("files", file("first.pdf"))).error).toBeNull();
|
|
152
|
+
const { error } = await client.upload("files", file("second.pdf"));
|
|
153
|
+
|
|
154
|
+
expect(error?.code).toBe("QUOTA_EXCEEDED");
|
|
155
|
+
expect((await cloudrop.api.usage("alice")).data).toEqual({ reservedBytes: 0, activeBytes: 600, files: 1 });
|
|
156
|
+
});
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## `onComplete`
|
|
160
|
+
|
|
161
|
+
What `onComplete` returns reaches the client as `data.data`:
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
test("answers the client with what onComplete returned", async () => {
|
|
165
|
+
const saved: string[] = [];
|
|
166
|
+
const bucket = testBucket();
|
|
167
|
+
const cloudrop = createCloudrop({
|
|
168
|
+
storage: bucket.storage,
|
|
169
|
+
secret,
|
|
170
|
+
routes: {
|
|
171
|
+
avatar: route(
|
|
172
|
+
{ accept: "image/*", maxSize: "1MB", authorize: signedIn },
|
|
173
|
+
{
|
|
174
|
+
onComplete: async ({ file, userId }) => {
|
|
175
|
+
saved.push(`${userId}: ${file.name}`); // your app's database write
|
|
176
|
+
return { owner: userId, bytes: file.size };
|
|
177
|
+
},
|
|
178
|
+
},
|
|
179
|
+
),
|
|
180
|
+
},
|
|
181
|
+
});
|
|
182
|
+
const client = testClient(cloudrop, { bucket, headers: { cookie: "session=alice" } });
|
|
183
|
+
|
|
184
|
+
const { data } = await client.upload("avatar", png("me.png", 300));
|
|
185
|
+
|
|
186
|
+
expect(data?.data).toEqual({ owner: "alice", bytes: 300 });
|
|
187
|
+
expect(saved).toEqual(["alice: me.png"]);
|
|
188
|
+
});
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## A multipart file
|
|
192
|
+
|
|
193
|
+
Files above `multipartThreshold` go up in parts, as in the browser. Lower the threshold in the test so a few MiB are
|
|
194
|
+
enough; parts are 8 MiB below 256 MiB, so 9 MiB makes two:
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
test("uploads a file larger than multipartThreshold in parts and stores every byte", async () => {
|
|
198
|
+
const bucket = testBucket();
|
|
199
|
+
const cloudrop = createCloudrop({
|
|
200
|
+
storage: bucket.storage,
|
|
201
|
+
secret,
|
|
202
|
+
multipartThreshold: "8MB", // the default is 64 MiB; a small threshold keeps the test fast
|
|
203
|
+
routes: { videos: route({ accept: "video/*", maxSize: "1GB", authorize: signedIn }) },
|
|
204
|
+
});
|
|
205
|
+
const client = testClient(cloudrop, { bucket, headers: { cookie: "session=alice" } });
|
|
206
|
+
// 9 MiB: an 8 MiB part and a 1 MiB one.
|
|
207
|
+
const bytes = new Uint8Array(9 * 1024 * 1024).map((_, index) => index % 251);
|
|
208
|
+
|
|
209
|
+
const { data, error } = await client.upload("videos", new File([bytes], "clip.mp4", { type: "video/mp4" }));
|
|
210
|
+
|
|
211
|
+
expect(error).toBeNull();
|
|
212
|
+
const stored = bucket.object(data?.file.key ?? "");
|
|
213
|
+
expect(stored?.parts).toBe(2);
|
|
214
|
+
expect(stored?.size).toBe(bytes.byteLength);
|
|
215
|
+
// Every byte in place; toEqual would compare the 9 MiB one by one and take most of a second.
|
|
216
|
+
expect(stored?.body.every((byte, index) => byte === bytes[index])).toBe(true);
|
|
217
|
+
expect(bucket.pendingUploads()).toBe(0);
|
|
218
|
+
});
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Through your app's mount
|
|
222
|
+
|
|
223
|
+
`testClient` reaches `cloudrop.handler` directly, so your route file and the middleware in front of it do not run. To
|
|
224
|
+
run them too, pass a `handler` that calls your app: any app that answers a `Request` with a `Response`, such as Hono's
|
|
225
|
+
`app.fetch`. A handler mounted at the wrong path then fails the test with `SERVER_ERROR` ("The upload server sent an
|
|
226
|
+
answer this client cannot read (HTTP 404)"):
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
// Your app, as your server builds it: here a fetch handler that mounts cloudrop at /api/cloudrop, as Hono's
|
|
230
|
+
// app.on(["POST", "OPTIONS"], "/api/cloudrop/*", (c) => cloudrop.handler(c.req.raw)) does.
|
|
231
|
+
function createApp(cloudrop: { handler(request: Request): Promise<Response> }) {
|
|
232
|
+
return {
|
|
233
|
+
fetch: (request: Request) =>
|
|
234
|
+
new URL(request.url).pathname.startsWith("/api/cloudrop/")
|
|
235
|
+
? cloudrop.handler(request)
|
|
236
|
+
: Promise.resolve(new Response("Not Found", { status: 404 })),
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
test("reaches cloudrop through the app's own mount", async () => {
|
|
241
|
+
const bucket = testBucket();
|
|
242
|
+
const cloudrop = createCloudrop({ storage: bucket.storage, secret, routes: { avatar } });
|
|
243
|
+
const app = createApp(cloudrop);
|
|
244
|
+
// Every request to the server goes through app.fetch: the mount path and the middleware in front of it run.
|
|
245
|
+
const client = testClient(
|
|
246
|
+
{ ...cloudrop, handler: (request) => app.fetch(request) },
|
|
247
|
+
{ bucket, headers: { cookie: "session=alice" } },
|
|
248
|
+
);
|
|
249
|
+
|
|
250
|
+
const { error } = await client.upload("avatar", png("me.png"));
|
|
251
|
+
|
|
252
|
+
expect(error).toBeNull();
|
|
253
|
+
});
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## What differs from a browser and a real bucket
|
|
257
|
+
|
|
258
|
+
The client is the real one, so progress, retries, multipart, `abort()` and `close()` run their real code. What a test
|
|
259
|
+
cannot see:
|
|
260
|
+
|
|
261
|
+
- **Your framework.** The client reaches `cloudrop.handler` directly. Your route file, the adapter
|
|
262
|
+
(`toNextHandler`, `toNodeHandler`) and middleware in front of it, such as a body parser that reads the body first,
|
|
263
|
+
do not run, so a test passes even when the handler is mounted at the wrong path, unless you test
|
|
264
|
+
[through your app's mount](#through-your-apps-mount). Check that the `basePath` of your page's
|
|
265
|
+
`createCloudropClient`, your mount and `createCloudrop` agree.
|
|
266
|
+
- **The page's origin.** The client runs on `http://localhost` and reaches the server there, as a same-origin page:
|
|
267
|
+
each request carries `Origin: http://localhost`, whatever `headers` says. A cross-origin setup and `trustedOrigins`
|
|
268
|
+
are not exercised; see [Deployment](deployment.md) for those.
|
|
269
|
+
- **Cookies.** A browser sends your session cookie by itself; here `headers` does it, for every request to the server
|
|
270
|
+
and never for the bucket, as the browser does. `headers` can be a function, called before each request.
|
|
271
|
+
- **Bucket CORS.** The test bucket answers every request; a real bucket refuses a browser's `PUT` that its CORS rule
|
|
272
|
+
does not allow. Check the rule on the real bucket with [`checkBucket`](bucket-setup.md).
|
|
273
|
+
- **Upload progress.** Bucket `PUT`s go through `fetch`, not `XMLHttpRequest`, so progress moves a whole part at a
|
|
274
|
+
time, as in a browser client created with a `fetch` option. This also keeps a jsdom or happy-dom environment, which
|
|
275
|
+
has an `XMLHttpRequest` of its own, from sending the bytes anywhere.
|
|
276
|
+
- **Resume after reload.** The client keeps nothing in IndexedDB: `resumable()` lists nothing, so one test's
|
|
277
|
+
unfinished upload never shows in the next.
|
|
278
|
+
- **The network.** Nothing is slow, dropped or refused on the way.
|
|
279
|
+
- **R2 itself.** The bucket checks signatures with cloudrop's own signer, so it proves the request is signed as cloudrop
|
|
280
|
+
signs, not that R2 accepts it. cloudrop's own test lanes check that against R2.
|
|
281
|
+
- **The clock.** The server and the bucket read the same clock, so `vi.useFakeTimers({ toFake: ["Date"] })` and
|
|
282
|
+
`vi.setSystemTime()` fix the date for both; in `node:test`, `t.mock.timers.enable({ apis: ["Date"], now })`, and in
|
|
283
|
+
Bun, `setSystemTime(date)` from `bun:test`. Faking every timer works too (`vi.useFakeTimers()`): an in-process
|
|
284
|
+
upload waits on no timer.
|
|
285
|
+
- **Bun's `File`.** Under `bun test`, `new File(parts, name, { type: "text/plain" })` reads back as
|
|
286
|
+
`text/plain;charset=utf-8`, and so does `application/json`, where a browser keeps the type as given. The server reads
|
|
287
|
+
a type by its essence (`M9-H1`), so the file is accepted and stored as `text/plain`, as from a browser.
|
|
288
|
+
|
|
289
|
+
## API
|
|
290
|
+
|
|
291
|
+
### `testBucket(options?)`
|
|
292
|
+
|
|
293
|
+
| Option | What it does |
|
|
294
|
+
| --- | --- |
|
|
295
|
+
| `publicUrl` | Where the bucket is served publicly, such as `"https://cdn.example.com"`, as in `r2({ publicUrl })`. Files on public routes get `file.url` under it. |
|
|
296
|
+
| `cors`, `lifecycle` | The bucket's CORS and lifecycle configuration as S3 XML, for tests of `cloudrop.api.checkBucket()`. Once either is given, the other reads as not configured. With neither, both read as refused, as with an R2 token that cannot read them. |
|
|
297
|
+
|
|
298
|
+
| Member | What it is |
|
|
299
|
+
| --- | --- |
|
|
300
|
+
| `storage` | The driver for `createCloudrop({ storage })`: `r2()` pointed at this bucket. |
|
|
301
|
+
| `fetch` | Reaches the bucket with a signed request, such as a URL from `cloudrop.api.getUrl()`. A `publicUrl` is not served: read a public file with `object(key)`. |
|
|
302
|
+
| `object(key)` | The stored object, or `null`: `key`, `size`, `type`, `disposition`, `metadata` (the `x-amz-meta-*` headers without the prefix), `parts` (`null` for a single `PUT`), `body` (a copy of the bytes) and `uploadedAt`. |
|
|
303
|
+
| `keys()` | Every stored key, sorted. |
|
|
304
|
+
| `pendingUploads()` | Multipart uploads started and neither completed nor aborted. `0` after a test means none was left behind. |
|
|
305
|
+
|
|
306
|
+
### `testClient(cloudrop, options)`
|
|
307
|
+
|
|
308
|
+
Returns a `CloudropClient`, typed from your server as `createCloudropClient<typeof cloudrop>()` would be.
|
|
309
|
+
|
|
310
|
+
| Option | What it does |
|
|
311
|
+
| --- | --- |
|
|
312
|
+
| `bucket` | Required: the test bucket the server stores in. |
|
|
313
|
+
| `headers` | Headers for every request to the server, never to the bucket: an object such as `{ cookie: "session=alice" }`, or a function, possibly async, that returns them. `origin` is always `http://localhost`. |
|
|
314
|
+
| `basePath` | The server's `basePath`: a path without a trailing slash. Default `"/api/cloudrop"`. |
|
|
315
|
+
|
|
316
|
+
A missing `bucket`, or a `basePath` that is not a path, throws `INVALID_CONFIG`. A `basePath` other than the server's
|
|
317
|
+
fails each upload with `NOT_FOUND` ("There is no cloudrop endpoint at this path. Check basePath.").
|
|
318
|
+
|
|
319
|
+
### `memoryStore(options?)`
|
|
320
|
+
|
|
321
|
+
`memoryStore()`, or `memoryStore({ transaction: false })`, returns a store without transactions: `onComplete` runs under
|
|
322
|
+
a lease, as with `sqlStore(executor)`. `memoryStore({ transaction: true })` adds `transaction` and `store.route`, as
|
|
323
|
+
`sqlStore(executor, { transaction: true })` does; `onComplete` of a route built with `store.route` receives `tx`, which
|
|
324
|
+
is `undefined`, since there is no database to write through. A route built with another store's `store.route`, such as
|
|
325
|
+
your database store's, is refused by `createCloudrop`; build the routes your tests share with plain `route()`, or from a
|
|
326
|
+
function that takes the store. Test the writes your `onComplete` makes through `tx` against your real database.
|
|
327
|
+
|
|
328
|
+
Each store is empty when created; create one per test.
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
This page is for anyone whose uploads fail, in development or in production. It lists symptoms you may meet while
|
|
4
|
+
setting up or running cloudrop, the usual cause of each, and how to fix it. Each section starts with what you see. For
|
|
5
|
+
the meaning of every error code, see [Errors](errors.md).
|
|
6
|
+
|
|
7
|
+
## Every upload ends in NETWORK_ERROR
|
|
8
|
+
|
|
9
|
+
You see `NETWORK_ERROR` with "The file could not reach the storage service, or the storage service refused it" on every
|
|
10
|
+
upload, although the connection works and the calls to your server succeed.
|
|
11
|
+
|
|
12
|
+
**Check the bucket's CORS rule first.** A rule that misses the page's origin, or one of the headers cloudrop signs (or a
|
|
13
|
+
checksum header you add), blocks every `PUT`. The browser hides the reason from the page, so the client sees a network
|
|
14
|
+
failure and gives up only after its retry budget.
|
|
15
|
+
|
|
16
|
+
- The browser console names what was blocked: the origin or the header.
|
|
17
|
+
- `npx cloudrop doctor --origin https://app.example.com` or
|
|
18
|
+
`cloudrop.api.checkBucket({ origins: ["https://app.example.com"] })` checks the rule, when the credentials may read
|
|
19
|
+
it. An R2 object token cannot, and reports `unknown` ("not checked"). `npx cloudrop setup --origin <origin> --apply`
|
|
20
|
+
adds the rule and keeps the bucket's others ([The cloudrop command](command.md)).
|
|
21
|
+
- The rule must allow `PUT` from the exact origin of the page, with `content-type`, `content-disposition`,
|
|
22
|
+
`if-none-match` and `x-amz-meta-cloudrop-id`. The full rule: [Bucket setup](bucket-setup.md).
|
|
23
|
+
|
|
24
|
+
Other causes that look the same from a page: R2 answers a refused upload URL (expired, or a bad signature) without CORS
|
|
25
|
+
headers, so the browser cannot read that answer either. The client renews the URL once and tries again before it gives
|
|
26
|
+
up.
|
|
27
|
+
|
|
28
|
+
## Every request gets ORIGIN_NOT_ALLOWED
|
|
29
|
+
|
|
30
|
+
Your pages get `ORIGIN_NOT_ALLOWED` ("This site may not upload here") from your own server, and the server log shows
|
|
31
|
+
"refused a request from https://app.example.com, but this server sees its own origin as http://…".
|
|
32
|
+
|
|
33
|
+
**Your app runs behind a proxy that terminates TLS or rewrites `Host`.** The handler sees its own origin in the request
|
|
34
|
+
URL and trusts no `X-Forwarded-*` header, so your own pages look cross-origin. List the app's public origin in
|
|
35
|
+
`trustedOrigins`:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
createCloudrop({
|
|
39
|
+
// ...
|
|
40
|
+
trustedOrigins: ["https://app.example.com"],
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The same fix applies when the page and the API are on different origins. The handler logs that warning once per refused
|
|
45
|
+
origin, for up to 16 origins. Both setups: [Deployment](deployment.md).
|
|
46
|
+
|
|
47
|
+
## Every upload ends UNAUTHORIZED from another origin
|
|
48
|
+
|
|
49
|
+
Uploads work when the page and the API share an origin, but a page on another origin always gets `UNAUTHORIZED`:
|
|
50
|
+
`authorize` finds no session because the browser did not send the cookie.
|
|
51
|
+
|
|
52
|
+
- **The page and the API are on different sites**, such as `app.example.com` and `api.example.net`. The session
|
|
53
|
+
cookie must be `SameSite=None; Secure`, and some browsers still block it as a third-party cookie. Put both on one
|
|
54
|
+
site, or send a bearer token with the client's `headers` option
|
|
55
|
+
([Send a bearer token](client.md#send-a-bearer-token)).
|
|
56
|
+
- **The cookie is set for the page's host only.** A cookie for `app.example.com` never reaches `api.example.com`. Set
|
|
57
|
+
it from the API's host or with `Domain=example.com`.
|
|
58
|
+
|
|
59
|
+
DevTools' Network panel shows whether the `/upload` request carried the cookie, and why the browser left it out. More:
|
|
60
|
+
[Deployment](deployment.md#cross-origin-an-api-on-another-origin).
|
|
61
|
+
|
|
62
|
+
## Requests through Node get 400
|
|
63
|
+
|
|
64
|
+
`toNodeHandler` answers `400` with `INVALID_INPUT` ("The request could not be read") when the request names no single
|
|
65
|
+
valid host: no `Host`, two `Host` headers, a malformed one, or a `host` that disagrees with HTTP/2's `:authority`. It
|
|
66
|
+
also refuses a request target that is not a path, such as `POST http://host/api/cloudrop/upload`. Browsers do not send
|
|
67
|
+
such requests; check what a proxy in front of Node forwards.
|
|
68
|
+
|
|
69
|
+
## Requests through Express get "The request body is not valid JSON"
|
|
70
|
+
|
|
71
|
+
Mount `toNodeHandler` **before** any body parser. A parser that reads the body first leaves nothing for cloudrop to
|
|
72
|
+
read, so cloudrop sees an empty body and answers `INVALID_INPUT`.
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
app.use("/api/cloudrop", toNodeHandler(cloudrop));
|
|
76
|
+
app.use(express.json()); // after
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## SERVER_ERROR: "The upload server sent an answer this client cannot read"
|
|
80
|
+
|
|
81
|
+
The client reached something that is not the cloudrop handler: a wrong `basePath`, a proxy's error page, or a server
|
|
82
|
+
running another cloudrop version. Check that `basePath` is the same on the server (`createCloudrop({ basePath })`) and
|
|
83
|
+
the client (`createCloudropClient({ basePath })`), and that the server answers at `<basePath>/upload`.
|
|
84
|
+
|
|
85
|
+
## Multipart uploads fail on Wrangler's local R2
|
|
86
|
+
|
|
87
|
+
Small files work, but a file over the multipart threshold fails at the end with `STORAGE_ERROR`: "The storage service
|
|
88
|
+
refused the request. Contact the site owner if this keeps happening." The server log says "The storage service does not
|
|
89
|
+
support this request".
|
|
90
|
+
|
|
91
|
+
**Wrangler's local R2 does not implement `ListParts`**, which the server needs to verify a multipart upload. Use RustFS
|
|
92
|
+
or real R2 to test multipart uploads. The failure is not retryable, so the client keeps no record to resume it:
|
|
93
|
+
`upload()` sends `/abort` at once, which removes the parts. A file of `start()` keeps its ticket and parts for `retry()`
|
|
94
|
+
until `abort()` or `pagehide`, which send `/abort`, or until the ticket expires; call `job.abort()` to remove them
|
|
95
|
+
sooner.
|
|
96
|
+
`checkBucket` there reports CORS and lifecycle as `unknown`, since Wrangler cannot report bucket settings. Details:
|
|
97
|
+
[`examples/next`](https://github.com/vcode-sh/cloudrop/blob/main/examples/next/README.md#run-with-wrangler-single-uploads-only).
|
|
98
|
+
|
|
99
|
+
## Resume does not work
|
|
100
|
+
|
|
101
|
+
`resumable()` always resolves `[]`, and `resume()` ends with `NOT_FOUND`.
|
|
102
|
+
|
|
103
|
+
- **The page is served over plain HTTP**, such as a LAN address like `http://192.168.1.20:3000`. Resuming needs a secure
|
|
104
|
+
context (HTTPS, or `localhost` in development), where browsers have Web Locks.
|
|
105
|
+
- **`persist: false`** is set on the client.
|
|
106
|
+
- **A different `namespace`.** A client sees only its own namespace's records.
|
|
107
|
+
- **The upload was not multipart.** Files sent in one `PUT` are never kept.
|
|
108
|
+
- **A polyfill loaded after the client.** The client looks for `indexedDB` and Web Locks once, when it is created.
|
|
109
|
+
|
|
110
|
+
More: [Resume after reload](resume.md#when-persistence-is-off-or-unavailable).
|
|
111
|
+
|
|
112
|
+
## resume() ends with UPLOAD_IN_USE
|
|
113
|
+
|
|
114
|
+
Another tab, or this page, still holds the upload: it is running, waiting for `retry()`, or waiting for the server to
|
|
115
|
+
answer its `/abort`. Finish or cancel it there, then try again. See [Two tabs](resume.md#two-tabs).
|
|
116
|
+
|
|
117
|
+
## resume() ends with INVALID_INPUT
|
|
118
|
+
|
|
119
|
+
The picked file is not the one the upload started with: the name, size, `lastModified`, type or the hash of its first
|
|
120
|
+
and last 64 KiB differ. Ask the user to pick the same file again.
|
|
121
|
+
|
|
122
|
+
## Every request answers 500 SERVER_ERROR
|
|
123
|
+
|
|
124
|
+
Every upload fails with `SERVER_ERROR` ("The upload server is not ready. Try again in a moment."), `cloudrop.api` calls
|
|
125
|
+
return `INVALID_CONFIG`, and the server log has one line starting with
|
|
126
|
+
`cloudrop: every request answers 500 until this is fixed.` The answer is retryable: the client tries each request again
|
|
127
|
+
with its backoff before the file fails, and a large upload in flight keeps its resume record, so once the setting is
|
|
128
|
+
fixed a reload can continue it.
|
|
129
|
+
|
|
130
|
+
**A setting that comes from the environment is missing or invalid.** cloudrop reads `CLOUDROP_SECRET` and the storage
|
|
131
|
+
presets' variables (`CLOUDROP_R2_*`, `CLOUDROP_S3_*`) on the first request, not when the server is created, so a build
|
|
132
|
+
needs no secrets and the server starts without them. The log line names every missing setting with its variable, and an
|
|
133
|
+
invalid value with the variable that holds it. Each request reads the environment again until it is complete, so values
|
|
134
|
+
your app sets on `process.env` after start (a secrets loader, say) take effect without a restart. For variables your
|
|
135
|
+
platform sets, restart or redeploy as usual. Once they are complete they are kept until the process restarts.
|
|
136
|
+
|
|
137
|
+
`npx cloudrop doctor --origin <origin>` (with `--env-file .env.local` for a file) names each missing or invalid
|
|
138
|
+
variable the same way, before you deploy ([The cloudrop command](command.md)).
|
|
139
|
+
|
|
140
|
+
With `NODE_ENV=development` the same settings are checked when the server is created, so a dev server fails as soon as
|
|
141
|
+
the server module loads instead (in `next dev`, on the first request to the cloudrop route).
|
|
142
|
+
|
|
143
|
+
## Text files fail at /complete with 502 STORAGE_ERROR on R2
|
|
144
|
+
|
|
145
|
+
The bytes reach the bucket, then `/complete` answers `502 STORAGE_ERROR` and the server log has
|
|
146
|
+
`The storage service's response had no content length.` Images and binary files upload fine. **Update to cloudrop
|
|
147
|
+
0.1.1 or later.** R2 compresses its answer to the `HEAD` request that verifies the stored size when the file has a
|
|
148
|
+
compressible type (`text/plain`, `application/json`, `text/html`, `image/svg+xml` and others) and is 50 bytes or more,
|
|
149
|
+
and then sends no `Content-Length`. Since 0.1.1 the driver asks for an uncompressed answer. On 0.1.0, a `fetch` option
|
|
150
|
+
for `r2()` or `s3()` that sets `accept-encoding: identity` on `HEAD` requests works around it.
|
|
151
|
+
|
|
152
|
+
## checkBucket reports unknown
|
|
153
|
+
|
|
154
|
+
`cloudrop doctor` shows the same as `NOT CHECKED`. The credentials may not read the bucket's settings (an R2 Object
|
|
155
|
+
Read & Write token cannot), the storage cannot report them (Wrangler's local R2), or you gave no origins. Check the settings with `wrangler r2 bucket cors list <bucket>` and
|
|
156
|
+
`wrangler r2 bucket lifecycle list <bucket>`, or in the dashboard. See
|
|
157
|
+
[What checkBucket can tell you](bucket-setup.md#what-checkbucket-can-tell-you).
|
|
158
|
+
|
|
159
|
+
## cloudrop doctor stops with "node: .env.local: not found"
|
|
160
|
+
|
|
161
|
+
`npx cloudrop doctor --env-file .env.local` prints `node: .env.local: not found` (or `invalid format`) and exits with
|
|
162
|
+
code 9, before any line of the command's own. **The file does not exist, or is a directory.** Node checks every
|
|
163
|
+
`--env-file` on its command line, even one meant for the command, and stops there. Fix the path; Bun runs the command,
|
|
164
|
+
which reports the file itself ([The cloudrop command](command.md#settings)).
|
|
165
|
+
|
|
166
|
+
## Retries after 429 come too fast
|
|
167
|
+
|
|
168
|
+
R2 answers concurrent writes to one key with `429` and `Retry-After: 5`, but the client retries sooner. **The CORS rule
|
|
169
|
+
does not expose `Retry-After`**, so the browser hides it and the client waits its own backoff alone. Add `Retry-After` to
|
|
170
|
+
the rule's exposed headers. See [Why expose Retry-After](bucket-setup.md#why-expose-retry-after).
|
|
171
|
+
|
|
172
|
+
## A dev server's first request logs bucket warnings
|
|
173
|
+
|
|
174
|
+
In development (`NODE_ENV=development`), the handler checks the bucket once and logs a warning for each missing setting:
|
|
175
|
+
the CORS rule for its own origin and `trustedOrigins`, the lifecycle rule, and private routes on a public bucket. Fix
|
|
176
|
+
what it names in [Bucket setup](bucket-setup.md).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudrop",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Fast, resumable, direct-to-bucket file uploads for Cloudflare R2 and S3-compatible storage.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -14,8 +14,12 @@
|
|
|
14
14
|
},
|
|
15
15
|
"type": "module",
|
|
16
16
|
"sideEffects": false,
|
|
17
|
+
"bin": {
|
|
18
|
+
"cloudrop": "./dist/cli.js"
|
|
19
|
+
},
|
|
17
20
|
"files": [
|
|
18
21
|
"dist",
|
|
22
|
+
"docs",
|
|
19
23
|
"CHANGELOG.md"
|
|
20
24
|
],
|
|
21
25
|
"engines": {
|
|
@@ -45,6 +49,10 @@
|
|
|
45
49
|
"types": "./dist/react.d.ts",
|
|
46
50
|
"default": "./dist/react.js"
|
|
47
51
|
},
|
|
52
|
+
"./testing": {
|
|
53
|
+
"types": "./dist/testing.d.ts",
|
|
54
|
+
"default": "./dist/testing.js"
|
|
55
|
+
},
|
|
48
56
|
"./adapters/sql": {
|
|
49
57
|
"types": "./dist/adapters/sql.d.ts",
|
|
50
58
|
"default": "./dist/adapters/sql.js"
|
|
@@ -59,7 +67,7 @@
|
|
|
59
67
|
}
|
|
60
68
|
},
|
|
61
69
|
"scripts": {
|
|
62
|
-
"build": "tsdown",
|
|
70
|
+
"build": "tsdown && bun ../../scripts/package-docs.ts",
|
|
63
71
|
"typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
|
|
64
72
|
"test": "vitest run --project unit",
|
|
65
73
|
"package:check": "../../scripts/check-package.sh"
|
|
@@ -78,7 +86,7 @@
|
|
|
78
86
|
},
|
|
79
87
|
"devDependencies": {
|
|
80
88
|
"@arethetypeswrong/cli": "^0.18.5",
|
|
81
|
-
"@cloudflare/workers-types": "5.
|
|
89
|
+
"@cloudflare/workers-types": "5.20261119.1",
|
|
82
90
|
"@libsql/client": "^0.18.0",
|
|
83
91
|
"@prisma/adapter-better-sqlite3": "^7.10.1",
|
|
84
92
|
"@prisma/adapter-pg": "^7.10.1",
|
|
@@ -93,12 +101,12 @@
|
|
|
93
101
|
"@types/react": "^19.3.0",
|
|
94
102
|
"@types/react-dom": "^19.3.0",
|
|
95
103
|
"aws4fetch": "^1.0.20",
|
|
96
|
-
"better-sqlite3": "^
|
|
104
|
+
"better-sqlite3": "^13.2.0",
|
|
97
105
|
"drizzle-orm": "1.0.0-rc.5",
|
|
98
|
-
"fast-check": "^4.10.
|
|
106
|
+
"fast-check": "^4.10.3",
|
|
99
107
|
"happy-dom": "^21.0.4",
|
|
100
108
|
"pg": "^8.23.1",
|
|
101
|
-
"postgres": "^4.
|
|
109
|
+
"postgres": "^4.1.1",
|
|
102
110
|
"prisma": "^7.10.1",
|
|
103
111
|
"publint": "^0.3.25",
|
|
104
112
|
"react": "^19.3.1",
|
|
@@ -106,7 +114,7 @@
|
|
|
106
114
|
"size-limit": "^14.3.0",
|
|
107
115
|
"tsdown": "^0.23.7",
|
|
108
116
|
"typescript": "^7.0.2",
|
|
109
|
-
"vitest": "^5.1.
|
|
110
|
-
"wrangler": "^4.
|
|
117
|
+
"vitest": "^5.1.1",
|
|
118
|
+
"wrangler": "^4.166.0"
|
|
111
119
|
}
|
|
112
120
|
}
|