Migration guide and changelog for v0.14.0

[Totodore]

Migration guide

With v0.14.0, multiple breaking changes have been introduced. Here is a little migration guide to help migrating from v0.13 to v0.14.

The end of storing SocketIo handle as a static to access it from inside a handler

Starting from v0.14 you can use the SocketIo type as an extractor. For example to emit data on another namespace.

io.ns("/", |s: SocketRef| {
    s.on("test", |Data(data): Data<String>, io: SocketIo| {
        let _ = io.of("/ns2").broadcast().emit("test", data);
    });
}); 

The global state feature

In v0.13 it was not required for the state types to be cloneable. Because this is now the case if you want to share common behavior with your state you should store it in an Arc:
react-rooms-chat example:

use std::{collections::{HashMap, VecDeque}, sync::Arc};
use tokio::sync::RwLock;

#[derive(serde::Serialize, Clone, Debug)]
pub struct Message {
    pub text: String,
    pub user: String,
    pub date: chrono::DateTime<chrono::Utc>,
}

pub type RoomStore = HashMap<String, VecDeque<Message>>;

#[derive(Clone, Default)]                           // We add a `Clone` impl to the store
pub struct MessageStore {
    pub messages: Arc<RwLock<RoomStore>>,           // We wrap the `RwLock<RoomStore>`in an `Arc`
}

impl MessageStore {
    pub async fn insert(&self, room: &str, message: Message) {
        let mut binding = self.messages.write().await;
        let messages = binding.entry(room.to_owned()).or_default();
        messages.push_front(message);
        messages.truncate(20);
    }

    pub async fn get(&self, room: &str) -> Vec<Message> {
        let messages = self.messages.read().await.get(room).cloned();
        messages.unwrap_or_default().into_iter().rev().collect()
    }
}

The extension feature

In v0.13 it was not required for any set extensions to be cloneable. Because it is now the case you should either make your extension type Clone if it is cheaply cloneable or wrap it with an Arc if it a heavy clone or that you want to share the underlying memory.
chat example:

use std::sync::atomic::AtomicUsize;

use serde::{Deserialize, Serialize};
use socketioxide::{
    extract::{Data, Extension, SocketRef, State},
    SocketIo,
};
use tower::ServiceBuilder;
use tower_http::{cors::CorsLayer, services::ServeDir};
use tracing::info;
use tracing_subscriber::FmtSubscriber;
use std::sync::Arc;

// Here the `Username` struct which is stored in the `Extensions` must be cloneable.
#[derive(Deserialize, Serialize, Debug, Clone)]
#[serde(transparent)]
struct Username(String);

#[derive(Deserialize, Serialize, Debug, Clone)]
#[serde(rename_all = "camelCase", untagged)]
enum Res {
    Login {
        #[serde(rename = "numUsers")]
        num_users: usize,
    },
    UserEvent {
        #[serde(rename = "numUsers")]
        num_users: usize,
        username: Username,
    },
    Message {
        username: Username,
        message: String,
    },
    Username {
        username: Username,
    },
}
#[derive(Clone)]
struct UserCnt(Arc<AtomicUsize>);
impl UserCnt {
    fn new() -> Self {
        Self(Arc::new(AtomicUsize::new(0)))
    }
    fn add_user(&self) -> usize {
        self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst) + 1
    }
    fn remove_user(&self) -> usize {
        self.0.fetch_sub(1, std::sync::atomic::Ordering::SeqCst) - 1
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let subscriber = FmtSubscriber::new();

    tracing::subscriber::set_global_default(subscriber)?;

    info!("Starting server");

    let (layer, io) = SocketIo::builder().with_state(UserCnt::new()).build_layer();

    io.ns("/", |s: SocketRef| {
        s.on(
            "new message",
             // now we can extract the `Username` directly with the `Extension` extractor calling `socket.extensions`
            |s: SocketRef, Data::<String>(msg), Extension::<Username>(username)| {
                let msg = Res::Message {
                    username,
                    message: msg,
                };
                s.broadcast().emit("new message", msg).ok();
            },
        );

        s.on(
            "add user",
            |s: SocketRef, Data::<String>(username), user_cnt: State<UserCnt>| {
                if s.extensions.get::<Username>().is_some() {
                    return;
                }
                let num_users = user_cnt.add_user();
                s.extensions.insert(Username(username.clone()));
                s.emit("login", Res::Login { num_users }).ok();

                let res = Res::UserEvent {
                    num_users,
                    username: Username(username),
                };
                s.broadcast().emit("user joined", res).ok();
            },
        );

        s.on("typing", |s: SocketRef, Extension::<Username>(username)| {
            s.broadcast()
                .emit("typing", Res::Username { username })
                .ok();
        });

        s.on(
            "stop typing",
            |s: SocketRef, Extension::<Username>(username)| {
                s.broadcast()
                    .emit("stop typing", Res::Username { username })
                    .ok();
            },
        );

        s.on_disconnect(
            |s: SocketRef, user_cnt: State<UserCnt>, Extension::<Username>(username)| {
                let num_users = user_cnt.remove_user();
                let res = Res::UserEvent {
                    num_users,
                    username,
                };
                s.broadcast().emit("user left", res).ok();
            },
        );
    });

    let app = axum::Router::new()
        .nest_service("/", ServeDir::new("dist"))
        .layer(
            ServiceBuilder::new()
                .layer(CorsLayer::permissive()) // Enable CORS policy
                .layer(layer),
        );

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();

    Ok(())
}

