@orpc/server 2.0.0-beta.48 → 2.0.0-beta.49

package/dist/plugins/request-headers.d.ts

@@ -0,0 +1,22 @@
+import type { StandardHandlerOptions, StandardHandlerPlugin } from '../adapters/standard/index.ts';
+/**
+ * The context shape into which the Request Headers Plugin injects `reqHeaders`.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-headers | Request Headers Plugin}
+ */
+export interface RequestHeadersHandlerPluginContext {
+    /**
+     * Request headers as a Headers instance. This is injected by the Request Headers Plugin.
+     */
+    reqHeaders?: Headers | undefined;
+}
+/**
+ * The Request Headers Plugin injects a `reqHeaders` instance into the context,
+ * allowing access to request headers in oRPC.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-headers | Request Headers Plugin}
+ */
+export declare class RequestHeadersHandlerPlugin<T extends RequestHeadersHandlerPluginContext> implements StandardHandlerPlugin<T> {
+    name: string;
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}

package/dist/plugins/request-headers.js

@@ -0,0 +1,30 @@
+import { toArray } from '@orpc/shared';
+import { toFetchHeaders } from '@standard-server/fetch';
+/**
+ * The Request Headers Plugin injects a `reqHeaders` instance into the context,
+ * allowing access to request headers in oRPC.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-headers | Request Headers Plugin}
+ */
+export class RequestHeadersHandlerPlugin {
+    name = '~request-headers';
+    init(options) {
+        return {
+            ...options,
+            interceptors: [
+                (interceptorOptions) => {
+                    const reqHeaders = interceptorOptions.context.reqHeaders ??
+                        toFetchHeaders(interceptorOptions.request.headers);
+                    return interceptorOptions.next({
+                        ...interceptorOptions,
+                        context: {
+                            ...interceptorOptions.context,
+                            reqHeaders,
+                        },
+                    });
+                },
+                ...toArray(options.interceptors),
+            ],
+        };
+    }
+}

package/dist/plugins/request-limit.d.ts

@@ -0,0 +1,30 @@
+import type { StandardHandlerOptions, StandardHandlerPlugin } from '../adapters/standard/index.ts';
+import type { Context } from '../context.ts';
+export interface RequestLimitHandlerPluginOptions {
+    /**
+     * The maximum allowed request body size in bytes.
+     */
+    maxBodySize: number;
+}
+/**
+ * Rejects requests whose body exceeds `maxBodySize`.
+ *
+ * When used with the request compression plugin, the limit applies to the
+ * decompressed payload rather than the compressed wire size.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-limit | Request Limit Plugin}
+ */
+export declare class RequestLimitHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    /**
+     * Should limit the original batch request body instead of sub-requests.
+     */
+    after: string[];
+    /**
+     * Should limit the final body size instead of the compressed one.
+     */
+    before: string[];
+    private readonly maxBodySize;
+    constructor(options: RequestLimitHandlerPluginOptions);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}

package/dist/plugins/request-limit.js

