ingenium 0.0.1

package/src/negotiation/format.ts

@@ -0,0 +1,88 @@
+/**
+ * `formatResponse(ctx, handlers)` — Express's `res.format` for Ingenium.
+ *
+ * Picks the best handler key against the request `Accept` header, runs it,
+ * sets `Content-Type` to the matched key, and writes the result as the
+ * response body. If no handler matches and no `default` key is provided,
+ * throws a `IngeniumError(406, 'NOT_ACCEPTABLE')`.
+ *
+ * Handlers may be sync or async — `formatResponse` always awaits.
+ */
+
+import { Buffer } from 'node:buffer'
+import { selectBest } from './accept.ts'
+import type { NegotiableCtx } from './negotiate.ts'
+import { IngeniumError } from '../errors.ts'
+
+/** Minimal context shape required by `formatResponse` — narrower than full `IngeniumContext`. */
+export interface FormattableCtx extends NegotiableCtx {
+  set(name: string, value: string | string[]): unknown
+  json(body: unknown, status?: number): void
+  send(body: Buffer | string, status?: number): void
+}
+
+/** Map of `mime → handler`. The reserved key `default` is the no-match fallback. */
+export type FormatHandlers = Record<string, () => unknown | Promise<unknown>>
+
+/**
+ * Pick the best handler key for `Accept` and run it.
+ *
+ * - JSON-shaped result objects are written via `ctx.json`.
+ * - String / Buffer results are written via `ctx.send` with the matched
+ *   content-type preserved (instead of `send`'s default text/plain inference).
+ * - `default` handler is used when no explicit key matches.
+ * - No match + no default → throws `IngeniumError(406, 'NOT_ACCEPTABLE')`.
+ */
+export async function formatResponse(
+  ctx: FormattableCtx,
+  handlers: FormatHandlers,
+): Promise<void> {
+  const keys = Object.keys(handlers).filter((k) => k !== 'default')
+  const acceptHeader = (() => {
+    const v = ctx.headers['accept']
+    return Array.isArray(v) ? v.join(',') : v
+  })()
+
+  let chosenKey: string | false = selectBest(acceptHeader, keys)
+
+  // No explicit match — fall back to `default`, else 406.
+  if (chosenKey === false) {
+    if ('default' in handlers) {
+      const result = await handlers['default']!()
+      writeResult(ctx, result, undefined)
+      return
+    }
+    throw new IngeniumError(
+      406,
+      'NOT_ACCEPTABLE',
+      `None of the offered types [${keys.join(', ')}] satisfy Accept: ${acceptHeader ?? '*/*'}`,
+    )
+  }
+
+  const handler = handlers[chosenKey]
+  if (!handler) {
+    // Defensive — shouldn't happen since selectBest only returns offered keys.
+    throw new IngeniumError(406, 'NOT_ACCEPTABLE', 'Internal: matched handler missing')
+  }
+  const result = await handler()
+  writeResult(ctx, result, chosenKey)
+}
+
+function writeResult(ctx: FormattableCtx, result: unknown, contentType: string | undefined): void {
+  if (contentType) ctx.set('content-type', contentType)
+  if (result === undefined || result === null) {
+    // Treat as empty body — caller handles 204 elsewhere.
+    ctx.send('', undefined)
+    return
+  }
+  if (typeof result === 'string') {
+    ctx.send(result, undefined)
+    return
+  }
+  if (Buffer.isBuffer(result) || result instanceof Uint8Array) {
+    ctx.send(Buffer.isBuffer(result) ? result : Buffer.from(result))
+    return
+  }
+  // Object → JSON.
+  ctx.json(result)
+}

package/src/negotiation/fresh.ts

