snub-ws

snub-ws

WebSocket server middleware for snub.

Built on uWebSockets.js. Requires Redis.

---

Install

npm install snub snub-ws

---

Quick start

const Snub = require('snub');
const SnubWS = require('snub-ws');

const snub = new Snub({ host: 'localhost' });

snub.use(SnubWS({ port: 8585, auth: false }));

snub.on('ws:hello', function (event, reply) {
  console.log('message from', event.from.username, ':', event.payload);
  reply('hi back');
});

A WebSocket client connects to ws://localhost:8585, sends ["hello", "world"], and the server logs message from null : world and replies ["hello:reply", "hi back"].

---

Config

SnubWS({
  port: 8585,

  // Authentication — see Auth section
  auth: false,

  // Log verbose internal info
  debug: false,

  // Allow the same username to have multiple simultaneous connections
  multiLogin: true,

  // Milliseconds before an unauthenticated client is kicked (AUTH_TIMEOUT)
  authTimeout: 3000,

  // Rate limiting: [maxMessages, windowMs] — false to disable
  // e.g. [50, 5000] = max 50 messages per 5 seconds
  throttle: [50, 5000],

  // Milliseconds of inactivity before a client is kicked (IDLE_TIMEOUT)
  // Minimum: 5 minutes. Maximum: 960 seconds (uWS v20 limit).
  idleTimeout: 960000,

  // Restrict WebSocket upgrades to listed origins. null = allow all.
  // e.g. ['https://example.com', 'https://app.example.com']
  allowedOrigins: null,

  // Maximum simultaneous connections. 0 = unlimited.
  maxConnections: 0,

  // Maximum inbound message size in bytes (default 16 MB)
  maxPayloadLength: 16777216,

  // Maximum outbound buffer in bytes before backpressure kicks in (default 1 MB)
  maxBackpressure: 1048576,

  // Maximum queued messages per client under backpressure.
  // When exceeded the queue is cleared and the client is kicked (QUEUE_OVERFLOW).
  maxQueueSize: 100,

  // Messages larger than this (bytes) are offloaded to HTTP. 0 = disabled.
  // Default: 0.5 MB
  offloadToHttpSize: 524288,

  // Include the raw message string in the snub payload for debugging.
  // true = all events, or pass an array of specific event names.
  includeRaw: false,

  // Additional event names that clients are blocked from sending
  internalWsEvents: [],
})

---

Auth

No auth

snub.use(SnubWS({ auth: false }));

All clients are accepted immediately on connect. username will be null.

Function

snub.use(SnubWS({
  auth: function (authPayload, accept) {
    if (authPayload.password === 'secret')
      return accept(true);
    accept(false);
  }
}));

accept can be called with:

• true — accept, username is taken from authPayload.username
• false — deny (client is kicked with AUTH_FAIL)
• object — accept and merge into the _acceptAuth reply sent to client

The authPayload argument is the object the client sent in its _auth message, merged with the current client state (so authPayload.remoteAddress etc. are available).

Snub event

Delegate auth to any listener in your app:

snub.use(SnubWS({ auth: 'authenticate-client' }));

snub.on('ws:authenticate-client', function (authPayload, reply) {
  // authPayload includes username, remoteAddress, etc.
  if (authPayload.username === 'admin')
    return reply({ role: 'admin' }); // merged into _acceptAuth
  reply(false);
});

HTTP Basic Auth

If the WebSocket upgrade request includes an Authorization: Basic … header, it is decoded and used as the auth payload automatically — no _auth message required.

---

Client protocol

Messages are JSON arrays: [eventName, payload?, replyId?]

Authenticate

Send this as the first message after connecting (required unless auth: false):

["_auth", { "username": "alice", "password": "secret" }]

On success the server responds:

["_acceptAuth", { "_id": "connectionId" }]

Additional keys from the accept(object) call are included in this response.

On failure the client is kicked with reason AUTH_FAIL.

Send a message

["event-name", { "any": "payload" }]

With a reply ID (the server will reply to this ID):

["event-name", { "any": "payload" }, "my-reply-id"]

The server replies with ["my-reply-id", replyData], or ["my-reply-id:error", { error: "..." }] if nothing was listening.

Built-in client events

Event	Sent by	Description
_auth	client	Authenticate with the server
_ping	client	Ping the server — server responds with _pong
_pong	client	Response to server-initiated _ping — ignored

Built-in server events

Event	Sent by	Description
_acceptAuth	server	Authentication accepted
_kickConnection	server	Server is about to close the connection — includes reason string
_offload	server	Message too large; fetch from HTTP — see Large messages
_ping	server	Server keepalive ping
_pong	server	Response to client _ping

---

Client → Server (receiving messages)

Inbound client messages are forwarded to snub with the ws: prefix.

snub.on('ws:my-event', function (event, reply) {
  console.log(event.from);     // client state object
  console.log(event.payload);  // the payload the client sent
  console.log(event._ts);      // server receive timestamp

  reply({ ok: true });         // sends ["replyId", { ok: true }] back to client
                               // (only if the client included a replyId)
});

The event.from object:

{
  id: 'instanceId;key_uid',   // unique connection ID
  username: 'alice',          // from auth payload (null if auth: false)
  channels: ['room1'],
  authenticated: true,
  connectTime: 1710000000000,
  remoteAddress: '127.0.0.1',
  lastMsgTime: 1710000001234,
  meta: {}                    // arbitrary key/value — see Meta
}