@@ -0,0 +1,68 @@
+import { ORPCError } from '@orpc/client';
+import { toArray } from '@orpc/shared';
+import { flattenStandardHeader } from '@standard-server/core';
+import { toFetchHeaders, toStandardBody } from '@standard-server/fetch';
+/**
+ * Rejects requests whose body exceeds `maxBodySize`.
+ *
+ * When used with the request compression plugin, the limit applies to the
+ * decompressed payload rather than the compressed wire size.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-limit | Request Limit Plugin}
+ */
+export class RequestLimitHandlerPlugin {
+    name = '~request-limit';
+    /**
+     * Should limit the original batch request body instead of sub-requests.
+     */
+    after = ['~batch'];
+    /**
+     * Should limit the final body size instead of the compressed one.
+     */
+    before = ['~request-compression'];
+    maxBodySize;
+    constructor(options) {
+        this.maxBodySize = options.maxBodySize;
+    }
+    init(options) {
+        const maxBodySize = this.maxBodySize;
+        const routingInterceptor = async ({ next, ...interceptorOptions }) => {
+            return next({
+                ...interceptorOptions,
+                request: {
+                    ...interceptorOptions.request,
+                    async resolveBody(hint) {
+                        const contentLength = Number(flattenStandardHeader(interceptorOptions.request.headers['content-length']));
+                        if (Number.isFinite(contentLength) && contentLength > maxBodySize) {
+                            throw new ORPCError('PAYLOAD_TOO_LARGE');
+                        }
+                        const stream = await interceptorOptions.request.resolveBody('octet-stream');
+                        // adapter might not support hint (e.g. peer adapter)
+                        if (!(stream instanceof ReadableStream)) {
+                            return stream;
+                        }
+                        let currentBodySize = 0;
+                        const limitedStream = stream.pipeThrough(new TransformStream({
+                            transform(chunk, controller) {
+                                currentBodySize += chunk.byteLength;
+                                if (currentBodySize > maxBodySize) {
+                                    controller.error(new ORPCError('PAYLOAD_TOO_LARGE'));
+                                    return;
+                                }
+                                controller.enqueue(chunk);
+                            },
+                        }));
+                        const response = new Response(limitedStream, {
+                            headers: toFetchHeaders(interceptorOptions.request.headers),
+                        });
+                        return toStandardBody(response, { hint });
+                    },
+                },
+            });
+        };
+        return {
+            ...options,
+            routingInterceptors: [routingInterceptor, ...toArray(options.routingInterceptors)],
+        };
+    }
+}

package/dist/plugins/response-compression.d.ts

@@ -0,0 +1,59 @@
+import type { StandardHeaders, StandardResponse } from '@standard-server/core';
+import type { StandardHandlerOptions, StandardHandlerPlugin, StandardHandlerRoutingInterceptorOptions } from '../adapters/standard/index.ts';
+import type { Context } from '../context.ts';
+export interface ResponseCompressionHandlerPluginOptions<T extends Context> {
+    /**
+     * The compression schemes to use for response compression.
+     * Schemes are prioritized by their order in this array and
+     * only applied if the client supports them (via Accept-Encoding).
+     *
+     * @default ['gzip', 'deflate']
+     */
+    encodings?: readonly ('gzip' | 'deflate' | 'deflate-raw')[] | undefined;
+    /**
+     * The minimum response size in bytes required to trigger compression.
+     * Responses smaller than this threshold will not be compressed to avoid overhead.
+     * If the response size cannot be determined, compression will still be applied.
+     *
+     * @default 1024 (1KB)
+     */
+    threshold?: number | undefined;
+    /**
+     * Determines whether a response with the given Content-Type should be compressed.
+     * Only consulted for binary transfers (streams, files, and file form-data parts).
+     * Also receives the routing interceptor options for per-request decisions.
+     *
+     * @default isCompressibleContentType (covers common text-based formats)
+     */
+    isCompressibleContentType?: ((contentType: string | null | undefined, options: StandardHandlerRoutingInterceptorOptions<T>) => boolean) | undefined;
+}
+/**
+ * Compresses response bodies based on the client's Accept-Encoding header.
+ * Works at the standard handler level, so it supports all adapters.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-compression | Response Compression Plugin}
+ */
+export declare class ResponseCompressionHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    /**
+     * Compression should be done after batching, to compress the final response.
+     * Compression should also be done after response headers are set, to access final headers like Content-Type and Cache-Control.
+     */
+    after: string[];
+    private readonly encodings;
+    private readonly threshold;
+    private readonly isCompressibleContentType;
+    constructor(options?: ResponseCompressionHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}
+/**
+ * Picks the first of `encodings` the client accepts, or `undefined` when the response
+ * must be sent as is because it is already encoded, partial, or forbids transforms.
+ * Shared by the response compression plugins so they agree on when to compress.
+ */
+export declare function negotiateResponseCompressionEncoding<TEncoding extends string>(response: StandardResponse, requestHeaders: StandardHeaders, encodings: readonly TEncoding[]): TEncoding | undefined;
+/**
+ * The headers of a response whose body is compressed with `encoding`.
+ * Shared by the response compression plugins so compressed responses carry the same headers.
+ */
+export declare function toCompressedHeaders(headers: StandardHeaders, encoding: string): StandardHeaders;

