# 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:
```bash
cargo check
```