kcp 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7802d290ec502e834ab5f7eb1e9b4c7a4f664b677ecae6c6f001fce6be4cd3c
-  data.tar.gz: 58fc1060c2be20897078deb312bfd4e671a5d5dd72b9656205ee2ccf8cc6fa31
+  metadata.gz: 571fb1bfe2f3a42c16c77b3c1e1bfe560d2cddf3f103bb74bd8c70cde474507e
+  data.tar.gz: 61968bb59630ea85f5d55c294e6cfa72e6f73c57c3ff734a02368239334c5f98
 SHA512:
-  metadata.gz: f01a77107b1821d1c32818c403982799e5a97b0dd214d6f9b8cb7e6419f1eb597849d31456f76abecadb75317d2a1a29bd85f3ea8694d88dcf57e2c6699d12d7
-  data.tar.gz: 2261acc0d59efcb3b94267a0b523e24fa9b036aa5ba7e18f52a2a857194051a94c1a2004d4ba1a993b7141e76e7ca9bfcae828ee7098c91aaaba66e2382b7edc
+  metadata.gz: d0972c1a441962ed5ea19c34c1b68575068743c28b6ba18fdf97bd7b98fbaa36a9b03e3000ca505ffc711431fef5ee0596770bb940920eb5b6aa38973f789e75
+  data.tar.gz: e984ff6afc0199d36b55b9e91509c3d08b7fe98e7a0da3b2e37124e4a835577a652bcd62c3e91d269b22800c649fd9c7b0aa7019695ff5101a425126282505fc

data/README.en.md

@@ -91,11 +91,32 @@ engine.flush
 pkt = engine.output
 ```
 
+### `setmtu(mtu)`
+
+Set the maximum size of a single KCP packet (`mtu`), default 1300. When an upper layer wraps each
+KCP packet in its own header and sends it as one UDP datagram, set this to "link MTU − upper-layer
+header overhead", otherwise the full datagram exceeds the MTU and gets IP-fragmented (fragments are
+frequently dropped on mobile/VPN links).
+
+```ruby
+engine.setmtu(1200)   # keep KCP packet + upper-layer header <= link MTU
+```
+
+### `mss`
+
+Returns the current segment payload size (`= mtu - 24` bytes of KCP header). A single `send` accepts
+at most `IKCP_WND_RCV` (128) segments; beyond that it returns `-2` and drops the whole block, so
+upper layers should feed data in `mss * 127` chunks to avoid large writes being dropped.
+
+```ruby
+engine.mss   # => 1176 (after setmtu(1200))
+```
+
 ### `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`.
+Pull pending encoded packets, **one packet per call** (never larger than `mtu`), 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)
@@ -229,6 +250,8 @@ end
    interactive workloads.
 4. KCP uses a 32-bit millisecond timestamp that wraps every ~49 days; this is expected (the protocol
    handles the wraparound).
+5. The default `mtu` is 1300; when an upper layer adds its own header, use `setmtu` to shrink KCP
+   packets below the link MTU, so the full datagram is not IP-fragmented.
 
 ## License
 

data/README.md

@@ -89,10 +89,29 @@ engine.flush
 pkt = engine.output
 ```
 
+### `setmtu(mtu)`
+
+设置单个 KCP 包的最大尺寸（mtu），默认 1300。当上层把每个 KCP 包再套一层头作为单个 UDP
+数据报发送时，应把它设为「链路 MTU - 上层头开销」，否则整包会超过 MTU 触发 IP 分片
+（移动网络/VPN 下分片极易被丢弃）。
+
+```ruby
+engine.setmtu(1200)   # 让 KCP 包 + 上层头 <= 链路 MTU
+```
+
+### `mss`
+
+返回当前分段载荷大小（= `mtu - 24` 字节 KCP 头）。单次 `send` 最多接受 `IKCP_WND_RCV`(128)
+个分段，超出会返回 `-2` 丢弃；上层按 `mss * 127` 切块喂入可避免大块写被丢。
+
+```ruby
+engine.mss   # => 1176（setmtu(1200) 之后）
+```
+
 ### `output`
 
