@nifrajs/core 1.12.0 → 1.13.0

package/src/router/pattern.ts

@@ -0,0 +1,176 @@
+import { RouteConfigError } from "../errors.ts"
+
+const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
+const RESERVED_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"])
+const COMPILED_ROUTE_PATTERN: unique symbol = Symbol("nifra.compiled-route-pattern")
+
+export type RoutePatternSegment =
+  | { readonly kind: "static"; readonly value: string }
+  | { readonly kind: "param"; readonly name: string }
+  | { readonly kind: "wildcard"; readonly name: string }
+
+/**
+ * Compiled route grammar shared by runtime routers, browser navigation, mocks, and adapters.
+ *
+ * The result, its two arrays, and every segment are frozen because consumers share one instance. In
+ * particular, a segment must not diverge from the lazily cached regex after first match. The measured
+ * sub-microsecond cost per route is paid only at registration and preserves that runtime invariant.
+ */
+export interface CompiledRoutePattern {
+  readonly [COMPILED_ROUTE_PATTERN]: true
+  readonly pattern: string
+  readonly segments: readonly RoutePatternSegment[]
+  readonly paramNames: readonly string[]
+}
+
+export type RoutePatternMatch =
+  | { readonly matched: true; readonly params: Record<string, string> }
+  | { readonly matched: false; readonly reason: "not-found" | "malformed" }
+
+/**
+ * Regex per compiled pattern, derived on first use. The core trie matches by descending segments and
+ * never asks for one, so building it during {@link compileRoutePattern} would charge every server's
+ * boot for the browser/mock adapters alone. Keyed by the frozen pattern, so the cache dies with it.
+ */
+const REGEX_CACHE = new WeakMap<CompiledRoutePattern, RegExp>()
+
+function regexOf(compiled: CompiledRoutePattern): RegExp {
+  let regex = REGEX_CACHE.get(compiled)
+  if (regex === undefined) {
+    if (compiled[COMPILED_ROUTE_PATTERN] !== true) {
+      throw new TypeError("route pattern was not produced by compileRoutePattern()")
+    }
+    const parts = compiled.segments.map((segment) =>
+      segment.kind === "static"
+        ? escapeRegex(segment.value)
+        : segment.kind === "param"
+          ? "([^/]+)"
+          : "(.+)",
+    )
+    regex = new RegExp(parts.length === 0 ? "^/$" : `^/${parts.join("/")}$`)
+    REGEX_CACHE.set(compiled, regex)
+  }
+  return regex
+}
+
+function validParamName(name: string): boolean {
+  return PARAM_NAME.test(name) && !RESERVED_PARAM_NAMES.has(name)
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^()|[\]\\{}$]/g, "\\$&")
+}
+
+/** Parse and validate Nifra's strict route grammar once. Trailing slashes remain significant. */
+export function compileRoutePattern(pattern: string): CompiledRoutePattern {
+  if (pattern.length === 0 || pattern.charCodeAt(0) !== 47 /* / */) {
+    throw new RouteConfigError("INVALID_PATH", `path must start with "/": "${pattern}"`)
+  }
+  const raw = pattern === "/" ? [] : pattern.slice(1).split("/")
+  const segments: RoutePatternSegment[] = []
+  const paramNames: string[] = []
+  for (let i = 0; i < raw.length; i++) {
+    const value = raw[i]!
+    if (value.charCodeAt(0) === 58 /* : */) {
+      const name = value.slice(1)
+      if (!validParamName(name)) {
+        throw new RouteConfigError(
+          "INVALID_PARAM_NAME",
+          `invalid parameter ":${name}" in "${pattern}"`,
+        )
+      }
+      if (paramNames.includes(name)) {
+        throw new RouteConfigError(
+          "DUPLICATE_PARAM",
+          `duplicate parameter ":${name}" in "${pattern}"`,
+        )
+      }
+      paramNames.push(name)
+      segments.push(Object.freeze({ kind: "param", name }))
+      continue
+    }
+    if (value.charCodeAt(0) === 42 /* * */) {
+      if (i !== raw.length - 1) {
+        throw new RouteConfigError(
+          "WILDCARD_NOT_LAST",
+          `wildcard must be the final segment in "${pattern}"`,
+        )
+      }
+      const name = value.length === 1 ? "*" : value.slice(1)
+      if (name !== "*" && !validParamName(name)) {
+        throw new RouteConfigError(
+          "INVALID_PARAM_NAME",
+          `invalid wildcard "*${name}" in "${pattern}"`,
+        )
+      }
+      if (paramNames.includes(name)) {
+        throw new RouteConfigError(
+          "DUPLICATE_PARAM",
+          `duplicate parameter "${name}" in "${pattern}"`,
+        )
+      }
+      paramNames.push(name)
+      segments.push(Object.freeze({ kind: "wildcard", name }))
+      continue
+    }
+    segments.push(Object.freeze({ kind: "static", value }))
+  }
+  const compiled = Object.freeze({
+    [COMPILED_ROUTE_PATTERN]: true,
+    pattern,
+    segments: Object.freeze(segments),
+    paramNames: Object.freeze(paramNames),
+  }) as CompiledRoutePattern
+  return compiled
+}
+
+/** Core precedence: static > param > wildcard at the first differing segment, independent of order. */
+export function compareRoutePatternSpecificity(
+  left: CompiledRoutePattern,
+  right: CompiledRoutePattern,
+): number {
+  const length = Math.max(left.segments.length, right.segments.length)
+  for (let i = 0; i < length; i++) {
+    const a = left.segments[i]
+    const b = right.segments[i]
+    if (a === undefined || b === undefined) return b === undefined ? -1 : 1
+    const aWeight = a.kind === "static" ? 3 : a.kind === "param" ? 2 : 1
+    const bWeight = b.kind === "static" ? 3 : b.kind === "param" ? 2 : 1
+    if (aWeight !== bWeight) return bWeight - aWeight
+  }
+  return 0
+}
+
+/** Decode router captures under one rule. Plain values take the zero-allocation path; malformed
+ * escapes return `null`, allowing HTTP to emit 400 while client navigation declines the match. */
+export function decodeRouteParams(raw: Record<string, string>): Record<string, string> | null {
+  let out: Record<string, string> | undefined
+  for (const key in raw) {
+    const value = raw[key]!
+    if (!value.includes("%")) continue
+    try {
+      out ??= { ...raw }
+      out[key] = decodeURIComponent(value)
+    } catch {
+      return null
+    }
+  }
+  return out ?? raw
+}
+
+/** Match one compiled pattern and return decoded captures. The caller decides cross-pattern order. */
+export function matchRoutePattern(
+  compiled: CompiledRoutePattern,
+  pathname: string,
+): RoutePatternMatch {
+  const match = regexOf(compiled).exec(pathname)
+  if (match === null) return { matched: false, reason: "not-found" }
+  const params: Record<string, string> = {}
+  for (let i = 0; i < compiled.paramNames.length; i++) {
+    params[compiled.paramNames[i]!] = match[i + 1] ?? ""
+  }
+  const decoded = decodeRouteParams(params)
+  return decoded === null
+    ? { matched: false, reason: "malformed" }
+    : { matched: true, params: decoded }
+}

