@nifrajs/middleware 2.9.1 → 2.10.0

package/src/multipart.ts

@@ -0,0 +1,166 @@
+export type MultipartBody =
+  | string
+  | Uint8Array
+  | ArrayBuffer
+  | ArrayBufferView
+  | Blob
+  | ReadableStream<Uint8Array>
+
+export type MultipartHeadersInit =
+  | Headers
+  | Readonly<Record<string, string>>
+  | ReadonlyArray<readonly [string, string]>
+
+export interface MultipartPart {
+  readonly headers?: MultipartHeadersInit
+  readonly body: MultipartBody
+}
+
+export interface MultipartResponseOptions {
+  /** Boundary token. If omitted, a cryptographically random boundary is generated. */
+  readonly boundary?: string
+  /** Multipart subtype. Defaults to `mixed`; use `form-data` when parts carry form names. */
+  readonly subtype?: "mixed" | "form-data"
+  /** HTTP response status. Defaults to 200. */
+  readonly status?: number
+}
+
+const TEXT = new TextEncoder()
+const BOUNDARY = /^[A-Za-z0-9'()+_,./:=? -]{1,70}$/
+
+interface ActiveReader {
+  current: ReadableStreamDefaultReader<Uint8Array> | undefined
+}
+
+function validateBoundary(value: string): string {
+  if (!BOUNDARY.test(value) || value.endsWith(" ")) {
+    throw new TypeError("multipartResponse: boundary must be a valid RFC token")
+  }
+  return value
+}
+
+function headersOf(init: MultipartHeadersInit | undefined): Headers {
+  const headers = new Headers()
+  if (init instanceof Headers) {
+    for (const [name, value] of init) headers.set(name, value)
+  } else if (Array.isArray(init)) {
+    for (const [name, value] of init) headers.append(name, value)
+  } else if (init !== undefined) {
+    for (const [name, value] of Object.entries(init)) headers.append(name, value)
+  }
+  for (const [name, value] of headers) {
+    if (hasHeaderControlCharacter(name) || hasHeaderControlCharacter(value)) {
+      throw new TypeError("multipartResponse: part headers cannot contain control characters")
+    }
+  }
+  return headers
+}
+
+function hasHeaderControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    // HTAB is the only C0 control permitted in an HTTP field value. Reject the rest, including
+    // DEL, so a caller cannot smuggle non-printing bytes into a multipart header line.
+    if ((code <= 31 && code !== 9) || code === 127) return true
+  }
+  return false
+}
+
+async function* bodyChunks(
+  body: MultipartBody,
+  activeReader: ActiveReader,
+): AsyncGenerator<Uint8Array> {
+  if (typeof body === "string") {
+    yield TEXT.encode(body)
+    return
+  }
+  if (body instanceof Uint8Array) {
+    yield body
+    return
+  }
+  if (body instanceof ArrayBuffer) {
+    yield new Uint8Array(body)
+    return
+  }
+  if (ArrayBuffer.isView(body)) {
+    yield new Uint8Array(body.buffer, body.byteOffset, body.byteLength)
+    return
+  }
+  const stream = body instanceof Blob ? body.stream() : body
+  const reader = stream.getReader() as ReadableStreamDefaultReader<Uint8Array>
+  activeReader.current = reader
+  let completed = false
+  try {
+    while (true) {
+      const result = await reader.read()
+      if (result.done) {
+        completed = true
+        return
+      }
+      yield result.value
+    }
+  } finally {
+    if (activeReader.current === reader) activeReader.current = undefined
+    if (!completed) await reader.cancel().catch(() => {})
+    reader.releaseLock()
+  }
+}
+
+async function* encodeParts(
+  parts: Iterable<MultipartPart> | AsyncIterable<MultipartPart>,
+  boundary: string,
+  activeReader: ActiveReader,
+): AsyncGenerator<Uint8Array> {
+  for await (const part of parts) {
+    if (part === null || typeof part !== "object") {
+      throw new TypeError("multipartResponse: every part must be an object")
+    }
+    yield TEXT.encode(`--${boundary}\r\n`)
+    for (const [name, value] of headersOf(part.headers)) {
+      yield TEXT.encode(`${name}: ${value}\r\n`)
+    }
+    yield TEXT.encode("\r\n")
+    yield* bodyChunks(part.body, activeReader)
+    yield TEXT.encode("\r\n")
+  }
+  yield TEXT.encode(`--${boundary}--\r\n`)
+}
+
+/**
+ * Stream a multipart response without buffering the parts. The part headers and bodies are emitted
+ * as supplied; this helper deliberately does not persist, inspect, or serialize payloads.
+ */
+export function multipartResponse(
+  parts: Iterable<MultipartPart> | AsyncIterable<MultipartPart>,
+  options: MultipartResponseOptions = {},
+): Response {
+  const boundary = validateBoundary(
+    options.boundary ?? `nifra-${crypto.randomUUID().replaceAll("-", "")}`,
+  )
+  const subtype = options.subtype ?? "mixed"
+  const activeReader: ActiveReader = { current: undefined }
+  const iterator = encodeParts(parts, boundary, activeReader)[Symbol.asyncIterator]()
+  const stream = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await iterator.next()
+        if (result.done) controller.close()
+        else controller.enqueue(result.value)
+      } catch (error) {
+        const reader = activeReader.current
+        if (reader !== undefined) await reader.cancel(error).catch(() => {})
+        await iterator.return?.(error)
+        controller.error(error)
+      }
+    },
+    async cancel(reason) {
+      const reader = activeReader.current
+      if (reader !== undefined) await reader.cancel(reason).catch(() => {})
+      await iterator.return?.(reason)
+    },
+  })
+  return new Response(stream, {
+    status: options.status ?? 200,
+    headers: { "content-type": `multipart/${subtype}; boundary=${boundary}` },
+  })
+}