package/dist/plugins/response-compression.js

@@ -0,0 +1,209 @@
+import { isAcceptableEncoding, isAsyncIteratorObject, isCompressibleContentType, isNoTransformCacheControl, parseAcceptEncodingQualities, toArray, varyByAcceptEncoding, } from '@orpc/shared';
+import { flattenStandardHeader, generateContentDisposition } from '@standard-server/core';
+import { toFetchBody } from '@standard-server/fetch';
+// Rough UTF-8 estimate. Mostly ASCII text stays close to 1 byte/char;
+// occasional multi-byte characters increase the average.
+const AVG_BYTES_PER_CHAR = 1.2;
+/**
+ * Compresses response bodies based on the client's Accept-Encoding header.
+ * Works at the standard handler level, so it supports all adapters.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-compression | Response Compression Plugin}
+ */
+export class ResponseCompressionHandlerPlugin {
+    name = '~response-compression';
+    /**
+     * Compression should be done after batching, to compress the final response.
+     * Compression should also be done after response headers are set, to access final headers like Content-Type and Cache-Control.
+     */
+    after = ['~batch', '~response-headers'];
+    encodings;
+    threshold;
+    isCompressibleContentType;
+    constructor(options = {}) {
+        this.encodings = options.encodings ?? ['gzip', 'deflate'];
+        this.threshold = options.threshold ?? 1024;
+        this.isCompressibleContentType = options.isCompressibleContentType ?? isCompressibleContentType;
+    }
+    init(options) {
+        const routingInterceptor = async ({ next, ...interceptorOptions }) => {
+            const result = await next();
+            if (!result.matched) {
+                return result;
+            }
+            const response = result.response;
+            const encoding = negotiateResponseCompressionEncoding(response, interceptorOptions.request.headers, this.encodings);
+            if (encoding === undefined) {
+                return result;
+            }
+            const body = response.body;
+            const headers = response.headers;
+            if (body instanceof ReadableStream) {
+                const contentLength = Number(flattenStandardHeader(headers['content-length']));
+                if ((!Number.isFinite(contentLength) || contentLength >= this.threshold) &&
+                    this.isCompressibleContentType(flattenStandardHeader(headers['content-type']), interceptorOptions)) {
+                    return {
+                        ...result,
+                        response: {
+                            ...response,
+                            body: body.pipeThrough(new CompressionStream(encoding)),
+                            headers: toCompressedHeaders(headers, encoding),
+                        },
+                    };
+                }
+            }
+            else if (body instanceof Blob) {
+                // Adapters only fall back to the blob type when no Content-Type header is set
+                const contentType = headers['content-type'] ?? body.type;
+                if ((!Number.isFinite(body.size) || body.size >= this.threshold) &&
+                    this.isCompressibleContentType(flattenStandardHeader(contentType), interceptorOptions)) {
+                    const contentDisposition = headers['content-disposition'] ??
+                        generateContentDisposition(body instanceof File ? body.name : 'blob');
+                    return {
+                        ...result,
+                        response: {
+                            ...response,
+                            body: body.stream().pipeThrough(new CompressionStream(encoding)),
+                            headers: {
+                                ...toCompressedHeaders(headers, encoding),
+                                'standard-server': headers['standard-server'] ?? 'file',
+                                'content-type': contentType,
+                                'content-disposition': contentDisposition,
+                            },
+                        },
+                    };
+                }
+            }
+            else if (body instanceof FormData) {
+                const PART_OVERHEAD = 64; // approx bytes for boundary + Content-Disposition/Content-Type headers per part
+                let contentLength = 0;
+                for (const [key, value] of body) {
+                    contentLength += PART_OVERHEAD + key.length;
+                    if (value instanceof Blob) {
+                        if (!Number.isFinite(value.size)) {
+                            // Bun-s3 can use NaN for size
+                            if (!this.isCompressibleContentType(value.type, interceptorOptions)) {
+                                // Unknown non-compressible part size makes the estimate unreliable
+                                contentLength = -Infinity;
+                                break;
+                            }
+                            // Unknown size for compressible content - still apply compression
+                            contentLength = Infinity;
+                        }
+                        else {
+                            contentLength += this.isCompressibleContentType(value.type, interceptorOptions)
+                                ? value.size
+                                : -value.size;
+                        }
+                    }
+                    else {
+                        contentLength += value.length * AVG_BYTES_PER_CHAR;
+                    }
+                }
+                if (contentLength >= this.threshold) {
+                    const res = new Response(body);
+                    const compressedStream = res.body.pipeThrough(new CompressionStream(encoding));
+                    return {
+                        ...result,
+                        response: {
+                            ...response,
+                            body: compressedStream,
+                            headers: {
+                                ...toCompressedHeaders(headers, encoding),
+                                'standard-server': [],
+                                'content-type': res.headers.get('content-type'),
+                            },
+                        },
+                    };
+                }
+            }
+            else if (body instanceof URLSearchParams) {
+                const string = body.toString();
+                if (string.length * AVG_BYTES_PER_CHAR >= this.threshold) {
+                    const [, bodyHeaders] = toFetchBody(body, headers);
+                    return {
+                        ...result,
+                        response: {
+                            ...response,
+                            body: new Blob([string]).stream().pipeThrough(new CompressionStream(encoding)),
+                            headers: {
+                                ...toCompressedHeaders(bodyHeaders, encoding),
+                                // An empty hint rather than none, so the adapter does not hint the compressed stream as `octet-stream`
+                                'standard-server': bodyHeaders['standard-server'] ?? [],
+                            },
+                        },
+                    };
+                }
+            }
+            else if (body !== undefined && !isAsyncIteratorObject(body)) {
+                const [string, bodyHeaders] = toFetchBody(body, headers);
+                if (string.length * AVG_BYTES_PER_CHAR >= this.threshold) {
+                    return {
+                        ...result,
+                        response: {
+                            ...response,
+                            body: new Blob([string]).stream().pipeThrough(new CompressionStream(encoding)),
+                            headers: {
+                                ...toCompressedHeaders(bodyHeaders, encoding),
+                                'standard-server': bodyHeaders['standard-server'] ?? [],
+                            },
+                        },
+                    };
+                }
+            }
+            return result;
+        };
+        return {
+            ...options,
+            routingInterceptors: [routingInterceptor, ...toArray(options.routingInterceptors)],
+        };
+    }
+}
+/**
+ * Picks the first of `encodings` the client accepts, or `undefined` when the response
+ * must be sent as is because it is already encoded, partial, or forbids transforms.
+ * Shared by the response compression plugins so they agree on when to compress.
+ */
+export function negotiateResponseCompressionEncoding(response, requestHeaders, encodings) {
+    if (flattenStandardHeader(response.headers['content-encoding']) !== undefined) {
+        // already compressed, do not compress again
+        return undefined;
+    }
+    /**
+     * A partial response body is a byte range of the identity representation, so compressing it
+     * would leave `Content-Range` describing offsets the client never receives.
+     */
+    if (response.status === 206 ||
+        flattenStandardHeader(response.headers['content-range']) !== undefined) {
+        return undefined;
+    }
+    // Cache-Control: no-transform forbids intermediaries (and these plugins) from transforming the body
+    if (isNoTransformCacheControl(flattenStandardHeader(response.headers['cache-control']))) {
+        return undefined;
+    }
+    const acceptEncodings = parseAcceptEncodingQualities(flattenStandardHeader(requestHeaders['accept-encoding']));
+    return encodings.find((encoding) => isAcceptableEncoding(acceptEncodings, encoding));
+}
+/**
+ * The headers of a response whose body is compressed with `encoding`.
+ * Shared by the response compression plugins so compressed responses carry the same headers.
+ */
+export function toCompressedHeaders(headers, encoding) {
+    return {
+        ...headers,
+        'content-length': [],
+        'content-encoding': encoding,
+        'vary': varyByAcceptEncoding(flattenStandardHeader(headers.vary)),
+        /**
+         * A strong tag shared with the identity bytes would let `If-Range` splice them after compressed ones.
+         * A weak tag still revalidates through `If-None-Match`, and the compressed body serves no ranges.
+         *
+         * @see https://www.rfc-editor.org/rfc/rfc9110.html#name-etag
+         */
+        'etag': weakenEtag(flattenStandardHeader(headers.etag)),
+        'accept-ranges': [],
+    };
+}
+function weakenEtag(etag) {
+    return etag === undefined || etag.startsWith('W/') ? etag : `W/${etag}`;
+}

