ingenium 0.0.1

package/src/transport/http2-helpers.ts

@@ -0,0 +1,242 @@
+import type { ServerHttp2Stream, IncomingHttpHeaders as Http2IncomingHeaders } from 'node:http2'
+import { constants as h2 } from 'node:http2'
+import type { IncomingHttpHeaders } from 'node:http'
+import type { IngeniumContext } from '../context/context.ts'
+import type { HttpMethod } from '../router/types.ts'
+import { createByteLimit } from '../body/limit.ts'
+
+/**
+ * HTTP/2 pseudo-headers (RFC 7540 §8.1.2.1). These appear as keys on the
+ * `headers` object when reading an inbound stream and must NOT be passed to
+ * any setHeader-style API on outbound responses (Node throws). Strip them
+ * from `ctx.headers` so user middleware sees a Node-http-compatible shape.
+ */
+const PSEUDO_HEADERS = new Set<string>([':method', ':path', ':scheme', ':authority', ':status'])
+
+/**
+ * Some HTTP/1 hop-by-hop headers are forbidden in HTTP/2 (RFC 7540 §8.1.2.2).
+ * Strip these from outbound responses if a handler set them — `Transfer-Encoding`
+ * is the most common offender (Express habit) and `connection` is implicit.
+ */
+const FORBIDDEN_RESPONSE_HEADERS = new Set<string>([
+  'transfer-encoding',
+  'connection',
+  'keep-alive',
+  'proxy-connection',
+  'upgrade',
+])
+
+/**
+ * Populate a pooled `IngeniumContext` from an inbound HTTP/2 stream + headers map.
+ * Mirrors `node.ts`'s `populateContext` but unpacks pseudo-headers and
+ * uppercases the method (HTTP/2 sends it lowercase per node:http2 convention).
+ */
+export function populateFromH2(
+  ctx: IngeniumContext,
+  stream: ServerHttp2Stream,
+  headers: Http2IncomingHeaders,
+  maxRequestBytes: number,
+): void {
+  const rawMethod = headers[h2.HTTP2_HEADER_METHOD]
+  ctx.method = (typeof rawMethod === 'string' ? rawMethod.toUpperCase() : 'GET') as HttpMethod
+
+  const rawPath = headers[h2.HTTP2_HEADER_PATH]
+  const url = typeof rawPath === 'string' ? rawPath : '/'
+  ctx.url = url
+
+  // Split path / query without allocating a URL object — same trick as NodeAdapter.
+  const qIdx = url.indexOf('?')
+  if (qIdx >= 0) {
+    ctx.path = url.slice(0, qIdx)
+    ctx.rawQuery = url.slice(qIdx + 1)
+  } else {
+    ctx.path = url
+    ctx.rawQuery = ''
+  }
+
+  // Filter pseudo-headers out of the user-visible `ctx.headers` so middleware
+  // sees an `IncomingHttpHeaders`-compatible bag.
+  const userHeaders: Record<string, string | string[] | undefined> = Object.create(null)
+  for (const name in headers) {
+    if (PSEUDO_HEADERS.has(name)) continue
+    userHeaders[name] = headers[name]
+  }
+  ctx.headers = userHeaders as IncomingHttpHeaders
+
+  const cl = userHeaders['content-length']
+  const contentLength = typeof cl === 'string' ? Number(cl) : undefined
+  const ct = typeof userHeaders['content-type'] === 'string' ? (userHeaders['content-type'] as string) : undefined
+
+  // The `ServerHttp2Stream` IS a Duplex with a Readable side — wrap it in the
+  // byte-limit Transform so the cap applies to EVERY consumer, including
+  // `ctx.body.stream()`. Three provably-safe skip conditions (mirror NodeAdapter):
+  //   1. Body-less method or Content-Length: 0
+  //   2. Cap disabled (Infinity)
+  //   3. Content-Length declared and ≤ cap (pre-check enforced; protocol
+  //      bounds the actual byte count to the declared length)
+  const noBody =
+    contentLength === 0 ||
+    ctx.method === 'GET' ||
+    ctx.method === 'HEAD' ||
+    ctx.method === 'OPTIONS'
+  const knownSafe =
+    contentLength !== undefined &&
+    Number.isFinite(contentLength) &&
+    contentLength <= maxRequestBytes
+  if (noBody || !Number.isFinite(maxRequestBytes) || knownSafe) {
+    ctx.body._attach(stream, ct, Number.isFinite(contentLength) ? contentLength : undefined)
+    return
+  }
+
+  // Cap unknown-length (chunked) bodies with a byte-limit Transform that
+  // becomes `ctx.body`'s source. Two failure modes have to be defended here,
+  // both rooted in `Stream.prototype.pipe` NOT forwarding `'error'` events:
+  //
+  //  1. Unhandled-error crash. When the cap trips, the Transform emits
+  //     `'error'`. The `body.stream()` consumer attaches its own listener, but
+  //     the chunked path in `IngeniumBody.buffer` re-pipes THIS Transform into
+  //     a second limiter and only listens on the DOWNSTREAM pipe — so this
+  //     Transform's `'error'` has no listener and becomes a process-killing
+  //     unhandled error (h2c has no socket-level teardown to swallow it).
+  //
+  //  2. Hung request. Because `pipe()` drops errors, that re-piped downstream
+  //     limiter never sees the overrun: it stops receiving data but never
+  //     `end`s or `error`s, so `body.buffer()`'s promise never settles and the
+  //     request hangs until the test/clien­t timeout.
+  //
+  // Fix both by (a) attaching a guard `'error'` listener so the event is always
+  // handled, and (b) forwarding the cap error to every stream this Transform
+  // was piped into, so re-piping consumers reject promptly. We deliberately do
+  // NOT touch the underlying h2 `stream` here: the 413 is produced by the body
+  // consumer's `IngeniumPayloadTooLargeError`, which the error boundary
+  // serializes and `writeH2Response` must flush on the still-open stream.
+  const limited = createByteLimit(maxRequestBytes)
+  const downstream = new Set<{ destroy(err?: Error): void; destroyed: boolean }>()
+  const origPipe = limited.pipe.bind(limited) as typeof limited.pipe
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  limited.pipe = function pipe(dest: any, ...rest: any[]) {
+    downstream.add(dest)
+    return origPipe(dest, ...rest)
+  } as typeof limited.pipe
+  limited.on('error', (err: Error) => {
+    for (const dest of downstream) {
+      if (!dest.destroyed) dest.destroy(err)
+    }
+    // Drain whatever inbound bytes the client is still sending. We stopped
+    // reading at the cap, so the raw h2 stream's readable side is left with
+    // unconsumed (and incoming) DATA frames. The response (413) flushes on the
+    // WRITABLE side, but a half-closed stream whose readable side never ends
+    // keeps the h2 SESSION's stream count > 0 — so a later graceful
+    // `client.close()` / `server.close()` hangs waiting for it. Unpipe the dead
+    // Transform and resume the raw stream to discard the rest, letting it reach
+    // `end` and the session close cleanly. `stream.on('error')` below absorbs
+    // any RST that arrives while draining.
+    stream.unpipe(limited)
+    stream.on('error', () => {})
+    stream.resume()
+  })
+  stream.pipe(limited)
+  ctx.body._attach(limited, ct, Number.isFinite(contentLength) ? contentLength : undefined)
+}
+
+/**
+ * Returns `true` (and writes a 413 response) if the inbound h2 stream's
+ * Content-Length exceeds the cap. Mirrors the Node adapter pre-check —
+ * called BEFORE `populateFromH2` so we don't even acquire a context for
+ * a request we're going to reject. Missing / invalid Content-Length →
+ * `false` (chunked-style framing, where the byte-limit catches the overrun).
+ */
+export function rejectH2IfContentLengthTooBig(
+  stream: ServerHttp2Stream,
+  headers: Http2IncomingHeaders,
+  maxRequestBytes: number,
+): boolean {
+  if (!Number.isFinite(maxRequestBytes)) return false
+  const raw = headers['content-length']
+  const cl = typeof raw === 'string' ? raw : Array.isArray(raw) ? raw[0] : undefined
+  if (typeof cl !== 'string' || cl.length === 0) return false
+  const n = Number(cl)
+  if (!Number.isFinite(n)) return false
+  if (n <= maxRequestBytes) return false
+
+  if (stream.destroyed || stream.closed) return true
+
+  // A client that declared an oversized Content-Length is, by definition,
+  // about to send (or has half-sent) body frames we will never read. When we
+  // respond + end early, the peer's continued DATA — or its own Content-Length
+  // bookkeeping if it later sends fewer bytes than declared — makes node:http2
+  // emit `ERR_HTTP2_STREAM_ERROR` on this stream. With no listener that is an
+  // unhandled-error crash. Absorb it: the 413 has already been delivered (or
+  // the stream is being torn down anyway), so there is nothing left to do.
+  stream.on('error', () => {
+    /* absorb late RST/protocol error from the rejected, never-read body */
+  })
+
+  try {
+    stream.respond({
+      [h2.HTTP2_HEADER_STATUS]: 413,
+      'content-type': 'application/json; charset=utf-8',
+    })
+    stream.end(
+      JSON.stringify({
+        error: `Request body exceeded ${maxRequestBytes} bytes`,
+        code: 'PAYLOAD_TOO_LARGE',
+      }),
+    )
+  } catch {
+    try {
+      stream.close(h2.NGHTTP2_INTERNAL_ERROR)
+    } catch {
+      stream.destroy()
+    }
+  }
+  return true
+}
+
+/**
+ * Write the `IngeniumContext` response state to an HTTP/2 stream. Handles all four
+ * `_body.kind` variants. HTTP/2 has no `Transfer-Encoding: chunked` (framing
+ * is implicit) and no hop-by-hop headers, so we strip those before responding.
+ */
+export function writeH2Response(ctx: IngeniumContext, stream: ServerHttp2Stream): void {
+  if (stream.destroyed || stream.closed) return
+
+  const responseHeaders: Record<string, string | string[] | number> = Object.create(null)
+  responseHeaders[h2.HTTP2_HEADER_STATUS] = ctx._statusCode
+
+  for (const name in ctx._headers) {
+    const lc = name.toLowerCase()
+    if (FORBIDDEN_RESPONSE_HEADERS.has(lc)) continue
+    if (PSEUDO_HEADERS.has(lc)) continue // defensive — shouldn't ever happen
+    const value = ctx._headers[name]
+    if (value !== undefined) responseHeaders[lc] = value
+  }
+
+  const body = ctx._body
+  switch (body.kind) {
+    case 'none':
+      stream.respond(responseHeaders, { endStream: true })
+      return
+    case 'string': {
+      if (responseHeaders['content-length'] === undefined) {
+        responseHeaders['content-length'] = Buffer.byteLength(body.data)
+      }
+      stream.respond(responseHeaders)
+      stream.end(body.data)
+      return
+    }
+    case 'buffer': {
+      if (responseHeaders['content-length'] === undefined) {
+        responseHeaders['content-length'] = body.data.length
+      }
+      stream.respond(responseHeaders)
+      stream.end(body.data)
+      return
+    }
+    case 'stream': {
+      stream.respond(responseHeaders)
+      body.data.pipe(stream)
+      return
+    }
+  }
+}

