@rapidrest/service-core 2.1.0 → 2.2.0

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

@@ -1,4 +1,4 @@
-import type { HttpRequest, HttpResponse, RequestHandler } from "./types.js";
+import type { HttpRequest, HttpResponse, HttpRouteOptions, RequestHandler } from "./types.js";
 /**
  * Runs an ordered array of middleware handlers sequentially, Express-style.
  * Supports both 3-param `(req, res, next)` handlers and 4-param `(err, req, res, next)`
@@ -30,6 +30,19 @@ export type WsUpgradeAuthResult = {
  * Authorization header skip the LOGIN step.
  */
 export type WsUpgradeAuth = (req: HttpRequest) => WsUpgradeAuthResult;
+/**
+ * Splits a route registration's variadic argument list into its optional leading `HttpRouteOptions`
+ * and the actual `RequestHandler` list. Shared by both `HttpRouter` (uWS) and `BunRouter` so a route
+ * can be registered as either `app.post(path, handler1, handler2)` (no options — the overwhelmingly
+ * common case, completely unaffected) or `app.post(path, { streamingBody: true }, handler1)`.
+ *
+ * Detection is purely by type: `RequestHandler`s are always functions, so a non-function first
+ * element can only be an options object. This never misfires against a real handler.
+ */
+export declare function splitRouteArgs(args: Array<RequestHandler | HttpRouteOptions>): {
+    options: HttpRouteOptions;
+    handlers: RequestHandler[];
+};
 /** Parses `:param` names out of a route pattern (e.g. `/users/:uid/:version` → `["uid","version"]`). */
 export declare function extractParamNames(routePath: string): string[];
 /**

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

@@ -1,4 +1,5 @@
 import type { HttpRequest, HttpResponse } from "../types.js";
+import { Readable } from "stream";
 /**
  * Minimal structural slice of Bun's `Server` used by `BunRequest`. Deliberately NOT typed as
  * `Bun.Server` — a public constructor parameter typed against the ambient `Bun` namespace would
@@ -137,3 +138,19 @@ export type ReadBunBodyResult = {
  * that lie about or omit `Content-Length` are still caught, matching uWS's guarantee.
  */
 export declare function readBunBody(req: BunRequest, rawRequest: Request, maxBodySize?: number): Promise<ReadBunBodyResult>;
+/**
+ * Exposes a Bun request body as a Node `Readable` stream instead of buffering it, for a route
+ * registered with `{ streamingBody: true }` (see `HttpRouteOptions`). Much simpler than the uWS
+ * equivalent (`makeBodyStream()`) because `rawRequest.body` is already a real, backpressure-aware
+ * Web `ReadableStream` — `Readable.fromWeb()` adapts it without copying, so pulling from the
+ * returned `Readable` (e.g. via `for await` or `.pipe()`) drives the same pull-based backpressure
+ * all the way back to the underlying Bun socket.
+ *
+ * Returns `undefined` for a request with no body (e.g. GET), matching `req.rawBody`/`req.body` being
+ * left `undefined` in that case on the ordinary buffering path.
+ *
+ * Destroys the returned stream if the client disconnects mid-upload, via the request's own
+ * `AbortSignal` — mirroring `makeBodyStream()`'s uWS `onAborted`-driven cleanup — so a handler
+ * consuming it via `for await` sees a thrown error instead of hanging forever.
+ */
+export declare function makeBunBodyStream(rawRequest: Request): Readable | undefined;

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

@@ -1,4 +1,4 @@
-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";
 /**
  * Bun-native HTTP/WebSocket router built on `Bun.serve()`. Exposes the same public surface as the
@@ -40,13 +40,13 @@ export declare class BunRouter implements IHttpRouter {
     private capturePreRouteCount;
     private pushRoute;
     private register;
-    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 `HttpRouter`'s identical method
      * doc comment for the full rationale. `path` is normalized the same way registered routes are, so

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

@@ -1,17 +1,17 @@
-export type { ErrorHandler, HttpRequest, HttpResponse, IHttpRouter, NextFunction, RequestHandler, WebSocketOptions, } from "./types.js";
+export type { ErrorHandler, HttpRequest, HttpResponse, HttpRouteOptions, IHttpRouter, NextFunction, RequestHandler, WebSocketOptions, } from "./types.js";
 export { DEFAULT_WS_OPTIONS } from "./types.js";
 export { isBunRuntime } from "./RuntimeDetect.js";
 export type { IWebSocketShim } from "./IWebSocketShim.js";
-export { extractParamNames, makeWsStubResponse, runChain } from "./MiddlewareChain.js";
+export { extractParamNames, makeWsStubResponse, runChain, splitRouteArgs } from "./MiddlewareChain.js";
 export type { WsUpgradeAuth, WsUpgradeAuthResult } from "./MiddlewareChain.js";
 export type { SessionStore } from "./session/SessionStore.js";
 export { RedisSessionStore } from "./session/RedisSessionStore.js";
 export { SessionManager } from "./session/SessionManager.js";
 export { createSessionMiddleware } from "./session/sessionMiddleware.js";
-export { UWSRequest, UWSResponse, readBody } from "./uWS/Adapters.js";
+export { UWSRequest, UWSResponse, makeBodyStream, readBody } from "./uWS/Adapters.js";
 export type { HttpRouter } from "./uWS/Router.js";
 export type { RequestWS } from "./uWS/WebSocket.js";
 export { UWSWebSocketShim, createWebSocketStream } from "./uWS/WebSocket.js";
-export { BunRequest, BunResponse, readBunBody } from "./bun/BunAdapters.js";
+export { BunRequest, BunResponse, makeBunBodyStream, readBunBody } from "./bun/BunAdapters.js";
 export { BunRouter } from "./bun/BunRouter.js";
 export { BunWebSocketShim } from "./bun/BunWebSocket.js";

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.0",
+    "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>",