WebSocket

WebSocket support in Ingenium is opt-in via the ws peer dependency. Once enabled, you register per-path handlers; unknown paths get the upgrade socket destroyed cleanly.

Install

npm install ws @types/ws

Usage

import { ingenium, enableWebSockets } from 'ingenium'

const app = ingenium()
enableWebSockets(app)

app.ws('/echo', (sock) => {
  sock.on('message', (msg) => sock.send(msg))
})

// Or hand the underlying http.Server to your own integrator:
app.upgradeWith((httpServer) => {
  // wire up `ws`, socket.io, etc.
})

await app.listen(3000)

How it works

• Uses WebSocketServer({ noServer: true }) under the hood.
• Hooks the upgrade event on the underlying http.Server.
• Per-path handlers are registered up front. The path the client connected on is matched against the registered handlers; unknown paths get the socket destroyed cleanly so misrouted clients don't sit idle.

The upgradeWith escape hatch

If you need full control - socket.io, custom subprotocols, or a non-ws library - call app.upgradeWith(httpServer => ...). Ingenium hands you the underlying http.Server so you can attach whatever integrator you want and bypass the per-path dispatcher entirely.

Where to next?

• Server-Sent Events - the one-way alternative.
• Transports - the transport contract.
• Graceful shutdown - closing in-flight sockets cleanly.
• Bun - Bun-compatible WebSocket considerations.