@@ -0,0 +1,89 @@
+/**
+ * `isFresh(reqHeaders, resHeaders)` — RFC 7232 conditional-request evaluator.
+ *
+ * Returns `true` when the response can be considered fresh relative to the
+ * client's cached copy, i.e. a `304 Not Modified` is appropriate. This is
+ * the engine behind `ctx.fresh` / `ctx.stale`.
+ *
+ * Decision matrix:
+ *   - `If-None-Match` present → compare against response `ETag`. Wildcard
+ *     `*` matches any current representation. Strong/weak prefixes are
+ *     normalized away (per RFC 7232 §2.3.2 weak-comparison rules).
+ *   - Else if `If-Modified-Since` present → compare against response
+ *     `Last-Modified` (or fall back to `Date`). Fresh when the resource has
+ *     not been modified since.
+ *   - Otherwise → not fresh (no precondition to evaluate).
+ *
+ * Methods other than GET/HEAD are not handled here — callers should gate
+ * on method themselves (Express does the same in `req.fresh`).
+ */
+
+/** Header bag shape — accepts both incoming-request and stored-response styles. */
+export type HeaderBag = Record<string, string | string[] | undefined>
+
+function getHeader(bag: HeaderBag, name: string): string | undefined {
+  const lower = name.toLowerCase()
+  const v = bag[lower]
+  if (v === undefined) {
+    // Try original-case key as fallback.
+    const alt = bag[name]
+    if (alt === undefined) return undefined
+    return Array.isArray(alt) ? alt.join(',') : alt
+  }
+  return Array.isArray(v) ? v.join(',') : v
+}
+
+/** Strip a leading `W/` weak prefix and surrounding double-quotes. */
+function normalizeEtag(tag: string): string {
+  let t = tag.trim()
+  if (t.startsWith('W/') || t.startsWith('w/')) t = t.slice(2)
+  if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) t = t.slice(1, t.length - 1)
+  return t
+}
+
+/** Split an `If-None-Match` header value into individual ETag tokens. */
+function splitInm(header: string): string[] {
+  return header.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
+}
+
+/**
+ * Returns `true` when the response is fresh w.r.t. the client's preconditions.
+ */
+export function isFresh(reqHeaders: HeaderBag, resHeaders: HeaderBag): boolean {
+  const ifNoneMatch = getHeader(reqHeaders, 'if-none-match')
+  const ifModifiedSince = getHeader(reqHeaders, 'if-modified-since')
+
+  // No conditional headers → cannot be fresh.
+  if (!ifNoneMatch && !ifModifiedSince) return false
+
+  // Cache-Control: no-cache on the request explicitly disables 304.
+  const reqCacheControl = getHeader(reqHeaders, 'cache-control')
+  if (reqCacheControl && /(?:^|,)\s*no-cache\s*(?:,|$)/i.test(reqCacheControl)) {
+    return false
+  }
+
+  // ───── If-None-Match takes precedence ─────
+  if (ifNoneMatch) {
+    if (ifNoneMatch.trim() === '*') return true
+    const etag = getHeader(resHeaders, 'etag')
+    if (!etag) return false
+    const target = normalizeEtag(etag)
+    for (const candidate of splitInm(ifNoneMatch)) {
+      if (normalizeEtag(candidate) === target) return true
+    }
+    return false
+  }
+
+  // ───── Fallback: If-Modified-Since ─────
+  if (ifModifiedSince) {
+    const lastModified = getHeader(resHeaders, 'last-modified') ?? getHeader(resHeaders, 'date')
+    if (!lastModified) return false
+    const sinceMs = Date.parse(ifModifiedSince)
+    const lastMs = Date.parse(lastModified)
+    if (!Number.isFinite(sinceMs) || !Number.isFinite(lastMs)) return false
+    // Fresh when resource hasn't changed since the client's copy.
+    return lastMs <= sinceMs
+  }
+
+  return false
+}

package/src/negotiation/json-etag.ts

