mnet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2024e36584d9a17b0671a60776e00d4cee60c0fae82fc940f293566a07f471c7
+  data.tar.gz: 06d1487cb7206d21b62311c89f7e2419785346ebceb86995e79c185f698640e7
+SHA512:
+  metadata.gz: 31c53f20db9e19f677e85452477000197e1f615bbf615a95d14faac1d84e9aa3045821eaa67302ebf6cf68f0ca3ed2e02f0af96b5e732affb84babe396296289
+  data.tar.gz: f06da08c602b9f4bba472e2778cdba7fd1d4e163c0c09d4aa244f04d6d22ba3cacc29b11939e95d986b199991b2b33af98a6e4f17bd0b5a0cd85705dc73cb3db

data/DESIGN.md

@@ -0,0 +1,164 @@
+# mnet 设计
+
+> 本文介绍 mnet 的包结构、数据传输、可靠性机制，以及「切网不断连」的实现原理。
+
+## 包结构
+
+```
+mnet/
+├── lib/
+│   ├── mnet.rb          # Mnet 模块：Session / KcpSession / Endpoint / Server / SessionIO
+│   └── mnet/version.rb  # 版本号
+└── mnet.gemspec         # 依赖 kcp gem
+
+kcp/（独立 gem，原生 C 扩展）
+└── lib/kcp.rb           # Kcp::Engine —— 可靠字节流引擎
+```
+
+### 模块分层
+
+```
+┌───────────────────────────────────────────────────┐
+│ 应用层  read / write / readpartial / wait_readable  │
+├───────────────────────────────────────────────────┤
+│ SessionIO —— IO 兼容接口（可直接套 OpenSSL SSLSocket）│
+├───────────────────────────────────────────────────┤
+│ Session（纯 Ruby ARQ）      │ KcpSession（KCP 引擎） │
+├───────────────────────────────────────────────────┤
+│ Endpoint —— UDP socket 管理 + 会话多路复用           │
+├───────────────────────────────────────────────────┤
+│ UDPSocket（单个 socket，复用所有会话）                │
+└───────────────────────────────────────────────────┘
+```
+
+## 数据传输流
+
+### 发送端
+
+```
+app.write(data)
+   │
+   ▼
+Session#write ── 切分（≤ MSS=1200B）── 分配字节偏移序号 seq
+   │
+   ▼
+封装 Mnet 头（magic + session_id + seq + ack + type + flags + window）
+   │
+   ▼
+[可选] AES-256-GCM 加密载荷（header 作为 AAD，头也防篡改）
+   │
+   ▼
+Endpoint#send_raw ──► UDP socket
+```
+
+### 接收端
+
+```
+UDP socket
+   │
+   ▼
+Endpoint#reader_loop（IO.select 批量收包，一次读多个数据报）
+   │
+   ▼
+解包 ── 按 session_id 查会话
+   │
+   ▼
+Session#handle_packet ── [解密] ── 按 seq 重组
+   │
+   ├─ seq == next_exp ：按序交付 → @recv_buf → 广播唤醒 read
+   └─ seq >  next_exp ：乱序 → 暂存 @reasm（等前面的缺口）
+   │
+   ▼
+app.read 取出
+```
+
+## 可靠性机制
+
+| 机制 | 纯 Ruby Session | KCP 引擎（KcpSession） |
+|---|---|---|
+| 有序交付 | 字节偏移 seq + 乱序缓冲 `@reasm` | KCP 内置 |
+| 丢包重传 | RTO（SRTT/RTTVAR 计算）超时重传 | KCP 快速重传 + 超时 |
+| 流控 | 接收窗口 `recv_cap`（动态适配内核缓冲） | KCP 窗口 |
+| 拥塞控制 | 无（mosh 式，只靠接收窗口） | KCP 内置（已关 nc=1） |
+
+### 序号与 ACK（纯 Ruby）
+
+```
+发送端                              接收端
+   │                                  │
+   │── DATA seq=0,len=1200 ──────────►│
+   │── DATA seq=1200,len=1200 ───────►│
+   │── DATA seq=2400,len=1200 ───────►│  (乱序：暂存 seq=2400)
+   │                                  │
+   │◄── ACK ack=1200 ─────────────────│  (只收到了 seq=0)
+   │                                  │
+   │── DATA seq=1200 重传 ───────────►│  (RTO 超时触发)
+   │                                  │
+   │◄── ACK ack=3600 ─────────────────│  (缺口补齐，连续后统一 ACK)
+```
+
+## 切网不断连（漫游）
+
+核心思想：**会话身份 ≠ 源地址**。
+
+TCP 用「源IP:源端口 + 目标IP:目标端口」四元组定位连接，源 IP 一变连接就断。
+mnet 用 **128-bit 随机 token（session_id）** 标识会话——对端收到包时只要 token 合法，
+就更新「这个会话现在从哪来」，于是源地址变化不中断连接。
+
+### 迁移过程
+
+```
+切网前：  client 192.168.1.5:5000 ── token ──► server（记住 client 地址）
+                                              │
+        （WIFI → 蜂窝，源地址变了；socket 绑定 0.0.0.0，内核自动换源）
+                                              │
+切网后：  client 10.0.0.8:5000  ── token ──► server
+                                              │
+                                              ▼
+                          update_peer 检测源地址变化
+                          → 更新指向 10.0.0.8:5000
+                          → 后续应答直接发往新地址（连接不断）
+```
+
+### 端口跳变 hop
+
+```
+┌─────────┐          ┌─────────┐
+│ client  │  socket1 │         │  旧 socket（保留 60s 收延迟包）
+│         ├─────────►│ server  │
+│         │  socket2 │         │  新 socket（hop 后发送走这个）
+└─────────┘          └─────────┘
+```
+
+- **真实切网**：客户端绑定 `0.0.0.0`，内核按路由自动换源地址，无需任何操作
+- **`hop`**：显式开新 socket（新源端口），旧 socket 保留 60s 兜底收延迟包
+
+## 会话状态机
+
+```
+              SYN                DATA/ACK
+  :connecting ────► :established ────► :closed
+      │                  │
+      │ SYNACK           │ FIN
+      ▼                  ▼
+  :established        :closed
+```
+
+## 线程模型
+
+```
+Endpoint（每个端点一个）
+├── reader 线程：IO.select 批量收包 → 解包 → 按 session_id 分发到会话
+└── ticker 线程：每 50ms 驱动会话（重传 / ACK / 保活 / 窗口探测）
+
+每个 Session
+├── 应用线程：write / read（阻塞在 Monitor + ConditionVariable）
+└── [可选] TLS 桥接线程（socketpair，仅嵌套 TLS 需要；明文用 session 直连）
+```
+
+## 加密（可选 session_key）
+
+- 会话 ID 由密钥派生：`session_id = SHA256(key)[0,16]`
+- 每包 **AES-256-GCM**，明文头作为 AAD（连头部都防篡改）
+- 每次加密用随机 nonce，避免重传时 nonce 复用
+- 密钥需**预共享**（带外分发）；密钥不对 → 解密失败 → 丢包 → 连不上

