@rapidrest/service-core 2.1.1 → 2.2.1

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>;
 /**
@@ -70,9 +71,23 @@ export declare class UWSResponse implements HttpResponse {
     isHead: boolean;
     /** Intermediate result passed between middleware. */
     result?: any;
+    /**
+     * Set by the router via `attachBodyStream()` for a streaming-body route (see
+     * `HttpRouteOptions.streamingBody`). `end()` checks `isBodyStreamFullyReceived()` against it —
+     * see that function's doc comment and `end()` for the full rationale.
+     */
+    private _bodyStream?;
     /** Allow arbitrary per-response properties. */
     [key: string]: any;
     constructor(uwsRes: UWSHttpResponse);
+    /**
+     * Associates this response with a streaming-body route's `req.bodyStream`, so `end()` can detect
+     * a response finalizing before uWS has received the whole declared request body and force the
+     * connection closed instead of hanging it — see `isBodyStreamFullyReceived()`'s doc comment for
+     * the full rationale. Called once, by the router, right after `makeBodyStream()` creates the
+     * stream (`HttpRouteOptions.streamingBody` routes only — never called otherwise).
+     */
+    attachBodyStream(stream: Readable): void;
     get statusCode(): number;
     get headersSent(): boolean;
     get writableEnded(): boolean;
@@ -136,3 +151,76 @@ 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;
+/**
+ * Returns `true` once uWS has delivered the final chunk of `stream`'s request body — i.e. it is safe
+ * to let the underlying connection return to uWS's keep-alive pool — regardless of whether anything
+ * has actually consumed the stream. Returns `true` for `undefined` (nothing to wait for) so callers
+ * can pass `req.bodyStream` directly without an existence check first.
+ *
+ * See `UWSResponse.end()`: a streaming route's handler can legitimately respond (an auth failure, a
+ * validation error, anything) without ever reading `req.bodyStream`. If the client declared a large
+ * `Content-Length` and hasn't actually sent it all yet — or, in the malicious case, never intends to
+ * — a plain `uwsRes.end()` at that point leaves the keep-alive connection open indefinitely: uWS
+ * won't consider it clean for reuse until it has received every byte of the declared body, and nothing
+ * in that scenario ever makes that happen. `end()` uses this check to force the connection closed
+ * instead whenever it would otherwise leave that promise unfulfilled.
+ */
+export declare function isBodyStreamFullyReceived(stream: Readable | undefined): boolean;
+/**
+ * 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 same pairing discipline also applies to the final chunk: when a chunk that overflows the
+ * buffer also happens to be the last one (`isLast`), `pause()` is skipped entirely — the stream is
+ * about to signal EOF via `push(null)` regardless, so Node's `Readable` never calls `_read()` again
+ * to issue the matching `resume()`, which would otherwise leave uWS's connection paused forever with
+ * nothing left in this function to ever un-pause it.
+ *
+ * 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`. A route that never reads `req.bodyStream` at all can still hit this path — e.g.
+ * `UWSResponse.end()` itself calls `uwsRes.close()` (which fires `onAborted`) when finalizing a
+ * response before the body was fully received — so a permanent no-op `error` listener is attached
+ * below as well: a `Readable` with no active consumer still emits `error` on `destroy(err)`, and
+ * Node treats an `error` event with zero listeners as fatal (crashes the process). This listener
+ * doesn't swallow anything from a real consumer — `for await`/`.pipe()`/an explicit `.on("error")`
+ * all still see the same event; EventEmitter calls every registered listener, not just the first.
+ *
+ * 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/dist/types/models/ModelUtils.d.ts

@@ -67,6 +67,8 @@ export declare class ModelUtils {
     private static idPropertyCache;
     private static readOnlyPropertyCache;
     private static columnTypeCache;
+    /** Caches each class's `@RequiresScope`-decorated property names to their required scopes (see `assertFieldScope()`). */
+    private static scopedPropertyCache;
     /** Sequence used to give every `Raw()` SQL expression's named parameter a unique name within one query. */
     private static rawParamSeq;
     /**
@@ -120,6 +122,43 @@ export declare class ModelUtils {
      * @returns The list of all property names that have the @ReadOnly decorator applied.
      */
     static getReadOnlyPropertyNames(modelClass: any): string[];