@@ -0,0 +1,122 @@
+/**
+ * `respondJsonWithEtag(ctx, body, opts)` — JSON response with auto ETag and
+ * 304 short-circuit when `If-None-Match` matches.
+ *
+ * Behavior:
+ *   1. Stringify `body` to JSON exactly once.
+ *   2. Compute weak ETag (default) over the stringified bytes.
+ *   3. If `If-None-Match` (after weak normalization) matches → set 304,
+ *      clear body, mark written. Skip writing the JSON.
+ *   4. Otherwise: set `ETag` + `Content-Type` headers, write the body via
+ *      the same internal shape `ctx.json` uses, and mark written.
+ *
+ * Uses the lower-level shape from `IngeniumContext` directly (rather than
+ * calling `ctx.json`) so the JSON.stringify result can be reused without
+ * a second pass.
+ */
+
+import type { IncomingHttpHeaders } from 'node:http'
+import { computeEtag } from './etag.ts'
+import type { ResponseBody } from '../context/context.ts'
+import { IngeniumUnserializableError } from '../errors.ts'
+
+/**
+ * Strict `JSON.stringify` wrapper mirroring the one in `context.ts`. Kept
+ * inline rather than shared to avoid a circular import between
+ * `negotiation/` and `context/` (and so this helper stays consumable as a
+ * standalone with the lightweight `JsonEtagCtx` shape).
+ */
+function strictStringifyForEtag(body: unknown): string {
+  try {
+    return JSON.stringify(body) as string
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    let reason: string
+    if (/circular/i.test(msg)) reason = `circular structure (${msg})`
+    else if (/BigInt/i.test(msg)) reason = `BigInt value (${msg})`
+    else reason = msg
+    try {
+      process.emitWarning(
+        `IngeniumUnserializableError: ${reason}`,
+        { type: 'IngeniumUnserializableError' },
+      )
+    } catch {
+      // emitWarning unavailable — swallow.
+    }
+    throw new IngeniumUnserializableError(
+      `Response body cannot be serialized: ${reason}`,
+      err,
+    )
+  }
+}
+
+/** Options for `respondJsonWithEtag`. */
+export interface JsonEtagOptions {
+  /** Prefix the ETag with `W/`. Defaults to `true`. */
+  weak?: boolean
+  /** HTTP status to use for the success path. Defaults to `200`. */
+  status?: number
+}
+
+/**
+ * Minimal context shape required by `respondJsonWithEtag` — keeps the
+ * helper testable with a plain stub and avoids a hard import cycle on
+ * the full `IngeniumContext` class.
+ */
+export interface JsonEtagCtx {
+  headers: IncomingHttpHeaders
+  _statusCode: number
+  _headers: Record<string, string | string[]>
+  _body: ResponseBody
+  _written: boolean
+}
+
+/** Strip `W/` and quotes for weak-comparison equality. */
+function normalizeEtag(tag: string): string {
+  let t = tag.trim()
+  if (t.startsWith('W/') || t.startsWith('w/')) t = t.slice(2)
+  if (t.length >= 2 && t.startsWith('"') && t.endsWith('"')) t = t.slice(1, t.length - 1)
+  return t
+}
+
+function ifNoneMatchHas(header: string, target: string): boolean {
+  if (header.trim() === '*') return true
+  const want = normalizeEtag(target)
+  for (const part of header.split(',')) {
+    const candidate = part.trim()
+    if (candidate.length === 0) continue
+    if (normalizeEtag(candidate) === want) return true
+  }
+  return false
+}
+
+export function respondJsonWithEtag(
+  ctx: JsonEtagCtx,
+  body: unknown,
+  opts: JsonEtagOptions = {},
+): void {
+  const weak = opts.weak ?? true
+  const status = opts.status ?? 200
+  const serialized = strictStringifyForEtag(body)
+  const etag = computeEtag(serialized, weak)
+
+  const inm = ctx.headers['if-none-match']
+  const inmStr = Array.isArray(inm) ? inm.join(',') : inm
+  if (typeof inmStr === 'string' && inmStr.length > 0 && ifNoneMatchHas(inmStr, etag)) {
+    // Short-circuit: cache hit.
+    ctx._statusCode = 304
+    ctx._headers['etag'] = etag
+    // 304 must not carry a body.
+    ctx._body = { kind: 'none' }
+    ctx._written = true
+    return
+  }
+
+  ctx._statusCode = status
+  ctx._headers['etag'] = etag
+  if (!ctx._headers['content-type']) {
+    ctx._headers['content-type'] = 'application/json; charset=utf-8'
+  }
+  ctx._body = { kind: 'string', data: serialized }
+  ctx._written = true
+}

package/src/negotiation/negotiate.ts

