@nifrajs/core 2.9.0 → 2.10.0

package/src/range.ts

@@ -0,0 +1,94 @@
+/**
+ * `Range: bytes=...` parsing - the shared owner for every byte-range surface in the framework.
+ *
+ * This lives in core rather than in the middleware package because two unrelated layers need the
+ * exact same answer: `@nifrajs/middleware`'s `rangeResponse` for caller-owned buffers, and
+ * `@nifrajs/web`'s `public/` static handler for files on disk. A second implementation that happens
+ * to agree today is how a media server ends up serving byte 0 of a seek request in one code path and
+ * byte N in the other.
+ *
+ * The input is request-controlled on every call, so the parser is bounded before it is clever: a
+ * capped header length and a capped specifier count keep a malformed range-set from turning a sort
+ * and merge into an allocation amplifier.
+ */
+
+export interface ByteRange {
+  readonly start: number
+  readonly end: number
+}
+
+export type ByteRangeResult =
+  | { readonly kind: "none" }
+  | { readonly kind: "unsatisfiable" }
+  | { readonly kind: "satisfiable"; readonly ranges: readonly ByteRange[] }
+
+const INTEGER = /^(?:0|[1-9]\d*)$/
+const MAX_RANGE_HEADER_LENGTH = 16 * 1024
+const MAX_RANGE_SPECIFIERS = 16
+
+function validSize(size: number): void {
+  if (!Number.isSafeInteger(size) || size < 0) {
+    throw new RangeError("parseByteRange: size must be a non-negative safe integer")
+  }
+}
+
+/**
+ * Parse an HTTP `Range: bytes=...` header against a known representation size.
+ *
+ * Three outcomes, and the distinction matters to the caller's status code: `none` means the header
+ * was absent or syntactically invalid and must be ignored (200), `unsatisfiable` means a well-formed
+ * range-set selected nothing (416), `satisfiable` carries the coalesced ranges (206).
+ */
+export function parseByteRange(value: string | null, size: number): ByteRangeResult {
+  validSize(size)
+  if (value === null) return { kind: "none" }
+  const match = /^bytes\s*=\s*(.+)$/i.exec(value)
+  if (match === null) return { kind: "none" }
+  const source = match[1]!
+  if (source.length > MAX_RANGE_HEADER_LENGTH) return { kind: "none" }
+  let separators = 0
+  for (const character of source) {
+    if (character === "," && ++separators >= MAX_RANGE_SPECIFIERS) return { kind: "none" }
+  }
+
+  const ranges: ByteRange[] = []
+  let validRangeSpec = false
+  for (const raw of source.split(",")) {
+    const item = raw.trim()
+    const dash = item.indexOf("-")
+    if (dash < 0) continue
+    const left = item.slice(0, dash).trim()
+    const right = item.slice(dash + 1).trim()
+    if (left === "" && (!INTEGER.test(right) || right === "0")) continue
+    if (left !== "" && !INTEGER.test(left)) continue
+    if (right !== "" && !INTEGER.test(right)) continue
+    validRangeSpec = true
+
+    let start: number
+    let end: number
+    if (left === "") {
+      const suffix = Number(right)
+      start = suffix >= size ? 0 : size - suffix
+      end = size - 1
+    } else {
+      start = Number(left)
+      end = right === "" ? size - 1 : Math.min(Number(right), size - 1)
+    }
+    if (start > end || start >= size || size === 0) continue
+    ranges.push({ start, end })
+  }
+
+  // A syntactically invalid Range header is ignored; a valid range-set with no overlap is 416.
+  if (ranges.length === 0) return validRangeSpec ? { kind: "unsatisfiable" } : { kind: "none" }
+  ranges.sort((a, b) => a.start - b.start || a.end - b.end)
+  const merged: ByteRange[] = []
+  for (const range of ranges) {
+    const previous = merged[merged.length - 1]
+    if (previous !== undefined && range.start <= previous.end + 1) {
+      merged[merged.length - 1] = { start: previous.start, end: Math.max(previous.end, range.end) }
+    } else {
+      merged.push(range)
+    }
+  }
+  return { kind: "satisfiable", ranges: merged }
+}

package/src/router/router.ts