package/dist/plugins/response-headers.d.ts

@@ -0,0 +1,30 @@
+import type { StandardHandlerOptions, StandardHandlerPlugin } from '../adapters/standard/index.ts';
+/**
+ * The context shape into which the Response Headers Plugin injects `resHeaders`.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-headers | Response Headers Plugin}
+ */
+export interface ResponseHeadersHandlerPluginContext {
+    /**
+     * Response headers as a Headers instance. This is injected by the Response Headers Plugin.
+     * When set before the response is sent, these headers will be included in the response. If not set, no additional headers will be added.
+     */
+    resHeaders?: Headers | undefined;
+}
+/**
+ * The Response Headers Plugin allows you to set response headers in oRPC.
+ * It injects a resHeaders instance into the context, enabling you to modify response headers easily.
+ *
+ * @remarks
+ * **Warning**: In a `streaming` batch, only the cookies of the first procedure to respond reach the client.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-headers | Response Headers Plugin}
+ */
+export declare class ResponseHeadersHandlerPlugin<T extends ResponseHeadersHandlerPluginContext> implements StandardHandlerPlugin<T> {
+    name: string;
+    /**
+     * Interceptors should run after batch interceptors so headers are applied to each sub-response.
+     */
+    before: string[];
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}

package/dist/plugins/response-headers.js

