kcp-io 0.0.5

A Rust wrapper for the KCP protocol — FFI bindings, safe API, and async tokio integration
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

//! KCP protocol configuration parameters and presets.
//!
//! This module defines [`KcpConfig`], which controls the behavior of the KCP
//! protocol engine including nodelay mode, update interval, retransmission
//! strategy, window sizes, MTU, and stream mode.

/// KCP protocol configuration parameters.
///
/// Controls the behavior of the underlying KCP engine. Use the provided presets
/// ([`default()`](KcpConfig::default), [`fast()`](KcpConfig::fast),
/// [`normal()`](KcpConfig::normal)) or customize individual fields.
///
/// # Example
///
/// ```
/// use kcp_io::core::KcpConfig;
///
/// // Use a preset
/// let config = KcpConfig::fast();
///
/// // Customize from a preset
/// let config = KcpConfig {
///     mtu: 1200,
///     snd_wnd: 256,
///     rcv_wnd: 256,
///     ..KcpConfig::fast()
/// };
/// ```
#[derive(Debug, Clone)]
pub struct KcpConfig {
    /// Enable nodelay mode. When `true`, KCP disables the wait-to-send delay
    /// and sends packets as soon as possible, reducing latency.
    pub nodelay: bool,
    /// Internal update interval in milliseconds. Lower values reduce latency
    /// but increase CPU usage. Typical range: 10–100 ms.
    pub interval: u32,
    /// Fast retransmit trigger count. When an out-of-order ACK is received
    /// this many times, KCP immediately retransmits the packet without waiting
    /// for a timeout. Set to 0 to disable fast retransmit.
    pub resend: i32,
    /// Disable congestion control. When `true`, KCP ignores the congestion
    /// window and sends at full speed (uses `nocwnd` mode). Useful for
    /// low-latency scenarios where bandwidth is not a concern.
    pub nc: bool,
    /// Maximum Transmission Unit in bytes. This is the maximum size of a single
    /// KCP output packet (including the 24-byte KCP header). Must account for
    /// UDP header overhead (28 bytes for IPv4). Default: 1400.
    pub mtu: u32,
    /// Send window size (number of packets). Larger values allow higher
    /// throughput but consume more memory. Default: 32.
    pub snd_wnd: u32,
    /// Receive window size (number of packets). Should generally be >= `snd_wnd`.
    /// Larger values allow higher throughput. Default: 128.
    pub rcv_wnd: u32,
    /// Enable stream mode. When `true`, KCP operates like a byte stream (similar
    /// to TCP), merging small packets and splitting large ones. When `false`
    /// (default), KCP preserves message boundaries.
    pub stream_mode: bool,
}

impl Default for KcpConfig {
    /// Returns a conservative default configuration.
    ///
    /// - nodelay: `false`
    /// - interval: `100` ms
    /// - resend: `0` (no fast retransmit)
    /// - nc: `false` (congestion control enabled)
    /// - mtu: `1400`
    /// - snd_wnd: `32`, rcv_wnd: `128`
    /// - stream_mode: `false`
    fn default() -> Self {
        Self {
            nodelay: false,
            interval: 100,
            resend: 0,
            nc: false,
            mtu: 1400,
            snd_wnd: 32,
            rcv_wnd: 128,
            stream_mode: false,
        }
    }
}

impl KcpConfig {
    /// Returns a low-latency (fast) configuration preset.
    ///
    /// Optimized for minimal latency at the cost of higher bandwidth usage.
    ///
    /// - nodelay: `true`
    /// - interval: `10` ms
    /// - resend: `2` (fast retransmit after 2 out-of-order ACKs)
    /// - nc: `true` (congestion control disabled)
    /// - mtu: `1400`
    /// - snd_wnd: `128`, rcv_wnd: `128`
    /// - stream_mode: `false`
    pub fn fast() -> Self {
        Self {
            nodelay: true,
            interval: 10,
            resend: 2,
            nc: true,
            mtu: 1400,
            snd_wnd: 128,
            rcv_wnd: 128,
            stream_mode: false,
        }
    }

    /// Returns a balanced (normal) configuration preset.
    ///
    /// Balances latency and bandwidth usage. Good for most use cases.
    ///
    /// - nodelay: `true`
    /// - interval: `40` ms
    /// - resend: `2`
    /// - nc: `false` (congestion control enabled)
    /// - mtu: `1400`
    /// - snd_wnd: `64`, rcv_wnd: `128`
    /// - stream_mode: `false`
    pub fn normal() -> Self {
        Self {
            nodelay: true,
            interval: 40,
            resend: 2,
            nc: false,
            mtu: 1400,
            snd_wnd: 64,
            rcv_wnd: 128,
            stream_mode: false,
        }
    }
}