kcp_tokio/lib.rs
1//! # KCP Rust — High-Performance Async KCP
2//!
3//! A modern, async-first implementation of the KCP (Fast and Reliable ARQ Protocol)
4//! built on top of Tokio.
5//!
6//! ## Architecture
7//!
8//! ```text
9//! ┌───────────────────────────────────────┐
10//! │ kcp-tokio (this crate) │
11//! │ │
12//! │ KcpStream / KcpListener ← user API │
13//! │ actor ← scheduler │
14//! │ transport ← UDP I/O │
15//! ├───────────────────────────────────────┤
16//! │ kcp-core (dependency) │
17//! │ │
18//! │ KcpEngine ← pure sync state machine│
19//! │ protocol ← wire types & constants │
20//! └───────────────────────────────────────┘
21//! ```
22//!
23//! ## Quick Start
24//!
25//! ```rust,no_run
26//! use kcp_tokio::{KcpConfig, KcpStream};
27//! use std::net::SocketAddr;
28//!
29//! #[tokio::main]
30//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
31//! let addr: SocketAddr = "127.0.0.1:8080".parse()?;
32//! let config = KcpConfig::new().fast_mode();
33//! let mut stream = KcpStream::connect(addr, config).await?;
34//!
35//! use tokio::io::AsyncWriteExt;
36//! stream.write_all(b"Hello, KCP!").await?;
37//!
38//! use tokio::io::AsyncReadExt;
39//! let mut buffer = [0u8; 1024];
40//! let n = stream.read(&mut buffer).await?;
41//! println!("Received: {:?}", &buffer[..n]);
42//!
43//! Ok(())
44//! }
45//! ```
46
47// ── Layer 1: Core protocol (re-exported from kcp-core) ─────────────────
48
49/// Core protocol types, constants, and wire format.
50pub use kcp_core::protocol;
51
52/// Direct access to the standalone `kcp-core` crate.
53pub use kcp_core;
54
55// ── Layer 2: Transport & runtime infrastructure ─────────────────────────
56
57pub mod transport;
58pub use transport::{Addr, Transport};
59#[cfg(feature = "tokio")]
60pub use transport::UdpTransport;
61
62// ── Layer 3: Configuration & errors (extends core with I/O concerns) ────
63
64pub mod config;
65pub mod error;
66pub use config::KcpConfig;
67pub use error::{KcpError, Result};
68
69// ── Layer 4: Async KCP (actor + stream + listener) ──────────────────────
70
71#[cfg(feature = "tokio")]
72pub mod engine;
73#[cfg(feature = "tokio")]
74pub(crate) mod actor;
75#[cfg(feature = "tokio")]
76pub mod stream;
77#[cfg(feature = "tokio")]
78pub mod listener;
79
80#[cfg(feature = "tokio")]
81pub use stream::KcpStream;
82#[cfg(feature = "tokio")]
83pub use listener::KcpListener;
84
85// ── Internal convenience re-exports ─────────────────────────────────────
86
87pub(crate) mod common;
88
89// ── Version info ────────────────────────────────────────────────────────
90
91pub const VERSION: &str = env!("CARGO_PKG_VERSION");
92pub const PROTOCOL_VERSION: u32 = 1;
93
94#[cfg(test)]
95mod tests {
96 use super::*;
97
98 #[test]
99 fn test_version() {
100 assert!(!VERSION.is_empty());
101 assert_eq!(PROTOCOL_VERSION, 1);
102 }
103}