@nifrajs/core 1.9.0 → 1.10.0

package/src/server/server.ts

@@ -5,8 +5,24 @@ import {
   type DeadlineAdmissionOptions,
   NIFRA_DEADLINE_HEADER,
   type RequestBudget,
-} from "@nifrajs/budget"
+} from "../budget.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
+import {
+  computeIdempotencyFingerprint,
+  DEFAULT_IDEMPOTENCY_HEADER,
+  DEFAULT_IDEMPOTENCY_TTL_MS,
+  type IdempotencyStore,
+  MemoryIdempotencyStore,
+  responseFromStored,
+  serializeResponse,
+  validIdempotencyKey,
+} from "../idempotency.ts"
+import {
+  CAPABILITY_GUARD,
+  type CapabilityUseEvent,
+  createCapabilityGuard,
+  normalizeRouteCapabilities,
+} from "../internal/capability-runtime.ts"
 import {
   type AssuranceDeclaration,
   type AssuranceEvidence,
@@ -152,13 +168,22 @@ type RawOnRequest = (req: Request) => MaybePromise<OnRequestResult>
 type RawOnResponse = (response: Response, req: Request) => MaybePromise<Response>
 type RawOnResponseFinalized = (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
 
+/** Registration-resolved idempotency for a route: the config with its store + defaults pinned. */
+interface ResolvedIdempotency {
+  readonly store: IdempotencyStore
+  readonly ttlMs: number
+  readonly headerName: string
+}
+
 interface RouteEntry {
   readonly handler: InternalHandler
   readonly schema: RouteSchema | undefined
+  /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
+  readonly idempotent: ResolvedIdempotency | undefined
   /** Per-request context extensions captured at registration (order-scoped). */
   readonly derives: ReadonlyArray<RawDerive>
   /** Static context extensions captured at registration. */
-  readonly decorations: Record<string, unknown>
+  readonly decorations: Record<PropertyKey, unknown>
   /** Whether {@link decorations} has any keys — precomputed so the hot path skips a no-op
    * `Object.assign` on the (common) no-decoration route. */
   readonly hasDecorations: boolean
@@ -254,6 +279,27 @@ export type Handler<
   Ctx = EmptyContext,
 > = (ctx: Context<Path, S> & Ctx) => MaybePromise<ResponseOf<S>>
 
+/**
+ * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
+ * exactly once when the response is finalized; a shed request carries a ready `429` Response.
+ */
+export type AdmissionDecision =
+  | { readonly admitted: true; release(): void }
+  | { readonly admitted: false; readonly response: Response }
+
+/**
+ * A capacity-admission gate. Decides, per request, whether the instance has capacity to run it now —
+ * bounding *concurrency*, which rate limits (frequency) and deadlines (duration) do not. Provide an
+ * implementation (see `@nifrajs/middleware`'s `createAdmissionController`) as {@link ServerOptions.admission}.
+ *
+ * Enabling it trades the fused native-route lane for native matching + this gate (the gate cannot be a
+ * per-request `onRequest` hook without disabling native routes entirely); when unset, the request path
+ * is untouched.
+ */
+export interface AdmissionController {
+  admit(req: Request): AdmissionDecision | Promise<AdmissionDecision>
+}
+
 export interface ServerOptions {
   /**
    * Max request body size (bytes), enforced **only when a route declares a body schema** — the cap
@@ -285,6 +331,24 @@ export interface ServerOptions {
   readonly maxInboundDeadlineMs?: number
   /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
   readonly gracefulSignals?: boolean
+  /**
+   * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
+   * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
+   * Off by default. Enabling it disables the fused native-route fast path (requests route through the
+   * shared matched lane where the gate runs); when unset, the request path pays nothing.
+   */
+  readonly admission?: AdmissionController
+  /**
+   * Optional token-only observation hook called by `useCapability(c, id)`. It receives no request,
+   * parameters, body, tenant, or values. Routes without capability declarations keep the old hot path.
+   */
+  readonly onCapabilityUse?: (event: CapabilityUseEvent) => void
+  /**
+   * Default store backing routes that declare `schema.idempotency` without their own `store`. Defaults
+   * to a shared in-process {@link MemoryIdempotencyStore} (created lazily on first idempotent route).
+   * Inject a durable store here to make request-scoped dedupe survive restarts app-wide.
+   */
+  readonly idempotencyStore?: IdempotencyStore
   /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
   readonly logger?: Logger
   /**
@@ -326,6 +390,8 @@ export interface RouteDescriptor {
   readonly schema: RouteSchema | undefined
   /** Effective enforcement evidence, populated only during reflection/introspection. */
   readonly assurance?: readonly AssuranceEvidence[]
+  /** Normalized declared effect tokens, populated only when the route declares any. */
+  readonly capabilities?: readonly string[]
   readonly tool?: {
     readonly name: string
     readonly description: string
@@ -1203,6 +1269,12 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly maxInboundDeadlineMs: number
   private readonly deadlineAdmissionOptions: DeadlineAdmissionOptions
   private readonly gracefulSignals: boolean
+  /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
+  private readonly capacityGate: AdmissionController | undefined
+  private readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
+  /** App-wide idempotency store (explicit option, else a lazily-created in-process default). */
+  private readonly configuredIdempotencyStore: IdempotencyStore | undefined
+  private lazyIdempotencyStore: IdempotencyStore | undefined
   private readonly logger: Logger
   /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
   private readonly defaultOnValidationError?: RouteSchema["onValidationError"]
@@ -1262,6 +1334,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       throw new RangeError("maxInboundDeadlineMs must be a finite positive number")
     }
     this.gracefulSignals = options.gracefulSignals ?? false
+    this.capacityGate = options.admission
+    this.onCapabilityUse = options.onCapabilityUse
+    this.configuredIdempotencyStore = options.idempotencyStore
+    this.lazyIdempotencyStore = undefined
     this.logger = options.logger ?? jsonLogger()
     this.defaultOnValidationError = options.onValidationError
     this.bunServer = undefined
@@ -1713,9 +1789,35 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     schema: RouteSchema | undefined,
     handler: (context: never) => unknown,
   ): void {
+    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 routeDecorations: Record<PropertyKey, unknown> = { ...this.decorations }
+    if (capabilities.length > 0) {
+      routeDecorations[CAPABILITY_GUARD] = createCapabilityGuard(
+        capabilities,
+        method,
+        path,
+        this.onCapabilityUse,
+      )
+    }
+    const hasDecorations = Reflect.ownKeys(routeDecorations).length > 0
+    // An idempotency route runs a dedupe lane that must buffer the body and capture the response, so it
+    // never takes the fused/native fast path — force it onto the portable matched lane (which routes
+    // through `fetchMatched`, where the dedupe wrapper lives).
+    const idempotent = this.resolveIdempotency(schema)
     const bare =
       schema?.body === undefined &&
       schema?.query === undefined &&
+      idempotent === undefined &&
       this.derives.length === 0 &&
       this.beforeHandleHooks.length === 0 &&
       this.afterHandleHooks.length === 0 &&
@@ -1724,7 +1826,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       bare && this.aroundHooks.length === 0
         ? this.buildFusedWeb(
             handler as unknown as InternalHandler,
-            Object.keys(this.decorations).length > 0 ? { ...this.decorations } : undefined,
+            hasDecorations ? routeDecorations : undefined,
             isContextlessNoArgArrow(handler),
           )
         : undefined
@@ -1733,10 +1835,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       // with the concrete RawContext the typed handler expects, so this is sound.
       handler: handler as unknown as InternalHandler,
       schema,
+      idempotent,
       fusedWeb,
       derives: [...this.derives],
-      decorations: { ...this.decorations },
-      hasDecorations: Object.keys(this.decorations).length > 0,
+      decorations: routeDecorations,
+      hasDecorations,
       beforeHandle: [...this.beforeHandleHooks],
       afterHandle: [...this.afterHandleHooks],
       onError: [...this.onErrorHooks],
@@ -1763,9 +1866,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         this.onErrorHooks.length === 0,
     }
     this.router.add(method, path, entry)
-    const descriptor: RouteDescriptor = { method, path, schema }
+    const descriptor: RouteDescriptor = {
+      method,
+      path,
+      schema,
+      ...(capabilities.length > 0 ? { capabilities } : {}),
+    }
     this.routeList.push(descriptor)
-    const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance]
+    const routeAssurance: AssuranceDeclaration[] = [...this.activeAssurance, ...handlerAssurance]
     if (schema?.body !== undefined) {
       routeAssurance.push(
         Object.freeze({
@@ -1775,6 +1883,27 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         }),
       )
     }
+    // Declaring `schema.idempotency` is the evidence that satisfies a write capability's idempotency
+    // requirement (capability assurance reads these ids). `durable` scope additionally proves the
+    // durable-command requirement.
+    if (schema?.idempotency !== undefined) {
+      routeAssurance.push(
+        Object.freeze({
+          id: NIFRA_ASSURANCE_IDS.IDEMPOTENCY_KEY,
+          source: "route-schema",
+          scope: "plugin",
+        }),
+      )
+      if (schema.idempotency.scope === "durable") {
+        routeAssurance.push(
+          Object.freeze({
+            id: NIFRA_ASSURANCE_IDS.DURABLE_COMMAND,
+            source: "route-schema",
+            scope: "plugin",
+          }),
+        )
+      }
+    }
     this.rawEntries.push({
       method,
       path,
@@ -1784,6 +1913,24 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     })
   }
 
+  /** Resolve a route's declared idempotency into a pinned store + defaults, or `undefined` when off. */
+  private resolveIdempotency(schema: RouteSchema | undefined): ResolvedIdempotency | undefined {
+    const config = schema?.idempotency
+    if (config === undefined) return undefined
+    return Object.freeze({
+      store: config.store ?? this.defaultIdempotencyStore(),
+      ttlMs: config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS,
+      headerName: (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase(),
+    })
+  }
+
+  /** The app-wide idempotency store: the configured one, else a lazily-created shared in-process store. */
+  private defaultIdempotencyStore(): IdempotencyStore {
+    if (this.configuredIdempotencyStore !== undefined) return this.configuredIdempotencyStore
+    this.lazyIdempotencyStore ??= new MemoryIdempotencyStore()
+    return this.lazyIdempotencyStore
+  }
+
   /**
    * Merge another server's routes into this one — the composition escape hatch for large apps.
    *
@@ -1855,6 +2002,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private fetchSource(
     source: RequestSource,
     platform?: Platform<EnvOf<Ctx>>,
+  ): MaybePromise<Response> {
+    // Off path (default): straight through — one property check, no closure, no promise.
+    if (this.capacityGate === undefined) return this.fetchSourceInner(source, platform)
+    return this.admitGated(requestOf(source), () => this.fetchSourceInner(source, platform))
+  }
+
+  private fetchSourceInner(
+    source: RequestSource,
+    platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<Response> {
     // Non-`async` on purpose: `dispatch` may return a `Response` *synchronously* (the bare-route fast
     // path, see RouteEntry.bare), and an `async fetch` would wrap every such result in a redundant
@@ -1886,6 +2042,15 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     source: RequestSource,
     entry: RouteEntry,
     params: Record<string, string>,
+  ): MaybePromise<Response> {
+    if (this.capacityGate === undefined) return this.fetchMatchedInner(source, entry, params)
+    return this.admitGated(requestOf(source), () => this.fetchMatchedInner(source, entry, params))
+  }
+
+  private fetchMatchedInner(
+    source: RequestSource,
+    entry: RouteEntry,
+    params: Record<string, string>,
   ): MaybePromise<Response> {
     const outcome = this.runMatched(
       source,
@@ -1906,6 +2071,45 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       : this.applyOnResponseAndFinalize(outcome, requestOf(source))
   }
 
+  /**
+   * Run `produce` under the capacity gate: admit → run → release exactly once when the response is
+   * produced (or the run throws). Only reached when {@link capacityGate} is set, so the off path pays
+   * nothing. The slot is held for the duration of handler execution, not the streaming of the body —
+   * capacity here bounds concurrent *work*, matching how in-flight is counted.
+   */
+  private admitGated(req: Request, produce: () => MaybePromise<Response>): MaybePromise<Response> {
+    const decision = (this.capacityGate as AdmissionController).admit(req)
+    return decision instanceof Promise
+      ? decision.then((settled) => this.runAdmitted(settled, produce))
+      : this.runAdmitted(decision, produce)
+  }
+
+  private runAdmitted(
+    decision: AdmissionDecision,
+    produce: () => MaybePromise<Response>,
+  ): MaybePromise<Response> {
+    if (!decision.admitted) return decision.response // shed: ready 429, no slot held
+    let released = false
+    const release = (): void => {
+      if (released) return
+      released = true
+      decision.release()
+    }
+    let outcome: MaybePromise<Response>
+    try {
+      outcome = produce()
+    } catch (error) {
+      release()
+      throw error
+    }
+    // Release the slot once the response settles — on resolve OR reject — via `finally`, which passes
+    // the value/rejection through unchanged. (A single settle hook, rather than separate then-arms: the
+    // request pipeline resolves handler errors to a Response, so a rejection arm would be unreachable.)
+    if (outcome instanceof Promise) return outcome.finally(release)
+    release()
+    return outcome
+  }
+
   /**
    * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` — the
    * `@nifrajs/node` adapter serializes the returned primitives straight to the socket, skipping the undici
@@ -1923,8 +2127,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     source: RequestSource,
     platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<NodeServeOutcome> {
-    // onResponse hooks transform a Response, so they force the Web path; wrap its result.
-    if (this.onResponseHooks.length > 0 || this.onResponseFinalizedHooks.length > 0) {
+    // onResponse hooks transform a Response, and the capacity gate wraps the Web response path — both
+    // force the Web path here (the gated `fetchSource` admits/sheds/releases); wrap its result.
+    if (
+      this.onResponseHooks.length > 0 ||
+      this.onResponseFinalizedHooks.length > 0 ||
+      this.capacityGate !== undefined
+    ) {
       const response = this.fetchSource(source, platform)
       return response instanceof Promise
         ? response.then((settled) => ({ kind: "response", response: settled }))
@@ -2196,6 +2405,111 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     wrapResponse: (response: Response) => T,
     onTimeout: () => T,
     webFast: boolean,
+  ): MaybePromise<T> {
+    // An idempotency route runs its dedupe lane first; on a fresh key it delegates to the normal lanes
+    // (with the body buffered). All non-idempotent routes skip straight to the lanes — no added cost.
+    if (entry.idempotent !== undefined) {
+      return this.runIdempotent(source, platform, entry, params, search, wrapResponse)
+    }
+    return this.runMatchedLanes(
+      source,
+      platform,
+      entry,
+      params,
+      search,
+      finalize,
+      wrapResponse,
+      onTimeout,
+      webFast,
+    )
+  }
+
+  /**
+   * Idempotency dedupe lane. Reads the `Idempotency-Key`, fingerprints the request, and consults the
+   * store: a fresh key runs the handler (via {@link runMatchedLanes} with the body buffered) and stores
+   * the response; a repeat key replays it without re-running; a key reused with a different body or an
+   * in-flight duplicate is rejected. Every branch materializes a `Response`, then adapts to `T` via the
+   * caller's `wrapResponse`, so it works on the Web fetch path and the Node-native outcome path alike.
+   */
+  private async runIdempotent<T>(
+    source: RequestSource,
+    platform: Platform | undefined,
+    entry: RouteEntry,
+    params: Record<string, string>,
+    search: string | undefined,
+    wrapResponse: (response: Response) => T,
+  ): Promise<T> {
+    const config = entry.idempotent as ResolvedIdempotency
+    const req = requestOf(source)
+    const key = req.headers.get(config.headerName)
+    if (key === null || !validIdempotencyKey(key)) {
+      return wrapResponse(jsonError(400, "idempotency_key_required"))
+    }
+    const read = await readBoundedBytes(req, this.maxBodyBytes)
+    if (!read.ok) {
+      return wrapResponse(
+        jsonError(read.status, read.status === 413 ? "payload_too_large" : "bad_request"),
+      )
+    }
+    const url = urlPartsOf(req.url)
+    const fingerprint = await computeIdempotencyFingerprint(
+      req.method,
+      `${url.pathname}${url.search}`,
+      read.bytes,
+    )
+
+    const begin = await config.store.begin(key, fingerprint, config.ttlMs)
+    if (begin.state === "replay") return wrapResponse(responseFromStored(begin.response))
+    if (begin.state === "mismatch") return wrapResponse(jsonError(409, "idempotency_key_reused"))
+    if (begin.state === "in-flight") {
+      return wrapResponse(jsonError(409, "idempotency_in_progress", { "Retry-After": "1" }))
+    }
+
+    // Fresh key: re-expose the buffered body as a Request so the normal lanes can read + validate it,
+    // then run those lanes to a concrete Response.
+    const bufferedInit: RequestInit = { method: req.method, headers: req.headers }
+    if (read.bytes.byteLength > 0)
+      bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
+    const buffered: RequestSource = new Request(req.url, bufferedInit)
+    let response: Response
+    try {
+      response = await this.runMatchedLanes(
+        buffered,
+        platform,
+        entry,
+        params,
+        search,
+        toResponse,
+        IDENTITY_RESPONSE,
+        RESPONSE_TIMEOUT,
+        false,
+      )
+    } catch (err) {
+      // The lanes never throw (errors resolve to a 500 Response), but stay fail-safe: release the
+      // reservation so a retry isn't wedged, then re-throw.
+      await config.store.abandon(key)
+      throw err
+    }
+    // Cache only successful responses; release the key on any error so the client can retry.
+    if (response.status >= 200 && response.status < 300) {
+      await config.store.complete(key, await serializeResponse(response))
+    } else {
+      await config.store.abandon(key)
+    }
+    return wrapResponse(response)
+  }
+
+  /** Run a matched route through its selected execution lane (fused/bare/bodyOnly/queryOnly/lifecycle). */
+  private runMatchedLanes<T>(
+    source: RequestSource,
+    platform: Platform | undefined,
+    entry: RouteEntry,
+    params: Record<string, string>,
+    search: string | undefined,
+    finalize: (result: unknown, set: CtxSet) => T,
+    wrapResponse: (response: Response) => T,
+    onTimeout: () => T,
+    webFast: boolean,
   ): MaybePromise<T> {
     // Translate the absolute wire deadline once, clamp it to local policy, then use the resulting
     // duration for both c.signal and c.budget. A client can only shorten work, never extend it.
@@ -2426,7 +2740,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    */
   private buildFusedWeb(
     handler: InternalHandler,
-    decorations: Record<string, unknown> | undefined,
+    decorations: Record<PropertyKey, unknown> | undefined,
     contextless: boolean,
   ): FusedWebRunner {
     const maxBodyBytes = this.maxBodyBytes
@@ -3097,7 +3411,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const mayUseFusedNative =
       this.requestTimeoutMs === 0 &&
       this.onResponseHooks.length === 0 &&
-      this.onResponseFinalizedHooks.length === 0
+      this.onResponseFinalizedHooks.length === 0 &&
+      // The capacity gate must wrap every request; the fused lane bypasses fetchMatched, so enabling
+      // admission drops fusion (native matching stays) and routes through the gated matched lane.
+      this.capacityGate === undefined
     const unboundedSignal = mayUseFusedNative ? getNeverAbortSignal() : undefined
     const unboundedBudget = mayUseFusedNative ? getUnboundedRequestBudget() : undefined
     let count = 0