socketioxide

The engineioxide-core crate provides shared types and utilities used by both engineioxide and socketioxide-core. The two primary types are:

• Sid: A unique identifier for a socket connection.
• Str: A wrapper around Bytes that ensures UTF-8 encoding.

Horizontal Scaling

You can achieve effortless horizontal scaling by using pluggable adapters:

• socketioxide-redis (Redis / Valkey)
• socketioxide-mongodb (MongoDB)
• socketioxide-postgres (PostgreSQL)

Middleware

Because Socketioxide integrates with the Tower ecosystem, you can use any tower-http middleware, such as:

• CORS
• Compression
• Authorization

Use the emit method to send data to one or many clients.

Argument Handling

• Multiple Arguments: If you provide tuple-like data (such as tuples or arrays), they are treated as multiple distinct arguments in the payload.
• Sending an Array as the First Argument: To send an array as the single first argument of a payload, you must wrap it in another array or a tuple.
• Vec Behavior: A Vec is always treated as a single argument.

Broadcasting and Scaling

When using broadcast methods (like .to(), .except(), etc.), the emit method returns a Future that must be awaited. This is because socketioxide may need to communicate with remote instances when using horizontal scaling via remote adapters.

To emit binary data correctly, you must use a data type that implements Serialize as binary data.

Warning: Using Vec<u8> will result in the data being treated as a sequence of numbers rather than actual binary data.

Recommended Approaches

1. Use Bytes: Use the bytes::Bytes crate.
2. Use serde_bytes: Use the serde_bytes crate.
3. Generic Binary Data: If you need to emit generic data that might contain binary, use rmpv::Value instead of serde_json::Value. serde_json::Value will serialize binary data as a sequence of numbers.

use bytes::Bytes;

// Emitting multiple arguments including binary data
async fn handler(socket: SocketRef, Data(data): Data::<(String, Bytes, Bytes)>) {
    socket.emit("test", &("world", "hello", Bytes::from_static(&[1, 2, 3, 4]))).ok();
}

The .local() operator allows you to broadcast messages to all sockets within a namespace that are connected specifically to the current node.

Important Note: When using the default in-memory adapter, this operator behaves as a no-op (it does nothing) because all sockets are inherently on the same node. This operator is primarily useful when using distributed adapters (like Redis) to limit the scope of a broadcast to the local instance rather than the entire cluster.

# use socketioxide::{SocketIo, extract::*};
# use serde_json::Value;
async fn handler(socket: SocketRef, Data(data): Data::<Value>) {
    // This message will be broadcast to all sockets in this
    // namespace that are connected to this node
    socket.local().emit("test", &data).await;
}

let (_, io) = SocketIo::new_svc();
io.ns("/", async |s: SocketRef| s.on("test", handler));

When you need to act on a group of sockets (e.g., emitting an event or disconnecting them), do not fetch the sockets into a list to iterate over them. Instead, chain the action directly to the operator chain. This is the correct and more efficient approach.

Incorrect (Inefficient): Fetching sockets and then looping to emit/leave.

Correct (Efficient): Chaining .emit() or .disconnect() directly to the selection operator.

// Correct Approach: Chain actions directly
io.within("room1").emit("foo", "bar").await.unwrap();
io.within("room1").disconnect().await.unwrap();

// Incorrect Approach: Fetching and looping
let sockets = io.within("room1").fetch_sockets().await.unwrap();
for socket in sockets {
    socket.emit("test", &"Hello").await.unwrap();
    socket.leave("room1").await.unwrap();
}