ingenium 0.0.1

package/src/body/limit.ts

@@ -0,0 +1,21 @@
+import { Transform, type TransformCallback } from 'node:stream'
+import { IngeniumPayloadTooLargeError } from '../errors.ts'
+
+/**
+ * A `Transform` stream that aborts with `IngeniumPayloadTooLargeError` as soon as
+ * cumulative throughput exceeds `maxBytes`. The check happens before the
+ * chunk is emitted downstream, so consumers never see bytes past the limit.
+ */
+export function createByteLimit(maxBytes: number): Transform {
+  let total = 0
+  return new Transform({
+    transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback) {
+      total += chunk.length
+      if (total > maxBytes) {
+        callback(new IngeniumPayloadTooLargeError(`Request body exceeded ${maxBytes} bytes`))
+        return
+      }
+      callback(null, chunk)
+    },
+  })
+}

package/src/body/middleware.ts

@@ -0,0 +1,30 @@
+import type { IngeniumMiddleware } from '../middleware/types.ts'
+
+/**
+ * Express compatibility shim. In Ingenium, body parsing is lazy via
+ * `ctx.body.json()` / `ctx.body.urlencoded()` / `ctx.body.text()` — there is
+ * no parse-on-every-request middleware to register. This factory exists so
+ * existing `app.use(express.json())` migration patterns keep compiling and
+ * reading naturally; the returned middleware is a zero-cost no-op.
+ *
+ * If you need to enforce a default `maxBytes` across all body access, set it
+ * via the `limit` option here and read it inside your handlers when calling
+ * `ctx.body.json({ limit })` — Ingenium doesn't store it implicitly.
+ *
+ * @returns a no-op middleware
+ */
+export function jsonMiddleware(_opts?: { limit?: number }): IngeniumMiddleware {
+  return async (_ctx, next) => {
+    await next()
+  }
+}
+
+/**
+ * See `jsonMiddleware` — same rationale. URL-encoded parsing is lazy via
+ * `ctx.body.urlencoded()`.
+ */
+export function urlencodedMiddleware(_opts?: { limit?: number }): IngeniumMiddleware {
+  return async (_ctx, next) => {
+    await next()
+  }
+}

package/src/body/multipart-types.ts

@@ -0,0 +1,40 @@
+import type { Buffer } from 'node:buffer'
+
+/**
+ * Options for `IngeniumBody.multipart()`.
+ *
+ * All limits are validated mid-parse — exceeding any of them throws before
+ * the full body is fully decoded so memory usage stays bounded.
+ */
+export interface MultipartOptions {
+  /** Total request body cap. Default 100,000 bytes (matches Express's body-parser default). */
+  maxBytes?: number
+  /** Per-file size cap. Default 10 * 1024 * 1024 (10 MiB). */
+  maxFileSize?: number
+  /** Maximum number of file parts in one request. Default 20. */
+  maxFiles?: number
+  /** Maximum number of plain (non-file) field parts. Default 100. */
+  maxFields?: number
+  /** Allowed MIME prefixes (e.g. ['image/']). File rejected if no prefix matches. Default: any. */
+  allowedMimePrefixes?: string[]
+}
+
+/** A single uploaded file part, fully buffered. */
+export interface MultipartFile {
+  /** Original filename as supplied by the client. */
+  filename: string
+  /** MIME type from the part's `Content-Type` header (defaults to `application/octet-stream`). */
+  mimeType: string
+  /** Byte length of `data`. */
+  size: number
+  /** Raw file bytes — fully buffered. For very large uploads, prefer `ctx.body.stream()`. */
+  data: Buffer
+}
+
+/** Result of parsing a `multipart/form-data` body. */
+export interface MultipartResult {
+  /** Plain-text form fields keyed by name. Repeated names collapse into an array. */
+  fields: Record<string, string | string[]>
+  /** File parts keyed by name. Repeated names collapse into an array. */
+  files: Record<string, MultipartFile | MultipartFile[]>
+}

package/src/body/multipart.ts

