Introduction to remote adapters

[Totodore]

Introduction to remote adapters.

With socketioxide v0.16 you can now use remote adapters!

Remote adapters are a way for socket.io to communicate to other instances in a horizontally scaled environment. This is useful when you have multiple running instances of your application and you want to broadcast messages to all connected clients.

They work by exchanging messages between instances using a shared storage backend. This can be a database, a message queue, or any other shared storage that all instances can access. Currently only Redis pub/sub is supported, but more backends will be added in the future.

What can you do with remote adapters?

• Broadcast a message.
• Broadcast a message and get a stream of expected acks.
• Join / leave rooms.
• Fetch rooms.
• Fetch sockets. When fetching sockets you will get a list of RemoteSocket. It implements a subset of the socket API. You can use it to emit message (with ack or not), join/leave rooms, get the socket id, etc...

What do you have to change in your code to use remote adapters?

The following structs are generic over the adapter you want to use, hence you need to, either specify the adapter type or generify your functions over the adapter type.
Prefer the latter as it allows you to switch between adapters without changing your code.

• SocketIo<A: Adapter>
• SocketIoLayer<A: Adapter>
• SocketIoService<A: Adapter>
• SocketRef<A: Adapter>
• RemoteSocket<A: Adapter>
• Socket<A: Adapter>
• AckSender<A: Adapter>

You should use generic functions instead of closures for event handlers. This allows you to be generic over the adapter you want to use.

To use remote adapters, you need to create an instance of the adapter and pass it to the Socketio struct when creating a new server. Here's an example using the Redis adapter:

use socketioxide::{
    adapter::{Adapter, Emitter},
    extract::{Data, SocketRef},
    ParserConfig, SocketIo,
};
use socketioxide_redis::drivers::redis::redis_client as redis;
use socketioxide_redis::{RedisAdapter, RedisAdapterCtr};

// It is heavily recommended to use generic fns instead of closures for handlers.
// This allows to be generic over the adapter you want to use.
async fn on_drawing<A: Adapter>(s: SocketRef<A>, Data(data): Data<Value>) {
    // This will broadcast the drawing data to all connected clients no matter 
    // which instance they are connected to.
    s.broadcast().emit("drawing", &data).await.ok();
}
// This is the first solution, you will need to change the signature of the handler 
// if you want to switch to another adapter.
fn on_connect(s: SocketRef<RedisAdapter<Emitter>>) {
    s.on("drawing", on_drawing);
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = redis::Client::open("redis://127.0.0.1:6379?protocol=resp3")?;
    let adapter = RedisAdapterCtr::new_with_redis(&client).await?;

    let (layer, io) = SocketIo::builder()
        .with_adapter::<RedisAdapter<_>>(adapter)
        .build_layer();

    io.ns("/", on_connect).await?;
    // You can then set the socket.io layer on your preferred HTTP lib.
    // ...
}

[tausifcreates]

The biggest release everyone was waiting for!