websockets

Real-time WebSocket helpers for Gingee apps (rooms, broadcast, tenant naming). Connections are accepted by the **master** process (HTTP upgrade on the public port). Configure handlers in app.json → websockets. Multi-node: set gingee.json → websockets.fanout.driver: "redis" and sibling websockets.redis so toRoom / toApp fan out across load-balanced masters (local sockets + Redis pub/sub). IMPORTANT: Requires the websockets permission. Multi-tenant apps: prefix rooms with tenantRoom(tenantId, name) so tenants cannot share channels accidentally.
Description:
  • Real-time WebSocket helpers for Gingee apps (rooms, broadcast, tenant naming). Connections are accepted by the **master** process (HTTP upgrade on the public port). Configure handlers in app.json → websockets. Multi-node: set gingee.json → websockets.fanout.driver: "redis" and sibling websockets.redis so toRoom / toApp fan out across load-balanced masters (local sockets + Redis pub/sub). IMPORTANT: Requires the websockets permission. Multi-tenant apps: prefix rooms with tenantRoom(tenantId, name) so tenants cannot share channels accidentally.
Examples
// From an HTTP script — push to a room
const ws = require('websockets');
ws.toRoom(ws.tenantRoom(tenantId, 'lobby'), { type: 'ping' });
// In box websocket handler (see app.json websockets.handler)
module.exports = async function (socket, ctx) {
  const room = require('websockets').tenantRoom(socket.tenantId || 'default', 'lobby');
  socket.join(room);
  socket.on('message', (raw) => {
    socket.to(room).send({ echo: raw });
  });
};

Methods

(inner) assertRoomTenant(room, tenantId) → {true}

Description:
  • Throw if room is not under the given tenant prefix.
Parameters:
Name Type Description
room string
tenantId string | number
Returns:
Type
true

(inner) getConnectionCount() → {number}

Returns:
open connections for the current app
Type
number

(inner) getRoomSize(room) → {number}

Parameters:
Name Type Description
room string
Returns:
Type
number

(inner) tenantRoom(tenantId, name) → {string}

Description:
  • Build a tenant-scoped room name: t:{tenantId}:{name}
Parameters:
Name Type Description
tenantId string | number
name string logical room (e.g. "lobby", "channel:42")
Returns:
Type
string

(inner) toApp(data) → {number}

Description:
  • Send a message to every open socket for the current app. Prefer toRoom with tenant-scoped rooms for multi-tenant apps.
Parameters:
Name Type Description
data string | object | Buffer
Returns:
recipients
Type
number

(inner) toRoom(room, data) → {number}

Description:
  • Send a message to all sockets in a room for the current app.
Parameters:
Name Type Description
room string
data string | object | Buffer Objects are JSON-serialized
Returns:
recipients
Type
number