attachNodeWebSocketServer

attachNodeWebSocketServer(options) listens for a Node HTTP server's upgrade event and handles upgrades to /_meeko/socket/<canal> through the ws package. Before accepting, the hub checks the path, Origin, session and channel authorization; afterwards, the adapter delivers each text message to the hub, pings peers and closes unresponsive ones.

serveNode calls it automatically when the application declares channels. Use it in a host with its own http.createServer, alongside toNodeListener.

Usage#

import { createServer } from "node:http";
import { attachNodeWebSocketServer, toNodeListener } from "@meekojs/meeko/node";

const publicOrigin = "https://example.com";
const server = createServer(toNodeListener((request) => app.fetch(request), { publicOrigin }));
const sockets = app.socket
  ? attachNodeWebSocketServer({ server, hub: app.socket.hub, publicOrigin, pathnamePrefix: app.socket.pathnamePrefix })
  : undefined;
server.listen(3000);

Type#

function attachNodeWebSocketServer(options: NodeWebSocketOptions): NodeWebSocketServer

interface NodeWebSocketOptions extends Omit<
  NodeSocketUpgradeOptions,
  "upgrade" | "reject" | "maxPendingBytes"
> {
  server: HttpServer;
  maxMessageBytes?: number;
  heartbeatMs?: number;
}

interface NodeWebSocketServer {
	close(): Promise<void>
}

Parameters#

attachNodeWebSocketServer(options):

Return value#

A NodeWebSocketServer with close(): removes the upgrade listener, terminates all peers and closes the ws server. The caller retains ownership of the HTTP server.

Each upgrade ends as follows:

Examples#

Graceful shutdown of a custom host#

process.once("SIGTERM", async () => {
  await sockets?.close();                                   // 1. Socket
  await new Promise<void>((done) => server.close(() => done())); // 2. HTTP
  await app.close();                                        // 3. application and sessions
});

A smaller limit for a chat#

attachNodeWebSocketServer({ server, hub: app.socket!.hub, publicOrigin, pathnamePrefix: app.socket!.pathnamePrefix, maxMessageBytes: 4 * 1024, heartbeatMs: 15_000 });

A larger frame closes the peer with 1009. Keep this limit equal to or above socket.maxMessageBytes in server/runtime.ts, or messages valid for the hub will be cut off earlier.

A proxy in front#

location /_meeko/socket/ {
  proxy_pass http://127.0.0.1:4173;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header Host $host;
  proxy_read_timeout 120s;   # greater than heartbeatMs
}

Common mistakes#

A limit that is not a positive integer#

attachNodeWebSocketServer({ server, hub, publicOrigin, maxMessageBytes: 0 });

RangeError: Invalid socket message limit; with heartbeatMs, Invalid socket heartbeat interval.

attachNodeWebSocketServer({ server, hub, publicOrigin, maxMessageBytes: 16 * 1024 });

A ws:// origin#

attachNodeWebSocketServer({ server, hub, publicOrigin: "wss://example.com" });

TypeError: Socket publicOrigin must use HTTP or HTTPS: the browser sends the page's origin as Origin, https://example.com.

attachNodeWebSocketServer({ server, hub, publicOrigin: "https://example.com" });

A prefix with a trailing /#

attachNodeWebSocketServer({ server, hub, publicOrigin, pathnamePrefix: "/ws/" });

TypeError: Invalid socket pathname prefix: the prefix starts with / and does not end with /. Pass the application's prefix, app.socket.pathnamePrefix, to match the URL used by generated clients.

attachNodeWebSocketServer({ server, hub: app.socket!.hub, publicOrigin, pathnamePrefix: app.socket!.pathnamePrefix });

Notes#

• ws. It is a dependency of @meekojs/meeko and loads when you call the function, not when you import the adapter.
• Messages. JSON text only: a binary message closes the peer with 1003. Per-message compression is disabled.
• Origin. Protects against cross-site WebSocket hijacking: a foreign origin never completes the upgrade, even to a channel that would subsequently reject it.
• IP. The upgrade records the socket's IP, which the channel sees in context.clientAddress.
• Multiple instances. The server only knows its peers; broadcasts between instances require RedisSocketPubSub.

Related#

• serveNodeServes a Meeko application with Node's HTTP server, its Socket channels with ws, graceful shutdown on signals and the process failure policy.
• toNodeListenerAdapts a Fetch handler to Node's http.createServer callback, with streaming, multiple Set-Cookie headers, cancellation on client disconnect and the connection's IP.
• createNodeSocketUpgradeHandlerChecks Socket upgrade policy in Node's upgrade event and leaves framing to the host's chosen WebSocket library.
• defineSocketChannelDeclares a WebSocket channel in server/socket with schemas for each direction, per-room and per-event guards, and handlers for client messages.
• WebSocketMeeko as a full-stack framework
• Broadcast and multiple instancesMeeko as a full-stack framework