---

Server → Client (sending messages)

Send to specific clients

Target by username or connection ID. Comma-separate to target multiple.

// by username
snub.poly('ws:send:alice', ['event-name', payload]).send();

// by connection ID
snub.poly('ws:send:' + connectionId, ['event-name', payload]).send();

// multiple targets
snub.poly('ws:send:alice,bob', ['event-name', payload]).send();

Send to all clients

snub.poly('ws:send-all', ['event-name', payload]).send();

// optionally filter to specific usernames/IDs
snub.poly('ws:send-all', ['event-name', payload, ['alice', 'bob']]).send();

Send to a channel

// via event name suffix
snub.poly('ws:send-channel:room1', ['event-name', payload]).send();

// multiple channels in suffix
snub.poly('ws:send-channel:room1,room2', ['event-name', payload]).send();

// or pass channel list as payload element
snub.poly('ws:send-channel', ['event-name', payload, ['room1', 'room2']]).send();

---

Channels

Channels are sets of string tags on a client. Use them to group clients for targeted broadcasts.

// Add channels to a client (by username or ID)
snub.poly('ws:add-channel:alice', ['room1', 'room2']).send();

// Remove specific channels
snub.poly('ws:del-channel:alice', ['room2']).send();

// Replace the entire channel set
snub.poly('ws:set-channel:alice', ['room1']).send();

---

Kick

// by username or ID
snub.poly('ws:kick:alice', 'reason string').send();

// multiple targets
snub.poly('ws:kick:alice,bob', 'reason string').send();

// with a custom WebSocket close code (default 1000)
snub.poly('ws:kick', ['alice', 'reason string', 1008]).send();

// kick everyone
snub.poly('ws:kick-all', 'reason string').send();

Before closing, the server sends ["_kickConnection", "reason string"] to the client so it can handle the reason before the socket closes.

Automatic kick reasons:

Reason	Cause
AUTH_TIMEOUT	Client did not authenticate within authTimeout ms
AUTH_FAIL	Auth check returned false
DUPE_LOGIN	Second connection from same username when multiLogin: false
IDLE_TIMEOUT	No messages received within idleTimeout ms
THROTTLE_LIMIT	Client exceeded the rate limit
QUEUE_OVERFLOW	Outbound queue exceeded maxQueueSize
SERVER_SHUTDOWN	Server received SIGINT / SIGTERM / SIGUSR2

---

Meta

Arbitrary key/value data attached to a client. Included in all from payloads and query results. Updated values are broadcast via ws:client-updated.

// set by username or ID
snub.poly('ws:set-meta:alice', { role: 'admin', plan: 'pro' }).send();

// set for multiple clients via payload list
snub.poly('ws:set-meta', [{ role: 'guest' }, ['alice', 'bob']]).send();

Allowed value types: string, number, boolean, or array of string/number/boolean.

• Strings/numbers: max 128 characters
• Arrays: max 64 items, each item max 64 characters
• Other types are silently dropped

---

Query

All query events use snub.mono(...).awaitReply() since they need a response.

// Get clients by username or connection ID
const clients = await snub.mono('ws:get-clients:alice').awaitReply();
const clients = await snub.mono('ws:get-clients:alice,bob').awaitReply();

// Pass IDs/usernames as payload instead of suffix
const clients = await snub.mono('ws:get-clients', ['alice', 'bob']).awaitReply();

// Get all connected clients across all instances
const all = await snub.mono('ws:connected-clients').awaitReply();

// Filter connected-clients to specific usernames/IDs
const some = await snub.mono('ws:connected-clients', ['alice']).awaitReply();

// Get all clients subscribed to one or more channels
const inRoom = await snub.mono('ws:channel-clients', ['room1']).awaitReply();
const inRooms = await snub.mono('ws:channel-clients', ['room1', 'room2']).awaitReply();

All queries return an array of client state objects (see shape above). Queries fan out to all running instances and aggregate the results.

---

Server lifecycle events

These are emitted by snub-ws itself — listen with snub.on(...).

snub.on('ws:client-authenticated', function (state) {
  console.log('connected:', state.username, state.id);
});

snub.on('ws:client-disconnected', function (state) {
  console.log('disconnected:', state.username);
});

snub.on('ws:client-updated', function (state) {
  // fired when meta or channels change
  console.log('updated:', state.username, state.meta);
});

snub.on('ws:client-failedauth', function (state) {
  console.log('auth failed from', state.remoteAddress);
});

---

Large message offloading

When offloadToHttpSize is set and an outbound message exceeds that size, the payload is stored in Redis with a 30-second TTL and the client receives a redirect instead:

["_offload", "a3f9...hex32chars"]

The client fetches the full payload over HTTP:

GET http://hostname:port/?offload=a3f9...hex32chars

The server responds with the original JSON message payload (Content-Type: application/json). The ID is 128-bit cryptographically random.

---

Multi-instance

Each snub-ws instance registers itself in Redis. Query events (connected-clients, channel-clients, get-clients) fan out to all live instances and aggregate results. Send events target clients on whichever instance holds them.

Each instance is identified by config.instanceId (defaults to PID + random suffix). Use a unique instanceId per process if running multiple instances on the same host.

---

Graceful shutdown

On SIGINT, SIGTERM, or SIGUSR2:

1. All connected clients are kicked with SERVER_SHUTDOWN
2. 500 ms drain window allows close handshakes to complete
3. The instance is removed from Redis
4. process.exit(0)