@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.
Files changed (115) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +237 -10
  3. package/dist/client/index.d.ts +3 -0
  4. package/dist/client/index.d.ts.map +1 -0
  5. package/dist/client/index.js +6 -0
  6. package/dist/client/index.js.map +1 -0
  7. package/dist/client/send-upload.d.ts +26 -0
  8. package/dist/client/send-upload.d.ts.map +1 -0
  9. package/dist/client/send-upload.js +66 -0
  10. package/dist/client/send-upload.js.map +1 -0
  11. package/dist/client/upload-queue.d.ts +52 -0
  12. package/dist/client/upload-queue.d.ts.map +1 -0
  13. package/dist/client/upload-queue.js +164 -0
  14. package/dist/client/upload-queue.js.map +1 -0
  15. package/dist/contract.d.ts +41 -1
  16. package/dist/contract.d.ts.map +1 -1
  17. package/dist/index.d.ts +40 -1
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +17 -4
  20. package/dist/index.js.map +1 -1
  21. package/dist/mcp/index.d.ts +65 -0
  22. package/dist/mcp/index.d.ts.map +1 -0
  23. package/dist/mcp/index.js +131 -0
  24. package/dist/mcp/index.js.map +1 -0
  25. package/dist/messages/en.d.ts +20 -0
  26. package/dist/messages/en.d.ts.map +1 -1
  27. package/dist/messages/en.js +20 -0
  28. package/dist/messages/en.js.map +1 -1
  29. package/dist/messages/index.d.ts +20 -0
  30. package/dist/messages/index.d.ts.map +1 -1
  31. package/dist/next/index.d.ts +2 -0
  32. package/dist/next/index.d.ts.map +1 -1
  33. package/dist/next/index.js +4 -2
  34. package/dist/next/index.js.map +1 -1
  35. package/dist/next/stored-file-route.d.ts +25 -0
  36. package/dist/next/stored-file-route.d.ts.map +1 -0
  37. package/dist/next/stored-file-route.js +14 -0
  38. package/dist/next/stored-file-route.js.map +1 -0
  39. package/dist/next/upload-route.d.ts +3 -0
  40. package/dist/next/upload-route.d.ts.map +1 -0
  41. package/dist/next/upload-route.js +11 -0
  42. package/dist/next/upload-route.js.map +1 -0
  43. package/dist/options.d.ts +6 -0
  44. package/dist/options.d.ts.map +1 -1
  45. package/dist/options.js +27 -0
  46. package/dist/options.js.map +1 -1
  47. package/dist/schema.d.ts +255 -0
  48. package/dist/schema.d.ts.map +1 -1
  49. package/dist/schema.js +17 -2
  50. package/dist/schema.js.map +1 -1
  51. package/dist/server/index.d.ts +7 -3
  52. package/dist/server/index.d.ts.map +1 -1
  53. package/dist/server/index.js +7 -3
  54. package/dist/server/index.js.map +1 -1
  55. package/dist/server/options.d.ts +2 -0
  56. package/dist/server/options.d.ts.map +1 -1
  57. package/dist/server/options.js +8 -0
  58. package/dist/server/options.js.map +1 -1
  59. package/dist/server/privacy.d.ts +6 -1
  60. package/dist/server/privacy.d.ts.map +1 -1
  61. package/dist/server/privacy.js +6 -3
  62. package/dist/server/privacy.js.map +1 -1
  63. package/dist/server/prune.d.ts +4 -0
  64. package/dist/server/prune.d.ts.map +1 -1
  65. package/dist/server/prune.js +4 -2
  66. package/dist/server/prune.js.map +1 -1
  67. package/dist/server/save.d.ts +15 -0
  68. package/dist/server/save.d.ts.map +1 -1
  69. package/dist/server/save.js +11 -9
  70. package/dist/server/save.js.map +1 -1
  71. package/dist/server/serve-upload.d.ts +6 -0
  72. package/dist/server/serve-upload.d.ts.map +1 -0
  73. package/dist/server/serve-upload.js +110 -0
  74. package/dist/server/serve-upload.js.map +1 -0
  75. package/dist/server/serve.d.ts +15 -0
  76. package/dist/server/serve.d.ts.map +1 -1
  77. package/dist/server/serve.js +38 -14
  78. package/dist/server/serve.js.map +1 -1
  79. package/dist/server/upload-page.d.ts +5 -0
  80. package/dist/server/upload-page.d.ts.map +1 -0
  81. package/dist/server/upload-page.js +87 -0
  82. package/dist/server/upload-page.js.map +1 -0
  83. package/dist/server/upload-tokens.d.ts +9 -0
  84. package/dist/server/upload-tokens.d.ts.map +1 -0
  85. package/dist/server/upload-tokens.js +43 -0
  86. package/dist/server/upload-tokens.js.map +1 -0
  87. package/dist/server/uploads.d.ts +73 -0
  88. package/dist/server/uploads.d.ts.map +1 -0
  89. package/dist/server/uploads.js +403 -0
  90. package/dist/server/uploads.js.map +1 -0
  91. package/migrations/0002_create_uploads.sql +33 -0
  92. package/module.json +9 -4
  93. package/package.json +17 -2
  94. package/src/client/index.ts +12 -0
  95. package/src/client/send-upload.ts +89 -0
  96. package/src/client/upload-queue.ts +220 -0
  97. package/src/contract.ts +45 -1
  98. package/src/index.ts +32 -5
  99. package/src/mcp/index.ts +206 -0
  100. package/src/messages/en.ts +20 -0
  101. package/src/next/index.ts +10 -2
  102. package/src/next/stored-file-route.ts +43 -0
  103. package/src/next/upload-route.ts +11 -0
  104. package/src/options.ts +28 -0
  105. package/src/schema.ts +20 -2
  106. package/src/server/index.ts +21 -3
  107. package/src/server/options.ts +8 -0
  108. package/src/server/privacy.ts +12 -4
  109. package/src/server/prune.ts +8 -2
  110. package/src/server/save.ts +25 -11
  111. package/src/server/serve-upload.ts +116 -0
  112. package/src/server/serve.ts +51 -14
  113. package/src/server/upload-page.ts +96 -0
  114. package/src/server/upload-tokens.ts +43 -0
  115. package/src/server/uploads.ts +437 -0
