kcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7bf16edd731053438f070b9bd3c31917fc51a6c0c33b38f650fbc81b5fc2f8db
+  data.tar.gz: 7b04f35a6eca243cde48a7e8c7b1fa1818a93c50a5a9fb39df1f39ed51299f3c
+SHA512:
+  metadata.gz: 16e4a8fafb2265f223b54fd3ad7d89b9d15ac4fbbc33793606164e6ec1b04f478f5db203b1b703a244067abfe380422d35c0d7ece1ff04d4c269f44be47e6880
+  data.tar.gz: fae9a45f110c3e0cbc9ccd4f364bcf71595c4e626bfc00921de7915343030d2ab830759a8d0871b3e1a6e429103d3f0755e679cdcd21cd1e7d7ab124eae3138c

data/README.en.md

@@ -0,0 +1,235 @@
+# kcp
+
+[简体中文](README.md) | English
+
+Ruby bindings for [KCP](https://github.com/skywind3000/kcp) (A Fast and Reliable ARQ Protocol),
+provided as a **native C extension**. KCP is a fast, reliable transport protocol (ARQ) written in C,
+offering lower latency and better real-time behaviour than TCP over lossy / weak networks.
+
+## Features
+
+- **Native C extension**: compiles the KCP C source (skywind3000/kcp) directly, with C-level performance
+- **Cross-platform**: built via `mkmf` and the Ruby toolchain — **x86_64 / arm64**, **macOS / Linux / Windows**
+- **Byte-stream mode** (`stream = 1`): data delivered as an ordered byte stream, no message framing
+- **Pull-model API**: the engine does not touch sockets; you send/receive UDP datagrams yourself via `output`/`input`
+- Zero runtime dependencies (Ruby >= 3.0 only)
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'kcp'
+```
+
+```bash
+gem install kcp
+```
+
+The C sources under `ext/kcp` (`ikcp.c` + `kcp_native.c`) are compiled automatically at install time;
+Ruby's `mkmf` picks the right compiler and architecture (MSVC/MinGW on Windows, clang/gcc on macOS/Linux,
+arm/x64 matched automatically).
+
+## Quick start
+
+The KCP engine only guarantees "reliably deliver a byte stream to the peer". It does **not** handle
+sockets, addressing, or encryption. Create one engine per endpoint and feed each other UDP datagrams:
+
+```ruby
+require 'kcp'
+
+CONV = 0x1122_3344  # session id, must match on both ends
+
+# ---- sender ----
+engine = Kcp::Engine.new(CONV)
+
+engine.send("hello kcp")       # queue data
+engine.flush                   # flush immediately
+
+# pull encoded KCP packets and hand them to UDP sendto
+while (pkt = engine.output)
+  udp_socket.send(pkt, 0, peer_host, peer_port)
+end
+
+# ---- receiver (after receiving a UDP datagram) ----
+engine.input(recv_datagram)    # feed the received packet
+
+# pull the ordered, delivered byte stream
+data = engine.recv             # => "hello kcp" (nil when no data)
+
+# drive the clock periodically (retransmit / window update / keepalive)
+engine.update(Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000)
+```
+
+## API
+
+### `Kcp::Engine.new(conv)`
+
+Create an engine. `conv` is a 32-bit session id (`uint32`); **both ends of a connection must use the
+same `conv`**. Use a different `conv` per concurrent connection.
+
+```ruby
+engine = Kcp::Engine.new(0x1234)
+```
+
+### `send(data)`
+
+Queue data for reliable delivery. Returns the number of bytes queued, or a negative value on error.
+**Data is not sent immediately** — call `flush` (immediate) or `update` (interval) to produce packets.
+
+```ruby
+engine.send("some bytes")
+```
+
+### `flush`
+
+Flush the send queue into encoded packets immediately (not throttled by `update`'s interval).
+Use `output` afterwards to pull them.
+
+```ruby
+engine.send(data)
+engine.flush
+pkt = engine.output
+```
+
+### `output`
+
+Pull pending encoded packets (a concatenated byte segment, ready for UDP `send`). Returns `nil` when
+there is nothing to send. **The pulled bytes must be sent verbatim to the peer**, which feeds them
+back via `input`.
+
+```ruby
+while (pkt = engine.output)
+  socket.send(pkt, 0, host, port)
+end
+```
+
+### `input(data)`
+
+Feed one received encoded packet (the contents of a low-level UDP datagram). KCP parses it and handles
+ACKs / retransmits / data; afterwards use `recv` to read data and `output` to pull packets to send back
+(e.g. ACKs).
+
+```ruby
+socket.recvfrom(65_536) do |data, addr|
+  engine.input(data)
+end
+```
+
+### `recv(maxlen = 65536)`
+
+Pull up to `maxlen` bytes of the peer's delivered, **ordered** byte stream. Returns `nil` when there is
+no data.
+
+```ruby
+if (chunk = engine.recv)
+  # handle the received data
+end
+```
+
+### `update(now_ms)`
+
+Drive the KCP clock: interval-based retransmit, ACK, window probing. `now_ms` is a **monotonic
+millisecond timestamp** (use `Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000`).
+
+Call it periodically in the main loop, e.g. every 10–100ms:
+
+```ruby
+loop do
+  engine.update((Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i)
+  sleep 0.01
+end
+```
+
+### `close`
+
+Drop the reference to the C object (the underlying C memory is reclaimed by the Ruby GC via
+`TypedData_Wrap_Struct`).
+
+```ruby
+engine.close
+```
+
+## About `update` and `now_ms`
+
+KCP has **no internal timer** and never reads the system clock itself. You must feed it the current
+time (`now_ms`) periodically so it can drive all time-related logic:
+
+- **Timeout retransmit**: each sent segment carries a `resendts` (next resend time); it is only resent
+  once `current` advances past it
+- **RTT measurement**: uses `current - segment.ts` to compute round-trip time, and from it the RTO
+- **Window probing**: sends WINS probes periodically when the peer's window is zero
+- **Dead-link detection**: declares the link dead after a timeout with no response
+
+`now_ms` must be a **monotonic millisecond timestamp** (`Process.clock_gettime(Process::CLOCK_MONOTONIC)`),
+because the monotonic clock only moves forward and is unaffected by system-time jumps (NTP sync, manual
+changes). It is a 32-bit millisecond value that wraps every ~49 days; KCP handles the wraparound with a
+signed difference internally, which is expected.
+
+### What happens if you don't `update`?
+
+1. The first line of `ikcp_flush` is `if (kcp->updated == 0) return;` — and `updated` is only set by
+   `update`, so without `update` nothing can even be sent (this gem's `flush` calls `update` once as a
+   fallback, so `send + flush` alone still works).
+2. Even if you bypass that, **retransmit relies on `current` advancing**: after a packet is lost, if you
+   don't `update`, `resendts` is never reached, so that single loss stalls the connection forever; ACKs
+   are also not flushed on interval, the peer's window never advances, and both directions freeze.
+
+Bottom line: **`update` is KCP's heartbeat**. `send + flush` is "send immediately" (low latency);
+`update` is "periodic drive" (retransmit / ACK / window / keepalive). Call it every 10–100ms — without
+it, a single packet loss kills the connection.
+
+## Full example (UDP echo)
+
+The `examples/` directory ships runnable server and client:
+
+```bash
+ruby -I lib examples/server.rb 9000              # terminal 1: start the server
+ruby -I lib examples/client.rb 127.0.0.1 9000    # terminal 2: type a line to echo, /quit to exit
+```
+
+The full code follows:
+
+```ruby
+require 'socket'
+require 'kcp'
+
+CONV = 0x1234
+
+def now_ms
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+end
+
+# ---- server ----
+server = UDPSocket.new
+server.bind('0.0.0.0', 9000)
+engine = Kcp::Engine.new(CONV)
+
+loop do
+  data, addr = server.recvfrom(65_536)
+  engine.input(data)
+
+  while (chunk = engine.recv)
+    engine.send(chunk)  # echo
+  end
+  engine.flush
+  while (pkt = engine.output)
+    server.send(pkt, 0, addr[3], addr[1])
+  end
+  engine.update(now_ms)
+end
+```
+
+## Notes
+
+1. **KCP only does reliable transport**; socket I/O, peer-address management, encryption and session
+   keepalive are up to the caller (the `mnet` gem in this repo builds a roaming transport layer that
+   survives IP changes on top of it).
+2. `conv` must match on both ends; use a different `conv` per concurrent connection.
+3. `flush` is immediate (low latency); `update` is interval-throttled (saves CPU). Use both for
+   interactive workloads.
+4. KCP uses a 32-bit millisecond timestamp that wraps every ~49 days; this is expected (the protocol
+   handles the wraparound).
+
+## License
+
+MIT. KCP source copyright skywind3000.

data/README.md

@@ -0,0 +1,221 @@
+# kcp
+
+[English](README.en.md) | 简体中文
+
+[KCP](https://github.com/skywind3000/kcp)（A Fast and Reliable ARQ Protocol）的 Ruby 绑定，
+以**原生 C 扩展**形式提供。KCP 是一个用 C 实现的快速可靠传输协议（ARQ），
+相比 TCP 在丢包/弱网场景下有更低的延迟和更好的实时性。
+
+## 特性
+
+- **原生 C 扩展**：直接编译 skywind3000/kcp 的 C 源码，性能与 C 一致
+- **跨平台**：通过 `mkmf` + Ruby 工具链构建，支持 **x86_64 / arm64**，**macOS / Linux / Windows**
+- **字节流模式**（`stream = 1`）：数据按有序字节流交付，无消息边界
+- **拉取式接口**：引擎不碰 socket，你通过 `output`/`input` 自己收发 UDP 数据报
+- 零运行时依赖（除 Ruby >= 3.0）
+
+## 安装
+
+```ruby
+# Gemfile
+gem 'kcp'
+```
+
+```bash
+gem install kcp
+```
+
+构建时会自动编译 `ext/kcp` 下的 C 源码（`ikcp.c` + `kcp_native.c`），
+由 Ruby 的 `mkmf` 负责选择对应平台的编译器与架构（Windows 用 MSVC/MinGW，macOS/Linux 用 clang/gcc，arm/x64 自动匹配）。
+
+## 快速开始
+
+KCP 引擎只管「把字节流可靠送达对端」，**不处理 socket、地址、加密**。
+两端各创建一个引擎，通过 UDP 数据报互相喂包即可：
+
+```ruby
+require 'kcp'
+
+CONV = 0x1122_3344  # 会话标识，两端必须一致
+
+# ---- 发送端 ----
+engine = Kcp::Engine.new(CONV)
+
+engine.send("hello kcp")       # 数据进入发送队列
+engine.flush                   # 立即刷出
+
+# 从引擎取出编码后的 KCP 包，交给 UDP sendto
+while (pkt = engine.output)
+  udp_socket.send(pkt, 0, peer_host, peer_port)
+end
+
+# ---- 接收端（收到 UDP 数据报后）----
+engine.input(recv_datagram)    # 喂入收到的包
+
+# 从引擎取出按序送达的字节流
+data = engine.recv             # => "hello kcp"（没有数据时返回 nil）
+
+# 周期性驱动（重传 / 窗口更新 / 心跳）
+engine.update(Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000)
+```
+
+## 接口说明
+
+### `Kcp::Engine.new(conv)`
+
+创建引擎。`conv` 是 32 位会话标识（`uint32`），**同一条连接的两端必须使用相同的 `conv`**，
+用于区分不同的会话。多个并发连接时应为每个连接分配不同的 `conv`。
+
+```ruby
+engine = Kcp::Engine.new(0x1234)
+```
+
+### `send(data)`
+
+把数据排入发送队列，返回排入的字节数，出错返回负数。**数据不会立即发出**，
+需要调用 `flush`（立即）或 `update`（按间隔）才会生成编码包。
+
+```ruby
+engine.send("some bytes")
+```
+
+### `flush`
+
+立即把发送队列里的数据刷成编码包（不受 `update` 的间隔节流）。刷完后用 `output` 取出。
+
+```ruby
+engine.send(data)
+engine.flush
+pkt = engine.output
+```
+
+### `output`
+
+取出待发送的编码包（可能是一段拼接好的字节，直接交给 UDP `send`）。没有待发送数据时返回 `nil`。
+**取出的字节必须原样发给对端**，对端收到后原样 `input`。
+
+```ruby
+while (pkt = engine.output)
+  socket.send(pkt, 0, host, port)
+end
+```
+
+### `input(data)`
+
+喂入一个收到的编码包（低层 UDP 数据报的内容）。KCP 会解析、处理 ACK/重传/数据，
+随后可用 `recv` 取数据、用 `output` 取要回发的包（例如 ACK）。
+
+```ruby
+socket.recvfrom(65_536) do |data, addr|
+  engine.input(data)
+end
+```
+
+### `recv(maxlen = 65536)`
+
+取出对端已送达的、**按序**的字节流（最多 `maxlen` 字节）。没有数据时返回 `nil`。
+
+```ruby
+if (chunk = engine.recv)
+  # 处理收到的数据
+end
+```
+
+### `update(now_ms)`
+
+驱动 KCP 时钟：触发按间隔的重传、ACK、窗口探测等。`now_ms` 是**单调毫秒时间戳**
+（建议用 `Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000`）。
+
+应在主循环里周期性调用，例如每 10~100ms 一次：
+
+```ruby
+loop do
+  engine.update((Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i)
+  sleep 0.01
+end
+```
+
+### `close`
+
+释放对 C 对象的引用（底层 C 内存由 Ruby GC 通过 `TypedData_Wrap_Struct` 自动回收）。
+
+```ruby
+engine.close
+```
+
+## 关于 `update` 与 `now_ms`
+
+KCP **内部没有计时器**，不会自己读系统时间。你必须周期性地喂给它当前时间（`now_ms`），
+它才能驱动所有和时间相关的逻辑：
+
+- **超时重传**：每个已发出的段带一个 `resendts`（下次重传时刻），`current` 推进到它之后才会重传
+- **RTT 测量**：用 `current - 段.ts` 算往返时间，进而算出 RTO
+- **窗口探测**：对端窗口为 0 时，定时发送 WINS 探测
+- **死链检测**：超时无响应则判死
+
+`now_ms` 必须是**单调毫秒时间戳**（`Process.clock_gettime(Process::CLOCK_MONOTONIC)`），
+因为单调时钟只前进、不受系统时间跳变（NTP 校时、手动改时间）干扰。它是 32 位毫秒，约 49 天回绕一次，
+KCP 内部用有符号差值处理回绕，属正常现象。
+
+### 不 `update` 会怎样
+
+1. `ikcp_flush` 第一行是 `if (kcp->updated == 0) return;` —— 而 `updated` 只有 `update` 才置位，
+   所以不 update 时，连包都发不出去（本 gem 的 `flush` 内部会先兜底调一次 update，故单独 `send + flush` 仍可用）。
+2. 即便绕过第 1 点，**重传依赖 `current` 推进**：丢了一个包后若不 update，`resendts` 永远到不了，
+   这一个丢包就会永久卡死；ACK 也不会按间隔刷出，对端窗口不前进，双向一起僵住。
+
+结论：**`update` 就是 KCP 的心跳**。`send + flush` 是「立即发」（低延迟），`update` 是「周期性驱动」
+（重传 / ACK / 窗口 / 保活）。每 10~100ms 调一次；缺了它，只要发生一次丢包连接就死。
+
+## 完整示例（UDP 回显）
+
+仓库内 `examples/` 下有可直接运行的服务端和客户端：
+
+```bash
+ruby -I lib examples/server.rb 9000              # 终端 1：起服务端
+ruby -I lib examples/client.rb 127.0.0.1 9000    # 终端 2：连上后输入即回显，/quit 退出
+```
+
+下面是对应的完整代码：
+
+```ruby
+require 'socket'
+require 'kcp'
+
+CONV = 0x1234
+
+def now_ms
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+end
+
+# ---- 服务端 ----
+server = UDPSocket.new
+server.bind('0.0.0.0', 9000)
+engine = Kcp::Engine.new(CONV)
+
+loop do
+  data, addr = server.recvfrom(65_536)
+  engine.input(data)
+
+  while (chunk = engine.recv)
+    engine.send(chunk)  # 回显
+  end
+  engine.flush
+  while (pkt = engine.output)
+    server.send(pkt, 0, addr[3], addr[1])
+  end
+  engine.update(now_ms)
+end
+```
+
+## 注意事项
+
+1. **KCP 只管可靠传输**，网络 I/O、对端地址管理、加密、会话保活都由上层负责
+   （本仓库的 `mnet` gem 在其上实现了「移动 IP 不中断」的漫游传输层）。
+2. `conv` 两端必须一致；并发连接请用不同 `conv`（或在上层协议里用会话 ID 复用）。
+3. `flush` 是立即刷出（低延迟）；`update` 是按间隔节流（省 CPU）。高频交互场景两者配合使用。
+4. KCP 使用 32 位毫秒时间戳，约 49 天回绕一次，属正常现象（协议内部处理了回绕）。
+
+## 许可
+
+MIT。KCP 源码版权归 skywind3000。

data/ext/kcp/extconf.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+
+# KCP + our shim. mkmf handles cross-compilation for arm/x86_64 and Windows
+# (MinGW/MSVC) via the Ruby toolchain (rbconfig).
+$srcs = %w[ikcp.c kcp_native.c]
+
+create_makefile('kcp_native')