Crate socketioxide_emitter

Source
Expand description

The Socketioxide Emitter crate allows you to easily communicate with a group of Socket.IO servers from another rust process (server-side). It must be used in conjunction with socketioxide-redis.

Socketioxide Emitter is not compatible with @socketio/redis-adapter and @socketio/redis-emitter. They use completely different protocols and cannot be used together. Do not mix socket.io JS servers with socketioxide rust servers. If you are looking for a way to emit events to a cluster of node socket.io servers in rust, you should use the socketio-rust-emitter package.

§Diagram taken from the socket.io documentation:

§Features and parsers

The emitter supports two parsers: Common and MessagePack. You can enable/disable them with the parser-common and parser-msgpack feature flags. If you disable all features, you won’t be able to emit events. It will be only possible to manipulate sockets (join/leave rooms, disconnect).

§Emit cheat sheet (example with redis)

use redis::{AsyncCommands, aio::MultiplexedConnection};
use socketioxide_emitter::{Driver, IoEmitter};

struct RedisConnection(MultiplexedConnection);
impl Driver for RedisConnection {
    type Error = redis::RedisError;

    async fn emit(&self, channel: String, data: Vec<u8>) -> Result<(), Self::Error> {
        self.0
            .clone()
            .publish::<_, _, redis::Value>(channel, data)
            .await?;
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = redis::Client::open("redis://127.0.0.1").unwrap();
    let conn = client.get_multiplexed_tokio_connection().await?;
    let conn = RedisConnection(conn);
    // sending to all clients
    IoEmitter::new().emit("event", "hello!", &conn).await?;

    // sending to all clients in 'room1' room
    IoEmitter::new().to("room1").emit("event", "message", &conn).await?;

    // sending to all clients in 'room1' except those in 'room2'
    IoEmitter::new().to("room1").except("room2").emit("event", "message", &conn).await?;

    // sending to individual socketid (private message).
    // (You will have to make the socket join a room corresponding to its id when it connects.)
    IoEmitter::new().to("tK3lxSproMuTbioPAAAB").emit("event", "message", &conn).await?;

    let nsp = IoEmitter::new().of("/admin");

    // sending to all clients in 'admin' namespace
    nsp.clone().emit("event", "message", &conn).await?;

    // sending to all clients in 'admin' namespace and in 'notifications' room
    nsp.to("notifications").emit("event", "message", &conn).await?;

    let msgpack = IoEmitter::new_msgpack();

    // sending to all clients and encode message with the msgpack format.
    msgpack.clone().emit("event", "message", &conn).await?;

    // sending to all clients in 'notifications' room and encode message with the msgpack format.
    msgpack.to("notifications").emit("event", "message", &conn).await?;

    Ok(())
}

Structs§

IoEmitter
The IoEmitter is the main structure for emitting events to a socket.io cluster. It provides a convenient way to broadcast events to all connected nodes and clients. It acts as a simple builder for creating socket.io messages to send through the driver.

Enums§

EmitErrormsgpack-parser or common-parser
An error that occurs when broadcasting messages.

Traits§

Driver
The abstraction between the socketio emitter and the underlying system. You must implement it for your specific Adapter driver.