@@ -0,0 +1,206 @@
1
+ // The MCP adapter of @softure-ai/files: two tools around a plain HTTP upload, so an assistant hands a large file
2
+ // (a video) to the app without putting its bytes in a tool call. `create_upload` answers a signed upload URL with a
3
+ // ready `curl` loop for the chunks (and the browser page as a fallback); the assistant runs it in its own sandbox and
4
+ // then calls `finalize_upload`, which turns the chunks into a stored file.
5
+ //
6
+ // Both tools write, so they are registered only for an identity that can write (mcp-access's write switch). Their
7
+ // input schemas are plain objects; the app's factory makes them strict (`createMcpServerFactory({ strictToolInput })`).
8
+ //
9
+ // createMcpServerFactory({
10
+ // name: "acme",
11
+ // registerTools: (server, identity) => registerFileUploadTools(server, { identity, getContext: () => getFilesContext() }),
12
+ // });
13
+ // mcpAccess({ serverName: "acme", tools: [...FILE_UPLOAD_MCP_TOOLS] });
14
+ //
15
+ // An app that turns the stored file into its own record passes `onFinalized` (its fields join the answer), its own
16
+ // tool texts in `descriptions`, and `hints` for the error codes it answers.
17
+ import type { CallToolResult, McpServer } from "@modelcontextprotocol/server";
18
+ import { errorLogLabel, type Err, type ErrorCode } from "@softure-ai/core";
19
+ import { z } from "zod";
20
+ import type { CreatedUpload, StoredFile } from "../contract.js";
21
+ import { filesMessages, getFilesErrorMessage } from "../messages/index.js";
22
+ import type { FilesContext } from "../server/context.js";
23
+ import { createUpload, finalizeUpload } from "../server/uploads.js";
24
+
25
+ export const CREATE_UPLOAD_TOOL_NAME = "create_upload";
26
+ export const FINALIZE_UPLOAD_TOOL_NAME = "finalize_upload";
27
+
28
+ /** The served tool descriptions by default; an app prefixes or replaces them through `descriptions`. */
29
+ export const FILE_UPLOAD_TOOL_DESCRIPTIONS = {
30
+ create_upload:
31
+ "Starts an upload of a file from your own environment (for a file too large for a tool call, such as a video). " +
32
+ "The file's bytes never go through this tool: it answers a one-time upload URL and a ready curl loop that sends the " +
33
+ "file in chunks; run it where the file is, then call finalize_upload with the upload_id. A person can open the " +
34
+ "same URL in a browser to upload the file there instead.",
35
+ finalize_upload:
36
+ "Finishes an upload started with create_upload once every chunk is sent: checks the bytes and stores the file. " +
37
+ "Answers the stored file's id. Calling it again answers the same file.",
38
+ } as const;
39
+
40
+ /** The catalog entries for `mcpAccess({ tools })`, so the token page and the catalog check know both tools. */
41
+ export const FILE_UPLOAD_MCP_TOOLS = [
42
+ { name: CREATE_UPLOAD_TOOL_NAME, access: "write", description: { en: "Starts an upload of a large file to a one-time URL." } },
43
+ { name: FINALIZE_UPLOAD_TOOL_NAME, access: "write", description: { en: "Stores a file once its upload is complete." } },
44
+ ] as const;
45
+
46
+ /** What the tools need of the MCP request's identity (`McpServerIdentity` of `@softure-ai/mcp-access`). */
47
+ export interface FileUploadToolIdentity {
48
+ readonly userId: string;
49
+ readonly canWrite: boolean;
50
+ }
51
+
52
+ export interface FileUploadToolsOptions {
53
+ readonly identity: FileUploadToolIdentity;
54
+ /** The files context, e.g. `() => getFilesContext()` from `@softure-ai/files/next`. */
55
+ readonly getContext: () => FilesContext | Promise<FilesContext>;
56
+ /** Whose files the uploads become; the token's user by default. */
57
+ readonly getOwnerId?: (identity: FileUploadToolIdentity) => string;
58
+ /** The kind of the stored files; `file` by default. */
59
+ readonly kind?: string;
60
+ /**
61
+ * Runs after every successful `finalize_upload`, a repeated one for the same file included (so keep it idempotent,
62
+ * e.g. an upsert by `file.id`). Returned fields join the answer (the file's own fields win a name clash); a returned
63
+ * `err(code)` answers that code as a failure; a thrown error answers the generic failure and is logged.
64
+ */
65
+ readonly onFinalized?: (file: StoredFile, ctx: FilesContext) => Promise<FileFinalizedAnswer>;
66
+ /** The served descriptions; a missing one keeps `FILE_UPLOAD_TOOL_DESCRIPTIONS`. */
67
+ readonly descriptions?: { readonly create_upload?: string; readonly finalize_upload?: string };
68
+ /**
69
+ * The text answered for an error code, the hook's codes and the package's `files.*` codes alike, followed by the code.
70
+ * Without a hint a `files.*` code answers its English sentence and any other code answers the code alone.
71
+ */
72
+ readonly hints?: Readonly<Record<string, string>>;
73
+ }
74
+
75
+ /** What `onFinalized` answers: extra fields for the tool's answer, nothing, or a failure. */
76
+ export type FileFinalizedAnswer = Readonly<Record<string, unknown>> | Err<ErrorCode> | undefined | void;
77
+
78
+ const createUploadInput = z.object({
79
+ name: z.string().min(1).max(255).describe("The file's name, e.g. promo.mp4."),
80
+ size: z.number().int().min(1).describe("The file's exact size in bytes (e.g. from `wc -c < file`)."),
81
+ content_type: z.string().min(3).max(255).optional().describe("The media type, e.g. video/mp4."),
82
+ sha256: z
83
+ .string()
84
+ .regex(/^[0-9a-fA-F]{64}$/)
85
+ .optional()
86
+ .describe("The file's SHA-256 in hex; when given, the upload is refused unless the bytes match."),
87
+ });
88
+
89
+ const finalizeUploadInput = z.object({
90
+ upload_id: z.string().uuid().describe("The upload_id create_upload answered."),
91
+ });
92
+
93
+ /** Registers `create_upload` and `finalize_upload` for an identity that can write; does nothing for a read-only one. */
94
+ export function registerFileUploadTools(server: Pick<McpServer, "registerTool">, options: FileUploadToolsOptions): void {
95
+ if (!options.identity.canWrite) return;
96
+ const ownerId = (options.getOwnerId ?? ((identity) => identity.userId))(options.identity);
97
+
98
+ server.registerTool(
99
+ CREATE_UPLOAD_TOOL_NAME,
100
+ {
101
+ description: options.descriptions?.create_upload ?? FILE_UPLOAD_TOOL_DESCRIPTIONS.create_upload,
102
+ inputSchema: createUploadInput,
103
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
104
+ },
105
+ (args) =>
106
+ answer(CREATE_UPLOAD_TOOL_NAME, options.hints, async () => {
107
+ const ctx = await options.getContext();
108
+ const created = await createUpload(ctx, {
109
+ ownerId,
110
+ name: args.name,
111
+ size: args.size,
112
+ ...(args.content_type === undefined ? {} : { contentType: args.content_type }),
113
+ ...(args.sha256 === undefined ? {} : { sha256: args.sha256 }),
114
+ ...(options.kind === undefined ? {} : { kind: options.kind }),
115
+ });
116
+ return created.ok ? describeCreatedUpload(created.value, args.size) : created;
117
+ }),
118
+ );
119
+
120
+ server.registerTool(
121
+ FINALIZE_UPLOAD_TOOL_NAME,
122
+ {
123
+ description: options.descriptions?.finalize_upload ?? FILE_UPLOAD_TOOL_DESCRIPTIONS.finalize_upload,
124
+ inputSchema: finalizeUploadInput,
125
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
126
+ },
127
+ (args) =>
128
+ answer(FINALIZE_UPLOAD_TOOL_NAME, options.hints, async () => {
129
+ const ctx = await options.getContext();
130
+ const finalized = await finalizeUpload(ctx, args.upload_id, { ownerId });
131
+ if (!finalized.ok) return finalized;
132
+ const extra = options.onFinalized === undefined ? undefined : await options.onFinalized(finalized.value, ctx);
133
+ if (isFailure(extra)) return extra;
134
+ return { ...extra, ...describeStoredFile(finalized.value) };
135
+ }),
136
+ );
137
+ }
138
+
139
+ /**
140
+ * A bash loop that sends `$FILE` to an upload URL in chunks with `dd` and `curl` (GNU and BSD alike). It stops at the
141
+ * first failed chunk; `CHUNKS="3 4"` before the loop resends only those (the URL answers `missingChunks` to a GET).
142
+ */
143
+ export function buildCurlUploadScript(upload: Pick<CreatedUpload, "uploadUrl" | "chunkSize" | "chunkCount">, size: number): string {
144
+ const chunk = String(upload.chunkSize);
145
+ const total = String(size);
146
+ return [
147
+ `FILE='path/to/the/file'`,
148
+ `URL='${upload.uploadUrl}'`,
149
+ `for i in \${CHUNKS:-$(seq 0 ${String(upload.chunkCount - 1)})}; do`,
150
+ ` start=$((i * ${chunk})); end=$((start + ${chunk} - 1)); [ "$end" -ge ${total} ] && end=$((${total} - 1))`,
151
+ ` dd if="$FILE" bs=${chunk} skip="$i" count=1 2>/dev/null | curl -sS --fail -X PUT -H "Content-Range: bytes $start-$end/${total}" --data-binary @- "$URL" >/dev/null || { echo "chunk $i failed: run the loop again with CHUNKS=\\"$i ...\\""; break; }`,
152
+ `done`,
153
+ `curl -sS "$URL"`,
154
+ ].join("\n");
155
+ }
156
+
157
+ function describeCreatedUpload(upload: CreatedUpload, size: number) {
158
+ return {
159
+ upload_id: upload.uploadId,
160
+ upload_url: upload.uploadUrl,
161
+ chunk_size: upload.chunkSize,
162
+ chunk_count: upload.chunkCount,
163
+ expires_at: upload.expiresAt.toISOString(),
164
+ curl: buildCurlUploadScript(upload, size),
165
+ browser_page: upload.uploadUrl,
166
+ next_step:
167
+ "Set FILE in the curl loop to the file's path and run it; the last line prints the upload's state. When missingChunks is " +
168
+ "empty, call finalize_upload with this upload_id. A person without a shell can open browser_page instead.",
169
+ };
170
+ }
171
+
172
+ function describeStoredFile(file: StoredFile) {
173
+ return { file_id: file.id, name: file.name, size: file.size, content_type: file.contentType, sha256: file.sha256 };
174
+ }
175
+
176
+ /** The tool's answer: a value as JSON text, an error code as its hint or sentence, a thrown error as a fixed text. */
177
+ async function answer(
178
+ tool: string,
179
+ hints: Readonly<Record<string, string>> | undefined,
180
+ work: () => Promise<unknown>,
181
+ ): Promise<CallToolResult> {
182
+ try {
183
+ const value = await work();
184
+ if (isFailure(value)) return failure(describeErrorCode(value.error, hints));
185
+ return { content: [{ type: "text", text: JSON.stringify(value) }] };
186
+ } catch (error) {
187
+ console.error(`@softure-ai/files: tool ${tool} failed: ${errorLogLabel(error)}`);
188
+ return failure(filesMessages.en.errors.core.unexpected);
189
+ }
190
+ }
191
+
192
+ /** `<hint or files sentence> (<code>)`, or the code alone for another module's code without a hint. */
193
+ function describeErrorCode(code: string, hints: Readonly<Record<string, string>> | undefined): string {
194
+ const hint = hints !== undefined && Object.hasOwn(hints, code) ? hints[code] : undefined;
195
+ if (hint !== undefined) return `${hint} (${code})`;
196
+ if (code.startsWith("files.")) return `${getFilesErrorMessage(filesMessages.en, code)} (${code})`;
197
+ return code;
198
+ }
199
+
200
+ function failure(text: string): CallToolResult {
201
+ return { content: [{ type: "text", text }], isError: true };
202
+ }
203
+
204
+ function isFailure(value: unknown): value is { readonly ok: false; readonly error: string } {
205
+ return typeof value === "object" && value !== null && "ok" in value && value.ok === false && "error" in value && typeof value.error === "string";
206
+ }
@@ -8,9 +8,29 @@ export const en = {
8
8
  quota_exceeded: "There is no space left for this file.",
9
9
  not_found: "The file was not found.",
10
10
  range_not_satisfiable: "The requested part of the file is outside it.",
11
+ content_type_not_allowed: "This type of file cannot be uploaded.",
12
+ too_many_uploads: "Too many uploads are in progress. Finish or wait for one first.",
13
+ upload_incomplete: "The upload is not complete yet: some parts have not arrived.",
14
+ checksum_mismatch: "The uploaded file does not match its checksum.",
15
+ upload_expired: "This upload has expired. Start it again.",
16
+ upload_rejected: "The upload was refused: the file does not match what the upload expects.",
17
+ network: "The connection dropped. Try again to resume where it stopped.",
18
+ upload_aborted: "The upload was stopped.",
11
19
  },
