Class: RTUInterface

Provides an abstraction layer beween the socket.io server and the Adonis IoC container.

Methods

except()

except(room: string | string[]): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<RTUServerToClientEvents>, SocketData>;

Excludes a room when emitting.

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<RTUServerToClientEvents>, SocketData>

a new BroadcastOperator instance for chaining

Example

// the "foo" event will be broadcast to all connected clients, except the ones that are in the "room-101" room
rtu.except("room-101").emit("foo", "bar");

// with an array of rooms
rtu.except(["room-101", "room-102"]).emit("foo", "bar");

// with multiple chained calls
rtu.except("room-101").except("room-102").emit("foo", "bar");

---

fetchSockets()

fetchSockets(): Promise<RemoteSocket<RTUClientToServerEvents, SocketData>[]>;

Returns the matching socket instances.

Note: this method also works within a cluster of multiple Socket.IO servers, with a compatible Adapter.

Returns

Promise<RemoteSocket<RTUClientToServerEvents, SocketData>[]>

Example

// return all Socket instances
const sockets = await rtu.fetchSockets();

// return all Socket instances in the "room1" room
const sockets = await rtu.in("room1").fetchSockets();

for (const socket of sockets) {
  console.log(socket.id);
  console.log(socket.handshake);
  console.log(socket.rooms);
  console.log(socket.data);

  socket.emit("hello");
  socket.join("room1");
  socket.leave("room2");
  socket.disconnect();
}

---

in()

in(room: string | string[]): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<RTUServerToClientEvents>, SocketData>;

Targets a room when emitting. Similar to to(), but might feel clearer in some cases:

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<RTUServerToClientEvents>, SocketData>

a new BroadcastOperator instance for chaining

Example

// disconnect all clients in the "room-101" room
rtu.in("room-101").disconnectSockets();

---

of()

of(name:
  | string
  | RegExp
| ParentNspNameMatchFn, fn?: (socket: RTUSocket<RTUServerToClientEvents, RTUClientToServerEvents, RTUInterServerEvents, RTUSocketData>) => void): Namespace<RTUServerToClientEvents, RTUClientToServerEvents, RTUInterServerEvents, RTUSocketData>;

Looks up a namespace.

Parameters

Parameter	Type	Description
name	| string | RegExp | ParentNspNameMatchFn	nsp name
fn?	(socket: RTUSocket<RTUServerToClientEvents, RTUClientToServerEvents, RTUInterServerEvents, RTUSocketData>) => void	optional, nsp connection ev handler

Returns

Namespace<RTUServerToClientEvents, RTUClientToServerEvents, RTUInterServerEvents, RTUSocketData>

Example

// with a simple string
const myNamespace = rtu.of("/my-namespace");

// with a regex
const dynamicNsp = rtu.of(/^/dynamic-\d+$/).on("connection", (socket) => {
  const namespace = socket.nsp; // newNamespace.name === "/dynamic-101"

  // broadcast to all clients in the given sub-namespace
  namespace.emit("hello");
});

---

send()

send(...args: unknown[]): this;

Sends a message event to all clients.

This method mimics the WebSocket.send() method.

Parameters

Parameter	Type
...args	unknown[]

Returns

this

self

See

https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send

Example

rtu.send("hello");

// this is equivalent to
rtu.emit("message", "hello");

---

serverSideEmit()

serverSideEmit<Ev>(ev: Ev, ...args: EventParams<DecorateAcknowledgementsWithTimeoutAndMultipleResponses<RTUInterServerEvents>, Ev>): boolean;

Sends a message to the other Socket.IO servers of the cluster.

Type Parameters

Type Parameter
Ev extends string

Parameters

Parameter	Type	Description
ev	Ev	the event name
...args	EventParams<DecorateAcknowledgementsWithTimeoutAndMultipleResponses<RTUInterServerEvents>, Ev>	an array of arguments, which may include an acknowledgement callback at the end

Returns

boolean

Example

rtu.serverSideEmit("hello", "world");

rtu.on("hello", (arg1) => {
  console.log(arg1); // prints "world"
});

// acknowledgements (without binary content) are supported too:
rtu.serverSideEmit("ping", (err, responses) => {
  if (err) {
    // some servers did not acknowledge the event in the given delay
  } else {
    console.log(responses); // one response per server (except the current one)
  }
});

rtu.on("ping", (cb) => {
  cb("pong");
});

---

serverSideEmitWithAck()

serverSideEmitWithAck<Ev>(ev: Ev, ...args: AllButLast<EventParams<RTUInterServerEvents, Ev>>): Promise<FirstNonErrorArg<Last<EventParams<RTUInterServerEvents, Ev>>>[]>;

Sends a message and expect an acknowledgement from the other Socket.IO servers of the cluster.

Type Parameters

Type Parameter
Ev extends string

Parameters

Parameter	Type	Description
ev	Ev	the event name
...args	AllButLast<EventParams<RTUInterServerEvents, Ev>>	an array of arguments

Returns

Promise<FirstNonErrorArg<Last<EventParams<RTUInterServerEvents, Ev>>>[]>

a Promise that will be fulfilled when all servers have acknowledged the event

Example

try {
  const responses = await rtu.serverSideEmitWithAck("ping");
  console.log(responses); // one response per server (except the current one)
} catch (e) {
  // some servers did not acknowledge the event in the given delay
}

---

to()

to(room: string | string[]): BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<RTUServerToClientEvents>, SocketData>;

Targets a room when emitting.

Parameters

Parameter	Type	Description
room	string | string[]	a room, or an array of rooms

Returns

BroadcastOperator<DecorateAcknowledgementsWithMultipleResponses<RTUServerToClientEvents>, SocketData>

a new BroadcastOperator instance for chaining

Example

// the “foo” event will be broadcast to all connected clients in the “room-101” room
rtu.to("room-101").emit("foo", "bar");

// with an array of rooms (a client will be notified at most once)
rtu.to(["room-101", "room-102"]).emit("foo", "bar");

// with multiple chained calls
rtu.to("room-101").to("room-102").emit("foo", "bar");

---

use()

use(fn: (socket: RTUSocket<RTUServerToClientEvents, RTUClientToServerEvents, RTUInterServerEvents, RTUSocketData>, next: (err?: ExtendedError) => void) => void): this;

Registers a middleware, which is a function that gets executed for every incoming Socket.

Parameters

Parameter	Type	Description
fn	(socket: RTUSocket<RTUServerToClientEvents, RTUClientToServerEvents, RTUInterServerEvents, RTUSocketData>, next: (err?: ExtendedError) => void) => void	the middleware function

Returns

this

Example

rtu.use((socket, next) => {
  // ...
  next();
});

---

write()

write(...args: unknown[]): this;

Sends a message event to all clients. Alias of send.

Parameters

Parameter	Type
...args	unknown[]

Returns

this

self