@nifrajs/core 1.10.0 → 1.11.0

package/src/server/server.ts

@@ -8,14 +8,17 @@ import {
 } from "../budget.ts"
 import { FrameworkError, RouteConfigError } from "../errors.ts"
 import {
+  canonicalizeIdempotencyBody,
   computeIdempotencyFingerprint,
   DEFAULT_IDEMPOTENCY_HEADER,
   DEFAULT_IDEMPOTENCY_TTL_MS,
+  IdempotencyResponseTooLargeError,
   type IdempotencyStore,
   MemoryIdempotencyStore,
   responseFromStored,
   serializeResponse,
   validIdempotencyKey,
+  validIdempotencyNamespace,
 } from "../idempotency.ts"
 import {
   CAPABILITY_GUARD,
@@ -30,6 +33,13 @@ import {
   assuranceEvidenceFor,
   NIFRA_ASSURANCE_IDS,
 } from "../internal/route-assurance.ts"
+import {
+  attachEffectLedger,
+  createRequestLedger,
+  DEFAULT_MAX_ENTRIES,
+  type EffectLedgerOptions,
+  type RequestLedger,
+} from "../ledger.ts"
 import { EMPTY_PARAMS, type Method, Router } from "../router/router.ts"
 import type {
   InferOutput,
@@ -164,7 +174,7 @@ type RawAfterHandle = (result: unknown, ctx: RawContext) => MaybePromise<unknown
 type RawErrorHandler = (error: unknown, ctx: RawContext) => MaybePromise<unknown>
 type RawAround = <T>(ctx: RawContext, next: () => MaybePromise<T>) => MaybePromise<T>
 export type OnRequestResult = Response | Request | undefined
-type RawOnRequest = (req: Request) => MaybePromise<OnRequestResult>
+type RawOnRequest = (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>
 type RawOnResponse = (response: Response, req: Request) => MaybePromise<Response>
 type RawOnResponseFinalized = (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
 
@@ -173,6 +183,20 @@ interface ResolvedIdempotency {
   readonly store: IdempotencyStore
   readonly ttlMs: number
   readonly headerName: string
+  readonly namespace: NonNullable<RouteSchema["idempotency"]>["namespace"]
+  readonly maxResponseBytes: number
+}
+
+/** Registration-resolved effect-ledger wiring for one capability-declaring route. */
+interface ResolvedEffectLedger {
+  readonly sink: EffectLedgerOptions["sink"]
+  readonly maxEntries: number
+  readonly chain: boolean
+  /** The registered route pattern — what the sealed ledger names (never the concrete URL). */
+  readonly method: string
+  readonly path: string
+  /** The route's declared capability tokens, surfaced on the sealed ledger. */
+  readonly declared: readonly string[]
 }
 
 interface RouteEntry {
@@ -180,6 +204,8 @@ interface RouteEntry {
   readonly schema: RouteSchema | undefined
   /** Resolved idempotency config; `undefined` = off (the dedupe lane is never entered). */
   readonly idempotent: ResolvedIdempotency | undefined
+  /** Resolved effect-ledger wiring; `undefined` = off (no per-request ledger, no settle step). */
+  readonly ledgered: ResolvedEffectLedger | undefined
   /** Per-request context extensions captured at registration (order-scoped). */
   readonly derives: ReadonlyArray<RawDerive>
   /** Static context extensions captured at registration. */
@@ -343,6 +369,16 @@ export interface ServerOptions {
    * parameters, body, tenant, or values. Routes without capability declarations keep the old hot path.
    */
   readonly onCapabilityUse?: (event: CapabilityUseEvent) => void
+  /**
+   * Enable the per-request effect ledger. Each route that declares `schema.capabilities` gets a
+   * bounded, token-only ledger; `useCapability(c, id, …)` appends one entry per effect, and the sink
+   * receives the sealed ledger when the response settles (only when it recorded entries). Token-only
+   * by construction — capability ids, phases, counters, digests; never payloads, values, or the
+   * concrete URL (the route *pattern* is recorded). Enabling it moves capability-declaring routes off
+   * the fused fast path (they need a per-request context + a settle step); all other routes are
+   * unaffected, and when unset the request path pays nothing.
+   */
+  readonly effectLedger?: EffectLedgerOptions
   /**
    * 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).
@@ -450,7 +486,7 @@ export interface RunningServer {
  */
 export interface Middleware {
   readonly name?: string
-  readonly onRequest?: (req: Request) => MaybePromise<OnRequestResult>
+  readonly onRequest?: (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>
   readonly around?: <T>(context: Context, next: () => MaybePromise<T>) => MaybePromise<T>
   readonly beforeHandle?: (context: Context) => MaybePromise<unknown>
   readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>
@@ -1272,6 +1308,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   /** Capacity-admission gate; `undefined` = off (the request path pays nothing). */
   private readonly capacityGate: AdmissionController | undefined
   private readonly onCapabilityUse: ((event: CapabilityUseEvent) => void) | undefined
+  /** Effect-ledger defaults pinned at construction; per-route `ledgered` copies add route identity. */
+  private readonly effectLedger:
+    | Omit<ResolvedEffectLedger, "method" | "path" | "declared">
+    | undefined
   /** App-wide idempotency store (explicit option, else a lazily-created in-process default). */
   private readonly configuredIdempotencyStore: IdempotencyStore | undefined
   private lazyIdempotencyStore: IdempotencyStore | undefined
@@ -1336,6 +1376,23 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.gracefulSignals = options.gracefulSignals ?? false
     this.capacityGate = options.admission
     this.onCapabilityUse = options.onCapabilityUse
+    if (options.effectLedger !== undefined) {
+      const ledger = options.effectLedger
+      if (typeof ledger.sink !== "function") {
+        throw new TypeError("effectLedger.sink must be a function")
+      }
+      const maxEntries = ledger.maxEntries ?? DEFAULT_MAX_ENTRIES
+      if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new RangeError("effectLedger.maxEntries must be a positive safe integer")
+      }
+      this.effectLedger = Object.freeze({
+        sink: ledger.sink,
+        maxEntries,
+        chain: ledger.chain ?? false,
+      })
+    } else {
+      this.effectLedger = undefined
+    }
     this.configuredIdempotencyStore = options.idempotencyStore
     this.lazyIdempotencyStore = undefined
     this.logger = options.logger ?? jsonLogger()
@@ -1375,8 +1432,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
    * Run before routing on the raw request. Return a `Response` to short-circuit, or a replacement
    * `Request` to continue routing with a rewritten method/URL/headers. Global.
    */
-  onRequest(fn: (req: Request) => MaybePromise<OnRequestResult>): this {
-    this.onRequestHooks.push(fn)
+  onRequest(
+    fn: (req: Request, platform?: Platform<EnvOf<Ctx>>) => MaybePromise<OnRequestResult>,
+  ): this {
+    this.onRequestHooks.push(fn as RawOnRequest)
     return this
   }
 
@@ -1800,6 +1859,11 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         `route handler assurance must use plugin scope (received ${invalidHandlerScope.scope})`,
       )
     }
+    const authenticated = assuranceEvidenceFor(
+      [...this.activeAssurance, ...handlerAssurance, ...this.globalAssurance],
+      method,
+      path,
+    ).some((evidence) => evidence.id === NIFRA_ASSURANCE_IDS.AUTHENTICATED)
     const routeDecorations: Record<PropertyKey, unknown> = { ...this.decorations }
     if (capabilities.length > 0) {
       routeDecorations[CAPABILITY_GUARD] = createCapabilityGuard(
@@ -1813,11 +1877,19 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     // 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 idempotent = this.resolveIdempotency(schema, authenticated)
+    // A ledgered route (capabilities declared + `server({ effectLedger })`) needs a per-request
+    // context to carry the ledger and a settle step to seal + sink it, so it too leaves the
+    // fused/contextless fast path. Resolved per route, at registration — like the capability guard.
+    const ledgered: ResolvedEffectLedger | undefined =
+      capabilities.length > 0 && this.effectLedger !== undefined
+        ? Object.freeze({ ...this.effectLedger, method, path, declared: capabilities })
+        : undefined
     const bare =
       schema?.body === undefined &&
       schema?.query === undefined &&
       idempotent === undefined &&
+      ledgered === undefined &&
       this.derives.length === 0 &&
       this.beforeHandleHooks.length === 0 &&
       this.afterHandleHooks.length === 0 &&
@@ -1836,6 +1908,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       handler: handler as unknown as InternalHandler,
       schema,
       idempotent,
+      ledgered,
       fusedWeb,
       derives: [...this.derives],
       decorations: routeDecorations,
@@ -1883,9 +1956,8 @@ 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.
+    // Declaring `schema.idempotency` is evidence for request replay only. It deliberately never proves
+    // durable command execution; that stronger evidence belongs to a command/outbox adapter.
     if (schema?.idempotency !== undefined) {
       routeAssurance.push(
         Object.freeze({
@@ -1894,15 +1966,6 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           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,
@@ -1914,13 +1977,73 @@ 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 {
+  private resolveIdempotency(
+    schema: RouteSchema | undefined,
+    authenticated: boolean,
+  ): ResolvedIdempotency | undefined {
     const config = schema?.idempotency
     if (config === undefined) return undefined
+    if (schema?.sse !== undefined) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "streaming/SSE responses cannot be used on an idempotency route",
+      )
+    }
+    const store = config.store ?? this.defaultIdempotencyStore()
+    if (config.scope === "durable" && store.durability !== "durable") {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        'durable idempotency requires a durable store (store.durability must be "durable")',
+      )
+    }
+    const ttlMs = config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS
+    if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "idempotency ttlMs must be a finite positive number",
+      )
+    }
+    const headerName = (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase()
+    try {
+      new Headers().set(headerName, "probe")
+    } catch {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        `invalid idempotency header name ${JSON.stringify(headerName)}`,
+      )
+    }
+    const namespace = config.namespace
+    if (namespace === undefined) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "idempotency namespace is required; use a principal resolver or an explicit shared scope",
+      )
+    }
+    if (typeof namespace === "string" && !validIdempotencyNamespace(namespace)) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        `invalid idempotency namespace ${JSON.stringify(namespace)}`,
+      )
+    }
+    if (authenticated && typeof namespace !== "function") {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "authenticated idempotency routes require a principal namespace resolver",
+      )
+    }
+    const maxResponseBytes = config.maxResponseBytes ?? this.maxBodyBytes
+    if (!Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 1) {
+      throw new RouteConfigError(
+        "INVALID_IDEMPOTENCY",
+        "idempotency maxResponseBytes must be a positive integer",
+      )
+    }
     return Object.freeze({
-      store: config.store ?? this.defaultIdempotencyStore(),
-      ttlMs: config.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS,
-      headerName: (config.headerName ?? DEFAULT_IDEMPOTENCY_HEADER).toLowerCase(),
+      store,
+      ttlMs,
+      headerName,
+      namespace,
+      maxResponseBytes,
     })
   }
 
@@ -2285,7 +2408,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     const originalRequest = requestOf(source)
     let current: RequestSource = source
     for (let i = 0; i < hooks.length; i++) {
-      const outcome = (hooks[i] as RawOnRequest)(requestOf(current))
+      const outcome = (hooks[i] as RawOnRequest)(requestOf(current), platform)
       if (outcome instanceof Promise) {
         return outcome.then((early) =>
           this.continueOnRequest(
@@ -2335,7 +2458,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         return wrapResponse(early)
       }
       if (index >= this.onRequestHooks.length) break
-      const outcome = (this.onRequestHooks[index] as RawOnRequest)(requestOf(current))
+      const outcome = (this.onRequestHooks[index] as RawOnRequest)(requestOf(current), platform)
       early = outcome instanceof Promise ? await outcome : outcome
       index++
     }
@@ -2445,6 +2568,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     if (key === null || !validIdempotencyKey(key)) {
       return wrapResponse(jsonError(400, "idempotency_key_required"))
     }
+    const namespace =
+      typeof config.namespace === "function"
+        ? await config.namespace(req.clone(), platform)
+        : config.namespace
+    if (!validIdempotencyNamespace(namespace)) {
+      return wrapResponse(jsonError(500, "idempotency_namespace_invalid"))
+    }
     const read = await readBoundedBytes(req, this.maxBodyBytes)
     if (!read.ok) {
       return wrapResponse(
@@ -2452,22 +2582,34 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       )
     }
     const url = urlPartsOf(req.url)
+    const canonicalBody = canonicalizeIdempotencyBody(read.bytes, req.headers.get("content-type"))
     const fingerprint = await computeIdempotencyFingerprint(
       req.method,
       `${url.pathname}${url.search}`,
-      read.bytes,
+      canonicalBody,
+      req.headers.get("content-type") ?? "",
     )
 
-    const begin = await config.store.begin(key, fingerprint, config.ttlMs)
-    if (begin.state === "replay") return wrapResponse(responseFromStored(begin.response))
+    const begin = await config.store.begin({ namespace, key, fingerprint, ttlMs: config.ttlMs })
+    if (begin.state === "replay") {
+      return wrapResponse(responseFromStored(begin.response, { maxBytes: config.maxResponseBytes }))
+    }
     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" }))
     }
+    if (begin.state === "capacity") {
+      return wrapResponse(jsonError(503, "idempotency_store_capacity", { "Retry-After": "1" }))
+    }
+    const reservation = begin.reservation
 
     // 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 }
+    const bufferedInit: RequestInit = {
+      method: req.method,
+      headers: req.headers,
+      signal: req.signal,
+    }
     if (read.bytes.byteLength > 0)
       bufferedInit.body = read.bytes as NonNullable<RequestInit["body"]>
     const buffered: RequestSource = new Request(req.url, bufferedInit)
@@ -2487,14 +2629,44 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     } 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)
+      await config.store.abandon({ namespace, key, reservation })
       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))
+      let storedResponse: Awaited<ReturnType<typeof serializeResponse>>
+      try {
+        storedResponse = await serializeResponse(response, { maxBytes: config.maxResponseBytes })
+      } catch (error) {
+        if (!(error instanceof IdempotencyResponseTooLargeError)) throw error
+        // The effect may already have happened, so never abandon and permit a duplicate execution.
+        // Commit a small terminal response under the winning key and return that same response now.
+        response = jsonError(507, "idempotency_response_too_large")
+        try {
+          storedResponse = await serializeResponse(response, {
+            maxBytes: config.maxResponseBytes,
+          })
+        } catch (terminalError) {
+          if (!(terminalError instanceof IdempotencyResponseTooLargeError)) throw terminalError
+          // Even an intentionally tiny bound must remain truthful. An empty 507 preserves terminal
+          // status + replay safety without silently storing more bytes than the route permits.
+          response = new Response(null, { status: 507 })
+          storedResponse = await serializeResponse(response, {
+            maxBytes: config.maxResponseBytes,
+          })
+        }
+      }
+      const completed = await config.store.complete({
+        namespace,
+        key,
+        reservation,
+        response: storedResponse,
+      })
+      if (!completed) {
+        return wrapResponse(jsonError(503, "idempotency_reservation_lost", { "Retry-After": "1" }))
+      }
     } else {
-      await config.store.abandon(key)
+      await config.store.abandon({ namespace, key, reservation })
     }
     return wrapResponse(response)
   }
