@orpc/node 2.0.0-beta.46 → 2.0.0-beta.48

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,354 @@
1
+ import { createReadStream } from "node:fs";
2
+ import { realpath, stat } from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { getTracer, isAcceptableEncoding, isCompressibleContentType, matchesHttpPathPrefix, mergeHttpPath, parseAcceptEncodingQualities, safeDecodeURIComponent, safeEncodeURIComponent, toArray } from "@orpc/shared";
5
+ import { flattenStandardHeader, parseStandardUrl } from "@standard-server/core";
6
+ import { toWebReadableStream } from "@standard-server/node";
7
+ import mime from "mime";
8
+
9
+ const TEXT_CONTENT_TYPE_REGEX = /^text\//;
10
+
11
+ const SHORT_NAME_ALIAS_REGEX = /^[^.]{0,6}~\d/;
12
+ const PRECOMPRESSED_ENCODINGS = [
13
+ ["br", ".br"],
14
+ ["zstd", ".zst"],
15
+ ["gzip", ".gz"]
16
+ ];
17
+
18
+ export class StaticFileHandlerPlugin {
19
+ name = "~static-file";
20
+
21
+ after = ["~tracing"];
22
+
23
+ before = ["~head-method"];
24
+ rootDir;
25
+
26
+ rootDirPrefix;
27
+
28
+ rootDirRealPaths;
29
+ path;
30
+ indexFile;
31
+ fallbackFile;
32
+ cacheControl;
33
+ dotfiles;
34
+ precompressed;
35
+ allowSymlinks;
36
+ mimeTypes;
37
+ constructor(options) {
38
+ this.rootDir = path.resolve(options.rootDir);
39
+ this.rootDirPrefix = this.rootDir.endsWith(path.sep) ? this.rootDir : this.rootDir + path.sep;
40
+ this.rootDirRealPaths = realpath(this.rootDir).catch(() => this.rootDir).then((rootDirReal) => [rootDirReal, rootDirReal.endsWith(path.sep) ? rootDirReal : rootDirReal + path.sep]);
41
+ this.path = stripTrailingSlash(options.path ?? "/");
42
+ this.indexFile = options.indexFile ?? "index.html";
43
+ this.fallbackFile = options.fallbackFile;
44
+ this.cacheControl = options.cacheControl ?? "public, max-age=0";
45
+ this.dotfiles = options.dotfiles ?? false;
46
+ this.precompressed = options.precompressed ?? false;
47
+ this.allowSymlinks = options.allowSymlinks ?? false;
48
+
49
+ this.mimeTypes = Object.assign(Object.create(null), options.mimeTypes);
50
+ }
51
+ init(options) {
52
+ const routingInterceptor = async ({ next, request, prefix }) => {
53
+ const result = await next();
54
+ if (result.matched || request.method !== "GET" && request.method !== "HEAD") {
55
+ return result;
56
+ }
57
+ const base = this.resolveBasePath(prefix);
58
+ const response = await this.serve(request, base);
59
+ if (response === undefined) {
60
+ return result;
61
+ }
62
+
63
+ getTracer()?.getActiveSpan()?.updateName(`${request.method} ${base === "/" ? "" : base}/* (static file)`);
64
+ return {
65
+ matched: true,
66
+ response
67
+ };
68
+ };
69
+ return {
70
+ ...options,
71
+
72
+ routingInterceptors: [...toArray(options.routingInterceptors), routingInterceptor]
73
+ };
74
+ }
75
+
76
+ resolveWithinRoot(segments) {
77
+ const resolved = path.join(this.rootDir, ...segments);
78
+ if (resolved !== this.rootDir && !resolved.startsWith(this.rootDirPrefix)) {
79
+ return undefined;
80
+ }
81
+ return resolved;
82
+ }
83
+
84
+ async resolveContainedRealPath(filePath) {
85
+ if (this.allowSymlinks) {
86
+ return filePath;
87
+ }
88
+ const [rootDirReal, rootDirRealPrefix] = await this.rootDirRealPaths;
89
+
90
+ const realPath = await realpath(filePath).catch(() => "");
91
+ return realPath === rootDirReal || realPath.startsWith(rootDirRealPrefix) ? realPath : undefined;
92
+ }
93
+ resolveContentType(filePath) {
94
+ const extension = path.extname(filePath).slice(1).toLowerCase();
95
+ const configured = this.mimeTypes[extension];
96
+ if (configured !== undefined) {
97
+ return configured;
98
+ }
99
+ const contentType = mime.getType(extension);
100
+ if (contentType === null) {
101
+ return "application/octet-stream";
102
+ }
103
+ return TEXT_CONTENT_TYPE_REGEX.test(contentType) ? `${contentType}; charset=utf-8` : contentType;
104
+ }
105
+ resolveBasePath(prefix) {
106
+ return prefix === undefined ? this.path : stripTrailingSlash(mergeHttpPath(prefix, this.path));
107
+ }
108
+
109
+ async lookup(segments) {
110
+ const filePath = this.resolveWithinRoot(segments);
111
+ if (filePath === undefined) {
112
+ return undefined;
113
+ }
114
+
115
+ const [stats, containedRealPath] = await Promise.all([stat(filePath).catch(() => undefined), this.resolveContainedRealPath(filePath)]);
116
+ if (stats === undefined || containedRealPath === undefined) {
117
+ return undefined;
118
+ }
119
+ return [filePath, stats];
120
+ }
121
+
122
+ resolveSegments(pathname, base) {
123
+ const segments = [];
124
+ for (const rawSegment of pathname.slice(base.length).split("/")) {
125
+ const segment = safeDecodeURIComponent(rawSegment);
126
+ if (segment === "" || segment === ".") {
127
+ continue;
128
+ }
129
+
130
+ if (segment === "..") {
131
+ if (segments.length === 0) {
132
+ return undefined;
133
+ }
134
+ segments.pop();
135
+ continue;
136
+ }
137
+ if (segment.includes("\0") || segment.includes("/") || segment.includes("\\")) {
138
+ return undefined;
139
+ }
140
+ if (!this.dotfiles && (segment.startsWith(".") || SHORT_NAME_ALIAS_REGEX.test(segment))) {
141
+ return undefined;
142
+ }
143
+ segments.push(segment);
144
+ }
145
+ return segments;
146
+ }
147
+ async serve(request, base) {
148
+ const [pathname, search] = parseStandardUrl(request.url);
149
+ if (base !== "/" && !matchesHttpPathPrefix(pathname, base)) {
150
+ return undefined;
151
+ }
152
+ const segments = this.resolveSegments(pathname, base);
153
+ if (segments === undefined) {
154
+ return undefined;
155
+ }
156
+ let found;
157
+ if (pathname.endsWith("/")) {
158
+
159
+ found = this.indexFile === false ? undefined : await this.lookup([...segments, this.indexFile]);
160
+ } else {
161
+ found = await this.lookup(segments);
162
+ if (found?.[1].isDirectory()) {
163
+ if (this.indexFile === false) {
164
+ found = undefined;
165
+ } else {
166
+
167
+ const location = `${base === "/" ? "" : base}${segments.map((segment) => `/${safeEncodeURIComponent(segment)}`).join("")}/`;
168
+ return {
169
+ status: 301,
170
+ headers: {
171
+ location: `${location}${search ?? ""}`,
172
+ ...this.cacheControl === false ? {} : { "cache-control": this.cacheControl }
173
+ }
174
+ };
175
+ }
176
+ }
177
+ }
178
+ if (found === undefined || !found[1].isFile()) {
179
+ if (this.fallbackFile === undefined) {
180
+ return undefined;
181
+ }
182
+ found = await this.lookup([this.fallbackFile]);
183
+ if (found === undefined || !found[1].isFile()) {
184
+ return undefined;
185
+ }
186
+ }
187
+ let [filePath, stats] = found;
188
+ const contentType = this.resolveContentType(filePath);
189
+ const negotiatesEncoding = this.precompressed && isCompressibleContentType(contentType);
190
+ let contentEncoding;
191
+ if (negotiatesEncoding) {
192
+ const qualities = parseAcceptEncodingQualities(flattenStandardHeader(request.headers["accept-encoding"]));
193
+ const variants = await Promise.all(PRECOMPRESSED_ENCODINGS.filter(([encoding]) => isAcceptableEncoding(qualities, encoding)).map(async ([encoding, extension]) => {
194
+ const candidatePath = filePath + extension;
195
+
196
+ const [candidateStats, containedRealPath] = await Promise.all([stat(candidatePath).catch(() => undefined), this.resolveContainedRealPath(candidatePath)]);
197
+ return candidateStats?.isFile() && containedRealPath !== undefined ? {
198
+ encoding,
199
+ extension,
200
+ stats: candidateStats
201
+ } : undefined;
202
+ }));
203
+ const variant = variants.find((variant) => variant !== undefined);
204
+ if (variant !== undefined) {
205
+ filePath += variant.extension;
206
+ stats = variant.stats;
207
+ contentEncoding = variant.encoding;
208
+ }
209
+ }
210
+ const size = stats.size;
211
+
212
+ const etag = `"${size.toString(16)}-${stats.mtime.getTime().toString(16)}"`;
213
+
214
+ const lastModifiedTime = Math.floor(stats.mtime.getTime() / 1e3) * 1e3;
215
+ const headers = {
216
+ "etag": etag,
217
+ "last-modified": stats.mtime.toUTCString(),
218
+ "accept-ranges": "bytes"
219
+ };
220
+ if (negotiatesEncoding) {
221
+
222
+ headers.vary = "accept-encoding";
223
+ }
224
+ if (this.cacheControl !== false) {
225
+ headers["cache-control"] = this.cacheControl;
226
+ }
227
+ if (isPreconditionFailed(request.headers, etag, lastModifiedTime)) {
228
+ return {
229
+ status: 412,
230
+ headers
231
+ };
232
+ }
233
+ if (isRequestFresh(request.headers, etag, lastModifiedTime)) {
234
+ return {
235
+ status: 304,
236
+ headers
237
+ };
238
+ }
239
+ let status = 200;
240
+ let start = 0;
241
+ let end = size - 1;
242
+ const range = request.method === "GET" ? flattenStandardHeader(request.headers.range) : undefined;
243
+ if (range !== undefined && isRangeApplicable(request.headers, etag, lastModifiedTime)) {
244
+ const parsed = parseByteRange(range, size);
245
+ if (parsed === "unsatisfiable") {
246
+ return {
247
+ status: 416,
248
+ headers: {
249
+ ...headers,
250
+ "content-range": `bytes */${size}`
251
+ }
252
+ };
253
+ }
254
+ if (parsed !== undefined) {
255
+ status = 206;
256
+ [start, end] = parsed;
257
+ headers["content-range"] = `bytes ${start}-${end}/${size}`;
258
+ }
259
+ }
260
+
261
+ if (contentEncoding !== undefined) {
262
+ headers["content-encoding"] = contentEncoding;
263
+ }
264
+ headers["content-type"] = contentType;
265
+ headers["content-length"] = `${end - start + 1}`;
266
+
267
+ const body = request.method === "HEAD" ? new ReadableStream({ start: (controller) => controller.close() }) : toWebReadableStream(status === 206 ? createReadStream(filePath, {
268
+ start,
269
+ end
270
+ }) : createReadStream(filePath));
271
+ return {
272
+ status,
273
+ headers,
274
+ body
275
+ };
276
+ }
277
+ }
278
+ function stripTrailingSlash(path) {
279
+ return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
280
+ }
281
+ function stripWeakEtagPrefix(etag) {
282
+ return etag.startsWith("W/") ? etag.slice(2) : etag;
283
+ }
284
+
285
+ function isPreconditionFailed(requestHeaders, etag, lastModifiedTime) {
286
+ const ifMatch = flattenStandardHeader(requestHeaders["if-match"])?.trim();
287
+
288
+ if (ifMatch !== undefined && ifMatch !== "") {
289
+ if (ifMatch === "*") {
290
+ return false;
291
+ }
292
+
293
+ return !ifMatch.split(",").some((tag) => tag.trim() === etag);
294
+ }
295
+ const ifUnmodifiedSince = flattenStandardHeader(requestHeaders["if-unmodified-since"]);
296
+ if (ifUnmodifiedSince !== undefined) {
297
+ const sinceTime = Date.parse(ifUnmodifiedSince);
298
+ return !Number.isNaN(sinceTime) && lastModifiedTime > sinceTime;
299
+ }
300
+ return false;
301
+ }
302
+
303
+ function isRequestFresh(requestHeaders, etag, lastModifiedTime) {
304
+ const ifNoneMatch = flattenStandardHeader(requestHeaders["if-none-match"]);
305
+ if (ifNoneMatch !== undefined) {
306
+ if (ifNoneMatch.trim() === "*") {
307
+ return true;
308
+ }
309
+ const bareEtag = stripWeakEtagPrefix(etag);
310
+ return ifNoneMatch.split(",").some((tag) => stripWeakEtagPrefix(tag.trim()) === bareEtag);
311
+ }
312
+ const ifModifiedSince = flattenStandardHeader(requestHeaders["if-modified-since"]);
313
+ if (ifModifiedSince !== undefined) {
314
+ const sinceTime = Date.parse(ifModifiedSince);
315
+ return !Number.isNaN(sinceTime) && lastModifiedTime <= sinceTime;
316
+ }
317
+ return false;
318
+ }
319
+ function isRangeApplicable(requestHeaders, etag, lastModifiedTime) {
320
+ const ifRange = flattenStandardHeader(requestHeaders["if-range"]);
321
+ if (ifRange === undefined) {
322
+ return true;
323
+ }
324
+
325
+ if (ifRange.startsWith("\"") || ifRange.startsWith("W/")) {
326
+ return ifRange === etag;
327
+ }
328
+ return Date.parse(ifRange) === lastModifiedTime;
329
+ }
330
+ function parseByteRange(range, size) {
331
+
332
+ const match = range.match(/^bytes=\s*(\d*)-(\d*)$/i);
333
+
334
+ if (match === null || match[1] === "" && match[2] === "") {
335
+ return undefined;
336
+ }
337
+ if (match[1] === "") {
338
+ const suffixLength = Number(match[2]);
339
+ if (suffixLength === 0 || size === 0) {
340
+ return "unsatisfiable";
341
+ }
342
+ return [Math.max(0, size - suffixLength), size - 1];
343
+ }
344
+ const start = Number(match[1]);
345
+ if (start >= size) {
346
+ return "unsatisfiable";
347
+ }
348
+ const end = match[2] === "" ? size - 1 : Math.min(Number(match[2]), size - 1);
349
+
350
+ if (end < start) {
351
+ return undefined;
352
+ }
353
+ return [start, end];
354
+ }
@@ -0,0 +1,133 @@
1
+ import type { Context } from "@orpc/server";
2
+ import type { StandardHandlerOptions, StandardHandlerPlugin, StandardHandlerRoutingInterceptorOptions } from "@orpc/server/standard";
3
+ import type { Promisable, Value } from "@orpc/shared";
4
+ import type { FilePropertyBag } from "node:buffer";
5
+ export interface TmpFileUploadHandlerPluginMaxBodySize {
6
+ /**
7
+ * The maximum size in bytes of request body content buffered into memory:
8
+ * JSON, URL-encoded forms, and the fields, part headers, and in-memory files
9
+ * of a multipart body in total, and each event of an event stream on its
10
+ * own. Exceeding it rejects with `PAYLOAD_TOO_LARGE`, except for uploads,
11
+ * which spool to disk instead once they no longer fit. Usually the lowest of
12
+ * the three limits, because this content cannot stream anywhere.
13
+ */
14
+ memory: number;
15
+ /**
16
+ * The maximum total size in bytes of uploaded file content: file bodies and
17
+ * the file parts of a multipart body combined, whether held in memory or
18
+ * spooled to temporary files. A larger body rejects the request with
19
+ * `PAYLOAD_TOO_LARGE`.
20
+ */
21
+ file: number;
22
+ /**
23
+ * The maximum total size in bytes of a request body that is consumed as a
24
+ * stream: event streams and raw binary streams. Enforced while the stream is
25
+ * consumed, so an oversized stream fails at the reader. Usually the highest
26
+ * of the three limits, but keep it finite so no client can stream
27
+ * indefinitely.
28
+ */
29
+ stream: number;
30
+ }
31
+ export interface TmpFileUploadHandlerPluginOptions<T extends Context> {
32
+ /**
33
+ * The directory temporary files are created under. Each request that spools
34
+ * an upload gets its own subdirectory inside it, removed when the request
35
+ * finishes.
36
+ *
37
+ * @default os.tmpdir()
38
+ */
39
+ tmpDir?: string | undefined;
40
+ /**
41
+ * The size limit for each kind of request body, either fixed or resolved
42
+ * per request, so limits can follow the request itself, such as a larger
43
+ * allowance for an authenticated user than for a guest. Every kind is
44
+ * required when the option is given, so none is left unbounded by accident;
45
+ * set a kind to `Number.POSITIVE_INFINITY` to deliberately leave it
46
+ * unlimited.
47
+ *
48
+ * A resolver runs only when a body is parsed, so a request without one never
49
+ * pays for it, and it receives the request as it arrived, before this plugin
50
+ * wraps its body resolution.
51
+ *
52
+ * @default unlimited for every kind
53
+ */
54
+ maxBodySize?: Value<Promisable<TmpFileUploadHandlerPluginMaxBodySize>, [options: StandardHandlerRoutingInterceptorOptions<T>]> | undefined;
55
+ /**
56
+ * The size in bytes an uploaded file must exceed before it is spooled to a
57
+ * temporary file. Smaller files stay in memory as plain `File`s, counted
58
+ * against `maxBodySize.memory`, and spool anyway once they no longer fit.
59
+ * Set to `0` to spool every non-empty upload.
60
+ *
61
+ * @default 64 * 1024
62
+ */
63
+ spoolThreshold?: number | undefined;
64
+ }
65
+ /**
66
+ * A `File` whose content lives in a temporary file on disk and is read lazily,
67
+ * so it can represent an upload far larger than available memory.
68
+ *
69
+ * @remarks
70
+ * Node's `fs.openAsBlob`, which backs this class, has known bugs with files
71
+ * over 2 GiB ({@link https://github.com/nodejs/node/issues/52585}): `size` is
72
+ * truncated above 4 GiB and `slice()` is unreliable above 2 GiB, while
73
+ * whole-file reads like `stream()` stay correct. When size or random access
74
+ * matters for such a file, stat or read {@link path} directly.
75
+ *
76
+ * @see {@link https://orpc.dev/docs/plugins/tmp-file-upload | Tmp File Upload Plugin}
77
+ */
78
+ export declare class TmpFile extends File {
79
+ /**
80
+ * Absolute path of the temporary file holding this file's content.
81
+ * The file is removed when the request finishes, so move or copy it
82
+ * to keep the content. The `File` reads from this path, so it must
83
+ * not be read after the file is moved or removed.
84
+ */
85
+ readonly path: string;
86
+ constructor(blob: Blob, path: string, name: string, options?: FilePropertyBag);
87
+ }
88
+ /**
89
+ * Parses file uploads into temporary files instead of memory. Bodies the standard
90
+ * body parser would buffer into an in-memory `File`, and multipart file parts, are
91
+ * streamed to disk once they outgrow the spool threshold and surfaced as lazily read
92
+ * {@link TmpFile} instances, so requests far larger than available memory parse in
93
+ * constant memory. Smaller uploads stay in memory as plain `File`s. Every other body is
94
+ * left to the standard parser.
95
+ *
96
+ * Request body sizes are limited per content category: buffered in memory, uploaded
97
+ * files, and streamed, each limit fixed or resolved per request. This subsumes the
98
+ * request limit plugin while sizing each kind of body to what it actually costs.
99
+ *
100
+ * @remarks
101
+ * Temporary files are removed when the request finishes. A streaming response body,
102
+ * an event iterator or a raw stream, keeps them alive until it completes, so
103
+ * responses that read the upload while streaming work. Any other response is
104
+ * transmitted after removal, so one that embeds the upload itself, as a `File` or
105
+ * inside `FormData`, needs the content copied or the file moved first.
106
+ *
107
+ * @see {@link https://orpc.dev/docs/plugins/tmp-file-upload | Tmp File Upload Plugin}
108
+ */
109
+ export declare class TmpFileUploadHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
110
+ name: string;
111
+ /**
112
+ * Should parse the original request body instead of batched sub-requests.
113
+ */
114
+ after: string[];
115
+ /**
116
+ * Should run inside the limit and compression plugins, so spooling receives
117
+ * the size-checked, decompressed bytes.
118
+ */
119
+ before: string[];
120
+ private readonly tmpDir;
121
+ private readonly maxBodySize;
122
+ private readonly spoolThreshold;
123
+ constructor(options?: TmpFileUploadHandlerPluginOptions<T>);
124
+ init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
125
+ private resolveBody;
126
+ /**
127
+ * Enforces size limits on a body the standard parser handles, counting the
128
+ * raw bytes before handing them back for regular parsing.
129
+ */
130
+ private parseLimitedBody;
131
+ private parseFileBody;
132
+ private parseMultipartBody;
133
+ }