@@ -0,0 +1,47 @@
+import { toArray } from '@orpc/shared';
+import { mergeStandardHeaders } from '@standard-server/core';
+import { toStandardHeaders } from '@standard-server/fetch';
+/**
+ * The Response Headers Plugin allows you to set response headers in oRPC.
+ * It injects a resHeaders instance into the context, enabling you to modify response headers easily.
+ *
+ * @remarks
+ * **Warning**: In a `streaming` batch, only the cookies of the first procedure to respond reach the client.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-headers | Response Headers Plugin}
+ */
+export class ResponseHeadersHandlerPlugin {
+    name = '~response-headers';
+    /**
+     * Interceptors should run after batch interceptors so headers are applied to each sub-response.
+     */
+    before = ['~batch'];
+    init(options) {
+        return {
+            ...options,
+            routingInterceptors: [
+                async (interceptorOptions) => {
+                    const resHeaders = new Headers(interceptorOptions.context.resHeaders);
+                    const result = await interceptorOptions.next({
+                        ...interceptorOptions,
+                        context: {
+                            ...interceptorOptions.context,
+                            resHeaders,
+                        },
+                    });
+                    if (!result.response) {
+                        return result;
+                    }
+                    return {
+                        ...result,
+                        response: {
+                            ...result.response,
+                            headers: mergeStandardHeaders(result.response.headers, toStandardHeaders(resHeaders)),
+                        },
+                    };
+                },
+                ...toArray(options.routingInterceptors),
+            ],
+        };
+    }
+}

package/dist/plugins/rethrow.d.ts