package/src/problem-details.ts

@@ -0,0 +1,208 @@
+import { definePlugin, pathnameOf } from "@nifrajs/core/server"
+
+const JSON_TYPE = /^(?:application\/json|[^/]+\/[^;]+\+json)(?:\s*;|$)/i
+const DEFAULT_MAX_BYTES = 64 * 1024
+
+const STATUS_TITLES: Readonly<Record<number, string>> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Content Too Large",
+  415: "Unsupported Media Type",
+  422: "Unprocessable Content",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  507: "Insufficient Storage",
+}
+
+export interface ProblemDetailsOptions {
+  /** Include only the request pathname as `instance`. Query strings are never included. Default false. */
+  readonly includeInstance?: boolean
+  /** Prefix for code-specific problem types. Default `about:blank`. */
+  readonly typeBase?: string
+  /** Maximum JSON error body inspected. Default 64 KiB. */
+  readonly maxBytes?: number
+}
+
+interface ErrorEnvelope {
+  readonly error: string
+  readonly issues?: unknown
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null
+}
+
+function readEnvelope(
+  body: string | Uint8Array,
+  contentType: string | null,
+  maxBytes: number,
+): ErrorEnvelope | undefined {
+  if (contentType === null || !JSON_TYPE.test(contentType)) return undefined
+  const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body
+  if (bytes.byteLength > maxBytes) return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bytes))
+  } catch {
+    return undefined
+  }
+  if (!isRecord(parsed) || parsed.ok !== false || typeof parsed.error !== "string") {
+    return undefined
+  }
+  return {
+    error: parsed.error,
+    ...(Object.hasOwn(parsed, "issues") ? { issues: parsed.issues } : {}),
+  }
+}
+
+async function readCappedBody(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+): Promise<Uint8Array | undefined> {
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+
+  try {
+    while (true) {
+      const result = await reader.read()
+      if (result.done) {
+        const bytes = new Uint8Array(size)
+        let offset = 0
+        for (const chunk of chunks) {
+          bytes.set(chunk, offset)
+          offset += chunk.byteLength
+        }
+        return bytes
+      }
+
+      if (size + result.value.byteLength > maxBytes) {
+        void reader.cancel().catch(() => {})
+        return undefined
+      }
+
+      chunks.push(result.value)
+      size += result.value.byteLength
+    }
+  } catch {
+    void reader.cancel().catch(() => {})
+    return undefined
+  }
+}
+
+function problemType(typeBase: string | undefined, code: string): string {
+  if (typeBase === undefined) return "about:blank"
+  return `${typeBase.replace(/\/+$/, "")}/${encodeURIComponent(code)}`
+}
+
+function problemDocument(
+  status: number,
+  envelope: ErrorEnvelope,
+  typeBase: string | undefined,
+  instance: string | undefined,
+): Record<string, unknown> {
+  const document: Record<string, unknown> = {
+    type: problemType(typeBase, envelope.error),
+    title: STATUS_TITLES[status] ?? "HTTP Error",
+    status,
+    code: envelope.error,
+  }
+  if (envelope.issues !== undefined) document.issues = envelope.issues
+  if (instance !== undefined) document.instance = instance
+  return document
+}
+
+function isAlreadyProblemDetails(contentType: string | null): boolean {
+  return contentType?.toLowerCase().startsWith("application/problem+json") === true
+}
+
+/**
+ * Opt-in RFC 9457 formatting for Nifra's structured error envelope.
+ *
+ * The default `{ ok: false, error }` response remains unchanged. This plugin only converts that
+ * framework envelope, so custom JSON errors and already-formatted problem documents pass through.
+ * Raw JSON error Responses are supported through a capped clone; encoded responses are never drained.
+ */
+export function problemDetails(options: ProblemDetailsOptions = {}) {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+    throw new Error("problemDetails: maxBytes must be a non-negative safe integer")
+  }
+  const instance = options.includeInstance === true
+  const typeBase = options.typeBase
+
+  return definePlugin("problemDetails", (app) =>
+    app.use({
+      onResponseBody(body, headers, req, status) {
+        if (
+          status < 400 ||
+          status >= 600 ||
+          headers.has("content-encoding") ||
+          isAlreadyProblemDetails(headers.get("content-type"))
+        ) {
+          return undefined
+        }
+        const envelope = readEnvelope(body, headers.get("content-type"), maxBytes)
+        if (envelope === undefined) return undefined
+        const document = problemDocument(
+          status,
+          envelope,
+          typeBase,
+          instance ? pathnameOf(req.url) : undefined,
+        )
+        headers.set("content-type", "application/problem+json")
+        headers.delete("content-length")
+        return JSON.stringify(document)
+      },
+      async onResponseRaw(response, req) {
+        if (
+          response.status < 400 ||
+          response.status >= 600 ||
+          response.body === null ||
+          response.headers.has("content-encoding") ||
+          isAlreadyProblemDetails(response.headers.get("content-type"))
+        ) {
+          return response
+        }
+        let bytes: Uint8Array | undefined
+        try {
+          const clone = response.clone()
+          if (clone.body === null) return response
+          bytes = await readCappedBody(clone.body, maxBytes)
+        } catch {
+          return response
+        }
+        if (bytes === undefined) return response
+        const envelope = readEnvelope(bytes, response.headers.get("content-type"), maxBytes)
+        if (envelope === undefined) return response
+        const headers = new Headers(response.headers)
+        headers.set("content-type", "application/problem+json")
+        headers.delete("content-length")
+        return new Response(
+          JSON.stringify(
+            problemDocument(
+              response.status,
+              envelope,
+              typeBase,
+              instance ? pathnameOf(req.url) : undefined,
+            ),
+          ),
+          { status: response.status, statusText: response.statusText, headers },
+        )
+      },
+    }),
+  )
+}

