broadcast

Send a message to every WebSocket in a room, from a wsHandler or from any route handler.

import { broadcast } from '@gio.js/core';

broadcast('lobby', JSON.stringify({ text: 'Deploy finished' }));

Reference

Returns

boolean: true when the message was handed to the server, false when no WebSocket server is connected - WebSockets are off ([websocket] enabled = false), the code runs under gio export or the test kit's callRoute, or the worker is restarting. A false message is dropped, like one sent to an empty room. true does not mean anyone received it: a room with no members takes the message silently.

Behavior

• Room membership lives in the Rust server, so a broadcast crosses to it as one frame however many sockets it reaches - including sockets handled by other workers of a pool.
• A socket receives broadcasts only once its wsHandler has accepted it.
• Delivery is best-effort, like any WebSocket send: under heavy backpressure messages are dropped rather than buffered without bound.

Errors

An empty or non-string room throws a TypeError; a name over 256 bytes throws a RangeError.

Examples

A chat room, with an HTTP publish endpoint

import { broadcast, type GioRequest, type GioSocket } from '@gio.js/core';

// WebSocket: ws://host/api/rooms/lobby
export function wsHandler(socket: GioSocket) {
  const room = socket.params.room as string;
  socket.join(room);
  socket.on('message', (text) => broadcast(room, String(text), { except: socket.id }));
}

// HTTP: POST /api/rooms/lobby publishes to everyone in the room.
export function POST(req: GioRequest<'/api/rooms/:room'>) {
  const { text } = req.json<{ text: string }>();
  const delivered = broadcast(req.params.room, JSON.stringify({ text, at: Date.now() }));
  return { delivered };
}

With one browser connected to /api/rooms/lobby, a POST of {"text":"hello"} answers {"delivered":true} and the socket receives {"text":"hello","at":...}.

Binary data

const frame = new Uint8Array([1, 2, 3]);
broadcast('telemetry', frame);   // a binary frame; clients get a Blob or ArrayBuffer

Good to know

• Per server process. Rooms do not span GioJS instances. Behind a load balancer, relay messages through a shared bus (Redis, NATS, Postgres LISTEN) and call broadcast on each instance.
• Room limits. A socket can be in up to 100 rooms; socket.join throws beyond that. Rooms disappear when their last member leaves.
• Not the same as socket.broadcast(data), which sends to every socket connected to the same path, the sender included.

Related

• WebSockets: Rooms
• wsHandler
• useWebSocket
• [websocket]

Version history