@rapidrest/service-core 2.1.1 → 2.2.0

package/dist/types/http/types.d.ts

@@ -1,4 +1,5 @@
 import { JWTUser } from "@rapidrest/core";
+import type { Readable } from "stream";
 /**
  * Framework-agnostic HTTP request interface. Mirrors the Express `Request` surface used throughout
  * this codebase so that route handlers, middleware, and utilities require no changes when the
@@ -13,6 +14,25 @@ export interface HttpRequest {
     query: Record<string, string | string[]>;
     body: any;
     rawBody?: Buffer;
+    /**
+     * The raw request body as a Node `Readable` stream, populated instead of `body`/`rawBody` for a
+     * route registered with `{ streamingBody: true }` (see `HttpRouteOptions`) — e.g. via the
+     * `@StreamingBody()` decorator. `undefined` for every ordinary route, where `body`/`rawBody` are
+     * populated as before.
+     *
+     * The stream yields `Buffer` chunks and supports `for await (const chunk of req.bodyStream)` as
+     * well as `.pipe()`. Backpressure is enforced end-to-end by both adapters — a slow consumer
+     * throttles how fast bytes are read off the underlying connection rather than buffering
+     * unbounded data in memory — which is the entire point of opting into streaming (e.g. a
+     * multi-GB file upload). The stream is destroyed (with an error) if the client disconnects
+     * mid-upload; a handler consuming it via `for await` sees that as a thrown error and should
+     * clean up (e.g. delete a partially-written temp file) in a `catch`/`finally`.
+     *
+     * A streaming route does NOT get the framework's default `maxBodySize` enforcement — that check
+     * only runs as part of the ordinary buffering path. The handler is responsible for enforcing
+     * whatever size limit makes sense for the route itself.
+     */
+    bodyStream?: Readable;
     cookies: Record<string, string>;
     signedCookies: Record<string, string>;
     /**
@@ -83,6 +103,25 @@ export type NextFunction = (err?: any) => void;
 export type RequestHandler = (req: HttpRequest, res: HttpResponse, next: NextFunction) => void | Promise<void>;
 /** Standard 4-param error-handling middleware function. */
 export type ErrorHandler = (err: any, req: HttpRequest, res: HttpResponse, next: NextFunction) => void | Promise<void>;
