@nifrajs/core 4.0.0 → 5.0.0

package/src/errors.ts

@@ -31,6 +31,7 @@ export type RouteConfigErrorCode =
   | "INVALID_VALIDATION_ORDER"
   | "INVALID_BODY_LIMIT"
   | "PLUGIN_RECONFIGURED"
+  | "MOUNT_CYCLE"
 
 /**
  * Thrown at route registration when a route is misconfigured. This is the

package/src/evidence.ts

@@ -34,6 +34,8 @@ export interface ProjectEvidenceSchemaPart {
 }
 
 export interface ProjectEvidenceSchema {
+  /** Set only when the route chose it; absent means the default for its auth stages. */
+  readonly validationOrder?: "validate-before-auth" | "auth-before-validation"
   readonly bodyLimit?: number | "unlimited"
   readonly bodyLimitReason?: string
   readonly headers?: ProjectEvidenceSchemaPart
@@ -160,6 +162,7 @@ function schemaOf(route: ReflectedRoute): ProjectEvidenceSchema | undefined {
     if (part !== undefined) errors[status] = part
   }
   const schema: ProjectEvidenceSchema = {
+    ...(source.validationOrder !== undefined ? { validationOrder: source.validationOrder } : {}),
     ...(source.bodyLimit !== undefined ? { bodyLimit: source.bodyLimit } : {}),
     ...(source.bodyLimitReason !== undefined ? { bodyLimitReason: source.bodyLimitReason } : {}),
     ...(headers !== undefined ? { headers } : {}),
@@ -328,9 +331,14 @@ function remapEvidenceSnapshot(
     const key = route(item.method, item.path)
     return Object.freeze({ ...item, ...key })
   })
-  const mounts = evidence.mounts?.map((item) =>
-    Object.freeze({ ...item, path: composedPath(pathPrefix, item.path) }),
-  )
+  const mounts = evidence.mounts?.map((item) => {
+    const path = composedPath(pathPrefix, item.path)
+    if (item.routes === undefined) return Object.freeze({ ...item, path })
+    const routes = item.routes.map((declared) =>
+      Object.freeze({ ...declared, path: composedPath(pathPrefix, declared.path) }),
+    )
+    return Object.freeze({ ...item, path, routes: Object.freeze(routes) })
+  })
   const assurance =
     evidence.assurance === undefined
       ? undefined