@@ -0,0 +1,33 @@
+import type { ThrowableError } from '@orpc/shared';
+import type { StandardHandlerInterceptorOptions, StandardHandlerOptions, StandardHandlerPlugin } from '../adapters/standard/index.ts';
+import type { Context } from '../context.ts';
+export interface RethrowHandlerPluginOptions<T extends Context> {
+    /**
+     * Decide which errors should be rethrown.
+     *
+     * @example
+     * ```ts
+     * const rethrowPlugin = new RethrowHandlerPlugin({
+     *   filter: (error) => {
+     *     // Rethrow all non-ORPCError errors
+     *     return !(error instanceof ORPCError)
+     *   }
+     * })
+     * ```
+     */
+    filter: (error: ThrowableError, options: StandardHandlerInterceptorOptions<T>) => boolean;
+}
+/**
+ * The plugin can bypass oRPC's built-in error handling
+ * and rethrow matching errors directly to your framework's error handling mechanism
+ * (e.g., NestJS exception filters, Express error middleware).
+ *
+ * @see {@link https://orpc.dev/docs/plugins/rethrow | Rethrow Handler Plugin}
+ */
+export declare class RethrowHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    private readonly filter;
+    private readonly CONTEXT_SYMBOL;
+    constructor(options: RethrowHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}

package/dist/plugins/rethrow.js

@@ -0,0 +1,59 @@
+import { toArray } from '@orpc/shared';
+/**
+ * The plugin can bypass oRPC's built-in error handling
+ * and rethrow matching errors directly to your framework's error handling mechanism
+ * (e.g., NestJS exception filters, Express error middleware).
+ *
+ * @see {@link https://orpc.dev/docs/plugins/rethrow | Rethrow Handler Plugin}
+ */
+export class RethrowHandlerPlugin {
+    name = '~rethrow';
+    filter;
+    CONTEXT_SYMBOL = Symbol('ORPC_RETHROW_HANDLER_PLUGIN_CONTEXT');
+    constructor(options) {
+        this.filter = options.filter;
+    }
+    init(options) {
+        const routingInterceptor = async (options) => {
+            const pluginContext = {};
+            const result = await options.next({
+                ...options,
+                context: {
+                    ...options.context,
+                    [this.CONTEXT_SYMBOL]: pluginContext,
+                },
+            });
+            if (pluginContext.error) {
+                throw pluginContext.error.value;
+            }
+            return result;
+        };
+        const interceptor = async (options) => {
+            const pluginContext = options.context[this.CONTEXT_SYMBOL];
+            if (!pluginContext) {
+                throw new TypeError('[RethrowHandlerPlugin] Rethrow handler context has been corrupted or modified by another plugin or interceptor');
+            }
+            try {
+                // await is important here to catch both sync and async errors
+                return await options.next();
+            }
+            catch (error) {
+                if (this.filter(error, options)) {
+                    pluginContext.error = { value: error };
+                }
+                throw error;
+            }
+        };
+        return {
+            ...options,
+            routingInterceptors: [
+                ...toArray(options.routingInterceptors),
+                routingInterceptor, // rethrow as early as possible and keep it close to `interceptor` to avoid a corrupted or modified context
+            ],
+            interceptors: [
+                interceptor, // catch as many errors as possible
+                ...toArray(options.interceptors),
+            ],
+        };
+    }
+}

package/dist/plugins/signal-sync.d.ts

@@ -0,0 +1,13 @@
+import type { StandardHandlerOptions, StandardHandlerPlugin } from '../adapters/standard/index.ts';
+import type { Context } from '../context.ts';
+/**
+ * Keeps the request signal and a streaming output (async iterator object or readable stream) in sync:
+ * cancelling the output aborts the signal with an `AbortError`,
+ * and aborting the signal ends the output with the abort reason and cancels it.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/signal-sync | Signal Sync Plugin}
+ */
+export declare class SignalSyncHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    name: string;
+    init(options: StandardHandlerOptions<T>): StandardHandlerOptions<T>;
+}