+/**
+ * Per-route registration options, optionally passed as the first element of a route's handler list
+ * (e.g. `app.post(path, { streamingBody: true }, ...handlers)`). Detected at runtime by both router
+ * implementations: a non-function first argument is treated as `HttpRouteOptions` rather than a
+ * `RequestHandler`, so omitting it entirely (the overwhelmingly common case) is unaffected — every
+ * existing call site that only ever passes handler functions keeps its exact current behavior.
+ */
+export interface HttpRouteOptions {
+    /**
+     * When `true`, the router does not buffer this route's request body into `req.body`/`req.rawBody`
+     * before running its middleware/handler chain. Instead the raw body is exposed as a stream on
+     * `req.bodyStream` (see its doc comment on `HttpRequest`), and the route's own handler is
+     * responsible for consuming it and enforcing any size limit it needs — the framework's
+     * `maxBodySize` 413 rejection does not apply to a streaming route. Set by the `@StreamingBody()`
+     * route decorator; see `RouteUtils.registerRoute()`.
+     */
+    streamingBody?: boolean;
+    [key: string]: any;
+}
 /**
  * Public surface shared by every HTTP router implementation (uWS-backed, Bun-backed, ...).
  * `Server.ts` depends only on this interface, never on a concrete router class, so the
@@ -90,13 +129,13 @@ export type ErrorHandler = (err: any, req: HttpRequest, res: HttpResponse, next:
  */
 export interface IHttpRouter {
     use(...handlers: RequestHandler[]): this;
-    get(path: string, ...handlers: RequestHandler[]): this;
-    post(path: string, ...handlers: RequestHandler[]): this;
-    put(path: string, ...handlers: RequestHandler[]): this;
-    delete(path: string, ...handlers: RequestHandler[]): this;
-    patch(path: string, ...handlers: RequestHandler[]): this;
-    head(path: string, ...handlers: RequestHandler[]): this;
-    options(path: string, ...handlers: RequestHandler[]): this;
+    get(path: string, ...handlers: Array<RequestHandler | HttpRouteOptions>): this;
+    post(path: string, ...handlers: Array<RequestHandler | HttpRouteOptions>): this;
+    put(path: string, ...handlers: Array<RequestHandler | HttpRouteOptions>): this;
+    delete(path: string, ...handlers: Array<RequestHandler | HttpRouteOptions>): this;
+    patch(path: string, ...handlers: Array<RequestHandler | HttpRouteOptions>): this;
+    head(path: string, ...handlers: Array<RequestHandler | HttpRouteOptions>): this;
+    options(path: string, ...handlers: Array<RequestHandler | HttpRouteOptions>): this;
     /** `true` if the application has registered its own literal `OPTIONS` route at `path` (as
      * opposed to the framework's own internal `/*` CORS-preflight fallback registered in `listen()`).
      * Consulted by `Server.ts`'s global CORS middleware so a real app-defined `OPTIONS` handler gets a

package/dist/types/http/uWS/Adapters.d.ts

@@ -1,5 +1,6 @@
 import type { HttpRequest, HttpResponse } from "../types.js";
 import type { HttpRequest as UWSHttpRequest, HttpResponse as UWSHttpResponse } from "uWebSockets.js";
+import { Readable } from "stream";
 /** Parses a `cookie` header string into a key/value map. */
 export declare function parseCookies(cookieHeader: string): Record<string, string>;
 /**
@@ -136,3 +137,50 @@ export declare const DEFAULT_MAX_BODY_SIZE: number;
 export declare function readBody(uwsRes: UWSHttpResponse, req: UWSRequest, maxBodySize?: number, res?: {
     onAbort: (callback: () => void) => void;
 }): Promise<boolean>;
+/**
+ * Internal buffer size (in bytes) at which `makeBodyStream()`'s stream applies backpressure — i.e.
+ * pauses pulling more bytes off the uWS connection until its consumer catches up. Chosen much larger
+ * than a Node `Readable`'s 16 KiB default: a streaming route exists specifically to move large
+ * payloads (e.g. a multi-GB mailbox import) efficiently, and throttling every 16 KiB would make
+ * pause()/resume() churn dominate. 1 MiB bounds worst-case extra memory per in-flight streaming
+ * request to a small, predictable amount while still giving a slow consumer (e.g. writing to disk)
+ * plenty of headroom before the network is throttled.
+ */
+export declare const STREAMING_BODY_HIGH_WATER_MARK: number;
+/**
+ * Exposes a uWS request body as a Node `Readable` stream instead of buffering it into memory, for a
+ * route registered with `{ streamingBody: true }` (see `HttpRouteOptions`). Does NOT populate
+ * `req.body`/`req.rawBody` and does NOT enforce any `maxBodySize` limit — this is the entire point:
+ * unlike `readBody()`, the caller has opted out of buffering specifically so an arbitrarily large
+ * body (e.g. a 20 GB PST/mbox import) never needs to fit in memory at once. Enforcing a size limit,
+ * if wanted, is the route handler's own responsibility while consuming the stream.
+ *
+ * Backpressure is real, not simulated: a chunk that overflows the stream's internal buffer
+ * (`push()` returning `false`) calls `uwsRes.pause()` (uWS suspends delivering more `onData`
+ * chunks), and the returned `Readable`'s `_read()` calls `uwsRes.resume()` — but ONLY when this
+ * function itself previously paused it. uWS's `pause()`/`resume()` are not simple idempotent
+ * throttle toggles: empirically, calling `resume()` when the connection was never paused (e.g. from
+ * `_read()`'s very first call, before any backpressure has ever been applied) stops any further
+ * `onData` delivery for the rest of the request, hanging it forever. A local `paused` flag makes
+ * `resume()` a no-op unless a matching `pause()` was actually issued, matching the exact
+ * pause/resume pairing uWS expects. A slow consumer (a route piping to a slow disk, or one simply
+ * not reading yet) still throttles how fast bytes are pulled off the client connection rather than
+ * piling up unbounded data in process memory — the failure mode this whole feature exists to avoid.
+ *
+ * The stream is destroyed with an error if the client disconnects mid-upload (wired through the
+ * existing single `onAborted` fan-out via `res.onAbort()`, matching `readBody()`'s own abort
+ * handling) so a handler awaiting `for await (const chunk of req.bodyStream)` sees a thrown error
+ * instead of hanging forever, and can clean up (e.g. delete a partial temp file) in its own
+ * `catch`/`finally`.
+ *
+ * Must be called synchronously, before any `await`, in the same tick as request handling begins —
+ * uWS requires `onData`/`onAborted` to be registered before any asynchronous operation, matching the
+ * exact constraint `readBody()` above is already subject to.
+ *
+ * @param uwsRes The uWS HttpResponse to read the body from.
+ * @param res Used only to register the abort callback through the framework's existing single
+ * `onAborted` slot (see `UWSResponse.onAbort()`) — never written to otherwise.
+ */
+export declare function makeBodyStream(uwsRes: UWSHttpResponse, res: {
+    onAbort: (callback: () => void) => void;
+}): Readable;

package/dist/types/http/uWS/Router.d.ts

@@ -1,5 +1,5 @@
 import uWS from "uWebSockets.js";
-import { type IHttpRouter, type RequestHandler, type WebSocketOptions } from "../types.js";
+import { type HttpRouteOptions, type IHttpRouter, type RequestHandler, type WebSocketOptions } from "../types.js";
 import { type WsUpgradeAuth } from "../MiddlewareChain.js";
 export { runChain, extractParamNames } from "../MiddlewareChain.js";
 export type { WsUpgradeAuth, WsUpgradeAuthResult } from "../MiddlewareChain.js";
@@ -55,13 +55,13 @@ export declare class HttpRouter implements IHttpRouter {
     private capturePreRouteCount;
     /** Builds the uWS handler for a route registered at `routePattern` (`undefined` for the router's own fallbacks). */
     private makeHandler;
-    get(routePath: string, ...handlers: RequestHandler[]): this;
-    post(routePath: string, ...handlers: RequestHandler[]): this;
-    put(routePath: string, ...handlers: RequestHandler[]): this;
-    delete(routePath: string, ...handlers: RequestHandler[]): this;
-    patch(routePath: string, ...handlers: RequestHandler[]): this;
-    head(routePath: string, ...handlers: RequestHandler[]): this;
-    options(routePath: string, ...handlers: RequestHandler[]): this;
+    get(routePath: string, ...handlersOrOptions: Array<RequestHandler | HttpRouteOptions>): this;
+    post(routePath: string, ...handlersOrOptions: Array<RequestHandler | HttpRouteOptions>): this;
+    put(routePath: string, ...handlersOrOptions: Array<RequestHandler | HttpRouteOptions>): this;
+    delete(routePath: string, ...handlersOrOptions: Array<RequestHandler | HttpRouteOptions>): this;
+    patch(routePath: string, ...handlersOrOptions: Array<RequestHandler | HttpRouteOptions>): this;
+    head(routePath: string, ...handlersOrOptions: Array<RequestHandler | HttpRouteOptions>): this;
+    options(routePath: string, ...handlersOrOptions: Array<RequestHandler | HttpRouteOptions>): this;
     /** Returns `true` if the application has registered its own literal `OPTIONS` route at `path`
      * (not the framework's own `/*` CORS-preflight fallback). See `explicitOptionsPaths`'s own doc
      * comment. `path` is normalized the same way registered routes are, so a trailing-slash mismatch

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rapidrest/service-core",
-    "version": "2.1.1",
+    "version": "2.2.0",
     "description": "Provides all core functionality for RapidREST based backend services.",
     "repository": "https://github.com/rapidrest/service-core.git",
     "author": "RapidREST <rapidrests@gmail.com>",