ingenium 0.0.1

package/src/ws/middleware.ts

@@ -0,0 +1,178 @@
+/**
+ * WebSocket registrar — the small piece of state that holds path → handler
+ * mappings and knows how to wire `'upgrade'` on a Node `http.Server`.
+ *
+ * Design: the `ws` package is loaded lazily via dynamic `import('ws')` so
+ * apps that never use WebSockets pay no cost (no module load, no peer-dep
+ * requirement). The first call to `attach()` resolves the import.
+ */
+
+import type { Server as HttpServer, IncomingMessage } from 'node:http'
+import type { Socket } from 'node:net'
+import { IngeniumContext } from '../context/context.ts'
+import type { HttpMethod } from '../router/types.ts'
+import type {
+  WebSocketHandler,
+  WebSocketHandlerOptions,
+  WsRegistrar,
+  WsRoute,
+} from './types.ts'
+
+/**
+ * Attempt to detect whether `ws` is installed. Used by the test suite to
+ * `describe.skipIf` the WS suite when the optional peer dep is missing.
+ */
+export async function peerHasWs(): Promise<boolean> {
+  try {
+    await import('ws')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Build a registrar bound to an app. The registrar is intentionally
+ * decoupled from `IngeniumApp` — the app calls `add()` from `app.ws()`, and
+ * `enableWebSockets()` (or the app's `listen()` integration) calls `attach()`
+ * once the underlying `http.Server` is created.
+ */
+export function createWebSocketRegistrar(): WsRegistrar {
+  const routes: Map<string, WsRoute> = new Map()
+  let attachedServer: HttpServer | null = null
+  // The `ws` `WebSocketServer` instance, lazy-initialized on first upgrade.
+  // We use one server per registered path so per-handler options apply.
+  const wssByPath: Map<string, unknown> = new Map()
+  // We keep a reference to the `ws` module after the first dynamic import.
+  let wsModule: typeof import('ws') | null = null
+
+  // Single shared upgrade listener — installed exactly once.
+  let upgradeListener: ((req: IncomingMessage, socket: Socket, head: Buffer) => void) | null = null
+
+  function add(path: string, handler: WebSocketHandler, options: WebSocketHandlerOptions = {}): void {
+    if (routes.has(path)) {
+      throw new Error(`ingenium.ws: path "${path}" already has a WebSocket handler`)
+    }
+    routes.set(path, { path, handler, options })
+  }
+
+  function attach(httpServer: HttpServer): void {
+    if (attachedServer === httpServer) return // idempotent
+    if (attachedServer !== null) {
+      throw new Error('ingenium.ws: registrar already attached to a different http.Server')
+    }
+    attachedServer = httpServer
+
+    upgradeListener = (req, socket, head) => {
+      // Parse the path from the upgrade request URL. We only look at the
+      // pathname — query strings are exposed via `ctx.rawQuery` for handlers
+      // that care.
+      const url = req.url ?? '/'
+      const qIdx = url.indexOf('?')
+      const path = qIdx >= 0 ? url.slice(0, qIdx) : url
+
+      const route = routes.get(path)
+      if (!route) {
+        // No handler for this path — close the socket cleanly. The
+        // 404-equivalent for WebSockets is just refusing the upgrade.
+        socket.destroy()
+        return
+      }
+
+      // Lazy-load `ws`. On the first upgrade, dynamically import. If `ws`
+      // isn't installed, give a clear actionable error and tear the socket
+      // down — apps that wired `app.ws(...)` without installing the peer
+      // dep should learn about it the moment a client tries to connect.
+      void (async () => {
+        try {
+          if (wsModule === null) wsModule = await import('ws')
+        } catch (err) {
+          process.emitWarning(
+            'ingenium: app.ws() was called but the `ws` package is not installed. ' +
+              'Install it with `npm install ws` (and `@types/ws` for TypeScript).',
+          )
+          socket.destroy()
+          return
+        }
+
+        let wss = wssByPath.get(route.path) as
+          | InstanceType<typeof import('ws').WebSocketServer>
+          | undefined
+        if (!wss) {
+          wss = new wsModule.WebSocketServer({
+            noServer: true,
+            maxPayload: route.options.maxPayload,
+            perMessageDeflate: route.options.perMessageDeflate ?? false,
+          })
+          wssByPath.set(route.path, wss)
+        }
+
+        wss.handleUpgrade(req, socket, head, (ws) => {
+          const ctx = buildMinimalContext(req, path)
+          try {
+            const ret = route.handler(ws, ctx)
+            if (ret && typeof (ret as Promise<unknown>).then === 'function') {
+              ;(ret as Promise<unknown>).catch((err) => {
+                process.emitWarning(
+                  `ingenium.ws: handler for ${path} rejected: ${(err as Error)?.message ?? String(err)}`,
+                )
+                try { ws.close(1011, 'handler error') } catch { /* socket may already be dead */ }
+              })
+            }
+          } catch (err) {
+            process.emitWarning(
+              `ingenium.ws: handler for ${path} threw: ${(err as Error)?.message ?? String(err)}`,
+            )
+            try { ws.close(1011, 'handler error') } catch { /* ignore */ }
+          }
+        })
+      })()
+    }
+
+    httpServer.on('upgrade', upgradeListener)
+  }
+
+  async function close(): Promise<void> {
+    // Detach the upgrade listener so a re-listen on the same server doesn't
+    // double-up handlers.
+    if (attachedServer && upgradeListener) {
+      attachedServer.off('upgrade', upgradeListener)
+    }
+    upgradeListener = null
+    attachedServer = null
+
+    // Close every per-path WebSocketServer. `ws.WebSocketServer.close(cb)`
+    // fires once all clients have disconnected; we await each in parallel.
+    const closes: Promise<void>[] = []
+    for (const wss of wssByPath.values()) {
+      const server = wss as InstanceType<typeof import('ws').WebSocketServer>
+      // Forcibly terminate any still-open clients so close() resolves
+      // promptly during test teardown.
+      for (const client of server.clients) {
+        try { client.terminate() } catch { /* ignore */ }
+      }
+      closes.push(new Promise<void>((resolve) => server.close(() => resolve())))
+    }
+    wssByPath.clear()
+    await Promise.all(closes)
+  }
+
+  return { add, attach, close }
+}
+
+/**
+ * Build a minimal `IngeniumContext` for a WebSocket handler. We don't run the
+ * full request pipeline (no middleware, no decorators) because the upgrade
+ * has already taken place — the handler owns the socket from here.
+ */
+function buildMinimalContext(req: IncomingMessage, path: string): IngeniumContext {
+  const ctx = new IngeniumContext()
+  ctx.method = (req.method ?? 'GET') as HttpMethod
+  ctx.url = req.url ?? '/'
+  ctx.path = path
+  const url = ctx.url
+  const qIdx = url.indexOf('?')
+  ctx.rawQuery = qIdx >= 0 ? url.slice(qIdx + 1) : ''
+  ctx.headers = req.headers
+  return ctx
+}

package/src/ws/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Public types for the optional WebSocket adapter. The `ws` package is an
+ * OPTIONAL peer dependency — these types are erased at runtime, so this file
+ * compiles even when `ws` is not installed.
+ */
+
+import type { IncomingMessage } from 'node:http'
+// Type-only — TypeScript erases this; safe even without `ws` installed.
+import type { WebSocket as WsWebSocket } from 'ws'
+import type { IngeniumContext } from '../context/context.ts'
+
+/** Re-export the underlying `ws` `WebSocket` type for convenience. */
+export type WebSocket = WsWebSocket
+
+/**
+ * Handler invoked when a client successfully upgrades to a WebSocket.
+ *
+ * `socket` is the `ws.WebSocket` instance. `ctx` is a minimal `IngeniumContext`
+ * populated from the upgrade `IncomingMessage` — the body / response writers
+ * are not meaningful for WS handlers (the upgrade has already happened).
+ */
+export type WebSocketHandler = (socket: WsWebSocket, ctx: IngeniumContext) => void | Promise<void>
+
+/** Per-handler options forwarded to `WebSocketServer({ noServer: true, ... })`. */
+export interface WebSocketHandlerOptions {
+  /** Max payload size (bytes) for incoming frames. */
+  maxPayload?: number
+  /** Enable permessage-deflate. Defaults to false (matches `ws` default). */
+  perMessageDeflate?: boolean
+}
+
+/** Internal: a registered handler entry. */
+export interface WsRoute {
+  path: string
+  handler: WebSocketHandler
+  options: WebSocketHandlerOptions
+}
+
+/** Bag passed to integrators (advanced). */
+export interface WsIntegrator {
+  (httpServer: import('node:http').Server): void
+}
+
+/** Shape of the per-app registrar exposed to `enableWebSockets`. */
+export interface WsRegistrar {
+  add(path: string, handler: WebSocketHandler, options?: WebSocketHandlerOptions): void
+  attach(httpServer: import('node:http').Server): void
+  close(): Promise<void>
+}
+
+/** Re-export so consumers can build minimal contexts in tests. */
+export type { IncomingMessage }

package/src/ws/ws-node-adapter.ts

@@ -0,0 +1,162 @@
+/**
+ * WebSocket-aware variant of `NodeAdapter`. Mirrors the behavior of
+ * `transport/node.ts` (request handling, socket tracking, graceful close)
+ * but exposes the underlying `http.Server` via an `onServerReady` callback
+ * so the WS registrar can `.on('upgrade', …)` it.
+ *
+ * We did not modify the core `NodeAdapter` because the core has no awareness
+ * of WebSockets; this adapter is opt-in via `enableWebSockets()`.
+ */
+
+import { createServer, type IncomingMessage, type Server as HttpServer, type ServerResponse } from 'node:http'
+import type { Socket } from 'node:net'
+import { Buffer } from 'node:buffer'
+import type { IngeniumContext } from '../context/context.ts'
+import type { HttpMethod } from '../router/types.ts'
+import type {
+  CloseOptions,
+  ListeningServer,
+  Transport,
+  TransportHooks,
+} from '../transport/types.ts'
+
+export type OnServerReady = (httpServer: HttpServer) => void
+
+export class WsNodeAdapter implements Transport {
+  private hooks: TransportHooks | null = null
+  private readonly onServerReady: OnServerReady
+
+  constructor(onServerReady: OnServerReady) {
+    this.onServerReady = onServerReady
+  }
+
+  attach(hooks: TransportHooks): void {
+    this.hooks = hooks
+  }
+
+  async listen(port: number, host = '127.0.0.1'): Promise<ListeningServer> {
+    if (!this.hooks) throw new Error('WsNodeAdapter.listen() called before attach()')
+    const hooks = this.hooks
+
+    const server = createServer((req, res) => {
+      handleRequest(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: dispatch leaked: ${(err as Error).message ?? String(err)}`)
+      })
+    })
+
+    // Hand the http.Server to the WS registrar BEFORE listen() resolves —
+    // this guarantees upgrade listeners are wired before any client can
+    // connect.
+    this.onServerReady(server)
+
+    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(() => {
+                  for (const socket of sockets) socket.destroy()
+                }, Math.max(0, timeoutMs))
+                if (typeof timer.unref === 'function') timer.unref()
+              }
+            }),
+        })
+      })
+    })
+  }
+}
+
+async function handleRequest(req: IncomingMessage, res: ServerResponse, hooks: TransportHooks): Promise<void> {
+  const ctx = hooks.acquire()
+  try {
+    populateContext(ctx, req)
+    await hooks.dispatch(ctx)
+    writeResponse(ctx, res)
+  } finally {
+    hooks.release(ctx)
+  }
+}
+
+function populateContext(ctx: IngeniumContext, req: IncomingMessage): void {
+  ctx.method = (req.method ?? 'GET') as HttpMethod
+  ctx.url = req.url ?? '/'
+  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
+
+  const cl = req.headers['content-length']
+  const contentLength = cl ? Number(cl) : undefined
+  const ct = req.headers['content-type']
+  ctx.body._attach(req, ct, Number.isFinite(contentLength) ? contentLength : undefined)
+}
+
+function writeResponse(ctx: IngeniumContext, res: ServerResponse): void {
+  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
+  }
+}