12
20
  core: {
13
21
  unexpected: "Something went wrong. Try again.",
14
22
  },
15
23
  },
24
+ uploadPage: {
25
+ title: "Upload a file",
26
+ intro: "Choose the file this upload is waiting for. It is sent in parts, and a broken connection resumes where it stopped.",
27
+ expected: "Expected: {name}, {size}.",
28
+ choose: "Choose a file",
29
+ start: "Upload",
30
+ progress: "Uploaded {done} of {total}.",
31
+ done: "Upload complete. Go back to where you started it to finish.",
32
+ wrongSize: "This file has a different size than the upload expects.",
33
+ failed: "The upload stopped. Press Upload again to resume.",
34
+ expired: "This upload link has expired. Start a new upload where you began this one.",
35
+ },
16
36
  };
package/src/next/index.ts CHANGED
@@ -1,4 +1,12 @@
1
- // The Next.js adapter of @softure-ai/files: the public link route and the request-side context
2
- // (docs/02-module-standard.md §8).
1
+ // The Next.js adapter of @softure-ai/files: the public link route, the owner route, the upload route and the
2
+ // request-side context (docs/02-module-standard.md §8).
3
3
  export { getFilesContext } from "./context.js";
4
4
  export { serveFileLinkRoute } from "./route.js";
