@nifrajs/core 3.3.0 → 4.0.0

package/src/server/response-contract-lane.ts

@@ -48,7 +48,7 @@ import {
 } from "../schema/standard.ts"
 import { INSTALL_RESPONSE_CONTRACT } from "./install.ts"
 import type { IdentityPlugin } from "./plugin.ts"
-import { isResponseResult } from "./runtime-core.ts"
+import { isResponseResult, status } from "./runtime-core.ts"
 import type { AnyServer } from "./server.ts"
 
 /**
@@ -62,6 +62,12 @@ import type { AnyServer } from "./server.ts"
  */
 export type ResponseContractMode = "warn" | "enforce"
 
+/** Success and status-specific error schemas captured by one route at registration time. */
+export interface ResponseContractDefinition {
+  readonly response?: StandardSchemaV1
+  readonly errors?: Readonly<Record<number, StandardSchemaV1>>
+}
+
 /** The outcome of checking one handler result against its declared response schema. */
 export type ResponseContractOutcome =
   /** Nothing to report. `value` is what should be serialized (the original result, or the cleaned one). */
@@ -91,38 +97,104 @@ export function checkResponseContract(
   result: unknown,
   mode: "warn" | "enforce",
 ): ResponseContractOutcome | Promise<ResponseContractOutcome> {
+  return checkRouteResponseContract({ response: schema }, result, mode)
+}
+
+/** The schema a reply with this status is held to: `response` for 2xx, else `errors[status]`. */
+const schemaFor = (definition: ResponseContractDefinition, code: number) =>
+  code >= 200 && code < 300 ? definition.response : definition.errors?.[code]
+
+/** A `c.json(...)` reply rebuilt around its validated value, keeping its status and headers. */
+function reserialize(reply: Response, value: unknown): Response {
+  const headers = new Headers(reply.headers)
+  headers.delete("content-length")
+  return new Response(JSON.stringify(value), {
+    status: reply.status,
+    statusText: reply.statusText,
+    headers,
+  })
+}
+
+/**
+ * Check a route's success or status-specific error payload. Plain `status()` results retain their
+ * status while enforcement replaces only the body with the validator's output. A `c.json(...)`
+ * reply is held to the contract through the value it was built from (`jsonReply`). Any other raw
+ * `Response` remains an explicit transport escape hatch because inspecting it would consume
+ * streams or alter redirects; assurance/static checks must govern that path separately.
+ */
+export function checkRouteResponseContract(
+  definition: ResponseContractDefinition,
+  result: unknown,
+  mode: "warn" | "enforce",
+  jsonReply?: { readonly body: unknown },
+): ResponseContractOutcome | Promise<ResponseContractOutcome> {
+  const plain = isResponseResult(result) ? result.plain : undefined
+  if (plain !== undefined) {
+    const schema = schemaFor(definition, plain.status)
+    if (schema === undefined) return { kind: "ok", value: result }
+    return validateContract(schema, plain.body, result, mode, (value) =>
+      status(
+        plain.status,
+        value,
+        plain.headers === undefined ? undefined : { headers: plain.headers },
+      ),
+    )
+  }
+  if (jsonReply !== undefined && result instanceof Response) {
+    const schema = schemaFor(definition, result.status)
+    if (schema === undefined) return { kind: "ok", value: result }
+    return validateContract(schema, jsonReply.body, result, mode, (value) =>
+      reserialize(result, value),
+    )
+  }
+
   // A handler may return a raw Response as deliberate control flow (a redirect, a stream). There is no
   // JSON payload to hold to the contract, and re-serializing one would corrupt it. A `status(...)` is
-  // the same control flow in plain-data form: the contract describes the route's SUCCESS payload, so
-  // holding an early exit (a 401 body, say) to it would fail every guarded route that declares one.
-  if (result instanceof Response || result === undefined || isResponseResult(result))
-    return { kind: "ok", value: result }
-  const settled = schema["~standard"].validate(result)
+  // intentionally handled above because its plain body and status remain available without consuming
+  // a stream. An absent body has nothing to validate.
+  if (result instanceof Response || result === undefined) return { kind: "ok", value: result }
+  const schema = definition.response
+  if (schema === undefined) return { kind: "ok", value: result }
+  return validateContract(schema, result, result, mode, (value) => value)
+}
+
+/** Validate `payload`; `served` is what goes out unchanged when nothing is enforced - the whole
+ * `status(...)` result or reply, never just its body. */
+function validateContract(
+  schema: StandardSchemaV1,
+  payload: unknown,
+  served: unknown,
+  mode: "warn" | "enforce",
+  replace: (value: unknown) => unknown,
+): ResponseContractOutcome | Promise<ResponseContractOutcome> {
+  const settled = schema["~standard"].validate(payload)
   return settled instanceof Promise
-    ? settled.then((r) => interpret(r, result, mode))
-    : interpret(settled, result, mode)
+    ? settled.then((r) => interpret(r, payload, served, mode, replace))
+    : interpret(settled, payload, served, mode, replace)
 }
 
 function interpret(
   settled: StandardResult<unknown>,
-  result: unknown,
+  payload: unknown,
+  served: unknown,
   mode: "warn" | "enforce",
+  replace: (value: unknown) => unknown,
 ): ResponseContractOutcome {
   if (settled.issues !== undefined) {
     const message = `response does not satisfy its declared contract: ${formatStandardIssues(settled.issues)}`
     // `warn` never changes what is served - it reports and gets out of the way, so switching it on can
     // never be the thing that broke production.
     return mode === "warn"
-      ? { kind: "warn", value: result, message }
+      ? { kind: "warn", value: served, message }
       : { kind: "violation", message }
   }
-  const dropped = droppedKeys(result, settled.value)
-  if (mode === "enforce") return { kind: "ok", value: settled.value }
+  const dropped = droppedKeys(payload, settled.value)
+  if (mode === "enforce") return { kind: "ok", value: replace(settled.value) }
   return dropped.length === 0
-    ? { kind: "ok", value: result }
+    ? { kind: "ok", value: served }
     : {
         kind: "warn",
-        value: result,
+        value: served,
         message: `response carries fields its contract does not declare: ${dropped.join(", ")}. They are being sent; \`responseContract: "enforce"\` would strip them.`,
       }
 }
