@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,437 @@
1
+ // Upload sessions: a client that cannot hand the server a stream (an assistant in its own sandbox, a phone over a
2
+ // proxy with a body limit) sends a file in chunks to a signed URL, and `finalizeUpload` turns them into a stored file.
3
+ //
4
+ // Every chunk but the last is `chunk_size` bytes and starts at a multiple of it, so "which bytes arrived" is the set
5
+ // of chunk indices in `received_chunks`. Each chunk is its own object in storage (`uploads/<id>/<index>`), written
6
+ // atomically by the driver and recorded only once whole; a recorded chunk is never rewritten, so a finalize reads
7
+ // parts that cannot change under it. The finalize streams the parts in order into `saveFile`, which hashes, counts,
8
+ // applies the quota and dedupe and writes the one final object (multipart on S3), then the parts are removed.
9
+ import { createHash, randomUUID } from "node:crypto";
10
+ import { err, errorLogLabel, ok, type Err, type Ok } from "@softure-ai/core";
11
+ import type { Queryable } from "@softure-ai/db";
12
+ import { and, asc, eq, gt, isNull, lte, sql, type SQL } from "drizzle-orm";
13
+ import type { ByteRange, CreatedUpload, FilesKeyErrorCode, FilesSaveErrorCode, StoredFile, UploadState, UploadStatus } from "../contract.js";
14
+ import { uploads, type UploadRow } from "../schema.js";
15
+ import type { FileBody, FileStorage } from "../storage.js";
16
+ import type { FilesContext } from "./context.js";
17
+ import { deleteFile, findFile, UUID_PATTERN } from "./files.js";
18
+ import { readLinkKeyring } from "./keys.js";
19
+ import { getFilesOptions } from "./options.js";
20
+ import { sumOwnerBytes } from "./queries.js";
21
+ import { saveFile, validateFileDescription } from "./save.js";
22
+ import { signUploadPath } from "./upload-tokens.js";
23
+
24
+ const SHA256_PATTERN = /^[0-9a-f]{64}$/;
25
+ const PART_PREFIX = "uploads";
26
+
27
+ export interface CreateUploadInput {
28
+ readonly ownerId: string;
29
+ /** The name the file will be saved under; only its last path part is kept, sanitised. */
30
+ readonly name: string;
31
+ /** Defaults to `application/octet-stream`; must match `uploads.contentTypes` when the app set it. */
32
+ readonly contentType?: string;
33
+ /** The exact size in bytes, at least 1 and at most `maxFileBytes`. */
34
+ readonly size: number;
35
+ /** The lowercase hex SHA-256 the bytes must have; checked at finalize. */
36
+ readonly sha256?: string;
37
+ /** The saved file's category; defaults to `file`. */
38
+ readonly kind?: string;
39
+ /** How long the session works, at most `uploads.ttlSeconds` (its default). */
40
+ readonly ttlSeconds?: number;
41
+ }
42
+
43
+ export type CreateUploadResult =
44
+ | Ok<CreatedUpload>
45
+ | Err<"files.invalid_input" | "files.too_large" | "files.quota_exceeded" | "files.content_type_not_allowed" | "files.too_many_uploads" | FilesKeyErrorCode>;
46
+
47
+ /** Opens an upload session for `ownerId` and answers the URL the client sends the chunks to. */
48
+ export async function createUpload(ctx: FilesContext, input: CreateUploadInput): Promise<CreateUploadResult> {
49
+ const options = getFilesOptions(ctx.config);
50
+ const described = validateFileDescription(input);
51
+ if (!described.ok) return described;
52
+ const sha256 = input.sha256?.toLowerCase();
53
+ const ttlSeconds = input.ttlSeconds ?? options.uploads.ttlSeconds;
54
+ const isValid =
55
+ Number.isSafeInteger(input.size) &&
56
+ input.size >= 1 &&
57
+ (sha256 === undefined || SHA256_PATTERN.test(sha256)) &&
58
+ Number.isSafeInteger(ttlSeconds) &&
59
+ ttlSeconds >= 1 &&
60
+ ttlSeconds <= options.uploads.ttlSeconds;
61
+ if (!isValid) return err("files.invalid_input");
62
+ if (input.size > options.maxFileBytes) return err("files.too_large");
63
+ if (!isContentTypeAllowed(described.value.contentType, options.uploads.contentTypes)) return err("files.content_type_not_allowed");
64
+ const keyring = readLinkKeyring(ctx.env ?? process.env);
65
+ if (!keyring.ok) return keyring;
66
+
67
+ const now = ctx.clock.now();
68
+ const id = randomUUID();
69
+ // Whole seconds, so the URL's expiry and the row's agree.
70
+ const expiresAt = new Date((Math.floor(now.getTime() / 1000) + ttlSeconds) * 1000);
71
+ const chunkSize = options.uploads.chunkBytes;
72
+ const opened = await ctx.db.transaction(async (tx: Queryable) => {
73
+ // The same lock as saveFile: the quota and the open sessions are read with nothing of this owner changing.
74
+ await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`files:${input.ownerId}`}, 0))`);
75
+ const [open] = await tx
76
+ .select({ count: sql<number>`count(*)::int` })
77
+ .from(uploads)
78
+ .where(and(eq(uploads.ownerId, input.ownerId), isNull(uploads.fileId), gt(uploads.expiresAt, now)));
79
+ if ((open?.count ?? 0) >= options.uploads.maxOpenPerOwner) return err("files.too_many_uploads");
80
+ if (options.quotaBytesPerOwner !== null && (await sumOwnerBytes(tx, input.ownerId, now)) + input.size > options.quotaBytesPerOwner) {
81
+ return err("files.quota_exceeded");
82
+ }
83
+ await tx.insert(uploads).values({
84
+ id,
85
+ ownerId: input.ownerId,
86
+ ...described.value,
87
+ size: input.size,
88
+ sha256: sha256 ?? null,
89
+ chunkSize,
90
+ receivedChunks: [],
91
+ expiresAt,
92
+ createdAt: now,
93
+ });
94
+ return ok();
95
+ });
96
+ if (!opened.ok) return opened;
97
+ const path = signUploadPath(ctx, keyring.value, id, expiresAt);
98
+ return ok({
99
+ uploadId: id,
100
+ uploadUrl: new URL(path, ctx.config.appOrigin).toString(),
101
+ chunkSize,
102
+ chunkCount: countChunks(input.size, chunkSize),
103
+ expiresAt,
104
+ });
105
+ }
106
+
107
+ export interface UploadLookupOptions {
108
+ /** Only this owner's session; another owner's reads as missing. */
109
+ readonly ownerId?: string;
110
+ }
111
+
112
+ /** A session that has not expired, or null. A finalized one is answered too (state `finalized`). */
113
+ export async function getUpload(ctx: FilesContext, uploadId: string, options: UploadLookupOptions = {}): Promise<UploadStatus | null> {
114
+ const row = await findUploadRow(ctx, uploadId, options);
115
+ return row === undefined ? null : toUploadStatus(row, ctx.clock.now());
116
+ }
117
+
118
+ /** The chunk a request carries: a byte range of the file, or null for the whole file in one request. */
119
+ export interface WriteUploadChunkInput {
120
+ readonly range: ByteRange | null;
121
+ /** The total the client declared (`Content-Range: bytes a-b/<total>`); must be the session's size. */
122
+ readonly total?: number;
123
+ readonly body: FileBody;
124
+ }
125
+
126
+ /** Why a chunk was refused. */
127
+ export type UploadChunkErrorCode =
128
+ /** No open session has this id (unknown, finalized or expired). */
129
+ | "files.not_found"
130
+ /** The range is not one chunk of this session (misaligned, wrong length, wrong total, a file larger than one chunk without a range). */
131
+ | "files.invalid_range"
132
+ /** The body had fewer or more bytes than the range. */
133
+ | "files.chunk_length_mismatch";
134
+
135
+ export type WriteUploadChunkResult = Ok<UploadStatus> | Err<UploadChunkErrorCode>;
136
+
137
+ /** Thrown into the driver's write when a body passes its range; the driver drops the partial object. */
138
+ class ChunkOverflowError extends Error {
139
+ constructor() {
140
+ super("@softure-ai/files: the chunk body passed its range");
141
+ }
142
+ }
143
+
144
+ /**
145
+ * Stores one chunk of an open session. A chunk that already arrived is answered as is, without reading the body:
146
+ * a client that resends it after a lost answer loses nothing. A storage failure propagates.
147
+ */
148
+ export async function writeUploadChunk(ctx: FilesContext, uploadId: string, input: WriteUploadChunkInput): Promise<WriteUploadChunkResult> {
149
+ const row = await findUploadRow(ctx, uploadId);
150
+ if (row?.fileId !== null || row.expiresAt.getTime() <= ctx.clock.now().getTime()) return err("files.not_found");
151
+ const index = findChunkIndex(row, input);
152
+ if (index === null) return err("files.invalid_range");
153
+ if (row.receivedChunks.includes(index)) return ok(toUploadStatus(row, ctx.clock.now()));
154
+
155
+ const expected = getChunkLength(row, index);
156
+ const storage = getFilesOptions(ctx.config).storage;
157
+ const key = getPartKey(row.id, index);
158
+ let length = 0;
159
+ async function* capped(): AsyncGenerator<Uint8Array> {
160
+ for await (const chunk of input.body as AsyncIterable<Uint8Array | string>) {
161
+ const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
162
+ length += bytes.byteLength;
163
+ if (length > expected) throw new ChunkOverflowError();
164
+ yield bytes;
165
+ }
166
+ }
167
+ try {
168
+ await storage.put(capped(), key);
169
+ } catch (error) {
170
+ if (error instanceof ChunkOverflowError) return err("files.chunk_length_mismatch");
171
+ throw error;
172
+ }
173
+ if (length !== expected) {
174
+ await deletePartQuietly(storage, key);
175
+ return err("files.chunk_length_mismatch");
176
+ }
177
+ // One statement, so parallel chunks of one session never lose each other's index.
178
+ const [updated] = await ctx.db
179
+ .update(uploads)
180
+ .set({
181
+ receivedChunks: sql`case when ${index}::int = any(${uploads.receivedChunks}) then ${uploads.receivedChunks} else array_append(${uploads.receivedChunks}, ${index}::int) end`,
182
+ })
183
+ .where(and(eq(uploads.id, row.id), isNull(uploads.fileId)))
184
+ .returning();
185
+ // Finalized in the meantime: the part is not needed, and the session no longer takes chunks.
186
+ if (updated === undefined) {
187
+ await deletePartQuietly(storage, key);
188
+ return err("files.not_found");
189
+ }
190
+ return ok(toUploadStatus(updated, ctx.clock.now()));
191
+ }
192
+
193
+ export type FinalizeUploadResult = Ok<StoredFile> | Err<"files.not_found" | "files.upload_incomplete" | "files.checksum_mismatch" | FilesSaveErrorCode>;
194
+
195
+ /** Thrown into the save when a part is missing from storage. */
196
+ class MissingPartError extends Error {
197
+ constructor(readonly index: number) {
198
+ super(`@softure-ai/files: upload part ${String(index)} is missing from storage`);
199
+ }
200
+ }
201
+
202
+ /** Thrown into the save when the bytes do not match the declared size or SHA-256; the save drops its object. */
203
+ class ContentMismatchError extends Error {
204
+ constructor() {
205
+ super("@softure-ai/files: the uploaded bytes do not match the declared size or SHA-256");
206
+ }
207
+ }
208
+
209
+ /**
210
+ * Turns a complete session into a stored file: every chunk present, the size and the declared SHA-256 checked while
211
+ * the parts stream into `saveFile` (quota and dedupe as there), then the parts are removed. Calling it again answers
212
+ * the same file; two parallel calls keep one.
213
+ */
214
+ export async function finalizeUpload(ctx: FilesContext, uploadId: string, options: UploadLookupOptions = {}): Promise<FinalizeUploadResult> {
215
+ const row = await findUploadRow(ctx, uploadId, options);
216
+ if (row === undefined) return err("files.not_found");
217
+ if (row.fileId !== null) return answerFinalizedFile(ctx, row.fileId);
218
+ const chunkCount = countChunks(row.size, row.chunkSize);
219
+ if (row.receivedChunks.length < chunkCount) return err("files.upload_incomplete");
220
+
221
+ const storage = getFilesOptions(ctx.config).storage;
222
+ let saved;
223
+ try {
224
+ saved = await saveFile(ctx, {
225
+ ownerId: row.ownerId,
226
+ name: row.originalName,
227
+ contentType: row.contentType,
228
+ kind: row.kind,
229
+ body: readParts(storage, row, chunkCount),
230
+ });
231
+ } catch (error) {
232
+ if (error instanceof ContentMismatchError) return err("files.checksum_mismatch");
233
+ if (!(error instanceof MissingPartError)) throw error;
234
+ console.error(`@softure-ai/files: upload ${row.id} lost part ${String(error.index)} in storage; the client must send it again`);
235
+ await ctx.db
236
+ .update(uploads)
237
+ .set({ receivedChunks: sql`array_remove(${uploads.receivedChunks}, ${error.index}::int)` })
238
+ .where(eq(uploads.id, row.id));
239
+ return err("files.upload_incomplete");
240
+ }
241
+ if (!saved.ok) return saved;
242
+
243
+ const [claimed] = await ctx.db
244
+ .update(uploads)
245
+ .set({ fileId: saved.value.id, finalizedAt: ctx.clock.now() })
246
+ .where(and(eq(uploads.id, row.id), isNull(uploads.fileId)))
247
+ .returning();
248
+ if (claimed === undefined) {
249
+ // Another finalize won: keep its file, drop this copy (unless dedupe answered that very file).
250
+ const winner = await findUploadRow(ctx, row.id);
251
+ const winnerFileId = winner?.fileId ?? null;
252
+ if (winnerFileId !== saved.value.id) await deleteFile(ctx, saved.value.id);
253
+ return winnerFileId === null ? err("files.not_found") : answerFinalizedFile(ctx, winnerFileId);
254
+ }
255
+ await deleteParts(storage, row);
256
+ return saved;
257
+ }
258
+
259
+ /** Removes sessions whose time is up, with their parts; answers how many went and how many must wait for the next run. */
260
+ export async function pruneUploads(ctx: FilesContext, batchSize: number): Promise<{ readonly deletedUploads: number; readonly failedUploads: number }> {
261
+ const storage = getFilesOptions(ctx.config).storage;
262
+ const now = ctx.clock.now();
263
+ let deletedUploads = 0;
264
+ let failedUploads = 0;
265
+ for (;;) {
266
+ const rows = await ctx.db
267
+ .select()
268
+ .from(uploads)
269
+ .where(lte(uploads.expiresAt, now))
270
+ .orderBy(asc(uploads.expiresAt), asc(uploads.id))
271
+ .limit(batchSize)
272
+ .offset(failedUploads);
273
+ for (const row of rows) {
274
+ if (await removeUpload(ctx, storage, row)) deletedUploads += 1;
275
+ else failedUploads += 1;
276
+ }
277
+ if (rows.length < batchSize) return { deletedUploads, failedUploads };
278
+ }
279
+ }
280
+
281
+ /** An owner's sessions with their parts (the privacy deletion); answers how many went and how many stay for prune. */
282
+ export async function deleteOwnerUploads(ctx: FilesContext, ownerId: string): Promise<{ readonly deletedUploads: number; readonly failedUploads: number }> {
283
+ const storage = getFilesOptions(ctx.config).storage;
284
+ const rows = await ctx.db.select().from(uploads).where(eq(uploads.ownerId, ownerId));
285
+ let deletedUploads = 0;
286
+ for (const row of rows) {
287
+ if (await removeUpload(ctx, storage, row)) deletedUploads += 1;
288
+ }
289
+ return { deletedUploads, failedUploads: rows.length - deletedUploads };
290
+ }
291
+
292
+ /** An owner's sessions that still take chunks (the privacy export). */
293
+ export async function listOpenUploads(ctx: FilesContext, ownerId: string): Promise<UploadStatus[]> {
294
+ const now = ctx.clock.now();
295
+ const rows = await ctx.db
296
+ .select()
297
+ .from(uploads)
298
+ .where(and(eq(uploads.ownerId, ownerId), isNull(uploads.fileId), gt(uploads.expiresAt, now)))
299
+ .orderBy(asc(uploads.createdAt), asc(uploads.id));
300
+ return rows.map((row) => toUploadStatus(row, now));
301
+ }
302
+
303
+ /** The storage key of one chunk of a session. */
304
+ export function getPartKey(uploadId: string, index: number): string {
305
+ return `${PART_PREFIX}/${uploadId}/${String(index)}`;
306
+ }
307
+
308
+ /** How many chunks a file of `size` bytes takes. */
309
+ export function countChunks(size: number, chunkSize: number): number {
310
+ return Math.ceil(size / chunkSize);
311
+ }
312
+
313
+ /** The session row, unless it expired. Not a uuid reads as missing. */
314
+ async function findUploadRow(ctx: FilesContext, uploadId: string, options: UploadLookupOptions = {}): Promise<UploadRow | undefined> {
315
+ if (!UUID_PATTERN.test(uploadId)) return undefined;
316
+ const conditions: SQL[] = [eq(uploads.id, uploadId), gt(uploads.expiresAt, ctx.clock.now())];
317
+ if (options.ownerId !== undefined) conditions.push(eq(uploads.ownerId, options.ownerId));
318
+ const [row] = await ctx.db
319
+ .select()
320
+ .from(uploads)
321
+ .where(and(...conditions));
322
+ return row;
323
+ }
324
+
325
+ async function answerFinalizedFile(ctx: FilesContext, fileId: string): Promise<Ok<StoredFile> | Err<"files.not_found">> {
326
+ const file = await findFile(ctx, fileId);
327
+ return file === null ? err("files.not_found") : ok(file);
328
+ }
329
+
330
+ /** The chunk index a request's range names, or null when it is not exactly one chunk of the session. */
331
+ function findChunkIndex(row: UploadRow, input: WriteUploadChunkInput): number | null {
332
+ if (input.total !== undefined && input.total !== row.size) return null;
333
+ if (input.range === null) return row.size <= row.chunkSize ? 0 : null;
334
+ const { start, end } = input.range;
335
+ if (!Number.isSafeInteger(start) || start < 0 || start % row.chunkSize !== 0 || start >= row.size) return null;
336
+ const index = start / row.chunkSize;
337
+ return end === start + getChunkLength(row, index) - 1 ? index : null;
338
+ }
339
+
340
+ function getChunkLength(row: Pick<UploadRow, "size" | "chunkSize">, index: number): number {
341
+ return Math.min(row.chunkSize, row.size - index * row.chunkSize);
342
+ }
343
+
344
+ /** The parts in order, checked against the declared size and SHA-256 as they pass. */
345
+ async function* readParts(storage: FileStorage, row: UploadRow, chunkCount: number): AsyncGenerator<Uint8Array> {
346
+ const hash = createHash("sha256");
347
+ let size = 0;
348
+ for (let index = 0; index < chunkCount; index += 1) {
349
+ const stream = await storage.get(getPartKey(row.id, index));
350
+ if (stream === null) throw new MissingPartError(index);
351
+ const reader = stream.getReader();
352
+ for (;;) {
353
+ const { done, value } = await reader.read();
354
+ if (done) break;
355
+ size += value.byteLength;
356
+ hash.update(value);
357
+ yield value;
358
+ }
359
+ }
360
+ if (size !== row.size || (row.sha256 !== null && hash.digest("hex") !== row.sha256)) throw new ContentMismatchError();
361
+ }
362
+
363
+ function toUploadStatus(row: UploadRow, now: Date): UploadStatus {
364
+ const chunkCount = countChunks(row.size, row.chunkSize);
365
+ const received = new Set(row.receivedChunks);
366
+ const missingChunks = Array.from({ length: chunkCount }, (_, index) => index).filter((index) => !received.has(index));
367
+ return {
368
+ uploadId: row.id,
369
+ name: row.originalName,
370
+ contentType: row.contentType,
371
+ size: row.size,
372
+ chunkSize: row.chunkSize,
373
+ chunkCount,
374
+ received: mergeChunkRanges(row, [...received].sort((left, right) => left - right)),
375
+ receivedBytes: [...received].reduce((total, index) => total + getChunkLength(row, index), 0),
376
+ missingChunks,
377
+ state: getUploadState(row, missingChunks.length, now),
378
+ fileId: row.fileId,
379
+ expiresAt: row.expiresAt,
380
+ };
381
+ }
382
+
383
+ function getUploadState(row: UploadRow, missingCount: number, now: Date): UploadState {
384
+ if (row.fileId !== null) return "finalized";
385
+ if (row.expiresAt.getTime() <= now.getTime()) return "expired";
386
+ return missingCount === 0 ? "complete" : "open";
387
+ }
388
+
389
+ /** Sorted chunk indices as merged byte ranges. */
390
+ function mergeChunkRanges(row: UploadRow, indices: readonly number[]): ByteRange[] {
391
+ const ranges: ByteRange[] = [];
392
+ for (const index of indices) {
393
+ const start = index * row.chunkSize;
394
+ const end = start + getChunkLength(row, index) - 1;
395
+ const last = ranges.at(-1);
396
+ if (last !== undefined && last.end + 1 === start) ranges[ranges.length - 1] = { start: last.start, end };
397
+ else ranges.push({ start, end });
398
+ }
399
+ return ranges;
400
+ }
401
+
402
+ /** Whether a normalised media type matches one of the allowed rules (`video/mp4`, `video/*`); null allows any. */
403
+ function isContentTypeAllowed(contentType: string, rules: readonly string[] | null): boolean {
404
+ if (rules === null) return true;
405
+ const essence = contentType.split(";")[0] ?? "";
406
+ const [type = ""] = essence.split("/");
407
+ return rules.some((rule) => rule === essence || rule === `${type}/*`);
408
+ }
409
+
410
+ /** Removes a session's parts and then its row; answers whether both went. */
411
+ async function removeUpload(ctx: FilesContext, storage: FileStorage, row: UploadRow): Promise<boolean> {
412
+ try {
413
+ for (let index = 0; index < countChunks(row.size, row.chunkSize); index += 1) await storage.delete(getPartKey(row.id, index));
414
+ } catch (error) {
415
+ console.error(`@softure-ai/files: deleting the parts of upload ${row.id} failed, pruneFiles retries: ${errorLogLabel(error)}`);
416
+ return false;
417
+ }
418
+ await ctx.db.delete(uploads).where(eq(uploads.id, row.id));
419
+ return true;
420
+ }
421
+
422
+ /** Removes the parts of a finalized session; a failure is logged and the prune of the expired session retries. */
423
+ async function deleteParts(storage: FileStorage, row: UploadRow): Promise<void> {
424
+ try {
425
+ for (let index = 0; index < countChunks(row.size, row.chunkSize); index += 1) await storage.delete(getPartKey(row.id, index));
426
+ } catch (error) {
427
+ console.error(`@softure-ai/files: deleting the parts of finalized upload ${row.id} failed, pruneFiles retries: ${errorLogLabel(error)}`);
428
+ }
429
+ }
430
+
431
+ async function deletePartQuietly(storage: FileStorage, key: string): Promise<void> {
432
+ try {
433
+ await storage.delete(key);
434
+ } catch (error) {
435
+ console.error(`@softure-ai/files: deleting a refused upload part failed: ${errorLogLabel(error)}`);
436
+ }
437
+ }