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
package/docs/README.md
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# cloudrop documentation
|
|
2
|
+
|
|
3
|
+
The guides for this version of cloudrop, as published. The project's history (decisions, research, plans) is in the
|
|
4
|
+
repository: https://github.com/vcode-sh/cloudrop/blob/main/docs/README.md.
|
|
5
|
+
|
|
6
|
+
## Guides
|
|
7
|
+
|
|
8
|
+
For developers adding uploads to an app, in reading order:
|
|
9
|
+
|
|
10
|
+
1. [Server](server.md): `createCloudrop`, storage drivers, routes and who may use them, the upload token,
|
|
11
|
+
mounting the handler in your framework, origins, and the `cloudrop.api` file operations.
|
|
12
|
+
2. [Bucket setup](bucket-setup.md): the CORS and lifecycle rules for R2 and S3, credentials and permissions,
|
|
13
|
+
and what `checkBucket` reports. [The cloudrop command](command.md) checks the settings and the bucket
|
|
14
|
+
(`cloudrop doctor`) and adds the rules (`cloudrop setup`).
|
|
15
|
+
3. [Client](client.md): `cloudrop/client` without React: uploading, progress, pause, retry, concurrency and
|
|
16
|
+
offline.
|
|
17
|
+
4. [React](react.md): `useUpload` and `useResumable`, and how to build an upload UI on them.
|
|
18
|
+
5. [Resume after reload](resume.md): how a large upload survives a reload or a closed tab.
|
|
19
|
+
6. [Database store](store.md): a row per upload in your database, `onComplete` once, quotas, revocation and the
|
|
20
|
+
sweep.
|
|
21
|
+
7. [Deployment](deployment.md): same-origin and cross-origin setups, cookies, proxies, building without secrets,
|
|
22
|
+
Cloudflare Workers.
|
|
23
|
+
8. [Hono with better-auth and Drizzle](hono.md): a complete app, step by step, with a Vite SPA on another origin.
|
|
24
|
+
9. [Testing your app](testing-your-app.md): `cloudrop/testing`, your routes, store and a whole upload in your
|
|
25
|
+
own tests, with no bucket, browser or network.
|
|
26
|
+
|
|
27
|
+
When something goes wrong:
|
|
28
|
+
|
|
29
|
+
- [Errors](errors.md): every error code, where it comes from and what to do.
|
|
30
|
+
- [Troubleshooting](troubleshooting.md): symptoms and their usual causes.
|
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
# Bucket setup
|
|
2
|
+
|
|
3
|
+
This page is for whoever sets up the bucket and its credentials. It covers what your bucket needs before browsers can
|
|
4
|
+
upload to it: the CORS rule, in R2's format and in the S3 format, the lifecycle rule that cleans up abandoned uploads,
|
|
5
|
+
the Wrangler commands that set both on R2 and the AWS CLI commands for any S3-compatible service, which credentials and
|
|
6
|
+
permissions cloudrop needs, and what `checkBucket` can and cannot report about all of this.
|
|
7
|
+
|
|
8
|
+
The [cloudrop command](command.md) does most of this for you: `npx cloudrop setup --origin <origin>` prints these rules
|
|
9
|
+
and commands for your origins, `--apply` adds the rules to the bucket and keeps every other rule, and
|
|
10
|
+
`npx cloudrop doctor --origin <origin>` checks the settings, the bucket and its rules.
|
|
11
|
+
|
|
12
|
+
The rule lists the origin of the **page** that uploads, not the origin of your API: the browser sends the bytes from
|
|
13
|
+
the page. With the page and the API on different origins, see [Deployment](deployment.md).
|
|
14
|
+
|
|
15
|
+
## What any bucket needs
|
|
16
|
+
|
|
17
|
+
| Setting | Why |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| A CORS rule allowing `PUT` from your page's origin | Browsers upload to the bucket directly, from your page's origin. Without the rule, the browser blocks every upload. |
|
|
20
|
+
| The four headers cloudrop signs, in the rule's allowed headers | `content-type`, `content-disposition`, `if-none-match` and `x-amz-meta-cloudrop-id`. A preflight fails if one is missing. |
|
|
21
|
+
| `ETag` in the exposed headers | Only `checkBucket` needs it: its CORS check reports a problem without it. The client never reads `ETag`; the server gets part ETags from the bucket when it completes an upload. |
|
|
22
|
+
| `Retry-After` in the exposed headers (recommended) | Lets the client wait as long as the bucket asks after a `429` or `503`. |
|
|
23
|
+
| A lifecycle rule that aborts incomplete multipart uploads | Parts of an upload that never finished are removed instead of staying stored. |
|
|
24
|
+
|
|
25
|
+
Add your production origin and, for development, your local origin such as `http://localhost:5173`. `GET` and `HEAD`
|
|
26
|
+
in the examples below are for reading files back from a page; uploads need only `PUT`.
|
|
27
|
+
|
|
28
|
+
### Why expose Retry-After
|
|
29
|
+
|
|
30
|
+
A browser hides every answer header the CORS rule does not expose. With `Retry-After` exposed, a retry after a `429` or
|
|
31
|
+
`503` waits at least as long as the bucket asks (at most 20 s). Without it, the client cannot read the header and waits
|
|
32
|
+
its own backoff alone: a random wait up to 0.5 s, then 1 s, 2 s and so on. R2 answers concurrent writes to one key with
|
|
33
|
+
`429` and `Retry-After: 5`, which a page cannot read when the rule omits it (measured 2026-11-16,
|
|
34
|
+
[findings](https://github.com/vcode-sh/cloudrop/blob/main/docs/research/r2-spike-findings.md#bad-checksum-gone-upload-and-throttling-from-a-browser-2026-11-16)).
|
|
35
|
+
Uploads work without it, and `checkBucket` does not ask for it.
|
|
36
|
+
|
|
37
|
+
### Checksum headers
|
|
38
|
+
|
|
39
|
+
If you add a checksum header to uploads, such as `x-amz-checksum-crc32c`, add it to the allowed headers too. A rule that
|
|
40
|
+
misses any header a `PUT` carries blocks that `PUT`.
|
|
41
|
+
|
|
42
|
+
## Set the CORS rule on R2
|
|
43
|
+
|
|
44
|
+
Setting CORS replaces the bucket's whole policy. Read the current rules first and keep any you still need (or let
|
|
45
|
+
`cloudrop setup --apply` merge them):
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
wrangler r2 bucket cors list <bucket>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Write the rules to `cors.json` in R2's format, a `rules` array:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"rules": [
|
|
56
|
+
{
|
|
57
|
+
"allowed": {
|
|
58
|
+
"origins": ["https://app.example.com", "http://localhost:5173"],
|
|
59
|
+
"methods": ["PUT", "GET", "HEAD"],
|
|
60
|
+
"headers": ["content-type", "content-disposition", "if-none-match", "x-amz-meta-cloudrop-id"]
|
|
61
|
+
},
|
|
62
|
+
"exposeHeaders": ["ETag", "Retry-After"],
|
|
63
|
+
"maxAgeSeconds": 3600
|
|
64
|
+
}
|
|
65
|
+
]
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Then apply it:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
wrangler r2 bucket cors set <bucket> --file cors.json
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Wrangler needs to be signed in to your Cloudflare account. Pass `--jurisdiction eu` (or `fedramp`) for a bucket in a
|
|
76
|
+
jurisdiction. A change can take up to 30 seconds to apply, in rare cases.
|
|
77
|
+
|
|
78
|
+
## Set the CORS rule on S3 and other services
|
|
79
|
+
|
|
80
|
+
The S3 format is a list of rules. It is the shape `examples/next` and cloudrop's R2 measurements use:
|
|
81
|
+
|
|
82
|
+
```json
|
|
83
|
+
[
|
|
84
|
+
{
|
|
85
|
+
"AllowedOrigins": ["https://app.example.com", "http://localhost:5173"],
|
|
86
|
+
"AllowedMethods": ["PUT", "GET", "HEAD"],
|
|
87
|
+
"AllowedHeaders": ["content-type", "content-disposition", "if-none-match", "x-amz-meta-cloudrop-id"],
|
|
88
|
+
"ExposeHeaders": ["ETag", "Retry-After"],
|
|
89
|
+
"MaxAgeSeconds": 3600
|
|
90
|
+
}
|
|
91
|
+
]
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
AWS's `PutBucketCors` API and the AWS CLI wrap that list in `CORSRules`:
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"CORSRules": [
|
|
99
|
+
{
|
|
100
|
+
"AllowedOrigins": ["https://app.example.com"],
|
|
101
|
+
"AllowedMethods": ["PUT", "GET", "HEAD"],
|
|
102
|
+
"AllowedHeaders": ["content-type", "content-disposition", "if-none-match", "x-amz-meta-cloudrop-id"],
|
|
103
|
+
"ExposeHeaders": ["ETag", "Retry-After"],
|
|
104
|
+
"MaxAgeSeconds": 3600
|
|
105
|
+
}
|
|
106
|
+
]
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Wrangler refuses this `CORSRules` format: convert it to the `rules` format above for `wrangler r2 bucket cors set`.
|
|
111
|
+
To apply it with the AWS CLI, see [the next section](#set-both-rules-with-the-aws-cli).
|
|
112
|
+
|
|
113
|
+
## Set both rules with the AWS CLI
|
|
114
|
+
|
|
115
|
+
The AWS CLI sets the CORS rule and the lifecycle rule on AWS S3 and on S3-compatible services that implement these S3
|
|
116
|
+
calls (checked on RustFS). For a service other than AWS, point it at the service with `--endpoint-url`. Save the
|
|
117
|
+
`CORSRules` document above as `cors-s3.json` (not the R2 `cors.json`, whose format differs), and this as
|
|
118
|
+
`lifecycle.json`:
|
|
119
|
+
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"Rules": [
|
|
123
|
+
{
|
|
124
|
+
"ID": "abort-incomplete-uploads",
|
|
125
|
+
"Status": "Enabled",
|
|
126
|
+
"Filter": { "Prefix": "" },
|
|
127
|
+
"AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 1 }
|
|
128
|
+
}
|
|
129
|
+
]
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The empty prefix makes the rule apply to the whole bucket, which `checkBucket` requires. Then apply both:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# AWS CLI v2 reads AWS_REGION; v1 reads only AWS_DEFAULT_REGION, so set both.
|
|
137
|
+
export AWS_ACCESS_KEY_ID=<access key id> AWS_SECRET_ACCESS_KEY=<secret access key>
|
|
138
|
+
export AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1
|
|
139
|
+
ENDPOINT=http://127.0.0.1:9000 # your service's S3 endpoint; leave out --endpoint-url for AWS S3
|
|
140
|
+
|
|
141
|
+
aws s3api put-bucket-cors --bucket <bucket> --cors-configuration file://cors-s3.json --endpoint-url "$ENDPOINT"
|
|
142
|
+
aws s3api put-bucket-lifecycle-configuration --bucket <bucket> \
|
|
143
|
+
--lifecycle-configuration file://lifecycle.json --endpoint-url "$ENDPOINT"
|
|
144
|
+
|
|
145
|
+
# Read them back
|
|
146
|
+
aws s3api get-bucket-cors --bucket <bucket> --endpoint-url "$ENDPOINT"
|
|
147
|
+
aws s3api get-bucket-lifecycle-configuration --bucket <bucket> --endpoint-url "$ENDPOINT"
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Both commands replace the bucket's whole CORS or lifecycle configuration, so merge in any rules it already has. The
|
|
151
|
+
credentials need permission to change bucket settings, which upload credentials often lack. Use an admin key for this
|
|
152
|
+
step, not the key you give cloudrop. These commands were checked against RustFS, with `checkBucket` reporting both rules
|
|
153
|
+
`ok` afterwards.
|
|
154
|
+
|
|
155
|
+
## Add the lifecycle rule
|
|
156
|
+
|
|
157
|
+
An upload that is never completed or aborted leaves its parts in the bucket. The client sends `/abort` when it can, but
|
|
158
|
+
a closed tab or a crash can leave parts behind, and so can an upload whose 24-hour token expired. A lifecycle rule that
|
|
159
|
+
aborts incomplete multipart uploads removes them.
|
|
160
|
+
|
|
161
|
+
On R2, new buckets get a 7-day rule by default. Check what yours has:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
wrangler r2 bucket lifecycle list <bucket>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Add one if it is missing, for the whole bucket:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
wrangler r2 bucket lifecycle add <bucket> abort-incomplete-uploads --abort-multipart-days 1
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
On S3 and other services, set it with [the AWS CLI](#set-both-rules-with-the-aws-cli).
|
|
174
|
+
|
|
175
|
+
`checkBucket` accepts any enabled rule that applies to the whole bucket (no prefix) and aborts incomplete multipart
|
|
176
|
+
uploads, whatever its number of days. The example's RustFS setup uses one day.
|
|
177
|
+
|
|
178
|
+
## Credentials and permissions
|
|
179
|
+
|
|
180
|
+
The server needs credentials that can, in the bucket:
|
|
181
|
+
|
|
182
|
+
- write objects and run multipart uploads (create, upload parts, list parts, complete, abort), and sign upload URLs for
|
|
183
|
+
them;
|
|
184
|
+
- read object metadata (`HEAD`) and objects (for `api.getUrl`);
|
|
185
|
+
- delete objects (rejected and aborted uploads, `api.delete`, `api.deletePrefix`);
|
|
186
|
+
- list objects (`api.deletePrefix`).
|
|
187
|
+
|
|
188
|
+
On R2, an API token with **Object Read & Write** permission on the bucket does all of this; cloudrop's live tests run
|
|
189
|
+
with one. Create it in the Cloudflare dashboard under R2, then pass its access key ID and secret access key to `r2()` or
|
|
190
|
+
set `CLOUDROP_R2_ACCESS_KEY_ID` and `CLOUDROP_R2_SECRET_ACCESS_KEY`.
|
|
191
|
+
|
|
192
|
+
An Object Read & Write token cannot read the bucket's CORS or lifecycle settings (R2 answers `403 AccessDenied`), so
|
|
193
|
+
`checkBucket` reports those as `unknown`. Check them with Wrangler or in the dashboard instead.
|
|
194
|
+
|
|
195
|
+
The browser never sees any of these credentials: it gets only presigned URLs, each for one object, one method and 15
|
|
196
|
+
minutes.
|
|
197
|
+
|
|
198
|
+
## What checkBucket can tell you
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
const { data: report, error } = await cloudrop.api.checkBucket({ origins: ["https://app.example.com"] });
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
| Check | `ok` when | Reported `unknown` when |
|
|
205
|
+
| --- | --- | --- |
|
|
206
|
+
| `cors` | Every origin may `PUT` with the four signed headers, and `ETag` is exposed. | The credentials may not read CORS (R2 object tokens), the storage cannot report it (Wrangler's local R2 answers `501`), or no origin was given. |
|
|
207
|
+
| `lifecycle` | An enabled rule for the whole bucket aborts incomplete multipart uploads. | The credentials may not read lifecycle rules, or the storage cannot report them. Origins do not matter here. |
|
|
208
|
+
| `publicAccess` | No private route stores files on a bucket with a `publicUrl`. | Never: this check reads only your configuration. |
|
|
209
|
+
|
|
210
|
+
What it does not check:
|
|
211
|
+
|
|
212
|
+
- `Retry-After` in the exposed headers;
|
|
213
|
+
- checksum headers you add;
|
|
214
|
+
- what an R2 admin read token would show: R2's answers to one have not been measured yet.
|
|
215
|
+
|
|
216
|
+
Any other storage failure fails the call with an error instead of a report.
|
|
217
|
+
|
|
218
|
+
In development (`NODE_ENV=development`, exactly), the handler's first request runs `checkBucket` once in the background
|
|
219
|
+
for its own origin and `trustedOrigins`, and logs a warning for each problem.
|
|
220
|
+
|
|
221
|
+
## Local development
|
|
222
|
+
|
|
223
|
+
- **RustFS:** `bun run setup:rustfs` in [`examples/next`](https://github.com/vcode-sh/cloudrop/blob/main/examples/next/README.md#run-with-rustfs-the-default)
|
|
224
|
+
creates a bucket with the CORS rule and the lifecycle rule.
|
|
225
|
+
- **Wrangler's local R2:** needs no CORS rule (it lets any `localhost` page upload), and cannot complete multipart
|
|
226
|
+
uploads. See [Troubleshooting](troubleshooting.md#multipart-uploads-fail-on-wranglers-local-r2).
|
package/docs/client.md
ADDED
|
@@ -0,0 +1,386 @@
|
|
|
1
|
+
# Client
|
|
2
|
+
|
|
3
|
+
This page is for developers writing the browser side without React, or wanting to know what the hooks run on. It covers
|
|
4
|
+
`cloudrop/client`: creating a client, uploading one file or several, following progress, pausing, cancelling and
|
|
5
|
+
retrying, how the client shares connections between uploads, what happens when the page goes offline or a request
|
|
6
|
+
stalls, what it cleans up, and closing it when the user signs out. Resuming after a reload, and `resumable()`, `resume()`, `discard()` and `forget()`, have
|
|
7
|
+
their own page: [Resume after reload](resume.md). Error codes: [Errors](errors.md).
|
|
8
|
+
|
|
9
|
+
## Create a client
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
"use client";
|
|
13
|
+
import { createCloudropClient } from "cloudrop/client";
|
|
14
|
+
import type { cloudrop } from "../lib/cloudrop"; // a type import: no server code or secret reaches the browser
|
|
15
|
+
|
|
16
|
+
const client = createCloudropClient<typeof cloudrop>();
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Import the server with `import type`. A value import would pull the server, its storage driver and its secret settings
|
|
20
|
+
into the browser bundle. The type is enough for the client to know your route names, each route's metadata and what
|
|
21
|
+
each route's `onComplete` returns.
|
|
22
|
+
|
|
23
|
+
| Option | What it does | Default |
|
|
24
|
+
| --- | --- | --- |
|
|
25
|
+
| `basePath` | Where the server's handler is mounted: a path on this page's origin, or an absolute URL such as `"https://api.example.com/api/cloudrop"`. No trailing slash, query or fragment. For a handler on another origin, list the page's origin in the server's `trustedOrigins`, or every call gets `ORIGIN_NOT_ALLOWED`. | `"/api/cloudrop"` |
|
|
26
|
+
| `headers` | Headers for the requests to your server (`/upload`, `/sign`, `/complete`, `/abort`), never for bucket `PUT`s: an object, or a function, possibly async, called before each request (see [Send a bearer token](#send-a-bearer-token)). | none |
|
|
27
|
+
| `fetch` | Replaces the global `fetch`, for tests and runtimes that bring their own. Passing it also sends bucket `PUT`s through it (see [Transports](#transports-xhr-or-fetch)). | global `fetch` |
|
|
28
|
+
| `concurrency` | How many bucket `PUT`s the client sends at once, across all its uploads: `"auto"` or a whole number from 1 to 16 (see [Concurrency and order](#concurrency-and-order)). | `"auto"` |
|
|
29
|
+
| `order` | Which `PUT`s go first when they wait for a connection: `"added"` or `"smallest-first"`. | `"added"` |
|
|
30
|
+
| `persist` | Keeps unfinished multipart uploads in IndexedDB so they can resume after a reload. `false` keeps nothing on disk. | `true` |
|
|
31
|
+
| `namespace` | Keeps one signed-in user's unfinished uploads apart from another's: pass the user's id. At most 256 characters. | `""` |
|
|
32
|
+
|
|
33
|
+
A wrong option throws `INVALID_CONFIG` when the client is created. Wire types (`UploadRequest`, `FileTicket`,
|
|
34
|
+
`ErrorBody` and the rest) and the route inference types (`RouteName`, `RouteMetadata`, `RouteResult`,
|
|
35
|
+
`InferableCloudrop`) are imported from `cloudrop/client`, never from `cloudrop`.
|
|
36
|
+
|
|
37
|
+
In React, [`cloudrop/react`](react.md) creates the client for you and gives you hooks for inputs, drop zones and
|
|
38
|
+
progress.
|
|
39
|
+
|
|
40
|
+
### Send a bearer token
|
|
41
|
+
|
|
42
|
+
The client sends cookies to your server. An app that keeps its session in a token instead, such as a desktop or mobile
|
|
43
|
+
shell around a web view, or a session handed over by QR code, adds it with the `headers` option:
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
const client = createCloudropClient<typeof cloudrop>({
|
|
47
|
+
basePath: "https://api.example.com/api/cloudrop",
|
|
48
|
+
headers: async () => ({ authorization: `Bearer ${await getToken()}` }), // your app's token, refreshed when needed
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
On the server, `authorize` reads `request.headers.get("authorization")`.
|
|
53
|
+
|
|
54
|
+
- **Only your server gets them.** The headers go with `/upload`, `/sign`, `/complete` and `/abort`, never with a
|
|
55
|
+
bucket `PUT`: a presigned URL must not carry your token, and bucket `PUT`s keep `XMLHttpRequest` and its byte-by-byte
|
|
56
|
+
progress (see [Transports](#transports-xhr-or-fetch)).
|
|
57
|
+
- **A function runs before each request,** so each request carries the token of its moment, and a token that expires
|
|
58
|
+
during a long upload is refreshed for the next `/sign` or `/complete`. An object is sent as it is with every request.
|
|
59
|
+
- **When the function throws or rejects,** that request is not sent and fails with `NETWORK_ERROR`, which the client
|
|
60
|
+
retries as any network failure. Its time counts against the request's timeout, and a cancel stops the wait.
|
|
61
|
+
- **`content-type` stays the client's.** A `content-type` among the headers is replaced by `application/json`.
|
|
62
|
+
- **At sign-out, await [`close()`](#close-the-client)** before the session the function reads ends: each `/abort`
|
|
63
|
+
calls the function too. Return no headers rather than throw when signed out: `/abort` needs only the upload token.
|
|
64
|
+
- **At `pagehide`, an async function may be too late.** The `/abort` a closing page sends for a failed file waits for
|
|
65
|
+
it, and a page that is gone sends nothing. The bucket's lifecycle rule and, with a store, the sweep clean up.
|
|
66
|
+
- **From a page on another origin,** the `authorization` header makes the browser send a preflight first. The handler
|
|
67
|
+
allows the headers a page on a `trustedOrigins` origin asks for.
|
|
68
|
+
- **A request without an `Origin` header,** as a native app sends, needs no `trustedOrigins` entry (see
|
|
69
|
+
[Origins](server.md#origins)).
|
|
70
|
+
|
|
71
|
+
## Upload one file
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
const controller = new AbortController();
|
|
75
|
+
const { data, error } = await client.upload("avatar", file, { signal: controller.signal });
|
|
76
|
+
|
|
77
|
+
if (error) {
|
|
78
|
+
showError(error.message); // your app's error display
|
|
79
|
+
} else {
|
|
80
|
+
console.log(data.file.key, data.data); // data.data is what onComplete returned, null without one
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
- `upload(route, file, options?)` sends one `File` and resolves to `{ data, error }`. It never rejects for an expected
|
|
85
|
+
failure.
|
|
86
|
+
- `options.metadata` is validated by the route's schema on the server. It is required when the route's schema requires
|
|
87
|
+
it, and TypeScript enforces that.
|
|
88
|
+
- `options.signal` cancels the upload: requests stop, the server is told, and the result is `ABORTED`.
|
|
89
|
+
- `data.file` is the stored file: `id`, `key`, `name`, `size`, `type` and `url` (the public URL on a public route,
|
|
90
|
+
otherwise `null`).
|
|
91
|
+
- No `this`: `const { upload } = createCloudropClient()` works too.
|
|
92
|
+
|
|
93
|
+
## Upload several files
|
|
94
|
+
|
|
95
|
+
Pass a list, such as an array or `input.files`, and `upload()` resolves to an `UploadResult` once every file has
|
|
96
|
+
settled:
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
const files = input.files; // a FileList, or null when the input has none
|
|
100
|
+
if (!files || files.length === 0) return;
|
|
101
|
+
const { data, error } = await client.upload("files", files);
|
|
102
|
+
|
|
103
|
+
for (const outcome of data?.files ?? []) {
|
|
104
|
+
if (outcome.status === "done") console.log(outcome.name, outcome.result.file.key);
|
|
105
|
+
else console.log(outcome.name, outcome.status, outcome.error.message); // "failed" or "aborted"
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
- `data.files` holds one outcome per file, in the order passed: `status: "done"` with its `result`, or `"failed"` or
|
|
110
|
+
`"aborted"` with its `error`.
|
|
111
|
+
- `error` is the error of the first file, in the order passed, that did not end done.
|
|
112
|
+
- Unlike other results, `data` stays when some files failed. It is `null` only when nothing started: wrong arguments, or
|
|
113
|
+
`/upload` refused the whole job (such as `TOO_MANY_FILES`).
|
|
114
|
+
- An error that belongs to one file carries `error.file`, `{ id, name }`.
|
|
115
|
+
- A value typed `File | File[]` fits neither `upload()` signature: pass it to `start()` and await `start(...).done`.
|
|
116
|
+
|
|
117
|
+
### Reset the file input
|
|
118
|
+
|
|
119
|
+
A browser fires no `change` event when the user picks the same file again, so clear the input after each pick. Copy the
|
|
120
|
+
files out of the input before you clear it.
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
input.addEventListener("change", () => {
|
|
124
|
+
const files = Array.from(input.files ?? []);
|
|
125
|
+
input.value = ""; // picking the same file again now fires change
|
|
126
|
+
if (files.length > 0) void client.upload("files", files);
|
|
127
|
+
});
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
In React, `getInputProps()` from [`cloudrop/react`](react.md#one-file) does this for you.
|
|
131
|
+
|
|
132
|
+
## Jobs: progress, pause and retry
|
|
133
|
+
|
|
134
|
+
`start()` gives you a handle to follow and control the upload while it runs:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
const files = input.files; // a FileList, or null when the input has none
|
|
138
|
+
if (!files || files.length === 0) return;
|
|
139
|
+
const job = client.start("files", files, { metadata, signal }); // a File, an array or a FileList
|
|
140
|
+
const unsubscribe = job.subscribe(() => render(job.getSnapshot()));
|
|
141
|
+
|
|
142
|
+
const first = job.files[0];
|
|
143
|
+
first?.pause(); first?.resume(); first?.abort(); // one file
|
|
144
|
+
job.pause(); job.resume(); job.abort(); // every file of the job
|
|
145
|
+
|
|
146
|
+
const { data, error } = await job.done;
|
|
147
|
+
const again = await job.retry(); // or job.files[0].retry(): the failed files again
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`input`, `metadata`, `signal` and `render` stand for your page's file input, the route's metadata, an optional
|
|
151
|
+
`AbortSignal` and your own rendering code.
|
|
152
|
+
|
|
153
|
+
- `start()` sends every file through one `/upload`, then runs each file on its own: one file failing or being
|
|
154
|
+
cancelled never stops another.
|
|
155
|
+
- `job.files` and `getSnapshot().files` are in the order the files were passed. Each file has an `id` (`"1"`, `"2"`, …)
|
|
156
|
+
that is unique per client.
|
|
157
|
+
- `job.done` resolves to the same `UploadResult` as `upload()` with a list, and never rejects.
|
|
158
|
+
|
|
159
|
+
### Snapshots and React
|
|
160
|
+
|
|
161
|
+
`getSnapshot()` returns the same object until something changes, so React's `useSyncExternalStore` works directly:
|
|
162
|
+
|
|
163
|
+
```tsx
|
|
164
|
+
import { useSyncExternalStore } from "react";
|
|
165
|
+
import type { UploadJob } from "cloudrop/client";
|
|
166
|
+
|
|
167
|
+
function Progress({ job }: { job: UploadJob<unknown> }) {
|
|
168
|
+
const snapshot = useSyncExternalStore(job.subscribe, job.getSnapshot);
|
|
169
|
+
return <progress value={snapshot.totals.progress} />;
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Each file in `snapshot.files` has:
|
|
174
|
+
|
|
175
|
+
| Field | Meaning |
|
|
176
|
+
| --- | --- |
|
|
177
|
+
| `status` | `queued`, `uploading`, `paused`, `completing`, `done`, `failed` or `aborted`. The last three are final. |
|
|
178
|
+
| `bytes`, `size` | Bytes sent and the file's size. |
|
|
179
|
+
| `progress` | From 0 to 1. |
|
|
180
|
+
| `speed` | Bytes per second, averaged over about 3 s. 0 unless uploading. |
|
|
181
|
+
| `eta` | Seconds left at the current speed; `null` while nothing moves. |
|
|
182
|
+
| `error`, `result` | The file's error, or its `/complete` result. |
|
|
183
|
+
|
|
184
|
+
`snapshot.totals` adds up `bytes`, `size`, `progress`, `speed` and `eta` over the files that did not fail or abort, so
|
|
185
|
+
a failed file never holds the job below 1. It also counts the `done`, `failed` and `aborted` files, and `count` is every
|
|
186
|
+
file of the job.
|
|
187
|
+
|
|
188
|
+
Listeners are called at once on a status change, at most every 100 ms while bytes flow, and every second while a file
|
|
189
|
+
uploads.
|
|
190
|
+
|
|
191
|
+
### Statuses
|
|
192
|
+
|
|
193
|
+
```text
|
|
194
|
+
queued -> uploading -> completing -> done
|
|
195
|
+
completing -> uploading (/complete reported parts missing)
|
|
196
|
+
queued or uploading -> paused -> (resume) -> queued
|
|
197
|
+
any status that is not final -> failed or aborted
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
A file is `queued` until its first bucket `PUT` gets a connection, `uploading` while its bytes go to the bucket, and
|
|
201
|
+
`completing` once every byte is sent and `/complete` runs. When `/complete` reports parts missing, the file goes back to
|
|
202
|
+
`uploading` to send them. A file resumed after `pause()` is `queued` again until it gets a connection. A file resumed
|
|
203
|
+
after a reload starts `queued` while its record is checked, then goes to `completing`, since its first request is
|
|
204
|
+
`/complete` (see [Resume after reload](resume.md#the-server-is-asked-first)).
|
|
205
|
+
|
|
206
|
+
### Pause and resume
|
|
207
|
+
|
|
208
|
+
- `pause()` stops a queued or uploading file's requests and keeps the parts already stored in the bucket. A file that
|
|
209
|
+
is completing (its bytes all sent) ignores it.
|
|
210
|
+
- `resume()` sends only the parts not yet stored in the bucket. A single `PUT` starts again from the beginning.
|
|
211
|
+
- `job.pause()` and `job.resume()` do that for every file.
|
|
212
|
+
|
|
213
|
+
### Test pause and progress locally
|
|
214
|
+
|
|
215
|
+
On `localhost` an upload finishes before you can press Pause. Slow it down:
|
|
216
|
+
|
|
217
|
+
- In Chrome's DevTools, open the Network panel and pick a throttling profile such as "Slow 4G", or add a custom one.
|
|
218
|
+
It slows the tab's bucket `PUT`s too, so progress, speed and Pause have time to show. The Offline profile fires the
|
|
219
|
+
page's `offline` event, which pauses the uploads (see [Offline](#offline)).
|
|
220
|
+
- Use a file over the server's `multipartThreshold` to see parts. In development you can lower the threshold, as
|
|
221
|
+
[`examples/next`](https://github.com/vcode-sh/cloudrop/blob/main/examples/next/README.md) does with `multipartThreshold: "8MB"`.
|
|
222
|
+
- The example's `/lab` page can delay every bucket `PUT` and inject failures, and shows each request.
|
|
223
|
+
|
|
224
|
+
### Cancel
|
|
225
|
+
|
|
226
|
+
`abort()` on a file, `job.abort()`, or the `signal` you passed cancels: requests stop, the file ends `aborted`, and the
|
|
227
|
+
server is told to clean up with `/abort`. A file still waiting for its ticket ends `aborted` at once; a ticket that
|
|
228
|
+
arrives for it later only gets its `/abort`. A failed file ends `aborted` too, and the server is told to drop what it
|
|
229
|
+
kept for `retry()`.
|
|
230
|
+
|
|
231
|
+
The one exception: a file after a `/complete` that may have succeeded is kept, never deleted.
|
|
232
|
+
|
|
233
|
+
### Retry
|
|
234
|
+
|
|
235
|
+
- `job.files[n].retry()` sends a failed file again and resolves with its outcome.
|
|
236
|
+
- `job.retry()` does that for every failed file and resolves with an `UploadResult` of the job's current outcomes once
|
|
237
|
+
every file has settled. Its `data` is `null` when its `/upload` for every file was refused, as with `done`.
|
|
238
|
+
- A retry reuses the file's ticket when it can, so the parts already stored in the bucket are not sent again and the
|
|
239
|
+
bytes stay counted.
|
|
240
|
+
- It asks `/upload` for a new ticket when the old one expired or was given up, or when the failure was one a new attempt
|
|
241
|
+
with the same ticket cannot fix: `UPLOAD_EXPIRED`, `INVALID_TOKEN`, `UPLOAD_REJECTED`, `VERIFICATION_FAILED`,
|
|
242
|
+
`NO_SUCH_UPLOAD`, or a file that never got a ticket. `job.retry()` asks for all of those files in one `/upload`. On a
|
|
243
|
+
new ticket the file starts again under a new key, and its `bytes` drop to 0.
|
|
244
|
+
- When a `/complete` may have succeeded, a retry sends `/complete` again first, never a second upload.
|
|
245
|
+
- `retry()` of a file that is still running waits for it to settle. Of a done or aborted file, it answers that outcome
|
|
246
|
+
at once.
|
|
247
|
+
- `job.done` keeps each file's first outcome, whatever a retry does later. The snapshot shows the current one.
|
|
248
|
+
|
|
249
|
+
## How files are sent
|
|
250
|
+
|
|
251
|
+
- Files up to the server's `multipartThreshold` (64 MiB by default) go in one `PUT`. Larger ones go in parts of 8 MiB
|
|
252
|
+
(16 MiB from 256 MiB, larger only when a file would need over 10,000 parts), read with `Blob.slice`, at most four
|
|
253
|
+
parts of one file at a time.
|
|
254
|
+
- Every part except the last has exactly the same size. R2 requires equal part sizes in a multipart upload, so the
|
|
255
|
+
server plans one part size per file and the client cuts the file by that plan.
|
|
256
|
+
- A request is tried up to 6 times with backoff: a random wait up to 0.5 s, then up to 1 s, 2 s and so on, at most 20 s.
|
|
257
|
+
When the answer carries `Retry-After`, the wait is at least that long (at most 20 s).
|
|
258
|
+
- An expired upload URL is renewed once.
|
|
259
|
+
- Parts that `/complete` reports missing are sent again, at most twice.
|
|
260
|
+
- Calls to your server send cookies (`credentials: "include"`), so `authorize` can read the session. Uploads to the
|
|
261
|
+
bucket send none.
|
|
262
|
+
|
|
263
|
+
A browser hides every answer header the bucket's CORS rule does not expose. Expose `Retry-After` in the rule, or the
|
|
264
|
+
client cannot read it and waits its own backoff alone. See [Bucket setup](bucket-setup.md).
|
|
265
|
+
|
|
266
|
+
### When /upload refuses one file
|
|
267
|
+
|
|
268
|
+
`/upload` answers per file. A file it refuses with a retryable error (the storage service failed or was busy while the
|
|
269
|
+
server started it) asks `/upload` again for itself alone, with the backoff above and within the attempts the job's
|
|
270
|
+
`/upload` left, while the job's other files go on.
|
|
271
|
+
|
|
272
|
+
- The file stays `queued` while it waits.
|
|
273
|
+
- Pausing it stops the wait until it resumes. Cancelling it ends it `aborted` at once, without another request.
|
|
274
|
+
- Going offline pauses it while it waits, after a refusal or after a later `/upload` that failed as a whole, whatever
|
|
275
|
+
the job's other files do; going back online asks at once. An `/upload` already sent is not stopped: a ticket it
|
|
276
|
+
brings waits paused.
|
|
277
|
+
- A refusal that is not retryable, such as a file over the size limit, fails the file at once.
|
|
278
|
+
|
|
279
|
+
## Concurrency and order
|
|
280
|
+
|
|
281
|
+
One client shares its connection slots between all its uploads. Each bucket `PUT` holds one slot, and one file has at
|
|
282
|
+
most four parts in flight. Calls to your server take no slot.
|
|
283
|
+
|
|
284
|
+
- **`concurrency: "auto"`** (the default) starts with 4 slots. After each 2 s in which the bytes sent rose by 10 % or
|
|
285
|
+
more while `PUT`s waited, it adds one, up to 8. A network error, a stall, or a `429` or `503` from the bucket halves
|
|
286
|
+
the slots.
|
|
287
|
+
- **A number from 1 to 16** fixes the slots.
|
|
288
|
+
- **`order: "added"`** (the default) sends files added earlier first. **`order: "smallest-first"`** sends smaller files
|
|
289
|
+
first, across every job of the client.
|
|
290
|
+
|
|
291
|
+
## Offline
|
|
292
|
+
|
|
293
|
+
When the page goes offline, every queued and uploading file pauses (`status: "paused"`) and resumes when the page is
|
|
294
|
+
back online.
|
|
295
|
+
|
|
296
|
+
- A file you paused stays paused. Your `pause()` or `resume()` of a file the network paused makes it yours.
|
|
297
|
+
- Files that start while the page is offline pause before any `PUT`.
|
|
298
|
+
- The `/upload` that starts a job, or that a `job.retry()` sends for several files, is not held: with no network it
|
|
299
|
+
fails those files with `NETWORK_ERROR` after its attempts, and `retry()` sends it again. A one-file `/upload` (a
|
|
300
|
+
file asking again after a refusal, a `file.retry()` that needs a new ticket) pauses while it waits.
|
|
301
|
+
|
|
302
|
+
## Stalled requests
|
|
303
|
+
|
|
304
|
+
In a browser, a bucket `PUT` that makes no progress for 30 s, or whose answer takes that long after the last byte,
|
|
305
|
+
counts as a network error and is tried again. Through `fetch`, which reports no progress, a `PUT` gets 30 s plus its
|
|
306
|
+
size at 100 KiB/s.
|
|
307
|
+
|
|
308
|
+
Calls to your server have a deadline for the whole answer: 30 s for `/upload` and `/sign`, 120 s for `/complete`. A
|
|
309
|
+
missed deadline is a retryable `NETWORK_ERROR`, tried again within the same attempts. Each `/upload` ask carries a
|
|
310
|
+
random `idempotencyKey`, the same on all of its attempts, so a server with a database store releases what an attempt
|
|
311
|
+
whose answer never arrived reserved. A `/complete` that timed out counts as one that may have finished, so a cancel or a
|
|
312
|
+
failure afterwards keeps the file. `/abort` gets 10 s and is sent once; if it is missed, the bucket's lifecycle rule
|
|
313
|
+
cleans up.
|
|
314
|
+
|
|
315
|
+
## Transports: XHR or fetch
|
|
316
|
+
|
|
317
|
+
- In a browser, bucket `PUT`s go through `XMLHttpRequest`, which reports bytes while they are sent, so progress moves
|
|
318
|
+
smoothly.
|
|
319
|
+
- Passing the `fetch` option sends everything through it, `PUT`s included. A part's bytes then count only once it is
|
|
320
|
+
stored, so progress moves a part at a time. To add a token or other headers to your server's requests, use the
|
|
321
|
+
`headers` option instead: it leaves `PUT`s on `XMLHttpRequest`.
|
|
322
|
+
- Outside a browser (Node, Bun, Deno, Workers), `PUT`s use `fetch` the same way.
|
|
323
|
+
|
|
324
|
+
## What gets cleaned up
|
|
325
|
+
|
|
326
|
+
- **Cancelling** returns `ABORTED` and tells the server to clean up with `/abort`.
|
|
327
|
+
- **A single-`PUT` file of `upload()` that fails after `/upload`** is cleaned up the same way, in the background, so
|
|
328
|
+
`upload()` answers the error at once. `upload()` returns no handle to retry with, so there is nothing to keep.
|
|
329
|
+
- **A multipart file of `upload()` that fails** for a reason a later attempt can fix, such as the network, keeps its
|
|
330
|
+
parts and its resume record, so a reload can [resume](resume.md) it and send only the parts the bucket lacks; no
|
|
331
|
+
`/abort` is sent. One the bucket or the server refused, or whose ticket expired, is cleaned up as a single `PUT` is,
|
|
332
|
+
and so is every failed file with persistence off or unavailable.
|
|
333
|
+
- **A failed file of `start()`** keeps its ticket and the parts already stored in the bucket, so `retry()` can reuse
|
|
334
|
+
them, until `abort()` of the file or the job (or `options.signal`), `pagehide`, or the ticket's expiry (24 hours).
|
|
335
|
+
`abort()` tells the server with `/abort`. `pagehide` does too, except for a multipart file `upload()` would keep,
|
|
336
|
+
which keeps its parts and its resume record for a reload. The bucket's lifecycle rule removes unfinished parts nobody
|
|
337
|
+
resumes. A failed single-`PUT` object kept until expiry stays in the bucket: call `job.abort()` once you will not
|
|
338
|
+
retry.
|
|
339
|
+
- **A file after a `/complete` that may have succeeded** is always kept, never deleted.
|
|
340
|
+
- **[`close()`](#close-the-client)** cancels every file, or, without `abort`, keeps each multipart upload's record for
|
|
341
|
+
its user's next client.
|
|
342
|
+
|
|
343
|
+
## Close the client
|
|
344
|
+
|
|
345
|
+
`close()` stops a client for good, which an app with signed-in users needs when the user changes:
|
|
346
|
+
|
|
347
|
+
```ts
|
|
348
|
+
await client.close({ abort: true }); // at sign-out: cancel every upload, telling the server
|
|
349
|
+
await client.forget(); // then delete the user's unfinished uploads
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
- **Afterwards** `start()`, `upload()` and `resume()` answer `CLIENT_CLOSED` before any request, and a job's or a
|
|
353
|
+
file's `retry()` sends nothing. `resumable()`, `discard()` and `forget()` keep working. Create a new client for the
|
|
354
|
+
next user.
|
|
355
|
+
- **Every file of every route stops,** queued, uploading, paused, failed or waiting for its ticket, in any phase. A file
|
|
356
|
+
waiting for its ticket ends `aborted` at once, and its `/upload`, if in flight, is cancelled.
|
|
357
|
+
- **`close({ abort: true })`,** at sign-out, cancels each file as `abort()` does: its `/abort` goes with its own
|
|
358
|
+
upload token and `keepalive`, so a reload right after does not stop it, and the records of those uploads go.
|
|
359
|
+
- **`close()` without options,** when another user signed in in another tab, stops each file as closing the tab would.
|
|
360
|
+
A multipart upload sends no `/abort` and keeps its record, which the same user [resumes](resume.md) on a new client
|
|
361
|
+
after signing in again, in this page or after a reload. A single `PUT`, which cannot resume, is cancelled, and so is
|
|
362
|
+
every file when persistence is off or unavailable.
|
|
363
|
+
- **A file whose `/complete` may have finished** is kept, never deleted, either way.
|
|
364
|
+
- **It resolves** once every file it stopped has ended and each `/abort` it sent was answered; it never rejects. A file
|
|
365
|
+
in the middle of `/complete` waits for that answer, at most 2 minutes. Await it before a sign-out ends what a
|
|
366
|
+
`headers` function reads, or that function cannot give the `/abort`s their headers.
|
|
367
|
+
- **The first call decides,** and every later call does nothing but resolve with the first.
|
|
368
|
+
|
|
369
|
+
In React, the factory returns the same `close()`: [Signed-in users](react.md#signed-in-users).
|
|
370
|
+
|
|
371
|
+
## Errors that only the client produces
|
|
372
|
+
|
|
373
|
+
Five codes come from the client and never from the server:
|
|
374
|
+
|
|
375
|
+
- `UPLOAD_REJECTED`: the bucket refused the bytes as signed (a different size, type or checksum).
|
|
376
|
+
- `ABORTED`: a cancel.
|
|
377
|
+
- `NETWORK_ERROR`: no answer after every attempt. Retryable.
|
|
378
|
+
- `UPLOAD_IN_USE`: `resume()` or `discard()` found the upload held in this browser (see
|
|
379
|
+
[Resume after reload](resume.md#two-tabs)).
|
|
380
|
+
- `CLIENT_CLOSED`: `start()`, `upload()` or `resume()` after [`close()`](#close-the-client).
|
|
381
|
+
|
|
382
|
+
Every other code, and what to do about it: [Errors](errors.md).
|
|
383
|
+
|
|
384
|
+
Why the client behaves as it does: the [M3-S decisions](https://github.com/vcode-sh/cloudrop/blob/main/docs/decisions/m3-slice.md), the
|
|
385
|
+
[M3-U decisions](https://github.com/vcode-sh/cloudrop/blob/main/docs/decisions/m3-uploader.md) and, for `close()` and `headers`, the
|
|
386
|
+
[M8-L decisions](https://github.com/vcode-sh/cloudrop/blob/main/docs/decisions/m8-client.md).
|