@@ -134,8 +206,9 @@ function interpret(
 export interface ResponseContractRuntime {
   readonly mode: ResponseContractMode
   check(
-    schema: StandardSchemaV1,
+    definition: ResponseContractDefinition,
     result: unknown,
+    context?: { readonly jsonReply?: Response | undefined; readonly jsonBody?: unknown },
   ): ResponseContractOutcome | Promise<ResponseContractOutcome>
 }
 
@@ -161,7 +234,15 @@ interface ResponseContractInstallable {
 export function responseContract(mode: ResponseContractMode = "warn"): IdentityPlugin {
   const runtime: ResponseContractRuntime = {
     mode,
-    check: (schema, result) => checkResponseContract(schema, result, mode),
+    check: (definition, result, context) =>
+      checkRouteResponseContract(
+        definition,
+        result,
+        mode,
+        result instanceof Response && result === context?.jsonReply
+          ? { body: context.jsonBody }
+          : undefined,
+      ),
   }
   const apply = <S extends AnyServer>(app: S): S => {
     ;(app as unknown as ResponseContractInstallable)[INSTALL_RESPONSE_CONTRACT](runtime)

package/src/server/response-observer-runtime.ts

@@ -1,5 +1,6 @@
 import type {
   NodeRequestContext,
+  NodeResponseBodyHook,
   NodeResponseHook,
   ResponseBodyHook,
   ResponseHeadersHook,
@@ -12,18 +13,30 @@ import { applyBodyReplacement, withReplacedBody } from "./response-hooks.ts"
 type MaybePromise<T> = T | Promise<T>
 type WebResponseHook = (response: Response, req: Request) => MaybePromise<Response>
 
-export type { ResponseBodyHook, ResponseHeadersHook } from "./node-outcome-hook.ts"
+export type {
+  NodeResponseBodyHook,
+  ResponseBodyHook,
+  ResponseHeadersHook,
+} from "./node-outcome-hook.ts"
 
 export interface ResponseObserverHost {
   assertConfigurable(operation: string): void
-  addResponseHook(web: WebResponseHook, node: NodeResponseHook | undefined): void
+  addResponseHook(
+    web: WebResponseHook,
+    node: NodeResponseHook | undefined,
+    headerOnly?: boolean,
+  ): void
   enableResponseBodyTagging(): object
   responseBodyOwners(): ReadonlySet<object>
 }
 
 export interface ResponseObserverMethods {
-  onResponseHeaders(fn: ResponseHeadersHook): this
-  onResponseBody(fn: ResponseBodyHook): this
+  /**
+   * Register a portable header hook. `node` is an optional equivalent for the Node-direct record;
+   * it must preserve the portable hook's observable header semantics.
+   */
+  onResponseHeaders(fn: ResponseHeadersHook, node?: NodeResponseHook): this
+  onResponseBody(fn: ResponseBodyHook, node?: NodeResponseBodyHook): this
   onResponseRaw(fn: (response: Response, req: Request) => MaybePromise<Response>): this
 }
 
@@ -81,7 +94,11 @@ export function createResponseObserverRuntime(): ResponseObserverRuntime {
   return {
     install(host) {
       return {
-        onResponseHeaders(this: ResponseObserverMethods, fn): ResponseObserverMethods {
+        onResponseHeaders(
+          this: ResponseObserverMethods,
+          fn: ResponseHeadersHook,
+          node?: NodeResponseHook,
+        ): ResponseObserverMethods {
           host.assertConfigurable("onResponseHeaders()")
           host.addResponseHook(
             (response, req) => {
@@ -89,11 +106,16 @@ export function createResponseObserverRuntime(): ResponseObserverRuntime {
               const out = fn(view.headers, view.request, response.status)
               return out instanceof Promise ? out.then(() => view.response) : view.response
             },
-            (response, req) => fn(recordHeadersView(response), req, response.status),
+            node ?? ((response, req) => fn(recordHeadersView(response), req, response.status)),
+            true,
           )
           return this
         },
-        onResponseBody(this: ResponseObserverMethods, fn): ResponseObserverMethods {
+        onResponseBody(
+          this: ResponseObserverMethods,
+          fn: ResponseBodyHook,
+          node?: NodeResponseBodyHook,
+        ): ResponseObserverMethods {
           host.assertConfigurable("onResponseBody()")
           host.enableResponseBodyTagging()
           host.addResponseHook(
@@ -108,12 +130,18 @@ export function createResponseObserverRuntime(): ResponseObserverRuntime {
             },
             (response, req) => {
               if (response.body === null) return undefined
-              const out = fn(response.body, recordHeadersView(response), req, response.status)
+              // An author-supplied twin sees the same bytes and returns through the same
+              // replacement channel; only the header-view allocation is skipped.
+              const out =
+                node === undefined
+                  ? fn(response.body, recordHeadersView(response), req, response.status)
+                  : node(response.body, response, req, response.status)
               if (out instanceof Promise)
                 return out.then((replaced) => applyBodyReplacement(response, replaced))
               applyBodyReplacement(response, out)
               return undefined
             },
+            false,
           )
           return this
         },
@@ -126,6 +154,7 @@ export function createResponseObserverRuntime(): ResponseObserverRuntime {
                 ? fn(response, req)
                 : response,
             () => undefined,
+            false,
           )
           return this
         },

package/src/server/runtime-core.ts

@@ -27,6 +27,8 @@ export const PRE_DECODED_BODY = Symbol("nifra.body.preDecoded")
 /** The stash shape under {@link PRE_DECODED_BODY}. */
 export interface PreDecodedBody {
   readonly value: unknown
+  /** The encoded size, so the route's own body limit still applies to a body decoded before routing. */
+  readonly byteLength: number
 }
 
 /**

package/src/server/server-types.ts

@@ -5,17 +5,19 @@
  */
 import type { CapabilityUseEvent } from "../internal/capability-runtime.ts"
 import type { AssuranceEvidence } from "../internal/route-assurance.ts"
-import type { Method } from "../router/router.ts"
+import type { RouteMethod } from "../router/router.ts"
 import type { ClientIpTrust } from "./client-ip.ts"
 import type { Context, Platform, RouteSchema } from "./context.ts"
 import type { Logger } from "./logger.ts"
 import type {
   NodeRequestHook,
+  NodeResponseBodyHook,
   NodeResponseHook,
   ResponseBodyHook,
   ResponseHeadersHook,
 } from "./node-outcome-hook.ts"
 import type { MaybePromise, OnRequestResult } from "./server.ts"
+import type { WebSocketUpgradeOutcome } from "./websocket.ts"
 
 /**
  * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
@@ -85,6 +87,8 @@ export interface ServerOptions {
   readonly wsMaxPayloadBytes?: number
   /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
   readonly requestTimeoutMs?: number
+  /** WebSocket upgrade admission/guard timeout (ms). Default 10_000; set to 0 only for a deliberate unbounded guard. */
+  readonly wsUpgradeTimeoutMs?: number
   /**
    * How to derive `c.clientIp` behind a reverse proxy or CDN. Omit (default) to trust only the raw
    * socket peer and never believe a forwarded header. Set `{ trustedHops: n }` when the app sits
@@ -167,10 +171,46 @@ export type FetchHandler<Env = unknown> = (
   platform?: Platform<Env>,
 ) => MaybePromise<Response>
 
+/** A fetch app that may also participate in adapter-owned WebSocket upgrades when mounted. */
+export interface MountableApp<Env = unknown> {
+  readonly fetch: FetchHandler<Env>
+  readonly resolveWebSocketUpgrade?: (
+    request: Request,
+    platform?: Platform<Env>,
+  ) => MaybePromise<WebSocketUpgradeOutcome>
+}
+
+/** Options for a first-class composed mount. */
+export interface MountOptions<Env = unknown> {
+  /** Absolute pathname prefix, optionally ending in `/*`. */
+  readonly path: string
+  /** The child app. Its HTTP fetch and optional WebSocket resolver share the mount. */
+  readonly app: MountableApp<Env>
+  /** Rewrite the child request to remove `path` before dispatch. Default: false. */
+  readonly stripPrefix?: boolean
+  /** Higher values run first; ties use the most specific path, then declaration order. */
+  readonly priority?: number
+  /** For safe replayable methods only, try the next matching mount when this one returns 404. */
+  readonly fallbackOn?: 404
+  /**
+   * Why this child is not analyzed, for a handler whose effects nifra cannot follow (a closure from
+   * another package). Capability assurance lists a mount with a reason as a known gap; a mount
+   * without one fails it, since its routes are invisible. A nifra `server()` belongs in `merge()`,
+   * where its routes are analyzed.
+   */
+  readonly opaque?: string
+}
+
 /** Options for a legacy fetch-handler mount. */
 export interface MountFetchOptions {
   /** Remove the mount prefix before invoking the legacy handler. Default: false. */
   readonly stripPrefix?: boolean
+  /** Higher values run first; ties use the most specific path, then declaration order. */
+  readonly priority?: number
+  /** For safe replayable methods only, try the next matching legacy mount when it returns 404. */
+  readonly fallbackOn?: 404
+  /** Why this handler is not analyzed - see {@link MountOptions.opaque}. */
+  readonly opaque?: string
 }
 
 /** A callback awaited after the Bun server has drained and stopped. */
@@ -200,9 +240,11 @@ export interface ToolAnnotations {
  * (e.g. `toOpenAPI`) enumerate routes after registration.
  */
 export interface RouteDescriptor {
-  readonly method: Method
+  readonly method: RouteMethod
   readonly path: string
   readonly schema: RouteSchema | undefined
+  /** Runtime response-contract mode captured when this route was registered. */
+  readonly responseContract?: "warn" | "enforce"
   /** Effective enforcement evidence, populated only during reflection/introspection. */
   readonly assurance?: readonly AssuranceEvidence[]
   /** Normalized declared effect tokens, populated only when the route declares any. */
@@ -246,6 +288,19 @@ export interface McpPromptDescriptor {
   readonly handler: (args: Record<string, string>) => MaybePromise<readonly PromptMessage[]>
 }
 
+/**
+ * TLS for `listen()`: serve HTTPS from Bun itself, with no proxy in front. `cert` and `key` are PEM,
+ * as text or as the file's bytes (`readFileSync("cert.pem")`); `passphrase` unlocks an encrypted key.
+ */
+export interface ListenTlsOptions {
+  /** The certificate chain, PEM. */
+  readonly cert: string | Uint8Array
+  /** The private key, PEM. */
+  readonly key: string | Uint8Array
+  /** The passphrase of an encrypted `key`. */
+  readonly passphrase?: string
+}
+
 /**
  * The handle `listen()` returns - the slice of Bun's server nifra holds and exposes.
  * Declared explicitly (rather than `ReturnType<typeof Bun.serve>`) so the public type
@@ -301,6 +356,8 @@ export interface Middleware {
    * an optional `onNodeResponse` twin only when the hook must see a real `Response`.
    */
   readonly onResponseHeaders?: ResponseHeadersHook
+  /** Allocation-light Node-direct twin for a portable header-only hook; keep its wire semantics identical. */
+  readonly onNodeResponseHeaders?: NodeResponseHook
   /**
    * PORTABLE post-serialization body hook - the payload tier. Receives the final
    * framework-serialized bytes (already resident on every runtime; no stream is drained) plus the
@@ -308,6 +365,8 @@ export interface Middleware {
    * (proxies, SSE, streamed SSR) are skipped by contract - transforming those needs `onResponse`.
    */
   readonly onResponseBody?: ResponseBodyHook
+  /** Allocation-light Node-direct twin for a portable body hook; keep its wire semantics identical. */
+  readonly onNodeResponseBody?: NodeResponseBodyHook
   /**
    * Response transform for untagged/raw responses (streams, proxied fetches, and framework errors).
    * Framework-serialized payloads use `onResponseBody` and remain on the Node direct lane.