@nifrajs/core 2.13.0 → 3.1.0

package/src/server/runtime-core.ts

@@ -5,12 +5,13 @@
  * its values) so `request-context`, `respond`, `node-outcome`, and the kernel form a cycle-free graph.
  */
 import { createUnboundedRequestBudget, type RequestBudget } from "../budget.ts"
+import { NODE_BRIDGE_MARKER_KEYS } from "./bridge-markers.ts"
 import type { CtxSet, RequestSource } from "./server.ts"
 
 /** A handler returns a `Response` (used as-is) or any value (serialized to JSON). */
 export type HandlerResult = Response | unknown
 
-export const RESPONSE_RESULT = Symbol.for("nifra.response.result")
+export const RESPONSE_RESULT = Symbol.for(NODE_BRIDGE_MARKER_KEYS.responseResult)
 export const CONTEXT_SET = Symbol("nifra.context.set")
 export const CONTEXT_SEARCH = Symbol("nifra.context.search")
 
@@ -28,6 +29,28 @@ export interface PreDecodedBody {
   readonly value: unknown
 }
 
+/**
+ * A response described as plain data - the status, any headers of its own, and a body still in value
+ * form. A `ResponseResult` carrying one is rendered on the SAME lane a handler's plain return takes:
+ * `JSON.stringify` straight into the node writer's `kind: "json"` outcome, or the web lane's prebuilt
+ * JSON init. No `Response` is constructed anywhere on the node path.
+ *
+ * That matters because building one is the dominant cost of answering early. Measured on the rig, one
+ * server per shape, all five answering the same 401: `c.set.status` + a plain object 82802 req/s,
+ * `beforeHandle` returning that same object 81819, `return new Response(...)` 49668, `throw new
+ * Response(...)` 47505, the same throw from a `derive` 48746. The `Response` costs 40%; the throw
+ * around it costs another 4%; unwinding a lifecycle stage instead of a handler costs nothing
+ * measurable. So the fix for a slow rejection is not a faster throw - it is not allocating the
+ * `Response`.
+ */
+export interface PlainRender {
+  readonly status: number
+  /** Headers belonging to this render. They win over anything the request left in `c.set.headers`. */
+  readonly headers?: Readonly<Record<string, string>>
+  /** The body as a value, serialized by the lane that renders it. `undefined` means no body. */
+  readonly body: unknown
+}
+
 export interface ResponseResult {
   readonly [RESPONSE_RESULT]: true
   toResponse(): Response
@@ -36,6 +59,9 @@ export interface ResponseResult {
     readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined
     readonly body: string | Uint8Array
   }
+  /** Present when this result can be rendered as plain data - see {@link PlainRender}. Every lane
+   * checks it before `toNodeBody`/`toResponse`, so a carrier that has one never builds a `Response`. */
+  readonly plain?: PlainRender
 }
 
 export function isResponseResult(value: unknown): value is ResponseResult {
@@ -47,6 +73,77 @@ export function isResponseResult(value: unknown): value is ResponseResult {
   )
 }
 