@@ -2584,6 +2756,20 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
         platform,
         this.maxBodyBytes,
       )
+      // Ledgered routes (capabilities + effectLedger) carry a bounded per-request ledger; the
+      // `useCapability` beacon appends to it, and the settle step below seals + sinks it. The route
+      // was forced off the fused/contextless lanes at registration, so this branch always runs.
+      let ledger: RequestLedger | undefined
+      if (entry.ledgered !== undefined) {
+        ledger = createRequestLedger({
+          method: entry.ledgered.method,
+          path: entry.ledgered.path,
+          declared: entry.ledgered.declared,
+          maxEntries: entry.ledgered.maxEntries,
+          chain: entry.ledgered.chain,
+        })
+        attachEffectLedger(ctx, ledger)
+      }
 
       if (entry.around.length === 0) {
         outcome = entry.bare
@@ -2609,6 +2795,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
           wrapResponse,
         )
       }
+      // Settle step: seal the ledger and hand it to the sink BEFORE the response is released, on
+      // success and error responses alike (partial work is exactly what an audit must capture). The
+      // lanes above resolve handler errors to responses, so a plain resolve arm is sufficient.
+      if (ledger !== undefined) {
+        const resolved = entry.ledgered as ResolvedEffectLedger
+        const active = ledger
+        outcome = (outcome instanceof Promise ? outcome : Promise.resolve(outcome)).then((value) =>
+          this.settleEffectLedger(active, resolved, value),
+        )
+      }
     }
     // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
     // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
@@ -2627,6 +2823,34 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return outcome
   }
 
+  /**
+   * Seal a ledgered request and deliver the sealed ledger to the sink. An empty ledger (declared
+   * capabilities, none exercised) is not delivered — there is nothing to audit. This post-effect
+   * ledger is observational: transactional/durable audit belongs in
+   * the owned effect transaction, so a sink outage must not turn a successful effect into a retryable
+   * 500 that can duplicate it.
+   */
+  private async settleEffectLedger<T>(
+    ledger: RequestLedger,
+    resolved: ResolvedEffectLedger,
+    value: T,
+  ): Promise<T> {
+    const sealed = await ledger.seal()
+    if (sealed.entries.length === 0) return value
+    try {
+      await resolved.sink(sealed)
+    } catch (err) {
+      // Token-only logging: the route pattern and the failure name — never entry payloads (there are
+      // none) and never the request.
+      this.logger.error("effect ledger sink failed", {
+        method: resolved.method,
+        path: resolved.path,
+        name: err instanceof Error ? err.name : "Error",
+      })
+    }
+    return value
+  }
+
   /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
    * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
   private runContextlessBare<T>(