@nifrajs/middleware 0.1.0-alpha.1

package/src/language.ts

@@ -0,0 +1,109 @@
+import { definePlugin } from "@nifrajs/core"
+
+export interface LanguageMatch {
+  readonly language: string
+  readonly matched: "exact" | "base" | "wildcard" | "default"
+}
+
+export interface LanguageOptions<L extends readonly string[]> {
+  readonly supported: L
+  readonly defaultLanguage: L[number]
+  /** Emit `Content-Language`. Default `true`. */
+  readonly header?: boolean
+}
+
+interface Range {
+  readonly tag: string
+  readonly q: number
+  readonly order: number
+}
+
+function parseAcceptLanguage(header: string | null): Range[] {
+  if (header === null) return []
+  const ranges: Range[] = []
+  let order = 0
+  for (const part of header.split(",")) {
+    const pieces = part.split(";").map((p) => p.trim())
+    const tag = (pieces[0] ?? "").toLowerCase()
+    if (tag === "") continue
+    let q = 1
+    for (const piece of pieces.slice(1)) {
+      const [name, raw] = piece.split("=")
+      if (name?.toLowerCase() !== "q" || raw === undefined) continue
+      const parsed = Number(raw)
+      if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        q = 0
+      } else {
+        q = parsed
+      }
+    }
+    if (q > 0) ranges.push({ tag, q, order })
+    order += 1
+  }
+  return ranges.sort((a, b) => b.q - a.q || a.order - b.order)
+}
+
+function baseOf(tag: string): string {
+  const dash = tag.indexOf("-")
+  return dash === -1 ? tag : tag.slice(0, dash)
+}
+
+/**
+ * Pick the best supported language for an `Accept-Language` header. Exact tags win, then compatible
+ * base-language matches, then `*`, then the configured default.
+ */
+export function pickLanguage<const L extends readonly string[]>(
+  header: string | null,
+  supported: L,
+  defaultLanguage: L[number],
+): LanguageMatch {
+  if (supported.length === 0) throw new Error("pickLanguage: supported must not be empty")
+  if (!supported.includes(defaultLanguage)) {
+    throw new Error("pickLanguage: defaultLanguage must be in supported")
+  }
+  const lower = new Map(supported.map((value) => [value.toLowerCase(), value] as const))
+  const ranges = parseAcceptLanguage(header)
+  for (const range of ranges) {
+    if (range.tag === "*") return { language: defaultLanguage, matched: "wildcard" }
+    const exact = lower.get(range.tag)
+    if (exact !== undefined) return { language: exact, matched: "exact" }
+    const requestedBase = baseOf(range.tag)
+    for (const value of supported) {
+      const candidate = value.toLowerCase()
+      if (baseOf(candidate) === requestedBase) return { language: value, matched: "base" }
+    }
+  }
+  return { language: defaultLanguage, matched: "default" }
+}
+
+/**
+ * Derives `c.language` from `Accept-Language` and emits `Content-Language` by default.
+ */
+export function language<const L extends readonly string[]>(options: LanguageOptions<L>) {
+  const { supported, defaultLanguage } = options
+  if (supported.length === 0) throw new Error("language: supported must not be empty")
+  if (!supported.includes(defaultLanguage)) {
+    throw new Error("language: defaultLanguage must be in supported")
+  }
+  const emitHeader = options.header !== false
+  const matches = new WeakMap<Request, LanguageMatch>()
+
+  return definePlugin("language", (app) =>
+    app
+      .derive((c) => {
+        const match = pickLanguage(c.req.headers.get("accept-language"), supported, defaultLanguage)
+        matches.set(c.req, match)
+        return { language: match.language, languageMatch: match }
+      })
+      .onResponse((res, req) => {
+        if (!emitHeader) return res
+        const match = matches.get(req)
+        if (match === undefined) return res
+        matches.delete(req)
+        if (res.headers.has("content-language")) return res
+        const headers = new Headers(res.headers)
+        headers.set("content-language", match.language)
+        return new Response(res.body, { status: res.status, statusText: res.statusText, headers })
+      }),
+  )
+}

package/src/logger.ts