5
+ export {
6
+ createStoredFileRoute,
7
+ type StoredFileRoute,
8
+ type StoredFileRouteContext,
9
+ type StoredFileRouteHandler,
10
+ type StoredFileRouteOptions,
11
+ } from "./stored-file-route.js";
12
+ export { serveUploadRoute } from "./upload-route.js";
@@ -0,0 +1,43 @@
1
+ // The owner route of stored files, mounted behind the app's sign-in guard in `app/media/[id]/route.ts`:
2
+ // `export const { GET, HEAD } = createStoredFileRoute({ getOwnerId: async () => (await getCurrentUser())?.id ?? null });`
3
+ // The session check is the app's (files does not depend on auth); the owner check is the module's. Without a session,
4
+ // and for a file that is missing or another owner's, the route answers the same `404`, so it never tells whether a
5
+ // file exists.
6
+ import type { FilesContext } from "../server/context.js";
7
+ import { notFound, serveStoredFile } from "../server/serve.js";
8
+ import { getFilesContext } from "./context.js";
9
+
10
+ /** The second argument Next.js passes a handler of a `[id]` segment. */
11
+ export interface StoredFileRouteContext {
12
+ readonly params: Promise<{ readonly id: string }>;
13
+ }
14
+
15
+ export type StoredFileRouteHandler = (request: Request, route: StoredFileRouteContext) => Promise<Response>;
16
+
17
+ export interface StoredFileRoute {
18
+ readonly GET: StoredFileRouteHandler;
19
+ readonly HEAD: StoredFileRouteHandler;
20
+ }
21
+
22
+ export interface StoredFileRouteOptions {
23
+ /**
24
+ * The signed-in user's id, the same value the app passed to `saveFile({ ownerId })`; null when nobody is signed in
25
+ * (the route answers 404). Typically the app's session lookup through auth.
26
+ */
27
+ readonly getOwnerId: (request: Request) => Promise<string | null>;
28
+ /** `inline` (the default: a player, an image) or `attachment` (a download). */
29
+ readonly disposition?: "attachment" | "inline";
30
+ /** The context the route reads; `getFilesContext()` (the registered config's database) by default. */
31
+ readonly getContext?: () => Promise<FilesContext>;
32
+ }
33
+
34
+ export function createStoredFileRoute(options: StoredFileRouteOptions): StoredFileRoute {
35
+ const getContext = options.getContext ?? (() => getFilesContext());
36
+ const handle: StoredFileRouteHandler = async (request, route) => {
37
+ const ownerId = await options.getOwnerId(request);
38
+ if (ownerId === null) return notFound();
39
+ const { id } = await route.params;
40
+ return serveStoredFile(await getContext(), id, request, { ownerId, disposition: options.disposition });
41
+ };
42
+ return { GET: handle, HEAD: handle };
43
+ }
@@ -0,0 +1,11 @@
1
+ // The upload route, mounted with one line:
2
+ // `app/u/[...upload]/route.ts → export { serveUploadRoute as GET, serveUploadRoute as HEAD, serveUploadRoute as PUT } from "@softure-ai/files/next";`
3
+ // It reads no session: an upload URL is protected by its signature, so the route must stay outside the app's
4
+ // sign-in guard and the edge's sign-in (README §4). The path is read from the request URL, not from Next's params.
5
+ import { serveUpload } from "../server/serve-upload.js";
6
+ import { getFilesContext } from "./context.js";
7
+
8
+ /** `GET`, `HEAD` and `PUT /u/<id>/<expiry>.<signature>`. */
9
+ export async function serveUploadRoute(request: Request): Promise<Response> {
10
+ return serveUpload(await getFilesContext(), request);
11
+ }
package/src/options.ts CHANGED
@@ -9,6 +9,9 @@ const DAY_SECONDS = 24 * 60 * 60;
9
9
 