@@ -0,0 +1,97 @@
+/**
+ * Higher-level `accepts*` helpers, parameterized over a context-like object
+ * with a `headers` map. Kept context-agnostic so they're trivially testable
+ * with a plain `{ headers: {...} }` stub.
+ */
+
+import type { IncomingHttpHeaders } from 'node:http'
+import { parseAcceptHeader, selectBest, expandShorthand } from './accept.ts'
+
+/** Minimal shape we depend on — `IngeniumContext` satisfies it. */
+export interface NegotiableCtx {
+  headers: IncomingHttpHeaders
+}
+
+function readHeader(ctx: NegotiableCtx, name: string): string | undefined {
+  const v = ctx.headers[name]
+  if (Array.isArray(v)) return v.join(',')
+  return v
+}
+
+/**
+ * `accepts(ctx)` → list of accepted media types in preference order
+ * (after expanding shorthand inputs is a no-op here — it returns the raw
+ * mime strings the client sent).
+ *
+ * `accepts(ctx, ...types)` → best matching offered type, or `false`.
+ * Each `type` may be a shorthand (`'json'`, `'html'`) or full mime
+ * (`'application/json'`).
+ */
+export function accepts(ctx: NegotiableCtx): string[]
+export function accepts(ctx: NegotiableCtx, ...types: string[]): string | false
+export function accepts(ctx: NegotiableCtx, ...types: string[]): string | false | string[] {
+  const header = readHeader(ctx, 'accept')
+  if (types.length === 0) {
+    return parseAcceptHeader(header).map((e) => e.type)
+  }
+  const best = selectBest(header, types.map(expandShorthand))
+  if (best === false) return false
+  // Map the canonical match back to the caller's original token (preserves shorthand).
+  for (const t of types) {
+    if (expandShorthand(t) === best) return t
+  }
+  return best
+}
+
+/**
+ * `acceptsCharsets(ctx)` → all charsets in preference order.
+ * `acceptsCharsets(ctx, ...charsets)` → best match or `false`.
+ */
+export function acceptsCharsets(ctx: NegotiableCtx): string[]
+export function acceptsCharsets(ctx: NegotiableCtx, ...charsets: string[]): string | false
+export function acceptsCharsets(
+  ctx: NegotiableCtx,
+  ...charsets: string[]
+): string | false | string[] {
+  const header = readHeader(ctx, 'accept-charset')
+  if (charsets.length === 0) return parseAcceptHeader(header).map((e) => e.type)
+  return selectBest(header, charsets)
+}
+
+/**
+ * `acceptsLanguages(ctx)` → all languages in preference order.
+ * `acceptsLanguages(ctx, ...langs)` → best match or `false`.
+ *
+ * Language matching is treated like opaque tokens with `*` as wildcard;
+ * partial-tag matching (e.g. `en` matching `en-US`) is **not** performed —
+ * use exact tags for predictable behavior, mirroring Express's default.
+ */
+export function acceptsLanguages(ctx: NegotiableCtx): string[]
+export function acceptsLanguages(ctx: NegotiableCtx, ...langs: string[]): string | false
+export function acceptsLanguages(
+  ctx: NegotiableCtx,
+  ...langs: string[]
+): string | false | string[] {
+  const header = readHeader(ctx, 'accept-language')
+  if (langs.length === 0) return parseAcceptHeader(header).map((e) => e.type)
+  return selectBest(header, langs)
+}
+
+/**
+ * `acceptsEncodings(ctx)` → all encodings in preference order.
+ * `acceptsEncodings(ctx, ...encodings)` → best match or `false`.
+ *
+ * Per RFC 9110 §12.5.4, when `Accept-Encoding` is absent, the server
+ * MAY assume the client accepts any encoding — we follow Express and
+ * return the first offered.
+ */
+export function acceptsEncodings(ctx: NegotiableCtx): string[]
+export function acceptsEncodings(ctx: NegotiableCtx, ...encodings: string[]): string | false
+export function acceptsEncodings(
+  ctx: NegotiableCtx,
+  ...encodings: string[]
+): string | false | string[] {
+  const header = readHeader(ctx, 'accept-encoding')
+  if (encodings.length === 0) return parseAcceptHeader(header).map((e) => e.type)
+  return selectBest(header, encodings)
+}

package/src/openapi/describe.ts

