@nifrajs/core 5.7.0 → 5.9.0

package/src/server/http.ts

@@ -150,3 +150,15 @@ export function pathnameOf(url: string): string {
   }
   return url.slice(start, end)
 }
+
+/**
+ * A `Vary` header value (`null` when the response has none) that names each of `names` once, matched
+ * without regard to case. `Vary: *` already covers every request header, so it comes back unchanged.
+ */
+export function varyOn(value: string | null, names: readonly string[]): string {
+  if (value === null || value.trim() === "") return names.join(", ")
+  const fields = value.split(",").map((field) => field.trim().toLowerCase())
+  if (fields.includes("*")) return value
+  const missing = names.filter((name) => !fields.includes(name.toLowerCase()))
+  return missing.length === 0 ? value : `${value}, ${missing.join(", ")}`
+}

package/src/server/idempotency-lane.ts

@@ -35,6 +35,7 @@ import { markTransportCap, readBoundedBytes, transportCapOf, UNLIMITED_BODY_BYTE
 import type { Platform, RouteSchema } from "./context.ts"
 import { jsonError, urlPartsOf } from "./http.ts"
 import { INSTALL_IDEMPOTENCY } from "./install.ts"
+import { carryToCopy } from "./request-local.ts"
 import { CONTEXT_REQUEST, PRE_DECODED_BODY, preDecodedBody, requestOf } from "./runtime-core.ts"
 import type { AnyServer, IdentityPlugin, RawContext, RequestSource } from "./server.ts"
 
@@ -467,6 +468,7 @@ function prepareRequest(source: RequestSource, platform: Platform | undefined):
       duplex: "half",
     }
     prepared = new Request(request.url, init)