package/src/router/router.ts

@@ -1,4 +1,5 @@
 import { RouteConfigError } from "../errors.ts"
+import { type CompiledRoutePattern, compileRoutePattern } from "./pattern.ts"
 
 /** HTTP methods the router accepts. */
 export const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] as const
@@ -11,24 +12,7 @@ function isMethod(value: string): value is Method {
   return METHOD_SET.has(value)
 }
 
-/** Parameter names must be valid identifiers — mirrors the global identifier rule. */
-const PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
-
-/** Object-prototype keys are rejected as param names: a route like `/:__proto__` could let a captured
- * value reach a prototype-polluting key. Param *names* come from the route pattern (never from request
- * input) and are validated here at registration, so a reserved key can never reach `buildParams` —
- * this boot-time guard is the whole protection. The runtime params object stays a plain `{}` (only
- * user-controlled *values* land in it, under these validated keys), keeping the param path
- * allocation-cheap; a null-prototype object would add cost for no added safety. */
-const RESERVED_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"])
-
-/** A param name is valid when it's an identifier AND not a reserved object-prototype key. */
-const validParamName = (name: string): boolean =>
-  PARAM_NAME.test(name) && !RESERVED_PARAM_NAMES.has(name)
-
 const SLASH = 47
-const COLON = 58
-const STAR = 42
 export const EMPTY_PARAMS: Record<string, string> = Object.freeze({})
 const DYNAMIC_MATCH_CACHE_MAX = 2048
 