@@ -0,0 +1,254 @@
+import { Buffer } from 'node:buffer'
+import { IngeniumBadRequestError, IngeniumPayloadTooLargeError } from '../errors.ts'
+import type { MultipartFile, MultipartOptions, MultipartResult } from './multipart-types.ts'
+
+/** Default per-file cap: 10 MiB. */
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024
+/** Default file-count cap. */
+const DEFAULT_MAX_FILES = 20
+/** Default field-count cap. */
+const DEFAULT_MAX_FIELDS = 100
+
+const CRLF = Buffer.from('\r\n')
+const DOUBLE_CRLF = Buffer.from('\r\n\r\n')
+const DASH_DASH = Buffer.from('--')
+
+/**
+ * Extract the `boundary` parameter from a `Content-Type` header.
+ * Per RFC 7578 / RFC 2046 the boundary is required and case-insensitive
+ * parameter name; the value may be quoted.
+ */
+function extractBoundary(contentType: string | undefined): string {
+  if (!contentType) {
+    throw new IngeniumBadRequestError('Content-Type header missing')
+  }
+  // The mime type itself is case-insensitive.
+  const lower = contentType.toLowerCase()
+  if (!lower.startsWith('multipart/form-data')) {
+    throw new IngeniumBadRequestError('Content-Type is not multipart/form-data')
+  }
+  // Walk parameters: split on `;` but only after the type. We don't bother with
+  // RFC 2231 continuations — boundaries are restricted to a 70-char ASCII subset.
+  const params = contentType.slice(contentType.indexOf(';') + 1).split(';')
+  for (const raw of params) {
+    const eq = raw.indexOf('=')
+    if (eq === -1) continue
+    const name = raw.slice(0, eq).trim().toLowerCase()
+    if (name !== 'boundary') continue
+    let value = raw.slice(eq + 1).trim()
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1)
+    }
+    if (value.length === 0) {
+      throw new IngeniumBadRequestError('multipart boundary is empty')
+    }
+    return value
+  }
+  throw new IngeniumBadRequestError('multipart boundary missing')
+}
+
+interface PartHeaders {
+  /** form-data field name (`Content-Disposition: ...; name="..."`). */
+  name: string
+  /** filename, if present. Presence marks the part as a file. */
+  filename: string | undefined
+  /** Content-Type header, if present. */
+  contentType: string | undefined
+}
+
+/**
+ * Parse the headers of a single part from a header-block string (already
+ * split off at the `\r\n\r\n` boundary). Header names are case-insensitive.
+ */
+function parsePartHeaders(block: string): PartHeaders {
+  const lines = block.split('\r\n')
+  let name: string | undefined
+  let filename: string | undefined
+  let contentType: string | undefined
+
+  for (const line of lines) {
+    if (line.length === 0) continue
+    const colon = line.indexOf(':')
+    if (colon === -1) {
+      throw new IngeniumBadRequestError('Malformed multipart body: invalid header line')
+    }
+    const headerName = line.slice(0, colon).trim().toLowerCase()
+    const headerValue = line.slice(colon + 1).trim()
+
+    if (headerName === 'content-disposition') {
+      // form-data; name="x"; filename="y"
+      const params = headerValue.split(';')
+      // First token is the disposition (`form-data`); we only accept that.
+      const disposition = params[0]?.trim().toLowerCase()
+      if (disposition !== 'form-data') {
+        throw new IngeniumBadRequestError('Malformed multipart body: unsupported Content-Disposition')
+      }
+      for (let i = 1; i < params.length; i++) {
+        const p = params[i]!
+        const eq = p.indexOf('=')
+        if (eq === -1) continue
+        const k = p.slice(0, eq).trim().toLowerCase()
+        let v = p.slice(eq + 1).trim()
+        if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1)
+        // Decode common escapes (\" and \\) — RFC 7578 references RFC 2183.
+        v = v.replace(/\\(.)/g, '$1')
+        if (k === 'name') name = v
+        else if (k === 'filename') filename = v
+      }
+    } else if (headerName === 'content-type') {
+      contentType = headerValue
+    }
+    // Other headers (Content-Transfer-Encoding etc.) are ignored.
+  }
+
+  if (name === undefined) {
+    throw new IngeniumBadRequestError('Malformed multipart body: missing form-data name')
+  }
+  return { name, filename, contentType }
+}
+
+/**
+ * Stash a parsed field into `fields` / `files`, collapsing repeated names
+ * into arrays in arrival order. Mixing field+file under one name follows
+ * arrival order too (rare; not specifically supported).
+ */
+function appendField(
+  result: MultipartResult,
+  headers: PartHeaders,
+  body: Buffer,
+): void {
+  if (headers.filename !== undefined) {
+    const file: MultipartFile = {
+      filename: headers.filename,
+      mimeType: headers.contentType ?? 'application/octet-stream',
+      size: body.length,
+      data: body,
+    }
+    const existing = result.files[headers.name]
+    if (existing === undefined) {
+      result.files[headers.name] = file
+    } else if (Array.isArray(existing)) {
+      existing.push(file)
+    } else {
+      result.files[headers.name] = [existing, file]
+    }
+  } else {
+    const value = body.toString('utf8')
+    const existing = result.fields[headers.name]
+    if (existing === undefined) {
+      result.fields[headers.name] = value
+    } else if (Array.isArray(existing)) {
+      existing.push(value)
+    } else {
+      result.fields[headers.name] = [existing, value]
+    }
+  }
+}
+
+/**
+ * Parse a `multipart/form-data` request body. Operates on raw bytes — boundary
+ * sequences can legally appear inside binary file payloads, so we never
+ * convert the payload to a string before splitting.
+ *
+ * @param buffer Full body bytes (already buffered & length-checked by caller).
+ * @param contentType Raw `Content-Type` header — boundary is extracted from it.
+ * @param opts Limits and filters.
+ */
+export function parseMultipart(
+  buffer: Buffer,
+  contentType: string | undefined,
+  opts: MultipartOptions = {},
+): MultipartResult {
+  const maxFileSize = opts.maxFileSize ?? DEFAULT_MAX_FILE_SIZE
+  const maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES
+  const maxFields = opts.maxFields ?? DEFAULT_MAX_FIELDS
+  const allowed = opts.allowedMimePrefixes
+
+  const boundary = extractBoundary(contentType)
+  const result: MultipartResult = { fields: {}, files: {} }
+
+  // Empty body → empty result. (No boundary delimiter at all.)
+  if (buffer.length === 0) return result
+
+  // RFC 7578: each part is preceded by `--<boundary>`. The first occurrence
+  // may not be at byte 0 (a "preamble" is permitted but must be ignored).
+  const dashBoundary = Buffer.concat([DASH_DASH, Buffer.from(boundary)])
+
+  let cursor = buffer.indexOf(dashBoundary)
+  if (cursor === -1) {
+    throw new IngeniumBadRequestError('Malformed multipart body: opening boundary not found')
+  }
+  cursor += dashBoundary.length
+
+  let fileCount = 0
+  let fieldCount = 0
+
+  // Loop over parts. After each `--<boundary>` we expect either:
+  //   `--`     → final close delimiter (end of stream)
+  //   `\r\n`   → start of a part (headers follow)
+  // anything else is malformed.
+  for (;;) {
+    if (cursor + 2 > buffer.length) {
+      throw new IngeniumBadRequestError('Malformed multipart body: truncated after boundary')
+    }
+    // Final delimiter: `--<boundary>--`
+    if (buffer[cursor] === 0x2d && buffer[cursor + 1] === 0x2d) {
+      // Close delimiter — done. We deliberately accept any trailing epilogue.
+      return result
+    }
+    // Otherwise expect CRLF before headers.
+    if (buffer[cursor] !== 0x0d || buffer[cursor + 1] !== 0x0a) {
+      throw new IngeniumBadRequestError('Malformed multipart body: expected CRLF after boundary')
+    }
+    cursor += 2
+
+    // Header block ends at the first `\r\n\r\n`.
+    const headerEnd = buffer.indexOf(DOUBLE_CRLF, cursor)
+    if (headerEnd === -1) {
+      throw new IngeniumBadRequestError('Malformed multipart body: missing header terminator')
+    }
+    const headerBlock = buffer.slice(cursor, headerEnd).toString('utf8')
+    const headers = parsePartHeaders(headerBlock)
+    cursor = headerEnd + DOUBLE_CRLF.length
+
+    // Body bytes run until the next `\r\n--<boundary>`. Boundaries may appear
+    // inside binary payloads so we MUST scan bytes, not strings.
+    const delimiter = Buffer.concat([CRLF, dashBoundary])
+    const partEnd = buffer.indexOf(delimiter, cursor)
+    if (partEnd === -1) {
+      throw new IngeniumBadRequestError('Malformed multipart body: missing closing boundary')
+    }
+
+    const partBody = buffer.slice(cursor, partEnd)
+
+    if (headers.filename !== undefined) {
+      // File part — apply size + count + mime checks.
+      if (partBody.length > maxFileSize) {
+        throw new IngeniumPayloadTooLargeError(
+          `File "${headers.filename}" exceeded ${maxFileSize} bytes`,
+        )
+      }
+      if (allowed && allowed.length > 0) {
+        const mime = (headers.contentType ?? 'application/octet-stream').toLowerCase()
+        const ok = allowed.some((prefix) => mime.startsWith(prefix.toLowerCase()))
+        if (!ok) {
+          throw new IngeniumBadRequestError('Disallowed mime type')
+        }
+      }
+      fileCount++
+      if (fileCount > maxFiles) {
+        throw new IngeniumBadRequestError('Too many files')
+      }
+    } else {
+      fieldCount++
+      if (fieldCount > maxFields) {
+        throw new IngeniumBadRequestError('Too many fields')
+      }
+    }
+
+    appendField(result, headers, partBody)
+
+    cursor = partEnd + delimiter.length
+    // Next iteration will check for `--` (close) or `\r\n` (next part).
+  }
+}

