@softure-ai/files 0.1.2 → 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 +43 -0
- package/README.md +237 -10
- package/dist/client/index.d.ts +3 -0
- package/dist/client/index.d.ts.map +1 -0
- package/dist/client/index.js +6 -0
- package/dist/client/index.js.map +1 -0
- package/dist/client/send-upload.d.ts +26 -0
- package/dist/client/send-upload.d.ts.map +1 -0
- package/dist/client/send-upload.js +66 -0
- package/dist/client/send-upload.js.map +1 -0
- package/dist/client/upload-queue.d.ts +52 -0
- package/dist/client/upload-queue.d.ts.map +1 -0
- package/dist/client/upload-queue.js +164 -0
- package/dist/client/upload-queue.js.map +1 -0
- package/dist/contract.d.ts +41 -1
- package/dist/contract.d.ts.map +1 -1
- package/dist/index.d.ts +40 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +17 -4
- package/dist/index.js.map +1 -1
- package/dist/mcp/index.d.ts +65 -0
- package/dist/mcp/index.d.ts.map +1 -0
- package/dist/mcp/index.js +131 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/messages/en.d.ts +20 -0
- package/dist/messages/en.d.ts.map +1 -1
- package/dist/messages/en.js +20 -0
- package/dist/messages/en.js.map +1 -1
- package/dist/messages/index.d.ts +20 -0
- package/dist/messages/index.d.ts.map +1 -1
- package/dist/next/index.d.ts +2 -0
- package/dist/next/index.d.ts.map +1 -1
- package/dist/next/index.js +4 -2
- package/dist/next/index.js.map +1 -1
- package/dist/next/stored-file-route.d.ts +25 -0
- package/dist/next/stored-file-route.d.ts.map +1 -0
- package/dist/next/stored-file-route.js +14 -0
- package/dist/next/stored-file-route.js.map +1 -0
- package/dist/next/upload-route.d.ts +3 -0
- package/dist/next/upload-route.d.ts.map +1 -0
- package/dist/next/upload-route.js +11 -0
- package/dist/next/upload-route.js.map +1 -0
- package/dist/options.d.ts +6 -0
- package/dist/options.d.ts.map +1 -1
- package/dist/options.js +27 -0
- package/dist/options.js.map +1 -1
- package/dist/schema.d.ts +255 -0
- package/dist/schema.d.ts.map +1 -1
- package/dist/schema.js +17 -2
- package/dist/schema.js.map +1 -1
- package/dist/server/index.d.ts +7 -3
- package/dist/server/index.d.ts.map +1 -1
- package/dist/server/index.js +7 -3
- package/dist/server/index.js.map +1 -1
- package/dist/server/options.d.ts +2 -0
- package/dist/server/options.d.ts.map +1 -1
- package/dist/server/options.js +8 -0
- package/dist/server/options.js.map +1 -1
- package/dist/server/privacy.d.ts +6 -1
- package/dist/server/privacy.d.ts.map +1 -1
- package/dist/server/privacy.js +6 -3
- package/dist/server/privacy.js.map +1 -1
- package/dist/server/prune.d.ts +4 -0
- package/dist/server/prune.d.ts.map +1 -1
- package/dist/server/prune.js +4 -2
- package/dist/server/prune.js.map +1 -1
- package/dist/server/save.d.ts +15 -0
- package/dist/server/save.d.ts.map +1 -1
- package/dist/server/save.js +11 -9
- package/dist/server/save.js.map +1 -1
- package/dist/server/serve-upload.d.ts +6 -0
- package/dist/server/serve-upload.d.ts.map +1 -0
- package/dist/server/serve-upload.js +110 -0
- package/dist/server/serve-upload.js.map +1 -0
- package/dist/server/serve.d.ts +15 -0
- package/dist/server/serve.d.ts.map +1 -1
- package/dist/server/serve.js +38 -14
- package/dist/server/serve.js.map +1 -1
- package/dist/server/upload-page.d.ts +5 -0
- package/dist/server/upload-page.d.ts.map +1 -0
- package/dist/server/upload-page.js +87 -0
- package/dist/server/upload-page.js.map +1 -0
- package/dist/server/upload-tokens.d.ts +9 -0
- package/dist/server/upload-tokens.d.ts.map +1 -0
- package/dist/server/upload-tokens.js +43 -0
- package/dist/server/upload-tokens.js.map +1 -0
- package/dist/server/uploads.d.ts +73 -0
- package/dist/server/uploads.d.ts.map +1 -0
- package/dist/server/uploads.js +403 -0
- package/dist/server/uploads.js.map +1 -0
- package/migrations/0002_create_uploads.sql +33 -0
- package/module.json +9 -4
- package/package.json +17 -2
- package/src/client/index.ts +12 -0
- package/src/client/send-upload.ts +89 -0
- package/src/client/upload-queue.ts +220 -0
- package/src/contract.ts +45 -1
- package/src/index.ts +32 -5
- package/src/mcp/index.ts +206 -0
- package/src/messages/en.ts +20 -0
- package/src/next/index.ts +10 -2
- package/src/next/stored-file-route.ts +43 -0
- package/src/next/upload-route.ts +11 -0
- package/src/options.ts +28 -0
- package/src/schema.ts +20 -2
- package/src/server/index.ts +21 -3
- package/src/server/options.ts +8 -0
- package/src/server/privacy.ts +12 -4
- package/src/server/prune.ts +8 -2
- package/src/server/save.ts +25 -11
- package/src/server/serve-upload.ts +116 -0
- package/src/server/serve.ts +51 -14
- package/src/server/upload-page.ts +96 -0
- package/src/server/upload-tokens.ts +43 -0
- package/src/server/uploads.ts +437 -0
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,49 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
|
|
|
4
4
|
in production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
|
|
5
5
|
"Definition of done").
|
|
6
6
|
|
|
7
|
+
## 0.3.0
|
|
8
|
+
|
|
9
|
+
- `serveStoredFile(ctx, fileId, request, { ownerId, disposition? })` in `/server` and `createStoredFileRoute({ getOwnerId })`
|
|
10
|
+
in `/next` (#993): the signed-in owner gets a stored file with the answer of a link (`GET`, `HEAD`, single byte
|
|
11
|
+
ranges, the same headers, one `404` for anything missing or another owner's), `inline` by default, with no link to
|
|
12
|
+
mint. The route sits behind the app's sign-in guard (README §4.4). `serveFileLink` answers as before.
|
|
13
|
+
- Migration for an app that mints a link for its own viewing, or that rebuilt the answer from `findFile`, `openFile`
|
|
14
|
+
and `parseRangeHeader`: mount `createStoredFileRoute` under a guarded prefix and point the player or image at
|
|
15
|
+
`/<prefix>/<file id>`; drop the link minting or the copied answer.
|
|
16
|
+
- A browser client, `@softure-ai/files/client` (#988): `sendUpload(file, { uploadUrl, signal, onProgress, fetch })`
|
|
17
|
+
reads the session's `HEAD`, sends only the missing chunks in order with `Content-Range`, reports
|
|
18
|
+
`{ sentBytes, totalBytes }`, honours an `AbortSignal` and answers a `Result` (`files.upload_expired`,
|
|
19
|
+
`files.upload_rejected`, `files.network`, `files.upload_aborted`). `createUploadQueue({ open, finalize })` keeps an
|
|
20
|
+
upload list whose items theme-notion's `UploadItem` takes as they are, with `add`, `retry`, `pause`, `resume`,
|
|
21
|
+
`remove`, `getItems` and `subscribe` (for `useSyncExternalStore`). An app that carries its own chunk loop can drop it.
|
|
22
|
+
- The upload page runs the same `sendUpload` (inlined) and says when its link has expired (`uploadPage.expired`).
|
|
23
|
+
- New messages for the client's codes: `errors.files.upload_expired`, `upload_rejected`, `network`, `upload_aborted`.
|
|
24
|
+
- `registerFileUploadTools` takes `onFinalized(file, ctx)` (#987): it runs after every successful `finalize_upload`,
|
|
25
|
+
a repeated one included, and its returned fields join the answer; a returned `err(code)` answers that code. Also
|
|
26
|
+
`descriptions` (the served text of both tools, defaults exported as `FILE_UPLOAD_TOOL_DESCRIPTIONS`) and `hints`
|
|
27
|
+
(the text answered for an error code). Without them the tools answer as in 0.2.0.
|
|
28
|
+
- Migration for an app that wraps the server to replace the finalize handler or the descriptions: drop the wrapper and
|
|
29
|
+
pass `onFinalized` (its step after `finalizeUpload`, made idempotent), `descriptions` and `hints` instead.
|
|
30
|
+
|
|
31
|
+
## 0.2.0
|
|
32
|
+
|
|
33
|
+
- Resumable uploads from clients (#949): table `files.uploads` (migration 0002), `createUpload` (a signed upload URL
|
|
34
|
+
under the link keyring, limits `uploads.chunkBytes` 64 MiB, `uploads.ttlSeconds`, `uploads.maxOpenPerOwner`,
|
|
35
|
+
`uploads.contentTypes`, `maxFileBytes` and the quota checked up front), `getUpload`, `writeUploadChunk` and
|
|
36
|
+
`finalizeUpload` (every chunk, size and optional SHA-256 checked, saved like `saveFile`, idempotent).
|
|
37
|
+
- The upload route `serveUploadRoute` (`app/u/[...upload]/route.ts`, `GET`, `HEAD`, `PUT`): chunked with
|
|
38
|
+
`Content-Range`, resumable through `HEAD` and the JSON status, streamed with a cap, a browser upload page, and the
|
|
39
|
+
`files-upload` rate limit bucket (`FILES_RATE_LIMIT_BUCKETS`) when the security module is on. Keep `/u` outside the
|
|
40
|
+
sign-in guard and add an edge bypass for it, as for `/f`.
|
|
41
|
+
- `@softure-ai/files/mcp`: `registerFileUploadTools` (`create_upload` with a ready `curl` loop, `finalize_upload`),
|
|
42
|
+
`FILE_UPLOAD_MCP_TOOLS` for the catalog, `buildCurlUploadScript`. `@modelcontextprotocol/server` is a new optional
|
|
43
|
+
peer.
|
|
44
|
+
- `pruneFiles` also removes expired upload sessions with their chunks (`deletedUploads`, `failedUploads` in its
|
|
45
|
+
report); the privacy export lists open sessions (`uploads`), the deletion removes them (`deletedUploads`,
|
|
46
|
+
`pendingUploads`).
|
|
47
|
+
- New dependency `@softure-ai/security` (the rate limit), new error codes `files.content_type_not_allowed`,
|
|
48
|
+
`files.too_many_uploads`, `files.upload_incomplete`, `files.checksum_mismatch` with their messages.
|
|
49
|
+
|
|
7
50
|
## 0.1.2
|
|
8
51
|
|
|
9
52
|
- No code change: the first release through the package's npm trusted publisher (OIDC), without `NPM_TOKEN`.
|
package/README.md
CHANGED
|
@@ -4,7 +4,8 @@ Stored files for a Next.js app that takes uploads or produces media (rendered vi
|
|
|
4
4
|
links that hand one of them to a third party: a social media scheduler that fetches media from a URL, a mail with a
|
|
5
5
|
large download, a webhook consumer. The module keeps one table, puts the bytes on a storage driver (a folder on a
|
|
6
6
|
volume, or an S3-compatible bucket), and serves links that work without the app's session, serve byte ranges for
|
|
7
|
-
video and stop working after their time.
|
|
7
|
+
video and stop working after their time. A client that cannot hand the server a stream (an assistant in its own
|
|
8
|
+
sandbox, a phone behind a proxy with a body limit) uploads through a signed URL in resumable chunks.
|
|
8
9
|
|
|
9
10
|
## 1. What it provides
|
|
10
11
|
|
|
@@ -27,8 +28,22 @@ video and stop working after their time.
|
|
|
27
28
|
`Content-Length`, `Accept-Ranges`, `206` for a range, `416` past the end, `Content-Disposition`, and
|
|
28
29
|
`Cache-Control: private, no-store` (no CDN keeps a copy), and the same `404` for an expired, revoked, deleted or
|
|
29
30
|
forged link. `revokeFileLinks(ctx, fileId)` stops every link made so far.
|
|
30
|
-
- **
|
|
31
|
-
|
|
31
|
+
- **The owner's own view**: `serveStoredFile(ctx, fileId, request, { ownerId })` and the Next route
|
|
32
|
+
`createStoredFileRoute({ getOwnerId })` give the signed-in owner the same answer (ranges, headers, one `404`) for a
|
|
33
|
+
player or an image in the app's own page, with no public link. See §4.4.
|
|
34
|
+
- **Resumable uploads** (`files.uploads`): `createUpload(ctx, { ownerId, name, contentType?, size, sha256?, kind?,
|
|
35
|
+
ttlSeconds? })` opens a session and answers `{ uploadId, uploadUrl, chunkSize, chunkCount, expiresAt }`. The client
|
|
36
|
+
sends the file to `uploadUrl` in chunks under the edge's body limit (64 MiB by default), resumes after a dropped
|
|
37
|
+
connection, and `finalizeUpload(ctx, uploadId)` checks every byte and the optional SHA-256 and saves the file like
|
|
38
|
+
`saveFile` (quota, dedupe). See §4.1.
|
|
39
|
+
- **A browser client** (`@softure-ai/files/client`): `sendUpload(file, { uploadUrl, signal?, onProgress? })` sends a
|
|
40
|
+
`File` to a session, only the chunks it lacks, and `createUploadQueue({ open, finalize })` keeps an upload list for
|
|
41
|
+
an upload screen (theme-notion's `UploadItem` takes its items as they are). See §4.3.
|
|
42
|
+
- **MCP upload tools** (`@softure-ai/files/mcp`): `registerFileUploadTools(server, { identity, getContext })` adds
|
|
43
|
+
`create_upload` (a signed URL, a ready `curl` loop and the browser page) and `finalize_upload`, so an assistant hands
|
|
44
|
+
over a video without its bytes going through a tool call. See §4.2.
|
|
45
|
+
- **Retention**: `pruneFiles(ctx)` removes expired and deleted files from storage and the table, and expired upload
|
|
46
|
+
sessions with their chunks; the `files.prune` job (`@softure-ai/files/jobs`) runs it hourly.
|
|
32
47
|
- **A privacy contributor** (the export lists the owner's files, the deletion removes them) and **a health check**
|
|
33
48
|
(the table answers, storage takes a write, free space above `health.minFreeBytes`).
|
|
34
49
|
- **`/testing`**: an in-memory driver, a fixed link keyring, `fetchFileLink` (status, headers and bytes of a link,
|
|
@@ -40,7 +55,8 @@ video and stop working after their time.
|
|
|
40
55
|
npm install @softure-ai/files
|
|
41
56
|
```
|
|
42
57
|
|
|
43
|
-
`@softure-ai/jobs` is an optional peer, needed only for the prune schedule
|
|
58
|
+
`@softure-ai/jobs` is an optional peer, needed only for the prune schedule; `@modelcontextprotocol/server` is an
|
|
59
|
+
optional peer, needed only for `@softure-ai/files/mcp`.
|
|
44
60
|
|
|
45
61
|
## 3. Configuration
|
|
46
62
|
|
|
@@ -67,7 +83,12 @@ files({
|
|
|
67
83
|
| `links.maxTtlSeconds` | 7 days | the longest lifetime `createFileLink` grants |
|
|
68
84
|
| `links.disposition` | `attachment` | `attachment` (a download) or `inline` (shown by the browser) |
|
|
69
85
|
| `health.minFreeBytes` | 1 GiB | the health check fails below this many free bytes (local disk only) |
|
|
86
|
+
| `uploads.chunkBytes` | 64 MiB | the bytes of one upload request; keep it under the edge's body limit (Cloudflare: 100 MB on Free and Pro, 200 MB on Business) |
|
|
87
|
+
| `uploads.ttlSeconds` | 1 day | how long an upload session and its URL work (at most 7 days); `createUpload` may ask for less |
|
|
88
|
+
| `uploads.maxOpenPerOwner` | 5 | sessions one owner may have open at once (`files.too_many_uploads`) |
|
|
89
|
+
| `uploads.contentTypes` | `null` (any) | the media types an upload may declare, `video/mp4` or `video/*` (`files.content_type_not_allowed`) |
|
|
70
90
|
| `routes.links` | `/f` | the link route's prefix; mount the route under the same folder |
|
|
91
|
+
| `routes.uploads` | `/u` | the upload route's prefix; mount the route under the same folder |
|
|
71
92
|
|
|
72
93
|
Building a driver touches neither the disk nor the network, so `next build` runs without the folder or the bucket's
|
|
73
94
|
keys.
|
|
@@ -127,6 +148,202 @@ const link = await createFileLink(ctx, saved.value.id, { ttlSeconds: 86_400 });
|
|
|
127
148
|
A request body streams in directly: `saveFile(ctx, { ownerId, body: request.body, name, contentType })` (a web
|
|
128
149
|
`ReadableStream` is an async iterable in Node 22).
|
|
129
150
|
|
|
151
|
+
### 4.1 Uploads from clients
|
|
152
|
+
|
|
153
|
+
A second route handler takes uploads:
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
// app/u/[...upload]/route.ts
|
|
157
|
+
export { serveUploadRoute as GET, serveUploadRoute as HEAD, serveUploadRoute as PUT } from "@softure-ai/files/next";
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Like `/f`, **the route has no session**: the URL carries an HMAC signature (under `SOFTURE_FILES_LINK_KEYS`, with its
|
|
161
|
+
own context, so an upload URL never passes as a link) and stops working once the session expires or is finalized. Keep
|
|
162
|
+
`/u` out of the app's sign-in guard, add an edge bypass for it as for `/f` (`apps[].access.bypassPaths: [/f, /u]` with
|
|
163
|
+
`@softure-ai/host`), and never cache it. Raise the edge's body limit only if you raise `uploads.chunkBytes`.
|
|
164
|
+
|
|
165
|
+
The app opens a session for a signed-in user and hands the URL to the client; the client sends the bytes; the app
|
|
166
|
+
finalizes:
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
import { createUpload, finalizeUpload } from "@softure-ai/files/server";
|
|
170
|
+
|
|
171
|
+
const created = await createUpload(ctx, { ownerId: user.id, name: "promo.mp4", contentType: "video/mp4", size, kind: "input" });
|
|
172
|
+
if (!created.ok) return created; // files.too_large, files.quota_exceeded, files.content_type_not_allowed, files.too_many_uploads, files.invalid_input
|
|
173
|
+
// ...the client uploads to created.value.uploadUrl...
|
|
174
|
+
const saved = await finalizeUpload(ctx, created.value.uploadId, { ownerId: user.id });
|
|
175
|
+
// saved.value is the StoredFile; files.upload_incomplete, files.checksum_mismatch, files.quota_exceeded otherwise
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
The wire protocol on `uploadUrl`:
|
|
179
|
+
|
|
180
|
+
| Request | Answer |
|
|
181
|
+
| --- | --- |
|
|
182
|
+
| `PUT` with `Content-Range: bytes <start>-<end>/<size>` | stores one chunk: `start` a multiple of `chunkSize`, `end` the chunk's last byte (the last chunk is shorter). `200` with the JSON status; a chunk that already arrived is answered without being rewritten, so a resend is safe. `416` for a range that is not one chunk, `400` for a body of another length, `404` once finalized or expired. |
|
|
183
|
+
| `PUT` without `Content-Range` | the whole file, when it fits one chunk |
|
|
184
|
+
| `HEAD` | `upload-state` (`open`, `complete`, `finalized`), `upload-size`, `upload-chunk-size`, `upload-received` (byte ranges, `0-67108863,134217728-201326591`), `upload-expires` |
|
|
185
|
+
| `GET` | the JSON status (`received`, `receivedBytes`, `missingChunks`, `state`, ...); a browser (`Accept: text/html`) gets the upload page instead |
|
|
186
|
+
|
|
187
|
+
The **upload page** is a small phone-friendly page on the same URL: the person picks the file and it is sent in chunks
|
|
188
|
+
with `fetch`, from the missing ones, so pressing Upload again resumes. Its loop is `sendUpload` of the browser client
|
|
189
|
+
(§4.3), inlined. Its copy is `filesMessages.en.uploadPage`; it
|
|
190
|
+
loads nothing external and runs one inline script under a per-response CSP nonce.
|
|
191
|
+
|
|
192
|
+
**Rate limit**: when the app enables `@softure-ai/security`, every request to the upload route counts in the
|
|
193
|
+
`files-upload` bucket, keyed by the session; spread `FILES_RATE_LIMIT_BUCKETS` (from `@softure-ai/files`) into
|
|
194
|
+
`security({ buckets })`, or the route throws a setup error naming it. Without the security module the route relies on
|
|
195
|
+
the signature alone.
|
|
196
|
+
|
|
197
|
+
Every chunk is its own object in storage (`uploads/<id>/<index>`); `finalizeUpload` streams them in order into
|
|
198
|
+
`saveFile`, which writes the one final object (a multipart upload on S3) and the parts are removed. Storage briefly
|
|
199
|
+
holds the file twice while a finalize runs. Two parallel finalizes keep one file; a second call answers the same file.
|
|
200
|
+
|
|
201
|
+
### 4.3 The browser client
|
|
202
|
+
|
|
203
|
+
`@softure-ai/files/client` runs in the browser (no Node built-ins, no server code). An app with its own upload screen
|
|
204
|
+
opens the session on the server and sends the file from the client:
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
"use client";
|
|
208
|
+
import { sendUpload } from "@softure-ai/files/client";
|
|
209
|
+
|
|
210
|
+
const opened = await openUpload({ name: file.name, size: file.size }); // a server action around createUpload
|
|
211
|
+
if (!opened.ok) return opened;
|
|
212
|
+
const sent = await sendUpload(file, {
|
|
213
|
+
uploadUrl: opened.value.uploadUrl,
|
|
214
|
+
signal: controller.signal,
|
|
215
|
+
onProgress: ({ sentBytes, totalBytes }) => setProgress(sentBytes / totalBytes),
|
|
216
|
+
});
|
|
217
|
+
if (sent.ok) await finishUpload(opened.value.uploadId); // a server action around finalizeUpload
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
`sendUpload` reads the session's `HEAD`, takes the chunk size from it and sends only the missing chunks, in order;
|
|
221
|
+
calling it again resumes. It reports `{ sentBytes, totalBytes }` once with what already arrived and after every chunk,
|
|
222
|
+
and answers a `Result`: `files.upload_expired` (`404`: expired, finalized for a write, or forged),
|
|
223
|
+
`files.upload_rejected` (another `4xx`, or a file whose size is not the session's), `files.network` (a failed request,
|
|
224
|
+
`429`, `5xx`) or `files.upload_aborted` (the signal). It never throws for these.
|
|
225
|
+
|
|
226
|
+
For a list of files, `createUploadQueue` does the bookkeeping:
|
|
227
|
+
|
|
228
|
+
```tsx
|
|
229
|
+
"use client";
|
|
230
|
+
import { createUploadQueue } from "@softure-ai/files/client";
|
|
231
|
+
import { UploadField, UploadItem } from "@softure-ai/theme-notion";
|
|
232
|
+
import { useState, useSyncExternalStore } from "react";
|
|
233
|
+
|
|
234
|
+
const [queue] = useState(() => createUploadQueue({ open: openUpload, finalize: (session) => finishUpload(session.uploadId) }));
|
|
235
|
+
const items = useSyncExternalStore(queue.subscribe, queue.getItems, queue.getItems);
|
|
236
|
+
|
|
237
|
+
<UploadField label={copy.files} onFilesSelected={(files) => queue.add(files)} />
|
|
238
|
+
{items.map((item) => (
|
|
239
|
+
<UploadItem key={item.id} item={item} onRetry={() => queue.retry(item.id)} onPause={() => queue.pause(item.id)}
|
|
240
|
+
onResume={() => queue.resume(item.id)} onRemove={() => queue.remove(item.id)} />
|
|
241
|
+
))}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
- Items are `{ id, name, size, state, progress, error?, errorCode? }`: `queued`, `uploading`, `paused`, `done`,
|
|
245
|
+
`failed`; `progress` 0–100, 100 only once finalized; `getItems` answers the same array until something changes.
|
|
246
|
+
- `open(file)` and `finalize(session, file)` are the app's (usually server actions) and answer a `Result`; their error
|
|
247
|
+
codes land in `errorCode` with the copy of `describeError(code)` (the built-in `files` messages by default, so an
|
|
248
|
+
app passes `(code) => getFilesErrorMessage(myMessages, code)` or its own wording).
|
|
249
|
+
- `concurrency` (1 by default) uploads run at once. `pause` aborts the running send and keeps the session; `resume`
|
|
250
|
+
and `retry` send only what is missing in the same session, and a session that expired is opened again on the next
|
|
251
|
+
`retry`. `remove` stops the upload and drops it; the unfinished session expires and `files.prune` removes it.
|
|
252
|
+
|
|
253
|
+
### 4.2 MCP upload tools
|
|
254
|
+
|
|
255
|
+
An MCP tool cannot take a video as an argument. With `@softure-ai/mcp-access`, register the two upload tools in the
|
|
256
|
+
app's server factory and list them in the catalog:
|
|
257
|
+
|
|
258
|
+
```ts
|
|
259
|
+
import { getFilesContext } from "@softure-ai/files/next";
|
|
260
|
+
import { FILE_UPLOAD_MCP_TOOLS, registerFileUploadTools } from "@softure-ai/files/mcp";
|
|
261
|
+
|
|
262
|
+
mcpAccess({ serverName: "acme", tools: [...appTools, ...FILE_UPLOAD_MCP_TOOLS] });
|
|
263
|
+
|
|
264
|
+
export const createServer = createMcpServerFactory({
|
|
265
|
+
name: "acme",
|
|
266
|
+
strictToolInput: true,
|
|
267
|
+
registerTools: (server, identity) => {
|
|
268
|
+
registerAppTools(server, identity);
|
|
269
|
+
registerFileUploadTools(server, { identity, getContext: () => getFilesContext(), kind: "input" });
|
|
270
|
+
},
|
|
271
|
+
});
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
- `create_upload({ name, size, content_type?, sha256? })` answers `upload_id`, `upload_url`, `chunk_size`,
|
|
275
|
+
`chunk_count`, `expires_at`, `curl` (a bash loop with `dd` and `curl` that sends every chunk; `CHUNKS="3 4"` resends
|
|
276
|
+
only those) and `browser_page`. The assistant runs the loop in its own sandbox; the bytes never pass through the tool
|
|
277
|
+
call.
|
|
278
|
+
- `finalize_upload({ upload_id })` answers `file_id`, `name`, `size`, `content_type`, `sha256`, or the error's
|
|
279
|
+
sentence with its code.
|
|
280
|
+
- Both are write tools: registered only when `identity.canWrite` (mcp-access's write switch). The uploads belong to the
|
|
281
|
+
token's user (`getOwnerId` changes that). The app's tools then take the `file_id`.
|
|
282
|
+
|
|
283
|
+
An app that turns the uploaded file into its own record in the same call, or that words its tool texts its own way,
|
|
284
|
+
passes three more options:
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
registerFileUploadTools(server, {
|
|
288
|
+
identity,
|
|
289
|
+
getContext: () => getFilesContext(),
|
|
290
|
+
// After every successful finalize, a repeated one for the same file included: keep it idempotent.
|
|
291
|
+
onFinalized: async (file) => {
|
|
292
|
+
const asset = await upsertAssetForFile(file.id); // the app's own step, e.g. a row plus a background job
|
|
293
|
+
return asset.ok ? { asset_id: asset.value.id } : asset; // fields join the answer; err(code) answers a failure
|
|
294
|
+
},
|
|
295
|
+
descriptions: { finalize_upload: `Acme: ${FILE_UPLOAD_TOOL_DESCRIPTIONS.finalize_upload}` },
|
|
296
|
+
hints: { "assets.quota_exceeded": "The plan holds no more assets." },
|
|
297
|
+
});
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
- `onFinalized(file, ctx)`: its returned fields are merged into the `finalize_upload` answer (the file's own fields
|
|
301
|
+
win a name clash); a returned `err(code)` answers that code as a failure; a thrown error answers the generic failure
|
|
302
|
+
and is logged.
|
|
303
|
+
- `descriptions`: the served text of `create_upload` and `finalize_upload`; the defaults are exported as
|
|
304
|
+
`FILE_UPLOAD_TOOL_DESCRIPTIONS`. The catalog entries in `FILE_UPLOAD_MCP_TOOLS` stay as they are.
|
|
305
|
+
- `hints`: the text answered for an error code, followed by the code: the hook's codes and the package's `files.*`
|
|
306
|
+
codes alike. Without a hint a `files.*` code answers its sentence and any other code answers the code alone.
|
|
307
|
+
|
|
308
|
+
### 4.4 Showing a file to its signed-in owner
|
|
309
|
+
|
|
310
|
+
A link is for someone outside the app (a scheduler, a recipient). To play a stored video or show an image to the
|
|
311
|
+
signed-in owner inside the app's own page, serve it by id through the owner route instead: no link is minted (no
|
|
312
|
+
write), and the file stays unreachable without a session.
|
|
313
|
+
|
|
314
|
+
```ts
|
|
315
|
+
// app/media/[id]/route.ts
|
|
316
|
+
import { getCurrentUser } from "@softure-ai/auth/next";
|
|
317
|
+
import { createStoredFileRoute } from "@softure-ai/files/next";
|
|
318
|
+
|
|
319
|
+
export const { GET, HEAD } = createStoredFileRoute({
|
|
320
|
+
getOwnerId: async () => (await getCurrentUser())?.id ?? null,
|
|
321
|
+
});
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
```tsx
|
|
325
|
+
<video src={`/media/${file.id}`} controls />
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
The route answers like a link (`GET` and `HEAD`, single byte ranges for seeking, `206`, `416`,
|
|
329
|
+
`Cache-Control: private, no-store`, `nosniff`, the sandboxing CSP) under the file's stored name, `inline` by default
|
|
330
|
+
(`disposition: "attachment"` for a download). Without a session, and for a file that is missing, expired, deleted or
|
|
331
|
+
another owner's, it answers the same `404`, so it never tells whether a file exists. files does not depend on auth:
|
|
332
|
+
the session lookup is the app's `getOwnerId`.
|
|
333
|
+
|
|
334
|
+
**Unlike `/f` and `/u`, this route sits behind the app's sign-in guard**: list its prefix in
|
|
335
|
+
`createAuthGuard(config, { protect: [...] })` and add no edge bypass for it.
|
|
336
|
+
|
|
337
|
+
A route of the app's own (another path shape, an extra permission check) calls the server function with the owner it
|
|
338
|
+
has checked:
|
|
339
|
+
|
|
340
|
+
```ts
|
|
341
|
+
import { getFilesContext } from "@softure-ai/files/next";
|
|
342
|
+
import { serveStoredFile } from "@softure-ai/files/server";
|
|
343
|
+
|
|
344
|
+
return serveStoredFile(await getFilesContext(), fileId, request, { ownerId: user.id });
|
|
345
|
+
```
|
|
346
|
+
|
|
130
347
|
## 5. Migrations and tables
|
|
131
348
|
|
|
132
349
|
Schema `files`, migration `0001_create_files.sql`, table `files`:
|
|
@@ -146,11 +363,17 @@ Schema `files`, migration `0001_create_files.sql`, table `files`:
|
|
|
146
363
|
A deleted or expired file keeps its row until `pruneFiles` has removed its bytes. Rollback: drop the table and its
|
|
147
364
|
`softure.migrations` row (the migration's header has the statements); the objects in storage stay.
|
|
148
365
|
|
|
366
|
+
Migration `0002_create_uploads.sql`, table `uploads`: one row per upload session (owner, sanitised name, content type,
|
|
367
|
+
kind, declared size and optional SHA-256, chunk size, `received_chunks` (the indices that arrived), `file_id` once
|
|
368
|
+
finalized, `expires_at`). The state is derived from those columns. A finalized session keeps its row until it expires,
|
|
369
|
+
so a repeated finalize answers the same file; `pruneFiles` then removes it. Rollback: drop `files.uploads` and the
|
|
370
|
+
version 2 row; chunk objects under `uploads/` stay in storage.
|
|
371
|
+
|
|
149
372
|
## 6. Environment variables
|
|
150
373
|
|
|
151
374
|
| Variable | Required | Meaning |
|
|
152
375
|
| --- | --- | --- |
|
|
153
|
-
| `SOFTURE_FILES_LINK_KEYS` | for links | the signing keyring, `<id>:<base64 of 32 bytes>[,<id>:<key>…]`: the first key signs, every key verifies. `generateFilesLinkKey()` (from `/server`) prints a new entry. Rotate by putting a new key first and dropping the old one after `links.maxTtlSeconds`. Without it, `createFileLink` answers `files.link_key_missing` and the route answers `404` (and logs the code). |
|
|
376
|
+
| `SOFTURE_FILES_LINK_KEYS` | for links and uploads | the signing keyring, `<id>:<base64 of 32 bytes>[,<id>:<key>…]`: the first key signs, every key verifies. `generateFilesLinkKey()` (from `/server`) prints a new entry. Rotate by putting a new key first and dropping the old one after `links.maxTtlSeconds`. Without it, `createFileLink` answers `files.link_key_missing` and the route answers `404` (and logs the code). |
|
|
154
377
|
| `SOFTURE_FILES_S3_ACCESS_KEY_ID`, `SOFTURE_FILES_S3_SECRET_ACCESS_KEY` | with `createS3Storage` | the bucket's access keys, read on each request (renamed with `accessKeyIdEnv` / `secretAccessKeyEnv`) |
|
|
155
378
|
|
|
156
379
|
## 7. Switches
|
|
@@ -159,13 +382,16 @@ None.
|
|
|
159
382
|
|
|
160
383
|
## 8. Appearance
|
|
161
384
|
|
|
162
|
-
|
|
385
|
+
The upload page (§4.1) is plain HTML with a minimal inline style, so it works before any theme loads; an app that
|
|
386
|
+
wants its own look builds a page on `createUpload` and the browser client (§4.3). A file browser is out of scope.
|
|
163
387
|
|
|
164
388
|
## 9. Copy
|
|
165
389
|
|
|
166
390
|
`filesMessages.en.errors.files.*` has a sentence per error code (`too_large`, `quota_exceeded`, `not_found`, ...);
|
|
167
391
|
`getFilesErrorMessage(messages, code)` picks one, falling back to the generic failure. The link route's `404` body
|
|
168
|
-
is a fixed `Not found` for machines, not copy.
|
|
392
|
+
is a fixed `Not found` for machines, not copy. `uploadPage.*` is the upload page's copy (`{name}`, `{size}`, `{done}`
|
|
393
|
+
and `{total}` are filled in). The browser client's codes (`upload_expired`, `upload_rejected`, `network`,
|
|
394
|
+
`upload_aborted`) have their sentences in the same group.
|
|
169
395
|
|
|
170
396
|
## 10. Hooks
|
|
171
397
|
|
|
@@ -178,12 +404,13 @@ None. A driver is the extension point: any object with `kind`, `put(body, key)`,
|
|
|
178
404
|
times), never the bytes or the storage key; an app that wants the bytes in the export adds links itself.
|
|
179
405
|
`deleteUserData` marks every file of the user deleted (nothing of theirs is served from that moment), removes the
|
|
180
406
|
bytes from storage and then the rows; a file whose storage delete fails keeps its marked row until `pruneFiles`
|
|
181
|
-
removes it.
|
|
407
|
+
removes it. Upload sessions too: the export lists the open ones (name, size, what arrived), the deletion removes all
|
|
408
|
+
of the user's sessions with their chunks.
|
|
182
409
|
|
|
183
410
|
## 12. Limitations
|
|
184
411
|
|
|
185
|
-
-
|
|
186
|
-
|
|
412
|
+
- Uploads from clients go through upload sessions (§4.1): chunks must align to the session's chunk size, and a
|
|
413
|
+
finalize briefly needs twice the file's size in storage. No image transforms, no virus scanning, no file browser UI.
|
|
187
414
|
- A link serves one range per request; a request for several ranges gets the whole file (`200`), as RFC 9110 allows.
|
|
188
415
|
No `If-Range` or `ETag`.
|
|
189
416
|
- Links are `attachment` with `nosniff` and a sandboxing `Content-Security-Policy` by default, so an uploaded HTML or
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
export { sendUpload, type SendUploadErrorCode, type SendUploadOptions, type SendUploadResult, type UploadProgress } from "./send-upload.js";
|
|
2
|
+
export { createUploadQueue, type UploadQueue, type UploadQueueItem, type UploadQueueOptions, type UploadQueueSession, type UploadQueueState, } from "./upload-queue.js";
|
|
3
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC5I,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
// The browser side of upload sessions: `sendUpload` sends a `File` to a session's signed URL in chunks, resumably,
|
|
2
|
+
// and `createUploadQueue` keeps a list of uploads for an upload screen (theme-notion's `UploadItem` takes its items
|
|
3
|
+
// as they are). No Node built-ins and no server code: safe to import from a client component.
|
|
4
|
+
export { sendUpload } from "./send-upload.js";
|
|
5
|
+
export { createUploadQueue, } from "./upload-queue.js";
|
|
6
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,oHAAoH;AACpH,8FAA8F;AAC9F,OAAO,EAAE,UAAU,EAAgG,MAAM,kBAAkB,CAAC;AAC5I,OAAO,EACL,iBAAiB,GAMlB,MAAM,mBAAmB,CAAC"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { Err, Ok } from "@softure-ai/core";
|
|
2
|
+
/** Why a send stopped: the session is gone, the route refused it, the network failed, or the caller aborted. */
|
|
3
|
+
export type SendUploadErrorCode = "files.upload_expired" | "files.upload_rejected" | "files.network" | "files.upload_aborted";
|
|
4
|
+
/** Bytes the session holds so far out of the file's size. */
|
|
5
|
+
export interface UploadProgress {
|
|
6
|
+
readonly sentBytes: number;
|
|
7
|
+
readonly totalBytes: number;
|
|
8
|
+
}
|
|
9
|
+
export interface SendUploadOptions {
|
|
10
|
+
/** The session's signed upload URL, as `createUpload` returned it. */
|
|
11
|
+
readonly uploadUrl: string;
|
|
12
|
+
/** Aborts between chunks and the chunk in flight; the send answers `files.upload_aborted`. */
|
|
13
|
+
readonly signal?: AbortSignal;
|
|
14
|
+
/** Called once with what already arrived, then after every chunk. */
|
|
15
|
+
readonly onProgress?: (progress: UploadProgress) => void;
|
|
16
|
+
/** The `fetch` to use; the global one by default. */
|
|
17
|
+
readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
|
|
18
|
+
}
|
|
19
|
+
export type SendUploadResult = Ok<UploadProgress> | Err<SendUploadErrorCode>;
|
|
20
|
+
/**
|
|
21
|
+
* Sends the chunks of `file` the session does not hold yet. Resuming is calling it again: a chunk that arrived is
|
|
22
|
+
* never sent twice. `404` answers `files.upload_expired`, another `4xx` (or a file whose size is not the session's)
|
|
23
|
+
* `files.upload_rejected`, a failed request, `429` or `5xx` `files.network`.
|
|
24
|
+
*/
|
|
25
|
+
export declare function sendUpload(file: Blob, options: SendUploadOptions): Promise<SendUploadResult>;
|
|
26
|
+
//# sourceMappingURL=send-upload.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"send-upload.d.ts","sourceRoot":"","sources":["../../src/client/send-upload.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAEhD,gHAAgH;AAChH,MAAM,MAAM,mBAAmB,GAAG,sBAAsB,GAAG,uBAAuB,GAAG,eAAe,GAAG,sBAAsB,CAAC;AAE9H,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;IACzD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxE;AAED,MAAM,MAAM,gBAAgB,GAAG,EAAE,CAAC,cAAc,CAAC,GAAG,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAE7E;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoDlG"}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Sends the chunks of `file` the session does not hold yet. Resuming is calling it again: a chunk that arrived is
|
|
3
|
+
* never sent twice. `404` answers `files.upload_expired`, another `4xx` (or a file whose size is not the session's)
|
|
4
|
+
* `files.upload_rejected`, a failed request, `429` or `5xx` `files.network`.
|
|
5
|
+
*/
|
|
6
|
+
export async function sendUpload(file, options) {
|
|
7
|
+
const { uploadUrl, signal, onProgress } = options;
|
|
8
|
+
const request = options.fetch ?? ((url, init) => fetch(url, init));
|
|
9
|
+
const fail = (error) => ({ ok: false, error });
|
|
10
|
+
const failForStatus = (status) => {
|
|
11
|
+
if (status === 404)
|
|
12
|
+
return fail("files.upload_expired");
|
|
13
|
+
return fail(status === 429 || status >= 500 ? "files.network" : "files.upload_rejected");
|
|
14
|
+
};
|
|
15
|
+
const isAborted = () => signal?.aborted === true;
|
|
16
|
+
const call = async (init) => {
|
|
17
|
+
if (isAborted())
|
|
18
|
+
return "files.upload_aborted";
|
|
19
|
+
try {
|
|
20
|
+
return await request(uploadUrl, { ...init, signal: signal ?? null });
|
|
21
|
+
}
|
|
22
|
+
catch {
|
|
23
|
+
// A thrown fetch is the network or the abort; both are expected and answered as a code.
|
|
24
|
+
return isAborted() ? "files.upload_aborted" : "files.network";
|
|
25
|
+
}
|
|
26
|
+
};
|
|
27
|
+
const head = await call({ method: "HEAD" });
|
|
28
|
+
if (typeof head === "string")
|
|
29
|
+
return fail(head);
|
|
30
|
+
if (!head.ok)
|
|
31
|
+
return failForStatus(head.status);
|
|
32
|
+
const totalBytes = Number(head.headers.get("upload-size"));
|
|
33
|
+
const chunkSize = Number(head.headers.get("upload-chunk-size"));
|
|
34
|
+
if (!Number.isSafeInteger(totalBytes) || !Number.isSafeInteger(chunkSize) || chunkSize <= 0 || totalBytes !== file.size) {
|
|
35
|
+
return fail("files.upload_rejected");
|
|
36
|
+
}
|
|
37
|
+
const received = [];
|
|
38
|
+
for (const part of (head.headers.get("upload-received") ?? "").split(",")) {
|
|
39
|
+
const match = /^(\d+)-(\d+)$/.exec(part.trim());
|
|
40
|
+
if (match !== null)
|
|
41
|
+
received.push({ start: Number(match[1]), end: Number(match[2]) });
|
|
42
|
+
}
|
|
43
|
+
const missing = [];
|
|
44
|
+
for (let start = 0; start < totalBytes; start += chunkSize) {
|
|
45
|
+
const end = Math.min(start + chunkSize, totalBytes) - 1;
|
|
46
|
+
if (!received.some((range) => range.start <= start && range.end >= end))
|
|
47
|
+
missing.push({ start, end });
|
|
48
|
+
}
|
|
49
|
+
let sentBytes = totalBytes - missing.reduce((sum, chunk) => sum + chunk.end - chunk.start + 1, 0);
|
|
50
|
+
onProgress?.({ sentBytes, totalBytes });
|
|
51
|
+
for (const chunk of missing) {
|
|
52
|
+
const answer = await call({
|
|
53
|
+
method: "PUT",
|
|
54
|
+
headers: { "content-range": `bytes ${String(chunk.start)}-${String(chunk.end)}/${String(totalBytes)}` },
|
|
55
|
+
body: file.slice(chunk.start, chunk.end + 1),
|
|
56
|
+
});
|
|
57
|
+
if (typeof answer === "string")
|
|
58
|
+
return fail(answer);
|
|
59
|
+
if (!answer.ok)
|
|
60
|
+
return failForStatus(answer.status);
|
|
61
|
+
sentBytes += chunk.end - chunk.start + 1;
|
|
62
|
+
onProgress?.({ sentBytes, totalBytes });
|
|
63
|
+
}
|
|
64
|
+
return { ok: true, value: { sentBytes, totalBytes } };
|
|
65
|
+
}
|
|
66
|
+
//# sourceMappingURL=send-upload.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"send-upload.js","sourceRoot":"","sources":["../../src/client/send-upload.ts"],"names":[],"mappings":"AA+BA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAU,EAAE,OAA0B;IACrE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,GAAW,EAAE,IAAiB,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IACxF,MAAM,IAAI,GAAG,CAAC,KAA0B,EAA4B,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9F,MAAM,aAAa,GAAG,CAAC,MAAc,EAA4B,EAAE;QACjE,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC;IAC3F,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,GAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1D,MAAM,IAAI,GAAG,KAAK,EAAE,IAAiB,EAA2C,EAAE;QAChF,IAAI,SAAS,EAAE;YAAE,OAAO,sBAAsB,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,wFAAwF;YACxF,OAAO,SAAS,EAAE,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,eAAe,CAAC;QAChE,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,IAAI,UAAU,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACxH,OAAO,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,QAAQ,GAAqC,EAAE,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1E,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,OAAO,GAAqC,EAAE,CAAC;IACrD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;QAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;QACxD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,IAAI,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACxG,CAAC;IAED,IAAI,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAClG,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC;YACxB,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,eAAe,EAAE,SAAS,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE;YACvG,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;SAC7C,CAAC,CAAC;QACH,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpD,SAAS,IAAI,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;QACzC,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC;AACxD,CAAC"}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { ErrorCode, Result } from "@softure-ai/core";
|
|
2
|
+
import { type SendUploadOptions } from "./send-upload.js";
|
|
3
|
+
export type UploadQueueState = "queued" | "uploading" | "paused" | "done" | "failed";
|
|
4
|
+
/** One upload of the list. */
|
|
5
|
+
export interface UploadQueueItem {
|
|
6
|
+
readonly id: string;
|
|
7
|
+
readonly name: string;
|
|
8
|
+
/** In bytes. */
|
|
9
|
+
readonly size: number;
|
|
10
|
+
readonly state: UploadQueueState;
|
|
11
|
+
/** 0-100, what the session holds; 100 only once finalized. */
|
|
12
|
+
readonly progress: number;
|
|
13
|
+
/** The copy for `errorCode`, on a failed item. */
|
|
14
|
+
readonly error?: string;
|
|
15
|
+
/** Why it failed: a `files.*` code of the client or whatever code the app's `open` or `finalize` answered. */
|
|
16
|
+
readonly errorCode?: ErrorCode;
|
|
17
|
+
}
|
|
18
|
+
/** What the app's `open` answers: at least the session's upload URL (`createUpload`'s answer fits). */
|
|
19
|
+
export interface UploadQueueSession {
|
|
20
|
+
readonly uploadUrl: string;
|
|
21
|
+
}
|
|
22
|
+
export interface UploadQueueOptions<TSession extends UploadQueueSession> {
|
|
23
|
+
/** Opens a session for a file, usually a server action around `createUpload`. */
|
|
24
|
+
readonly open: (file: File) => Promise<Result<TSession>>;
|
|
25
|
+
/** Turns a sent session into a stored file, usually a server action around `finalizeUpload`. */
|
|
26
|
+
readonly finalize: (session: TSession, file: File) => Promise<Result<unknown>>;
|
|
27
|
+
/** Uploads sent at the same time; 1 by default. */
|
|
28
|
+
readonly concurrency?: number;
|
|
29
|
+
/** The copy for a failure code; the built-in English `files` messages by default. */
|
|
30
|
+
readonly describeError?: (code: ErrorCode) => string;
|
|
31
|
+
/** The `fetch` the sender uses; the global one by default. */
|
|
32
|
+
readonly fetch?: SendUploadOptions["fetch"];
|
|
33
|
+
}
|
|
34
|
+
export interface UploadQueue {
|
|
35
|
+
/** Queues files (a `FileList` works) and answers their item ids. */
|
|
36
|
+
add(files: Iterable<File> | ArrayLike<File>): string[];
|
|
37
|
+
/** Queues a failed upload again; it keeps its session unless the session expired. */
|
|
38
|
+
retry(id: string): void;
|
|
39
|
+
/** Stops a queued or running upload; what arrived stays in the session. */
|
|
40
|
+
pause(id: string): void;
|
|
41
|
+
/** Queues a paused upload again; it sends only what is missing. */
|
|
42
|
+
resume(id: string): void;
|
|
43
|
+
/** Stops an upload and drops it from the list. An unfinished session expires and `files.prune` removes it. */
|
|
44
|
+
remove(id: string): void;
|
|
45
|
+
/** The list, in the order files were added; the same array until something changes. */
|
|
46
|
+
getItems(): readonly UploadQueueItem[];
|
|
47
|
+
/** Calls `listener` after every change; answers the function that stops it. */
|
|
48
|
+
subscribe(listener: () => void): () => void;
|
|
49
|
+
}
|
|
50
|
+
/** Creates an upload list; `open` and `finalize` are the app's, the sending is the package's. */
|
|
51
|
+
export declare function createUploadQueue<TSession extends UploadQueueSession>(options: UploadQueueOptions<TSession>): UploadQueue;
|
|
52
|
+
//# sourceMappingURL=upload-queue.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"upload-queue.d.ts","sourceRoot":"","sources":["../../src/client/upload-queue.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EAAc,KAAK,iBAAiB,EAAuB,MAAM,kBAAkB,CAAC;AAE3F,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErF,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8GAA8G;IAC9G,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB,CAAC,QAAQ,SAAS,kBAAkB;IACrE,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzD,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/E,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC;IACrD,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,qFAAqF;IACrF,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mEAAmE;IACnE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8GAA8G;IAC9G,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uFAAuF;IACvF,QAAQ,IAAI,SAAS,eAAe,EAAE,CAAC;IACvC,+EAA+E;IAC/E,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C;AAcD,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,QAAQ,SAAS,kBAAkB,EAAE,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GAAG,WAAW,CA0IzH"}
|