@nifrajs/core 2.14.1 → 3.2.0

package/src/internal/route-compiler.ts

@@ -0,0 +1,234 @@
+/**
+ * Registration-time route compilation.
+ *
+ * This module owns the policy decisions that turn a route declaration into the immutable facts the
+ * execution-plan builder and the route catalog consume. It deliberately runs only from `Server.register`
+ * and `Server.registerBatch`; no function here is reachable from the request path.
+ *
+ * The public Server remains the fluent registration surface. This module is the deep implementation seam
+ * behind that surface: body limits, capability and assurance evidence, optional runtimes, decorations, and
+ * lane selection are resolved once, together, so adding a new route policy does not require editing the
+ * kernel's dispatch code.
+ */
+import type { EffectLifecycleObserver } from "../effect-lifecycle.ts"
+import { RouteConfigError } from "../errors.ts"
+import { type CompiledRoutePattern, compileRoutePattern } from "../router/pattern.ts"
+import type { Method } from "../router/router.ts"
+import type { StandardSchemaV1 } from "../schema/standard.ts"
+import { assertByteLimit } from "../server/body.ts"
+import type { RouteSchema } from "../server/context.ts"
+import type { IdempotencyRuntime, ResolvedIdempotency } from "../server/idempotency-lane.ts"
+import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger-lane.ts"
+import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
+import {
+  CAPABILITY_GUARD,
+  type CapabilityUseEvent,
+  createCapabilityGuard,
+  normalizeRouteCapabilities,
+  type RegisteredCapabilityInterceptor,
+} from "./capability-runtime.ts"
+import {
+  type AssuranceDeclaration,
+  assuranceDeclarationsOf,
+  assuranceEvidenceFor,
+  NIFRA_ASSURANCE_IDS,
+  validEvidenceId,
+} from "./route-assurance.ts"
+import type {
+  RawAfterHandle,
+  RawAround,
+  RawBeforeHandle,
+  RawDerive,
+  RawErrorHandler,
+} from "./route-execution.ts"
+import { type RouteLaneSelection, selectRouteLanes } from "./route-lanes.ts"
+
+export interface RouteCompilerContext {
+  readonly maxBodyBytes: number
+  readonly activeAssurance: readonly AssuranceDeclaration[]
+  readonly globalAssurance: readonly AssuranceDeclaration[]
+  readonly decorations: Record<string, unknown>
+  readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
+  readonly capabilityInterceptors: readonly RegisteredCapabilityInterceptor[]
+  readonly capabilityObservers: readonly EffectLifecycleObserver[]
+  readonly effectLedgerRuntime: EffectLedgerRuntime | undefined
+  readonly idempotencyRuntime: IdempotencyRuntime | undefined
+  readonly responseContractRuntime: ResponseContractRuntime | undefined
+  readonly derives: readonly RawDerive[]
+  readonly beforeHandleHooks: readonly RawBeforeHandle[]
+  readonly afterHandleHooks: readonly RawAfterHandle[]
+  readonly onErrorHooks: readonly RawErrorHandler[]
+  readonly aroundHooks: readonly RawAround[]
+  readonly defaultOnValidationError: RouteSchema["onValidationError"] | undefined
+}
+
+export interface CompiledRouteOptions {
+  readonly pattern: CompiledRoutePattern
+  readonly bodyLimit: number | undefined
+  readonly capabilities: readonly string[]
+  readonly handlerAssurance: readonly AssuranceDeclaration[]
+  readonly routeDecorations: Record<PropertyKey, unknown>
+  readonly hasDecorations: boolean
+  readonly idempotent: ResolvedIdempotency | undefined
+  readonly ledgered: ResolvedEffectLedger | undefined
+  readonly responseContract:
+    | { readonly runtime: ResponseContractRuntime; readonly schema: StandardSchemaV1 }
+    | undefined
+  readonly lanes: RouteLaneSelection
+  readonly routeAssurance: readonly AssuranceDeclaration[]
+}
+
+/** Resolve all registration-time policy and lane facts for one route. */
+export function compileRouteOptions(
+  context: RouteCompilerContext,
+  method: Method,
+  path: string,
+  schema: RouteSchema | undefined,
+  handler: (context: never) => unknown,
+): CompiledRouteOptions {
+  const pattern = compileRoutePattern(path)
+  let bodyLimit: number | undefined = context.maxBodyBytes
+  const invalidBodyLimit = (message: string): never => {
+    throw new RouteConfigError("INVALID_BODY_LIMIT", `route ${method} ${path}: ${message}`)
+  }
+  if (schema?.bodyLimitReason !== undefined && schema.bodyLimit !== "unlimited") {
+    invalidBodyLimit('bodyLimitReason is only valid with bodyLimit: "unlimited"')
+  }
+  if (schema?.bodyLimit === "unlimited") {
+    if (typeof schema.bodyLimitReason !== "string" || schema.bodyLimitReason.trim().length === 0) {
+      invalidBodyLimit('bodyLimit: "unlimited" requires a non-empty bodyLimitReason')
+    }
+    if (schema.body !== undefined) {
+      invalidBodyLimit('bodyLimit: "unlimited" cannot be used with a body schema; use a finite cap')
+    }
+    if (schema.idempotency !== undefined) {
+      invalidBodyLimit('bodyLimit: "unlimited" cannot be used with idempotency')
+    }
+    bodyLimit = undefined
+  } else if (schema?.bodyLimit !== undefined) {
+    try {
+      assertByteLimit(schema.bodyLimit, "route bodyLimit")
+    } catch {
+      invalidBodyLimit('bodyLimit must be a non-negative safe integer or "unlimited"')
+    }
+    bodyLimit = schema.bodyLimit
+  }
+
+  const capabilities = normalizeRouteCapabilities(schema?.capabilities)
+  const handlerAssurance = assuranceDeclarationsOf(handler as unknown as object)
+  const invalidHandlerScope = handlerAssurance.find((declaration) => declaration.scope !== "plugin")
+  if (invalidHandlerScope !== undefined) {
+    throw new RouteConfigError(
+      "INVALID_ASSURANCE",
+      `route handler assurance must use plugin scope (received ${invalidHandlerScope.scope})`,
+    )
+  }
+
+  const authenticated = assuranceEvidenceFor(
+    [...context.activeAssurance, ...handlerAssurance, ...context.globalAssurance],
+    method,
+    path,
+  ).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
+  const routeDecorations: Record<PropertyKey, unknown> = { ...context.decorations }
+  if (capabilities.length > 0) {
+    routeDecorations[CAPABILITY_GUARD] = createCapabilityGuard(
+      capabilities,
+      method,
+      path,
+      context.onCapabilityUse,
+      context.idempotencyRuntime?.trackEffect,
+      Object.freeze([...context.capabilityInterceptors]),
+      Object.freeze([...context.capabilityObservers]),
+    )
+  }
+  const hasDecorations = Reflect.ownKeys(routeDecorations).length > 0
+
+  if (schema?.idempotency !== undefined && context.idempotencyRuntime === undefined) {
+    throw new RouteConfigError(
+      "INVALID_IDEMPOTENCY",
+      "route declares idempotency but the idempotency plugin is not installed; add .use(idempotency())",
+    )
+  }
+  const idempotent = context.idempotencyRuntime?.resolve(
+    schema,
+    authenticated,
+    context.maxBodyBytes,
+  )
+  const ledgered = context.effectLedgerRuntime?.resolve(capabilities, method, path)
+  const contracted =
+    context.responseContractRuntime !== undefined && schema?.response !== undefined
+      ? { runtime: context.responseContractRuntime, schema: schema.response }
+      : undefined
+  const lanes = selectRouteLanes({
+    schema,
+    hasIdempotency: idempotent !== undefined,
+    hasLedger: ledgered !== undefined,
+    hasResponseContract: contracted !== undefined,
+    hasDecorations,
+    derives: context.derives.length,
+    beforeHandle: context.beforeHandleHooks.length,
+    afterHandle: context.afterHandleHooks.length,
+    onError: context.onErrorHooks.length,
+    around: context.aroundHooks.length,
+    defaultOnValidationError: context.defaultOnValidationError !== undefined,
+  })
+
+  const routeAssurance: AssuranceDeclaration[] = [...context.activeAssurance, ...handlerAssurance]
+  if (contracted?.runtime.mode === "enforce" && schema?.response !== undefined) {
+    routeAssurance.push(
+      Object.freeze({
+        id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
+        source: "response-contract",
+        scope: "plugin",
+      }),
+    )
+  }
+  for (const id of schema?.assurance ?? []) {
+    if (!validEvidenceId(id)) {
+      throw new Error(
+        `route assurance: invalid evidence id ${JSON.stringify(id)} on ${method} ${path} (use lowercase dot/dash segments)`,
+      )
+    }
+    const declared = { id, source: "declared", scope: "plugin" } as AssuranceDeclaration
+    Object.defineProperty(declared, "provenance", {
+      value: "declared",
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    })
+    routeAssurance.push(Object.freeze(declared))
+  }
+  const unlimitedBody = schema?.bodyLimit === "unlimited"
+  if (!unlimitedBody && (schema?.body !== undefined || typeof schema?.bodyLimit === "number")) {
+    routeAssurance.push(
+      Object.freeze({
+        id: NIFRA_ASSURANCE_IDS.BODY_BOUNDED,
+        source: "route-schema",
+        scope: "plugin",
+      }),
+    )
+  }
+  if (schema?.idempotency !== undefined) {
+    routeAssurance.push(
+      Object.freeze({
+        id: NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY,
+        source: "route-schema",
+        scope: "plugin",
+      }),
+    )
+  }
+
+  return {
+    pattern,
+    bodyLimit,
+    capabilities,
+    handlerAssurance,
+    routeDecorations,
+    hasDecorations,
+    idempotent,
+    ledgered,
+    responseContract: contracted,
+    lanes,
+    routeAssurance: Object.freeze(routeAssurance),
+  }
+}

