English | 简体中文

Lynn_tcp is a lightweight, high-performance asynchronous TCP framework built on Tokio.

It adopts a DDD (Domain-Driven Design) + Onion Architecture, separating core domain logic from infrastructure concerns for better maintainability and extensibility.

Keywords

• Lightweight: Concise code that is easy to learn and use
• Concurrent & Performance: Built on Tokio's excellent async runtime for high-concurrency multi-user connections
• Low Latency: Read-write separation design for minimal latency
• Security: Strong typing and memory safety guarantees of Rust
• Production Ready: Prometheus metrics, connection limiting, rate limiting, and heartbeat management built-in

Tips: Lynn_tcp is designed for message forwarding and long-lived TCP game servers.

Quickly develop business scenarios with the framework — customize message parsing, encryption, routing, and more.

Architecture

Lynn_tcp v2.0 is organized into three clean layers following the Onion Architecture pattern:

┌─────────────────────────────────────┐
│         Interface Layer             │  ← Public API (no breaking changes)
│   (lynn_server / lynn_client / ...) │
├─────────────────────────────────────┤
│         Application Layer           │  ← Orchestration: server/client startup
│   (LynnServer / LynnClient)         │
├─────────────────────────────────────┤
│          Domain Layer               │  ← Pure business logic
│   (Router / Handler / Model)        │
├─────────────────────────────────────┤
│       Infrastructure Layer          │  ← Concrete implementations
│   (TCP / Metrics / Validation)      │
└─────────────────────────────────────┘

Quick Start

Dependencies

Add to your Cargo.toml:

Full features (recommended):

[dependencies]
lynn_tcp = "2"
tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] }
tracing-subscriber = "0.3"

Server only:

[dependencies]
lynn_tcp = { version = "2", features = ["server"] }
tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] }
tracing-subscriber = "0.3"

Client only:

[dependencies]
lynn_tcp = { version = "2", features = ["client"] }
tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] }
tracing-subscriber = "0.3"

Minimal Server

use lynn_tcp::{lynn_server::*, lynn_tcp_dependents::*};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    let _ = LynnServer::new()
        .await
        .add_router(1, ping_handler)
        .add_router(2, echo_handler)
        .add_router(3, broadcast_handler)
        .start()
        .await;

    Ok(())
}

pub async fn ping_handler() -> HandlerResult {
    println!("📡 Ping received");
    HandlerResult::new_without_send()
}

pub async fn echo_handler(input_buf_vo: InputBufVO) -> HandlerResult {
    let addr = input_buf_vo.get_input_addr().unwrap();
    println!("📨 Echo from: {}", addr);
    HandlerResult::new_without_send()
}

pub async fn broadcast_handler(clients_context: ClientsContext) -> HandlerResult {
    let addrs = clients_context.get_all_clients_addrs().await;
    HandlerResult::new_with_send(3, "hello everyone!".into(), addrs)
}

Server with Custom Config

use lynn_tcp::{lynn_server::*, lynn_tcp_dependents::*};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    let config = LynnServerConfigBuilder::new()
        .with_addr("0.0.0.0:9876")?
        .with_server_max_connections(Some(&500))
        .with_server_max_taskpool_size(&256)
        .with_tcp_nodelay(&true)
        .with_tcp_keepalive_enabled(&true)
        .with_tcp_keepalive_time_secs(&120)
        .build();

    let _ = LynnServer::new_with_config(config)
        .await
        .add_router(1, my_handler)
        .start()
        .await;

    Ok(())
}

pub async fn my_handler() -> HandlerResult {
    HandlerResult::new_without_send()
}

Minimal Client

use lynn_tcp::{
    lynn_client::LynnClient,
    lynn_tcp_dependents::*,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    let mut client = LynnClient::new_with_addr("127.0.0.1:9177")
            .await
            .start()
            .await;

    // Send a message
    client.send_data(
        HandlerResult::new_with_send_to_server(1, "hello".into())
    ).await?;

    // Receive response
    if let Some(response) = client.get_receive_data().await {
        println!("Received: {:?}", response.get_all_bytes());
    }

    Ok(())
}

Examples

All examples are located in the examples/ directory. Run them with:

The echo_server_client and multi_route_service examples are the best starting points for understanding Client ↔ Server communication.

Features

Note: metrics is automatically enabled when server is selected. To use it independently: features = ["metrics"].

Available Configuration (LynnServerConfigBuilder)

Road Map

✅ Core Features (v1.0.0+)

• ✅ TCP Server with multi-route async handler dispatch
• ✅ TCP Client with message send/receive
• ✅ Custom message header/tail marks
• ✅ Automatic client heartbeat & cleanup
• ✅ Asynchronous task routing service
• ✅ Prometheus + Grafana monitoring (v1.2.5)
• ✅ DDD + Onion Architecture refactoring (v2.0.0)
• ✅ 7 runnable examples covering all scenarios

🔜 Planned

Flow Chart

Release Notes

See version.md for full version history.

Test Results

Platform: Debian 12.12 (4H4G) — 2025.10.21

• model-1: one request by one response
• model-2: concurrent send request and recv response
• total time: 15s

lynn_tcp v1.1.x

lynn_tcp v1.2.x

📊 Benchmarks for v2.0.0 are forthcoming. The architectural refactoring focuses on maintainability with no expected performance regression.

FAQ

Q: Is v2.0.0 backward compatible with v1.x?

A: Yes. All public API signatures remain unchanged. You only need to update the version in Cargo.toml: lynn_tcp = "2".

Q: Do I need to change my code after upgrading?

A: No. The refactoring was purely structural — no behavior was modified. Your existing code will compile and run as before.

Q: Why jump from v1.2.x to v2.0.0?

A: The DDD + Onion Architecture restructuring represents a significant architectural improvement. The major version bump reflects this depth of change, even though the public API is fully compatible.

Q: How do I run the examples?

A: See the Examples section above. Each example can be run with cargo run --example <name>.

Q: How do I enable metrics?

A: Metrics are automatically enabled with the server feature. To run the metrics example: cargo run --example metrics_example --features metrics. See METRICS.md for detailed documentation.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Lynn_tcp by you shall be licensed as MIT, without any additional terms or conditions.