WebSocket · In depth

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.

Explain it like I’m five

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 it fits

When should I use it?

Choose it for ws:// endpoints or when a reverse proxy already handles TLS and you need one or more independently configured socket routes.

A practical API pattern

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.

Read this article as Markdown

JavaScript

const http = require('http')
const { HttpServer, METHODS, SocketServer } = require('redweb')

const httpServer = new HttpServer({
  listen: false,
  publicPaths: ['./public'],
  services: [
    { serviceName: '/health', method: METHODS.GET, function: (req, res) => res.json({ ok: true }) },
  ],
})

const server = http.createServer(httpServer.app)

new SocketServer({
  server,
  routes: [ChatRoute],
})

server.listen(3030)

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.

Configuration

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 "/")

Surface area

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.