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/command.md
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
# The cloudrop command
|
|
2
|
+
|
|
3
|
+
This page is for whoever sets up an app's storage. The package ships a `cloudrop` command with two subcommands:
|
|
4
|
+
`doctor` tells you in plain words what is missing in your settings and your bucket, and `setup` gives you the bucket's
|
|
5
|
+
CORS and lifecycle rules, or adds them to the bucket for you. It runs on Node 24 or later and on Bun.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx cloudrop doctor --origin https://app.example.com --origin http://localhost:5173
|
|
9
|
+
npx cloudrop setup --origin https://app.example.com # prints the rules and the commands
|
|
10
|
+
npx cloudrop setup --origin https://app.example.com --dry-run # shows what --apply would change
|
|
11
|
+
npx cloudrop setup --origin https://app.example.com --apply # adds them, keeping every other rule
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
`bunx cloudrop` works the same way. `--origin` names an origin your pages upload from (the page's, not your API's) and
|
|
15
|
+
is required; repeat it for each origin. An origin is exactly what the browser sends: scheme, host and port, in lower
|
|
16
|
+
case, with no path, not even a trailing `/`, and no `*`. Given `http://localhost:5173/`, the command answers with the
|
|
17
|
+
origin to use instead, `http://localhost:5173`; it refuses a pattern such as `https://*.example.com`, which no browser
|
|
18
|
+
sends: name each origin.
|
|
19
|
+
|
|
20
|
+
## Settings
|
|
21
|
+
|
|
22
|
+
The command reads the same variables as the library: `CLOUDROP_R2_ACCOUNT_ID`, `CLOUDROP_R2_BUCKET`,
|
|
23
|
+
`CLOUDROP_R2_ACCESS_KEY_ID` and `CLOUDROP_R2_SECRET_ACCESS_KEY` for R2, or the `CLOUDROP_S3_*` variables for another
|
|
24
|
+
S3-compatible service, and `CLOUDROP_SECRET`. When any `CLOUDROP_R2_*` variable is set it checks R2, otherwise S3.
|
|
25
|
+
|
|
26
|
+
- `--env-file <path>` also reads a file of `NAME=value` lines, such as `.env.local`, the way Node's `--env-file` does:
|
|
27
|
+
`export` in front of a name is allowed, a value in single quotes, double quotes or backticks is taken as written
|
|
28
|
+
and may run over several lines (`\n` in double quotes is a line break), and in an unquoted value `#` starts a
|
|
29
|
+
comment, so quote a value that contains one. Nothing in the file is run or expanded. A variable set in the environment
|
|
30
|
+
wins over the file, as with Node, and the command says so for each cloudrop variable set in both.
|
|
31
|
+
- **On Node, a missing `--env-file` stops before the command runs.** Node itself checks every `--env-file` on its
|
|
32
|
+
command line, the command's own included, and exits with code 9 and `node: .env.local: not found` (or
|
|
33
|
+
`invalid format` for a directory). Check the path. Bun runs the command, which reports the file with exit code 2.
|
|
34
|
+
- `--jurisdiction eu` (or `fedramp`) selects the endpoint of an R2 bucket in a jurisdiction, as `r2({ jurisdiction })`
|
|
35
|
+
does.
|
|
36
|
+
|
|
37
|
+
A name that is not a setting but looks like one, such as `CLOUDROP_R2_BUCKT` or `cloudrop_secret`, gets a `note` naming
|
|
38
|
+
the setting it was probably meant to be, among the settings of the service its name names. `CLOUDROP_R2_ENDPOINT` and
|
|
39
|
+
`CLOUDROP_R2_REGION` get a note that R2 needs neither. When settings for R2 and S3 are both set, a `note` says that R2
|
|
40
|
+
is checked.
|
|
41
|
+
|
|
42
|
+
The command never prints a setting's value, only its name. The commands it prints name the bucket as
|
|
43
|
+
`"$CLOUDROP_R2_BUCKET"` (or `"$CLOUDROP_S3_BUCKET"`), so they work in a shell that has the variable set.
|
|
44
|
+
|
|
45
|
+
## doctor
|
|
46
|
+
|
|
47
|
+
`doctor` checks, in order:
|
|
48
|
+
|
|
49
|
+
1. that every storage setting is present and valid, naming the variable to fix;
|
|
50
|
+
2. that `CLOUDROP_SECRET` is set and has at least 32 characters;
|
|
51
|
+
3. that the bucket answers and the credentials may list it (a listing, which tells a missing bucket from a missing
|
|
52
|
+
object). When it does not, the finding names the settings to check: the account ID (R2) or the endpoint (S3) when
|
|
53
|
+
the service cannot be reached, the keys, the bucket and `--jurisdiction` when it refuses them, the region (S3) when
|
|
54
|
+
it answers that the bucket is in another one;
|
|
55
|
+
4. the bucket's CORS rule for each `--origin` and its lifecycle rule, as `cloudrop.api.checkBucket` does.
|
|
56
|
+
|
|
57
|
+
Each line is one finding: `ok`, `PROBLEM` with what to do, `NOT CHECKED` with how to check by hand, or a `note`. The
|
|
58
|
+
last line sums them up. Against an R2 bucket with an Object Read & Write token it prints:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
cloudrop doctor: checking R2 settings, the bucket and its rules for http://localhost:5173.
|
|
62
|
+
ok R2 settings are present and valid (CLOUDROP_R2_*).
|
|
63
|
+
ok CLOUDROP_SECRET is set.
|
|
64
|
+
ok The bucket answers, and these credentials may list it.
|
|
65
|
+
NOT CHECKED CORS: These storage credentials may not read the bucket's CORS rules (R2 object tokens cannot). Check it with an admin read token or in the dashboard. By hand: wrangler r2 bucket cors list "$CLOUDROP_R2_BUCKET"
|
|
66
|
+
NOT CHECKED Lifecycle: These storage credentials may not read the bucket's lifecycle rules (R2 object tokens cannot). Check it with an admin read token or in the dashboard. By hand: wrangler r2 bucket lifecycle list "$CLOUDROP_R2_BUCKET"
|
|
67
|
+
No problems found. 2 checks could not run; see above.
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
An object token cannot read bucket settings, so those two checks are reported as not checked, never as a failure. Run
|
|
71
|
+
`doctor` with an admin token to check them too.
|
|
72
|
+
|
|
73
|
+
`doctor` writes nothing, so it does not prove that the credentials may upload: a read-only token lists the bucket as
|
|
74
|
+
well as a read-write one does. Give the app a token with Object Read & Write
|
|
75
|
+
([Credentials and permissions](bucket-setup.md#credentials-and-permissions)).
|
|
76
|
+
|
|
77
|
+
Your code may pass settings to `r2()`, `s3()` or `createCloudrop()` instead of the environment; `doctor` reads only the
|
|
78
|
+
environment and the env file, so it reports those settings as missing.
|
|
79
|
+
|
|
80
|
+
## setup
|
|
81
|
+
|
|
82
|
+
Without `--apply`, `setup` reaches nothing. It prints the CORS rule in R2's format (`cors.json` for Wrangler) and in the
|
|
83
|
+
S3 format (`cors-s3.json` for the AWS CLI), the lifecycle rule (`lifecycle.json`), and the commands that set them: the
|
|
84
|
+
Wrangler ones for R2, the AWS CLI ones for other services, both when no settings name the service. The rules are those
|
|
85
|
+
of [Bucket setup](bucket-setup.md): `PUT`, `GET` and `HEAD` from your origins with the four headers cloudrop signs,
|
|
86
|
+
`ETag` and `Retry-After` exposed, and an abort of incomplete multipart uploads after 1 day across the bucket.
|
|
87
|
+
|
|
88
|
+
Setting CORS with Wrangler or the AWS CLI replaces every rule the bucket has. List the current rules first and add the
|
|
89
|
+
ones you keep to the file, or use `--apply`.
|
|
90
|
+
|
|
91
|
+
With `--apply`, `setup` writes the rules through the S3 API (`PutBucketCors` and `PutBucketLifecycleConfiguration`):
|
|
92
|
+
|
|
93
|
+
- **It merges, it never replaces.** It reads the current rules and adds cloudrop's own rule: `cloudrop-uploads` for
|
|
94
|
+
CORS, `cloudrop-abort-incomplete` for lifecycle. Every other rule is written back as it was read, a lifecycle rule's
|
|
95
|
+
expirations, transitions and filters included, and so is the bucket's transition default on AWS.
|
|
96
|
+
- **It only adds.** When `cloudrop-uploads` exists, it gains what it lacks (an origin you pass, a method or header
|
|
97
|
+
cloudrop needs) where it stands; origins, headers and the max age already on it stay. To remove an origin, edit the
|
|
98
|
+
rule by hand.
|
|
99
|
+
- When another enabled rule already aborts incomplete multipart uploads across the bucket (R2 creates one by default),
|
|
100
|
+
the lifecycle rules are left as they are. When `cloudrop-abort-incomplete` exists but no longer does that (someone
|
|
101
|
+
disabled it or gave it a prefix), `setup` leaves the lifecycle rules alone, still writes the CORS rule, and reports
|
|
102
|
+
the problem (exit 1): fix or delete that rule by hand.
|
|
103
|
+
- It writes nothing for a setting that would not change.
|
|
104
|
+
- It needs credentials that may read and change bucket settings, such as an R2 Admin Read & Write token. Use it for
|
|
105
|
+
this step only; the app needs no more than Object Read & Write.
|
|
106
|
+
- When it cannot read the current rules, it writes nothing and exits 1. It also lists the bucket, as `doctor` does.
|
|
107
|
+
When the listing fails too, the keys, the bucket name or the network is the problem, and it names the settings to
|
|
108
|
+
check. When the listing works and the read was refused, the credentials may not read bucket settings, as an R2 object
|
|
109
|
+
token cannot; it names an R2 Admin Read & Write token, or S3's two permissions for the setting. `--replace` (with
|
|
110
|
+
`--apply` or `--dry-run`) writes cloudrop's rules alone instead, replacing what the bucket has, but only when the
|
|
111
|
+
read was refused (`403`). A read that failed for any other reason, such as a timeout or a service that does not
|
|
112
|
+
support it, never leads to a write. Neither does a configuration written in XML the command does not read (CDATA,
|
|
113
|
+
comments or namespace prefixes): check that bucket's rules by hand.
|
|
114
|
+
|
|
115
|
+
`--dry-run` does everything `--apply` does except the writes, and shows the result: which rule it would add or update
|
|
116
|
+
and which rules it would keep. R2 can take up to 30 seconds to apply a change; run `doctor` afterwards to check.
|
|
117
|
+
|
|
118
|
+
Wrangler's local R2 cannot read or write bucket settings (it answers `501`), and needs no CORS rule.
|
|
119
|
+
|
|
120
|
+
## Exit codes
|
|
121
|
+
|
|
122
|
+
| Code | Meaning |
|
|
123
|
+
| --- | --- |
|
|
124
|
+
| `0` | Nothing is wrong: every check passed or could not run, or `setup` printed, wrote or would write the rules. |
|
|
125
|
+
| `1` | `doctor` found a problem, or `setup` could not read, could not write, or found the settings incomplete. |
|
|
126
|
+
| `2` | A usage error: an unknown command or option, a missing `--origin`, a value that is not an exact origin, `--replace` without `--apply` or `--dry-run`, or an `--env-file` that cannot be read. |
|
|
127
|
+
| `9` | Node's own, not the command's: an `--env-file` that does not exist or is a directory (see [Settings](#settings)). |
|
|
128
|
+
|
|
129
|
+
In CI, `cloudrop doctor` fails the job on a problem and passes when it could only not check something.
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# Deployment
|
|
2
|
+
|
|
3
|
+
This page is for developers taking an app with cloudrop to production. It covers where the page, the API and the bucket
|
|
4
|
+
live, and what each setup needs: one origin for the page and the API, or an API on another origin, with cookies,
|
|
5
|
+
`trustedOrigins` and the bucket's CORS rule. It also covers a TLS proxy in front of the server, building without
|
|
6
|
+
secrets, and Cloudflare Workers.
|
|
7
|
+
|
|
8
|
+
## Three places, two kinds of request
|
|
9
|
+
|
|
10
|
+
An **origin** is a scheme, host and port, such as `https://app.example.com`. An upload involves three:
|
|
11
|
+
|
|
12
|
+
| Where | What it is | Example |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| The page | Where the browser runs your app and `cloudrop/client` | `https://app.example.com` |
|
|
15
|
+
| The API | Where `cloudrop.handler` is mounted (`basePath`) | `https://app.example.com/api/cloudrop` |
|
|
16
|
+
| The bucket | The storage endpoint the presigned URLs point at | `https://<account>.r2.cloudflarestorage.com` |
|
|
17
|
+
|
|
18
|
+
The browser makes two kinds of request:
|
|
19
|
+
|
|
20
|
+
- **Page to API:** `POST` to `/upload`, `/sign`, `/complete` and `/abort`, with cookies (`credentials: "include"`).
|
|
21
|
+
The API decides from them who may upload.
|
|
22
|
+
- **Page to bucket:** `PUT` of the bytes to presigned URLs, with no cookies. The bucket's CORS rule decides whether the
|
|
23
|
+
browser may send them.
|
|
24
|
+
|
|
25
|
+
So the bucket's CORS rule always lists the **page's** origin, never the API's: the bytes leave from the page. The
|
|
26
|
+
rule itself: [Bucket setup](bucket-setup.md).
|
|
27
|
+
|
|
28
|
+
## Same origin: the simple setup
|
|
29
|
+
|
|
30
|
+
When the page and the API share an origin, the browser sends the session cookie as a first-party cookie and the
|
|
31
|
+
client's default `basePath` (`/api/cloudrop`) reaches the handler. With one app serving both, no `trustedOrigins` is
|
|
32
|
+
needed; through a proxy or rewrite, list the page's origin (below). The bucket's CORS rule is needed either way.
|
|
33
|
+
|
|
34
|
+
You get one origin in either of two ways:
|
|
35
|
+
|
|
36
|
+
- **One app serves both**, such as a Next.js app with the handler in `app/api/cloudrop/[...all]/route.ts`.
|
|
37
|
+
- **A proxy or rewrite** sends `/api/cloudrop/*` on the page's origin to a separate API server. In Next.js:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
// next.config.ts
|
|
41
|
+
import type { NextConfig } from "next";
|
|
42
|
+
|
|
43
|
+
const config: NextConfig = {
|
|
44
|
+
async rewrites() {
|
|
45
|
+
return [{ source: "/api/cloudrop/:path*", destination: "https://api.internal.example.com/api/cloudrop/:path*" }];
|
|
46
|
+
},
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
export default config;
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The browser still sees one origin, but the API server now sees its own host in the request URL, not the page's. The
|
|
53
|
+
handler compares the page's `Origin` header with the origin it sees, so list the page's public origin on the API
|
|
54
|
+
server: `trustedOrigins: ["https://app.example.com"]`. The handler's log names both origins the first time it
|
|
55
|
+
refuses one.
|
|
56
|
+
|
|
57
|
+
## Cross-origin: an API on another origin
|
|
58
|
+
|
|
59
|
+
The page at `https://app.example.com` calls an API at `https://api.example.com`.
|
|
60
|
+
|
|
61
|
+
On the client, set an absolute `basePath`:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
const client = createCloudropClient<typeof cloudrop>({ basePath: "https://api.example.com/api/cloudrop" });
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
On the server, trust the page's origin. `basePath` stays the path on the API server:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
export const cloudrop = createCloudrop({
|
|
71
|
+
storage: r2(),
|
|
72
|
+
trustedOrigins: ["https://app.example.com"], // exact origins, never "*"
|
|
73
|
+
routes: { avatar },
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The handler answers the browser's CORS preflight for those origins and allows credentials, and the client already sends
|
|
78
|
+
cookies. What remains is the cookie itself:
|
|
79
|
+
|
|
80
|
+
- **Same site, different origin.** `app.example.com` and `api.example.com` share the site `example.com`, so the browser
|
|
81
|
+
sends cookies set for the API's host, or for `Domain=example.com`, even with `SameSite=Lax`. Ports do not change the
|
|
82
|
+
site either: `http://localhost:3000` and `http://localhost:4000` are different origins of one site.
|
|
83
|
+
- **Different sites.** For a page on `app.example.com` and an API on `api.example.net`, the session cookie must be
|
|
84
|
+
`SameSite=None; Secure`, and so served over HTTPS. Browsers that block third-party cookies may still drop it. If
|
|
85
|
+
you cannot put the page and the API on one site, send a token with the client's `headers` option instead, which
|
|
86
|
+
reaches only your server, never the bucket: [Send a bearer token](client.md#send-a-bearer-token).
|
|
87
|
+
|
|
88
|
+
With `authorize` that finds no session, every upload ends `UNAUTHORIZED`: check in the browser's DevTools whether the
|
|
89
|
+
`/upload` request carried the cookie.
|
|
90
|
+
|
|
91
|
+
A whole app in this shape, a Vite SPA on one origin and a Hono API with better-auth on another of the same site, step by
|
|
92
|
+
step and with its CORS middleware kept off cloudrop's path: [Hono with better-auth and Drizzle](hono.md).
|
|
93
|
+
|
|
94
|
+
## Behind a proxy that terminates TLS
|
|
95
|
+
|
|
96
|
+
The handler takes its own origin from the request URL and trusts no `X-Forwarded-*` header. Behind a load balancer or
|
|
97
|
+
reverse proxy that terminates TLS or rewrites `Host`, the server sees `http://internal-host:3000` while the page is on
|
|
98
|
+
`https://app.example.com`, so your own pages look cross-origin and get `ORIGIN_NOT_ALLOWED`. List the public origin:
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
createCloudrop({
|
|
102
|
+
// ...
|
|
103
|
+
trustedOrigins: ["https://app.example.com"],
|
|
104
|
+
});
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
More: [Origins](server.md#origins) and [Troubleshooting](troubleshooting.md#every-request-gets-origin_not_allowed).
|
|
108
|
+
|
|
109
|
+
## Build without secrets
|
|
110
|
+
|
|
111
|
+
Settings that come from the environment, `CLOUDROP_SECRET` and the storage presets' variables, are read on the first
|
|
112
|
+
request, not when the module loads. So `next build`, or a Docker build stage without secrets, loads your server module
|
|
113
|
+
without any of them. Pass the secrets to the running server only.
|
|
114
|
+
|
|
115
|
+
A setting still missing at run time makes every upload request answer `500 SERVER_ERROR`, and the server logs one line
|
|
116
|
+
starting `cloudrop: every request answers 500 until this is fixed.` Each request reads the environment again until it is
|
|
117
|
+
complete, so values your app sets on `process.env` after start (a secrets loader, say) take effect without a restart.
|
|
118
|
+
For variables your platform sets, restart or redeploy as usual. A health check catches the problem at deploy time: any
|
|
119
|
+
`cloudrop.api` call returns that `INVALID_CONFIG` error. With `NODE_ENV=development`, the settings are checked when the
|
|
120
|
+
server is created, so a dev server fails as soon as the server module loads (in `next dev`, on the first request to the
|
|
121
|
+
cloudrop route, which Next.js compiles on demand).
|
|
122
|
+
|
|
123
|
+
## Cloudflare Workers
|
|
124
|
+
|
|
125
|
+
A Worker gets its settings as the `env` argument of `fetch`, per request, while cloudrop reads only `process.env`. So
|
|
126
|
+
create the server from `env` yourself, passing every setting explicitly, and keep it for the life of the isolate:
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
import { createCloudrop, r2 } from "cloudrop";
|
|
130
|
+
import { routes } from "./routes"; // your routes, built with route()
|
|
131
|
+
|
|
132
|
+
interface Env {
|
|
133
|
+
CLOUDROP_SECRET: string;
|
|
134
|
+
CLOUDROP_R2_ACCOUNT_ID: string;
|
|
135
|
+
CLOUDROP_R2_ACCESS_KEY_ID: string;
|
|
136
|
+
CLOUDROP_R2_SECRET_ACCESS_KEY: string;
|
|
137
|
+
CLOUDROP_R2_BUCKET: string;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const createServer = (env: Env) =>
|
|
141
|
+
createCloudrop({
|
|
142
|
+
secret: env.CLOUDROP_SECRET,
|
|
143
|
+
storage: r2({
|
|
144
|
+
accountId: env.CLOUDROP_R2_ACCOUNT_ID,
|
|
145
|
+
accessKeyId: env.CLOUDROP_R2_ACCESS_KEY_ID,
|
|
146
|
+
secretAccessKey: env.CLOUDROP_R2_SECRET_ACCESS_KEY,
|
|
147
|
+
bucket: env.CLOUDROP_R2_BUCKET,
|
|
148
|
+
}),
|
|
149
|
+
routes,
|
|
150
|
+
});
|
|
151
|
+
|
|
152
|
+
export type Server = ReturnType<typeof createServer>; // for createCloudropClient<Server>() in the browser
|
|
153
|
+
|
|
154
|
+
let cloudrop: Server | undefined;
|
|
155
|
+
|
|
156
|
+
export default {
|
|
157
|
+
fetch(request: Request, env: Env) {
|
|
158
|
+
cloudrop ??= createServer(env); // once per isolate
|
|
159
|
+
return cloudrop.handler(request);
|
|
160
|
+
},
|
|
161
|
+
};
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
- Creating the server per request also works, but every call checks the options again and imports the token secret's
|
|
165
|
+
key: explicit settings are checked and loaded in `createCloudrop`, not lazily. Memoizing per isolate pays that once.
|
|
166
|
+
- A missing binding (`env.CLOUDROP_SECRET` is `undefined`) or a wrong value (a short secret, a malformed account id)
|
|
167
|
+
throws `INVALID_CONFIG` from `r2()` or `createCloudrop` inside `fetch`, so the Worker fails that request with an exception rather than a cloudrop 500.
|
|
168
|
+
- How the server's parallel storage calls fit Workers' subrequest limits has not been measured yet, and no test lane
|
|
169
|
+
runs cloudrop on Workers.
|
package/docs/errors.md
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Errors
|
|
2
|
+
|
|
3
|
+
This page is for developers handling cloudrop's errors in their app, and for anyone reading one in a log. It lists every
|
|
4
|
+
error code cloudrop produces: where it comes from, whether trying again can help, what it means, and what your app or
|
|
5
|
+
your user should do. It also explains the shape of an error and how errors move from the storage service through your
|
|
6
|
+
server to the browser.
|
|
7
|
+
|
|
8
|
+
## The shape of an error
|
|
9
|
+
|
|
10
|
+
Every public call returns `{ data, error }` instead of throwing for an expected failure. `error` is a `CloudropError`:
|
|
11
|
+
|
|
12
|
+
| Field | What it holds |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| `code` | A stable code from the tables below. Branch on this. |
|
|
15
|
+
| `message` | One or two sentences for a person: what happened and what to do next. Show this; never parse it. |
|
|
16
|
+
| `retryable` | `true` when the same request may succeed later. |
|
|
17
|
+
| `parts` | `PARTS_MISSING` only: the part numbers to send again. |
|
|
18
|
+
| `file` | In a job, the file the error belongs to: `{ id, name }`. |
|
|
19
|
+
| `status`, `storageCode` | On the server only: the storage service's HTTP status and own error code, for logs. Never shown to users. |
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
const { data, error } = await upload("avatar", file);
|
|
23
|
+
if (error) {
|
|
24
|
+
if (error.code === "FILE_TOO_LARGE") showError("Pick a file under 5 MB."); // your app's error display
|
|
25
|
+
else showError(error.message);
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Messages never contain credentials, presigned URLs or raw storage responses. The handler sends a client only an error's
|
|
30
|
+
`code`, `message`, `retryable` and `parts`; everything else goes to your server's `logger`.
|
|
31
|
+
|
|
32
|
+
**The client has already retried.** A retryable error that reaches your code has been through the client's attempts
|
|
33
|
+
(up to 6 per request, with backoff). Offer the user a retry button rather than retrying in a loop: `retry()` on a job or
|
|
34
|
+
file reuses what is already stored in the bucket (see [Client](client.md#retry)).
|
|
35
|
+
|
|
36
|
+
**Configuration errors are thrown.** `INVALID_CONFIG` is the one code that is thrown instead of returned: it needs a
|
|
37
|
+
code change, not a retry.
|
|
38
|
+
|
|
39
|
+
## How errors travel
|
|
40
|
+
|
|
41
|
+
1. **Storage driver.** The storage service answers, and the driver turns its answer into a code such as
|
|
42
|
+
`STORAGE_DENIED` or `RATE_LIMITED`. You see these codes directly from `cloudrop.api` calls.
|
|
43
|
+
2. **Server handler.** Before a storage failure reaches a browser, the handler logs the full error and replaces it with
|
|
44
|
+
one of two codes: `RATE_LIMITED` ("The storage service is busy") when the storage was throttling, otherwise
|
|
45
|
+
`STORAGE_ERROR`, retryable when the storage failure was. A browser never sees `STORAGE_DENIED`,
|
|
46
|
+
`STORAGE_UNREACHABLE`, `INVALID_PART` or `CHECKSUM_MISMATCH`.
|
|
47
|
+
3. **Client.** The client adds five codes of its own (`UPLOAD_REJECTED`, `ABORTED`, `NETWORK_ERROR`, `UPLOAD_IN_USE`,
|
|
48
|
+
`CLIENT_CLOSED`) and uses a few shared codes for its own failures, such as `STORAGE_ERROR` when the browser's
|
|
49
|
+
storage fails.
|
|
50
|
+
|
|
51
|
+
The HTTP status in the tables is what the handler answers with that code.
|
|
52
|
+
|
|
53
|
+
## Upload endpoint errors
|
|
54
|
+
|
|
55
|
+
These come from the handler, in answer to `/upload`, `/sign`, `/complete` or `/abort`.
|
|
56
|
+
|
|
57
|
+
| Code | HTTP | Retryable | What it means | What to do |
|
|
58
|
+
| --- | --- | --- | --- | --- |
|
|
59
|
+
| `UNAUTHORIZED` | 401 | No | `authorize` returned `unauthorized()`, or a plugin refused with this code. The message is the one `authorize` or the plugin gave. | Show the message; the user usually needs to sign in. |
|
|
60
|
+
| `FORBIDDEN` | 403 | No | `authorize` returned `forbidden()`, or a plugin refused with this code: the user is signed in but may not upload this, such as over a quota or on the wrong plan. | Show the message, which says what to do. Signing in again does not help. |
|
|
61
|
+
| `ORIGIN_NOT_ALLOWED` | 403 | No | The request came from an origin the handler does not accept. | Add the page's origin to `trustedOrigins`. Behind a proxy, add the app's public origin (see [Troubleshooting](troubleshooting.md#every-request-gets-origin_not_allowed)). |
|
|
62
|
+
| `METHOD_NOT_ALLOWED` | 405 | No | The request was not `POST` (or an `OPTIONS` preflight). | Send `POST`. Check that nothing else is mounted at the same path. |
|
|
63
|
+
| `UNSUPPORTED_MEDIA_TYPE` | 415 | No | The body was not sent as `Content-Type: application/json`. | Send JSON. The cloudrop client always does; check a proxy or custom client. |
|
|
64
|
+
| `BODY_TOO_LARGE` | 413 | No | The request body is over 64 KiB. | Send fewer files in one call. |
|
|
65
|
+
| `UNKNOWN_ROUTE` | 404 | No | No route has that name, or the token's route was removed or renamed by a deploy. | Check the route name. For an old token, start a new upload. |
|
|
66
|
+
| `INVALID_METADATA` | 400 | No | The metadata failed the route's schema, is over 2 KiB as JSON, or was sent to a route without a schema. The message names the first problem. | Fix the metadata the page sends. |
|
|
67
|
+
| `TOO_MANY_FILES` | 400 | No | More files than the route's `maxFiles` in one `/upload`. Refuses the whole job. | Send fewer files at once, or raise `maxFiles`. |
|
|
68
|
+
| `FILE_TOO_LARGE` | 400 | No | A file is over the route's `maxSize`. Refuses that file only. | Ask the user for a smaller file. |
|
|
69
|
+
| `FILE_TYPE_NOT_ALLOWED` | 400 | No | A file's type is not in `accept`, is not a valid MIME type, or its extension does not match its type. Refuses that file only. | Ask the user for another file, or rename it so the extension matches. |
|
|
70
|
+
| `QUOTA_EXCEEDED` | 403 | No | With a database store and `quota`: the file would take its owner past their storage limit (reserved plus stored bytes). Refuses that file only; the others of the same `/upload` may fit. | Show the message. The user frees space or the app raises their `quota`; then start the upload again. |
|
|
71
|
+
| `INVALID_TOKEN` | 400 | No | The upload token is not valid: not signed by a configured secret, or damaged. | Start the upload again. The client's `retry()` does this. |
|
|
72
|
+
| `UPLOAD_EXPIRED` | 410 | No | The upload's 24-hour token has expired. With a database store also "This upload was cancelled or has expired": the file's row was ended by `/abort`, `api.revokeUploads`, a refusal or the sweep, or the database has no row for it. | Start the upload again. The client's `retry()` does this, through `authorize`, so a signed-out user is refused. |
|
|
73
|
+
| `NOT_UPLOADED` | 409 | No | `/complete` found no object for a single `PUT`. | Upload the file, then complete it. The client does this in order. |
|
|
74
|
+
| `PARTS_MISSING` | 409 | No | `/complete` found parts missing or of the wrong size. `parts` lists them. | Nothing: the client sends those parts again and completes, at most twice. |
|
|
75
|
+
| `VERIFICATION_FAILED` | 422 | No | The stored file's size or type does not match what was declared, so it was deleted; or another file is stored under this upload's key. | Start a new upload. `retry()` asks for a new ticket. |
|
|
76
|
+
| `NO_SUCH_UPLOAD` | 410 | No | The multipart upload no longer exists: it was aborted or expired. | Start a new upload. `retry()` and `resume()` ask for a new ticket. |
|
|
77
|
+
| `ALREADY_EXISTS` | 409 | No | Another file already has this multipart upload's key. | Start a new upload. With a custom `key`, make keys unique. |
|
|
78
|
+
| `RATE_LIMITED` | 503 | Yes | The storage service was throttling while the server called it. | Try again in a moment. |
|
|
79
|
+
| `STORAGE_ERROR` | 502 | Sometimes | The server's call to the storage service failed (retryable), or the storage refused it (not retryable). Your server log has the details. | When retryable, try again. Otherwise check the server log: often credentials, permissions or the bucket name. |
|
|
80
|
+
| `SERVER_ERROR` | 500 | Sometimes | Something in the server failed: your `authorize`, `owner`, `onComplete` or a plugin threw, or cloudrop hit a bug. Retryable when the file is stored but `onComplete` or a hook did not finish, and while an environment setting is missing. With a database store, also retryable when the store failed ("could not reach its upload records"), when `quota` failed ("could not check your storage limit"), and while another request is completing the same file ("Another request is completing this upload", sent with `Retry-After: 2` and not logged). | Check the server log. When retryable, try again; the client does. |
|
|
81
|
+
| `NOT_FOUND` | 404 | No | There is no cloudrop endpoint at the requested path. | Check that `basePath` matches on the server and the client. |
|
|
82
|
+
| `INVALID_INPUT` | 400 | No | The request body is malformed: not a JSON object, no route name, no files, a bad file entry, an `idempotencyKey` that is not 16 to 128 letters, digits, `-` or `_`, wrong part numbers. The Node adapter also answers it for a request it cannot read. | Use the cloudrop client, or fix the request your own client sends. |
|
|
83
|
+
|
|
84
|
+
## Client errors
|
|
85
|
+
|
|
86
|
+
These come from `cloudrop/client`. The first five never come from the server.
|
|
87
|
+
|
|
88
|
+
| Code | Retryable | What it means | What to do |
|
|
89
|
+
| --- | --- | --- | --- |
|
|
90
|
+
| `NETWORK_ERROR` | Yes | No answer after every attempt: your server could not be reached, or the file could not reach the bucket. A bucket that refuses a `PUT` without CORS headers looks the same to a browser. Also when the client's `headers` function threw or rejected, so the request was not sent. | Check the connection and retry. If every upload ends this way, check the bucket's CORS rule first (see [Troubleshooting](troubleshooting.md#every-upload-ends-in-network_error)). |
|
|
91
|
+
| `UPLOAD_REJECTED` | No | The bucket refused the bytes as signed: a different size, type or checksum, a link refused even after renewal, or another refusal. | Start a new upload; `retry()` asks for a new ticket. When it keeps happening, check the server's clock and the credentials' permissions. |
|
|
92
|
+
| `ABORTED` | No | The upload was cancelled through `abort()` or the `signal`. | Nothing, unless the user wants to start again. |
|
|
93
|
+
| `UPLOAD_IN_USE` | No | `resume()` or `discard()` found the upload held in this page or another tab. | Finish or cancel it there, then try again. |
|
|
94
|
+
| `CLIENT_CLOSED` | No | `start()`, `upload()` or `resume()` on a client after its [`close()`](client.md#close-the-client), such as the last user's client after a sign-out. | Use the client of the user who is signed in now. |
|
|
95
|
+
| `RATE_LIMITED` | Yes | The bucket answered `429` or `503` to every attempt, or a proxy in front of your server answered `429`. | Try again in a moment. |
|
|
96
|
+
| `STORAGE_ERROR` (from the bucket) | Yes | The bucket answered a `PUT` with `408` or a `5xx` other than `501` on every attempt. A `501` ends the file with `UPLOAD_REJECTED` instead. | Retry the upload. |
|
|
97
|
+
| `NO_SUCH_UPLOAD` (from the bucket) | No | The bucket answered a part's `PUT` with `404 NoSuchUpload`: the multipart upload was aborted (in another tab, by the sweep or by the bucket's lifecycle rule). The same code and message as the server's. | Start a new upload; `retry()` asks for a new ticket. |
|
|
98
|
+
| `STORAGE_ERROR` (from your server) | Yes / No | Your server's call to the storage service failed or was refused, as in the [endpoint table](#upload-endpoint-errors): such as bad credentials, or Wrangler's local R2 refusing a multipart completion. | When retryable, retry. Otherwise check the server log. |
|
|
99
|
+
| `STORAGE_ERROR` (browser storage) | No | The browser's storage for unfinished uploads could not be read or written. Only `resumable()`, `resume()`, `discard()` and `forget()` answer it; `discard()` also when the browser refuses Web Locks. | Nothing for the upload: a browser storage failure never stops uploads; only resuming after a reload may not work. |
|
|
100
|
+
| `SERVER_ERROR` | When HTTP 500+ | Your server sent an answer the client cannot read: a wrong `basePath`, a proxy's error page, or another cloudrop version. | Check that `basePath` points at the cloudrop handler and that server and client run the same cloudrop version. |
|
|
101
|
+
| `NOT_FOUND` | No | `resume()` found no unexpired record of that upload: it finished, was cancelled or expired, or persistence is off. `discard()` found it no longer listed: it finished, or was cancelled or discarded. | After `resume()`, start the upload again with `start()` or `upload()`. After `discard()`, read the list again: nothing is left to discard. |
|
|
102
|
+
| `INVALID_INPUT` | No | Wrong arguments: no route name, no `File`, options that are not an object, a `signal` that is not an `AbortSignal`, metadata that JSON cannot encode, a different file passed to `resume()`, or a wrong argument to `discard()` or `forget()`. | Fix the call. For `resume()`, ask the user to pick the same file again. |
|
|
103
|
+
|
|
104
|
+
A code the client does not know, from a newer server, passes through with its message.
|
|
105
|
+
|
|
106
|
+
## Storage driver and file API errors
|
|
107
|
+
|
|
108
|
+
These come from the storage driver, which you meet through `cloudrop.api` and in your server log. The handler turns
|
|
109
|
+
them into `RATE_LIMITED` or `STORAGE_ERROR` before a browser sees them (see [How errors travel](#how-errors-travel)).
|
|
110
|
+
|
|
111
|
+
| Code | Retryable | What it means | What to do |
|
|
112
|
+
| --- | --- | --- | --- |
|
|
113
|
+
| `INVALID_INPUT` | No | A bad argument: an invalid key, an `expiresIn` out of range, a `deletePrefix` prefix not ending in `/`, non-exact origins for `checkBucket`, or a size over the storage's limit. | Fix the argument; the message names it. |
|
|
114
|
+
| `STORAGE_UNREACHABLE` | Yes | The storage service could not be reached, or did not answer in time. | Check the endpoint and the network, then retry. |
|
|
115
|
+
| `STORAGE_DENIED` | No | The storage service refused the request: wrong access key, missing permission or wrong bucket name; or this server's clock is more than 15 minutes off; or a signed request expired. | Check the credentials, their permissions and the bucket name. For a clock error, sync the clock (NTP). |
|
|
116
|
+
| `STORAGE_ERROR` | Sometimes | The storage failed (retryable), the bucket does not exist, the storage does not support the request (such as Wrangler's local R2 and `ListParts`), or another refusal. | When retryable, retry. Otherwise follow the message. |
|
|
117
|
+
| `RATE_LIMITED` | Yes | The storage service is throttling (`429` or `503`). | Retry after a short delay. |
|
|
118
|
+
| `NOT_FOUND` | No | The object does not exist. | Check the key. `head()` answers `null` instead, and `delete()` succeeds. |
|
|
119
|
+
| `ALREADY_EXISTS` | No | A create-only write found an object with this key. | Choose a different key. |
|
|
120
|
+
| `NO_SUCH_UPLOAD` | No | The multipart upload no longer exists. | Start a new upload. |
|
|
121
|
+
| `INVALID_PART` | No | Parts are missing or have the wrong size at completion. | Upload them again, then complete. In `/complete`, the handler answers a retryable `STORAGE_ERROR` instead. |
|
|
122
|
+
| `CHECKSUM_MISMATCH` | No | The uploaded bytes do not match their checksum. | Upload them again. |
|
|
123
|
+
|
|
124
|
+
## Database store file API errors
|
|
125
|
+
|
|
126
|
+
With a [database store](store.md), `cloudrop.api.file`, `usage`, `revokeUploads`, `deleteFile`, `reconcile` and `sweep`
|
|
127
|
+
answer these. Without a store each answers `INVALID_CONFIG`: "api.<name> needs a database store. Pass store to
|
|
128
|
+
createCloudrop."
|
|
129
|
+
|
|
130
|
+
| Code | Retryable | What it means | What to do |
|
|
131
|
+
| --- | --- | --- | --- |
|
|
132
|
+
| `NOT_FOUND` | No | `deleteFile` found no completed file with this id: it never completed, or the store has no row for it. | Check the id; it is the `file.id` the upload returned. |
|
|
133
|
+
| `INVALID_INPUT` | No | An id or owner that is not 1 to 255 characters, a sweep `limit` outside 1 to 1,000, or a `graceMs` under 15 minutes. | Fix the argument; the message names it. |
|
|
134
|
+
| `SERVER_ERROR` | Yes | The database failed or could not be reached ("The server could not reach its upload records."). The server log has the database's error. | Try again. A sweep leaves a failed row for its next run and counts it in `failed`. |
|
|
135
|
+
| `STORAGE_ERROR`, `RATE_LIMITED` | Varies | `deleteFile` or `sweep` could not delete an object or abort a multipart upload. | As in the driver table above. The row stays as it was, so calling again finishes the work. |
|
|
136
|
+
|
|
137
|
+
## Configuration errors
|
|
138
|
+
|
|
139
|
+
| Code | Thrown by | What to do |
|
|
140
|
+
| --- | --- | --- |
|
|
141
|
+
| `INVALID_CONFIG` | `createCloudrop`, `route`, `r2`, `s3`, `createCloudropClient`, `toNextHandler`, `toNodeHandler`, a plugin's `extendRoute`, and the store adapters (`sqlStore`, `drizzleStore`, `prismaStore`); a store also throws it on its first call when a table or column is missing, which the handler logs while answering a retryable `SERVER_ERROR` | Fix the option the message names. A missing setting names its environment variable when there is one; a missing column names its table. |
|
|
142
|
+
|
|
143
|
+
Settings read from the environment (`CLOUDROP_SECRET`, `CLOUDROP_R2_*`, `CLOUDROP_S3_*`) are reported on the first
|
|
144
|
+
request instead of thrown, and `INVALID_CONFIG` then arrives in a result: the handler logs it (again only when the
|
|
145
|
+
message changes) and answers every request with a retryable `SERVER_ERROR` 500, every `cloudrop.api` call returns
|
|
146
|
+
`{ data: null, error }` with it, and a storage preset's own methods return it until its settings are complete. See
|
|
147
|
+
[Every request answers 500](troubleshooting.md#every-request-answers-500-server_error).
|
|
148
|
+
|
|
149
|
+
Why errors work this way: the error decisions in [docs/decisions](https://github.com/vcode-sh/cloudrop/blob/main/docs/decisions/README.md) and the design's
|
|
150
|
+
[failure classifier](https://github.com/vcode-sh/cloudrop/blob/main/docs/superpowers/specs/2026-11-15-cloudrop-design.md#62-failure-classifier).
|