@nifrajs/core 4.0.2 → 5.1.0

package/src/internal/hook-origins.ts

@@ -0,0 +1,153 @@
+/**
+ * Where each registered hook came from, for `reflectHooks` (`nifra routes --hooks`). Development-only:
+ * every write sits behind the inline `process.env.NODE_ENV !== "production"` guard at its call site in
+ * `server.ts`, so a production define folds the writes away and this module drops out of the bundle.
+ * Reads happen only from reflection, never on the request path.
+ */
+
+export type HookKind =
+  | "onRequest"
+  | "around"
+  | "authenticate"
+  | "derive"
+  | "beforeHandle"
+  | "afterHandle"
+  | "onError"
+  | "onResponse"
+  | "responseHeaders"
+  | "onResponseFinalized"
+
+export interface HookOrigin {
+  readonly kind: HookKind
+  /** The server the hook was registered on. */
+  readonly owner: object
+  /** The plugin being applied when it was registered, if any. */
+  readonly plugin: string | undefined
+  /** A group's static headers turned into this hook at adoption: report the owner's declarations. */
+  readonly statics?: true
+}
+
+/** Which requests an adopted hook still runs for: under a group prefix, or a merged server's routes. */
+export type HookScopeTag =
+  | { readonly inner: unknown; readonly prefix: string }
+  | {
+      readonly inner: unknown
+      readonly routes: readonly { readonly method: string; readonly path: string }[]
+    }
+
+/** One `responseHeaders()` declaration that reached a server's static tier. */
+export interface StaticHeadersTag {
+  readonly owner: object
+  readonly names: readonly string[]
+  readonly source: unknown
+  readonly plugin: string | undefined
+}
+
+export interface AdoptionTag {
+  readonly source: object
+  readonly prefix: string | undefined
+}
+
+const origins = new WeakMap<object, HookOrigin>()
+const scopes = new WeakMap<object, HookScopeTag>()
+const sources = new WeakMap<object, unknown>()
+const statics = new WeakMap<object, StaticHeadersTag[]>()
+const adoptions = new WeakMap<object, AdoptionTag[]>()
+let applying: string | undefined
+// A merged server whose static headers are about to become one of the target's response hooks.
+let staticsOwner: object | undefined
+
+const isRef = (value: unknown): value is object =>
+  (typeof value === "function" || typeof value === "object") && value !== null
+
+/** Record a hook's origin. The first registration wins, so a hook re-adopted elsewhere keeps its site. */
+export function tagHook(hook: unknown, kind: HookKind, owner: object, groupStatics?: true): void {
+  if (!isRef(hook) || origins.has(hook)) return
+  if (kind === "responseHeaders" && staticsOwner !== undefined) {
+    origins.set(hook, { kind, owner: staticsOwner, plugin: applying, statics: true })
+    staticsOwner = undefined
+    return
+  }
+  origins.set(
+    hook,
+    groupStatics === true
+      ? { kind, owner, plugin: applying, statics: true }
+      : { kind, owner, plugin: applying },
+  )
+}
+
+/**
+ * A merge folds the source's static headers into the target: into its static tier, or - once the
+ * target has a response hook - into a new hook, which the next `responseHeaders` tag then is.
+ */
+export function adoptStaticTags(target: object, source: object, becomesHook: boolean): void {
+  if (becomesHook) {
+    staticsOwner = source
+    return
+  }
+  for (const tag of statics.get(source) ?? []) {
+    tagStatic(target, tag.names, tag.source, tag.owner, tag.plugin)
+  }
+}
+
+/** The author's function (or header record) an internal wrapper adapts, for naming it. */
+export function tagSource(wrapper: unknown, source: unknown): void {
+  if (isRef(wrapper)) sources.set(wrapper, source)
+}
+
+/** Pair each scoped wrapper with the hook it gates and the scope it gates it by. */
+export function tagScoped(
+  originals: readonly unknown[],
+  wrapped: readonly unknown[],
+  scope:
+    | { readonly prefix: string }
+    | { readonly routes: readonly { readonly method: string; readonly path: string }[] },
+): void {
+  for (let i = 0; i < wrapped.length; i++) {
+    const wrapper = wrapped[i]
+    if (isRef(wrapper) && wrapper !== originals[i])
+      scopes.set(wrapper, { inner: originals[i], ...scope })
+  }
+}
+
+export function tagStatic(
+  server: object,
+  names: readonly string[],
+  source: unknown,
+  owner: object = server,
+  plugin: string | undefined = applying,
+): void {
+  const list = statics.get(server)
+  const tag = { owner, names: names.map((name) => name.toLowerCase()), source, plugin }
+  if (list === undefined) statics.set(server, [tag])
+  else list.push(tag)
+}
+
+export function tagAdoption(target: object, source: object, prefix: string | undefined): void {
+  const list = adoptions.get(target)
+  const tag = { source, prefix }
+  if (list === undefined) adoptions.set(target, [tag])
+  else list.push(tag)
+}
+
+const outer: (string | undefined)[] = []
+
+/** Mark the plugin a `use()` is applying, until the matching {@link leavePlugin}. */
+export function enterPlugin(name: string | undefined): void {
+  outer.push(applying)
+  if (name !== undefined) applying = name
+}
+
+export function leavePlugin(): void {
+  applying = outer.pop()
+}
+
+export const hookOriginOf = (hook: unknown): HookOrigin | undefined =>
+  isRef(hook) ? origins.get(hook) : undefined
+export const hookScopeOf = (hook: unknown): HookScopeTag | undefined =>
+  isRef(hook) ? scopes.get(hook) : undefined
+export const hookSourceOf = (hook: unknown): unknown =>
+  isRef(hook) ? sources.get(hook) : undefined
+export const staticHeadersOf = (server: object): readonly StaticHeadersTag[] =>
+  statics.get(server) ?? []
+export const adoptionsOf = (server: object): readonly AdoptionTag[] => adoptions.get(server) ?? []

