kcp 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42d14476648e8ceeab7e1719c5f60ef345c1756985653d680250f7cff245f556
-  data.tar.gz: 7e9598575a4293778ea9def78f24dfcdcdb5d8a280cf6dd7457ab613c40ea5d9
+  metadata.gz: 571fb1bfe2f3a42c16c77b3c1e1bfe560d2cddf3f103bb74bd8c70cde474507e
+  data.tar.gz: 61968bb59630ea85f5d55c294e6cfa72e6f73c57c3ff734a02368239334c5f98
 SHA512:
-  metadata.gz: 75c1449845bf2f6c3df5afa9cb0cd158430101c090b1069174b56a210933576865b502cc76b735aa59253b8f87d79e590a19c2c7dc2c63c8a6a0770dd61646ab
-  data.tar.gz: 3e74c12241e69202ccb56e4f5fe600a0b3f69bc6b918c4e17ea8abedca016bb15464d7b81cf700f1454056e592f4ad13ab9d48c9a014de6ce07e1d8504db475e
+  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/kcp_native.c

@@ -8,33 +8,46 @@
 #include <stdlib.h>
 #include <string.h>
 
+/* 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;
-    char *out;
-    int outlen;
-    int outcap;
+    kcp_pkt *head;
+    kcp_pkt *tail;
 } kcp_ctx;
 
-/* Max bytes returned per output() call -- safely under the 64KB UDP datagram
-   limit, so a burst of KCP packets never overflows a single sendto(). */
-#define KCP_MAX_BLOB 60000
-
 static int shim_output(const char *buf, int len, ikcpcb *kcp, void *user) {
     kcp_ctx *ctx = (kcp_ctx *)user;
-    if (ctx->outlen + len > ctx->outcap) {
-        ctx->outcap = (ctx->outlen + len) * 2 + 256;
-        ctx->out = (char *)realloc(ctx->out, ctx->outcap);
-    }
-    memcpy(ctx->out + ctx->outlen, buf, len);
-    ctx->outlen += len;
+    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);
-        free(ctx->out);
+        pkt = ctx->head;
+        while (pkt) {
+            kcp_pkt *next = pkt->next;
+            free(pkt);
+            pkt = next;
+        }
         free(ctx);
     }
 }
@@ -108,17 +121,28 @@ 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->outlen <= 0) return Qnil;
-    /* 一次最多返回 60KB 拼接好的包，避免单个 UDP 数据报超过 64KB（EMSGSIZE） */
-    int n = ctx->outlen < KCP_MAX_BLOB ? ctx->outlen : KCP_MAX_BLOB;
-    VALUE buf = rb_str_new(ctx->out, n);
-    if (n < ctx->outlen) {
-        memmove(ctx->out, ctx->out + n, ctx->outlen - n);
-    }
-    ctx->outlen -= n;
+    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;
 }
 
+static VALUE m_kcp_setmtu(VALUE mod, VALUE self, VALUE mtu) {
+    kcp_ctx *ctx = get_ctx(self);
+    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));
@@ -133,5 +157,7 @@ void Init_kcp_native(void) {
     rb_define_singleton_method(m, "kcp_update", m_kcp_update, 2);
     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.2'
+  VERSION = '0.1.3'
 end

data/lib/kcp.rb

@@ -52,6 +52,19 @@ 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)

metadata

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