package/src/internal/route-execution.ts

@@ -19,6 +19,7 @@
 import type { RequestBudget } from "../budget.ts"
 import type { RequestLedger } from "../ledger.ts"
 import type { StandardSchemaV1 } from "../schema/standard.ts"
+import { UNLIMITED_BODY_BYTES } from "../server/body.ts"
 import type { Platform, RouteSchema } from "../server/context.ts"
 import type { ResolvedIdempotency } from "../server/idempotency-lane.ts"
 import type { EffectLedgerRuntime, ResolvedEffectLedger } from "../server/ledger-lane.ts"
@@ -26,8 +27,9 @@ import type { ProtoPoisoning } from "../server/proto-guard.ts"
 import type { Registry } from "../server/registry.ts"
 import { RequestContext } from "../server/request-context.ts"
 import type { ResponseContractRuntime } from "../server/response-contract-lane.ts"
-import type { HandlerResult } from "../server/runtime-core.ts"
+import type { HandlerResult, ResponseResult } from "../server/runtime-core.ts"
 import type { CtxSet, MaybePromise, RawContext, RequestSource, Server } from "../server/server.ts"
+import type { RouteProgram } from "./route-program.ts"
 
 export type InternalHandler = (ctx: RawContext) => MaybePromise<HandlerResult>
 
