ingenium 0.0.1

package/src/transport/node.ts

@@ -0,0 +1,261 @@
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
+import type { Socket } from 'node:net'
+import type { IngeniumContext } from '../context/context.ts'
+import type { HttpMethod } from '../router/types.ts'
+import { createByteLimit } from '../body/limit.ts'
+import type { CloseOptions, ListeningServer, Transport, TransportHooks } from './types.ts'
+
+/**
+ * Node.js `node:http` transport. Owns a single `http.Server`; on each
+ * request, populates a pooled `IngeniumContext` directly from the
+ * `IncomingMessage` (no WinterCG translation), awaits dispatch, then writes
+ * the context's response state to the `ServerResponse`.
+ */
+export class NodeAdapter implements Transport {
+  private hooks: TransportHooks | null = null
+
+  attach(hooks: TransportHooks): void {
+    this.hooks = hooks
+  }
+
+  async listen(port: number, host = '127.0.0.1'): Promise<ListeningServer> {
+    if (!this.hooks) throw new Error('NodeAdapter.listen() called before attach()')
+    const hooks = this.hooks
+
+    const server = createServer((req, res) => {
+      handleRequest(req, res, hooks).catch((err) => {
+        // Last-resort safety net — the dispatch loop should have caught everything.
+        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: dispatch leaked: ${(err as Error).message ?? String(err)}`)
+      })
+    })
+
+    // Track every open socket so close() can drain (and, if asked, force-kill)
+    // idle keep-alive connections that `server.close()` alone would leave open.
+    const sockets = new Set<Socket>()
+    server.on('connection', (socket) => {
+      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) =>
+            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(() => {
+                  // Force-close any sockets still hanging around (idle
+                  // keep-alives or slow handlers). server.close()'s callback
+                  // will fire once they're destroyed.
+                  for (const socket of sockets) socket.destroy()
+                }, Math.max(0, timeoutMs))
+                // Don't keep the event loop alive just for the force-close timer.
+                if (typeof timer.unref === 'function') timer.unref()
+              }
+            }),
+        })
+      })
+    })
+  }
+}
+
+async function handleRequest(req: IncomingMessage, res: ServerResponse, hooks: TransportHooks): Promise<void> {
+  // Normalize once: TransportHooks types maxRequestBytes as optional for
+  // backward-compat; framework dispatch always sets it. Older fixtures may
+  // not — treat undefined as "no cap" (Infinity).
+  const maxBytes = hooks.maxRequestBytes ?? Number.POSITIVE_INFINITY
+
+  // Content-Length pre-check: if the client declares a body larger than the
+  // ceiling, reject IMMEDIATELY without acquiring a context or buffering
+  // anything. Chunked requests (no Content-Length) and Content-Length: 0
+  // fall through to the byte-limit Transform below, which catches
+  // mid-stream overruns.
+  if (rejectIfContentLengthTooBig(req, res, maxBytes)) return
+
+  const ctx = hooks.acquire()
+  try {
+    populateContext(ctx, req, maxBytes)
+    await hooks.dispatch(ctx)
+    writeResponse(ctx, res)
+  } finally {
+    hooks.release(ctx)
+  }
+}
+
+/**
+ * Returns `true` (and writes a 413 response) if the request advertises a
+ * Content-Length greater than `maxRequestBytes`. Returns `false` for missing,
+ * invalid, or in-range Content-Length values — those cases are handled by
+ * the byte-limit Transform downstream.
+ */
+function rejectIfContentLengthTooBig(
+  req: IncomingMessage,
+  res: ServerResponse,
+  maxRequestBytes: number,
+): boolean {
+  if (!Number.isFinite(maxRequestBytes)) return false
+  const raw = req.headers['content-length']
+  if (typeof raw !== 'string' || raw.length === 0) return false
+  const n = Number(raw)
+  if (!Number.isFinite(n)) return false
+  if (n <= maxRequestBytes) return false
+
+  res.statusCode = 413
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('connection', 'close')
+  res.end(
+    JSON.stringify({
+      error: `Request body exceeded ${maxRequestBytes} bytes`,
+      code: 'PAYLOAD_TOO_LARGE',
+    }),
+  )
+  // Hint the kernel to drop any pending body bytes; we never read them.
+  req.socket?.destroy()
+  return true
+}
+
+function populateContext(ctx: IngeniumContext, req: IncomingMessage, maxRequestBytes: number): void {
+  ctx.method = (req.method ?? 'GET') as HttpMethod
+  ctx.url = req.url ?? '/'
+  // Split path / query without allocating a URL object.
+  const url = ctx.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
+  ctx.remoteAddress = req.socket?.remoteAddress ?? '127.0.0.1'
+  // Detect TLS via the socket's `encrypted` flag (set by tls.TLSSocket).
+  ctx.baseProtocol = (req.socket as { encrypted?: boolean })?.encrypted ? 'https' : 'http'
+
+  // Wire body lazily — the source stream is only consumed if a body method is called.
+  const cl = req.headers['content-length']
+  const contentLength = cl ? Number(cl) : undefined
+  const ct = req.headers['content-type']
+  // Wrap the raw IncomingMessage in a transport-level byte-limit so the cap
+  // applies to EVERY consumer, including `ctx.body.stream()`. We skip the
+  // wrap in three provably-safe cases:
+  //
+  //   1. The request is structurally body-less (GET/HEAD/OPTIONS or
+  //      Content-Length: 0). No body to cap.
+  //   2. The cap is disabled (Number.POSITIVE_INFINITY).
+  //   3. Content-Length is declared AND ≤ cap. The pre-check
+  //      (`rejectIfContentLengthTooBig`) already verified this; node:http
+  //      itself enforces the declared length and stops reading at the
+  //      byte count, so the body cannot exceed the cap. The Transform
+  //      would be redundant defense in this path.
+  //
+  // Chunked encoding (no Content-Length) keeps the Transform — that's
+  // where the cap actually matters, because the client controls the
+  // stream length without any prior declaration.
+  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(req, ct, Number.isFinite(contentLength) ? contentLength : undefined)
+    return
+  }
+
+  // Cap unknown-length (chunked) bodies with a byte-limit Transform. `pipe()`
+  // does NOT forward `'error'` events, so when the chunked path in
+  // `IngeniumBody.buffer` re-pipes this Transform into a SECOND limiter and only
+  // listens on the downstream pipe, the cap error here would (a) be an
+  // unhandled-error crash and (b) never reach that downstream — so the
+  // consumer's promise would hang. Attach a guard `'error'` listener and
+  // forward the error to every stream this Transform was piped into. We leave
+  // `req`/its socket alone so the response (413) can still flush.
+  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)
+    }
+    // Discard the rest of the inbound body so the socket can be reused/closed.
+    req.unpipe(limited)
+    req.on('error', () => {})
+    req.resume()
+  })
+  req.pipe(limited)
+  ctx.body._attach(limited, ct, Number.isFinite(contentLength) ? contentLength : undefined)
+}
+
+function writeResponse(ctx: IngeniumContext, res: ServerResponse): void {
+  const body = ctx._body
+  const headers = ctx._headers
+
+  // Compute content-length where we know it. Mutating ctx._headers is safe
+  // because the context is being released to the pool right after this call.
+  switch (body.kind) {
+    case 'string':
+      if (headers['content-length'] === undefined) {
+        headers['content-length'] = String(Buffer.byteLength(body.data))
+      }
+      break
+    case 'buffer':
+      if (headers['content-length'] === undefined) {
+        headers['content-length'] = String(body.data.length)
+      }
+      break
+    case 'none':
+    case 'stream':
+      break
+  }
+
+  // Single writeHead call instead of `statusCode = ...; setHeader × N`.
+  // node:http has a fast path that flushes status line + headers in one
+  // serialization pass — measurably faster than the per-header setHeader
+  // sequence on hot endpoints.
+  if (body.kind === 'stream') {
+    res.writeHead(ctx._statusCode, headers)
+    body.data.pipe(res)
+    return
+  }
+  res.writeHead(ctx._statusCode, headers)
+  if (body.kind === 'none') {
+    res.end()
+  } else {
+    res.end(body.data)
+  }
+}

package/src/transport/shutdown.ts

@@ -0,0 +1,86 @@
+/**
+ * Graceful shutdown helper. Wires POSIX signal handlers to drain a
+ * {@link ListeningServer}, run a user cleanup hook, then exit.
+ *
+ * Most production deployments (Kubernetes, systemd, PM2, ECS, Fly, …) send
+ * SIGTERM when they want a process to stop. By default Node simply dies on
+ * SIGTERM, which kills in-flight requests and leaves keep-alive sockets
+ * dangling. Calling {@link gracefulShutdown} after `app.listen()` opts the
+ * process into a clean drain instead.
+ */
+
+import type { ListeningServer } from './types.ts'
+
+/** Options for {@link gracefulShutdown}. */
+export interface ShutdownOptions {
+  /**
+   * Maximum time (ms) to wait for sockets to drain before they are forcibly
+   * destroyed. Defaults to `10_000` (10s) — matches Kubernetes' default
+   * `terminationGracePeriodSeconds` headroom.
+   */
+  gracefulTimeoutMs?: number
+
+  /**
+   * Signals to listen for. Defaults to `['SIGTERM', 'SIGINT']`.
+   */
+  signals?: NodeJS.Signals[]
+
+  /**
+   * User cleanup hook — runs AFTER the server stops accepting new
+   * connections but BEFORE the process exits. Use for closing DB pools,
+   * flushing logs, etc. Awaited; throwing exits with code 1.
+   */
+  onShutdown?: () => void | Promise<void>
+
+  /** Logger used to announce shutdown lifecycle events. Defaults to `console.log`. */
+  logger?: (msg: string) => void
+}
+
+/**
+ * Wire signal handlers that gracefully shut down `server` on SIGTERM/SIGINT
+ * (or whichever signals you pass). Returns an unsubscribe function that
+ * removes the listeners — mostly useful for tests.
+ *
+ * @example
+ *   const server = await app.listen(3000)
+ *   gracefulShutdown(server, { onShutdown: async () => db.close() })
+ */
+export function gracefulShutdown(
+  server: ListeningServer,
+  opts: ShutdownOptions = {},
+): () => void {
+  const gracefulTimeoutMs = opts.gracefulTimeoutMs ?? 10_000
+  const signals: NodeJS.Signals[] = opts.signals ?? ['SIGTERM', 'SIGINT']
+  const log = opts.logger ?? ((msg: string) => console.log(msg))
+
+  let shuttingDown = false
+
+  const handler = (signal: NodeJS.Signals): void => {
+    if (shuttingDown) {
+      // Second signal during an in-progress drain → bail immediately.
+      log(`ingenium: received ${signal} during shutdown — forcing exit`)
+      process.exit(1)
+      return
+    }
+    shuttingDown = true
+    log(`ingenium: received ${signal}, shutting down (timeout ${gracefulTimeoutMs}ms)`)
+
+    void (async () => {
+      try {
+        if (opts.onShutdown) await opts.onShutdown()
+        await server.close({ gracefulTimeoutMs })
+        log('ingenium: shutdown complete')
+        process.exit(0)
+      } catch (err) {
+        log(`ingenium: shutdown failed: ${(err as Error)?.message ?? String(err)}`)
+        process.exit(1)
+      }
+    })()
+  }
+
+  for (const signal of signals) process.on(signal, handler)
+
+  return (): void => {
+    for (const signal of signals) process.off(signal, handler)
+  }
+}

package/src/transport/types.ts

@@ -0,0 +1,72 @@
+import type { IngeniumContext } from '../context/context.ts'
+
+/** A function the framework hands to the transport — call it per request. */
+export type TransportDispatch = (ctx: IngeniumContext) => Promise<void>
+
+/** A function the transport calls to acquire a context from the pool. */
+export type TransportAcquire = () => IngeniumContext
+
+/** A function the transport calls to release a context back to the pool. */
+export type TransportRelease = (ctx: IngeniumContext) => void
+
+/**
+ * The hooks a transport uses to interact with the framework. The transport
+ * owns the request/response objects from its underlying server (node:http,
+ * Bun.serve, etc.), populates a `IngeniumContext` from each request, awaits the
+ * `dispatch` callback, then writes the context's response state to the wire.
+ */
+export interface TransportHooks {
+  acquire: TransportAcquire
+  release: TransportRelease
+  dispatch: TransportDispatch
+  /**
+   * Hard ceiling (bytes) on the total request body. Adapters SHOULD wrap the
+   * inbound body stream in `createByteLimit(maxRequestBytes)` before handing
+   * it to `ctx.body._attach(...)`, AND reject with a 413 immediately when
+   * the request advertises a `Content-Length` greater than this value (no
+   * need to read the body). `Number.POSITIVE_INFINITY` disables the cap.
+   *
+   * Optional for backward compatibility with adapters / test fixtures that
+   * predate this hook. The framework's `app.listen()` always populates the
+   * field (default 2 MiB); consumers that read it should treat `undefined`
+   * as "no cap" (`Number.POSITIVE_INFINITY`).
+   */
+  maxRequestBytes?: number
+}
+
+/** Options accepted by {@link ListeningServer.close}. */
+export interface CloseOptions {
+  /**
+   * Maximum time (ms) to wait for keep-alive sockets to drain naturally
+   * before they are forcibly destroyed. When omitted (or undefined), no
+   * force-close occurs and `close()` waits indefinitely for sockets to
+   * finish — this matches the historical Node `server.close()` behavior.
+   */
+  gracefulTimeoutMs?: number
+}
+
+/** A transport-agnostic listening server handle. */
+export interface ListeningServer {
+  /** Bound port (resolved if `port: 0` was passed). */
+  port: number
+  /** The bound host. */
+  host: string
+  /**
+   * Stop accepting new connections; resolves when in-flight requests
+   * finish. If `gracefulTimeoutMs` is provided, idle keep-alive sockets
+   * still open after that many milliseconds are forcibly destroyed.
+   */
+  close(opts?: CloseOptions): Promise<void>
+}
+
+/**
+ * A transport binds the Ingenium dispatch loop to a concrete server
+ * runtime (Node's `node:http`, Bun.serve, etc).
+ */
+export interface Transport {
+  /** Wire up the transport with framework-side hooks. Called once by `app.listen()`. */
+  attach(hooks: TransportHooks): void
+
+  /** Bind to a port and start accepting requests. */
+  listen(port: number, host?: string): Promise<ListeningServer>
+}

package/src/util/safe-json.ts

@@ -0,0 +1,66 @@
+/**
+ * `safeJsonStringify(value, opts?)` — a lenient `JSON.stringify` that never
+ * throws on circular references or `BigInt` values.
+ *
+ * Behavior:
+ * - Circular references → replaced with the string `'[Circular]'`.
+ * - `BigInt` values     → serialized as a JSON string (e.g. `1n` → `"1"`).
+ *   This preserves precision and is reversible by the caller; if you need a
+ *   different convention, pass your own `replacer`.
+ * - Symbol values       → omitted (matches `JSON.stringify` default).
+ * - Functions           → omitted (matches `JSON.stringify` default).
+ *
+ * Intended for opt-in use by callers who want lenient behavior — the
+ * default `ctx.json()` path remains strict and surfaces a
+ * `IngeniumUnserializableError` so the bug is visible.
+ *
+ * @example
+ *   import { safeJsonStringify } from 'ingenium'
+ *   ctx.send(safeJsonStringify(value), 200)
+ *   ctx.set('content-type', 'application/json; charset=utf-8')
+ */
+
+/** Options for `safeJsonStringify`. */
+export interface SafeJsonStringifyOptions {
+  /**
+   * Pass-through to `JSON.stringify`'s third argument — number of spaces or
+   * indent string for pretty-printing. Defaults to no indentation.
+   */
+  space?: string | number
+  /**
+   * Optional user replacer applied AFTER the cycle/BigInt sanitization. If
+   * provided, behaves like `JSON.stringify`'s second argument.
+   */
+  replacer?: (key: string, value: unknown) => unknown
+}
+
+/**
+ * Stringify `value` without throwing on circular structures or `BigInt`s.
+ * See module doc for the exact substitution rules.
+ */
+export function safeJsonStringify(
+  value: unknown,
+  opts: SafeJsonStringifyOptions = {},
+): string {
+  const seen = new WeakSet<object>()
+  const userReplacer = opts.replacer
+
+  const replacer = (key: string, val: unknown): unknown => {
+    let v: unknown = val
+    if (typeof v === 'bigint') {
+      // Preserve precision by emitting as a JSON string.
+      v = v.toString()
+    } else if (typeof v === 'object' && v !== null) {
+      if (seen.has(v as object)) return '[Circular]'
+      seen.add(v as object)
+    }
+    if (userReplacer) v = userReplacer(key, v)
+    return v
+  }
+
+  // `JSON.stringify` returns `undefined` for top-level `undefined`,
+  // functions, and symbols — normalize to the literal string 'undefined'
+  // so the return type contract (`string`) holds.
+  const out = JSON.stringify(value, replacer, opts.space)
+  return out === undefined ? 'undefined' : out
+}

package/src/ws/index.ts

@@ -0,0 +1,164 @@
+/**
+ * WebSocket adapter for Ingenium (optional `ws` peer dependency).
+ *
+ * # Usage
+ * ```ts
+ * import { ingenium } from 'ingenium'
+ * import { enableWebSockets } from 'ingenium/ws'
+ *
+ * const app = ingenium()
+ * enableWebSockets(app)
+ * app.ws('/echo', (sock) => {
+ *   sock.on('message', (m) => sock.send(m))
+ * })
+ * await app.listen(3000)
+ * ```
+ *
+ * # Why a monkey-patch?
+ * `enableWebSockets(app)` augments the app instance with `app.ws()` and
+ * wraps `app.listen()` so the registrar gets attached to the underlying
+ * `http.Server` once it's bound. We chose this over extending `IngeniumApp` to
+ * avoid pulling `./ws/middleware.ts` into the core import graph (which would
+ * create a soft dep on `ws` types from every `app.ts` consumer). This is a
+ * known pattern in WS-extending frameworks (e.g. `express-ws`).
+ *
+ * The trade-off: TypeScript can't statically see `app.ws` unless the
+ * augmentation below is loaded. Importing this module both registers the
+ * runtime patch AND adds the type augmentation to the global `IngeniumApp`.
+ */
+
+import type { IngeniumApp } from '../app.ts'
+import type { ListeningServer, Transport } from '../transport/types.ts'
+import { createWebSocketRegistrar, peerHasWs } from './middleware.ts'
+import { WsNodeAdapter } from './ws-node-adapter.ts'
+import type {
+  WebSocketHandler,
+  WebSocketHandlerOptions,
+  WsIntegrator,
+  WsRegistrar,
+} from './types.ts'
+
+export type {
+  WebSocketHandler,
+  WebSocketHandlerOptions,
+  WsIntegrator,
+  WsRegistrar,
+  WebSocket,
+} from './types.ts'
+export { createWebSocketRegistrar, peerHasWs } from './middleware.ts'
+
+// ───── Type augmentation ────────────────────────────────────────────────────
+// Declared on IngeniumApp so `app.ws(...)` and `app.upgradeWith(...)` typecheck
+// for any consumer that imports from 'ingenium/ws'.
+declare module '../app.ts' {
+  interface IngeniumApp {
+    ws(path: string, handler: WebSocketHandler, options?: WebSocketHandlerOptions): IngeniumApp
+    upgradeWith(integrator: WsIntegrator): IngeniumApp
+  }
+}
+
+/** Per-app state attached by `enableWebSockets`. Internal. */
+interface WsAppState {
+  registrar: WsRegistrar
+  integrators: WsIntegrator[]
+  enabled: true
+}
+
+const APP_STATE: WeakMap<IngeniumApp, WsAppState> = new WeakMap()
+
+/** Options for `enableWebSockets`. Reserved for future use. */
+export interface EnableWebSocketsOptions {
+  /**
+   * When `true`, eagerly probes for the `ws` peer dependency at install
+   * time and prints a warning if it is missing. Default: `false` (we wait
+   * until the first upgrade attempt).
+   */
+  warnOnMissingPeer?: boolean
+}
+
+/**
+ * Augment a `IngeniumApp` with WebSocket support. Idempotent — calling more than
+ * once on the same app is a no-op.
+ */
+export function enableWebSockets(app: IngeniumApp, opts: EnableWebSocketsOptions = {}): void {
+  if (APP_STATE.has(app)) return
+
+  const registrar = createWebSocketRegistrar()
+  const state: WsAppState = { registrar, integrators: [], enabled: true }
+  APP_STATE.set(app, state)
+
+  if (opts.warnOnMissingPeer) {
+    void peerHasWs().then((ok) => {
+      if (!ok) {
+        process.emitWarning(
+          'ingenium: enableWebSockets() called but `ws` is not installed. ' +
+            'Install it with `npm install ws`.',
+        )
+      }
+    })
+  }
+
+  // Attach the new methods. We assign with a cast because the augmentation
+  // above only exists at the type layer.
+  ;(app as unknown as { ws: IngeniumApp['ws'] }).ws = function (
+    path: string,
+    handler: WebSocketHandler,
+    options?: WebSocketHandlerOptions,
+  ): IngeniumApp {
+    state.registrar.add(path, handler, options)
+    return app
+  }
+
+  ;(app as unknown as { upgradeWith: IngeniumApp['upgradeWith'] }).upgradeWith = function (
+    integrator: WsIntegrator,
+  ): IngeniumApp {
+    state.integrators.push(integrator)
+    return app
+  }
+
+  // Swap in a WebSocket-aware Node transport. We do this via bracket-access
+  // because `IngeniumApp#transport` is `private` (TypeScript-only — `private`
+  // doesn't actually hide the field at runtime). If the user injected a
+  // custom transport via `IngeniumAppOptions.transport`, we leave it alone and
+  // log a warning — they're responsible for calling `registrar.attach()`
+  // themselves via `app.upgradeWith(...)`.
+  const appAny = app as unknown as { transport: Transport }
+  const existing = appAny.transport
+  const isDefault = existing.constructor?.name === 'NodeAdapter'
+
+  if (isDefault) {
+    appAny.transport = new WsNodeAdapter((httpServer) => {
+      state.registrar.attach(httpServer)
+      for (const integrator of state.integrators) integrator(httpServer)
+    })
+  } else {
+    process.emitWarning(
+      'ingenium.ws: a custom Transport is in use — WebSockets will only be wired ' +
+        'if you call `app.upgradeWith((httpServer) => registrar.attach(httpServer))` from your transport.',
+    )
+  }
+
+  // Wrap close() of the eventual ListeningServer so the registrar tears
+  // down its WebSocketServers first — otherwise `server.close()` hangs
+  // forever waiting on the open WS sockets.
+  const originalListen = app.listen.bind(app)
+  ;(app as unknown as { listen: IngeniumApp['listen'] }).listen = async function (
+    port: number,
+    host?: string,
+  ): Promise<ListeningServer> {
+    const server = await originalListen(port, host)
+    const originalClose = server.close.bind(server)
+    return {
+      port: server.port,
+      host: server.host,
+      close: async (closeOpts) => {
+        await state.registrar.close()
+        await originalClose(closeOpts)
+      },
+    }
+  }
+}
+
+// Re-export the WS-aware Node transport for advanced users who want to
+// construct it manually (e.g. when wiring a custom Transport stack).
+export { WsNodeAdapter } from './ws-node-adapter.ts'