-取出待发送的编码包（可能是一段拼接好的字节，直接交给 UDP `send`）。没有待发送数据时返回 `nil`。
-**取出的字节必须原样发给对端**，对端收到后原样 `input`。
+取出待发送的编码包，**每次一个**（不超过 `mtu`），直接交给 UDP `send`。没有待发送数据时
+返回 `nil`。**取出的字节必须原样发给对端**，对端收到后原样 `input`。
 
 ```ruby
 while (pkt = engine.output)
@@ -215,6 +234,8 @@ end
 2. `conv` 两端必须一致；并发连接请用不同 `conv`（或在上层协议里用会话 ID 复用）。
 3. `flush` 是立即刷出（低延迟）；`update` 是按间隔节流（省 CPU）。高频交互场景两者配合使用。
 4. KCP 使用 32 位毫秒时间戳，约 49 天回绕一次，属正常现象（协议内部处理了回绕）。
+5. 默认 `mtu` 为 1300；上层再包一层头时请用 `setmtu` 把 KCP 包缩小到链路 MTU 以内，避免整包
+   超过 MTU 被 IP 分片。
 
 ## 许可
 

data/ext/kcp/ikcp.c

@@ -34,7 +34,7 @@ const IUINT32 IKCP_ASK_SEND = 1;		// need to send IKCP_CMD_WASK
 const IUINT32 IKCP_ASK_TELL = 2;		// need to send IKCP_CMD_WINS
 const IUINT32 IKCP_WND_SND = 32;
 const IUINT32 IKCP_WND_RCV = 128;       // must >= max fragment size
-const IUINT32 IKCP_MTU_DEF = 1400;
+const IUINT32 IKCP_MTU_DEF = 1300;
 const IUINT32 IKCP_ACK_FAST	= 3;
 const IUINT32 IKCP_INTERVAL	= 100;
 const IUINT32 IKCP_OVERHEAD = 24;

data/ext/kcp/kcp_native.c

@@ -8,45 +8,46 @@
 #include <stdlib.h>
 #include <string.h>
 
-typedef struct {
-    char *data;
+/* One encoded KCP packet produced by ikcp_flush, kept as its own buffer so a
+   single output() call returns exactly one packet. mnet wraps each packet in
+   its own header and sends it as one UDP datagram, so packets must never be
+   merged: merging would create datagrams larger than the MTU and cause IP
+   fragmentation (which is unreliable on mobile/VPN links). */
+typedef struct kcp_pkt {
+    struct kcp_pkt *next;
     int len;
+    char data[1];
 } kcp_pkt;
 
 typedef struct {
     ikcpcb *kcp;
-    kcp_pkt *pkts;
-    int count;
-    int cap;
+    kcp_pkt *head;
+    kcp_pkt *tail;
 } kcp_ctx;
 
-/* shim_output 每个 KCP 报文（≤ mtu）单独入队，output() 一次只取一个包，
-   避免把多个 KCP 报文拼成一个大 blob，导致上层封成单个超大 UDP 数据报被
-   IP 分片（分片常被 NAT/防火墙丢弃，造成远端云主机连接异常）。 */
 static int shim_output(const char *buf, int len, ikcpcb *kcp, void *user) {
     kcp_ctx *ctx = (kcp_ctx *)user;
-    if (ctx->count >= ctx->cap) {
-        int newcap = ctx->cap ? ctx->cap * 2 : 32;
-        kcp_pkt *npkts = (kcp_pkt *)realloc(ctx->pkts, newcap * sizeof(kcp_pkt));
-        if (!npkts) return -1;
-        ctx->pkts = npkts;
-        ctx->cap = newcap;
-    }
-    kcp_pkt *p = &ctx->pkts[ctx->count];
-    p->data = (char *)malloc(len);
-    if (!p->data) return -1;
-    memcpy(p->data, buf, len);
-    p->len = len;
-    ctx->count++;
+    kcp_pkt *pkt = (kcp_pkt *)malloc(sizeof(kcp_pkt) + len);
+    if (!pkt) return -1;
+    pkt->next = NULL;
+    pkt->len = len;
+    memcpy(pkt->data, buf, len);
+    if (ctx->tail) ctx->tail->next = pkt; else ctx->head = pkt;
+    ctx->tail = pkt;
     return 0;
 }
 
 static void ctx_free(void *ptr) {
     kcp_ctx *ctx = (kcp_ctx *)ptr;
     if (ctx) {
+        kcp_pkt *pkt;
         if (ctx->kcp) ikcp_release(ctx->kcp);
-        for (int i = 0; i < ctx->count; i++) free(ctx->pkts[i].data);
-        free(ctx->pkts);
+        pkt = ctx->head;
+        while (pkt) {
+            kcp_pkt *next = pkt->next;
+            free(pkt);
+            pkt = next;
+        }
         free(ctx);
     }
 }
@@ -120,15 +121,15 @@ static VALUE m_kcp_flush(VALUE mod, VALUE self) {
 
 static VALUE m_kcp_output(VALUE mod, VALUE self) {
     kcp_ctx *ctx = get_ctx(self);
-    if (ctx->count <= 0) return Qnil;
-    /* 一次只返回一个 KCP 报文（≤ mtu），避免上层拼成超长 UDP 数据报触发 IP 分片 */
-    kcp_pkt p = ctx->pkts[0];
-    VALUE buf = rb_str_new(p.data, p.len);
-    free(p.data);
-    ctx->count--;
-    if (ctx->count > 0) {
-        memmove(&ctx->pkts[0], &ctx->pkts[1], ctx->count * sizeof(kcp_pkt));
-    }
+    kcp_pkt *pkt;
+    VALUE buf;
+    if (!ctx->head) return Qnil;
+    /* 一次只返回一个 KCP 包，交由上层各自封装成不超过 MTU 的 UDP 数据报。 */
+    pkt = ctx->head;
+    ctx->head = pkt->next;
+    if (!ctx->head) ctx->tail = NULL;
+    buf = rb_str_new(pkt->data, pkt->len);
+    free(pkt);
     return buf;
 }
 
@@ -137,6 +138,11 @@ static VALUE m_kcp_setmtu(VALUE mod, VALUE self, VALUE mtu) {
     return INT2NUM(ikcp_setmtu(ctx->kcp, NUM2INT(mtu)));
 }
 
+static VALUE m_kcp_mss(VALUE mod, VALUE self) {
+    kcp_ctx *ctx = get_ctx(self);
+    return INT2NUM(ctx->kcp->mss);
+}
+
 static VALUE m_kcp_waitsnd(VALUE mod, VALUE self) {
     kcp_ctx *ctx = get_ctx(self);
     return INT2NUM(ikcp_waitsnd(ctx->kcp));
@@ -152,5 +158,6 @@ void Init_kcp_native(void) {
     rb_define_singleton_method(m, "kcp_flush", m_kcp_flush, 1);
     rb_define_singleton_method(m, "kcp_output", m_kcp_output, 1);
     rb_define_singleton_method(m, "kcp_setmtu", m_kcp_setmtu, 2);
+    rb_define_singleton_method(m, "kcp_mss", m_kcp_mss, 1);
     rb_define_singleton_method(m, "kcp_waitsnd", m_kcp_waitsnd, 1);
 }

data/lib/kcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kcp
-  VERSION = '0.1.1'
+  VERSION = '0.1.3'
 end

data/lib/kcp.rb

@@ -52,17 +52,24 @@ module Kcp
       KcpNative.kcp_flush(@ctx)
     end
 
+    # 设置 KCP 包的最大尺寸（mtu）。默认 1300。上层（如 mnet）把每个 KCP 包
+    # 再包一层头作为单个 UDP 数据报发送时，应把它设成「链路 MTU - 上层头开销」，
+    # 否则整包会超过 MTU 触发 IP 分片。
+    def setmtu(mtu)
+      KcpNative.kcp_setmtu(@ctx, mtu)
+    end
+
+    # 当前分段载荷大小（= mtu - 24 字节 KCP 头）。单次 send 最多接受
+    # IKCP_WND_RCV(128) 个分段，超出会返回 -2 丢弃；上层按 mss 切块可避免。
+    def mss
+      KcpNative.kcp_mss(@ctx)
+    end
+
     # 取出待发送的编码包（一次一个 KCP 包），交给低层发送。没有待发送时返回 nil。
     def output
       KcpNative.kcp_output(@ctx)
     end
 
-    # 设置 KCP 内部 MTU（默认 1400）。上层如 mnet 会额外加自己的 header + GCM tag，
-    # 需要把 MTU 调小，保证「KCP 包 + 外层封装」仍小于路径 MTU，避免 IP 分片。
-    def mtu=(mtu)
-      KcpNative.kcp_setmtu(@ctx, mtu)
-    end
-
     # 发送队列里待发送的包数（>0 表示窗口已满、有积压）。
     def waitsnd
       KcpNative.kcp_waitsnd(@ctx)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kcp
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - kcp developers