@nifrajs/core 5.10.0 → 5.12.0

package/src/internal/route-lanes.ts

@@ -2,9 +2,9 @@
  * Registration-time route-lane selection.
  *
  * A route's lane is a property of its registered shape, not of an individual request. Keeping this
- * decision in a small internal module gives the server kernel one vocabulary for bare/body/query/
- * lifecycle execution while preserving the important invariant: this module is never called from the
- * request path. The returned booleans are consumed by the existing compiled execution plan and fused
+ * decision in a small internal module gives the server kernel one vocabulary for
+ * bare/body/query/input/lifecycle execution. This module is never called from the request path. The
+ * returned booleans are consumed by the existing compiled execution plan and fused
  * builders; no adapter or extra dispatch hop is introduced at runtime.
  */
 import type { RouteSchema } from "../server/context.ts"
@@ -18,7 +18,7 @@ export interface RouteLaneSelection {
   readonly lane: RouteExecutionLane
   readonly lifecycleLane: LifecycleExecutionLane
   readonly lifecycleHookLane: "hooks" | undefined
-  readonly fusedLane: "bare" | "body" | "query" | "hooks" | "body-hooks" | undefined
+  readonly fusedLane: "bare" | "body" | "query" | "inputs" | "hooks" | undefined
 }
 
 export function selectRouteLanes(options: {
@@ -52,13 +52,20 @@ export function selectRouteLanes(options: {
 
   const authBeforeValidation =
     options.hasAuth === true || schema?.validationOrder === "auth-before-validation"
-  // No fused lane validates params, headers, or cookies: any of those schemas keeps the stage runner.
-  const plain =
-    schema?.params === undefined && schema?.headers === undefined && schema?.cookies === undefined
+  // Narrow body/query runners handle simple shapes; the shared input lane composes schemas.
+  const plain = schema?.headers === undefined && schema?.cookies === undefined
+  const noParams = schema?.params === undefined
+  const hasInputSchema =
+    schema?.headers !== undefined ||
+    schema?.cookies !== undefined ||
+    schema?.params !== undefined ||
+    schema?.body !== undefined ||
+    schema?.query !== undefined
 
   const bare =
     !authBeforeValidation &&
     plain &&
+    noParams &&
     schema?.body === undefined &&
     schema?.query === undefined &&
     !hasIdempotency &&
@@ -69,19 +76,18 @@ export function selectRouteLanes(options: {
     afterHandle === 0 &&
     onError === 0
 
-  // A route whose ONLY lifecycle step is a query schema can fuse too: the parse + validate + handler +
-  // respond collapse into one closure with no lifecycle promise on the sync path. The guards mirror the
-  // query lane below PLUS everything the fused dispatch skips: around hooks, the idempotency/ledger
-  // wrappers, and validation-error recovery (schema or server default) - the fused invalid path is
-  // exactly `validationError(issues)`, so any recovery semantics keep the generic lane.
+  // A route whose only input stages are path params and/or a query schema can fuse too: validate +
+  // handler + respond collapse into one closure with no lifecycle promise on the sync path. The guards
+  // mirror the query lane below PLUS everything the fused dispatch skips: around hooks, the
+  // idempotency/ledger wrappers, and validation-error recovery (schema or server default).
   const fusedQuery =
     !bare &&
     !authBeforeValidation &&
     !hasResponseContract &&
-    schema?.query !== undefined &&
+    (schema?.query !== undefined || schema?.params !== undefined) &&
     schema.body === undefined &&
     plain &&
-    schema.onValidationError === undefined &&
+    schema?.onValidationError === undefined &&
     !defaultOnValidationError &&
     !hasIdempotency &&
     !hasLedger &&
@@ -112,17 +118,32 @@ export function selectRouteLanes(options: {
     !hasLedger &&
     around === 0
 
+  // The shared input runner handles every ordinary validation shape, including body+query and
+  // params+headers+cookies combinations. It also carries lifecycle and error hooks; only recovery
+  // callbacks or outer wrappers that observe the stage sequence need the general program.
+  const fusedInputs =
+    hasInputSchema &&
+    !authBeforeValidation &&
+    !hasResponseContract &&
+    schema.onValidationError === undefined &&
+    !defaultOnValidationError &&
+    !hasIdempotency &&
+    !hasLedger &&
+    decorationsAssignable &&
+    around === 0
+
   // The idempotency gate lives in the general program, so an idempotent route always runs it.
   const lane: RouteExecutionLane =
     authBeforeValidation || hasIdempotency
       ? "lifecycle"
       : bare
         ? "bare"
-        : bodyOnly
+        : bodyOnly && (noParams || fusedBody)
           ? "body"
           : !hasResponseContract &&
               schema?.body === undefined &&
               schema?.query !== undefined &&
+              noParams &&
               plain &&
               derives === 0 &&
               beforeHandle === 0 &&
@@ -131,10 +152,8 @@ export function selectRouteLanes(options: {
             ? "query"
             : "lifecycle"
 
-  // Lifecycle routes with no params schema are the common middleware shape: derive/before plus an
-  // optional query or body schema. Select their complete validation stage at registration so the
-  // request path never re-checks params/body presence. Parameter-schema routes retain the generic
-  // lifecycle runner until their more involved recovery matrix is selected explicitly.
+  // Select the lifecycle stage shape at registration so the request path never re-checks which input
+  // schemas or hook phases are present.
   const lifecycleLane: LifecycleExecutionLane =
     lane !== "lifecycle" || !plain
       ? undefined
@@ -146,12 +165,8 @@ export function selectRouteLanes(options: {
           ? "query"
           : "hooks"
 
-  // A route whose only lifecycle steps are derive, before and after hooks (any number of each, at least
-  // one) runs them in one fused closure chain, with the route's decorations and error hooks. Anything
-  // that can observe around hooks, a response contract or a validation-error recovery keeps the
-  // generic runner. A params, headers or cookies schema
-  // routes back to the generic lane because the fused builder has no validation step for them, and a
-  // `body` schema is the `body-hooks` lane below because this one does not parse the body.
+  // A route with lifecycle hooks and no validated inputs uses the same compiled hook chain. Input
+  // routes use `fusedInputs` above, including when their hooks run after validation.
   const hookCount = derives + beforeHandle + afterHandle
   const lifecycleHookLane =
     lane === "lifecycle" &&
@@ -164,28 +179,11 @@ export function selectRouteLanes(options: {
     !defaultOnValidationError &&
     plain &&
     schema?.body === undefined &&
-    hookCount > 0 &&
+    (hookCount > 0 || onError > 0) &&
     around === 0
       ? "hooks"
       : undefined
 
-  // The same hooks around a body schema: the fused closure runs parse, validate, derive, before,
-  // handler and after in one function frame, the win `fusedBody` already gives the no-hooks shape.
-  const fusedBodyLifecycle =
-    lane === "lifecycle" &&
-    !authBeforeValidation &&
-    schema?.body !== undefined &&
-    schema?.query === undefined &&
-    plain &&
-    schema?.onValidationError === undefined &&
-    !defaultOnValidationError &&
-    !hasResponseContract &&
-    decorationsAssignable &&
-    !hasIdempotency &&
-    !hasLedger &&
-    hookCount > 0 &&
-    around === 0
-
   return {
     bare,
     fusedQuery,
@@ -202,7 +200,9 @@ export function selectRouteLanes(options: {
             ? "body"
             : bare
               ? "bare"
-              : (lifecycleHookLane ?? (fusedBodyLifecycle ? "body-hooks" : undefined))
+              : fusedInputs
+                ? "inputs"
+                : lifecycleHookLane
         : undefined,
   }
 }

package/src/manifest.ts

@@ -15,6 +15,7 @@ import {
   type RouteSnapshotSchema,
 } from "./diff.ts"
 import { type ProjectEvidenceSnapshot, snapshotProjectEvidence } from "./evidence.ts"
+import { validCapabilityId } from "./internal/capability-runtime.ts"
 import { codeUnitOrder } from "./internal/code-unit-order.ts"
 import { hasControlCharacter } from "./internal/control-character.ts"
 import { sha256Hex } from "./internal/hex.ts"
@@ -368,7 +369,7 @@ export async function parseNifraManifest(
         !Array.isArray(capabilities.unproven) ||
         typeof capabilities.covered !== "boolean" ||
         [...capabilities.declared, ...capabilities.evidenced, ...capabilities.unproven].some(
-          (value) => typeof value !== "string" || !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(value),
+          (value) => typeof value !== "string" || !validCapabilityId(value),
         )
       ) {
         throw new Error(`nifra manifest: ${source} contains invalid capability material`)

package/src/server/body.ts

@@ -10,6 +10,9 @@
 import { jsonError } from "./http.ts"
 import { carryToCopy } from "./request-local.ts"
 
+/** Default request-body cap shared by the full Server and the compact edge server. */
+export const DEFAULT_MAX_BODY_BYTES = 1_000_000
+
 interface BodySource {
   readonly headers: Pick<Headers, "get">
   readonly body: ReadableStream<Uint8Array> | null

package/src/server/core-copies.ts

@@ -26,7 +26,7 @@ if (!copies.includes(here) && copies.push(here) > 1) {
 
 /** This copy's version: a literal like the package root's `VERSION` (no fs on the edge), which
  * `scripts/version.ts` rewrites on every release and `check:publish` asserts. */
-const COPY_VERSION = "5.10.0"
+const COPY_VERSION = "5.12.0"
 
 /** Record this copy's version beside its URL. Called by each `server()` behind the development guard,
  * so a production bundle drops it with the version; a copy that built a server has recorded one. */

package/src/server/idle-timeout.ts

@@ -47,7 +47,7 @@ const longest = (scopes: readonly number[]): number =>
  * ```
  */
 export function withIdleTimeout<T>(
-  c: Context,
+  c: Pick<Context, "signal">,
   seconds: number,
   work: () => MaybePromise<T>,
 ): MaybePromise<T> {
@@ -55,9 +55,7 @@ export function withIdleTimeout<T>(
     throw new RangeError("withIdleTimeout: seconds must be an integer from 0 to 255")
   }
   // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only RequestContext defines this key, with this signature; any other context leaves it undefined.
-  const control = (c as Context & { [CONTEXT_IDLE_TIMEOUT]?: IdleTimeoutControl })[
-    CONTEXT_IDLE_TIMEOUT
-  ]
+  const control = (c as { [CONTEXT_IDLE_TIMEOUT]?: IdleTimeoutControl })[CONTEXT_IDLE_TIMEOUT]
   const signal = c.signal
   if (control === undefined || signal.aborted) return work()
   const set = (value: number | undefined): void => {

package/src/server/json-response.ts

@@ -1,5 +1,214 @@
+import { isRawJson } from "./json-shared.ts"
 import { retried } from "./json-text.ts"
 
+/** A JSON value would exceed the caller's UTF-8 byte budget. */
+export class JsonByteLimitError extends RangeError {
+  constructor() {
+    super("JSON output exceeds the byte limit")
+    this.name = "JsonByteLimitError"
+  }
+}
+
+const OMIT_JSON_VALUE = Symbol("nifra.omitJsonValue")
+
+interface JsonBudget {
+  readonly maxBytes: number
+  usedBytes: number
+}
+
+function addJsonBytes(budget: JsonBudget, bytes: number): void {
+  if (bytes > budget.maxBytes - budget.usedBytes) throw new JsonByteLimitError()
+  budget.usedBytes += bytes
+}
+
+/** Count a quoted JSON string without allocating its escaped representation. */
+function countQuotedJsonString(value: string, budget: JsonBudget): void {
+  addJsonBytes(budget, 2) // opening and closing quotes
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    if (
+      code === 0x22 ||
+      code === 0x5c ||
+      code === 0x08 ||
+      code === 0x09 ||
+      code === 0x0a ||
+      code === 0x0c ||
+      code === 0x0d
+    ) {
+      addJsonBytes(budget, 2)
+    } else if (code < 0x20) {
+      addJsonBytes(budget, 6) // \\u00xx
+    } else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1)
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        addJsonBytes(budget, 4)
+        index++
+      } else {
+        addJsonBytes(budget, 6) // well-formed JSON escapes a lone surrogate
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      addJsonBytes(budget, 6)
+    } else {
+      addJsonBytes(budget, code < 0x80 ? 1 : code < 0x800 ? 2 : 3)
+    }
+  }
+}
+
+/** Count the UTF-8 bytes of an already-encoded JSON fragment. */
+function countRawJsonBytes(value: string, budget: JsonBudget): void {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    const next = value.charCodeAt(index + 1)
+    if (code >= 0xd800 && code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) {
+      addJsonBytes(budget, 4)
+      index++
+    } else addJsonBytes(budget, code < 0x80 ? 1 : code < 0x800 ? 2 : 3)
+  }
+}
+
+function ownJsonValue(value: object, key: string): unknown {
+  const toJSON = Reflect.get(value, "toJSON")
+  return typeof toJSON === "function" ? Reflect.apply(toJSON, value, [key]) : value
+}
+
+function normalizedJsonValue(
+  value: unknown,
+  key: string,
+  budget: JsonBudget,
+  ancestors: Set<object>,
+): unknown | typeof OMIT_JSON_VALUE {
+  if (typeof value === "object" && value !== null && isRawJson?.(value) === true) {
+    const raw = Reflect.get(value, "rawJSON")
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The runtime guard below verifies this optional JSON.rawJSON extension is callable before use.
+    const rawJSON = (JSON as JSON & { readonly rawJSON?: (text: string) => unknown }).rawJSON
+    if (typeof raw !== "string" || typeof rawJSON !== "function")
+      throw new TypeError("Could not serialize JSON.rawJSON")
+    countRawJsonBytes(raw, budget)
+    return rawJSON(raw)
+  }
+  if ((typeof value === "object" && value !== null) || typeof value === "function") {
+    value = ownJsonValue(value, key)
+  } else if (typeof value === "bigint") {
+    const boxed = Object(value)
+    const toJSON = Reflect.get(boxed, "toJSON")
+    if (typeof toJSON === "function") value = Reflect.apply(toJSON, boxed, [key])
+  }
+
+  if (value === null) {
+    addJsonBytes(budget, 4)
+    return null
+  }
+  if (typeof value === "string") {
+    countQuotedJsonString(value, budget)
+    return value
+  }
+  if (typeof value === "boolean") {
+    addJsonBytes(budget, value ? 4 : 5)
+    return value
+  }
+  if (typeof value === "number") {
+    const text = JSON.stringify(value)!
+    addJsonBytes(budget, text.length) // JSON numbers are ASCII.
+    return value
+  }
+  if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol")
+    return OMIT_JSON_VALUE
+  if (typeof value === "bigint") throw new TypeError("Do not know how to serialize a BigInt")
+
+  // JSON.stringify unwraps primitive wrapper objects before writing them.
+  try {
+    return normalizedJsonValue(Number.prototype.valueOf.call(value), key, budget, ancestors)
+  } catch (error) {
+    if (error instanceof JsonByteLimitError) throw error
+  }
+  try {
+    return normalizedJsonValue(String.prototype.valueOf.call(value), key, budget, ancestors)
+  } catch (error) {
+    if (error instanceof JsonByteLimitError) throw error
+  }
+  try {
+    return normalizedJsonValue(Boolean.prototype.valueOf.call(value), key, budget, ancestors)
+  } catch (error) {
+    if (error instanceof JsonByteLimitError) throw error
+  }
+  try {
+    BigInt.prototype.valueOf.call(value)
+  } catch {
+    // Not a boxed BigInt; continue with ordinary object serialization.
+    return normalizeJsonObject(value, budget, ancestors)
+  }
+  throw new TypeError("Do not know how to serialize a BigInt")
+}
+
+function normalizeJsonObject(
+  object: object,
+  budget: JsonBudget,
+  ancestors: Set<object>,
+): unknown | typeof OMIT_JSON_VALUE {
+  if (ancestors.has(object)) throw new TypeError("Converting circular structure to JSON")
+  ancestors.add(object)
+  try {
+    if (Array.isArray(object)) {
+      addJsonBytes(budget, 1) // [
+      const result: unknown[] = Object.setPrototypeOf([], null)
+      const length = object.length
+      for (let index = 0; index < length; index++) {
+        if (index > 0) addJsonBytes(budget, 1)
+        const key = String(index)
+        const item = normalizedJsonValue(Reflect.get(object, key), key, budget, ancestors)
+        if (item === OMIT_JSON_VALUE) {
+          addJsonBytes(budget, 4)
+          result[index] = null
+        } else result[index] = item
+      }
+      addJsonBytes(budget, 1) // ]
+      return result
+    }
+
+    addJsonBytes(budget, 1) // {
+    const result: Record<string, unknown> = Object.create(null)
+    let first = true
+    for (const property of Object.keys(object)) {
+      const item = normalizedJsonValue(Reflect.get(object, property), property, budget, ancestors)
+      if (item === OMIT_JSON_VALUE) continue
+      if (!first) addJsonBytes(budget, 1)
+      countQuotedJsonString(property, budget)
+      addJsonBytes(budget, 1) // :
+      first = false
+      Object.defineProperty(result, property, {
+        configurable: true,
+        enumerable: true,
+        value: item,
+        writable: true,
+      })
+    }
+    addJsonBytes(budget, 1) // }
+    return result
+  } finally {
+    ancestors.delete(object)
+  }
+}
+
+/**
+ * Serialize a JSON value only when its exact UTF-8 size fits `maxBytes`. The preflight snapshots
+ * enumerable values and `toJSON` results while counting, so an oversized output is rejected before
+ * constructing the escaped JSON string or its encoded byte buffer. Returns `undefined` for a root
+ * value with no JSON representation, matching `JSON.stringify`.
+ */
+export function boundedJsonText(
+  value: unknown,
+  maxBytes: number,
+): { readonly text: string; readonly byteLength: number } | undefined {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+    throw new RangeError("maxBytes must be a non-negative safe integer")
+  const budget: JsonBudget = { maxBytes, usedBytes: 0 }
+  const normalized = normalizedJsonValue(value, "", budget, new Set())
+  if (normalized === OMIT_JSON_VALUE) return undefined
+  const text = JSON.stringify(normalized)
+  if (text === undefined) return undefined
+  return { text, byteLength: budget.usedBytes }
+}
+
 /** `Response.json`, with each `bigint` written as its decimal string, as `jsonText` writes it. */
 export function jsonResponse(value: unknown, init?: ResponseInit): Response {
   try {

package/src/server/server-types.ts

@@ -17,7 +17,7 @@ import type {
   ResponseHeadersHook,
 } from "./node-outcome-hook.ts"
 import type { MaybePromise, OnRequestResult } from "./server.ts"
-import type { WebSocketUpgradeOutcome } from "./websocket.ts"
+import type { TopicAdapter, WebSocketUpgradeOutcome } from "./websocket.ts"
 
 /**
  * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
@@ -126,6 +126,12 @@ export interface ServerOptions {
    * the whole message.
    */
   readonly wsMaxPayloadBytes?: number
+  /**
+   * Topic membership and broadcast implementation for WebSocket routes. By default, Nifra uses an
+   * in-process `TopicRegistry`; pass an adapter to bridge subscriptions and publishes to a shared
+   * fan-out service. `app.publish()` returns a promise when the adapter publishes asynchronously.
+   */
+  readonly topicAdapter?: TopicAdapter
   /** 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. */