@@ -230,7 +230,9 @@ function resolve<T>(
     const upper = method.toUpperCase()
     const cached = upper === method ? undefined : terminal.staticMatches.get(upper)
     if (cached !== undefined) return cached
-    if (!terminal.handlers.has(upper)) return resolveDirect(terminal, method, params)
+    const cacheable =
+      terminal.handlers.has(upper) || (upper === "HEAD" && terminal.handlers.has("GET"))
+    if (!cacheable) return resolveDirect(terminal, method, params)
 
     const res = resolveDirect(terminal, method, params)
     terminal.staticMatches.set(upper, res)
@@ -248,11 +250,20 @@ function resolveDirect<T>(
     return { found: true, payload: terminal.handlers.get(method)!, params }
   }
   const upper = method.toUpperCase()
-  if (upper === method || !terminal.handlers.has(upper)) {
-    return { found: false, reason: "method-not-allowed", allowed: [...terminal.handlers.keys()] }
+  if (upper !== method && terminal.handlers.has(upper)) {
+    return { found: true, payload: terminal.handlers.get(upper)!, params }
   }
-  const payload = terminal.handlers.get(upper)! // present by the has() check above
-  return { found: true, payload, params }
+  // RFC 9110 §9.3.2: HEAD is GET without the body. A route registered for GET answers HEAD with
+  // the GET handler; the serving runtime strips the body, so status + headers mirror GET exactly.
+  // An explicitly registered HEAD handler takes precedence via the has() checks above.
+  if (upper === "HEAD") {
+    const get = terminal.handlers.get("GET")
+    if (get !== undefined) return { found: true, payload: get, params }
+  }
+  const allowed = [...terminal.handlers.keys()]
+  // Advertise the implicit HEAD support granted above.
+  if (terminal.handlers.has("GET") && !terminal.handlers.has("HEAD")) allowed.push("HEAD")
+  return { found: false, reason: "method-not-allowed", allowed }
 }
 
 /**

package/src/server/platform-adapters.ts

@@ -0,0 +1,255 @@
+/**
+ * Thin adapters for platforms that do not expose a Web `fetch` handler directly.
+ *
+ * The app remains a Web-standard handler. These adapters only translate the platform event envelope;
+ * they do not own identity, persistence, retries, or platform credentials.
+ */
+
+import type { Platform } from "./context.ts"
+import type { MaybePromise } from "./server.ts"
+
+export interface FetchApp<Env = unknown> {
+  fetch(request: Request, platform?: Platform<Env>): MaybePromise<Response>
+}
+
+export type VercelHandler = (request: Request) => MaybePromise<Response>
+
+/** Adapt a Web-standard app to a Vercel Edge Function default export. */
+export function toVercelHandler<Env = unknown>(app: FetchApp<Env>): VercelHandler {
+  return (request) => app.fetch(request)
+}
+
+type HeaderValue = string | readonly string[] | undefined
+type HeaderRecord = Readonly<Record<string, HeaderValue>>
+
+function decodeBase64(value: string): Uint8Array<ArrayBuffer> {
+  const binary = atob(value)
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length))
+  for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index)
+  return bytes
+}
+
+function encodeBase64(bytes: Uint8Array): string {
+  let binary = ""
+  for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000))
+  }
+  return btoa(binary)
+}
+
+function headersFromRecords(
+  single: HeaderRecord | undefined,
+  multi: HeaderRecord | undefined,
+): Headers {
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(single ?? {})) {
+    if (value === undefined) continue
+    for (const item of Array.isArray(value) ? value : [value]) headers.append(name, item)
+  }
+  for (const [name, value] of Object.entries(multi ?? {})) {
+    headers.delete(name)
+    if (value === undefined) continue
+    for (const item of Array.isArray(value) ? value : [value]) headers.append(name, item)
+  }
+  return headers
+}
+
+function absoluteUrl(
+  raw: string | undefined,
+  path: string,
+  query: string | undefined,
+  headers: Headers,
+): string {
+  if (raw !== undefined) {
+    try {
+      return new URL(raw).toString()
+    } catch {
+      // Fall through to the structured event fields.
+    }
+  }
+  const host = headers.get("host") ?? "nifra.invalid"
+  const url = new URL(path || "/", `https://${host}`)
+  if (query !== undefined && query !== "") url.search = query.startsWith("?") ? query : `?${query}`
+  return url.toString()
+}
+
+function requestBody(
+  body: string | null | undefined,
+  encoded: boolean | undefined,
+): string | Uint8Array<ArrayBuffer> | undefined {
+  if (body === undefined || body === null) return undefined
+  return encoded === true ? decodeBase64(body) : body
+}
+
+/**
+ * Every `set-cookie` on a response, as separate values.
+ *
+ * `Headers.forEach` and `Headers.get` collapse repeated `set-cookie` into one comma-joined string,
+ * and a cookie's `Expires` attribute contains a comma - so the joined form cannot be split back
+ * apart, and a plain record keyed by header name keeps only one cookie regardless. Both platforms
+ * have a dedicated channel for this; `getSetCookie` is how we fill it.
+ */
+function setCookiesOf(headers: Headers): readonly string[] {
+  const getSetCookie = (headers as { getSetCookie?: () => string[] }).getSetCookie
+  if (typeof getSetCookie === "function") return getSetCookie.call(headers)
+  const single = headers.get("set-cookie")
+  return single === null ? [] : [single]
+}
+
+async function platformResponse(
+  response: Response,
+  /** `cookies` is API Gateway v2's dedicated array; v1 and Netlify carry them in multi-value headers. */
+  cookieChannel: "cookies" | "multiValueHeaders",
+): Promise<PlatformResponse> {
+  const bytes = new Uint8Array(await response.arrayBuffer())
+  const headers: Record<string, string> = {}
+  response.headers.forEach((value, name) => {
+    if (name.toLowerCase() === "set-cookie") return
+    headers[name] = value
+  })
+  const cookies = setCookiesOf(response.headers)
+  return {
+    statusCode: response.status,
+    headers,
+    ...(cookies.length === 0
+      ? {}
+      : cookieChannel === "cookies"
+        ? { cookies }
+        : { multiValueHeaders: { "set-cookie": cookies } }),
+    body: encodeBase64(bytes),
+    isBase64Encoded: true,
+  }
+}
+
+export interface NetlifyEvent {
+  readonly httpMethod: string
+  readonly path: string
+  readonly rawUrl?: string
+  readonly rawQuery?: string
+  readonly headers?: HeaderRecord
+  readonly multiValueHeaders?: HeaderRecord
+  readonly body?: string | null
+  readonly isBase64Encoded?: boolean
+  readonly cookies?: readonly string[]
+}
+
+export interface PlatformResponse {
+  readonly statusCode: number
+  /** Single-valued headers. `set-cookie` never appears here - see the two fields below. */
+  readonly headers: Readonly<Record<string, string>>
+  /**
+   * Repeated headers, currently only `set-cookie`. Netlify Functions and API Gateway REST (v1) read
+   * this; omitted when the response sets no cookies.
+   */
+  readonly multiValueHeaders?: Readonly<Record<string, readonly string[]>>
+  /** API Gateway HTTP API (v2) takes cookies here rather than in a header. Omitted when there are none. */
+  readonly cookies?: readonly string[]
+  readonly body: string
+  readonly isBase64Encoded: true
+}
+
+export type NetlifyHandler = (event: NetlifyEvent) => Promise<PlatformResponse>
+
+/** Adapt a Web-standard app to a Netlify Functions event handler. */
+export function toNetlifyHandler<Env = unknown>(app: FetchApp<Env>): NetlifyHandler {
+  return async (event) => {
+    const headers = headersFromRecords(event.headers, event.multiValueHeaders)
+    if (event.cookies !== undefined && !headers.has("cookie")) {
+      headers.set("cookie", event.cookies.join("; "))
+    }
+    const init: RequestInit = {
+      method: event.httpMethod,
+      headers,
+    }
+    const body = requestBody(event.body, event.isBase64Encoded)
+    if (body !== undefined) init.body = body
+    const request = new Request(
+      absoluteUrl(event.rawUrl, event.path, event.rawQuery, headers),
+      init,
+    )
+    return platformResponse(await app.fetch(request), "multiValueHeaders")
+  }
+}
+
+export interface LambdaV2Event {
+  readonly version?: "2.0"
+  readonly rawPath?: string
+  readonly rawQueryString?: string
+  readonly headers?: HeaderRecord
+  readonly cookies?: readonly string[]
+  readonly body?: string | null
+  readonly isBase64Encoded?: boolean
+  readonly requestContext?: {
+    readonly domainName?: string
+    readonly http?: { readonly method: string; readonly path?: string }
+  }
+}
+
+export interface LambdaV1Event {
+  readonly httpMethod: string
+  readonly path: string
+  readonly headers?: HeaderRecord
+  readonly multiValueHeaders?: HeaderRecord
+  readonly queryStringParameters?: Readonly<Record<string, string | undefined>>
+  readonly multiValueQueryStringParameters?: Readonly<Record<string, readonly string[] | undefined>>
+  readonly body?: string | null
+  readonly isBase64Encoded?: boolean
+  readonly requestContext?: { readonly domainName?: string }
+}
+
+export type LambdaEvent = LambdaV2Event | LambdaV1Event
+export type LambdaResponse = PlatformResponse
+export type LambdaHandler = (event: LambdaEvent, context?: unknown) => Promise<LambdaResponse>
+
+function isLambdaV2(event: LambdaEvent): event is LambdaV2Event {
+  return "version" in event || "rawPath" in event || "rawQueryString" in event
+}
+
+function queryFromLambdaV1(event: LambdaV1Event): string {
+  const params = new URLSearchParams()
+  for (const [name, value] of Object.entries(event.multiValueQueryStringParameters ?? {})) {
+    for (const item of value ?? []) params.append(name, item)
+  }
+  for (const [name, value] of Object.entries(event.queryStringParameters ?? {})) {
+    if (value !== undefined && !params.has(name)) params.set(name, value)
+  }
+  return params.toString()
+}
+
+/** Adapt API Gateway HTTP API (v2) and REST API (v1) events to a Web-standard app. */
+export function toLambdaHandler<Env = unknown>(app: FetchApp<Env>): LambdaHandler {
+  return async (event) => {
+    const v2 = isLambdaV2(event)
+    const headers = headersFromRecords(event.headers, v2 ? undefined : event.multiValueHeaders)
+    let path: string
+    let query: string
+    let method: string
+    let rawUrl: string | undefined
+    if (v2) {
+      method = event.requestContext?.http?.method ?? "GET"
+      path = event.rawPath ?? event.requestContext?.http?.path ?? "/"
+      query = event.rawQueryString ?? ""
+      const domain = event.requestContext?.domainName
+      rawUrl =
+        domain === undefined ? undefined : `https://${domain}${path}${query ? `?${query}` : ""}`
+      if (event.cookies !== undefined && !headers.has("cookie"))
+        headers.set("cookie", event.cookies.join("; "))
+    } else {
+      method = event.httpMethod
+      path = event.path
+      query = queryFromLambdaV1(event)
+      const domain = event.requestContext?.domainName
+      rawUrl =
+        domain === undefined ? undefined : `https://${domain}${path}${query ? `?${query}` : ""}`
+    }
+    const body = event.body
+    const init: RequestInit = {
+      method,
+      headers,
+    }
+    const requestBodyValue = requestBody(body, event.isBase64Encoded)
+    if (requestBodyValue !== undefined) init.body = requestBodyValue
+    const request = new Request(absoluteUrl(rawUrl, path, query, headers), init)
+    return platformResponse(await app.fetch(request), v2 ? "cookies" : "multiValueHeaders")
+  }
+}

