raknet-rust 0.2.0

Asynchronous, high-performance RakNet transport library for Rust.
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# raknet-rust

[![Rust](https://img.shields.io/badge/Rust-2024_edition-000000?logo=rust)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![Status](https://img.shields.io/badge/Status-Stable-brightgreen)](#)
[![Platform](https://img.shields.io/badge/Platform-%20RakNet-2ea44f)](#)

`raknet-rust` is a RakNet transport library written in Rust.

It is built for modern async server/client networking and is especially useful for
Minecraft Bedrock Edition projects (servers, proxies, and tooling), while still remaining
usable as a general RakNet library.

## Getting Started

### Installation

With `cargo add`:

```bash
cargo add raknet-rust
```

Or edit `Cargo.toml` directly:

```toml
[dependencies]
raknet-rust = "0.2.0"
```

## API Surface

- Stable application API lives under `client`, `server`, `listener`, `connection` and root re-exports.
- Advanced low-level API is namespaced under `raknet_rust::low_level::{protocol, session, transport}`.

### Usage

Basic server:

```rust
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use raknet_rust::server::{RaknetServer, RaknetServerEvent};

#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
    let bind = SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 19132);
    let mut server = RaknetServer::bind(bind).await?;

    while let Some(event) = server.next_event().await {
        if let RaknetServerEvent::Packet { peer_id, payload, .. } = event {
            server.send(peer_id, payload).await?;
        }
    }

    Ok(())
}
```

Basic client:

```rust
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use raknet_rust::client::{RaknetClient, RaknetClientEvent};

#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
    let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 19132);
    let mut client = RaknetClient::connect(addr).await?;

    while let Some(event) = client.next_event().await {
        match event {
            RaknetClientEvent::Connected { .. } => client.send(b"\xfehello").await?,
            RaknetClientEvent::Packet { .. } => break,
            RaknetClientEvent::Disconnected { .. } => break,
            _ => {}
        }
    }

    Ok(())
}
```

Callback facade (`on_connect / on_packet / on_disconnect`):

```rust
use std::pin::Pin;
use std::future::Future;
use raknet_rust::server::RaknetServer;

fn hook_ok<'a>() -> Pin<Box<dyn Future<Output = std::io::Result<()>> + Send + 'a>> {
    Box::pin(async { Ok(()) })
}

#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
    let mut server = RaknetServer::bind("0.0.0.0:19132".parse().unwrap()).await?;
    let mut facade = server
        .facade()
        .on_connect(|_server, _event| hook_ok())
        .on_packet(|server, event| Box::pin(async move {
            server.send(event.peer_id, event.payload).await?;
            Ok(())
        }))
        .on_disconnect(|_server, _event| hook_ok());

    facade.run().await
}
```

Listener incoming helper:

```rust
use std::net::SocketAddr;
use raknet_rust::Listener;

#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
    let bind: SocketAddr = "0.0.0.0:19132".parse().unwrap();
    let mut listener = Listener::bind(bind).await?;
    listener.start().await?;

    let mut incoming = listener.incoming()?;
    while let Some(conn) = incoming.next().await {
        let meta = conn.metadata();
        println!("accepted peer={} addr={}", meta.id().as_u64(), meta.remote_addr());
    }

    Ok(())
}
```

## Observability

- The runtime emits `tracing` events (connect, disconnect, decode error, handshake reject/timeout).
- To collect logs in your application, configure a subscriber (for example, `tracing-subscriber`).
- For Prometheus format export, use `telemetry::TelemetryExporter`:
  - `exporter.ingest_server_event(&event)`
  - `let body = exporter.render_prometheus()`

## License

Apache-2.0. See [LICENSE](LICENSE) for details.