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
77
78
79
80
81
82
83
84
85
86

# UDP

UDP uses datagram pipelines. The model is similar to TCP, but the boundary is a complete datagram rather than a byte stream.

## Server

`UdpServer::bind(addr)` creates a socket server builder. `.pipeline(|| ...)` sets the socket-level pipeline factory:

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

struct UdpEcho;

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

let server = UdpServer::bind("127.0.0.1:0")
    .pipeline(|| {
        datagram_pipeline()
            .codec(Utf8DatagramCodec)
            .handler(UdpEcho)
    })
    .start()
    .await?;

server.shutdown();
server.wait().await?;
# Ok::<(), rs_netty::Error>(())
```

`UdpServerHandle` exposes `local_addr()`, `shutdown()`, and `wait()`.

## Client

`UdpClient::connect(remote_addr)` binds to `"0.0.0.0:0"` by default. Use `.bind(local_addr)` to choose a local address. `UdpClientHandle<W>` provides these methods for the default remote peer:

- `write(msg)`
- `flush()`
- `write_and_flush(msg)`

It also supports explicit peers:

- `write_to(peer_addr, msg)`
- `write_to_and_flush(peer_addr, msg)`

## Socket-Level Pipeline

A UDP server currently creates one socket-level pipeline, not a child pipeline per peer. For every datagram, the runtime creates new `DatagramInfo`, `InboundContext`, `BusinessContext`, `DatagramContext`, and `OutboundContext` values. `peer_addr()` is the sender of the current datagram.

If the application needs per-peer state, store it in the handler yourself:

```rust
use std::{collections::HashMap, net::SocketAddr};

struct PeerState;

struct StatefulUdp {
    peers: HashMap<SocketAddr, PeerState>,
}
```

## Configuration

UDP uses `UdpSocketConfig`:

- `read_buffer_capacity`: default 64 KiB; normalized to at least `max_datagram_size`.
- `write_buffer_capacity`: default 8 KiB.
- `max_datagram_size`: default 64 KiB.
- `outbound_queue_size`: default 1024.

Builder methods include:

- `read_buffer_capacity(value)`
- `write_buffer_capacity(value)`
- `max_datagram_size(value)`
- `outbound_queue_size(value)`

UDP currently has no TCP-style `tcp_nodelay`, connection stats, or idle timeout.

## Datagram Write Semantics

`DatagramContext::write(msg)` writes to the current datagram peer. `write_to(peer, msg)` writes to an explicit peer. Both only stage data in the handler-local outbox. `flush` or `*_and_flush` sends pending datagrams through `send_to`.

A UDP flush acknowledgement only means the local `send_to` call completed. It does not mean the peer received the datagram, and UDP still provides no ordering, retransmission, or reliability guarantee.