Crate ghost_sync

Crate ghost_sync 

Source
Expand description

§ghost-sync GitHub

A composable Tokio TCP relay for room-based multiplayer messaging.

ghost-sync provides a lightweight, backpressure-aware server and an asynchronous client for building real-time multiplayer applications where state sync is managed explicitly via rooms.

§Features

  • Room Management: Clients join isolated rooms. All messages within a room are broadcast to all connected peers.
  • Efficient Broadcasts: Messages are serialized exactly once per room and zero-copy shared among all recipients.
  • Backpressure: Prevents slow clients from consuming unbounded server memory via drop-on-full semantics. Hook into backpressure events via ServerHandler::on_backpressure.
  • Custom Handlers: Inject your own application logic using the ServerHandler trait (e.g., on_connect, on_join, on_leave, on_broadcast).

§Quick Examples

§Server

use ghost_sync::{Server, NoopHandler};

#[tokio::main]
async fn main() {
    let server = Server::builder()
        .bind("127.0.0.1:8080")
        .handler(NoopHandler)
        .build();

    // Creates a background task running the server
    let handle = server.run().await.unwrap();

    // Keep the server alive
    std::future::pending::<()>().await;
}

§Client

use ghost_sync::{Client, ServerEvent};

#[tokio::main]
async fn main() {
    let mut client = Client::connect("127.0.0.1:8080").await.unwrap();

    // Join a room to start receiving and sending broadcasts
    client.join("test-room", None).await.unwrap();

    while let Ok(Some(event)) = client.recv().await {
        match event {
            ServerEvent::Joined { client_id, room_id } => println!("Joined room: {}", room_id),
            ServerEvent::Broadcast { sender_id, data } => {
                println!("Received broadcast: {:?}", data);
            },
            _ => {}
        }
    }
}

Re-exports§

pub use log::*;

Modules§

log

Macros§

debug
error
info
trace
warn

Structs§

Client
A connected relay client.
ClientBuilder
Builder for configuring a Client.
NoopHandler
Default no-op handler. Accepts all connections, ignores all events.
Server
A broadcast relay game server.
ServerBuilder
Builder for configuring a Server.
ServerConfig
Server configuration.
ServerHandle
Handle to a running server.
Uuid
A Universally Unique Identifier (UUID).

Enums§

ServerEvent
Client-facing event (clean API over [ServerWire]) Events the client receives from the server.
SyncError
Errors that can occur during client-server communication and protocol handling.

Traits§

ServerHandler
Optional hook trait for server lifecycle events. All methods have no-op defaults — implement only what you need.

Type Aliases§

Result