@@ -49,7 +51,7 @@ export type RouteExecutionRunner = <T, R extends Registry, Ctx>(
   platform: Platform | undefined,
   nativeContext: boolean,
   finalize: (result: unknown, set: CtxSet) => T,
-  wrapResponse: (response: Response) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
 ) => MaybePromise<T>
 
 export type ContextRouteRunner = <T, R extends Registry, Ctx>(
@@ -58,7 +60,7 @@ export type ContextRouteRunner = <T, R extends Registry, Ctx>(
   source: RequestSource,
   ctx: RawContext,
   finalize: (result: unknown, set: CtxSet) => T,
-  wrapResponse: (response: Response) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
 ) => MaybePromise<T>
 
 /** The kernel's private execution surface, mirrored structurally. The runner methods are private on
@@ -76,66 +78,40 @@ interface RouteExecutionRuntime {
     budget: RequestBudget,
     platform: Platform | undefined,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runBare<T>(
     entry: RouteEntry,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runBodyOnly<T>(
     entry: RouteEntry,
     source: RequestSource,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runQueryOnly<T>(
     entry: RouteEntry,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
-  runLifecycleHooks<T>(
-    entry: RouteEntry,
-    ctx: RawContext,
-    finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
-  ): MaybePromise<T>
-  runLifecycleQuery<T>(
-    entry: RouteEntry,
-    ctx: RawContext,
-    finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
-  ): MaybePromise<T>
-  runLifecycleBody<T>(
+  runProgram<T>(
     entry: RouteEntry,
     source: RequestSource,
     ctx: RawContext,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
-  ): MaybePromise<T>
-  runLifecycleBodyQuery<T>(
-    entry: RouteEntry,
-    source: RequestSource,
-    ctx: RawContext,
-    finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
-  ): MaybePromise<T>
-  runLifecycle<T>(
-    entry: RouteEntry,
-    source: RequestSource,
-    ctx: RawContext,
-    finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   runWithAround<T>(
     entry: RouteEntry,
     ctx: RawContext,
     run: () => MaybePromise<T>,
     finalize: (result: unknown, set: CtxSet) => T,
-    wrapResponse: (response: Response) => T,
+    wrapResponse: (response: Response | ResponseResult) => T,
   ): MaybePromise<T>
   readonly maxBodyBytes: number
   readonly protoPoisoning: ProtoPoisoning
@@ -157,13 +133,19 @@ export function compileRouteExecutionPlan(options: {
   readonly contextless: boolean
   readonly hasAround: boolean
   readonly hasLedger: boolean
-  readonly lifecycleLane: LifecycleExecutionLane
   readonly fusedWeb: FusedWebRunner | undefined
   readonly fusedBody: FusedBodyRunner | undefined
-  readonly fusedLane: "bare" | "body" | "query" | undefined
+  readonly fusedLane:
+    | "bare"
+    | "body"
+    | "query"
+    | "derive-before"
+    | "derive-before-after"
+    | "body-derive-before"
+    | "body-derive-before-after"
+    | undefined
 }): RouteExecutionPlan {
-  const { lane, contextless, hasAround, hasLedger, lifecycleLane, fusedWeb, fusedBody, fusedLane } =
-    options
+  const { lane, contextless, hasAround, hasLedger, fusedWeb, fusedBody, fusedLane } = options
 
   if (contextless) {
     const run: RouteExecutionRunner = (
@@ -190,7 +172,7 @@ export function compileRouteExecutionPlan(options: {
         finalize,
         wrapResponse,
       )
-    return Object.freeze({ run, fusedWeb, fusedBody, fusedLane })
+    return Object.freeze({ run, fusedWeb, fusedBody, fusedLane }) as RouteExecutionPlan
   }
 
   let inner: ContextRouteRunner
@@ -219,55 +201,14 @@ export function compileRouteExecutionPlan(options: {
         )
       break
     default:
-      switch (lifecycleLane) {
-        case "hooks":
-          inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
-            (runtime as unknown as RouteExecutionRuntime).runLifecycleHooks(
-              entry,
-              ctx,
-              finalize,
-              wrapResponse,
-            )
-          break
-        case "query":
-          inner = (runtime, entry, _source, ctx, finalize, wrapResponse) =>
-            (runtime as unknown as RouteExecutionRuntime).runLifecycleQuery(
-              entry,
-              ctx,
-              finalize,
-              wrapResponse,
-            )
-          break
-        case "body":
-          inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
-            (runtime as unknown as RouteExecutionRuntime).runLifecycleBody(
-              entry,
-              source,
-              ctx,
-              finalize,
-              wrapResponse,
-            )
-          break
-        case "body-query":
-          inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
-            (runtime as unknown as RouteExecutionRuntime).runLifecycleBodyQuery(
-              entry,
-              source,
-              ctx,
-              finalize,
-              wrapResponse,
-            )
-          break
-        default:
-          inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
-            (runtime as unknown as RouteExecutionRuntime).runLifecycle(
-              entry,
-              source,
-              ctx,
-              finalize,
-              wrapResponse,
-            )
-      }
+      inner = (runtime, entry, source, ctx, finalize, wrapResponse) =>
+        (runtime as unknown as RouteExecutionRuntime).runProgram(
+          entry,
+          source,
+          ctx,
+          finalize,
+          wrapResponse,
+        )
   }
 
   const execute: ContextRouteRunner = hasAround
@@ -295,7 +236,7 @@ export function compileRouteExecutionPlan(options: {
     wrapResponse,
   ) => {
     const server = runtime as unknown as RouteExecutionRuntime
-    const maxBodyBytes = entry.bodyLimit ?? server.maxBodyBytes
+    const maxBodyBytes = entry.bodyLimit ?? UNLIMITED_BODY_BYTES
     const ctx = nativeContext
       ? RequestContext.native(source, params, search, maxBodyBytes, platform, server.protoPoisoning)
       : new RequestContext(
@@ -328,7 +269,7 @@ export function compileRouteExecutionPlan(options: {
     }
     return outcome
   }
-  return Object.freeze({ run, fusedWeb, fusedBody, fusedLane })
+  return Object.freeze({ run, fusedWeb, fusedBody, fusedLane }) as RouteExecutionPlan
 }
 
 /** Registration-compiled route behavior. Every adapter invokes the same runner; the optional fused
@@ -340,13 +281,27 @@ export interface RouteExecutionPlan {
   /** Which builder produced {@link fusedWeb} - a merge rebinds the closure to the executing server
    * and must rebuild it with the SAME semantics (a query-fused route rebuilt as bare would skip its
    * validation). `undefined` iff `fusedWeb` is. */
-  readonly fusedLane: "bare" | "body" | "query" | undefined
+  readonly fusedLane:
+    | "bare"
+    | "body"
+    | "query"
+    | "derive-before"
+    | "derive-before-after"
+    | "body-derive-before"
+    | "body-derive-before-after"
+    | undefined
 }
 
 export interface RouteEntry {
   readonly handler: InternalHandler
   readonly schema: RouteSchema | undefined
-  /** Effective transport body cap; `undefined` is an explicit streaming/upload exemption. */
+  /**
+   * Effective transport body cap, already resolved at registration: the route's own
+   * `schema.bodyLimit` when it declared one, the server's `maxBodyBytes` otherwise. `undefined` is
+   * an explicit streaming/upload exemption (`bodyLimit: "unlimited"`) and means NO cap - readers
+   * must fall back to {@link UNLIMITED_BODY_BYTES}, never to the server default, which would be a
+   * tighter bound than the route asked for.
+   */
   readonly bodyLimit: number | undefined
   /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
   readonly idempotent: ResolvedIdempotency | undefined
@@ -370,11 +325,13 @@ export interface RouteEntry {
   readonly afterHandle: ReadonlyArray<RawAfterHandle>
   readonly onError: ReadonlyArray<RawErrorHandler>
   /** Registration-specialized hook shape for the common derive + before middleware route. */
-  readonly lifecycleHookLane: "derive-before" | undefined
+  readonly lifecycleHookLane: "derive-before" | "derive-before-after" | undefined
   /** Wraps the matched route lifecycle. Empty for the common no-around path. */
   readonly around: ReadonlyArray<RawAround>
   /** The single immutable execution decision consumed by portable, Node-direct, and Bun-native paths. */
   readonly execution: RouteExecutionPlan
+  /** One immutable general lifecycle program compiled at registration. */
+  readonly program: RouteProgram
 }
 
 /** The fused Web lane: same inputs `routeAndRun` would hand the generic path, a `Response` out. */
@@ -399,5 +356,5 @@ export type FusedBodyRunner = <T>(
   platform: Platform | undefined,
   nativeContext: boolean,
   finalize: (result: unknown, set: CtxSet, ctx: RawContext) => T,
-  wrapResponse: (response: Response) => T,
+  wrapResponse: (response: Response | ResponseResult) => T,
 ) => MaybePromise<T>