package/src/transport/http2.ts

@@ -0,0 +1,316 @@
+import {
+  createServer as createH2cServer,
+  createSecureServer as createH2Server,
+  constants as h2,
+  type Http2SecureServer,
+  type Http2Server,
+  type ServerHttp2Stream,
+  type IncomingHttpHeaders as Http2IncomingHeaders,
+  type Http2ServerRequest,
+  type Http2ServerResponse,
+} from 'node:http2'
+import type { Socket } from 'node:net'
+import type { TLSSocket } from 'node:tls'
+import type { IncomingHttpHeaders } from 'node:http'
+import type { HttpMethod } from '../router/types.ts'
+import type {
+  CloseOptions,
+  ListeningServer,
+  Transport,
+  TransportHooks,
+} from './types.ts'
+import { populateFromH2, rejectH2IfContentLengthTooBig, writeH2Response } from './http2-helpers.ts'
+import { createByteLimit } from '../body/limit.ts'
+
+/** TLS options accepted by the h2 (secure) adapter. */
+export interface Http2AdapterOptions {
+  /** TLS certificate (PEM). */
+  cert: Buffer | string
+  /** TLS private key (PEM). */
+  key: Buffer | string
+  /**
+   * If true, the secure server also accepts HTTP/1.1 connections via ALPN
+   * fallback. Inbound HTTP/1 requests are dispatched through the same path
+   * used by `NodeAdapter`. Default: false (HTTP/2 only).
+   */
+  allowHttp1?: boolean
+}
+
+/**
+ * HTTP/2-over-TLS (`h2`) transport. Uses Node's built-in `http2.createSecureServer`.
+ * Browsers REQUIRE TLS for HTTP/2 — there is no cleartext HTTP/2 negotiation
+ * over the open web. For local testing without certs, use {@link Http2cAdapter}.
+ *
+ * Per-request: on `'stream'`, populates a pooled `IngeniumContext` from pseudo-headers,
+ * awaits dispatch, then writes the response via `stream.respond()` + `stream.end()`
+ * (or pipes for `Readable` bodies).
+ */
+export class Http2Adapter implements Transport {
+  private hooks: TransportHooks | null = null
+
+  constructor(private readonly options: Http2AdapterOptions) {}
+
+  attach(hooks: TransportHooks): void {
+    this.hooks = hooks
+  }
+
+  async listen(port: number, host = '127.0.0.1'): Promise<ListeningServer> {
+    if (!this.hooks) throw new Error('Http2Adapter.listen() called before attach()')
+    const hooks = this.hooks
+
+    const server: Http2SecureServer = createH2Server({
+      cert: this.options.cert,
+      key: this.options.key,
+      allowHTTP1: this.options.allowHttp1 === true,
+    })
+
+    server.on('stream', (stream, headers) => {
+      handleStream(stream, headers, hooks).catch((err) => emergencyAbort(stream, err))
+    })
+
+    if (this.options.allowHttp1 === true) {
+      // ALPN fallback: HTTP/1.1 clients land here, NOT on `'stream'`.
+      server.on('request', (req, res) => {
+        handleHttp1Fallback(req, res, hooks).catch((err) => {
+          if (!res.headersSent) {
+            res.statusCode = 500
+            res.setHeader('content-type', 'application/json; charset=utf-8')
+            res.end(JSON.stringify({ error: 'Internal Server Error', code: 'INTERNAL_ERROR' }))
+          } else {
+            res.end()
+          }
+          process.emitWarning(`ingenium(h2/http1): dispatch leaked: ${(err as Error).message ?? String(err)}`)
+        })
+      })
+    }
+
+    return startServer(server, port, host)
+  }
+}
+
+/**
+ * HTTP/2 cleartext (`h2c`) transport. Uses Node's `http2.createServer` — no TLS,
+ * so this is intended for local development, internal service-to-service calls
+ * behind an L7 proxy that handles TLS termination, or test suites. Browsers do
+ * not speak h2c; use {@link Http2Adapter} for browser traffic.
+ *
+ * Constructor takes no required arguments.
+ */
+export class Http2cAdapter implements Transport {
+  private hooks: TransportHooks | null = null
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  constructor(_options: {} = {}) {
+    // Reserved for future tuning knobs (settings frame, max concurrent streams, …).
+  }
+
+  attach(hooks: TransportHooks): void {
+    this.hooks = hooks
+  }
+
+  async listen(port: number, host = '127.0.0.1'): Promise<ListeningServer> {
+    if (!this.hooks) throw new Error('Http2cAdapter.listen() called before attach()')
+    const hooks = this.hooks
+
+    const server: Http2Server = createH2cServer()
+
+    server.on('stream', (stream, headers) => {
+      handleStream(stream, headers, hooks).catch((err) => emergencyAbort(stream, err))
+    })
+
+    return startServer(server, port, host)
+  }
+}
+
+// ───── shared internals ─────────────────────────────────────────────────────
+
+async function handleStream(
+  stream: ServerHttp2Stream,
+  headers: Http2IncomingHeaders,
+  hooks: TransportHooks,
+): Promise<void> {
+  // Normalize the optional hook field — older fixtures may not set it.
+  const maxBytes = hooks.maxRequestBytes ?? Number.POSITIVE_INFINITY
+  // Reject oversized Content-Length BEFORE we acquire a context — the request
+  // is dead on arrival. Chunked / unknown-length bodies fall through to the
+  // byte-limit Transform installed by `populateFromH2`.
+  if (rejectH2IfContentLengthTooBig(stream, headers, maxBytes)) return
+
+  const ctx = hooks.acquire()
+  try {
+    populateFromH2(ctx, stream, headers, maxBytes)
+    await hooks.dispatch(ctx)
+    writeH2Response(ctx, stream)
+  } finally {
+    hooks.release(ctx)
+  }
+}
+
+/**
+ * HTTP/1.1 fallback path used when `allowHttp1` is set on `Http2Adapter`.
+ * Mirrors `NodeAdapter.populateContext` + `writeResponse`. We can't reuse
+ * `node.ts` directly because the framework should not import from a sibling
+ * adapter, and `Http2ServerRequest`/`Response` are subclasses of the http
+ * primitives but with the same surface — so we duplicate the small populate +
+ * write loop here.
+ */
+async function handleHttp1Fallback(
+  req: Http2ServerRequest,
+  res: Http2ServerResponse,
+  hooks: TransportHooks,
+): Promise<void> {
+  // Same Content-Length pre-check as the pure-h1 NodeAdapter path.
+  const maxBytes = hooks.maxRequestBytes ?? Number.POSITIVE_INFINITY
+  if (Number.isFinite(maxBytes)) {
+    const raw = req.headers['content-length']
+    if (typeof raw === 'string' && raw.length > 0) {
+      const n = Number(raw)
+      if (Number.isFinite(n) && n > maxBytes) {
+        res.statusCode = 413
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('connection', 'close')
+        res.end(
+          JSON.stringify({
+            error: `Request body exceeded ${maxBytes} bytes`,
+            code: 'PAYLOAD_TOO_LARGE',
+          }),
+        )
+        return
+      }
+    }
+  }
+
+  const ctx = hooks.acquire()
+  try {
+    ctx.method = (req.method ?? 'GET') as HttpMethod
+    const url = req.url ?? '/'
+    ctx.url = url
+    const qIdx = url.indexOf('?')
+    if (qIdx >= 0) {
+      ctx.path = url.slice(0, qIdx)
+      ctx.rawQuery = url.slice(qIdx + 1)
+    } else {
+      ctx.path = url
+      ctx.rawQuery = ''
+    }
+    ctx.headers = req.headers as unknown as IncomingHttpHeaders
+
+    const cl = req.headers['content-length']
+    const contentLength = typeof cl === 'string' ? Number(cl) : undefined
+    const ct = typeof req.headers['content-type'] === 'string' ? (req.headers['content-type'] as string) : undefined
+    const source = Number.isFinite(maxBytes) ? req.pipe(createByteLimit(maxBytes)) : req
+    ctx.body._attach(source, ct, Number.isFinite(contentLength) ? contentLength : undefined)
+
+    await hooks.dispatch(ctx)
+
+    res.statusCode = ctx._statusCode
+    for (const name in ctx._headers) {
+      const value = ctx._headers[name]
+      if (value !== undefined) res.setHeader(name, value)
+    }
+    const body = ctx._body
+    switch (body.kind) {
+      case 'none':
+        res.end()
+        break
+      case 'string':
+        if (!res.hasHeader('content-length')) {
+          res.setHeader('content-length', Buffer.byteLength(body.data))
+        }
+        res.end(body.data)
+        break
+      case 'buffer':
+        if (!res.hasHeader('content-length')) {
+          res.setHeader('content-length', body.data.length)
+        }
+        res.end(body.data)
+        break
+      case 'stream':
+        body.data.pipe(res)
+        break
+    }
+  } finally {
+    hooks.release(ctx)
+  }
+}
+
+function emergencyAbort(stream: ServerHttp2Stream, err: unknown): void {
+  // Last-resort safety net — the dispatch loop should have caught everything.
+  if (!stream.headersSent && !stream.destroyed) {
+    try {
+      stream.respond(
+        { [h2.HTTP2_HEADER_STATUS]: 500, 'content-type': 'application/json; charset=utf-8' },
+      )
+      stream.end(JSON.stringify({ error: 'Internal Server Error', code: 'INTERNAL_ERROR' }))
+    } catch {
+      // fall through to destroy
+    }
+  }
+  if (!stream.destroyed) {
+    try {
+      stream.close(h2.NGHTTP2_INTERNAL_ERROR)
+    } catch {
+      stream.destroy()
+    }
+  }
+  process.emitWarning(`ingenium(h2): dispatch leaked: ${(err as Error).message ?? String(err)}`)
+}
+
+/**
+ * Bind the underlying server and return a {@link ListeningServer} handle.
+ * Same socket-tracking pattern as `NodeAdapter` so `close({ gracefulTimeoutMs })`
+ * can force-kill idle connections.
+ */
+function startServer(
+  server: Http2Server | Http2SecureServer,
+  port: number,
+  host: string,
+): Promise<ListeningServer> {
+  const sockets = new Set<Socket | TLSSocket>()
+  server.on('connection', (socket: Socket) => {
+    sockets.add(socket)
+    socket.on('close', () => sockets.delete(socket))
+  })
+  server.on('secureConnection', (socket: TLSSocket) => {
+    sockets.add(socket)
+    socket.on('close', () => sockets.delete(socket))
+  })
+
+  return new Promise<ListeningServer>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      const addr = server.address()
+      if (!addr || typeof addr === 'string') {
+        reject(new Error('Failed to determine bound address'))
+        return
+      }
+      resolve({
+        port: addr.port,
+        host: addr.address,
+        close: (opts?: CloseOptions): Promise<void> =>
+          new Promise<void>((res, rej) => {
+            let settled = false
+            let timer: NodeJS.Timeout | null = null
+
+            server.close((err) => {
+              if (timer) clearTimeout(timer)
+              if (settled) return
+              settled = true
+              err ? rej(err) : res()
+            })
+
+            const timeoutMs = opts?.gracefulTimeoutMs
+            if (typeof timeoutMs === 'number' && Number.isFinite(timeoutMs)) {
+              timer = setTimeout(() => {
+                for (const socket of sockets) socket.destroy()
+              }, Math.max(0, timeoutMs))
+              if (typeof timer.unref === 'function') timer.unref()
+            }
+          }),
+      })
+    })
+  })
+}
+
+// Re-export types for downstream consumers who need to type adapter options.
+export type { Http2AdapterOptions as Http2Options }