package/src/internal/route-assurance.ts

@@ -1,4 +1,4 @@
-import { METHODS, type Method } from "../router/router.ts"
+import { isRegistrableMethod, METHODS, type Method, type RouteMethod } from "../router/router.ts"
 
 /** Where enforcement evidence follows Nifra's route-registration semantics. */
 export type AssuranceScope = "global" | "subsequent" | "plugin"
@@ -15,8 +15,11 @@ export interface AssuranceEvidence {
 /** Metadata installed on a middleware/plugin by {@link withRouteAssurance}. */
 export interface AssuranceDeclaration extends AssuranceEvidence {
   readonly scope: AssuranceScope
-  /** Restrict evidence to these HTTP methods. Omit for every method. */
-  readonly methods?: readonly Method[]
+  /** Restrict evidence to these HTTP methods, a custom one such as `PURGE` included. Omit for every
+   * method. */
+  readonly methods?: readonly RouteMethod[]
+  /** Withhold evidence from these HTTP methods. Every other method keeps it, custom ones included. */
+  readonly exceptMethods?: readonly RouteMethod[]
   /** Restrict evidence to these absolute route globs. Omit for every path. */
   readonly paths?: readonly string[]
 }
@@ -117,12 +120,8 @@ function normalizeDeclaration(value: AssuranceDeclaration): AssuranceDeclaration
   if (value.scope !== "global" && value.scope !== "subsequent" && value.scope !== "plugin") {
     throw new Error(`route assurance: invalid scope ${JSON.stringify(value.scope)}`)
   }
-  const methods = value.methods?.map((method) => method.toUpperCase())
-  for (const method of methods ?? []) {
-    if (!METHOD_SET.has(method)) {
-      throw new Error(`route assurance: unsupported HTTP method ${JSON.stringify(method)}`)
-    }
-  }
+  const methods = registrableMethods(value.methods)
+  const exceptMethods = registrableMethods(value.exceptMethods)
   const paths = value.paths?.map((path) => {
     routeGlob(path)
     return path
@@ -134,16 +133,31 @@ function normalizeDeclaration(value: AssuranceDeclaration): AssuranceDeclaration
   ) {
     throw new Error(`route assurance: invalid provenance ${JSON.stringify(value.provenance)}`)
   }
-  return Object.freeze({
+  const declaration: { -readonly [K in keyof AssuranceDeclaration]: AssuranceDeclaration[K] } = {
     id: value.id,
     source: value.source.trim(),
     scope: value.scope,
-    // Carried, not defaulted: evidence attached by an author (rather than installed by a running
-    // hook) must stay distinguishable so `requireProvenance: "runtime"` rules can still reject it.
-    ...(value.provenance !== undefined ? { provenance: value.provenance } : {}),
-    ...(methods !== undefined ? { methods: Object.freeze(methods as Method[]) } : {}),
-    ...(paths !== undefined ? { paths: Object.freeze(paths) } : {}),
-  })
+  }
+  // Carried, not defaulted: evidence attached by an author (rather than installed by a running
+  // hook) must stay distinguishable so `requireProvenance: "runtime"` rules can still reject it.
+  if (value.provenance !== undefined) declaration.provenance = value.provenance
+  if (methods !== undefined) declaration.methods = methods
+  if (exceptMethods !== undefined) declaration.exceptMethods = exceptMethods
+  if (paths !== undefined) declaration.paths = Object.freeze(paths)
+  return Object.freeze(declaration)
+}
+
+function registrableMethods(
+  values: readonly string[] | undefined,
+): readonly RouteMethod[] | undefined {
+  if (values === undefined) return undefined
+  const methods = values.map((method) => method.toUpperCase())
+  for (const method of methods) {
+    if (!isRegistrableMethod(method)) {
+      throw new Error(`route assurance: unsupported HTTP method ${JSON.stringify(method)}`)
+    }
+  }
+  return Object.freeze(methods)
 }
 
 /** Validate and freeze declarations, one or many. */
@@ -179,8 +193,8 @@ export function declarationApplies(
   method: string,
   path: string,
 ): boolean {
-  if (declaration.methods !== undefined && !declaration.methods.includes(method as Method))
-    return false
+  if (declaration.methods !== undefined && !declaration.methods.includes(method)) return false
+  if (declaration.exceptMethods?.includes(method) === true) return false
   return (
     declaration.paths === undefined ||
     declaration.paths.some((pattern) => routeGlob(pattern).test(path))

package/src/internal/route-compiler.ts

@@ -35,6 +35,7 @@ import {
   NIFRA_ASSURANCE_IDS,
   validEvidenceId,
 } from "./route-assurance.ts"
+import type { CatalogRoute } from "./route-catalog.ts"
 import type {
   RawAfterHandle,
   RawAround,
@@ -43,7 +44,9 @@ import type {
   RawDerive,
   RawErrorHandler,
 } from "./route-execution.ts"
+import { compileRouteExecutionPlan } from "./route-execution.ts"
 import { type RouteLaneSelection, selectRouteLanes } from "./route-lanes.ts"
+import { compileRouteProgram } from "./route-program.ts"
 
 export interface RouteCompilerContext {
   readonly maxBodyBytes: number
@@ -83,6 +86,108 @@ export interface CompiledRouteOptions {
   readonly authenticated: boolean
 }
 
+const RESPONSE_CONTRACT_EVIDENCE: AssuranceDeclaration = Object.freeze({
+  id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
+  source: "response-contract",
+  scope: "plugin",
+})
+
+function responseDefinitionOf(
+  schema: RouteSchema | undefined,
+): ResponseContractDefinition | undefined {
+  return schema?.response !== undefined || schema?.errors !== undefined
+    ? {
+        ...(schema.response === undefined ? {} : { response: schema.response }),
+        ...(schema.errors === undefined ? {} : { errors: schema.errors }),
+      }
+    : undefined
+}
+
+/**
+ * Recompile a route another server compiled, under the response contract and effect ledger the
+ * adopting server installed and the route's own server did not. Both only add a check or a record,
+ * so a merged route can never serve more than it did standalone - and without this, the same
+ * `.use()` covered a `group()` route but not a `merge()`d one. A route that already resolved its
+ * own contract or ledger keeps it.
+ */
+export function adoptRouteRuntimes(
+  route: CatalogRoute,
+  responseContractRuntime: ResponseContractRuntime | undefined,
+  effectLedgerRuntime: EffectLedgerRuntime | undefined,
+): CatalogRoute {
+  const { entry, descriptor } = route
+  const definition =
+    entry.responseContract === undefined && responseContractRuntime !== undefined
+      ? responseDefinitionOf(entry.schema)
+      : undefined
+  const ledgered =
+    entry.ledgered ??
+    effectLedgerRuntime?.resolve(descriptor.capabilities ?? [], route.method, route.path)
+  if (definition === undefined && ledgered === entry.ledgered) return route
+  const responseContract =
+    definition === undefined || responseContractRuntime === undefined
+      ? entry.responseContract
+      : { runtime: responseContractRuntime, definition }
+  // Either runtime rules out every fused lane, so the route needs only the generic plan here - and
+  // nothing the source server's validation-error default decided about fusion can matter any more.
+  const lanes = selectRouteLanes({
+    schema: entry.schema,
+    hasAuth: entry.authStages.length > 0,
+    hasIdempotency: entry.idempotent !== undefined,
+    hasLedger: ledgered !== undefined,
+    hasResponseContract: responseContract !== undefined,
+    hasDecorations: entry.hasDecorations,
+    derives: entry.derives.length,
+    beforeHandle: entry.beforeHandle.length,
+    afterHandle: entry.afterHandle.length,
+    onError: entry.onError.length,
+    around: entry.around.length,
+    defaultOnValidationError: false,
+  })
+  const program = compileRouteProgram({
+    schema: entry.schema,
+    handler: entry.handler,
+    derives: entry.derives,
+    authStages: entry.authStages,
+    beforeHandle: entry.beforeHandle,
+    afterHandle: entry.afterHandle,
+    onError: entry.onError,
+    decorations: entry.decorations,
+    hasDecorations: entry.hasDecorations,
+    bodySchema: entry.schema?.body,
+    bodyLimit: entry.bodyLimit,
+    responseContract,
+  })
+  const execution = compileRouteExecutionPlan({
+    lane: lanes.lane,
+    contextless: false,
+    hasAround: entry.around.length > 0,
+    hasLedger: ledgered !== undefined,
+    fusedWeb: undefined,
+    fusedBody: undefined,
+    fusedLane: undefined,
+  })
+  const enforced = definition !== undefined && responseContractRuntime?.mode === "enforce"
+  return {
+    ...route,
+    entry: {
+      ...entry,
+      ledgered,
+      responseContract,
+      lifecycleHookLane: undefined,
+      execution,
+      program,
+    },
+    descriptor:
+      definition === undefined || responseContractRuntime === undefined
+        ? descriptor
+        : { ...descriptor, responseContract: responseContractRuntime.mode },
+    assurance: enforced
+      ? Object.freeze([...route.assurance, RESPONSE_CONTRACT_EVIDENCE])
+      : route.assurance,
+  }
+}
+
 /** Resolve all registration-time policy and lane facts for one route. */
 export function compileRouteOptions(
   context: RouteCompilerContext,
@@ -181,13 +286,7 @@ export function compileRouteOptions(
     context.maxBodyBytes,
   )
   const ledgered = context.effectLedgerRuntime?.resolve(capabilities, method, path)
-  const responseDefinition =
-    schema?.response !== undefined || schema?.errors !== undefined
-      ? {
-          ...(schema.response === undefined ? {} : { response: schema.response }),
-          ...(schema.errors === undefined ? {} : { errors: schema.errors }),
-        }
-      : undefined
+  const responseDefinition = responseDefinitionOf(schema)
   const contracted =
     context.responseContractRuntime !== undefined && responseDefinition !== undefined
       ? { runtime: context.responseContractRuntime, definition: responseDefinition }
@@ -208,15 +307,7 @@ export function compileRouteOptions(
   })
 
   const routeAssurance: AssuranceDeclaration[] = [...context.activeAssurance, ...handlerAssurance]
-  if (contracted?.runtime.mode === "enforce") {
-    routeAssurance.push(
-      Object.freeze({
-        id: NIFRA_ASSURANCE_IDS.RESPONSE_CONTRACT,
-        source: "response-contract",
-        scope: "plugin",
-      }),
-    )
-  }
+  if (contracted?.runtime.mode === "enforce") routeAssurance.push(RESPONSE_CONTRACT_EVIDENCE)
   for (const id of schema?.assurance ?? []) {
     if (!validEvidenceId(id)) {
       throw new Error(