@nifrajs/core 2.11.0 → 2.12.0

package/src/server/server-types.ts

@@ -40,15 +40,45 @@ export interface AdmissionController {
 
 export interface ServerOptions {
   /**
-   * Max request body size (bytes), enforced **only when a route declares a body schema** - the cap
-   * lives in the schema-validated read path. Default 1_000_000.
+   * Max request body size (bytes), the default transport cap for every route. Default 1_000_000.
+   * A route can choose a finite `schema.bodyLimit` of its own; an explicit `'unlimited'` route
+   * requires `schema.bodyLimitReason` and is intended only for a separately bounded streaming or
+   * upload integration.
    *
-   * A route WITHOUT a body schema (raw body, file upload, BYO-validation) that reads `c.req` directly
-   * is not auto-bounded - use **`c.boundedBody(maxBytes?)`** / **`c.boundedJson(maxBytes?)`**, which
-   * apply this same cap (override per route by passing `maxBytes` - larger for an upload endpoint,
-   * smaller to tighten one).
+   * Framework readers (the body-schema lane, `c.boundedJson`) enforce the cap when they read. A
+   * route WITHOUT a body schema (raw body, file upload, BYO-validation) is covered too: direct
+   * `c.req` reads (`json()`, `arrayBuffer()`, the raw `body` stream, ...) are capped in place -
+   * lazily, nothing is buffered until code actually reads - and answer 413 past the limit.
+   * `c.boundedBody(n)` states its own explicit per-read limit, above or below the route's cap.
    */
   readonly maxBodyBytes?: number
+  /**
+   * Prototype-poisoning policy for JSON bodies (the schema path and `c.boundedJson`). An own
+   * `__proto__` key, or a `constructor` carrying a `prototype`, is the payload shape that turns a
+   * later innocent merge/assign into prototype pollution. `"reject"` (default) answers the same
+   * flat 400 as malformed JSON; `"strip"` removes the offending keys and continues; `"ignore"`
+   * parses as-is (only for routes that never merge body input into other objects). Clean payloads
+   * pay a substring pre-scan only - the deep walk runs solely on suspect text.
+   */
+  readonly protoPoisoning?: "reject" | "strip" | "ignore"
+  /**
+   * Declare that every `Request` reaching `app.fetch` was framed by a runtime HTTP parser, so its
+   * `Content-Length` is an exact transport boundary rather than a hint. Set this ONLY when the
+   * runtime's own request object is handed through untouched with no adapter in between to mark it -
+   * a bare `export default app` on an edge runtime. Every supported ingress already marks itself:
+   * `listen()` on Bun, `toFetchHandler(app)` on Workers/edge, `@nifrajs/deno`, and `@nifrajs/node`
+   * (which reads exact bytes and never needs the mark). Reach for this option only for an ingress
+   * nifra does not ship an adapter for.
+   *
+   * Left off (default), the JSON body lane copies the body out and enforces the cap on DELIVERED
+   * bytes, because an unmarked request may have been rebuilt by an adapter that kept a caller's
+   * `content-length` while decoding a payload of a different size. That check costs an extra pass
+   * over the body, which is why an edge deployment that cannot be lied to may opt out of it.
+   *
+   * Do not set this on an app whose `fetch` is also called with `Request`s assembled from
+   * untrusted input.
+   */
+  readonly trustBodyFraming?: boolean
   /** Max inbound WebSocket message size (bytes) when `listen()`ing on Bun - frames over this are rejected
    * by the runtime before reaching your handler (so a huge frame can't be JSON-parsed into memory).
    * Default: `maxBodyBytes` (1 MB). */
@@ -91,6 +121,21 @@ export interface ServerOptions {
   readonly onCapabilityUse?: (event: CapabilityUseEvent) => void
   /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
   readonly logger?: Logger
+  /**
+   * How much of an unhandled error reaches the log for a 500. Never reaches the client either way -
+   * the response is always a bare `internal_error`.
+   *
+   * - `"full"` (default) - `name`, the error's own text as `detail`, and `stack`.
+   * - `"message"` - `name` and `detail`, no stack.
+   * - `"none"` - `name` only.
+   *
+   * An error's text can quote the input that produced it, which is how request data ends up in a log
+   * sink. The framework's answer is the redacting logger rather than blanket suppression: pass
+   * `logger: jsonLogger({ valuePatterns: commonSecretPatterns })` to scrub tokens, JWTs, and emails
+   * out of `detail` and `stack` while keeping the diagnosis. Reach for `"none"` when the sink itself
+   * is the thing you don't trust.
+   */
+  readonly errorLogDetail?: "full" | "message" | "none"
   /**
    * App-wide fallback fired when a route **without its own `onValidationError`** fails body/query
    * validation. Same contract as the per-route hook (`(issues, ctx, kind) => Response | repaired-value |
@@ -101,6 +146,21 @@ export interface ServerOptions {
   readonly onValidationError?: RouteSchema["onValidationError"]
 }
 
+/** A fetch-compatible handler used by {@link Server.mountFetch}. */
+export type FetchHandler<Env = unknown> = (
+  request: Request,
+  platform?: Platform<Env>,
+) => MaybePromise<Response>
+
+/** Options for a legacy fetch-handler mount. */
+export interface MountFetchOptions {
+  /** Remove the mount prefix before invoking the legacy handler. Default: false. */
+  readonly stripPrefix?: boolean
+}
+
+/** A callback awaited after the Bun server has drained and stopped. */
+export type StopHook = () => MaybePromise<void>
+
 /**
  * MCP tool safety hints, surfaced in `tools/list`, that tell an agent how risky a `.tool()` call is - so it
  * can decide whether to auto-invoke or confirm first. All optional; an omitted hint means "unknown". Mirrors