package/src/server/server.ts

@@ -2501,7 +2501,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   ): MaybePromise<T> {
     const hooks = this.onRequestHooks
     const originalRequest = requestOf(source)
-    this.responseSources.set(source as object, originalRequest)
+    // A Web Request is already the exact object visible to the hooks and the response walk. Only
+    // adapter sources need the source→request mapping; avoiding the WeakMap write keeps the common
+    // Bun/Deno/edge lifecycle allocation-light while preserving Node's lazy Request identity.
+    if (source !== originalRequest) this.responseSources.set(source as object, originalRequest)
     let current: RequestSource = source
     for (let i = 0; i < hooks.length; i++) {
       const outcome = (hooks[i] as RawOnRequest)(requestOf(current), platform)
@@ -4447,7 +4450,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       )
       count += 1
     }
-    return count === 0 ? undefined : routes
+    if (count === 0) return undefined
+    // RFC 9110 §9.3.2: a GET route answers HEAD with identical status + headers (Bun strips the
+    // body on the wire). Alias the compiled GET handler under HEAD so HEAD stays on the native
+    // lane instead of falling through to the portable dispatcher; the router applies the same
+    // fallback there, so both lanes agree. An explicit HEAD registration wins via the ??=.
+    for (const path of Object.keys(routes)) {
+      const methods = routes[path]!
+      if (methods.GET !== undefined) methods.HEAD ??= methods.GET
+    }
+    return routes
   }
 
   /**

package/src/server.ts

@@ -53,6 +53,21 @@ export {
   redactLogFields,
   silentLogger,
 } from "./server/logger.ts"
+export {
+  type FetchApp,
+  type LambdaEvent,
+  type LambdaHandler,
+  type LambdaResponse,
+  type LambdaV1Event,
+  type LambdaV2Event,
+  type NetlifyEvent,
+  type NetlifyHandler,
+  type PlatformResponse,
+  toLambdaHandler,
+  toNetlifyHandler,
+  toVercelHandler,
+  type VercelHandler,
+} from "./server/platform-adapters.ts"
 export type { Registry, RouteInfo } from "./server/registry.ts"
 export {
   type AdmissionController,