@orpc/node 2.0.0-beta.47 → 2.0.0-beta.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,465 @@
1
+ import { Buffer } from 'node:buffer';
2
+ import { openAsBlob } from 'node:fs';
3
+ import { appendFile, mkdtemp, rm } from 'node:fs/promises';
4
+ import { tmpdir } from 'node:os';
5
+ import path from 'node:path';
6
+ import { ORPCError } from '@orpc/server';
7
+ import { isAsyncIteratorObject, override, toArray, value, wrapAsyncIterator, wrapReadableStream, } from '@orpc/shared';
8
+ import { flattenStandardHeader, getFilenameFromContentDisposition, resolveStandardBodyHint, } from '@standard-server/core';
9
+ import { toFetchHeaders, toStandardBody } from '@standard-server/fetch';
10
+ import { parseHeaderParameters, parseMultipart } from './multipart.js';
11
+ /**
12
+ * A `File` whose content lives in a temporary file on disk and is read lazily,
13
+ * so it can represent an upload far larger than available memory.
14
+ *
15
+ * @remarks
16
+ * Node's `fs.openAsBlob`, which backs this class, has known bugs with files
17
+ * over 2 GiB ({@link https://github.com/nodejs/node/issues/52585}): `size` is
18
+ * truncated above 4 GiB and `slice()` is unreliable above 2 GiB, while
19
+ * whole-file reads like `stream()` stay correct. When size or random access
20
+ * matters for such a file, stat or read {@link path} directly.
21
+ *
22
+ * @see {@link https://orpc.dev/docs/plugins/tmp-file-upload | Tmp File Upload Plugin}
23
+ */
24
+ export class TmpFile extends File {
25
+ path;
26
+ constructor(blob,
27
+ /**
28
+ * Absolute path of the temporary file holding this file's content.
29
+ * The file is removed when the request finishes, so move or copy it
30
+ * to keep the content. The `File` reads from this path, so it must
31
+ * not be read after the file is moved or removed.
32
+ */
33
+ path, name, options) {
34
+ super([blob], name, options);
35
+ this.path = path;
36
+ }
37
+ }
38
+ /**
39
+ * Parses file uploads into temporary files instead of memory. Bodies the standard
40
+ * body parser would buffer into an in-memory `File`, and multipart file parts, are
41
+ * streamed to disk once they outgrow the spool threshold and surfaced as lazily read
42
+ * {@link TmpFile} instances, so requests far larger than available memory parse in
43
+ * constant memory. Smaller uploads stay in memory as plain `File`s. Every other body is
44
+ * left to the standard parser.
45
+ *
46
+ * Request body sizes are limited per content category: buffered in memory, uploaded
47
+ * files, and streamed, each limit fixed or resolved per request. This subsumes the
48
+ * request limit plugin while sizing each kind of body to what it actually costs.
49
+ *
50
+ * @remarks
51
+ * Temporary files are removed when the request finishes. A streaming response body,
52
+ * an event iterator or a raw stream, keeps them alive until it completes, so
53
+ * responses that read the upload while streaming work. Any other response is
54
+ * transmitted after removal, so one that embeds the upload itself, as a `File` or
55
+ * inside `FormData`, needs the content copied or the file moved first.
56
+ *
57
+ * @see {@link https://orpc.dev/docs/plugins/tmp-file-upload | Tmp File Upload Plugin}
58
+ */
59
+ export class TmpFileUploadHandlerPlugin {
60
+ name = '~tmp-file-upload';
61
+ /**
62
+ * Should parse the original request body instead of batched sub-requests.
63
+ */
64
+ after = ['~batch'];
65
+ /**
66
+ * Should run inside the limit and compression plugins, so spooling receives
67
+ * the size-checked, decompressed bytes.
68
+ */
69
+ before = ['~request-limit', '~request-compression'];
70
+ tmpDir;
71
+ maxBodySize;
72
+ spoolThreshold;
73
+ constructor(options = {}) {
74
+ this.tmpDir = options.tmpDir ?? tmpdir();
75
+ this.maxBodySize = options.maxBodySize ?? {
76
+ memory: Number.POSITIVE_INFINITY,
77
+ file: Number.POSITIVE_INFINITY,
78
+ stream: Number.POSITIVE_INFINITY,
79
+ };
80
+ this.spoolThreshold = options.spoolThreshold ?? 64 * 1024;
81
+ }
82
+ init(options) {
83
+ const routingInterceptor = async ({ next, ...interceptorOptions }) => {
84
+ const tmpFiles = new RequestTmpFiles(this.tmpDir);
85
+ let cleanupDeferred = false;
86
+ try {
87
+ const result = await next({
88
+ ...interceptorOptions,
89
+ request: {
90
+ ...interceptorOptions.request,
91
+ resolveBody: (hint) => this.resolveBody(interceptorOptions, hint, tmpFiles),
92
+ },
93
+ });
94
+ /**
95
+ * A streaming response body transmits after this interceptor returns and
96
+ * may read the uploaded tmp files while doing so, so their removal rides
97
+ * on the body finishing instead. That covers abandoned transfers too: the
98
+ * adapter cancels the body, which reaches the same finish hook only after
99
+ * any in-flight procedure logic has completed.
100
+ */
101
+ if (result.matched && tmpFiles.inUse) {
102
+ const body = result.response.body;
103
+ if (isAsyncIteratorObject(body)) {
104
+ cleanupDeferred = true;
105
+ return {
106
+ matched: true,
107
+ response: {
108
+ ...result.response,
109
+ /**
110
+ * @warning
111
+ * Remember use `override` for AsyncIteratorObject to remain other special properties
112
+ */
113
+ body: override(body, wrapAsyncIterator(body, { onFinish: () => tmpFiles.cleanup() })),
114
+ },
115
+ };
116
+ }
117
+ if (body instanceof ReadableStream) {
118
+ cleanupDeferred = true;
119
+ return {
120
+ matched: true,
121
+ response: {
122
+ ...result.response,
123
+ /**
124
+ * @warning
125
+ * Remember use `override` for ReadableStream to remain other special properties
126
+ */
127
+ body: override(body, wrapReadableStream(body, { onFinish: () => tmpFiles.cleanup() })),
128
+ },
129
+ };
130
+ }
131
+ }
132
+ return result;
133
+ }
134
+ finally {
135
+ if (!cleanupDeferred) {
136
+ await tmpFiles.cleanup();
137
+ }
138
+ }
139
+ };
140
+ return {
141
+ ...options,
142
+ routingInterceptors: [routingInterceptor, ...toArray(options.routingInterceptors)],
143
+ };
144
+ }
145
+ async resolveBody(interceptorOptions, hint, tmpFiles) {
146
+ const { request } = interceptorOptions;
147
+ // The same resolution order the standard body parsers apply
148
+ const resolvedHint = hint ?? resolveStandardBodyHint(request.headers);
149
+ // A body-less request has nothing to limit or spool
150
+ if (resolvedHint === 'none') {
151
+ return request.resolveBody(hint);
152
+ }
153
+ const maxBodySize = await value(this.maxBodySize, interceptorOptions);
154
+ /**
155
+ * A form-data hint always means multipart here, even though it can also
156
+ * arrive explicitly or through the standard-server header on a body that
157
+ * is not. Such a body fails the multipart parse, unlike the standard
158
+ * parser, which would fall back to urlencoded form data.
159
+ */
160
+ if (resolvedHint === 'form-data') {
161
+ return this.parseMultipartBody(request, tmpFiles, maxBodySize);
162
+ }
163
+ if (resolvedHint === 'file') {
164
+ return this.parseFileBody(request, tmpFiles, maxBodySize);
165
+ }
166
+ if (resolvedHint === 'json' || resolvedHint === 'url-search-params') {
167
+ return this.parseLimitedBody(request, hint, resolvedHint, maxBodySize.memory);
168
+ }
169
+ // Streams are consumed on the fly, but the decoder buffers each event whole, however fast the stream is read
170
+ const eventLimit = resolvedHint === 'event-stream' ? maxBodySize.memory : Number.POSITIVE_INFINITY;
171
+ return this.parseLimitedBody(request, hint, resolvedHint, maxBodySize.stream, eventLimit);
172
+ }
173
+ /**
174
+ * Enforces size limits on a body the standard parser handles, counting the
175
+ * raw bytes before handing them back for regular parsing.
176
+ */
177
+ async parseLimitedBody(request, hint, resolvedHint, limit, eventLimit = Number.POSITIVE_INFINITY) {
178
+ if (limit === Number.POSITIVE_INFINITY && eventLimit === Number.POSITIVE_INFINITY) {
179
+ return request.resolveBody(hint);
180
+ }
181
+ assertContentLengthWithin(request.headers, limit);
182
+ const stream = await request.resolveBody('octet-stream');
183
+ // adapter might not support hint (e.g. peer adapter)
184
+ if (!(stream instanceof ReadableStream)) {
185
+ return stream;
186
+ }
187
+ // An event can't outgrow a limit at or above the total one
188
+ const fits = eventLimit < limit ? createEventSizeCheck(eventLimit) : undefined;
189
+ const response = new Response(limitStream(stream, limit, fits), {
190
+ headers: toFetchHeaders(request.headers),
191
+ });
192
+ return toStandardBody(response, { hint: resolvedHint });
193
+ }
194
+ async parseFileBody(request, tmpFiles, maxBodySize) {
195
+ assertContentLengthWithin(request.headers, maxBodySize.file);
196
+ const stream = await request.resolveBody('octet-stream');
197
+ // adapter might not support hint (e.g. peer adapter)
198
+ if (!(stream instanceof ReadableStream)) {
199
+ return stream;
200
+ }
201
+ const contentDisposition = flattenStandardHeader(request.headers['content-disposition']);
202
+ const fileName = contentDisposition !== undefined
203
+ ? getFilenameFromContentDisposition(contentDisposition)
204
+ : undefined;
205
+ const contentType = flattenStandardHeader(request.headers['content-type']);
206
+ const upload = new UploadWriter(tmpFiles, new Budget(maxBodySize.memory), new Budget(maxBodySize.file), this.spoolThreshold);
207
+ for await (const chunk of stream) {
208
+ await upload.write(chunk);
209
+ }
210
+ return upload.end(fileName ?? 'blob', contentType ?? '');
211
+ }
212
+ async parseMultipartBody(request, tmpFiles, maxBodySize) {
213
+ const contentType = flattenStandardHeader(request.headers['content-type']);
214
+ const boundary = contentType === undefined ? undefined : parseHeaderParameters(contentType).get('boundary');
215
+ if (boundary === undefined || boundary === '') {
216
+ throw new TypeError('Invalid multipart body: content-type header is missing the boundary parameter');
217
+ }
218
+ /**
219
+ * The whole multipart body, framing included, can never exceed what its two
220
+ * content categories allow together.
221
+ */
222
+ const totalLimit = maxBodySize.memory + maxBodySize.file;
223
+ assertContentLengthWithin(request.headers, totalLimit);
224
+ const stream = await request.resolveBody('octet-stream');
225
+ // adapter might not support hint (e.g. peer adapter)
226
+ if (!(stream instanceof ReadableStream)) {
227
+ return stream;
228
+ }
229
+ const limited = totalLimit === Number.POSITIVE_INFINITY ? stream : limitStream(stream, totalLimit);
230
+ const form = new FormData();
231
+ const memory = new Budget(maxBodySize.memory);
232
+ const file = new Budget(maxBodySize.file);
233
+ await parseMultipart(limited, boundary, (part) => {
234
+ const name = part.name;
235
+ memory.charge(part.headerSize);
236
+ if (part.filename === undefined) {
237
+ const chunks = [];
238
+ return {
239
+ write: (chunk) => {
240
+ memory.charge(chunk.length);
241
+ // The parser only guarantees the chunk until write returns, so retaining it requires a copy
242
+ chunks.push(Buffer.from(chunk));
243
+ },
244
+ end: () => {
245
+ form.append(name, Buffer.concat(chunks).toString());
246
+ },
247
+ };
248
+ }
249
+ const filename = part.filename;
250
+ // A part without a content-type defaults to text/plain, matching the standard parser
251
+ const type = part.type ?? 'text/plain';
252
+ const upload = new UploadWriter(tmpFiles, memory, file, this.spoolThreshold);
253
+ return {
254
+ write: (chunk) => upload.write(chunk),
255
+ end: async () => {
256
+ form.append(name, await upload.end(filename, type));
257
+ },
258
+ };
259
+ });
260
+ return form;
261
+ }
262
+ }
263
+ /**
264
+ * Rejects early when the declared length already exceeds the limit. The length
265
+ * can lie, so the streaming enforcement stays either way.
266
+ */
267
+ function assertContentLengthWithin(headers, limit) {
268
+ const contentLength = Number(flattenStandardHeader(headers['content-length']));
269
+ if (Number.isFinite(contentLength) && contentLength > limit) {
270
+ throw new ORPCError('PAYLOAD_TOO_LARGE');
271
+ }
272
+ }
273
+ /**
274
+ * Limits a stream's total size, also rejecting once `fits` refuses a chunk.
275
+ * `fits` sees every chunk in order, so it can keep state across them.
276
+ */
277
+ function limitStream(stream, limit, fits = () => true) {
278
+ let total = 0;
279
+ return stream.pipeThrough(new TransformStream({
280
+ transform(chunk, controller) {
281
+ total += chunk.byteLength;
282
+ if (total > limit || !fits(chunk)) {
283
+ controller.error(new ORPCError('PAYLOAD_TOO_LARGE'));
284
+ return;
285
+ }
286
+ controller.enqueue(chunk);
287
+ },
288
+ }));
289
+ }
290
+ const CR = 0x0d;
291
+ const LF = 0x0a;
292
+ /**
293
+ * Counts each event's bytes across chunks until its blank line, since the
294
+ * decoder buffers the whole event, and fails once one outgrows the limit. Scans
295
+ * raw bytes, as UTF-8 never puts CR or LF in a multi-byte character.
296
+ */
297
+ function createEventSizeCheck(eventLimit) {
298
+ let eventSize = 0;
299
+ // The event's trailing line ending: none, a lone CR, or a complete one
300
+ let trailing = 'none';
301
+ return (chunk) => {
302
+ // Buffer's native indexOf skips the content between line endings
303
+ const bytes = Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
304
+ let nextCR = indexOrEnd(bytes, CR, 0);
305
+ let nextLF = indexOrEnd(bytes, LF, 0);
306
+ let offset = 0;
307
+ while (true) {
308
+ const lineEnding = Math.min(nextCR, nextLF);
309
+ if (lineEnding > offset) {
310
+ eventSize += lineEnding - offset;
311
+ trailing = 'none';
312
+ }
313
+ if (lineEnding === bytes.length) {
314
+ return eventSize <= eventLimit;
315
+ }
316
+ const byte = bytes[lineEnding];
317
+ offset = lineEnding + 1;
318
+ if (byte === CR) {
319
+ nextCR = indexOrEnd(bytes, CR, offset);
320
+ }
321
+ else {
322
+ nextLF = indexOrEnd(bytes, LF, offset);
323
+ }
324
+ // The decoder skips line endings before an event
325
+ if (eventSize === 0) {
326
+ continue;
327
+ }
328
+ if (++eventSize > eventLimit) {
329
+ return false;
330
+ }
331
+ if (trailing === 'line' || (trailing === 'cr' && byte === CR)) {
332
+ // A blank line: the decoder releases the event
333
+ eventSize = 0;
334
+ trailing = 'none';
335
+ }
336
+ else {
337
+ trailing = byte === CR ? 'cr' : 'line';
338
+ }
339
+ }
340
+ };
341
+ }
342
+ function indexOrEnd(bytes, byte, from) {
343
+ const index = bytes.indexOf(byte, from);
344
+ return index === -1 ? bytes.length : index;
345
+ }
346
+ class Budget {
347
+ limit;
348
+ used = 0;
349
+ constructor(limit) {
350
+ this.limit = limit;
351
+ }
352
+ charge(size) {
353
+ if (!this.tryCharge(size)) {
354
+ throw new ORPCError('PAYLOAD_TOO_LARGE');
355
+ }
356
+ }
357
+ tryCharge(size) {
358
+ if (this.used + size > this.limit) {
359
+ return false;
360
+ }
361
+ this.used += size;
362
+ return true;
363
+ }
364
+ refund(size) {
365
+ this.used -= size;
366
+ }
367
+ }
368
+ class UploadWriter {
369
+ tmpFiles;
370
+ memory;
371
+ file;
372
+ spoolThreshold;
373
+ held = [];
374
+ heldSize = 0;
375
+ tmpPath;
376
+ constructor(tmpFiles, memory, file, spoolThreshold) {
377
+ this.tmpFiles = tmpFiles;
378
+ this.memory = memory;
379
+ this.file = file;
380
+ this.spoolThreshold = spoolThreshold;
381
+ }
382
+ async write(chunk) {
383
+ this.file.charge(chunk.length);
384
+ if (this.tmpPath !== undefined) {
385
+ return this.tmpFiles.append(this.tmpPath, chunk);
386
+ }
387
+ if (this.heldSize + chunk.length <= this.spoolThreshold &&
388
+ this.memory.tryCharge(chunk.length)) {
389
+ // Chunks are only guaranteed until write returns, so holding one requires a copy
390
+ this.held.push(Buffer.from(chunk));
391
+ this.heldSize += chunk.length;
392
+ return;
393
+ }
394
+ this.tmpPath = await this.tmpFiles.create(Buffer.concat([...this.held, chunk]));
395
+ this.memory.refund(this.heldSize);
396
+ this.held = [];
397
+ }
398
+ async end(name, type) {
399
+ if (this.tmpPath !== undefined) {
400
+ return this.tmpFiles.seal(this.tmpPath, name, type);
401
+ }
402
+ // A File keeps one part per chunk, so merge them first
403
+ return new File([Buffer.concat(this.held, this.heldSize)], name, { type });
404
+ }
405
+ }
406
+ /**
407
+ * Owns every temporary file a request creates: creates them inside one lazily
408
+ * created per-request directory and guarantees removal. Content lands through
409
+ * self-contained appends rather than long-lived handles, so a request holds at
410
+ * most one transient file descriptor per in-flight write no matter how many
411
+ * files it carries, and removal never contends with an open handle on platforms
412
+ * that cannot delete open files.
413
+ *
414
+ * Filesystem failures surface as `INTERNAL_SERVER_ERROR`, keeping them distinct
415
+ * from the malformed-body errors the handler reports as `BAD_REQUEST`. Their
416
+ * details ride only on `cause`, which is never serialized to the client.
417
+ */
418
+ class RequestTmpFiles {
419
+ tmpDir;
420
+ dir;
421
+ count = 0;
422
+ constructor(tmpDir) {
423
+ this.tmpDir = tmpDir;
424
+ }
425
+ get inUse() {
426
+ return this.dir !== undefined;
427
+ }
428
+ async create(content) {
429
+ try {
430
+ this.dir ??= mkdtemp(path.join(this.tmpDir, 'orpc-upload-'));
431
+ const tmpPath = path.join(await this.dir, String(this.count++));
432
+ await appendFile(tmpPath, content);
433
+ return tmpPath;
434
+ }
435
+ catch (cause) {
436
+ throw new ORPCError('INTERNAL_SERVER_ERROR', { cause });
437
+ }
438
+ }
439
+ async append(tmpPath, chunk) {
440
+ try {
441
+ await appendFile(tmpPath, chunk);
442
+ }
443
+ catch (cause) {
444
+ throw new ORPCError('INTERNAL_SERVER_ERROR', { cause });
445
+ }
446
+ }
447
+ async seal(tmpPath, name, type) {
448
+ try {
449
+ return new TmpFile(await openAsBlob(tmpPath), tmpPath, name, { type });
450
+ }
451
+ catch (cause) {
452
+ throw new ORPCError('INTERNAL_SERVER_ERROR', { cause });
453
+ }
454
+ }
455
+ async cleanup() {
456
+ if (this.dir !== undefined) {
457
+ try {
458
+ await rm(await this.dir, { recursive: true, force: true });
459
+ }
460
+ catch {
461
+ // The request outcome must not change because removal failed
462
+ }
463
+ }
464
+ }
465
+ }
package/package.json CHANGED
@@ -1,53 +1,51 @@
1
1
  {
2
2
  "name": "@orpc/node",
3
- "type": "module",
4
- "version": "2.0.0-beta.47",
3
+ "version": "2.0.0-beta.49",
5
4
  "description": "Node.js plugins for oRPC: static file serving, temporary file uploads, and batch response compression",
6
- "license": "MIT",
7
- "funding": [
8
- "https://github.com/sponsors/dinwwwh",
9
- "https://opencollective.com/middleapi"
5
+ "keywords": [
6
+ "compression",
7
+ "file-upload",
8
+ "node",
9
+ "nodejs",
10
+ "orpc",
11
+ "static-files",
12
+ "typescript"
10
13
  ],
11
14
  "homepage": "https://orpc.dev",
15
+ "license": "MIT",
12
16
  "repository": {
13
17
  "type": "git",
14
18
  "url": "git+https://github.com/middleapi/orpc.git",
15
19
  "directory": "packages/node"
16
20
  },
17
- "keywords": [
18
- "orpc",
19
- "nodejs",
20
- "node",
21
- "static-files",
22
- "file-upload",
23
- "compression",
24
- "typescript"
21
+ "funding": [
22
+ "https://github.com/sponsors/dinwwwh",
23
+ "https://opencollective.com/middleapi"
24
+ ],
25
+ "files": [
26
+ "dist"
25
27
  ],
28
+ "type": "module",
26
29
  "sideEffects": false,
27
30
  "exports": {
28
31
  "./package.json": "./package.json",
29
32
  ".": {
30
- "types": "./dist/index.d.mts",
31
- "import": "./dist/index.mjs",
32
- "default": "./dist/index.mjs"
33
+ "types": "./dist/index.d.ts",
34
+ "import": "./dist/index.js",
35
+ "default": "./dist/index.js"
33
36
  }
34
37
  },
35
- "files": [
36
- "dist"
37
- ],
38
38
  "dependencies": {
39
- "@orpc/server": "2.0.0-beta.47",
40
- "@orpc/shared": "2.0.0-beta.47",
41
- "@standard-server/core": "~0.13.0",
42
- "@standard-server/fetch": "~0.13.0",
43
- "@standard-server/node": "~0.13.0",
44
- "mime": "^4.1.1"
39
+ "@orpc/server": "2.0.0-beta.49",
40
+ "@orpc/shared": "2.0.0-beta.49",
41
+ "@standard-server/core": "~0.15.0",
42
+ "@standard-server/fetch": "~0.15.0",
43
+ "@standard-server/node": "~0.15.0",
44
+ "mime": "^4.1.2"
45
45
  },
46
46
  "devDependencies": {
47
- "@orpc/client": "2.0.0-beta.47",
47
+ "@orpc/client": "2.0.0-beta.49",
48
48
  "supertest": "^7.3.1"
49
49
  },
50
- "scripts": {
51
- "type:check": "tsc -b"
52
- }
50
+ "scripts": {}
53
51
  }