@@ -245,7 +229,7 @@ export class Router<T> {
    * (boot-time, L2) on a duplicate route, a malformed pattern, or conflicting
    * parameter names for the same path shape.
    */
-  add(method: Method, path: string, payload: T): void {
+  add(method: Method, pattern: string | CompiledRoutePattern, payload: T): void {
     DYNAMIC_MATCH_CACHES.delete(this)
     const upper = method.toUpperCase()
     // The `Method` parameter type is the compile-time guard; this re-checks at
@@ -253,66 +237,24 @@ export class Router<T> {
     if (!isMethod(upper)) {
       throw new RouteConfigError("INVALID_METHOD", `unsupported HTTP method "${method}"`)
     }
-    if (path.length === 0 || path.charCodeAt(0) !== SLASH) {
-      throw new RouteConfigError("INVALID_PATH", `path must start with "/": "${path}"`)
-    }
-
-    const segments = path === "/" ? [] : path.slice(1).split("/")
-    const paramNames: string[] = []
-    let isStatic = true
+    const compiled = typeof pattern === "string" ? compileRoutePattern(pattern) : pattern
+    const path = compiled.pattern
+    const paramNames = compiled.paramNames
+    const isStatic = paramNames.length === 0
     let node = this.root
 
-    for (let i = 0; i < segments.length; i++) {
-      const seg = segments[i]!
-      const marker = seg.charCodeAt(0)
-
-      if (marker === COLON) {
-        isStatic = false
-        const name = seg.slice(1)
-        if (!validParamName(name)) {
-          throw new RouteConfigError(
-            "INVALID_PARAM_NAME",
-            `invalid parameter ":${name}" in "${path}"`,
-          )
-        }
-        if (paramNames.includes(name)) {
-          throw new RouteConfigError(
-            "DUPLICATE_PARAM",
-            `duplicate parameter ":${name}" in "${path}"`,
-          )
-        }
-        paramNames.push(name)
+    for (const segment of compiled.segments) {
+      if (segment.kind === "param") {
         node.paramChild ??= createNode<T>()
         node = node.paramChild
-      } else if (marker === STAR) {
-        isStatic = false
-        if (i !== segments.length - 1) {
-          throw new RouteConfigError(
-            "WILDCARD_NOT_LAST",
-            `wildcard must be the final segment in "${path}"`,
-          )
-        }
-        const name = seg.length === 1 ? "*" : seg.slice(1)
-        if (name !== "*" && !validParamName(name)) {
-          throw new RouteConfigError(
-            "INVALID_PARAM_NAME",
-            `invalid wildcard "*${name}" in "${path}"`,
-          )
-        }
-        if (paramNames.includes(name)) {
-          throw new RouteConfigError(
-            "DUPLICATE_PARAM",
-            `duplicate parameter "${name}" in "${path}"`,
-          )
-        }
-        paramNames.push(name)
+      } else if (segment.kind === "wildcard") {
         node.wildcardChild ??= createNode<T>()
         node = node.wildcardChild
       } else {
-        let child = node.staticChildren.get(seg)
+        let child = node.staticChildren.get(segment.value)
         if (child === undefined) {
           child = createNode<T>()
-          node.staticChildren.set(seg, child)
+          node.staticChildren.set(segment.value, child)
         }
         node = child
       }

package/src/server/contract.ts

@@ -4,7 +4,7 @@ import { normalizeRouteCapabilities } from "../internal/capability-runtime.ts"
 import { METHODS, type Method } from "../router/router.ts"
 import type { InferOutput, StandardSchemaV1 } from "../schema/standard.ts"
 import type { Context, IdempotencyConfig, Params, RouteSchema } from "./context.ts"
-import type { OutputOf } from "./registry.ts"
+import type { EmptyRegistry, OutputOf, Registry } from "./registry.ts"
 import { Server } from "./server.ts"
 
 /** An additional (non-success) response a contract operation can document, e.g. a `404`. */
@@ -140,9 +140,13 @@ type HandlerReturnForOp<O extends OperationDef> = O extends {
   ? Response | InferOutput<R>
   : unknown
 
-/** The handlers `implement` requires: one per operation, typed from the op's input + response contract. */
-export type HandlersFor<C extends ContractShape> = {
-  [K in keyof C]: (context: ContextForOp<C[K]>) => MaybePromise<HandlerReturnForOp<C[K]>>
+/**
+ * The handlers `implement` requires: one per operation, typed from the op's input + response contract,
+ * intersected with the host app's accumulated `derive`/`decorate` context - the same
+ * `Context & Ctx` an inline {@link Handler} receives, so a handler graduates either way unchanged.
+ */
+export type HandlersFor<C extends ContractShape, Ctx = NonNullable<unknown>> = {
+  [K in keyof C]: (context: ContextForOp<C[K]> & Ctx) => MaybePromise<HandlerReturnForOp<C[K]>>
 }
 
 const METHOD_SET: ReadonlySet<string> = new Set(METHODS)
@@ -189,7 +193,11 @@ type AnyFn = (...args: never[]) => unknown
  * the implemented server stays route-for-route identical to the equivalent inline server (the
  * mode-conformance guarantee), and a contract-typed client and a `typeof app`-typed client agree.
  */
-export type RegistryFromImpl<C extends ContractShape, H extends HandlersFor<C>> = {
+export type RegistryFromImpl<
+  C extends ContractShape,
+  H extends HandlersFor<C, Ctx>,
+  Ctx = NonNullable<unknown>,
+> = {
   [P in C[keyof C]["path"]]: {
     [K in keyof C as C[K]["path"] extends P ? C[K]["method"] : never]: {
       readonly params: Params<C[K]["path"]>
@@ -215,13 +223,28 @@ export type RegistryFromImpl<C extends ContractShape, H extends HandlersFor<C>>
  * builder, so the result is identical to writing the routes inline — handlers
  * lift over **unchanged** ("graduation"), and body/query schemas validate at the
  * request boundary exactly as in inline mode.
+ *
+ * Pass a pre-configured `app` to give the contract's routes a middleware chain. A route captures the
+ * server's `derive`/`decorate`/assurance chain **at registration**, so anything applied to the
+ * returned server afterwards reaches the contract's routes not at all - the app must already carry it:
+ *
+ * ```ts
+ * const app = implement(contract, handlers, server().use(auth).derive(sessionOf))
+ * ```
+ *
+ * That is also the seam that lets `nifra assure` prove rather than merely classify a contract-first
+ * app: the plugin that installs the enforcement is what declares the evidence
+ * ({@link withRouteAssurance}), and only a plugin installed *before* registration is captured. Handlers
+ * then see the app's `Ctx`, and the returned server keeps any routes the app already had.
  */
-export function implement<const C extends ContractShape, H extends HandlersFor<C>>(
-  contract: C,
-  handlers: H,
-): Server<RegistryFromImpl<C, H>> {
-  const app = new Server()
-  for (const [name, op] of Object.entries(contract)) {
+export function implement<
+  const C extends ContractShape,
+  H extends HandlersFor<C, Ctx>,
+  R extends Registry = EmptyRegistry,
+  Ctx = NonNullable<unknown>,
+>(contract: C, handlers: H, app?: Server<R, Ctx>): Server<R & RegistryFromImpl<C, H, Ctx>, Ctx> {
+  const target = (app ?? new Server()) as Server<R, Ctx>
+  const routes = Object.entries(contract).map(([name, op]) => {
     // body/query are validated at the request boundary; `response` is a type + introspection contract
     // ONLY — never validated at runtime and never read on the request hot path (the lifecycle reads
     // schema.body/query by name; the `bare`/bodyOnly/queryOnly fast-path gates ignore `response`). Built
@@ -243,14 +266,15 @@ export function implement<const C extends ContractShape, H extends HandlersFor<C
             ...(op.classification !== undefined ? { classification: op.classification } : {}),
           }
         : undefined
-    app.register(
-      op.method,
-      op.path,
+    return {
+      method: op.method,
+      path: op.path,
       schema,
-      handlers[name as keyof H] as (context: never) => unknown,
-    )
-  }
+      handler: handlers[name as keyof H] as (context: never) => unknown,
+    }
+  })
+  target.registerBatch(routes)
   // Runtime registered exactly the contract's routes through the inline path; the
   // registry type is computed from the contract inputs + handler return types.
-  return app as unknown as Server<RegistryFromImpl<C, H>>
+  return target as unknown as Server<R & RegistryFromImpl<C, H, Ctx>, Ctx>
 }