+    carryToCopy(request, prepared)
     const decoded = preDecodedBody(request)
     if (decoded !== undefined) Object.defineProperty(prepared, PRE_DECODED_BODY, { value: decoded })
   } catch (error) {

package/src/server/idle-timeout.ts

@@ -0,0 +1,107 @@
+/**
+ * `withIdleTimeout()`: one request's own idle timeout on a Bun `listen()` server, held while slow
+ * work runs and put back before the response goes out.
+ */
+import type { Context } from "./context.ts"
+import { CONTEXT_IDLE_TIMEOUT, getNeverAbortSignal } from "./runtime-core.ts"
+
+type MaybePromise<T> = T | Promise<T>
+
+type IdleTimeoutControl = (this: unknown, seconds: number | undefined) => boolean
+
+/** The `seconds` of every scope still running on a context. Deleted when the last one ends or the
+ * request is aborted, which also tells a scope ending after an abort to leave the socket alone. */
+const scopesOf = new WeakMap<object, number[]>()
+
+const longest = (scopes: readonly number[]): number =>
+  scopes.includes(0) ? 0 : Math.max(...scopes)
+
+/**
+ * Run `work` with the idle timeout of the request's connection set to `seconds` (`0` turns it off),
+ * then put back the listener's.
+ *
+ * Bun closes a connection that moves no bytes for `listen()`'s `idleTimeoutSec` seconds (10 by
+ * default), and a handler that is still working sends none, so an export or a long upstream call is
+ * cut mid-flight. Raising `idleTimeoutSec` raises it for every connection, idle keep-alive ones
+ * included; this raises it for one request. The listener's value is back before the response goes
+ * out because Bun keeps the last value on the socket for the requests that follow on it, so a value
+ * left in place would hold an idle connection open.
+ *
+ * The request's deadline (`requestTimeoutMs`, an inbound deadline) still bounds the response: when it
+ * fires, the 503 is sent with the listener's timeout back and `c.signal` aborts, but `work`
+ * keeps running unless it stops on that signal. Scopes nest: while several run on one request the
+ * longest applies, and `0` outlasts any number. `seconds` runs from 0 to 255, the longest Bun holds
+ * an idle connection; work that may idle longer takes `0`.
+ *
+ * A streamed response is sent after the handler returns, so call this inside the stream's producer
+ * to hold it until the last chunk. Off `listen()` - another adapter, `app.fetch` in a test - it runs
+ * `work` unchanged.
+ *
+ * @example
+ * ```ts
+ * import { withIdleTimeout } from "@nifrajs/core/idle-timeout"
+ *
+ * app.post("/exports", (c) => withIdleTimeout(c, 0, () => buildExport(c.body)))
+ * // Every route declared after this one:
+ * app.around((c, next) => withIdleTimeout(c, 120, next))
+ * ```
+ */
+export function withIdleTimeout<T>(
+  c: Context,
+  seconds: number,
+  work: () => MaybePromise<T>,
+): MaybePromise<T> {
+  if (!Number.isSafeInteger(seconds) || seconds < 0 || seconds > 255) {
+    throw new RangeError("withIdleTimeout: seconds must be an integer from 0 to 255")
+  }
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only RequestContext defines this key, with this signature; any other context leaves it undefined.
+  const control = (c as Context & { [CONTEXT_IDLE_TIMEOUT]?: IdleTimeoutControl })[
+    CONTEXT_IDLE_TIMEOUT
+  ]
+  const signal = c.signal
+  if (control === undefined || signal.aborted) return work()
+  const set = (value: number | undefined): void => {
+    control.call(c, value)
+  }
+  let scopes = scopesOf.get(c)
+  if (scopes === undefined) {
+    scopes = []
+    scopesOf.set(c, scopes)
+  }
+  const own = scopes
+  own.push(seconds)
+  set(longest(own))
+  // An abort is the deadline's 503 or a closed client: either way the response is final, so the
+  // listener's timeout goes back now rather than when the abandoned work settles.
+  const abort = (): void => {
+    if (scopesOf.get(c) !== own) return
+    scopesOf.delete(c)
+    set(undefined)
+  }
+  // The never-abort signal is one object shared by every request without a deadline.
+  const listens = signal !== getNeverAbortSignal()
+  if (listens) signal.addEventListener("abort", abort, { once: true })
+  const end = (): void => {
+    if (listens) signal.removeEventListener("abort", abort)
+    if (scopesOf.get(c) !== own) return
+    own.splice(own.indexOf(seconds), 1)
+    if (own.length > 0) {
+      set(longest(own))
+      return
+    }
+    scopesOf.delete(c)
+    set(undefined)
+  }
+  let result: MaybePromise<T>
+  try {
+    result = work()
+  } catch (err) {
+    end()
+    throw err
+  }
+  if (!(result instanceof Promise)) {
+    end()
+    return result
+  }
+  return result.finally(end)
+}

package/src/server/json-shared.ts

@@ -0,0 +1,38 @@
+/**
+ * What core's JSON walks share besides the writer: the `Date` hooks the response contract reads, the
+ * `__proto__`-safe field setter, and the plain-record tests canonical JSON uses. Apart from
+ * `json-text.ts` so the Node adapter's generated copy of that module holds only the writer.
+ */
+
+export const DATE_TO_JSON = Date.prototype.toJSON
+// What `Date.prototype.toJSON` reads a `Date`'s time value through.
+const DATE_TO_PRIMITIVE = Date.prototype[Symbol.toPrimitive]
+const DATE_VALUE_OF = Date.prototype.valueOf
+
+/**
+ * Whether `date` reaches the `@@toPrimitive` and `valueOf` that `Date.prototype.toJSON` reads its time
+ * value through as they ship, on itself, its class or `Date.prototype`. Then its steps, taken by the
+ * caller, give what the call would: `null` for a time value that is not finite, else what its
+ * `toISOString` answers, called through it as `toJSON` calls it.
+ */
+export const readsShippedTime = (date: Date): boolean =>
+  date[Symbol.toPrimitive] === DATE_TO_PRIMITIVE && date.valueOf === DATE_VALUE_OF
+
+/** Sets `key` on `out` as an own field, `__proto__` included, which an assignment takes as the prototype. */
+export function define(out: Record<string, unknown>, key: string, value: unknown): void {
+  if (key === "__proto__")
+    Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true })
+  else out[key] = value
+}
+
+// biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the member is optional, so an engine without JSON.rawJSON leaves it undefined.
+export const isRawJson = (JSON as JSON & { readonly isRawJSON?: (value: unknown) => boolean })
+  .isRawJSON
+
+/**
+ * Whether `proto` is a plain record's prototype: `Object.prototype`, `null`, or any prototype whose own
+ * prototype is null, which admits another realm's plain object. A boxed primitive's or a class's is
+ * not. A `JSON.rawJSON` value's is `null` too, so a caller tells one apart first.
+ */
+export const isPlainPrototype = (proto: unknown): boolean =>
+  proto === null || proto === Object.prototype || Object.getPrototypeOf(proto) === null

