@nifrajs/core 1.10.0 → 1.12.0

package/src/errors.ts

@@ -25,6 +25,7 @@ export type RouteConfigErrorCode =
   | "WILDCARD_NOT_LAST"
   | "INVALID_METHOD"
   | "INVALID_ASSURANCE"
+  | "INVALID_IDEMPOTENCY"
 
 /**
  * Thrown at route registration when a route is misconfigured. This is the

package/src/idempotency.ts

@@ -24,6 +24,33 @@ export const IDEMPOTENT_REPLAY_HEADER = "x-nifra-idempotent-replay"
 
 const KEY_MAX_LENGTH = 255
 
+// A replay is a new HTTP exchange, not a byte-for-byte resurrection of connection state. Session
+// setters and hop-by-hop headers belong only to the winning response. Filter on both write and read:
+// durable stores may still contain records created by an older Nifra version.
+const REPLAY_UNSAFE_RESPONSE_HEADERS: ReadonlySet<string> = new Set([
+  "authentication-info",
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authentication-info",
+  "proxy-authorization",
+  "set-cookie",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+])
+
+function replaySafeHeaders(
+  headers: Iterable<readonly [string, string]>,
+): readonly (readonly [string, string])[] {
+  const safe: Array<readonly [string, string]> = []
+  for (const [name, value] of headers) {
+    if (!REPLAY_UNSAFE_RESPONSE_HEADERS.has(name.toLowerCase())) safe.push([name, value])
+  }
+  return safe
+}
+
 /** A serialized response held by a store. `body` is base64 so binary payloads round-trip intact. */
 export interface StoredResponse {
   readonly status: number
@@ -39,10 +66,33 @@ export interface StoredResponse {
  * not yet completed (a concurrent duplicate) → 409 + Retry-After.
  */
 export type IdempotencyBeginResult =
-  | { readonly state: "new" }
+  | { readonly state: "new"; readonly reservation: string }
   | { readonly state: "replay"; readonly response: StoredResponse }
   | { readonly state: "mismatch" }
   | { readonly state: "in-flight" }
+  | { readonly state: "capacity" }
+
+/** Namespaces isolate the same client key across tenants/subjects without putting identity in a header. */
+export interface IdempotencyEntryKey {
+  readonly namespace: string
+  readonly key: string
+}
+
+export interface IdempotencyBeginInput extends IdempotencyEntryKey {
+  readonly fingerprint: string
+  readonly ttlMs: number
+}
+
+export interface IdempotencyCompletionInput extends IdempotencyEntryKey {
+  /** Opaque ownership token returned by `begin(state:"new")`. */
+  readonly reservation: string
+  readonly response: StoredResponse
+}
+
+export interface IdempotencyAbandonInput extends IdempotencyEntryKey {
+  /** Opaque ownership token returned by `begin(state:"new")`. */
+  readonly reservation: string
+}
 
 /**
  * Storage seam for idempotent responses. `begin` MUST be atomic: for one key, exactly one concurrent
@@ -50,16 +100,21 @@ export type IdempotencyBeginResult =
  * this free from the single-threaded event loop; a durable store uses an atomic insert.
  */
 export interface IdempotencyStore {
-  /** Reserve `key` for `fingerprint`, retaining any stored response for `ttlMs`. */
-  begin(
-    key: string,
-    fingerprint: string,
-    ttlMs: number,
-  ): IdempotencyBeginResult | Promise<IdempotencyBeginResult>
-  /** Persist the final response for a reserved key so later retries replay it. */
-  complete(key: string, response: StoredResponse): void | Promise<void>
-  /** Release a reservation that produced no cacheable response, so the client may retry. */
-  abandon(key: string): void | Promise<void>
+  /**
+   * An honest durability marker. Omit/`memory` for process-local stores; a route declaring
+   * `scope: "durable"` rejects anything other than `durable` at registration.
+   */
+  readonly durability?: "memory" | "durable"
+  /** Reserve one namespaced key. Exactly one concurrent caller may receive `new`. */
+  begin(input: IdempotencyBeginInput): IdempotencyBeginResult | Promise<IdempotencyBeginResult>
+  /**
+   * Persist the final response only when `reservation` still owns the key. Returns false for a stale
+   * completion (for example after expiry + re-reservation), which prevents an older request from
+   * overwriting a newer result.
+   */
+  complete(input: IdempotencyCompletionInput): boolean | Promise<boolean>
+  /** Release only the pending reservation owned by `reservation`. */
+  abandon(input: IdempotencyAbandonInput): boolean | Promise<boolean>
 }
 
 /** A key must be a non-empty, bounded, control-char-free token. Fail closed on anything else. */
@@ -67,11 +122,16 @@ export function validIdempotencyKey(key: string): boolean {
   if (typeof key !== "string" || key.length === 0 || key.length > KEY_MAX_LENGTH) return false
   for (let i = 0; i < key.length; i++) {
     const code = key.charCodeAt(i)
-    if (code <= 31 || code === 127) return false
+    if (code < 33 || code > 126) return false
   }
   return true
 }
 
+/** Namespace values are server-resolved, bounded opaque tokens (normally a tenant/subject hash). */
+export function validIdempotencyNamespace(namespace: string): boolean {
+  return validIdempotencyKey(namespace)
+}
+
 const encoder = new TextEncoder()
 
 /**
@@ -82,8 +142,10 @@ export async function computeIdempotencyFingerprint(
   method: string,
   path: string,
   body: Uint8Array,
+  contentType = "",
 ): Promise<string> {
-  const head = encoder.encode(`${method.toUpperCase()}\n${path}\n`)
+  const mediaType = contentType.split(";", 1)[0]?.trim().toLowerCase() ?? ""
+  const head = encoder.encode(`${method.toUpperCase()}\n${path}\n${mediaType}\n`)
   const material = new Uint8Array(head.length + body.length)
   material.set(head, 0)
   material.set(body, head.length)
@@ -94,6 +156,41 @@ export async function computeIdempotencyFingerprint(
   return hex
 }
 
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value)
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("non-finite JSON number")
+    return JSON.stringify(value)
+  }
+  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>
+    const entries = Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+    return `{${entries.join(",")}}`
+  }
+  throw new TypeError("unsupported JSON value")
+}
+
+/** Canonicalize JSON bodies so whitespace/property-order retries bind to the same semantic request. */
+export function canonicalizeIdempotencyBody(
+  body: Uint8Array,
+  contentType: string | null,
+): Uint8Array {
+  const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase() ?? ""
+  if (mediaType !== "application/json" && !mediaType.endsWith("+json")) return body
+  try {
+    return encoder.encode(canonicalJson(JSON.parse(new TextDecoder().decode(body))))
+  } catch {
+    // Invalid JSON is rejected by the validation/body lane. Preserve its raw bytes for a stable
+    // fingerprint until that rejection releases the reservation.
+    return body
+  }
+}
+
 const BASE64_CHUNK = 0x8000
 
 function bytesToBase64(bytes: Uint8Array): string {
@@ -111,19 +208,93 @@ function base64ToBytes(value: string): Uint8Array {
   return bytes
 }
 
+function base64DecodedLength(value: string): number {
+  if (value === "") return 0
+  if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+    throw new TypeError("idempotency: corrupt stored response body")
+  }
+  const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0
+  return (value.length / 4) * 3 - padding
+}
+
+export class IdempotencyResponseTooLargeError extends Error {
+  constructor(public readonly maxBytes: number) {
+    super(`idempotency response exceeds the ${maxBytes}-byte storage bound`)
+    this.name = "IdempotencyResponseTooLargeError"
+  }
+}
+
+async function boundedResponseBytes(response: Response, maxBytes: number): Promise<Uint8Array> {
+  const contentLength = response.headers.get("content-length")
+  if (contentLength !== null && /^\d+$/.test(contentLength) && Number(contentLength) > maxBytes) {
+    throw new IdempotencyResponseTooLargeError(maxBytes)
+  }
+  const body = response.clone().body
+  if (body === null) return new Uint8Array()
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > maxBytes) {
+        await reader.cancel()
+        throw new IdempotencyResponseTooLargeError(maxBytes)
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
 /** Buffer a response into a storable form. Clones first so the live response body stays intact. */
-export async function serializeResponse(response: Response): Promise<StoredResponse> {
-  const bytes = new Uint8Array(await response.clone().arrayBuffer())
+export async function serializeResponse(
+  response: Response,
+  options: { readonly maxBytes?: number } = {},
+): Promise<StoredResponse> {
+  const maxBytes = options.maxBytes
+  if (maxBytes !== undefined && (!Number.isInteger(maxBytes) || maxBytes < 0)) {
+    throw new RangeError("idempotency: max response bytes must be a non-negative integer")
+  }
+  const bytes =
+    maxBytes === undefined
+      ? new Uint8Array(await response.clone().arrayBuffer())
+      : await boundedResponseBytes(response, maxBytes)
   return {
     status: response.status,
-    headers: [...response.headers] as readonly (readonly [string, string])[],
+    headers: replaySafeHeaders(response.headers),
     body: bytes.length > 0 ? bytesToBase64(bytes) : "",
   }
 }
 
 /** Rebuild a live response from storage, stamping the replay marker header. */
-export function responseFromStored(stored: StoredResponse): Response {
-  const headers = new Headers(stored.headers as [string, string][])
+export function responseFromStored(
+  stored: StoredResponse,
+  options: { readonly maxBytes?: number } = {},
+): Response {
+  if (!Number.isInteger(stored.status) || stored.status < 200 || stored.status > 599) {
+    throw new TypeError("idempotency: corrupt stored response status")
+  }
+  const decodedLength = base64DecodedLength(stored.body)
+  if (options.maxBytes !== undefined) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
+      throw new RangeError("idempotency: max response bytes must be a non-negative safe integer")
+    }
+    if (decodedLength > options.maxBytes) {
+      throw new IdempotencyResponseTooLargeError(options.maxBytes)
+    }
+  }
+  const headers = new Headers(replaySafeHeaders(stored.headers) as [string, string][])
   headers.set(IDEMPOTENT_REPLAY_HEADER, "1")
   // Reference the Response body type structurally: `BodyInit` isn't a named type under every lib config,
   // but a fresh `Uint8Array` is a valid body — the cast bridges the `ArrayBufferLike` generic variance.
@@ -135,13 +306,17 @@ export function responseFromStored(stored: StoredResponse): Response {
 
 interface MemoryEntry {
   readonly fingerprint: string
-  readonly expiresAt: number
+  readonly reservation: string
+  readonly ttlMs: number
+  expiresAt: number
   response: StoredResponse | undefined
 }
 
 export interface MemoryIdempotencyStoreOptions {
   /** Injectable clock (epoch ms) for deterministic TTL tests. Default `Date.now`. */
   readonly now?: () => number
+  /** Hard memory bound. At capacity new keys fail closed; completed/pending entries are never evicted early. */
+  readonly maxEntries?: number
 }
 
 /**
@@ -150,37 +325,73 @@ export interface MemoryIdempotencyStoreOptions {
  * as absent (lazy eviction on access); a periodic {@link MemoryIdempotencyStore.sweep} bounds memory.
  */
 export class MemoryIdempotencyStore implements IdempotencyStore {
+  readonly durability = "memory" as const
   private readonly entries = new Map<string, MemoryEntry>()
   private readonly now: () => number
+  private readonly maxEntries: number
 
   constructor(options: MemoryIdempotencyStoreOptions = {}) {
     this.now = options.now ?? Date.now
+    this.maxEntries = options.maxEntries ?? 10_000
+    if (!Number.isInteger(this.maxEntries) || this.maxEntries < 1) {
+      throw new RangeError("idempotency: maxEntries must be a positive integer")
+    }
   }
 
-  begin(key: string, fingerprint: string, ttlMs: number): IdempotencyBeginResult {
-    const existing = this.entries.get(key)
+  begin(input: IdempotencyBeginInput): IdempotencyBeginResult {
+    const storageKey = this.storageKey(input)
+    const existing = this.entries.get(storageKey)
     if (existing !== undefined && existing.expiresAt > this.now()) {
-      if (existing.fingerprint !== fingerprint) return { state: "mismatch" }
+      if (existing.fingerprint !== input.fingerprint) return { state: "mismatch" }
       if (existing.response !== undefined) return { state: "replay", response: existing.response }
       return { state: "in-flight" }
     }
-    this.entries.set(key, {
-      fingerprint,
-      expiresAt: this.now() + ttlMs,
+    if (existing !== undefined) this.entries.delete(storageKey)
+    if (this.entries.size >= this.maxEntries) {
+      this.sweep()
+      if (this.entries.size >= this.maxEntries) return { state: "capacity" }
+    }
+    const reservation = crypto.randomUUID()
+    this.entries.set(storageKey, {
+      fingerprint: input.fingerprint,
+      reservation,
+      ttlMs: input.ttlMs,
+      expiresAt: this.now() + input.ttlMs,
       response: undefined,
     })
-    return { state: "new" }
+    return { state: "new", reservation }
   }
 
-  complete(key: string, response: StoredResponse): void {
+  complete(input: IdempotencyCompletionInput): boolean {
+    const key = this.storageKey(input)
     const entry = this.entries.get(key)
-    if (entry !== undefined) entry.response = response
+    if (entry === undefined || entry.reservation !== input.reservation) return false
+    if (entry.expiresAt <= this.now()) {
+      this.entries.delete(key)
+      return false
+    }
+    entry.response = input.response
+    entry.expiresAt = this.now() + entry.ttlMs
+    return true
   }
 
-  abandon(key: string): void {
+  abandon(input: IdempotencyAbandonInput): boolean {
+    const key = this.storageKey(input)
     const entry = this.entries.get(key)
+    if (entry !== undefined && entry.expiresAt <= this.now()) {
+      this.entries.delete(key)
+      return false
+    }
     // Only drop a still-pending reservation; never evict a completed (replayable) response.
-    if (entry !== undefined && entry.response === undefined) this.entries.delete(key)
+    if (
+      entry !== undefined &&
+      entry.response === undefined &&
+      entry.reservation === input.reservation
+    ) {
+      this.entries.delete(key)
+      return true
+    }
+    return false
   }
 
   /** Evict expired entries. Callers may run this on an interval; access-time eviction covers the rest. */
@@ -195,6 +406,10 @@ export class MemoryIdempotencyStore implements IdempotencyStore {
   get size(): number {
     return this.entries.size
   }
+
+  private storageKey(input: IdempotencyEntryKey): string {
+    return `${input.namespace.length}:${input.namespace}${input.key}`
+  }
 }
 
 /** Convenience factory mirroring the other core primitives' `create*` style. */

package/src/index.ts

@@ -12,17 +12,22 @@
  * (it shipped at "0.0.0" through 1.0.0 before those guards existed). Kept narrow (`as const`) so
  * consumers can pin it at the type level — see `test/version.test-d.ts`.
  */
-export const VERSION = "1.10.0" as const
+export const VERSION = "1.12.0" as const
 
 export type Version = typeof VERSION
 
 export * from "./assurance.ts"
 export * from "./capabilities.ts"
+export * from "./causality.ts"
 export * from "./classification.ts"
 export * from "./diff.ts"
 export { FrameworkError, RouteConfigError, type RouteConfigErrorCode } from "./errors.ts"
 export * from "./idempotency.ts"
 export { FRAMEWORK_NAME, type FrameworkName } from "./internal/brand.ts"
+export * from "./invariants.ts"
+export * from "./ledger.ts"
+export * from "./manifest.ts"
+export * from "./mount.ts"
 export * from "./reflection.ts"
 export { METHODS, type Method, Router, type RouterMatch } from "./router/router.ts"
 export type {