@orpc/node 2.0.0-beta.43 → 2.0.0-beta.44

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/README.md CHANGED
@@ -17,7 +17,7 @@
17
17
  <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
18
18
  </a>
19
19
  <a href="https://deepwiki.com/middleapi/orpc">
20
- <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
20
+ <img alt="Ask DeepWiki" src="https://img.shields.io/badge/Ask-DeepWiki-blue" />
21
21
  </a>
22
22
  </div>
23
23
 
@@ -95,14 +95,6 @@ Like what we build over at [middleapi](https://github.com/middleapi)? You can he
95
95
  </tr>
96
96
  </table>
97
97
 
98
- ### Special Sponsors
99
-
100
- <table>
101
- <tr>
102
- <td align="center"><a href="http://twitter.com/rauchg?ref=middleapi&amp;utm_source=middleapi&amp;utm_medium=sponsor" target="_blank" rel="noopener sponsored" title="Guillermo Rauch"><img src="https://avatars.githubusercontent.com/u/13041?u=1ee8d111657cdd02ff6d253df00978d17ee6d722&amp;v=4" width="279" alt="Guillermo Rauch"/><br />Guillermo Rauch</a></td>
103
- </tr>
104
- </table>
105
-
106
98
  ### Premium Sponsors
107
99
 
108
100
  <table>
@@ -178,7 +170,7 @@ Like what we build over at [middleapi](https://github.com/middleapi)? You can he
178
170
  </tr>
179
171
  </table>
180
172
 
181
- With thanks to [38 past sponsors](https://orpc.dev/sponsors#past-sponsors) who helped get oRPC here.
173
+ With thanks to [39 past sponsors](https://orpc.dev/sponsors#past-sponsors) who helped get oRPC here.
182
174
 
183
175
  ## References
184
176
 
package/dist/index.d.mts CHANGED
@@ -178,16 +178,18 @@ declare class StaticFileHandlerPlugin<T extends Context> implements StandardHand
178
178
  interface TmpFileUploadHandlerPluginMaxBodySize {
179
179
  /**
180
180
  * The maximum size in bytes of request body content buffered into memory:
181
- * JSON, URL-encoded forms, and the fields and part headers of a multipart
182
- * body in total, and each event of an event stream on its own. Exceeding it
183
- * rejects with `PAYLOAD_TOO_LARGE`. Usually the lowest of the three limits,
184
- * because this content cannot stream anywhere.
181
+ * JSON, URL-encoded forms, and the fields, part headers, and in-memory files
182
+ * of a multipart body in total, and each event of an event stream on its
183
+ * own. Exceeding it rejects with `PAYLOAD_TOO_LARGE`, except for uploads,
184
+ * which spool to disk instead once they no longer fit. Usually the lowest of
185
+ * the three limits, because this content cannot stream anywhere.
185
186
  */
186
187
  memory: number;
187
188
  /**
188
- * The maximum total size in bytes of upload content a request streams into
189
- * temporary files: file bodies and the file parts of a multipart body
190
- * combined. A larger body rejects the request with `PAYLOAD_TOO_LARGE`.
189
+ * The maximum total size in bytes of uploaded file content: file bodies and
190
+ * the file parts of a multipart body combined, whether held in memory or
191
+ * spooled to temporary files. A larger body rejects the request with
192
+ * `PAYLOAD_TOO_LARGE`.
191
193
  */
192
194
  file: number;
193
195
  /**
@@ -223,6 +225,15 @@ interface TmpFileUploadHandlerPluginOptions<T extends Context> {
223
225
  * @default unlimited for every kind
224
226
  */
225
227
  maxBodySize?: Value<Promisable<TmpFileUploadHandlerPluginMaxBodySize>, [options: StandardHandlerRoutingInterceptorOptions<T>]>;
228
+ /**
229
+ * The size in bytes an uploaded file must exceed before it is spooled to a
230
+ * temporary file. Smaller files stay in memory as plain `File`s, counted
231
+ * against `maxBodySize.memory`, and spool anyway once they no longer fit.
232
+ * Set to `0` to spool every non-empty upload.
233
+ *
234
+ * @default 64 * 1024
235
+ */
236
+ spoolThreshold?: number;
226
237
  }
227
238
  /**
228
239
  * A `File` whose content lives in a temporary file on disk and is read lazily,
@@ -257,12 +268,13 @@ declare class TmpFile extends File {
257
268
  /**
258
269
  * Parses file uploads into temporary files instead of memory. Bodies the standard
259
270
  * body parser would buffer into an in-memory `File`, and multipart file parts, are
260
- * streamed to disk and surfaced as lazily read {@link TmpFile} instances, so requests
261
- * far larger than available memory parse in constant memory. Every other body is left
262
- * to the standard parser.
271
+ * streamed to disk once they outgrow the spool threshold and surfaced as lazily read
272
+ * {@link TmpFile} instances, so requests far larger than available memory parse in
273
+ * constant memory. Smaller uploads stay in memory as plain `File`s. Every other body is
274
+ * left to the standard parser.
263
275
  *
264
- * Request body sizes are limited per content category: buffered in memory, spooled
265
- * to disk, and streamed, each limit fixed or resolved per request. This subsumes the
276
+ * Request body sizes are limited per content category: buffered in memory, uploaded
277
+ * files, and streamed, each limit fixed or resolved per request. This subsumes the
266
278
  * request limit plugin while sizing each kind of body to what it actually costs.
267
279
  *
268
280
  * @remarks
@@ -287,6 +299,7 @@ declare class TmpFileUploadHandlerPlugin<T extends Context> implements StandardH
287
299
  before: string[];
288
300
  private readonly tmpDir;
289
301
  private readonly maxBodySize;
302
+ private readonly spoolThreshold;
290
303
  constructor(options?: TmpFileUploadHandlerPluginOptions<T>);
291
304
  init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
292
305
  private resolveBody;
@@ -295,7 +308,7 @@ declare class TmpFileUploadHandlerPlugin<T extends Context> implements StandardH
295
308
  * raw bytes before handing them back for regular parsing.
296
309
  */
297
310
  private parseLimitedBody;
298
- private spoolFileBody;
311
+ private parseFileBody;
299
312
  private parseMultipartBody;
300
313
  }
301
314
 
package/dist/index.d.ts CHANGED
@@ -178,16 +178,18 @@ declare class StaticFileHandlerPlugin<T extends Context> implements StandardHand
178
178
  interface TmpFileUploadHandlerPluginMaxBodySize {
179
179
  /**
180
180
  * The maximum size in bytes of request body content buffered into memory:
181
- * JSON, URL-encoded forms, and the fields and part headers of a multipart
182
- * body in total, and each event of an event stream on its own. Exceeding it
183
- * rejects with `PAYLOAD_TOO_LARGE`. Usually the lowest of the three limits,
184
- * because this content cannot stream anywhere.
181
+ * JSON, URL-encoded forms, and the fields, part headers, and in-memory files
182
+ * of a multipart body in total, and each event of an event stream on its
183
+ * own. Exceeding it rejects with `PAYLOAD_TOO_LARGE`, except for uploads,
184
+ * which spool to disk instead once they no longer fit. Usually the lowest of
185
+ * the three limits, because this content cannot stream anywhere.
185
186
  */
186
187
  memory: number;
187
188
  /**
188
- * The maximum total size in bytes of upload content a request streams into
189
- * temporary files: file bodies and the file parts of a multipart body
190
- * combined. A larger body rejects the request with `PAYLOAD_TOO_LARGE`.
189
+ * The maximum total size in bytes of uploaded file content: file bodies and
190
+ * the file parts of a multipart body combined, whether held in memory or
191
+ * spooled to temporary files. A larger body rejects the request with
192
+ * `PAYLOAD_TOO_LARGE`.
191
193
  */
192
194
  file: number;
193
195
  /**
@@ -223,6 +225,15 @@ interface TmpFileUploadHandlerPluginOptions<T extends Context> {
223
225
  * @default unlimited for every kind
224
226
  */
225
227
  maxBodySize?: Value<Promisable<TmpFileUploadHandlerPluginMaxBodySize>, [options: StandardHandlerRoutingInterceptorOptions<T>]>;
228
+ /**
229
+ * The size in bytes an uploaded file must exceed before it is spooled to a
230
+ * temporary file. Smaller files stay in memory as plain `File`s, counted
231
+ * against `maxBodySize.memory`, and spool anyway once they no longer fit.
232
+ * Set to `0` to spool every non-empty upload.
233
+ *
234
+ * @default 64 * 1024
235
+ */
236
+ spoolThreshold?: number;
226
237
  }
227
238
  /**
228
239
  * A `File` whose content lives in a temporary file on disk and is read lazily,
@@ -257,12 +268,13 @@ declare class TmpFile extends File {
257
268
  /**
258
269
  * Parses file uploads into temporary files instead of memory. Bodies the standard
259
270
  * body parser would buffer into an in-memory `File`, and multipart file parts, are
260
- * streamed to disk and surfaced as lazily read {@link TmpFile} instances, so requests
261
- * far larger than available memory parse in constant memory. Every other body is left
262
- * to the standard parser.
271
+ * streamed to disk once they outgrow the spool threshold and surfaced as lazily read
272
+ * {@link TmpFile} instances, so requests far larger than available memory parse in
273
+ * constant memory. Smaller uploads stay in memory as plain `File`s. Every other body is
274
+ * left to the standard parser.
263
275
  *
264
- * Request body sizes are limited per content category: buffered in memory, spooled
265
- * to disk, and streamed, each limit fixed or resolved per request. This subsumes the
276
+ * Request body sizes are limited per content category: buffered in memory, uploaded
277
+ * files, and streamed, each limit fixed or resolved per request. This subsumes the
266
278
  * request limit plugin while sizing each kind of body to what it actually costs.
267
279
  *
268
280
  * @remarks
@@ -287,6 +299,7 @@ declare class TmpFileUploadHandlerPlugin<T extends Context> implements StandardH
287
299
  before: string[];
288
300
  private readonly tmpDir;
289
301
  private readonly maxBodySize;
302
+ private readonly spoolThreshold;
290
303
  constructor(options?: TmpFileUploadHandlerPluginOptions<T>);
291
304
  init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
292
305
  private resolveBody;
@@ -295,7 +308,7 @@ declare class TmpFileUploadHandlerPlugin<T extends Context> implements StandardH
295
308
  * raw bytes before handing them back for regular parsing.
296
309
  */
297
310
  private parseLimitedBody;
298
- private spoolFileBody;
311
+ private parseFileBody;
299
312
  private parseMultipartBody;
300
313
  }
301
314
 
package/dist/index.mjs CHANGED
@@ -613,6 +613,7 @@ class TmpFileUploadHandlerPlugin {
613
613
  before = ["~request-limit", "~request-compression"];
614
614
  tmpDir;
615
615
  maxBodySize;
616
+ spoolThreshold;
616
617
  constructor(options = {}) {
617
618
  this.tmpDir = options.tmpDir ?? tmpdir();
618
619
  this.maxBodySize = options.maxBodySize ?? {
@@ -620,6 +621,7 @@ class TmpFileUploadHandlerPlugin {
620
621
  file: Number.POSITIVE_INFINITY,
621
622
  stream: Number.POSITIVE_INFINITY
622
623
  };
624
+ this.spoolThreshold = options.spoolThreshold ?? 64 * 1024;
623
625
  }
624
626
  init(options) {
625
627
  const routingInterceptor = async ({ next, ...interceptorOptions }) => {
@@ -687,7 +689,7 @@ class TmpFileUploadHandlerPlugin {
687
689
  return this.parseMultipartBody(request, tmpFiles, maxBodySize);
688
690
  }
689
691
  if (resolvedHint === "file") {
690
- return this.spoolFileBody(request, tmpFiles, maxBodySize.file);
692
+ return this.parseFileBody(request, tmpFiles, maxBodySize);
691
693
  }
692
694
  if (resolvedHint === "json" || resolvedHint === "url-search-params") {
693
695
  return this.parseLimitedBody(request, hint, resolvedHint, maxBodySize.memory);
@@ -714,8 +716,8 @@ class TmpFileUploadHandlerPlugin {
714
716
  });
715
717
  return toStandardBody(response, { hint: resolvedHint });
716
718
  }
717
- async spoolFileBody(request, tmpFiles, fileLimit) {
718
- assertContentLengthWithin(request.headers, fileLimit);
719
+ async parseFileBody(request, tmpFiles, maxBodySize) {
720
+ assertContentLengthWithin(request.headers, maxBodySize.file);
719
721
  const stream = await request.resolveBody("octet-stream");
720
722
  if (!(stream instanceof ReadableStream)) {
721
723
  return stream;
@@ -723,12 +725,11 @@ class TmpFileUploadHandlerPlugin {
723
725
  const contentDisposition = flattenStandardHeader(request.headers["content-disposition"]);
724
726
  const fileName = contentDisposition !== void 0 ? getFilenameFromContentDisposition(contentDisposition) : void 0;
725
727
  const contentType = flattenStandardHeader(request.headers["content-type"]);
726
- const limited = fileLimit === Number.POSITIVE_INFINITY ? stream : limitStream(stream, fileLimit);
727
- const tmpPath = await tmpFiles.allocate();
728
- for await (const chunk of limited) {
729
- await tmpFiles.append(tmpPath, chunk);
728
+ const upload = new UploadWriter(tmpFiles, new Budget(maxBodySize.memory), new Budget(maxBodySize.file), this.spoolThreshold);
729
+ for await (const chunk of stream) {
730
+ await upload.write(chunk);
730
731
  }
731
- return tmpFiles.seal(tmpPath, fileName ?? "blob", contentType ?? "");
732
+ return upload.end(fileName ?? "blob", contentType ?? "");
732
733
  }
733
734
  async parseMultipartBody(request, tmpFiles, maxBodySize) {
734
735
  const contentType = flattenStandardHeader(request.headers["content-type"]);
@@ -744,21 +745,16 @@ class TmpFileUploadHandlerPlugin {
744
745
  }
745
746
  const limited = totalLimit === Number.POSITIVE_INFINITY ? stream : limitStream(stream, totalLimit);
746
747
  const form = new FormData();
747
- const used = { memory: 0, file: 0 };
748
- const charge = (category, size) => {
749
- used[category] += size;
750
- if (used[category] > maxBodySize[category]) {
751
- throw new ORPCError("PAYLOAD_TOO_LARGE");
752
- }
753
- };
748
+ const memory = new Budget(maxBodySize.memory);
749
+ const file = new Budget(maxBodySize.file);
754
750
  await parseMultipart(limited, boundary, (part) => {
755
751
  const name = part.name;
756
- charge("memory", part.headerSize);
752
+ memory.charge(part.headerSize);
757
753
  if (part.filename === void 0) {
758
754
  const chunks = [];
759
755
  return {
760
756
  write: (chunk) => {
761
- charge("memory", chunk.length);
757
+ memory.charge(chunk.length);
762
758
  chunks.push(Buffer.from(chunk));
763
759
  },
764
760
  end: () => {
@@ -768,16 +764,11 @@ class TmpFileUploadHandlerPlugin {
768
764
  }
769
765
  const filename = part.filename;
770
766
  const type = part.type ?? "text/plain";
771
- let tmpPath;
767
+ const upload = new UploadWriter(tmpFiles, memory, file, this.spoolThreshold);
772
768
  return {
773
- write: async (chunk) => {
774
- charge("file", chunk.length);
775
- tmpPath ??= await tmpFiles.allocate();
776
- await tmpFiles.append(tmpPath, chunk);
777
- },
769
+ write: (chunk) => upload.write(chunk),
778
770
  end: async () => {
779
- tmpPath ??= await tmpFiles.allocate();
780
- form.append(name, await tmpFiles.seal(tmpPath, filename, type));
771
+ form.append(name, await upload.end(filename, type));
781
772
  }
782
773
  };
783
774
  });
@@ -848,7 +839,58 @@ function indexOrEnd(bytes, byte, from) {
848
839
  const index = bytes.indexOf(byte, from);
849
840
  return index === -1 ? bytes.length : index;
850
841
  }
851
- const EMPTY_CHUNK = new Uint8Array(0);
842
+ class Budget {
843
+ constructor(limit) {
844
+ this.limit = limit;
845
+ }
846
+ used = 0;
847
+ charge(size) {
848
+ if (!this.tryCharge(size)) {
849
+ throw new ORPCError("PAYLOAD_TOO_LARGE");
850
+ }
851
+ }
852
+ tryCharge(size) {
853
+ if (this.used + size > this.limit) {
854
+ return false;
855
+ }
856
+ this.used += size;
857
+ return true;
858
+ }
859
+ refund(size) {
860
+ this.used -= size;
861
+ }
862
+ }
863
+ class UploadWriter {
864
+ constructor(tmpFiles, memory, file, spoolThreshold) {
865
+ this.tmpFiles = tmpFiles;
866
+ this.memory = memory;
867
+ this.file = file;
868
+ this.spoolThreshold = spoolThreshold;
869
+ }
870
+ held = [];
871
+ heldSize = 0;
872
+ tmpPath;
873
+ async write(chunk) {
874
+ this.file.charge(chunk.length);
875
+ if (this.tmpPath !== void 0) {
876
+ return this.tmpFiles.append(this.tmpPath, chunk);
877
+ }
878
+ if (this.heldSize + chunk.length <= this.spoolThreshold && this.memory.tryCharge(chunk.length)) {
879
+ this.held.push(Buffer.from(chunk));
880
+ this.heldSize += chunk.length;
881
+ return;
882
+ }
883
+ this.tmpPath = await this.tmpFiles.create(Buffer.concat([...this.held, chunk]));
884
+ this.memory.refund(this.heldSize);
885
+ this.held = [];
886
+ }
887
+ async end(name, type) {
888
+ if (this.tmpPath !== void 0) {
889
+ return this.tmpFiles.seal(this.tmpPath, name, type);
890
+ }
891
+ return new File([Buffer.concat(this.held, this.heldSize)], name, { type });
892
+ }
893
+ }
852
894
  class RequestTmpFiles {
853
895
  constructor(tmpDir) {
854
896
  this.tmpDir = tmpDir;
@@ -858,10 +900,12 @@ class RequestTmpFiles {
858
900
  get inUse() {
859
901
  return this.dir !== void 0;
860
902
  }
861
- async allocate() {
903
+ async create(content) {
862
904
  try {
863
905
  this.dir ??= mkdtemp(path.join(this.tmpDir, "orpc-upload-"));
864
- return path.join(await this.dir, String(this.count++));
906
+ const tmpPath = path.join(await this.dir, String(this.count++));
907
+ await appendFile(tmpPath, content);
908
+ return tmpPath;
865
909
  } catch (cause) {
866
910
  throw new ORPCError("INTERNAL_SERVER_ERROR", { cause });
867
911
  }
@@ -875,7 +919,6 @@ class RequestTmpFiles {
875
919
  }
876
920
  async seal(tmpPath, name, type) {
877
921
  try {
878
- await appendFile(tmpPath, EMPTY_CHUNK);
879
922
  return new TmpFile(await openAsBlob(tmpPath), tmpPath, name, { type });
880
923
  } catch (cause) {
881
924
  throw new ORPCError("INTERNAL_SERVER_ERROR", { cause });
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@orpc/node",
3
3
  "type": "module",
4
- "version": "2.0.0-beta.43",
4
+ "version": "2.0.0-beta.44",
5
5
  "description": "Node.js plugins for oRPC: static file serving, temporary file uploads, and batch response compression",
6
6
  "license": "MIT",
7
7
  "funding": [
@@ -36,16 +36,16 @@
36
36
  "dist"
37
37
  ],
38
38
  "dependencies": {
39
- "@orpc/server": "2.0.0-beta.43",
40
- "@orpc/shared": "2.0.0-beta.43",
41
- "@standard-server/core": "~0.10.2",
42
- "@standard-server/fetch": "~0.10.2",
43
- "@standard-server/node": "~0.10.2",
44
- "mime": "^4.1.0"
39
+ "@orpc/server": "2.0.0-beta.44",
40
+ "@orpc/shared": "2.0.0-beta.44",
41
+ "@standard-server/core": "~0.10.3",
42
+ "@standard-server/fetch": "~0.10.3",
43
+ "@standard-server/node": "~0.10.3",
44
+ "mime": "^4.1.1"
45
45
  },
46
46
  "devDependencies": {
47
- "@orpc/client": "2.0.0-beta.43",
48
- "supertest": "^7.2.2"
47
+ "@orpc/client": "2.0.0-beta.44",
48
+ "supertest": "^7.3.1"
49
49
  },
50
50
  "scripts": {
51
51
  "type:check": "tsc -b"