data/README.en.md

@@ -0,0 +1,125 @@
+# mnet
+
+[简体中文](README.md) | English
+
+A reliable UDP transport whose connections survive network / egress changes (like mosh).
+It ships a pure-Ruby ARQ engine plus a C engine built on the `kcp` gem.
+
+> For the internals (package structure, data flow, roaming) see **[DESIGN.md](DESIGN.md)**.
+
+## Features
+
+- **Roaming**: sessions are identified by a 128-bit token (not the TCP source-address 4-tuple),
+  so the peer just updates its address when the source changes
+- **Port hopping**: mosh-style `hop`; old sockets are kept for 60s to catch delayed packets
+- **Optional encryption**: per-packet AES-256-GCM (`key`, pre-shared)
+- **Two engines**: `proto: :mnet` (pure Ruby, no C dependency) / `proto: :kcp` (C engine, fast)
+- **Stream sessions**: `Mnet::Session` implements an IO-compatible interface
+  (`read / write / readpartial / wait_readable`), so `OpenSSL::SSL::SSLSocket` can wrap it directly
+- Cross-platform: the pure-Ruby part is inherently portable; KCP is a native extension from the `kcp` gem
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'mnet'
+```
+
+## Quick start
+
+```ruby
+require 'mnet'
+
+# ---- server (echo) ----
+server = Mnet::Server.new('0.0.0.0', 9000)
+loop do
+  io = server.accept_session
+  Thread.new { while (d = io.readpartial(65_536)); io.write(d); end }
+end
+
+# ---- client ----
+endpoint = Mnet::Endpoint.new
+sess = endpoint.dial('127.0.0.1', 9000, proto: :kcp)  # :mnet or :kcp
+sess.write('hello')
+puts sess.readpartial(1024)
+```
+
+## Engine choice
+
+| `proto` | Description |
+|---|---|
+| `:mnet` | pure-Ruby ARQ, no C dependency, simple and easy to debug |
+| `:kcp` | C engine (via the `kcp` gem), ~8x faster, requires building a native extension |
+
+## Encryption (pre-shared key)
+
+Per-packet AES-256-GCM; both ends must pre-share the same 32-byte key:
+
+```ruby
+require 'securerandom'
+key = SecureRandom.random_bytes(32)
+
+# server registers the key (one or more)
+server = Mnet::Server.new('0.0.0.0', 9000, keys: [key])
+
+# client dials with the key
+sess = endpoint.dial('127.0.0.1', 9000, proto: :kcp, key: key)
+```
+
+The session id is derived from the key (`SHA256(key)[0,16]`); with the wrong key the server fails to
+decrypt and drops the packet, so the client cannot connect.
+
+## TLS (nested)
+
+`Mnet::Session` implements an IO-compatible interface, so `SSLSocket` can wrap it directly
+(`SSLServer` usage is compatible):
+
+```ruby
+require 'openssl'
+
+server = Mnet::Server.new('0.0.0.0', 9001)
+ssl_server = OpenSSL::SSL::SSLServer.new(server, ssl_context)
+ssl_server.start_immediately = false   # do the handshake in worker threads, don't block accept
+loop do
+  ssl_sock = ssl_server.accept
+  Thread.new do
+    ssl_sock.accept
+    # ...read/write ssl_sock...
+  end
+end
+```
+
+## Roaming
+
+```ruby
+endpoint.hop   # simulate a network change (in reality the client binds 0.0.0.0, and the OS
+               # re-picks the source address automatically, so no manual hop is needed)
+```
+
+## Benchmarks
+
+Environment: loopback (127.0.0.1), pipelined echo (concurrent writer/reader, counted by total bytes).
+
+| Scheme | 1KB-message throughput |
+|---|---|
+| TCP (raw) | ~49 MB/s |
+| TCP + SSL | ~22 MB/s |
+| **mnet pure Ruby** (`proto: :mnet`) | ~1.8 MB/s |
+| mnet pure Ruby + key (AES-GCM) | ~1.6 MB/s |
+| **mnet + KCP** (`proto: :kcp`) | **~5.0 MB/s** |
+| mnet + KCP + key (AES-GCM) | ~4.1 MB/s |
+
+Takeaways:
+
+- **The KCP engine is ~2.7x faster than pure Ruby** (5.0 vs 1.8 MB/s)
+- **Encryption overhead is small**: `key` (per-packet AES-GCM) only costs ~15–18%
+- **Plaintext KCP is ~1/10 of TCP**; the bottleneck is the Ruby per-packet glue
+  (pack/unpack + thread switching), not the ARQ algorithm
+- These are synthetic loopback numbers; over a real network latency dominates and interactive
+  (small-message) workloads feel identical
+
+Reproduce: `ruby -I lib -I ../kcp/lib test/bench_compare.rb [msgs] [msg_bytes]`
+
+## License
+
+MIT.

data/README.md

@@ -0,0 +1,118 @@
+# mnet
+
+[English](README.en.md) | 简体中文
+
+可靠的 UDP 传输层，连接在**切换网络 / 出口 IP 变化时不断开**（类似 mosh）。
+提供纯 Ruby ARQ 引擎，以及基于 `kcp` gem 的 C 引擎。
+
+> 想了解内部实现原理（包结构、数据传输、切网不断连）见 **[DESIGN.md](DESIGN.md)**。
+
+## 特性
+
+- **切网不断连**：会话用 128-bit token 标识（而非 TCP 的源地址四元组），源地址变化时对端自动更新指向
+- **端口跳变**：mosh 式 `hop`，旧 socket 保留 60s 收延迟包
+- **可选加密**：每包 AES-256-GCM（`key`，需预共享）
+- **两种引擎**：`proto: :mnet`（纯 Ruby，无 C 依赖）/ `proto: :kcp`（C 引擎，快）
+- **流式会话**：`Mnet::Session` 实现 IO 兼容接口（`read / write / readpartial / wait_readable`），可直接被 `OpenSSL::SSL::SSLSocket` 包装
+- 跨平台：纯 Ruby 部分天然跨平台，KCP 由 `kcp` gem 提供原生扩展
+
+## 安装
+
+```ruby
+# Gemfile
+gem 'mnet'
+```
+
+## 快速开始
+
+```ruby
+require 'mnet'
+
+# ---- 服务端（回显）----
+server = Mnet::Server.new('0.0.0.0', 9000)
+loop do
+  io = server.accept_session
+  Thread.new { while (d = io.readpartial(65_536)); io.write(d); end }
+end
+
+# ---- 客户端 ----
+endpoint = Mnet::Endpoint.new
+sess = endpoint.dial('127.0.0.1', 9000, proto: :kcp)  # :mnet 或 :kcp
+sess.write('hello')
+puts sess.readpartial(1024)
+```
+
+## 引擎选择
+
+| `proto` | 说明 |
+|---|---|
+| `:mnet` | 纯 Ruby ARQ，无 C 依赖，简单、易调试 |
+| `:kcp` | C 引擎（依赖 `kcp` gem），快约 8 倍，需编译原生扩展 |
+
+## 加密（预共享密钥）
+
+每包 AES-256-GCM，两端需预共享同一个 32 字节密钥：
+
+```ruby
+require 'securerandom'
+key = SecureRandom.random_bytes(32)
+
+# 服务端注册密钥（可注册多个）
+server = Mnet::Server.new('0.0.0.0', 9000, keys: [key])
+
+# 客户端带密钥拨号
+sess = endpoint.dial('127.0.0.1', 9000, proto: :kcp, key: key)
+```
+
+会话 ID 由密钥派生（`SHA256(key)[0,16]`）；密钥不对时服务端解密失败、直接丢弃包，客户端连不上。
+
+## TLS（嵌套）
+
+`Mnet::Session` 实现了 IO 兼容接口，可被 `SSLSocket` 直接包装（`SSLServer` 写法兼容）：
+
+```ruby
+require 'openssl'
+
+server = Mnet::Server.new('0.0.0.0', 9001)
+ssl_server = OpenSSL::SSL::SSLServer.new(server, ssl_context)
+ssl_server.start_immediately = false   # 把握手放到工作线程，不阻塞 accept
+loop do
+  ssl_sock = ssl_server.accept
+  Thread.new do
+    ssl_sock.accept
+    # ...读写 ssl_sock...
+  end
+end
+```
+
+## 切网迁移
+
+```ruby
+endpoint.hop   # 模拟切网（真实场景下客户端绑 0.0.0.0，内核自动换源地址，无需手动 hop）
+```
+
+## 基准测试
+
+环境：loopback（127.0.0.1），pipelined echo（写端与读端并发，按总字节计）。
+
+| 方案 | 1KB 消息吞吐 |
+|---|---|
+| TCP（裸） | ~49 MB/s |
+| TCP + SSL | ~22 MB/s |
+| **mnet 纯 Ruby**（`proto: :mnet`） | ~1.8 MB/s |
+| mnet 纯 Ruby + key（AES-GCM） | ~1.6 MB/s |
+| **mnet + KCP**（`proto: :kcp`） | **~5.0 MB/s** |
+| mnet + KCP + key（AES-GCM） | ~4.1 MB/s |
+
+结论：
+
+- **KCP 引擎比纯 Ruby 快约 2.7 倍**（5.0 vs 1.8 MB/s）
+- **加密开销很小**：`key`（每包 AES-GCM）只慢 ~15~18%
+- **明文 KCP 约为 TCP 的 1/10**；瓶颈在 Ruby 层的每包 glue（pack/unpack + 线程切换），不在 ARQ 算法
+- 以上是 loopback 合成基准；真实网络延迟主导时，交互式（小消息）体感无差别
+
+复现：`ruby -I lib -I ../kcp/lib test/bench_compare.rb [消息数] [消息字节]`
+
+## 许可
+
+MIT。

data/lib/mnet/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mnet
+  VERSION = '0.1.0'
+end