@@ -0,0 +1,79 @@
+import type { HttpMethod } from '../router/types.ts'
+import type {
+  Operation,
+  Parameter,
+  RequestBody,
+  Response,
+  SecurityRequirement,
+} from './types.ts'
+
+/**
+ * Per-route metadata supplied via `app.describe('METHOD', '/path', meta)`.
+ * Merged into the generated Operation by `generateOpenApi`.
+ *
+ * Anything you put here ends up on the operation object verbatim, except:
+ * - `hidden: true` skips the route entirely (won't appear in the spec).
+ * - `parameters` are *appended* to the path-param parameters extracted from
+ *   the route syntax, so you typically only put `query`, `header`, or
+ *   `cookie` parameters here.
+ */
+export interface RouteDescriptor {
+  summary?: string
+  description?: string
+  operationId?: string
+  tags?: string[]
+  deprecated?: boolean
+  hidden?: boolean
+  parameters?: Parameter[]
+  requestBody?: RequestBody
+  responses?: Record<string | number, Response>
+  security?: SecurityRequirement[]
+  /** Extension passthrough — anything starting with `x-` is preserved. */
+  [extension: `x-${string}`]: unknown
+}
+
+/** Stable lookup key used by the descriptor map. */
+export function descriptorKey(method: HttpMethod, path: string): string {
+  return `${method} ${path}`
+}
+
+/**
+ * Merge a `RouteDescriptor` onto a base `Operation` (which already carries
+ * the path parameters extracted from the route syntax). Mutates and returns
+ * the base operation for caller convenience.
+ *
+ * Order rules:
+ * - `parameters` are concatenated (path params first, descriptor params after).
+ * - `responses` map keys are normalized to strings (200 → '200').
+ * - Extensions (`x-*`) are copied verbatim.
+ */
+export function mergeDescriptor(
+  base: Operation,
+  desc: RouteDescriptor | undefined,
+): Operation {
+  if (!desc) return base
+  if (desc.summary !== undefined) base.summary = desc.summary
+  if (desc.description !== undefined) base.description = desc.description
+  if (desc.operationId !== undefined) base.operationId = desc.operationId
+  if (desc.tags !== undefined) base.tags = [...desc.tags]
+  if (desc.deprecated !== undefined) base.deprecated = desc.deprecated
+  if (desc.security !== undefined) base.security = desc.security
+  if (desc.requestBody !== undefined) base.requestBody = desc.requestBody
+  if (desc.parameters && desc.parameters.length > 0) {
+    base.parameters = [...(base.parameters ?? []), ...desc.parameters]
+  }
+  if (desc.responses) {
+    const out: Record<string, Response> = {}
+    for (const k of Object.keys(desc.responses)) {
+      out[String(k)] = desc.responses[k as keyof typeof desc.responses] as Response
+    }
+    base.responses = out
+  }
+  // Copy x-* extensions verbatim.
+  for (const k of Object.keys(desc)) {
+    if (k.startsWith('x-')) {
+      ;(base as Record<string, unknown>)[k] = (desc as Record<string, unknown>)[k]
+    }
+  }
+  return base
+}

package/src/openapi/extract-params.ts

@@ -0,0 +1,62 @@
+import type { Parameter } from './types.ts'
+
+/**
+ * Extract OpenAPI `path` parameter descriptors from a Ingenium route
+ * pattern. Mirrors the path syntax documented in `API.md`:
+ *
+ * - `/users/:id`        → required string param `id`
+ * - `/users/:id?`       → optional string param `id`
+ * - `/files/*path`      → required string param `path` (greedy tail)
+ *
+ * All extracted params get `schema: { type: 'string' }` since Ingenium
+ * preserves URL segments as raw strings; consumers can override the schema
+ * via `app.describe()` if they want a tighter type (e.g. integer ids).
+ *
+ * Pure function: deterministic, no allocations beyond the result array.
+ *
+ * @example
+ * extractPathParams('/users/:id/posts/:slug?')
+ * // [
+ * //   { name: 'id', in: 'path', required: true, schema: { type: 'string' } },
+ * //   { name: 'slug', in: 'path', required: false, schema: { type: 'string' } },
+ * // ]
+ */
+export function extractPathParams(path: string): Parameter[] {
+  if (!path) return []
+  const params: Parameter[] = []
+  const segments = path.split('/')
+
+  for (const seg of segments) {
+    if (!seg) continue
+    if (seg[0] === ':') {
+      // Trim a single trailing `?` to detect optionality.
+      const isOptional = seg.endsWith('?')
+      const name = isOptional ? seg.slice(1, -1) : seg.slice(1)
+      if (!name) continue
+      params.push({
+        name,
+        in: 'path',
+        // OpenAPI 3.1: path parameters MUST be required: true. If the route
+        // declares an optional segment, the server actually accepts two
+        // distinct paths (with and without the segment). For correctness in
+        // generated specs, we still emit required: true and surface the
+        // optionality via an `x-rift-optional` extension; tools that need it
+        // can split the path themselves.
+        required: !isOptional,
+        schema: { type: 'string' },
+        ...(isOptional ? { 'x-rift-optional': true } : {}),
+      })
+    } else if (seg[0] === '*') {
+      const name = seg.slice(1) || 'wildcard'
+      params.push({
+        name,
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+        'x-rift-wildcard': true,
+      })
+    }
+  }
+
+  return params
+}