Ibrahim TCP

Ibrahim TCP is a lightweight, high-performance TCP protocol library written in pure Rust.
It provides a reliable, fault-tolerant transport with compression, retries, and acknowledgements — perfect for real-time systems like multiplayer games, telemetry, or distributed nodes.

✨ Features

• 🔁 Reliable messaging over TCP with ACK/NACK retry system
• ⚙️ Automatic reconnection and resend of unacknowledged packets
• ⚡ LZ4 compression for high throughput
• 🧩 Text-based protocol — human-readable, no JSON overhead
• 🧱 Async & efficient (Tokio runtime)
• 🔒 Fault-tolerant: handles disconnects, lag, and large payloads
• 💡 Easy integration — plug it into your app or server backend

You can use it to:

power multiplayer game servers

handle state replication between distributed nodes

manage low-latency telemetry for clients (mobile, PC, console)

🧩 Architecture

typical Ibrahim system has three layers:

Client (Game) ⇄ Ibrahim Gateway Server ⇄ Shard / Zone Servers ↑ Matchmaking / State Service

Each client connects via TCP to a Gateway Server.

The Gateway broadcasts game events (ticks, health, bullets, etc.).

Each Zone Server syncs world state with other nodes via the same protocol.

All communications use Packet (compressed + reliable). *

🧠 Architecture

Each client sends packets with a unique id.

The server broadcasts messages to all clients.

Each packet is compressed and tracked.

Missing ACKs trigger automatic retransmission.

Compression = LZ4 (fastest ratio for real-time text data).

🧰 License

GPLv3 © Muhammad Yasir Gujjar Use it freely for open-source, educational, or commercial projects.

Usage

📦 Import

[dependencies] ibrahim-protocol = "1.0" tokio = { version = "1", features = ["full"] }

🖥 Example 1: Game Server (single instance)

use ibrahim_tcp::{Packet, Server};
use tokio::{time::{sleep, Duration}};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let server = Server::new("0.0.0.0:4000").await?;
    println!("[GameServer] Listening on 0.0.0.0:4000");

    let mut tick = 0;
    loop {
        // simulate world tick update
        let pkt = Packet::new(tick, format!("world_tick={} player_updates=42", tick), true);
        server.broadcast(&pkt).await;
        tick += 1;
        sleep(Duration::from_millis(50)).await; // ~20 ticks/sec
    }
}

🎮 Example 2: Game Client

use ibrahim_tcp::Client;
use std::env;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let args: Vec<String> = env::args().collect();
    let name = args.get(1).cloned().unwrap_or("Player".into());
    let client = Client::new("127.0.0.1:4000");
    client.run(&name).await
}

⚙️ Example 3: Distributed Zone System

Imagine multiple “zones” (maps) in your game:

zone-1 runs on 127.0.0.1:4000

zone-2 runs on 127.0.0.1:4001

Each zone can send replicated updates to others.

use ibrahim_tcp::{Packet, Client, Server};
use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() -> std::io::Result<()> {
    // zone-1 server
    let server = Server::new("127.0.0.1:4000").await?;
    // zone-2 client connects to zone-1
    let client = Client::new("127.0.0.1:4000");

    tokio::spawn(async move {
        client.run("zone-2").await.unwrap();
    });

    println!("[Zone-1] Syncing with Zone-2...");
    let mut tick = 0u64;
    loop {
        let pkt = Packet::new(tick, format!("sync_state: zone=1 tick={}", tick), true);
        server.broadcast(&pkt).await;
        tick += 1;
        sleep(Duration::from_millis(100)).await;
    }
}

You’ll see:

[Zone-1] Syncing with Zone-2... [zone-2] recv: sync_state: zone=1 tick=10

That’s a distributed zone replication — perfect for large multiplayer backends.

🔁 Example 4: Reliable Messages (ACK + retry)

If a client doesn’t acknowledge a message within 3s, ibrahim-tcp automatically resends it.

You can confirm ACKs via logs (just enable debug!() logs in your code):

let pkt = Packet::new(1001, "fire bullet id=392".into(), true);
client.send(pkt).await?; // handled via retry system

You can trust delivery even during lag or packet loss.

🧠 Integrating with Your Game Engine

For an FPS or RTS: Data Type Recommended Channel Notes Player input Packet::new(..., compressed=false) No need to compress small control packets Entity state Compressed, reliable packets Auto retries ensure sync Chat / Text Compressed packets Human-readable Heartbeat / Ping Lightweight text packet For latency display

Example heartbeat:

let ping = Packet::new(999, "ping".to_string(), false);
server.broadcast(&ping).await;

🏗 Scaling Up

For massive multiplayer:

Deploy multiple Server instances (zones).

Use Redis or NATS to distribute updates between servers.

Each client connects to its nearest zone.

Ibrahim ensures ordered, compressed, reliable state across them. ' [Client] -- TCP --> [Zone Server] -- TCP --> [Global State Sync] ' 🧪 Testing Locally

Start the main server

cargo run --example server

Start multiple clients

cargo run --example client Yasir

cargo run --example client Bob

Observe real-time tick updates from the server.

Optional: connect with telnet or curl to test low-level protocol:

telnet 127.0.0.1 4000

You’ll see binary/text framed messages (compressed).

. [nasir] connected . [nasir] recv: health=90 . [nasir] recv: health=70 . [nasir] recv: health=60 . [nasir] recv: health=14 . [nasir] recv: revive=+15 . [nasir] recv: ammo=2

💡 Example Distributed Layout (for docs)

       ┌──────────────┐
       │ Master Server│
       └──────┬───────┘
              │
  ┌───────────┴───────────┐
  │                       │
┌─▼──────────┐     ┌──────▼────────┐
│ Zone A     │     │ Zone B        │
│ (Europe)   │     │ (America)     │
└─────┬──────┘     └──────┬───────┘
      │                   │
   Clients A           Clients B

Each line is an ibrahim-tcp connection. Packets are compressed, ordered, and retried automatically.

This crate compiles cleanly on Rust 1.80+, no warnings, fully async.
To verify:

cargo check