Changelog

socketioxide

• (Breaking): State reworked to avoid having unsafe global mutable state (issue #317). Therefore State types must now implement Clone and will be cloned for each handler where the state is used.
• (Breaking): Extensions reworked to avoid Send + Sync requirements on extensions (issue #295). They are now extracted by Cloning. Therefore all the type must implement Clone. An Extension extractor is available to get an extension directly without calling socket.extensions.get().
• feat: New HttpExtension types to extract extensions from the http request.
• feat: SocketIo can now be used as an extractor. So you can now easily access the entire socket.io context from your handlers.
• feat: Dynamic namespaces. You can know set dynamic namespaces with the dyn_ns function. You can specify patterns with the {name} syntax thanks to the matchit crate. The dynamic namespace will create a child namespace for any path that matches the given pattern with the given handler.

What's Changed

• chore(deps): update tokio-tungstenite requirement from 0.21.0 to 0.23.0 by @dependabot in chore(deps): update tokio-tungstenite requirement from 0.21.0 to 0.23.0 #326
• feat(socketio/extensions): rework extensions and add an Extension decorator and an HttpExtension decorator by @Totodore in feat(socketio/extensions): rework extensions and add an Extension decorator and an HttpExtension decorator #309
• chore(deps): remove useless dashmap dep and improve doc by @Totodore in chore(deps): remove useless dashmap dep and improve doc #328
• Feat: io client shared in socketdata by @Totodore in Feat: io client shared in socketdata #327
• doc: fix useless links by @Totodore in doc: fix useless links #329
• chore(ci): bench only on main and on manual trigger by @Totodore in chore(ci): bench only on main and on manual trigger #332
• feat: per client state by @Totodore in feat: per client state #330
• feat: remove config from socket by @Totodore in feat: remove config from socket #331
• feat(socketio/packet): switch to Str type for ns path storage by @Totodore in feat(socketio/packet): switch to Str type for ns path storage #334
• chore(deps): bump ws and engine.io-client in /examples/loco-rooms-chat/client by @dependabot in chore(deps): bump ws and engine.io-client in /examples/loco-rooms-chat/client #336
• chore(deps-dev): bump braces from 3.0.2 to 3.0.3 in /examples/loco-rooms-chat/client by @dependabot in chore(deps-dev): bump braces from 3.0.2 to 3.0.3 in /examples/loco-rooms-chat/client #337
• chore(deps): bump ws and engine.io-client in /examples/react-rooms-chat/client by @dependabot in chore(deps): bump ws and engine.io-client in /examples/react-rooms-chat/client #338
• chore(deps-dev): bump braces from 3.0.2 to 3.0.3 in /examples/react-rooms-chat/client by @dependabot in chore(deps-dev): bump braces from 3.0.2 to 3.0.3 in /examples/react-rooms-chat/client #339
• feat: namespace routing by @Totodore in feat: namespace routing #333
• fix: add generic ns path to avoid .into() everywhere in packet by @Totodore in fix: add generic ns path to avoid .into() everywhere in packet #340
• feat: Namespace key in map as Str by @Totodore in feat: Namespace key in map as Str #342
• feat: Namespace key in map as Str by @Totodore in feat: Namespace key in map as Str #343

Full Changelog: v0.13.1...v0.14.0