package/src/context/body.ts

@@ -0,0 +1,324 @@
+import type { Readable } from 'node:stream'
+import { Buffer } from 'node:buffer'
+import { IngeniumBadRequestError, IngeniumPayloadTooLargeError, IngeniumValidationError } from '../errors.ts'
+import { createByteLimit } from '../body/limit.ts'
+import { parseMultipart } from '../body/multipart.ts'
+import type { MultipartOptions, MultipartResult } from '../body/multipart-types.ts'
+import {
+  isStandardSchema,
+  type StandardIssue,
+  type StandardSchemaV1,
+} from '../schema/standard.ts'
+
+/** Minimal duck-type for any validation library that accepts unknown and returns a typed value. */
+export interface ParseSchema<T> {
+  parse(input: unknown): T
+}
+
+/** Optional Zod-like schema: success/failure object output (used internally for friendlier errors). */
+export interface SafeParseSchema<T> {
+  safeParse(input: unknown): { success: true; data: T } | { success: false; error: { issues: ZodLikeIssue[] } }
+}
+
+interface ZodLikeIssue {
+  path: ReadonlyArray<string | number>
+  message: string
+}
+
+/** Normalize a Standard Schema issue path into a dot-joined field key. */
+function standardPathToField(path: StandardIssue['path']): string {
+  if (!path || path.length === 0) return '_'
+  const parts: string[] = []
+  for (const seg of path) {
+    if (seg !== null && typeof seg === 'object' && 'key' in seg) {
+      parts.push(String(seg.key))
+    } else {
+      parts.push(String(seg))
+    }
+  }
+  return parts.join('.') || '_'
+}
+
+/**
+ * Default body size limit for `IngeniumBody.json/text/urlencoded/buffer`.
+ * 100,000 bytes matches Express's `body-parser` default (`'100kb'`),
+ * which is the convention every Express app implicitly relies on. Override
+ * per-call (`ctx.body.json(undefined, 5_000_000)`) or set a different
+ * default by configuring your `ingenium.json({ limit })` middleware (the
+ * middleware is currently a stub — see `body/middleware.ts`).
+ */
+const DEFAULT_MAX_BYTES = 100_000
+
+/**
+ * Lazy body accessor. Bytes are not read until one of the consume methods
+ * (`json`, `text`, `urlencoded`, `buffer`, `stream`) is called.
+ *
+ * One instance is allocated per `IngeniumContext` (pool-bound), so per-request
+ * cost is just a `reset()`.
+ */
+export class IngeniumBody {
+  /** @internal */ _source: Readable | null = null
+  /** @internal */ _consumed = false
+  /** @internal */ _contentType: string | undefined = undefined
+  /** @internal */ _contentLength: number | undefined = undefined
+  /**
+   * @internal
+   * Parse cache. Stores the raw body bytes after the first successful
+   * `buffer()` (or `text()` / `json()` / `urlencoded()`, which all go
+   * through `buffer()`). Subsequent buffer-producing consumers reuse
+   * these bytes instead of throwing "already consumed".
+   *
+   * Caches the RAW Buffer (not parsed objects) so different callers can
+   * apply different schemas / decoders against the same bytes — a
+   * common pattern when an audit middleware reads the body before the
+   * handler does. Re-parsing JSON from a cached buffer is cheap; mixing
+   * schemas against a cached parsed object would be incorrect.
+   *
+   * `stream()` opts out (it hands the caller ownership of the raw
+   * Readable) and `multipart()` opts out (its result is bespoke and
+   * re-parsing with different options would be ambiguous).
+   *
+   * Checked with `!== null` rather than truthiness so an empty body
+   * (`Buffer.alloc(0)`) still hits the cache on subsequent reads.
+   */
+  /** @internal */ _cached: Buffer | null = null
+
+  /** @internal Adapter calls this on each request before dispatch. */
+  _attach(source: Readable | null, contentType: string | undefined, contentLength: number | undefined): void {
+    this._source = source
+    this._consumed = false
+    this._contentType = contentType
+    this._contentLength = contentLength
+    this._cached = null
+  }
+
+  /** @internal Pool reset. */
+  _reset(): void {
+    this._source = null
+    this._consumed = false
+    this._contentType = undefined
+    this._contentLength = undefined
+    this._cached = null
+  }
+
+  /**
+   * Returns the raw request body stream. Throws if already consumed OR
+   * if the body has already been buffered (cached) — once we hold the
+   * bytes, we can't hand the caller back a fresh Readable to own.
+   */
+  stream(): Readable {
+    if (this._cached !== null) throw new IngeniumBadRequestError('Request body already consumed')
+    if (this._consumed) throw new IngeniumBadRequestError('Request body already consumed')
+    if (!this._source) throw new IngeniumBadRequestError('Request has no body')
+    this._consumed = true
+    return this._source
+  }
+
+  /**
+   * Buffers the entire body into a `Buffer`. Honors `maxBytes` (default 100KB).
+   *
+   * If the body has already been buffered once (by any prior `buffer()`,
+   * `text()`, `json()`, or `urlencoded()` call), returns the cached bytes
+   * — `maxBytes` is still enforced against `cached.length`, so a caller
+   * passing a tighter cap than the original still gets a 413.
+   */
+  async buffer(maxBytes: number = DEFAULT_MAX_BYTES): Promise<Buffer> {
+    // Cached path: reuse bytes, but honor the caller's ceiling.
+    if (this._cached !== null) {
+      if (this._cached.length > maxBytes) {
+        throw new IngeniumPayloadTooLargeError(
+          `Request body exceeded ${maxBytes} bytes`,
+        )
+      }
+      return this._cached
+    }
+    if (this._consumed) throw new IngeniumBadRequestError('Request body already consumed')
+    if (!this._source) {
+      // Empty body — cache the empty buffer so subsequent consumers
+      // also hit the cached path (consistent semantics).
+      this._cached = Buffer.alloc(0)
+      return this._cached
+    }
+    this._consumed = true
+
+    const cl = this._contentLength
+    if (cl !== undefined && cl > maxBytes) {
+      // Drain source so the connection can be reused.
+      this._source.resume()
+      throw new IngeniumPayloadTooLargeError(
+        `Request body exceeded ${maxBytes} bytes`,
+      )
+    }
+
+    const source = this._source
+
+    // Fast path: Content-Length is known and within cap. Pre-allocate exactly
+    // one Buffer and copy chunks directly into it — eliminates the chunks[]
+    // array, the per-chunk push, and the final Buffer.concat copy. Same
+    // observable behavior, ~2-3 fewer allocations per request, and a single
+    // contiguous write instead of a copy-then-walk.
+    //
+    // The transport-layer Transform may already be installed; that's fine —
+    // it just no-ops for in-bounds bodies. We do not install a second one
+    // here when we know the length (the transport already enforced).
+    if (cl !== undefined && cl >= 0) {
+      const buf = Buffer.allocUnsafe(cl)
+      let offset = 0
+      return new Promise<Buffer>((resolve, reject) => {
+        source.on('data', (chunk: Buffer) => {
+          // Defensive: clamp to declared length so a misbehaving stream
+          // can't write past our pre-allocated buffer. (`node:http` itself
+          // already enforces Content-Length, so this is belt + suspenders.)
+          const remaining = cl - offset
+          if (remaining <= 0) return
+          const n = chunk.length <= remaining ? chunk.length : remaining
+          chunk.copy(buf, offset, 0, n)
+          offset += n
+        })
+        source.on('end', () => {
+          // If the client truncated, return the partial buffer (matches the
+          // chunks-then-concat path's behavior pre-optimization).
+          const result = offset === cl ? buf : buf.subarray(0, offset)
+          // Cache before resolving so a follow-up consumer that awaits this
+          // same promise can read `_cached` immediately after.
+          this._cached = result
+          resolve(result)
+        })
+        source.on('error', reject)
+      })
+    }
+
+    // Unknown length (chunked encoding, no Content-Length) — fall back to
+    // the chunks + Buffer.concat path with the byte-limit Transform on top.
+    const limited = source.pipe(createByteLimit(maxBytes))
+    const chunks: Buffer[] = []
+    return new Promise<Buffer>((resolve, reject) => {
+      limited.on('data', (chunk: Buffer) => chunks.push(chunk))
+      limited.on('end', () => {
+        const result = Buffer.concat(chunks)
+        this._cached = result
+        resolve(result)
+      })
+      limited.on('error', reject)
+    })
+  }
+
+  /** Buffers the body and decodes as UTF-8 text. */
+  async text(maxBytes?: number): Promise<string> {
+    const buf = await this.buffer(maxBytes)
+    return buf.length === 0 ? '' : buf.toString('utf8')
+  }
+
+  /**
+   * Parses the body as JSON. If a schema is provided, the parsed value is
+   * validated. Detection order:
+   *
+   *   1. Standard Schema v1 (`["~standard"]`) — async-aware, multi-issue
+   *   2. Zod-like `safeParse(input)` — multi-issue
+   *   3. Plain `parse(input): T` — throws on failure
+   *
+   * Validation failures are normalized into `IngeniumValidationError` with a
+   * field-level `fields` map (dot-joined paths; empty path → `_`).
+   */
+  async json<T = unknown>(
+    schema?: StandardSchemaV1<unknown, T> | SafeParseSchema<T> | ParseSchema<T>,
+    maxBytes?: number,
+  ): Promise<T> {
+    // Inline `text()` to skip one async indirection (one microtask saved
+    // per ctx.body.json() call). Same observable behavior.
+    const buf = await this.buffer(maxBytes)
+    const text = buf.length === 0 ? '' : buf.toString('utf8')
+    let parsed: unknown
+    try {
+      parsed = text.length === 0 ? null : JSON.parse(text)
+    } catch (err) {
+      throw new IngeniumBadRequestError('Invalid JSON', err)
+    }
+    if (schema) {
+      // 1. Standard Schema v1 — most modern, takes precedence.
+      if (isStandardSchema(schema)) {
+        const maybe = schema['~standard'].validate(parsed)
+        const result = maybe instanceof Promise ? await maybe : maybe
+        if (result.issues) {
+          const fields: Record<string, string> = {}
+          for (const issue of result.issues) {
+            fields[standardPathToField(issue.path)] = issue.message
+          }
+          throw new IngeniumValidationError(fields)
+        }
+        return result.value as T
+      }
+      // 2. Zod-like safeParse.
+      if ('safeParse' in schema && typeof (schema as SafeParseSchema<T>).safeParse === 'function') {
+        const result = (schema as SafeParseSchema<T>).safeParse(parsed)
+        if (!result.success) {
+          const fields: Record<string, string> = {}
+          for (const issue of result.error.issues) {
+            fields[issue.path.join('.') || '_'] = issue.message
+          }
+          throw new IngeniumValidationError(fields)
+        }
+        return result.data
+      }
+      // 3. Plain parse.
+      try {
+        return (schema as ParseSchema<T>).parse(parsed)
+      } catch (err) {
+        throw new IngeniumValidationError({ _: (err as Error).message ?? 'validation failed' })
+      }
+    }
+    return parsed as T
+  }
+
+  /** Parses the body as `application/x-www-form-urlencoded`. */
+  async urlencoded(maxBytes?: number): Promise<Record<string, string>> {
+    const text = await this.text(maxBytes)
+    const params = new URLSearchParams(text)
+    const out: Record<string, string> = {}
+    for (const [k, v] of params) out[k] = v
+    return out
+  }
+
+  /**
+   * Parses the body as `multipart/form-data` (RFC 7578).
+   *
+   * Returns plain-text fields and fully buffered file parts. For very large
+   * uploads prefer `stream()` and parse manually — this method holds every
+   * file in memory.
+   *
+   * Failure modes:
+   * - Body exceeds `maxBytes` → `IngeniumPayloadTooLargeError`
+   * - Single file exceeds `maxFileSize` → `IngeniumPayloadTooLargeError`
+   * - Too many files / fields → `IngeniumBadRequestError`
+   * - Disallowed mime type → `IngeniumBadRequestError`
+   * - Content-Type isn't `multipart/form-data` or boundary missing → `IngeniumBadRequestError`
+   * - Malformed body → `IngeniumBadRequestError`
+   */
+  async multipart(opts: MultipartOptions = {}): Promise<MultipartResult> {
+    // Multipart opts out of the buffer cache. Unlike json/text/urlencoded —
+    // which all return idempotent decodings of the same bytes — multipart's
+    // result is bespoke (file parts, field limits, mime allow-lists), and
+    // re-parsing the same bytes under different `opts` would silently return
+    // a different shape. Safer to treat multipart as a terminal consumer:
+    // it runs once, then any further body access throws.
+    //
+    // To enforce that, we either consume the live stream (first call) or
+    // read the cached buffer (someone called .text()/.json() first), then
+    // immediately invalidate both — clearing `_cached` and setting
+    // `_consumed = true` so subsequent .json()/.text()/.multipart()/.stream()
+    // calls throw "already consumed".
+    const contentType = this._contentType
+    const buf = await this.buffer(opts.maxBytes ?? DEFAULT_MAX_BYTES)
+    this._cached = null
+    this._consumed = true
+    try {
+      return parseMultipart(buf, contentType, opts)
+    } catch (err) {
+      // Preserve framework errors (415/413/400) as-is.
+      if (err instanceof IngeniumPayloadTooLargeError || err instanceof IngeniumBadRequestError) {
+        throw err
+      }
+      throw new IngeniumBadRequestError('Malformed multipart body', err)
+    }
+  }
+}