cloudrop 0.2.0 → 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.
@@ -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).
package/docs/hono.md ADDED
@@ -0,0 +1,276 @@
1
+ # Hono with better-auth and Drizzle
2
+
3
+ This page adds cloudrop to an app built like this: a Hono API on Bun with better-auth, Drizzle on Postgres with
4
+ drizzle-kit migrations, a React SPA on another origin of the same site calling the API with cookies, background jobs
5
+ in a worker process, and shadcn on Base UI. The steps are in the order you take them. The working version of every
6
+ snippet is in [`examples/hono`](https://github.com/vcode-sh/cloudrop/blob/main/examples/hono/README.md) (the API and the worker) and
7
+ [`examples/vite-react`](https://github.com/vcode-sh/cloudrop/blob/main/examples/vite-react/README.md) (the web app), which run against RustFS and Postgres in
8
+ Docker with no credentials.
9
+
10
+ The page uses the layout of a monorepo with an API app, a web app, a worker app and shared packages (`@app/db` for the
11
+ schema and the pool, `@app/api` for oRPC). Adapt the names to yours.
12
+
13
+ ## 1. One package owns cloudrop
14
+
15
+ Give the server side a package of its own, say `@app/uploads`, that depends on `cloudrop` and exports a factory and its
16
+ type:
17
+
18
+ ```ts
19
+ // packages/uploads/src/index.ts
20
+ export function createUploads(deps: UploadsDeps) { /* step 5 */ }
21
+ export type Uploads = ReturnType<typeof createUploads>;
22
+ ```
23
+
24
+ Three places import cloudrop, each a different entry:
25
+
26
+ | Who | Imports | Why |
27
+ | --- | --- | --- |
28
+ | `@app/uploads` | `cloudrop`, `cloudrop/adapters/drizzle` | the server, its routes and the store |
29
+ | `@app/db` | `cloudrop/adapters/drizzle` | `cloudropPgTables()` in the schema (step 2) |
30
+ | the web app | `cloudrop/react`, `cloudrop/client` | the hooks and their client; the server only as `import type` |
31
+
32
+ If your repository checks which package may import which SDK, register those three. The web app must reach
33
+ `@app/uploads` only through `import type`: a value import pulls the server, the database driver and the secret's
34
+ settings into the browser bundle.
35
+
36
+ `drizzle-orm` is an optional peer dependency of cloudrop (`>=0.45.0 <1 || >=1.0.0-rc.5 <2`): it uses your app's copy,
37
+ so the store and your queries share one Drizzle.
38
+
39
+ ## 2. Declare the tables in your schema
40
+
41
+ cloudrop keeps two tables, `cloudrop_files` and `cloudrop_usage`. Declare them in a schema file of their own, beside
42
+ your other features:
43
+
44
+ ```ts
45
+ // packages/db/src/schema/cloudrop.ts
46
+ import { cloudropPgTables } from "cloudrop/adapters/drizzle";
47
+
48
+ export const { files: cloudropFiles, usage: cloudropUsage } = cloudropPgTables();
49
+ ```
50
+
51
+ Export it from the schema index (`export * from "./cloudrop"`), as you do for every feature. The time columns are
52
+ `timestamptz(3)`, millisecond precision, the same as `timestamp(name, { withTimezone: true, precision: 3 })`.
53
+
54
+ The tables are your app's: read them with your own Drizzle queries, which is how you list a user's files (step 6).
55
+ cloudrop's file API has no listing call because you already have the better one, a query you can join and page as
56
+ you like. Write to them only through cloudrop, which keeps each owner's usage in step with their files.
57
+
58
+ ## 3. Generate and apply the migration
59
+
60
+ ```sh
61
+ bun run db:generate # drizzle-kit generate: a migration with both tables, their indexes and CHECKs
62
+ bun run db:migrate # drizzle-kit migrate, as an explicit step
63
+ ```
64
+
65
+ Until the tables exist, every upload fails with a retryable `SERVER_ERROR` and the server logs which table is missing.
66
+ The store needs no session state, so it works through PgBouncer in transaction mode: its one setting, a 2 s
67
+ `lock_timeout` while it claims a file, is set with `set_config(..., true)`, local to the transaction.
68
+
69
+ ## 4. Mount the handler beside better-auth, outside your CORS middleware
70
+
71
+ ```ts
72
+ // apps/server/src/app.ts
73
+ const UPLOADS_PATH = "/api/cloudrop";
74
+
75
+ // X-CSRF-Token is oRPC's CSRF header (step 6).
76
+ const browserCors = cors({ origin: webOrigins, credentials: true, allowHeaders: ["Content-Type", "X-CSRF-Token"] });
77
+ app.use((c, next) => (c.req.path.startsWith(`${UPLOADS_PATH}/`) ? next() : browserCors(c, next)));
78
+
79
+ app.on(["GET", "POST"], "/api/auth/*", (c) => deps.handleAuth(c.req.raw));
80
+ app.on(["POST", "OPTIONS"], `${UPLOADS_PATH}/*`, (c) => deps.uploads.handler(c.req.raw));
81
+ ```
82
+
83
+ - The handler serves `POST` (`/upload`, `/sign`, `/complete`, `/abort`) and `OPTIONS`, their preflight. Any other
84
+ method gets Hono's 404; with `app.all` it gets cloudrop's `METHOD_NOT_ALLOWED`.
85
+ - **Skip cloudrop's path in a global `hono/cors`.** This is the trap. `hono/cors` answers every `OPTIONS` itself and
86
+ never calls the route, so cloudrop's own preflight, which checks the origin against its `trustedOrigins` and allows
87
+ the headers the page asks for, never runs. Uploads with cookies still pass while the app's list happens to allow
88
+ `Content-Type`; a client that sends an `Authorization` header ([bearer token](client.md#send-a-bearer-token)), or an
89
+ app list without `POST`, fails in the browser's preflight with a CORS error that names no cloudrop code. cloudrop sets
90
+ the CORS headers on its other answers too, so it needs nothing from the middleware. The browser lane proves the
91
+ preflight reaches cloudrop through the real app.
92
+ - `basePath` stays `/api/cloudrop`, the default, so the server needs no option for it.
93
+
94
+ ## 5. Authorize with the session
95
+
96
+ `authorize` reads the session the same way the API does, from the request's headers, and returns the user's id. With a
97
+ store, `owner` says whose quota a file counts against:
98
+
99
+ ```ts
100
+ // packages/uploads/src/index.ts
101
+ export function createUploads(deps: UploadsDeps) {
102
+ const store = drizzleStore(deps.db, { dialect: "postgres", transaction: true });
103
+ const signedIn = async ({ request }: { request: Request }) => {
104
+ const session = await deps.readSession(request.headers); // auth.api.getSession({ headers })
105
+ return session ? { userId: session.user.id } : unauthorized("Sign in to upload files.");
106
+ };
107
+ const uploads = createCloudrop({
108
+ storage: deps.storage,
109
+ store,
110
+ quota: () => deps.quotaBytes,
111
+ trustedOrigins: deps.webOrigins, // the web app's exact origins, as in better-auth's trustedOrigins
112
+ routes: { avatar, attachments }, // step 6
113
+ });
114
+ return uploads;
115
+ }
116
+ ```
117
+
118
+ The composition root builds it once: `createUploads({ db, storage: r2(), readSession: (headers) =>
119
+ auth.api.getSession({ headers }), webOrigins, quotaBytes })`. `trustedOrigins` is required because the web app is on
120
+ another origin: without it every call gets `ORIGIN_NOT_ALLOWED`. The cookie needs nothing special: the web app and the
121
+ API are the same site, so a host-only `SameSite=Lax` cookie on the API's host travels with `credentials: "include"`
122
+ ([Deployment](deployment.md#cross-origin-an-api-on-another-origin)).
123
+
124
+ ## 6. Define the routes
125
+
126
+ ```ts
127
+ avatar: store.route(
128
+ // replace: one avatar per user; the next completed avatar deletes the previous one.
129
+ { accept: "image/*", maxSize: "2MB", replace: true, authorize: signedIn },
130
+ {
131
+ prefix: ({ userId }) => `users/${userId}/avatar`,
132
+ owner: ({ userId }) => userId,
133
+ onComplete: async ({ tx, userId, file }) => {
134
+ const row = { key: file.key, fileId: file.id, updatedAt: new Date() };
135
+ await tx.insert(avatar).values({ userId, ...row }).onConflictDoUpdate({ target: avatar.userId, set: row });
136
+ },
137
+ },
138
+ ),
139
+ attachments: store.route(
140
+ { accept: "*/*", maxSize: "100MB", maxFiles: 10, authorize: signedIn },
141
+ { prefix: ({ userId }) => `users/${userId}/attachments`, owner: ({ userId }) => userId },
142
+ ),
143
+ ```
144
+
145
+ - `store.route` gives `onComplete` Drizzle's transaction as `tx`: the avatar row commits with cloudrop's record of the
146
+ upload, or neither does. Keep network calls out of it. `replace: true` deletes the previous avatar's row in that same
147
+ commit, and its object right after ([One file per owner](store.md#one-file-per-owner-replace)).
148
+ - Files above 64 MiB go in parts (`multipartThreshold` changes it; the example uses 8 MB so a demo file shows parts).
149
+ - To list a user's files, call `uploads.api.files({ owner: userId })`, a page at a time, or select from
150
+ `cloudropFiles` with your app's Drizzle where `owner` is the user and `status` is `completed`: the tables are yours.
151
+ To delete one, check its owner with `uploads.api.file(id)`, then call `uploads.api.deleteFile(id)`, which removes the
152
+ object and frees its bytes in the quota. The example's oRPC router `files` (`list`, `delete`, `avatar`) does both.
153
+ - Protect the RPC router against cross-site requests. oRPC accepts a `multipart/form-data` body, which a page on
154
+ another origin of the same site can post without a preflight, and the browser sends the `SameSite=Lax` session
155
+ cookie with it. Add oRPC's pair: `SimpleCsrfProtectionHandlerPlugin` from `@orpc/server/plugins` on the
156
+ `RPCHandler`, `SimpleCsrfProtectionLinkPlugin` from `@orpc/client/plugins` on the `RPCLink`, and allow its
157
+ `X-CSRF-Token` header in your CORS middleware. cloudrop's own endpoints need nothing: they require
158
+ `application/json` and check `Origin`.
159
+
160
+ ## 7. The web client
161
+
162
+ ```ts
163
+ // apps/web/src/lib/upload.ts
164
+ import { createCloudropClient } from "cloudrop/client";
165
+ import { createUploadHooks } from "cloudrop/react";
166
+ import { createContext, useContext } from "react";
167
+ import type { Uploads as Server } from "@app/uploads"; // types only
168
+
169
+ function createUploads(userId: string) {
170
+ const client = createCloudropClient<Server>({ basePath: `${API_ORIGIN}/api/cloudrop`, namespace: userId });
171
+ return { client, ...createUploadHooks<Server>({ client }) };
172
+ }
173
+ export type Uploads = ReturnType<typeof createUploads>;
174
+
175
+ const byUser = new Map<string, Uploads>();
176
+ export function uploadsFor(userId: string): Uploads {
177
+ const known = byUser.get(userId) ?? createUploads(userId);
178
+ byUser.set(userId, known);
179
+ return known;
180
+ }
181
+ export const UploadsContext = createContext(uploadsFor(""));
182
+ export const useUploads = () => useContext(UploadsContext);
183
+
184
+ // apps/web/src/app.tsx: keyed by the user, so a new user's components mount with that user's hooks.
185
+ const userId = authClient.useSession().data?.user.id ?? "";
186
+ useCloseOtherUsers(userId); // from Signed-in users in the React guide
187
+ // React 19 renders a context as its provider; on React 18 write <UploadsContext.Provider>.
188
+ <UploadsContext key={userId} value={uploadsFor(userId)}>
189
+ {/* the app */}
190
+ </UploadsContext>;
191
+
192
+ // In a component:
193
+ const { useUpload } = useUploads();
194
+ const { files, getInputProps } = useUpload("attachments", { multiple: true });
195
+ ```
196
+
197
+ - `basePath` is absolute: the handler is on the API's origin, not the page's.
198
+ - The client sends cookies with every call to it; the oRPC link and the better-auth client need
199
+ `credentials: "include"` of their own.
200
+ - **One client per user, with the user's id as `namespace`** ([Resume](resume.md#namespace-and-sign-out)). A client
201
+ lists and resumes only its namespace's records, so the next user of the browser never sees the last one's
202
+ unfinished uploads, even when that user closed the tab or let the session expire without signing out, and the first
203
+ user still finds them on their next sign-in. The namespace is fixed when the client is created, which is why the app
204
+ keys the context by the user: one module-level client, without a namespace, would show every user's records to
205
+ whoever signs in next. The cost is a context and a component remount when the user changes.
206
+ - At sign-out, await `useUploads().close({ abort: true })`, which cancels the user's uploads on every route and tells
207
+ the server, so their rows end `aborted`, then `useUploads().client.forget()`: the namespace hides the records,
208
+ `forget()` deletes them and the upload tokens they hold, and aborts none. Closing first keeps a file that would get
209
+ its ticket afterwards from asking for it. `useCloseOtherUsers` in [Signed-in users](react.md#signed-in-users) closes
210
+ the last user's client when the user changes without a sign-out on this page, keeping its unfinished uploads for
211
+ that user's next sign-in; the example's `src/lib/upload.ts` has it, and `src/components/auth-panel.tsx` the
212
+ sign-out.
213
+ - To drop one unfinished upload, call `useResumable().discard(upload)`: the server aborts it, which with the store
214
+ ends its row and frees the bytes it reserved, and the browser deletes its record
215
+ ([Discard one upload](resume.md#discard-one-upload)). The example's panel has Discard per row and Discard all, each
216
+ through `discard`.
217
+ - The hooks: [React](react.md). The example's drop zone (`getDropProps`, `getInputProps`, `isDragOver`), upload list,
218
+ unfinished-uploads panel and avatar picker are in `examples/vite-react/src/components`.
219
+
220
+ ## 8. The sweep, as a scheduled job
221
+
222
+ Abandoned uploads keep their reservation in the quota and may leave parts in the bucket until a sweep ends them
223
+ ([The sweep](store.md#the-sweep)). Run it from the worker as a scheduled job, not in the API:
224
+
225
+ ```ts
226
+ // The worker process, with BullMQ: a job scheduler adds the sweep job every hour. Any queue with cron schedules
227
+ // works the same way.
228
+ import { Queue, Worker } from "bullmq";
229
+
230
+ const connection = { host: "127.0.0.1", port: 6379 };
231
+ await new Queue("upload-sweep", { connection }).upsertJobScheduler(
232
+ "hourly",
233
+ { pattern: "41 * * * *", tz: "UTC" },
234
+ // BullMQ tries a job once unless told otherwise: here a failed sweep is retried after one minute, then after two.
235
+ { name: "sweep", opts: { attempts: 3, backoff: { type: "exponential", delay: 60_000 } } },
236
+ );
237
+ new Worker(
238
+ "upload-sweep",
239
+ async () => {
240
+ // Every page in one call; the time limit leaves the rest to the next run.
241
+ const { data, error } = await uploads.api.sweep({ all: true, signal: AbortSignal.timeout(10 * 60_000) });
242
+ if (error) throw error; // the queue retries the job
243
+ for (const stuck of data.reported) log.warn({ action: "upload_completion_stuck", id: stuck.id });
244
+ },
245
+ { connection },
246
+ );
247
+ ```
248
+
249
+ The worker builds its own `createUploads` with the same storage and database; it serves no requests, so its
250
+ `readSession` can answer `null`. Two sweeps at once are safe. `examples/hono/src/worker.ts` runs the same sweep on a
251
+ timer. An account deletion runs `uploads.api.eraseOwner(userId)` from the same job until it reports `done`
252
+ ([Erase an owner](store.md#erase-an-owner)).
253
+
254
+ ## 9. The bucket's CORS rule names the web origin
255
+
256
+ The browser sends the bytes from the page, so the bucket's CORS rule lists the web app's origins, never the API's, with
257
+ `PUT`, the four headers cloudrop signs (`content-type`, `content-disposition`, `if-none-match`,
258
+ `x-amz-meta-cloudrop-id`) and `ETag` and `Retry-After` exposed. Add a lifecycle rule that aborts incomplete multipart
259
+ uploads. Both, for R2 and S3: [Bucket setup](bucket-setup.md).
260
+
261
+ ## 10. Map uploads onto your Attachment component
262
+
263
+ shadcn's `Attachment` (in its registry) has five states. A file from `useUpload` maps onto them by
264
+ its `status`:
265
+
266
+ | cloudrop `status` | `Attachment` state | Second line |
267
+ | --- | --- | --- |
268
+ | `queued`, `paused` | `idle` | "Waiting", "Paused" |
269
+ | `uploading` | `uploading` | percent of the size, with a progress bar |
270
+ | `completing` | `processing` | the server verifies the object and runs `onComplete` |
271
+ | `done` | `done` | the size |
272
+ | `failed` | `error` | `file.error.code` and `file.error.message`, with Retry |
273
+ | `aborted` | `idle` | "Cancelled" |
274
+
275
+ `examples/vite-react/src/components/upload-row.tsx` is that mapping, with Cancel while the file runs and Retry once it
276
+ failed.