+    /**
+     * Returns a map of every `@RequiresScope`-decorated property on `modelClass` to the scope(s) it requires (the
+     * exact same `rrst:scopes` metadata `@rapidrest/core`'s `ObjectUtils.deleteScopedProps()` reads to redact a
+     * property from an already-fetched result). `undefined` when `modelClass` isn't provided.
+     *
+     * Deliberately does NOT use `getReadOnlyPropertyNames()`'s prototype-walking-only pattern: a plain class field
+     * initializer (`public salary: number = 0`) compiles to an own-INSTANCE assignment, so it never appears on the
+     * prototype at all unless its OWN decorator specifically forces a placeholder there (this framework's
+     * `@ReadOnly`/`@Identifier` do; `@rapidrest/core`'s `RequiresScope` has no reason to and doesn't). Confirmed
+     * empirically: `Object.getOwnPropertyNames(SomeClass.prototype)` for a bare `@RequiresScope("x") salary = 0`
+     * field returns only `["constructor"]`. Instead this walks the property names of an actual constructed
+     * instance (mirroring `deleteScopedProps()`'s own `Object.getOwnPropertyNames(obj)` over a data object) union
+     * the prototype chain (still needed to also catch a property that IS forced onto the prototype, e.g. one
+     * additionally decorated with `@ReadOnly`) — metadata itself is always read off `modelClass.prototype`
+     * (`Reflect.getMetadata` walks the prototype chain on its own), regardless of which own-properties surfaced
+     * the candidate name.
+     */
+    private static getScopedPropertyNames;
+    /**
+     * Rejects (400) a search filter, sort or count referencing a `@RequiresScope`-protected property when the
+     * requesting user doesn't hold at least one of its required scopes.
+     *
+     * Without this, `@RequiresScope` was only ever a RESPONSE-time redaction (`ObjectUtils.deleteScopedProps()`,
+     * applied after a query already ran) — a scope-restricted field could still drive `WHERE`/`ORDER BY`/count
+     * itself, letting a caller who could never READ the field's value still binary-search it out via repeated
+     * `gt()`/`lt()`/`range()` filters, turn a `HEAD` request's `Content-Length` into an existence/equality oracle
+     * via `count()`, or read its relative ordering via `sort`. Checked at query-BUILD time instead, so a
+     * disallowed field never reaches `WHERE`/`ORDER BY`/count in the first place — matches `hasScopes()`'s exact
+     * semantics (same function `deleteScopedProps()` uses), so query-time rejection and response-time redaction
+     * never disagree about who has access to a given field.
+     *
+     * Applied uniformly to every field referenced by a filter (regardless of operator — `eq`/`gt`/`like`/`regex`/
+     * `exists`/... all pass through this same per-key check) and to every `sort` key, on both SQL and Mongo.
+     *
+     * @throws {ApiError} 400 `SEARCH_SCOPED_FIELD` if `property` requires a scope `user` doesn't hold.
+     */
+    private static assertFieldScope;
     /**
      * Resolves the declared type of a model property, from an explicit `type` override on `@Column` or (falling
      * back) the TypeScript design-time type reflected at decoration time. Returns `undefined` when `modelClass`

package/dist/types/routes/RouteUtils.d.ts

@@ -71,6 +71,26 @@ export declare class RouteUtils {
      * @param requiredScopes The list of scopes of which the authenticated user's token must carry at least one.
      */
     checkRequiredScopes(requiredScopes: string[]): RequestHandler;
+    /**
+     * Creates a WebSocket-specific error-sanitizing middleware, appended as the last item in every
+     * `@WebSocket()` route's handler chain (see `registerRoute()`'s WS branch below). Mirrors what
+     * `Server.ts`'s `handleError()`/`serializeError()` already do for ordinary HTTP routes: an
+     * `ApiError`'s own status/code/message pass through unchanged (it's meant to reach the client),
+     * but anything else — a raw DB driver error, an unexpected throw from `RateLimiter`,
+     * `ACLUtils.findACL()`, or any other non-`ApiError` thrown by a middleware in the chain — is
+     * replaced with a generic internal error before `runChain()`'s own end-of-chain fallback can turn
+     * it into a response.
+     *
+     * This matters specifically for WebSocket routes because `runChain()`'s fallback response, for a
+     * WS route, ends up as the literal WebSocket close reason (`ws.close(1002, message)` — see
+     * `Router.ts`/`BunRouter.ts`'s `ws()` `open` handlers), visible to any client via the browser
+     * close event's `event.reason`. An ordinary HTTP route gets the same sanitization for free
+     * because `Server.ts` registers `handleError` as global middleware, which `registerRoute()`
+     * concatenates onto every HTTP route's own handler chain — but `app.ws()` is never given
+     * `globalMiddleware` (only the WS-specific chain built here), so WS routes need their own copy of
+     * the same safety net.
+     */
+    sanitizeWsError(): RequestHandler;
     /**
      * Converts the given array of string or Function objects to functions bound to the given route object.
      *

package/package.json

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