package/src/server/json-text.ts

@@ -3,7 +3,7 @@
  * id answered a 500. Every plain JSON writer goes through this instead: a `bigint` is written as its
  * decimal string, the encoding OpenAPI generators and protobuf's JSON mapping use for 64-bit integers.
  * Only a first attempt that threw is retried, so a value without one costs nothing more. The Node
- * adapter runs a generated copy (scripts/gen-node-outcome.ts), so this module imports nothing.
+ * adapter runs a generated copy (scripts/gen-vendored.ts), so this module imports nothing.
  */
 
 const bigintAsText = (_key: string, value: unknown): unknown =>

package/src/server/node-outcome.ts

@@ -109,7 +109,7 @@ export function plainNodeOutcome(plain: PlainRender, set: CtxSet): NodeServeOutc
   return {
     kind: "json",
     status: plain.status,
-    headers: plainRenderHeaders(plain, set),
+    headers: plainRenderHeaders(plain.headers, set._headers),
     cookies: set._cookies,
     body: plain.body === undefined || isBodylessStatus(plain.status) ? null : jsonText(plain.body),
   }

package/src/server/request-context.ts

@@ -17,7 +17,12 @@ import { jsonText } from "./json-text.ts"
 import type { ProtoPoisoning } from "./proto-guard.ts"
 import { searchOf } from "./query.ts"
 import { residentText, responseJsonContentType } from "./respond.ts"