+/**
+ * The headers a plain render ships: its own on top of whatever the request left in `c.set.headers`,
+ * so an ambient header (a request id, say) survives an early exit the way it survives an ordinary
+ * return, and a header named at the exit site still wins.
+ *
+ * Always a fresh object when the render has headers of its own: the node writers mutate the record
+ * they are handed (content-type, content-length, cookies), and a `status(...)` value is commonly
+ * hoisted to module scope and answered from on every request.
+ */
+export function plainRenderHeaders(
+  plain: PlainRender,
+  set: CtxSet,
+): Record<string, string> | undefined {
+  const own = plain.headers
+  if (own === undefined) return set._headers
+  return set._headers === undefined ? { ...own } : { ...set._headers, ...own }
+}
+
+/**
+ * Finish the request here, with this status and body, without building a `Response`.
+ *
+ * Returned or thrown, from a handler or from any lifecycle stage:
+ *
+ * ```ts
+ * app.derive((c) => {
+ *   const user = sessionOf(c)
+ *   if (user === undefined) return status(401, { error: "unauthorized" })
+ *   return { user }
+ * })
+ * ```
+ *
+ * A `derive` is the reason this exists as a value rather than as a rule about `beforeHandle`: a
+ * `beforeHandle` already short-circuits by returning a value, but a `derive`'s return IS the context
+ * extension, so before this its only exit was `throw new Response(...)` - the most expensive way to
+ * say 401 (see {@link PlainRender} for the measurements). Returning it is preferred; throwing it
+ * carries the same cost as any other throw and stays supported so a guard helper called for effect
+ * (`requireSession(c)`) can still end the request from inside a call it makes.
+ *
+ * The body is serialized by the lane that renders it, exactly like a handler's plain return, so the
+ * response carries a `content-length` rather than falling to chunked, and queued cookies still apply.
+ */
+export function status(
+  code: number,
+  body?: unknown,
+  init?: { readonly headers?: Readonly<Record<string, string>> },
+): ResponseResult {
+  // The range `Response` accepts, enforced HERE so the plain lane cannot outrun it. A plain render
+  // is written straight to the socket by the Node adapter, where `writeHead` takes 100-999 - so a
+  // status this rejects would otherwise ship on Node and throw on every Web runtime, from the same
+  // code. One integer comparison against the value already in a register; the divergence it closes
+  // is the kind that only shows up in the runtime an app did not test on.
+  if (!Number.isInteger(code) || code < 200 || code > 599) {
+    throw new RangeError(`[nifra] status(${String(code)}): HTTP status must be an integer 200-599`)
+  }
+  const headers = init?.headers
+  const plain: PlainRender =
+    headers === undefined ? { status: code, body } : { status: code, headers, body }
+  return {
+    [RESPONSE_RESULT]: true,
+    plain,
+    // Only the lanes that cannot take plain data reach this - an edge runtime handed the value by a
+    // caller outside the server, say. Built on demand, never on the lanes that matter.
+    toResponse(): Response {
+      const headers: Record<string, string> = { ...init?.headers }
+      if (body === undefined) return new Response(null, { status: code, headers })
+      headers["content-type"] ??= "application/json;charset=utf-8"
+      return new Response(JSON.stringify(body), { status: code, headers })
+    },
+  }
+}
+
 /** The concrete `Request` for a source - itself when a real `Request` was passed (the Web path), or the
  * lazily-built one (the Node adapter). A real `Request` IS a `RequestSource`, so no wrapper is allocated
  * on the Web hot path. */

package/src/server/server-types.ts

@@ -144,6 +144,21 @@ export interface ServerOptions {
    * Fastify's `setErrorHandler`) instead of repeating a formatter per route.
    */
   readonly onValidationError?: RouteSchema["onValidationError"]
+  /**
+   * What to do when an order-scoped hook (`derive`/`beforeHandle`/`around`/`aroundCapability`/
+   * `afterHandle`/`onError`/`decorate`) covers no route because it was added after the last route was
+   * registered. `register()` snapshots the current chain into each route as it is declared, so a hook
+   * appended after every route reaches nothing and is silently dead. `"warn"` (default) logs once at
+   * seal (first `listen()`/`fetch`/`resolveNode`); `"error"` throws a `FrameworkError`
+   * (`UNUSED_SCOPED_HOOKS`); `"off"` skips the bookkeeping entirely, including the one-frame stack
+   * capture. App-global hooks (`onRequest`/`onResponse`/...) are unaffected in every mode.
+   *
+   * This is a development-time diagnostic: the whole audit is guarded by `process.env.NODE_ENV !==
+   * "production"`, so any bundler that defines `NODE_ENV` (vite/esbuild/webpack/next, `bun build
+   * --production`) dead-code-eliminates it, leaving zero bytes and zero per-request cost in the shipped
+   * bundle. It fires in development, test, and CI - where you catch the mistake - not in production.
+   */
+  readonly unusedScopedHooks?: "warn" | "error" | "off"
 }
 
 /** A fetch-compatible handler used by {@link Server.mountFetch}. */
@@ -246,7 +261,9 @@ export interface RunningServer {
 /**
  * A bundle of lifecycle hooks applied together via {@link Server.use} - the unit
  * `@nifrajs/middleware` ships (cors, security headers, rate-limit). Every hook is
- * optional and wired to its lifecycle point. Middleware is context-agnostic (sees
+ * optional and wired to its lifecycle point. Middleware carrying a portable response tier must be
+ * marked with `withResponseObserver()` from `@nifrajs/core/response-observer`, or the server must
+ * install `responseObserver()` before the bundle is applied. Middleware is context-agnostic (sees
  * the base `Context`); `use` does no context-type merging - the full type-merging
  * plugin system is deferred, and `.use` is reserved as its future entry point.
  */