@@ -0,0 +1,44 @@
+import { definePlugin } from "@nifrajs/core"
+
+/** Structured fields logged per request. */
+export interface RequestLogFields {
+  readonly method: string
+  readonly path: string
+  readonly status: number
+  /** Wall-clock duration in ms (0 if the start couldn't be paired). */
+  readonly ms: number
+}
+
+export interface LoggerOptions {
+  /** Sink for each line. Default: `console.log(JSON.stringify(fields))`. Route to your own logger here. */
+  readonly log?: (fields: RequestLogFields) => void
+}
+
+/**
+ * A {@link definePlugin} plugin that logs one structured line per request — method, path, status,
+ * and duration — via `onRequest`/`onResponse` (so it covers 404s and errors too). The start time is
+ * paired to the request through a `WeakMap` (no per-request allocation leak). Idempotent.
+ */
+export function logger(options: LoggerOptions = {}) {
+  // A request logger's whole job is to log; the default writes JSON to stdout, routable via `log`.
+  const sink = options.log ?? ((fields: RequestLogFields) => console.log(JSON.stringify(fields)))
+  const starts = new WeakMap<Request, number>()
+  return definePlugin("logger", (app) =>
+    app
+      .onRequest((req) => {
+        starts.set(req, performance.now())
+        return undefined
+      })
+      .onResponse((res, req) => {
+        const start = starts.get(req)
+        starts.delete(req)
+        sink({
+          method: req.method,
+          path: new URL(req.url).pathname,
+          status: res.status,
+          ms: start === undefined ? 0 : Math.round(performance.now() - start),
+        })
+        return res
+      }),
+  )
+}

package/src/method-override.ts

@@ -0,0 +1,87 @@
+import { definePlugin, METHODS, type Method } from "@nifrajs/core"
+import { jsonError } from "./_utils.ts"
+
+export interface MethodOverrideOptions {
+  /**
+   * Header carrying the desired method. Default `"x-http-method-override"`.
+   * Set `false` to disable header-based override.
+   */
+  readonly header?: string | false
+  /**
+   * Query parameter carrying the desired method. Disabled by default because query-tunneled writes are
+   * easier to trigger accidentally from links/forms. Use only with CSRF protection on browser routes.
+   */
+  readonly query?: string | false
+  /** Original request methods allowed to tunnel. Default `["POST"]`. */
+  readonly methods?: readonly string[]
+  /** Target methods accepted from the override source. Default `["PUT", "PATCH", "DELETE"]`. */
+  readonly allowed?: readonly Method[]
+  /** Invalid override values reject with `400` by default. Use `"ignore"` for legacy clients. */
+  readonly onInvalid?: "reject" | "ignore"
+}
+
+const SUPPORTED = new Set<string>(METHODS)
+const DEFAULT_ALLOWED = ["PUT", "PATCH", "DELETE"] as const
+
+function normalizeMethod(value: string): Method | null {
+  const method = value.trim().toUpperCase()
+  if (!SUPPORTED.has(method)) return null
+  return method as Method
+}
+
+function singleQueryValue(req: Request, name: string): string | null | false {
+  const values = new URL(req.url).searchParams.getAll(name)
+  if (values.length === 0) return null
+  if (values.length > 1) return false
+  return values[0] ?? null
+}
+
+function replacement(req: Request, method: Method): Request {
+  return new Request(req, { method })
+}
+
+/**
+ * HTTP method override for clients that can only send `POST`. The middleware rewrites the request
+ * before routing, so handlers, validation, and response hooks all see the overridden method.
+ *
+ * Header override is enabled by default; query override is opt-in. Form-body override is deliberately
+ * not implemented because reading the body before routing would consume or buffer it for every write.
+ */
+export function methodOverride(options: MethodOverrideOptions = {}) {
+  const header = options.header === undefined ? "x-http-method-override" : options.header
+  const query = options.query ?? false
+  const sourceMethods = new Set((options.methods ?? ["POST"]).map((m) => m.toUpperCase()))
+  const allowed = new Set<Method>(options.allowed ?? DEFAULT_ALLOWED)
+  const rejectInvalid = options.onInvalid !== "ignore"
+
+  if (header !== false && header.trim() === "") throw new Error("methodOverride: header is empty")
+  if (query !== false && query.trim() === "") throw new Error("methodOverride: query is empty")
+
+  return definePlugin("methodOverride", (app) =>
+    app.onRequest((req) => {
+      if (!sourceMethods.has(req.method.toUpperCase())) return undefined
+
+      const values: string[] = []
+      if (header !== false) {
+        const value = req.headers.get(header)
+        if (value !== null) values.push(value)
+      }
+      if (query !== false) {
+        const value = singleQueryValue(req, query)
+        if (value === false)
+          return rejectInvalid ? jsonError(400, "invalid_method_override") : undefined
+        if (value !== null) values.push(value)
+      }
+      if (values.length === 0) return undefined
+      if (values.length > 1 && new Set(values.map((v) => v.trim().toUpperCase())).size > 1) {
+        return rejectInvalid ? jsonError(400, "invalid_method_override") : undefined
+      }
+
+      const method = normalizeMethod(values[0] ?? "")
+      if (method === null || !allowed.has(method)) {
+        return rejectInvalid ? jsonError(400, "invalid_method_override") : undefined
+      }
+      return method === req.method ? undefined : replacement(req, method)
+    }),
+  )
+}