10
10
  /** A file kind: lowercase letters, digits, `_` and `-`, starting with a letter, at most 32 characters. */
11
11
  export const FILE_KIND_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/;
12
+ /** An allowed upload media type: `type/subtype` or `type/*`, lowercase. */
13
+ const CONTENT_TYPE_RULE_PATTERN = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/(\*|[a-z0-9][a-z0-9!#$&^_.+-]*)$/;
14
+
12
15
  /** The kind of a file saved without one. */
13
16
  export const DEFAULT_FILE_KIND = "file";
14
17
 
@@ -47,6 +50,31 @@ export const filesOptionsSchema = z.strictObject({
47
50
  disposition: z.enum(["attachment", "inline"]).default("attachment"),
48
51
  })
49
52
  .default({ maxTtlSeconds: 7 * DAY_SECONDS, disposition: "attachment" }),
53
+ uploads: z
54
+ .strictObject({
55
+ /**
56
+ * The bytes of one upload request: a chunk. Keep it under the edge's body limit (Cloudflare refuses bodies over
57
+ * 100 MB on Free and Pro plans).
58
+ */
59
+ chunkBytes: z
60
+ .number()
61
+ .int()
62
+ .min(1024)
63
+ .max(1024 * MIB)
64
+ .default(64 * MIB),
65
+ /** How long an upload session (and its URL) works; `createUpload` may ask for less. */
66
+ ttlSeconds: z
67
+ .number()
68
+ .int()
69
+ .min(60)
70
+ .max(7 * DAY_SECONDS)
71
+ .default(DAY_SECONDS),
72
+ /** Sessions one owner may have open at once (not finalized, not expired). */
73
+ maxOpenPerOwner: z.number().int().min(1).max(1000).default(5),
74
+ /** The media types an upload may declare (`video/mp4`, `video/*`); null: any. */
75
+ contentTypes: z.array(z.string().regex(CONTENT_TYPE_RULE_PATTERN, "must be type/subtype or type/*")).min(1).nullable().default(null),
76
+ })
77
+ .default({ chunkBytes: 64 * MIB, ttlSeconds: DAY_SECONDS, maxOpenPerOwner: 5, contentTypes: null }),
50
78
  health: z
51
79
  .strictObject({
52
80
  /** Below this many free bytes (when the driver can tell) the health check fails. */
package/src/schema.ts CHANGED
@@ -1,5 +1,5 @@
1
- // Drizzle view of the module's table (migrations/0001_create_files.sql). The migration is the source of truth;
2
- // this file only types the queries.
1
+ // Drizzle view of the module's tables (migrations 0001 and 0002). The migrations are the source of truth; this file
2
+ // only types the queries.
3
3
  import { bigint, integer, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
4
4
 
5
5
  export const filesSchema = pgSchema("files");
@@ -20,3 +20,21 @@ export const files = filesSchema.table("files", {
20
20
  });
21
21
 
22
22
  export type FileRow = typeof files.$inferSelect;
23
+
24
+ export const uploads = filesSchema.table("uploads", {
25
+ id: uuid("id").primaryKey(),
26
+ ownerId: text("owner_id").notNull(),
27
+ originalName: text("original_name").notNull(),
28
+ contentType: text("content_type").notNull(),
29
+ kind: text("kind").notNull(),
30
+ size: bigint("size", { mode: "number" }).notNull(),
31
+ sha256: text("sha256"),
32
+ chunkSize: integer("chunk_size").notNull(),
33
+ receivedChunks: integer("received_chunks").array().notNull(),
34
+ fileId: uuid("file_id"),
35
+ expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
36
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
37
+ finalizedAt: timestamp("finalized_at", { withTimezone: true }),
38
+ });
39
+
40
+ export type UploadRow = typeof uploads.$inferSelect;
@@ -29,7 +29,7 @@ export {
29
29
  } from "./links.js";
30
30
  export { createLocalStorage, type LocalStorageOptions } from "./local-storage.js";
31
31
  export { DEFAULT_CONTENT_TYPE, formatContentDisposition, normalizeContentType, sanitizeFileName } from "./names.js";
32
- export { getFilesModule, getFilesOptions, getLinksRoute } from "./options.js";
32
+ export { getFilesModule, getFilesOptions, getLinksRoute, getUploadsRoute } from "./options.js";
33
33
  export { deleteFilesUserData, exportFilesUserData, filesPrivacyContributor, type FilesDeletionReport, type FilesUserData } from "./privacy.js";
34
34
  export { pruneFiles, type PruneFilesOptions, type PruneFilesReport } from "./prune.js";
35
35
  export {
@@ -40,6 +40,24 @@ export {
40
40
  splitIntoParts,
41
41
  type S3StorageOptions,
42
42
  } from "./s3-storage.js";
43
- export { saveFile, type SaveFileInput, type SaveFileResult } from "./save.js";
44
- export { parseRangeHeader, serveFileLink } from "./serve.js";
43
+ export { saveFile, validateFileDescription, type FileDescription, type FileDescriptionInput, type SaveFileInput, type SaveFileResult } from "./save.js";
44
+ export {
45
+ countChunks,
46
+ createUpload,
47
+ finalizeUpload,
48
+ getPartKey,
49
+ getUpload,
50
+ writeUploadChunk,
51
+ type CreateUploadInput,
52
+ type CreateUploadResult,
53
+ type FinalizeUploadResult,
54
+ type UploadChunkErrorCode,
55
+ type UploadLookupOptions,
56
+ type WriteUploadChunkInput,
57
+ type WriteUploadChunkResult,
58
+ } from "./uploads.js";
59
+ export { signUploadPath, verifyUploadPath } from "./upload-tokens.js";
60
+ export { FILES_UPLOAD_RATE_LIMIT_BUCKET, serveUpload } from "./serve-upload.js";
61
+ export { renderUploadPage } from "./upload-page.js";
62
+ export { parseRangeHeader, serveFileLink, serveStoredFile, type ServeStoredFileOptions } from "./serve.js";
45
63
  export { EMPTY_PAYLOAD_SHA256, encodeRfc3986, signRequest, type SigV4Credentials, type SignRequestInput } from "./sigv4.js";
@@ -26,6 +26,14 @@ export function getLinksRoute(config: SoftureConfig): string {
26
26
  return trimTrailingSlashes(links);
27
27
  }
28
28
 
29
+ /** The path prefix of upload URLs after the app's override (`files({ routes: { uploads } })`), without a trailing slash. */
30
+ export function getUploadsRoute(config: SoftureConfig): string {
31
+ const { uploads } = getFilesModule(config).routes;
32
+ // The manifest declares it, so a missing one means a broken module definition.
33
+ if (uploads === undefined) throw new Error("@softure-ai/files: the uploads route is missing from the module manifest");
34
+ return trimTrailingSlashes(uploads);
35
+ }
36
+
29
37
  /** The path without trailing slashes; a loop, not `/\/+$/`, which backtracks quadratically on a run of slashes. */
30
38
  function trimTrailingSlashes(path: string): string {
31
39
  let end = path.length;
@@ -1,24 +1,31 @@
1
1
  // The files part of a GDPR export and deletion (`@softure-ai/privacy`). A file belongs to its owner: the export
2
2
  // lists the owner's live files (never the bytes or the storage key; the app links them itself when it wants), and
3
- // the deletion removes every file of the owner from storage and the table.
3
+ // the deletion removes every file of the owner from storage and the table. Upload sessions are the owner's too: the
4
+ // export lists the open ones, the deletion removes all of them with their parts.
4
5
  import { ok, type Ok, type PrivacyContributor } from "@softure-ai/core";
5
6
  import type { Queryable } from "@softure-ai/db";
6
7
  import { and, asc, eq } from "drizzle-orm";
7
- import type { StoredFile } from "../contract.js";
8
+ import type { StoredFile, UploadStatus } from "../contract.js";
8
9
  import { files } from "../schema.js";
9
10
  import { toStoredFile, type FilesContext } from "./context.js";
10
11
  import { removeMarkedFile } from "./files.js";
11
12
  import { isLive } from "./queries.js";
13
+ import { deleteOwnerUploads, listOpenUploads } from "./uploads.js";
12
14
 
13
15
  /** What files holds about one user, as it appears in their export. */
14
16
  export interface FilesUserData {
15
17
  readonly files: readonly StoredFile[];
18
+ /** Upload sessions still taking chunks. */
19
+ readonly uploads: readonly UploadStatus[];
16
20
  }
17
21
 
18
22
  export interface FilesDeletionReport {
19
23
  readonly deletedFiles: number;
20
24
  /** Files whose storage delete failed; their rows stay marked deleted and `pruneFiles` removes them. */
21
25
  readonly pendingFiles: number;
26
+ readonly deletedUploads: number;
27
+ /** Sessions whose parts could not be deleted; `pruneFiles` removes them once they expire. */
28
+ readonly pendingUploads: number;
22
29
  }
23
30
 
24
31
  export async function exportFilesUserData(ctx: FilesContext, userId: string): Promise<Ok<FilesUserData>> {
@@ -27,7 +34,7 @@ export async function exportFilesUserData(ctx: FilesContext, userId: string): Pr
27
34
  .from(files)
28
35
  .where(and(eq(files.ownerId, userId), isLive(ctx.clock.now())))
29
36
  .orderBy(asc(files.createdAt), asc(files.id));
30
- return ok({ files: rows.map(toStoredFile) });
37
+ return ok({ files: rows.map(toStoredFile), uploads: await listOpenUploads(ctx, userId) });
31
38
  }
32
39
 
33
40
  export async function deleteFilesUserData(ctx: FilesContext, userId: string): Promise<Ok<FilesDeletionReport>> {
@@ -39,7 +46,8 @@ export async function deleteFilesUserData(ctx: FilesContext, userId: string): Pr
39
46
  for (const row of rows) {
40
47
  if (await removeMarkedFile(ctx, row)) deletedFiles += 1;
41
48
  }
42
- return ok({ deletedFiles, pendingFiles: rows.length - deletedFiles });
49
+ const removedUploads = await deleteOwnerUploads(ctx, userId);
50
+ return ok({ deletedFiles, pendingFiles: rows.length - deletedFiles, deletedUploads: removedUploads.deletedUploads, pendingUploads: removedUploads.failedUploads });
43
51
  }
44
52
 
45
53
  export const filesPrivacyContributor: PrivacyContributor = {
@@ -1,9 +1,11 @@
1
- // Retention: files past their expiry and files deleted but not yet out of storage leave storage, then the table.
1
+ // Retention: files past their expiry and files deleted but not yet out of storage leave storage, then the table;
2
+ // upload sessions past their expiry leave with their parts.
2
3
  // Run it from the `files.prune` job (`@softure-ai/files/jobs`) or a cron calling `pruneFiles(ctx)`.
3
4
  import { asc, isNotNull, lte, or } from "drizzle-orm";
4
5
  import { files } from "../schema.js";
5
6
  import type { FilesContext } from "./context.js";
6
7
  import { removeMarkedFile } from "./files.js";
8
+ import { pruneUploads } from "./uploads.js";
7
9
 
8
10
  const DEFAULT_BATCH_SIZE = 500;
9
11
 
@@ -17,6 +19,10 @@ export interface PruneFilesReport {
17
19
  readonly freedBytes: number;
18
20
  /** Files whose storage delete failed; they stay for the next run. */
19
21
  readonly failedFiles: number;
22
+ /** Expired upload sessions removed with their parts. */
23
+ readonly deletedUploads: number;
24
+ /** Expired upload sessions whose parts could not be deleted; they stay for the next run. */
25
+ readonly failedUploads: number;
20
26
  }
21
27
 
22
28
  export async function pruneFiles(ctx: FilesContext, options: PruneFilesOptions = {}): Promise<PruneFilesReport> {
@@ -41,6 +47,6 @@ export async function pruneFiles(ctx: FilesContext, options: PruneFilesOptions =
41
47
  failedFiles += 1;
42
48
  }
43
49
  }
44
- if (rows.length < batchSize) return { deletedFiles, freedBytes, failedFiles };
50
+ if (rows.length < batchSize) return { deletedFiles, freedBytes, failedFiles, ...(await pruneUploads(ctx, batchSize)) };
45
51
  }
46
52
  }
@@ -123,27 +123,41 @@ export async function saveFile(ctx: FilesContext, input: SaveFileInput): Promise
123
123
  return stored.ok ? ok(stored.value.row) : stored;
124
124
  }
125
125
 
126
- interface ValidFields {
126
+ interface ValidFields extends FileDescription {
127
+ readonly expiresAt: Date | null;
128
+ }
129
+
130
+ function validateFields(input: SaveFileInput, now: Date, defaultTtlSeconds: number | null): Ok<ValidFields> | Err<"files.invalid_input"> {
131
+ const described = validateFileDescription(input);
132
+ if (!described.ok) return described;
133
+ const expiresAt = resolveExpiry(input, now, defaultTtlSeconds);
134
+ if (expiresAt === false) return err("files.invalid_input");
135
+ return ok({ ...described.value, expiresAt });
136
+ }
137
+
138
+ /** What describes a file before its bytes, as a caller gives it. */
139
+ export interface FileDescriptionInput {
140
+ readonly ownerId: string;
141
+ readonly name: string;
142
+ readonly contentType?: string;
143
+ readonly kind?: string;
144
+ }
145
+
146
+ /** The description made safe to store: the owner checked, the name sanitised, the media type normalised. */
147
+ export interface FileDescription {
127
148
  readonly originalName: string;
128
149
  readonly contentType: string;
129
150
  readonly kind: string;
130
- readonly expiresAt: Date | null;
131
151
  }
132
152
 
133
- function validateFields(input: SaveFileInput, now: Date, defaultTtlSeconds: number | null): Ok<ValidFields> | Err<"files.invalid_input"> {
153
+ /** Checks the owner, kind and media type of a file to save or upload, and sanitises its name. */
154
+ export function validateFileDescription(input: FileDescriptionInput): Ok<FileDescription> | Err<"files.invalid_input"> {
134
155
  if (input.ownerId.length === 0 || input.ownerId.length > MAX_OWNER_ID_LENGTH) return err("files.invalid_input");
135
156
  const kind = input.kind ?? DEFAULT_FILE_KIND;
136
157
  if (!FILE_KIND_PATTERN.test(kind)) return err("files.invalid_input");
137
158
  const contentType = normalizeContentType(input.contentType ?? DEFAULT_CONTENT_TYPE);
138
159
  if (contentType === null) return err("files.invalid_input");
139
- const expiresAt = resolveExpiry(input, now, defaultTtlSeconds);
140
- if (expiresAt === false) return err("files.invalid_input");
141
- return ok({
142
- originalName: sanitizeFileName(input.name),
143
- contentType,
144
- kind,
145
- expiresAt,
146
- });
160
+ return ok({ originalName: sanitizeFileName(input.name), contentType, kind });
147
161
  }
148
162
 
149
163
  /** The expiry from `expiresAt`, `ttlSeconds` or the default; false when the input is contradictory or in the past. */