SocketServer
HTTP-upgrade WebSocket server on top of `ws`. Builds and listens on its own HTTP server by default; if you pass a Node `server`, it attaches upgrade handling and leaves `.listen()` to you unless `listen: true` is explicit.
The simple mental model
SocketServer is a switchboard for persistent conversations. It accepts a WebSocket upgrade, finds the route for that path, and lets that route handle the connection.
When should I use it?
Use defineApp({ sockets: [ChatRoute] }) for normal startup. Use SocketServer directly to attach routed upgrades to a separately owned Node HTTP server.
Follow the example
This pattern explains the named API. Application classes, credentials, and assets may need to be supplied; use a complete recipe for a runnable starting point.
import { HttpServer, SocketServer } from 'redweb'
import { ChatRoute } from './ChatRoute.js'
// Advanced: attach to a listener whose lifecycle your application owns.
const http = new HttpServer({ listen: false, publicPaths: [] })
const sockets = new SocketServer({ server: http.server, routes: [ChatRoute] })
http.server.listen(3030)
// At application shutdown, detach sockets before closing their shared listener.
async function shutdown() {
await sockets.shutdown()
await http.shutdown()
}- 1
The HTTP server is built or reused according to the options.
- 2
Upgrade requests are matched to routes instead of being sent to every handler.
- 3
Each route owns its clients, handlers, services, limits, and cleanup lifecycle.
Choices you can make
- port: number (default 3000)
- listen: boolean (default true for owned servers); supplied servers do not listen unless explicitly true
- server: existing http.Server to attach to without double-listening (optional)
- routes: array of SocketRoute subclasses (defaults to a single DefaultRoute at "/")
Methods and members
constructor(options)
Creates or reuses an HTTP server, instantiates supplied routes or a DefaultRoute, attaches upgrade handling, and starts listening only when Redweb owns the server or listen is explicitly true.
addRoute(RouteClass)
Instantiate and register another `SocketRoute` at runtime.
handleUpgrade(req, socket, head)
Internal: normalises the request path, picks a matching route (or "/"), and forwards the upgrade to that route's server.
shutdown()
Closes all registered routes and the underlying HTTP server.