package/src/openapi.ts

@@ -0,0 +1,174 @@
+import { definePlugin } from "@nifrajs/core"
+// The OpenAPI generator only — `@nifrajs/schema/openapi` is pure (no TypeBox runtime), so the openapi()
+// plugin gets full `t`-schema introspection without pulling the `t` builder into every consumer.
+import { toOpenAPI } from "@nifrajs/schema/openapi"
+
+/** A registered route as seen by {@link buildOpenApiDocument} — structurally a `@nifrajs/core`
+ * `RouteDescriptor` (so `app.routes()` is passed straight through). */
+export interface RouteLike {
+  readonly method: string
+  readonly path: string
+  // `| undefined` (not just `?`) so a core `RouteDescriptor` — whose `schema` is a *required*
+  // `RouteSchema | undefined` — is assignable under `exactOptionalPropertyTypes`.
+  readonly schema?:
+    | { readonly body?: unknown; readonly query?: unknown; readonly response?: unknown }
+    | undefined
+}
+
+export interface OpenApiInfo {
+  readonly title?: string
+  readonly version?: string
+  readonly description?: string
+}
+
+export interface OpenApiServer {
+  readonly url: string
+  readonly description?: string
+}
+
+export interface OpenApiTag {
+  readonly name: string
+  readonly description?: string
+}
+
+/** A security requirement: scheme name → required scopes (`[]` = no scopes). */
+export type SecurityRequirement = Readonly<Record<string, readonly string[]>>
+
+/** Scalar API-reference UI options. */
+export interface OpenApiUiOptions {
+  /** Where to serve the UI page. Default `"/reference"`. */
+  readonly path?: string
+  /** Page title. Defaults to `info.title`. */
+  readonly title?: string
+  /** The Scalar script URL (loaded from a CDN). Default jsDelivr's `@scalar/api-reference`. */
+  readonly cdn?: string
+}
+
+export interface OpenApiOptions {
+  readonly info?: OpenApiInfo
+  readonly servers?: readonly OpenApiServer[]
+  /** Tag definitions (top-level `tags`). Reference them from an operation via `operations`. */
+  readonly tags?: readonly OpenApiTag[]
+  /** Reusable security schemes → `components.securitySchemes` (e.g. `{ bearer: { type: "http", scheme: "bearer" } }`). */
+  readonly securitySchemes?: Readonly<Record<string, Record<string, unknown>>>
+  /** Document-wide security requirement; override per-operation via `operations`. */
+  readonly security?: readonly SecurityRequirement[]
+  /** Where the plugin serves the document. Default `"/openapi.json"`. */
+  readonly path?: string
+  /** Exclude routes from the document (the doc path itself is always excluded). */
+  readonly exclude?: (route: { readonly method: string; readonly path: string }) => boolean
+  /** Per-operation overrides keyed by `"GET /users/:id"`, shallow-merged over the generated skeleton —
+   * the escape hatch for rich request/response schemas, tags, and per-op security (Standard Schema
+   * can't be introspected). */
+  readonly operations?: Readonly<Record<string, Record<string, unknown>>>
+  /** Also serve a Scalar API-reference UI page rendering the spec (`true` → `/reference`). */
+  readonly ui?: boolean | OpenApiUiOptions
+}
+
+/**
+ * Build an OpenAPI 3.1 document from a route list. Delegates to `@nifrajs/schema`'s `toOpenAPI`, so a
+ * route validated with `t` (TypeBox) emits full field-level request/query/response schemas plus
+ * `$ref`-reused `components.schemas`; a BYO Standard Schema (zod/valibot/arktype) exposes no portable
+ * JSON-Schema form, so its body/response is omitted (supply it via `options.operations`). Path params,
+ * wildcards, tags, security, and servers always emit. Exported so you can also generate the doc at
+ * build time (write it to disk in CI) without booting the server.
+ */
+export function buildOpenApiDocument(
+  routes: readonly RouteLike[],
+  options: OpenApiOptions = {},
+): Record<string, unknown> {
+  const docPath = options.path ?? "/openapi.json"
+  // toOpenAPI has no exclude hook, so filter here: never document the doc endpoint itself, then apply
+  // the caller's exclude predicate.
+  const included = routes.filter(
+    (route) =>
+      route.path !== docPath &&
+      options.exclude?.({ method: route.method, path: route.path }) !== true,
+  )
+  // toOpenAPI duck-types an "app" by a `routes()` method (its `isApp`); this shim lets the runtime
+  // plugin reuse the rich generator over a plain route list without holding a live Server reference.
+  // The cast is required because toOpenAPI's parameter is a nominal `ContractShape | Server` union,
+  // and the shim only satisfies it structurally.
+  const appShim = { routes: () => included } as unknown as Parameters<typeof toOpenAPI>[0]
+  return toOpenAPI(appShim, {
+    title: options.info?.title ?? "nifra API",
+    version: options.info?.version ?? "0.0.0",
+    ...(options.info?.description !== undefined ? { description: options.info.description } : {}),
+    ...(options.servers !== undefined ? { servers: options.servers } : {}),
+    ...(options.tags !== undefined ? { tags: options.tags } : {}),
+    ...(options.security !== undefined ? { security: options.security } : {}),
+    ...(options.securitySchemes !== undefined ? { securitySchemes: options.securitySchemes } : {}),
+    ...(options.operations !== undefined ? { operations: options.operations } : {}),
+  }) as unknown as Record<string, unknown>
+}
+
+const SCALAR_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+
+/**
+ * Minimal HTML that mounts the Scalar API reference against a spec URL. The interpolated values are
+ * dev-provided config (not request input), but they're still escaped so a stray quote or `<` can't
+ * break the markup.
+ */
+function scalarPage(specUrl: string, title: string, cdn: string): string {
+  const attr = (s: string): string => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;")
+  const text = (s: string): string => s.replace(/&/g, "&amp;").replace(/</g, "&lt;")
+  return `<!doctype html>
+<html>
+  <head>
+    <title>${text(title)}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script id="api-reference" data-url="${attr(specUrl)}"></script>
+    <script src="${attr(cdn)}"></script>
+  </body>
+</html>`
+}
+
+/**
+ * Serve an OpenAPI 3.1 document (a structural subset — see {@link buildOpenApiDocument}) at
+ * `options.path` (default `/openapi.json`), generated from the app's registered routes. Generation is
+ * **lazy + memoized**: it reads `app.routes()` on the first request, by which point every route is
+ * registered — so the plugin's own position in the chain doesn't matter.
+ *
+ * Pass `ui: true` (or `ui: { path, title, cdn }`) to also serve a Scalar API-reference page (default
+ * `/reference`) that renders the spec. The page loads Scalar from a CDN; pin/self-host via `ui.cdn`,
+ * and remember to allow that origin if you ship a `script-src` Content-Security-Policy.
+ *
+ * ```ts
+ * app.use(openapi({ info: { title: "My API", version: "1.0.0" }, ui: true }))
+ * ```
+ */
+export function openapi(options: OpenApiOptions = {}) {
+  const docPath = options.path ?? "/openapi.json"
+  const ui: OpenApiUiOptions | undefined =
+    options.ui === true ? {} : options.ui === false ? undefined : options.ui
+  const uiPath = ui !== undefined ? (ui.path ?? "/reference") : undefined
+  let cached: string | undefined
+  let uiCached: string | undefined
+  return definePlugin("openapi", (app) => {
+    // Capture `app` (the same mutable builder every later `.get()`/`.post()` registers on) and read its
+    // routes lazily, at request time — so all routes exist regardless of where the plugin sits.
+    app.register("GET", docPath, undefined, () => {
+      cached ??= JSON.stringify(
+        buildOpenApiDocument(app.routes(), {
+          ...options,
+          path: docPath,
+          // Don't document the UI page itself (the doc path is already excluded by buildOpenApiDocument).
+          exclude: (route) => route.path === uiPath || options.exclude?.(route) === true,
+        }),
+      )
+      return new Response(cached, { headers: { "content-type": "application/json" } })
+    })
+    if (ui !== undefined && uiPath !== undefined) {
+      const title = ui.title ?? options.info?.title ?? "nifra API"
+      const cdn = ui.cdn ?? SCALAR_CDN
+      app.register("GET", uiPath, undefined, () => {
+        uiCached ??= scalarPage(docPath, title, cdn)
+        return new Response(uiCached, { headers: { "content-type": "text/html; charset=utf-8" } })
+      })
+    }
+    return app
+  })
+}