@@ -499,6 +507,7 @@ function schemaFromEvidence(schema: ProjectEvidenceSchema | undefined): Reflecte
   const response = schemaPartToReflection(schema.response)
   const sse = schemaPartToReflection(schema.sse)
   return {
+    ...(schema.validationOrder !== undefined ? { validationOrder: schema.validationOrder } : {}),
     ...(schema.bodyLimit !== undefined ? { bodyLimit: schema.bodyLimit } : {}),
     ...(schema.bodyLimitReason !== undefined ? { bodyLimitReason: schema.bodyLimitReason } : {}),
     ...(headers !== undefined ? { headers } : {}),

package/src/index.ts

@@ -16,7 +16,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "4.0.0" as const
+export const VERSION = "5.0.0" as const
 
 export type Version = typeof VERSION
 
@@ -54,6 +54,8 @@ export {
   type AuthHeaders,
   type AuthMaybePromise,
   authenticated,
+  isAuthenticatedRequest,
+  markAuthenticatedRequest,
   rejected,
 } from "./server/auth.ts"
 export type {
@@ -116,6 +118,7 @@ export type {
   RouteInfoFor,
 } from "./server/registry.ts"
 export { replacedRequestOf } from "./server/request-lineage.ts"
+export { writableResponse } from "./server/respond.ts"
 export {
   type PlainRender,
   type ResponseResult,
@@ -127,6 +130,7 @@ export {
   type AdmissionDecision,
   type AnyServer,
   type ContextPlugin,
+  type DeclaredMountRoute,
   type DefinePluginResult,
   defineContextPlugin,
   defineIdentityPlugin,
@@ -150,6 +154,7 @@ export {
   type NodeResponseHook,
   type NodeServeOutcome,
   type OnRequestResult,
+  type OpaqueMountDeclaration,
   type PluginTypeCollapsed,
   type PromptArgument,
   type PromptMessage,

package/src/internal/durable-shared.ts

@@ -63,12 +63,22 @@ export function reconciliationLimit(value = DEFAULT_RECONCILIATION_LIMIT): numbe
   return value
 }
 
-export function cursorOffset(cursor?: string): number {
-  if (cursor === undefined) return 0
-  if (!/^(?:0|[1-9][0-9]*)$/u.test(cursor)) throw new TypeError("invalid reconciliation cursor")
-  const offset = Number(cursor)
-  if (!Number.isSafeInteger(offset)) throw new TypeError("invalid reconciliation cursor")
-  return offset
+/**
+ * One page of `matches` in id order, the cursor being the last id returned. Keyed rather than an
+ * offset into the matching set: a caller reconciles each page before asking for the next, so the
+ * set shrinks under it, and an offset then lands past records that were never returned.
+ */
+function keysetPage<Record>(
+  matches: [id: string, record: Record][],
+  limit: number,
+): ReconciliationScanPage<Record> {
+  // Code-unit order, the order the `id > cursor` comparisons use.
+  matches.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  const page = matches.slice(0, limit)
+  const records = Object.freeze(page.map(([, record]) => cloneValue(record)))
+  const last = page.at(-1)
+  if (matches.length <= limit || last === undefined) return Object.freeze({ records })
+  return Object.freeze({ records, cursor: last[0] })
 }
 
 export function memoryScan<
@@ -76,28 +86,18 @@ export function memoryScan<
   State extends string,
 >(
   source: Iterable<Record>,
+  idOf: (record: Record) => string,
   input: ReconciliationScanOptions<State>,
 ): ReconciliationScanPage<Record> {
   const states = new Set(input.states)
-  const offset = cursorOffset(input.cursor)
-  const end = offset + input.limit
-  const records: Record[] = []
-  let seen = 0
-  let more = false
+  const matches: [string, Record][] = []
   for (const record of source) {
     if (!states.has(record.state)) continue
     if (input.updatedBefore !== undefined && record.updatedAt > input.updatedBefore) continue
-    if (seen >= end) {
-      more = true
-      break
-    }
-    if (seen >= offset) records.push(cloneValue(record))
-    seen++
+    const id = idOf(record)
+    if (input.cursor === undefined || id > input.cursor) matches.push([id, record])
   }
-  return Object.freeze({
-    records: Object.freeze(records),
-    ...(more ? { cursor: String(offset + records.length) } : {}),
-  })
+  return keysetPage(matches, input.limit)
 }
 
 export function bucketAdd<State extends string>(
@@ -129,29 +129,17 @@ export function indexedScan<Record extends { readonly updatedAt: number }, State
   resolve: (id: string) => Record | undefined,
   input: ReconciliationScanOptions<State>,
 ): ReconciliationScanPage<Record> {
-  const offset = cursorOffset(input.cursor)
-  const end = offset + input.limit
-  const records: Record[] = []
-  let seen = 0
-  let more = false
+  const matches: [string, Record][] = []
   for (const state of new Set(input.states)) {
-    if (more) break
     const bucket = byState.get(state)
     if (bucket === undefined) continue
     for (const id of bucket) {
+      if (input.cursor !== undefined && id <= input.cursor) continue
       const record = resolve(id)
       if (record === undefined) continue
       if (input.updatedBefore !== undefined && record.updatedAt > input.updatedBefore) continue
-      if (seen >= end) {
-        more = true
-        break
-      }
-      if (seen >= offset) records.push(cloneValue(record))
-      seen++
+      matches.push([id, record])
     }
   }
-  return Object.freeze({
-    records: Object.freeze(records),
-    ...(more ? { cursor: String(offset + records.length) } : {}),
-  })
+  return keysetPage(matches, input.limit)
 }

package/src/internal/durable-types.ts

@@ -138,6 +138,9 @@ export interface SagaRecord {
   readonly createdAt: number
   readonly updatedAt: number
   readonly version: number
+  /** The `resume`/`compensate` call that owns the saga while `leaseUntil` is in the future. */
+  readonly owner?: string
+  readonly leaseUntil?: number
 }
 
 export interface SagaStore {

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))