+import type {
+  ResponseContractDefinition,
+  ResponseContractRuntime,
+} from "./response-contract-lane.ts"
 import {
+  CONTEXT_IDLE_TIMEOUT,
   CONTEXT_REQUEST,
   CONTEXT_SEARCH,
   CONTEXT_SET,
@@ -166,8 +171,40 @@ const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8"
  * handler never reads it costs the adapter neither a lookup nor a platform object of its own. */
 export const PLATFORM_PEER = Symbol()
 
+/** Where a Bun listener leaves the idle timeout of a request's connection: called with the request
+ * and the seconds to allow, or `undefined` to put back the listener's own. */
+export const PLATFORM_IDLE_TIMEOUT = Symbol()
+
+/** The request the adapter received, on a platform made for one request: the routed source may be a
+ * rewritten or stripped copy, which Bun does not know. */
+export const PLATFORM_REQUEST = Symbol()
+
 export type PeerPlatform = Platform & {
   readonly [PLATFORM_PEER]?: (source: RequestSource) => string | undefined
+  readonly [PLATFORM_IDLE_TIMEOUT]?: (source: RequestSource, seconds: number | undefined) => void
+  readonly [PLATFORM_REQUEST]?: RequestSource
+}
+
+/**
+ * Whether merging `decorations` into a context can complete. A decoration named for a read-only
+ * accessor of the context (`req`, `set`, `signal`) makes `Object.assign` throw on every request, a
+ * failure the general program routes to the route's error hooks and a fused lane would not.
+ */
+export function decorationsAssignable(decorations: Record<PropertyKey, unknown>): boolean {
+  for (const key of Reflect.ownKeys(decorations)) {
+    for (
+      let proto: object | null = RequestContext.prototype;
+      proto !== null && proto !== Object.prototype;
+      proto = Object.getPrototypeOf(proto)
+    ) {
+      const descriptor = Object.getOwnPropertyDescriptor(proto, key)
+      if (descriptor === undefined) continue
+      if (descriptor.get !== undefined && descriptor.set === undefined) return false
+      if (descriptor.writable === false) return false
+      break
+    }
+  }
+  return true
 }
 
 export class RequestContext implements RawContext {
@@ -190,6 +227,13 @@ export class RequestContext implements RawContext {
   private declare cookiesValue: Readonly<Record<string, string>> | undefined
   declare jsonReply: Response | undefined
   declare jsonBody: unknown
+  /** The route's response contract, if it has one, for {@link json} to write by. */
+  declare jsonContract:
+    | {
+        readonly runtime: ResponseContractRuntime
+        readonly definition: ResponseContractDefinition
+      }
+    | undefined
   private declare readonly source: RequestSource
   private declare readonly maxBodyBytes: number
   private declare readonly protoPoisoning: ProtoPoisoning
@@ -264,6 +308,14 @@ export class RequestContext implements RawContext {
     return requestOf(this.source)
   }
 
+  [CONTEXT_IDLE_TIMEOUT](seconds: number | undefined): boolean {
+    const platform = this.platformValue
+    const set = platform?.[PLATFORM_IDLE_TIMEOUT]
+    if (set === undefined) return false
+    set(platform?.[PLATFORM_REQUEST] ?? this.source, seconds)
+    return true
+  }
+
   get [CONTEXT_SEARCH](): string {
     this.searchValue ??= searchOf(this.source.url)
     return this.searchValue
@@ -336,6 +388,13 @@ export class RequestContext implements RawContext {
    */
   json(body: unknown, init?: ResponseInit | number): Response {
     const i = statusInit(init)
+    // A contracted route's value is written here once, as its contract judges it: the bytes and the
+    // check share one call of each `toJSON` hook, a `Date`'s included.
+    const contract = this.jsonContract
+    const value =
+      contract?.runtime.write === undefined
+        ? body
+        : contract.runtime.write(contract.definition, body, i?.status)
     let reply: Response | undefined
     if (DEFERS_RESPONSE) {
       const defer = deferredResponderFor()
@@ -344,17 +403,17 @@ export class RequestContext implements RawContext {
       // (`undefined`, a function, a symbol) - exactly the case where `Response.json` throws, so it
       // gets the throw rather than an invented body. The content-type is the runtime's own, read
       // off `Response.json` once, so a deferred response carries the same one byte for byte.
-      const text = defer === undefined ? undefined : (jsonText(body) as string | undefined)
+      const text = defer === undefined ? undefined : (jsonText(value) as string | undefined)
       const headers =
         text === undefined ? undefined : ownHeaderRecord(i?.headers, responseJsonContentType())
       if (defer !== undefined && text !== undefined && headers !== undefined) {
         reply = defer(text, i?.status ?? 200, headers)
       }
     }
-    reply ??= markResidentBody(jsonResponse(body, i))
+    reply ??= markResidentBody(jsonResponse(value, i))
     // Remembered so a response contract holds the value to the route's schema: this is the
     // framework's JSON helper, not a raw-Response escape hatch.
-    this.jsonBody = body
+    this.jsonBody = value
     this.jsonReply = reply
     return reply
   }

package/src/server/request-local.ts

@@ -0,0 +1,109 @@
+/**
+ * Request-local state: a value tied to one request that follows it through the copies made of it.
+ * A `WeakMap<Request, T>` loses its value at the first `new Request(url, req)`, and nifra itself
+ * rebuilds a request when a mount strips its prefix, when a WebSocket pass is reused for HTTP, and
+ * when a target is resolved. Every such copy joins the request's scope, so each reads and writes
+ * the same values.
+ */
+
+/** One request-local slot from {@link requestLocal}. */
+export interface RequestLocal<T> {
+  /** The value set through `request` or any request in its scope, else `undefined`. */
+  get(request: Request): T | undefined
+  /** Set the value for `request`'s whole scope. */
+  set(request: Request, value: T): void
+  has(request: Request): boolean
+  /** Remove the value from `request`'s scope; `true` when there was one. */
+  delete(request: Request): boolean
+}
+
+type Values = Map<object, unknown>
+
+/**
+ * A copy maps to the request it was made from, and the end of that chain (the anchor) to its
+ * scope's values once one is set. Keyed in the global symbol registry so two copies of core keep
+ * one table, and weak, so a scope lives exactly as long as a request in it.
+ */
+type Links = WeakMap<Request, Request | Values>
+
+// biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion lint/plugin/noChainedTypeAssertions: only this module writes the slot, and only a Links table.
+const shared = globalThis as unknown as Record<symbol, Links | undefined>
+const LINKS = Symbol.for("nifra.requestLocals")
+
+const linksOf = (): Links => (shared[LINKS] ??= new WeakMap())
+
+/** The request at the end of `request`'s chain of copies. */
+function anchorOf(links: Links, request: Request): Request {
+  let anchor = request
+  let link = links.get(anchor)
+  while (link !== undefined && !(link instanceof Map)) {
+    anchor = link
+    link = links.get(anchor)
+  }
+  return anchor
+}
+
+/** `to` was just built from `from`, with nothing set on it: it joins `from`'s scope. Until a first
+ * slot makes the table there is no scope to join, and a copy records nothing. */
+export function carryToCopy(from: Request, to: Request): void {
+  shared[LINKS]?.set(to, from)
+}
+
+/**
+ * Join `to` to `from`'s request-local scope: each then reads every value set through either, now
+ * and later. nifra does this wherever it rebuilds a request itself; call it where a wrapper or an
+ * `onRequest` hook rebuilds one, right after `new Request(url, req)`. A value `to` already holds is
+ * kept where `from` has none.
+ */
+export function carryRequestLocals(from: Request, to: Request): void {
+  const links = shared[LINKS]
+  if (links === undefined) return
+  const target = anchorOf(links, from)
+  const joining = anchorOf(links, to)
+  if (target === joining) return
+  const own = links.get(joining)
+  links.set(joining, target)
+  if (!(own instanceof Map)) return
+  const held = links.get(target)
+  if (!(held instanceof Map)) links.set(target, own)
+  else for (const [key, value] of own) if (!held.has(key)) held.set(key, value)
+}
+
+function valuesOf(request: Request, create: boolean): Values | undefined {
+  const links = linksOf()
+  const anchor = anchorOf(links, request)
+  const held = links.get(anchor)
+  if (held instanceof Map || !create) return held instanceof Map ? held : undefined
+  const fresh: Values = new Map()
+  links.set(anchor, fresh)
+  return fresh
+}
+
+/**
+ * A slot for one per-request value - a verified client IP, a request id, an auth decision - that
+ * survives the request copies nifra makes (a mount's prefix strip, a WebSocket pass reused for HTTP,
+ * target resolution) and the ones a wrapper makes with {@link carryRequestLocals}. A copy made any
+ * other way starts empty. Values are held weakly and never cross requests. Make slots at startup, as
+ * below: copies are linked only once a first slot exists, so a request copied before then starts
+ * empty.
+ *
+ * ```ts
+ * const clientIp = requestLocal<string>()
+ * app.onRequest((req, platform) => { clientIp.set(req, platform?.clientIp ?? "") })
+ * // ... in a mounted child app, after the prefix strip:
+ * clientIp.get(c.req)
+ * ```
+ */
+export function requestLocal<T>(): RequestLocal<T> {
+  linksOf()
+  const key = {}
+  return {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only `set` below writes `key`, and only a T.
+    get: (request) => valuesOf(request, false)?.get(key) as T | undefined,
+    set: (request, value) => {
+      valuesOf(request, true)?.set(key, value)
+    },
+    has: (request) => valuesOf(request, false)?.has(key) === true,
+    delete: (request) => valuesOf(request, false)?.delete(key) === true,
+  }
+}

package/src/server/respond.ts

@@ -39,7 +39,7 @@ function headersInit(set: CtxSet): Record<string, string> | Headers | undefined
 function plainRenderSet(plain: PlainRender, set: CtxSet): CtxSet {
   return {
     status: plain.status,
-    _headers: plainRenderHeaders(plain, set),
+    _headers: plainRenderHeaders(plain.headers, set._headers),
     _cookies: set._cookies,
   } as CtxSet
 }