package/src/powered-by.ts

@@ -0,0 +1,31 @@
+import type { Middleware } from "@nifrajs/core"
+import { withHeaders } from "./_utils.ts"
+
+export interface PoweredByOptions {
+  /** Header name. Default `"x-powered-by"`. */
+  readonly header?: string
+  /** Header value. Default `"Nifra"`. */
+  readonly value?: string
+  /** Do not overwrite an existing header by default. */
+  readonly respectExisting?: boolean
+}
+
+/**
+ * Opt-in `X-Powered-By` style header. Nifra does not emit this by default; use it only when you want a
+ * public framework/product marker.
+ */
+export function poweredBy(options: PoweredByOptions = {}): Middleware {
+  const header = options.header ?? "x-powered-by"
+  const value = options.value ?? "Nifra"
+  const respectExisting = options.respectExisting !== false
+  if (header.trim() === "") throw new Error("poweredBy: header is empty")
+  if (/[\r\n]/.test(value)) throw new Error("poweredBy: value contains a newline")
+
+  return {
+    name: "powered-by",
+    onResponse(res) {
+      if (respectExisting && res.headers.has(header)) return res
+      return withHeaders(res, (headers) => headers.set(header, value))
+    },
+  }
+}

package/src/pretty-json.ts

@@ -0,0 +1,97 @@
+import { definePlugin } from "@nifrajs/core"
+
+export interface PrettyJsonOptions {
+  /** JSON indentation spaces. Default `2`. */
+  readonly spaces?: number
+  /** Maximum response bytes to inspect. Default `1_000_000`; larger responses pass through. */
+  readonly maxBytes?: number
+  /** Append a final newline. Default `true`. */
+  readonly newline?: boolean
+  /** Optional query toggle. When set, pretty printing runs only when the parameter is present. */
+  readonly query?: string | false
+  /** Only pretty-print matching requests. Default `true`. */
+  readonly enabled?: boolean | ((request: Request) => boolean)
+}
+
+const JSON_TYPE = /^(?:application\/json|[^/]+\/[^;]+\+json)(?:\s*;|$)/i
+
+function isJson(contentType: string): boolean {
+  return JSON_TYPE.test(contentType)
+}
+
+function parseLength(value: string | null): number | undefined {
+  if (value === null) return undefined
+  if (!/^(?:0|[1-9]\d*)$/.test(value)) return undefined
+  return Number(value)
+}
+
+async function readTextCapped(res: Response, maxBytes: number): Promise<string | null> {
+  const body = res.clone().body
+  if (body === null) return null
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let total = 0
+  let text = ""
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) return text + decoder.decode()
+      total += value.byteLength
+      if (total > maxBytes) {
+        await reader.cancel()
+        return null
+      }
+      text += decoder.decode(value, { stream: true })
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Pretty-print JSON responses for debugging and developer-facing APIs. It only touches JSON content,
+ * skips encoded responses, caps inspection size, and leaves invalid JSON untouched.
+ */
+export function prettyJson(options: PrettyJsonOptions = {}) {
+  const spaces = options.spaces ?? 2
+  if (!Number.isInteger(spaces) || spaces < 0 || spaces > 10) {
+    throw new Error("prettyJson: spaces must be an integer from 0 to 10")
+  }
+  const maxBytes = options.maxBytes ?? 1_000_000
+  if (!Number.isInteger(maxBytes) || maxBytes < 0) {
+    throw new Error("prettyJson: maxBytes must be a non-negative integer")
+  }
+  const newline = options.newline !== false
+  const query = options.query ?? false
+  if (query !== false && query.trim() === "") throw new Error("prettyJson: query is empty")
+  const enabled = options.enabled ?? true
+  const isEnabled = typeof enabled === "function" ? enabled : enabled ? () => true : () => false
+
+  return definePlugin("prettyJson", (app) =>
+    app.onResponse(async (res, req) => {
+      if (!isEnabled(req)) return res
+      if (query !== false && !new URL(req.url).searchParams.has(query)) return res
+      if (res.body === null || res.headers.has("content-encoding")) return res
+      if (!isJson(res.headers.get("content-type") ?? "")) return res
+      const declared = parseLength(res.headers.get("content-length"))
+      if (declared !== undefined && declared > maxBytes) return res
+
+      const text = await readTextCapped(res, maxBytes)
+      if (text === null) return res
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(text)
+      } catch {
+        return res
+      }
+
+      const headers = new Headers(res.headers)
+      headers.delete("content-length")
+      return new Response(`${JSON.stringify(parsed, null, spaces)}${newline ? "\n" : ""}`, {
+        status: res.status,
+        statusText: res.statusText,
+        headers,
+      })
+    }),
+  )
+}