feat: implement typed metadata storage for rooms and clients (limited, but work for now)

Author: ronakgh97

examples/bot.rs

@@ -12,7 +12,7 @@ use wincode::{SchemaRead, SchemaWrite};
 const ADDR: &str = "127.0.0.1:7777";
 const ROOM: &str = "test-room";
 const BOT_COUNT: usize = 144;
-const TICK_RATE: u64 = 24;
+const TICK_RATE: u64 = 8;
 const MAX_SPEED: f32 = 400.0;
 const SCREEN: f32 = 600.0;
 

examples/daemon.rs

@@ -36,6 +36,13 @@ impl DaemonHandler {
     }
 }
 
+#[allow(dead_code)]
+#[derive(Debug)]
+struct RoomMeta {
+    foo: String,
+    bar: String,
+}
+
 impl ServerHandler for DaemonHandler {
     fn on_connect(&self, addr: SocketAddr) -> bool {
         let count = self
@@ -310,6 +317,13 @@ async fn main() -> Result<()> {
     }
 
     server_handle.create_room("test-room")?;
+    server_handle.set_room_meta(
+        "test-room",
+        RoomMeta {
+            foo: "foo".to_string(),
+            bar: "bar".to_string(),
+        },
+    );
 
     let ctrl_listener = TcpListener::bind("0.0.0.0:8888").await?;
     info!("Control server listening on 0.0.0.0:8888");

src/client.rs

@@ -1,5 +1,6 @@
 use tokio::io::{BufReader, BufWriter};
 use tokio::net::TcpStream;
+use uuid::Uuid;
 
 use crate::protocol;
 use crate::types::{ClientWire, ServerEvent, ServerWire, SyncError};
@@ -9,6 +10,7 @@ pub struct Client {
     reader: BufReader<tokio::net::tcp::OwnedReadHalf>,
     writer: BufWriter<tokio::net::tcp::OwnedWriteHalf>,
     max_payload: usize,
+    client_id: Option<Uuid>,
 }
 
 impl Client {
@@ -22,6 +24,14 @@ impl Client {
         ClientBuilder::new()
     }
 
+    /// Get the client's UUID assigned by the server.
+    ///
+    /// Returns `None` before the first successful [`join`](Self::join) + [`recv`](Self::recv)
+    /// (the server assigns the ID and sends it in the `Joined` event).
+    pub fn client_id(&self) -> Option<Uuid> {
+        self.client_id
+    }
+
     /// Join a room. If room does not exist, returns [`SyncError::RoomNotFound`]
     pub async fn join(&mut self, room_id: &str) -> Result<(), SyncError> {
         let msg = ClientWire::JoinRoom {
@@ -36,7 +46,7 @@ impl Client {
     }
 
     /// Send a ping (keep-alive).
-    #[inline(always)]
+    #[inline]
     pub async fn ping(&mut self) -> Result<(), SyncError> {
         self.send(&ClientWire::Ping).await
     }
@@ -53,7 +63,7 @@ impl Client {
     /// Receive the next server event.
     /// Ping/pong keepalive is handled internally
     /// Returns `Ok(None)` on clean disconnect.
-    #[inline]
+    #[inline(always)]
     pub async fn recv(&mut self) -> Result<Option<ServerEvent>, SyncError> {
         loop {
             let payload = match protocol::read_frame_raw(&mut self.reader, self.max_payload).await {
@@ -78,14 +88,21 @@ impl Client {
                 continue;
             }
 
+            // Capture client_id from Joined event
+            if let ServerWire::Joined { client_id, .. } = &wire {
+                self.client_id = Some(*client_id);
+            }
+
             return Ok(Some(Self::wire_to_event(wire)));
         }
     }
 
+    #[inline(always)]
     async fn send(&mut self, msg: &ClientWire) -> Result<(), SyncError> {
         protocol::write_frame(&mut self.writer, msg).await
     }
 
+    #[inline]
     fn wire_to_event(wire: ServerWire) -> ServerEvent {
         match wire {
             ServerWire::Joined { client_id, room_id } => ServerEvent::Joined { client_id, room_id },
@@ -141,6 +158,7 @@ impl ClientBuilder {
             reader: BufReader::with_capacity(2 * 1024 * 1024, read_half),
             writer: BufWriter::with_capacity(1024 * 1024, write_half),
             max_payload: self.max_payload,
+            client_id: None,
         })
     }
 }

src/handler.rs

@@ -47,6 +47,7 @@ pub trait ServerHandler: Send + Sync + 'static {
 
     /// Called when a broadcast message is relayed.
     /// client_id is the sender, and the message has already been relayed to all peers.
+    #[inline]
     fn on_broadcast(&self, _client_id: Uuid, _room_id: &str, _data: &[u8]) {}
 
     /// Called when a frame is dropped because a client's write channel is full.
@@ -55,6 +56,7 @@ pub trait ServerHandler: Send + Sync + 'static {
     /// NOTE: For auto-kicking or pausing slow clients, you need to monitor channel length via [`ServerHandle::get_client_channel_len`](crate::ServerHandle::get_client_channel_len)
     /// or [`ServerHandle::get_room_channel_lens`](crate::ServerHandle::get_room_channel_lens) and implement your own logic in this hook.
     /// The library does not auto-kick or pause clients on backpressure, as some games may prefer to drop frames silently.
+    #[inline]
     fn on_backpressure(&self, _client_id: Uuid, _room_id: &str) {}
 
     /// Called when server is shutdown via ctrl-c (shutdown signals)

src/lib.rs

@@ -6,6 +6,7 @@ pub mod log;
 mod protocol;
 mod room;
 mod server;
+mod storage;
 mod types;
 
 pub use client::{Client, ClientBuilder};

src/room.rs

@@ -1,10 +1,11 @@
-use std::collections::HashMap;
+use std::any::Any;
 
 use bytes::Bytes;
 use dashmap::DashMap;
 use tokio::sync::mpsc;
 use uuid::Uuid;
 
+use crate::storage::Storage;
 use crate::types::{Result, ServerWire, SyncError};
 
 /// A broadcast frame to be sent to a client. `Bytes` is reference-counted,
@@ -17,20 +18,20 @@ pub type BroadcastFrame = Bytes;
 /// connected clients identified by their UUIDs. Each client has a
 /// write channel for outgoing frames.
 ///
-/// Rooms carry a string metadata map. The library does not interpret metadata —
+/// Rooms carry a typed metadata storage. The library does not interpret metadata —
 /// users store whatever they need (passwords, max players, game mode, etc.)
 /// and check it in their [`ServerHandler`](crate::ServerHandler) hooks.
 pub struct Room {
     clients: DashMap<Uuid, mpsc::Sender<BroadcastFrame>>,
-    metadata: DashMap<String, String>,
+    pub(crate) metadata: Storage,
 }
 
 #[allow(dead_code)]
 impl Room {
     fn new() -> Self {
         Self {
-            clients: DashMap::with_capacity(64),
-            metadata: DashMap::with_capacity(128),
+            clients: DashMap::with_capacity(128),
+            metadata: Storage::new(),
         }
     }
 
@@ -58,7 +59,7 @@ impl Room {
     ///
     /// Returns `None` if the client is not in this room.
     /// Higher values indicate the client's writer task is falling behind.
-    #[inline(always)]
+    #[inline]
     pub fn channel_len(&self, id: &Uuid) -> Option<usize> {
         self.clients
             .get(id)
@@ -69,7 +70,7 @@ impl Room {
     ///
     /// Returns `(uuid, channel_len)` pairs. Useful for monitoring
     /// backpressure and identifying slow clients.
-    #[inline(always)]
+    #[inline]
     pub fn all_channel_lens(&self) -> Vec<(Uuid, usize)> {
         self.clients
             .iter()
@@ -122,31 +123,34 @@ impl Room {
         self.clients.iter().map(|e| *e.key()).collect()
     }
 
-    /// Get a metadata value by key.
+    /// Store a typed metadata value. Replaces any previous value.
     #[inline]
-    pub fn get_meta(&self, key: &str) -> Option<String> {
-        self.metadata.get(key).map(|v| v.clone())
+    pub fn set_meta<T: Any + Send + Sync + 'static>(&self, value: T) {
+        self.metadata.set(value);
     }
 
-    /// Set a metadata key-value pair.
+    /// Read the stored metadata via a callback.
+    ///
+    /// Returns `None` if no metadata is set or the stored type doesn't match `T`.
+    /// The callback receives `&T` and can extract whatever it needs — no `Clone` required.
     #[inline]
-    pub fn set_meta(&self, key: impl Into<String>, value: impl Into<String>) {
-        self.metadata.insert(key.into(), value.into());
+    pub fn get_meta<T: Any + Send + Sync + 'static, R>(
+        &self,
+        f: impl FnOnce(&T) -> R,
+    ) -> Option<R> {
+        self.metadata.get(f)
     }
 
-    /// Remove a metadata key.
+    /// Remove and return the stored metadata, downcasted to `T`.
     #[inline]
-    pub fn remove_meta(&self, key: &str) -> bool {
-        self.metadata.remove(key).is_some()
+    pub fn take_meta<T: Any + Send + Sync + 'static>(&self) -> Option<T> {
+        self.metadata.take()
     }
 
-    /// Get all metadata as a HashMap.
+    /// Check if metadata is set on this room.
     #[inline]
-    pub fn get_all_meta(&self) -> HashMap<String, String> {
-        self.metadata
-            .iter()
-            .map(|e| (e.key().clone(), e.value().clone()))
-            .collect()
+    pub fn has_meta(&self) -> bool {
+        self.metadata.is_set()
     }
 }
 

src/server.rs

@@ -1,4 +1,4 @@
-use std::collections::HashMap;
+use std::any::Any;
 use std::net::SocketAddr;
 use std::sync::Arc;
 use std::time::Duration;
@@ -12,13 +12,15 @@ use uuid::Uuid;
 use crate::handler::{NoopHandler, ServerHandler};
 use crate::protocol;
 use crate::room::RoomManager;
+use crate::storage::Storage;
 use crate::types::{ClientWire, Result, ServerConfig, ServerWire, SyncError};
 use crate::{error, info, warn};
 
 /// Tracks per-client state on the server side.
 struct ClientState {
     room_id: Option<String>,
     addr: SocketAddr,
+    metadata: Storage,
 }
 
 /// A broadcast relay game server.
@@ -74,7 +76,7 @@ impl ServerHandle {
     }
 
     /// Create a room at runtime. Fails if the room already exists.
-    #[inline(always)]
+    #[inline]
     pub fn create_room(&self, id: &str) -> Result<()> {
         self.rooms.create(id)?;
         self.handler.on_room_create(id);
@@ -85,7 +87,7 @@ impl ServerHandle {
     ///
     /// Soft delete: connected clients are not kicked, but their next
     /// broadcast or join will fail with a [`SyncError::RoomNotFound`].
-    #[inline(always)]
+    #[inline]
     pub fn delete_room(&self, id: &str) -> bool {
         let existed = self.rooms.delete(id);
         if existed {
@@ -135,24 +137,80 @@ impl ServerHandle {
         self.rooms.get(room_id).map(|r| r.all_channel_lens())
     }
 
-    /// Get a metadata value from a room.
-    pub fn get_room_meta(&self, room_id: &str, key: &str) -> Option<String> {
-        self.rooms.get(room_id)?.get_meta(key)
+    /// Store typed metadata on a room. Replaces any previous metadata.
+    /// Returns `false` if the room doesn't exist.
+    pub fn set_room_meta<T: Any + Send + Sync + 'static>(&self, room_id: &str, value: T) -> bool {
+        if let Some(room) = self.rooms.get(room_id) {
+            room.metadata.set(value);
+            true
+        } else {
+            false
+        }
     }
 
-    /// Set a metadata value on a room. Returns `false` if the room doesn't exist.
-    pub fn set_room_meta(&self, room_id: &str, key: &str, value: &str) -> bool {
-        if let Some(room) = self.rooms.get(room_id) {
-            room.set_meta(key, value);
+    /// Read room metadata via a callback.
+    ///
+    /// The callback receives `&T` if metadata is set and the type matches.
+    /// Returns `None` if the room doesn't exist or has no metadata of type `T`.
+    ///
+    /// This avoids needing `Clone` on your metadata type.
+    pub fn with_room_meta<T: Any + Send + Sync + 'static, R>(
+        &self,
+        room_id: &str,
+        f: impl FnOnce(&T) -> R,
+    ) -> Option<R> {
+        self.rooms.get(room_id)?.metadata.get(f)
+    }
+
+    /// Remove and return room metadata, downcasted to `T`.
+    /// Returns `None` if the room doesn't exist or has no metadata of type `T`.
+    pub fn take_room_meta<T: Any + Send + Sync + 'static>(&self, room_id: &str) -> Option<T> {
+        self.rooms.get(room_id)?.metadata.take()
+    }
+
+    /// Check if a room has metadata set.
+    pub fn room_has_meta(&self, room_id: &str) -> bool {
+        self.rooms.get(room_id).is_some_and(|r| r.metadata.is_set())
+    }
+
+    /// Store typed metadata on a connected client. Replaces any previous metadata.
+    /// Returns `false` if the client doesn't exist.
+    pub fn set_client_meta<T: Any + Send + Sync + 'static>(
+        &self,
+        client_id: &Uuid,
+        value: T,
+    ) -> bool {
+        if let Some(state) = self.clients.get(client_id) {
+            state.metadata.set(value);
             true
         } else {
             false
         }
     }
 
-    /// Get all metadata from a room as a HashMap. Returns `None` if room doesn't exist.
-    pub fn get_room_meta_all(&self, room_id: &str) -> Option<HashMap<String, String>> {
-        self.rooms.get(room_id).map(|r| r.get_all_meta())
+    /// Read client metadata via a callback.
+    ///
+    /// The callback receives `&T` if metadata is set and the type matches.
+    /// Returns `None` if the client doesn't exist or has no metadata of type `T`.
+    pub fn with_client_meta<T: Any + Send + Sync + 'static, R>(
+        &self,
+        client_id: &Uuid,
+        f: impl FnOnce(&T) -> R,
+    ) -> Option<R> {
+        self.clients.get(client_id)?.metadata.get(f)
+    }
+
+    /// Remove and return client metadata, downcasted to `T`.
+    /// Returns `None` if the client doesn't exist or has no metadata of type `T`.
+    pub fn take_client_meta<T: Any + Send + Sync + 'static>(&self, client_id: &Uuid) -> Option<T> {
+        self.clients.get(client_id)?.metadata.take()
+    }
+
+    /// Check if a client has metadata set.
+    pub fn client_has_meta(&self, client_id: &Uuid) -> bool {
+        self.clients
+            .get(client_id)
+            .is_some_and(|c| c.metadata.is_set())
     }
 
     /// Room a client is currently in. Returns `None` if not in a room or not connected.
@@ -358,6 +416,7 @@ impl Server {
             ClientState {
                 room_id: None,
                 addr,
+                metadata: Storage::new(),
             },
         );
 
@@ -540,7 +599,7 @@ impl Server {
         Ok(())
     }
 
-    #[inline]
+    #[inline(always)]
     async fn cleanup_client(self: &Arc<Self>, client_id: Uuid, room_id: &str) {
         let notify = ServerWire::PlayerLeft { client_id };
         if let Some(room) = self.rooms.get(room_id) {