Introduction

rs-netty is a Tokio-native, Netty-inspired networking framework for Rust. It keeps the familiar Channel / Pipeline / Handler model, but rebuilds the main path around Rust’s type system, async/await, Tokio tasks, bounded channel queues, and ordinary owned messages.

The crate root enables #![deny(unsafe_code)]. The primary public entry points are:

• pipeline(): builds a TCP stream pipeline.
• datagram_pipeline(): builds a UDP datagram pipeline.
• TcpServer / TcpClient: run TCP servers and clients.
• UdpServer / UdpClient: run UDP servers and clients.
• Handler / DatagramHandler / Inbound / Business / Outbound: implement pipeline stages.
• Channel / DatagramChannel: write, flush, or close from outside the current handler.
• Life: optional lifecycle hooks.
• #[handler]: generates TCP and UDP final handler impls for simple handlers.

Minimal TCP Server

This is close to examples/tcp_echo_server.rs:

use rs_netty::{codec::LineCodec, handler, pipeline, Result, TcpServer};

#[tokio::main]
async fn main() -> Result<()> {
    TcpServer::bind("127.0.0.1:9000")
        .pipeline(|| {
            pipeline()
                .codec(LineCodec::new())
                .handler(Echo)
        })
        .run()
        .await
}

struct Echo;

#[handler(Echo)]
async fn echo(msg: String) -> Result<String> {
    Ok(msg)
}

LineCodec decodes the TCP byte stream into String values. Echo receives a String, and the macro-generated handler writes and flushes the returned String through the outbound side.

Minimal UDP Server

This is close to examples/udp_echo_server.rs:

use rs_netty::{codec::Utf8DatagramCodec, datagram_pipeline, handler, Result, UdpServer};

#[tokio::main]
async fn main() -> Result<()> {
    UdpServer::bind("127.0.0.1:9002")
        .pipeline(|| {
            datagram_pipeline()
                .codec(Utf8DatagramCodec)
                .handler(UdpEcho)
        })
        .run()
        .await
}

struct UdpEcho;

#[handler(UdpEcho)]
async fn udp_echo(msg: String) -> Result<String> {
    Ok(format!("echo: {msg}"))
}

UDP pipelines process complete datagrams. DatagramContext::write replies to the sender of the current datagram by default. Use write_to or write_to_and_flush to send to an explicit peer.

How To Read This Guide

If you want to use the framework, start with Typed Pipeline, TCP, UDP, Handlers, and Codecs. If you want to extend it, focus on Architecture, Lifecycle, Channel Write And Flush, Extension Guide, and API Map.