rs-netty 1.1.0

A Tokio-native typed TCP/UDP pipeline framework inspired by Netty.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# 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`:

```rust
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`:

```rust
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`.