package/src/range.ts

@@ -0,0 +1,176 @@
+import { type ByteRange, type ByteRangeResult, parseByteRange } from "@nifrajs/core/range"
+
+// The parser lives in core because `@nifrajs/web`'s `public/` handler needs the identical answer for
+// files on disk, and web cannot depend on this package. Re-exported here so the middleware surface
+// stays one import.
+export { type ByteRange, type ByteRangeResult, parseByteRange }
+
+export interface RangeResponseOptions {
+  /** Media type for the complete representation and each single-range response. */
+  readonly contentType?: string
+  /** Entity tag used for conditional requests and `If-Range`. */
+  readonly etag?: string
+  /** Validator used for conditional requests and date-form `If-Range`. */
+  readonly lastModified?: Date
+  /** Optional cache policy copied to the response. */
+  readonly cacheControl?: string
+}
+
+const TEXT = new TextEncoder()
+
+function bytesOf(body: string | ArrayBuffer | ArrayBufferView | Uint8Array): Uint8Array {
+  if (typeof body === "string") return TEXT.encode(body)
+  if (body instanceof Uint8Array) return body
+  if (body instanceof ArrayBuffer) return new Uint8Array(body)
+  return new Uint8Array(body.buffer, body.byteOffset, body.byteLength)
+}
+
+function httpDate(date: Date): string {
+  const time = date.getTime()
+  if (!Number.isFinite(time))
+    throw new RangeError("rangeResponse: lastModified must be a valid Date")
+  return new Date(time).toUTCString()
+}
+
+function validators(options: RangeResponseOptions): Headers {
+  const headers = new Headers()
+  if (options.contentType !== undefined) headers.set("content-type", options.contentType)
+  if (options.etag !== undefined) headers.set("etag", options.etag)
+  if (options.lastModified !== undefined)
+    headers.set("last-modified", httpDate(options.lastModified))
+  if (options.cacheControl !== undefined) headers.set("cache-control", options.cacheControl)
+  return headers
+}
+
+function emptyResponse(status: number, headers: Headers): Response {
+  headers.delete("content-length")
+  headers.delete("content-type")
+  return new Response(null, { status, headers })
+}
+
+function matchesIfNoneMatch(value: string, etag: string): boolean {
+  const normalized = etag.startsWith("W/") ? etag.slice(2) : etag
+  return value.split(",").some((candidate) => {
+    const item = candidate.trim()
+    if (item === "*") return true
+    const comparable = item.startsWith("W/") ? item.slice(2) : item
+    return comparable === normalized
+  })
+}
+
+function ifRangeMatches(value: string | null, options: RangeResponseOptions): boolean {
+  if (value === null) return true
+  const item = value.trim()
+  if (options.etag !== undefined) return !item.startsWith("W/") && item === options.etag
+  if (options.lastModified === undefined) return false
+  const time = Date.parse(item)
+  return (
+    Number.isFinite(time) &&
+    Math.floor(time / 1000) >= Math.floor(options.lastModified.getTime() / 1000)
+  )
+}
+
+function shouldReturnNotModified(request: Request, options: RangeResponseOptions): boolean {
+  if (request.method !== "GET" && request.method !== "HEAD") return false
+  const ifNoneMatch = request.headers.get("if-none-match")
+  // RFC conditional precedence: an If-None-Match header suppresses date evaluation even when this
+  // representation has no ETag to compare. A non-matching tag must not be upgraded to a 304 by an
+  // older If-Modified-Since value.
+  if (ifNoneMatch !== null) {
+    return options.etag !== undefined && matchesIfNoneMatch(ifNoneMatch, options.etag)
+  }
+  // If-Modified-Since remains a valid fallback when the request did not send If-None-Match.
+  const lastModified = options.lastModified?.getTime()
+  const ifModifiedSince = request.headers.get("if-modified-since")
+  return (
+    lastModified !== undefined &&
+    Number.isFinite(lastModified) &&
+    ifModifiedSince !== null &&
+    Number.isFinite(Date.parse(ifModifiedSince)) &&
+    Math.floor(Date.parse(ifModifiedSince) / 1000) >= Math.floor(lastModified / 1000)
+  )
+}
+
+function responseBody(bytes: Uint8Array, request: Request): Uint8Array | null {
+  return request.method === "HEAD" ? null : bytes
+}
+
+function multipartBytes(
+  bytes: Uint8Array,
+  ranges: readonly ByteRange[],
+  size: number,
+  contentType: string,
+  boundary: string,
+): Uint8Array {
+  const chunks: Uint8Array[] = []
+  let total = 0
+  const add = (chunk: Uint8Array): void => {
+    chunks.push(chunk)
+    total += chunk.byteLength
+  }
+  for (const range of ranges) {
+    add(TEXT.encode(`--${boundary}\r\n`))
+    add(TEXT.encode(`Content-Range: bytes ${range.start}-${range.end}/${size}\r\n`))
+    add(TEXT.encode(`Content-Type: ${contentType}\r\n\r\n`))
+    add(bytes.subarray(range.start, range.end + 1))
+    add(TEXT.encode("\r\n"))
+  }
+  add(TEXT.encode(`--${boundary}--\r\n`))
+  const body = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    body.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return body
+}
+
+/**
+ * Create a standards-shaped byte representation response with Range, If-Range, and conditional
+ * validator handling. The input is already caller-owned memory; this helper does not read or retain
+ * external state. Multiple ranges use `multipart/byteranges` and adjacent ranges are coalesced.
+ */
+export function rangeResponse(
+  request: Request,
+  body: string | ArrayBuffer | ArrayBufferView | Uint8Array,
+  options: RangeResponseOptions = {},
+): Response {
+  const bytes = bytesOf(body)
+  const headers = validators(options)
+  headers.set("accept-ranges", "bytes")
+
+  if (shouldReturnNotModified(request, options)) return emptyResponse(304, headers)
+
+  const requestedRange =
+    request.method === "GET" || request.method === "HEAD" ? request.headers.get("range") : null
+  const range =
+    requestedRange !== null && ifRangeMatches(request.headers.get("if-range"), options)
+      ? parseByteRange(requestedRange, bytes.byteLength)
+      : { kind: "none" as const }
+
+  if (range.kind === "unsatisfiable") {
+    headers.set("content-range", `bytes */${bytes.byteLength}`)
+    headers.set("content-length", "0")
+    return new Response(null, { status: 416, headers })
+  }
+
+  if (range.kind === "none") {
+    headers.set("content-length", String(bytes.byteLength))
+    return new Response(responseBody(bytes, request), { status: 200, headers })
+  }
+
+  const contentType = options.contentType ?? "application/octet-stream"
+  if (range.ranges.length === 1) {
+    const selected = range.ranges[0]!
+    const selectedBytes = bytes.subarray(selected.start, selected.end + 1)
+    headers.set("content-range", `bytes ${selected.start}-${selected.end}/${bytes.byteLength}`)
+    headers.set("content-length", String(selectedBytes.byteLength))
+    return new Response(responseBody(selectedBytes, request), { status: 206, headers })
+  }
+
+  const boundary = `nifra-${crypto.randomUUID().replaceAll("-", "")}`
+  const selectedBytes = multipartBytes(bytes, range.ranges, bytes.byteLength, contentType, boundary)
+  headers.set("content-type", `multipart/byteranges; boundary=${boundary}`)
+  headers.set("content-length", String(selectedBytes.byteLength))
+  return new Response(responseBody(selectedBytes, request), { status: 206, headers })
+}