Struct ServerHandle 

pub struct ServerHandle { /* private fields */ }

Handle to a running server.

Provides runtime control: shutdown, room management and state queries Rooms can be created and deleted at any time, new clients will see the updated room list, and existing clients in deleted rooms get errors on their next broadcast or join attempt.

Implementations

impl ServerHandle

pub async fn shutdown(&self)

Signal the server to stop accepting connections and disconnect all clients.

pub fn create_room(&self, id: &str) -> Result<()>

Create a room at runtime. Fails if the room already exists.

pub fn delete_room(&self, id: &str) -> bool

Delete a room at runtime. Returns true if the room existed.

Soft delete: connected clients are not kicked, but their next broadcast or join will fail with a SyncError::RoomNotFound.

pub fn room_exists(&self, id: &str) -> bool

Check if a room exists.

pub fn room_count(&self) -> usize

Number of active rooms.

pub fn get_room_ids(&self) -> Vec<String>

List all room IDs.

pub fn get_room_clients(&self, id: &str) -> Option<Vec<Uuid>>

Client IDs in a room. Returns None if the room doesn’t exist.

pub fn room_client_count(&self, id: &str) -> Option<usize>

Number of clients in a room. Returns None if the room doesn’t exist.

pub fn get_client_channel_len( &self, room_id: &str, client_id: &Uuid, ) -> Option<usize>

Get the write channel queue length for a specific client in a room.

Returns None if the room doesn’t exist or the client is not in it. Higher values indicate the client’s writer task is falling behind.

pub fn get_room_channel_lens(&self, room_id: &str) -> Option<Vec<(Uuid, usize)>>

Get all clients’ write channel queue lengths in a room.

Returns None if the room doesn’t exist. Each entry is (uuid, channel_len). Useful for monitoring backpressure.

pub fn set_room_meta<T: Any + Send + Sync + 'static>( &self, room_id: &str, value: T, ) -> bool

Store typed metadata on a room. Replaces any previous metadata. Returns false if the room doesn’t exist.

pub fn with_room_meta<T: Any + Send + Sync + 'static, R>( &self, room_id: &str, f: impl FnOnce(&T) -> R, ) -> Option<R>

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 take_room_meta<T: Any + Send + Sync + 'static>( &self, room_id: &str, ) -> Option<T>

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 room_has_meta(&self, room_id: &str) -> bool

Check if a room has metadata set.

pub fn set_client_meta<T: Any + Send + Sync + 'static>( &self, client_id: &Uuid, value: T, ) -> bool

Store typed metadata on a connected client. Replaces any previous metadata. Returns false if the client doesn’t exist.

pub fn with_client_meta<T: Any + Send + Sync + 'static, R>( &self, client_id: &Uuid, f: impl FnOnce(&T) -> R, ) -> Option<R>

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 take_client_meta<T: Any + Send + Sync + 'static>( &self, client_id: &Uuid, ) -> Option<T>

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 client_has_meta(&self, client_id: &Uuid) -> bool

Check if a client has metadata set.

pub fn get_client_room(&self, client_id: Uuid) -> Option<String>

Room a client is currently in. Returns None if not in a room or not connected.

pub fn get_client_addr(&self, client_id: Uuid) -> Option<SocketAddr>

Remote address of a connected client.

pub fn get_client_count(&self) -> usize

Total number of connected clients.

pub fn kick_client(&self, client_id: &Uuid) -> bool

Kick a client from their current room. Broadcasts PlayerLeft to other clients and calls the on_leave handler. The client connection will be closed by the server.