#lexchb/memcached

• 模块名：lexchb/memcached，版本 0.1.0
• 首选编译目标：wasm-gc
• 依赖：仅 moonbitlang/core 的 buffer、debug、encoding/utf8、string

#安装

moon add lexchb/memcached

#快速开始

// 内存转录：服务器依次回答 STORED 与一个 VALUE 块。
let conn = @memcached.ScriptedConnection::new([
  b"STORED\r\n", b"VALUE foo 0 3\r\nbar\r\nEND\r\n",
])
let client = @memcached.Client::new(conn)
println(client.set("foo", b"bar")) // Status::Stored
for value in client.get(["foo"]) {
  println(value.key) // foo
  println(value.data) // b"bar"
}

#一、目录结构

#二、分层架构

        ┌─────────────────────────────────────────┐
        │  client.mbt   Client / 校验 / 便捷方法   │  面向使用者的 API
        └───────────────┬─────────────┬───────────┘
                        │             │
        ┌───────────────▼──┐   ┌──────▼──────────────┐
        │ memcached.mbt    │   │ transport.mbt       │
        │ Request::to_bytes│   │ trait Connection    │
        │ Decoder          │   │ ScriptedConnection  │
        │ 协议错误类型      │   │ TransportError      │
        └──────────────────┘   └─────────────────────┘

• 编解码层（memcached.mbt）不持有任何连接，纯粹是字节进、字节出，所以可以脱离网络做单元测试。
• 传输层（transport.mbt）只描述“字节怎么进出”，不关心 memcached 语义。
• 客户端层（client.mbt）把两者串起来：写入编码后的请求，循环读取直到解出一个完整响应。

#三、数据模型

#请求

#noreply 与「是否有应答」

#响应

#错误

#四、请求编码流程

1. 新建一个 @buffer.Buffer。
2. 按 Request 变体分支拼装：
   • Storage：写命令词 → 空格 → key → " <flags> <exptime> <bytes>" → 若有 CAS 令牌再补 " <cas>" → 若有 noreply 再补 " noreply" → \r\n → 原始数据 → \r\n。 其中 <bytes> 由 value.length() 现场计算，不需要调用方手工填写，避免长度与实际数据不一致。
   • Get：按 with_cas 选择 get 或 gets，然后依次追加每个 key。
   • Gat：先写 gat/gats 与 <exptime>，再追加每个 key——注意过期时间在 key 之前。
   • Delete / Incr / Decr / Touch：按模板拼接，noreply 由 write_noreply 统一追加在行尾。
   • Version：常量 version\r\n。
   • Stats：写 stats，有分节名时再补 " <sub>"——段名按调用方给出的样子原样写出， 因此 detail on、cachedump 1 100 这类带参数的段名会变成 stats detail on 这样的命令行。
   • FlushAll：写 flush_all，有延迟时再补 " <delay>"，最后是 noreply。
   • Verbosity：写 verbosity <level>，最后是 noreply。
   • CacheMemlimit：写 cache_memlimit <megabytes>，最后是 noreply。
   • SlabsReassign：写 slabs reassign <src> <dst>，最后是 noreply。
   • SlabsAutomove：写 slabs automove <mode>，最后是 noreply。
   • Quit：常量 quit\r\n。
3. Buffer::to_bytes() 返回最终字节。

set foo 7 60 3\r\nbar\r\n          # Storage(Set, "foo", 7, 60, b"bar", None, false)
set foo 0 0 3 noreply\r\nbar\r\n   # Storage(Set, "foo", 0, 0, b"bar", None, true)
cas foo 0 0 3 42\r\nbar\r\n        # Storage(Cas, "foo", 0, 0, b"bar", Some(42), false)
get foo bar\r\n                    # Get(["foo","bar"], with_cas=false)
gets foo bar\r\n                   # Get(["foo","bar"], with_cas=true)
gat 30 foo bar\r\n                 # Gat(["foo","bar"], 30, with_cas=false)
touch foo 30\r\n                   # Touch("foo", 30, noreply=false)
delete foo\r\n
delete foo noreply\r\n
incr counter 3\r\n
version\r\n
stats items\r\n
flush_all\r\n                      # FlushAll(None, noreply=false)
flush_all 10\r\n                   # FlushAll(Some(10), noreply=false)
verbosity 2\r\n
cache_memlimit 64\r\n              # CacheMemlimit(64, noreply=false)
slabs reassign -1 2\r\n            # SlabsReassign(-1, 2, noreply=false)
slabs automove 2 noreply\r\n       # SlabsAutomove(2, noreply=true)
quit\r\n

#五、响应解码流程

Decoder::next
  └─ decode_response          在一段缓冲里找第一个 \r\n，定位首行
       ├─ "VALUE ..."  ──► parse_value_header ──► decode_value_blocks（循环）
       ├─ "STAT ..."   ──► parse_stat_line ────► decode_stats（循环）
       ├─ "VERSION ..." ─► Version(去掉 8 字节前缀后的文本)
       ├─ "END"        ──► Values([])       （get 全部未命中）
       └─ 其它         ──► decode_status    （状态行 / 错误行 / 计数器数字）

#1. 定位首行

#2. 状态行 / 错误行 / 计数器

• STORED、NOT_STORED、EXISTS、NOT_FOUND、DELETED、TOUCHED、OK → 对应的 Status （OK 是 flush_all、verbosity、cache_memlimit 与 slabs 系命令的应答）
• ERROR → Remote(Generic, 行内容)
• 以 CLIENT_ERROR 开头 → Remote(Client, ...)
• 以 SERVER_ERROR 开头 → Remote(Server, ...)
• 全为 ASCII 数字 → Counter(值)（incr/decr 的返回）
• 其它 → Malformed("unexpected response line ...")

#3. VALUE 块

• 数据块以字节数定帧，而不是以 \r\n 定帧。 它先检查缓冲区是否已有 header.size 个字节加尾随的 \r\n；不够就返回 None 等更多数据，够了就按声明长度切出 data。因此值里含 \r\n（二进制数据）也不会被截断。若数据后面的两个字节不是 \r\n， 报 Malformed。
• 循环收块。 一个 VALUE 块处理完后，继续看下一行：是 END 就返回累积的 Values(values)，是下一个 VALUE 就换掉当前 header 接着处理，其它内容报 Malformed。 这里刻意不用递归：一次 get 上百个 key 时，递归深度会等于块数。

#4. STAT 块与 VERSION 行

#5. 增量解码器

• 一次 read 可能只给半个响应 → next() 返回 None，feed 剩余部分后即可解出（响应跨包重组）。
• 一次 read 可能给多个响应 → 连续调用 next() 就能逐个取出（流水线批处理就建立在这上面）。
• Remote 错误行会被消费掉 → 错误行本身就是一个完整响应，所以它从缓冲区头部移除之后才抛出。 否则同一个错误会对之后每一次 next() 重复抛出，服务器确实发回来的那些应答永远读不到。Malformed 不走这条路：这段字节根本读不成一个响应，「下一个响应从哪里开始」正是此时不知道的事，恢复靠 resync()。Desynchronised 同理——缓冲区里的残片还没被读成任何东西。

#缓冲上限与失步恢复

#6. 错误信息里的对端数据

• 逐字符调用 Char::escape(quote=false)：回车、换行、制表等控制字符被写成「反斜杠 + 字母」 两个字符的形式，不可打印字符写成 \u{7f} 这样，因此消息始终是单行可读的；
• 最多引用 MAX_QUOTED_CHARS = 64 个字符，超出部分截断并补 ...。

#六、客户端执行流程

Client { conn : &Connection, decoder : Decoder }

#两个入口：execute 与 send

1. validate_request(request) —— 先做本地校验，不合法就抛 Malformed，一个字节都不写出去；
2. guard request.expects_reply() —— 拦下没有应答可读的命令；
3. conn.write(request.to_bytes()) —— 把编码后的请求整段写出；
4. 循环尝试解码：
   • decoder.next() 返回 Some(response) → 直接返回；
   • 返回 None → conn.read(4096) 再读一块；
     • 读到 0 字节说明对端已关闭 → 抛 TransportError::Io("server closed the connection mid-response")；
     • 否则 decoder.feed(chunk) 后继续循环。

#便捷方法

#流水线批处理：pipeline

1. 进函数先把入参复制一份快照，之后校验与写出都只看这份快照——Array 是可变的，若在校验 与写出之间有人动了原数组，就能让一条没被校验过的请求混上线路；
2. 整批先校验（validate_pipeline，见第七节），可能在一个字节都没写出去时就拒绝；
3. 依次写出快照里每个请求的全部字节，中途不读；
4. 写出时顺手记下每个请求是否有应答（一张 Array[Bool] 槽位表），随后照它读回：槽位为 true 才去读一条应答，填进该格；为 false 就留 None。判定只做一次、与配对同源，因此不会出现 「数出 3 条应答、却只有 2 个位置可填」这种漂移——计数和填槽用的是同一份数据。

#七、请求校验

#key 的合法性（validate_key）

1. 非空，且 UTF-8 编码后长度不超过 MAX_KEY_LENGTH = 250 字节（服务器按字节计数，不是字符数）；
2. 每个字节的值不能 <= 0x20（含空格、制表符、换行等空白与控制字符），也不能是 0x7F。

#请求级校验（validate_request）

#批处理的校验（validate_pipeline）

#八、传输层与测试替身

trait Connection {
  fn write(Self, BytesView) -> Unit raise TransportError
  fn read(Self, Int) -> Bytes raise TransportError   // 空结果 = 对端已关闭
  fn close(Self) -> Unit raise TransportError
}

• 构造时给一串 chunks，read 每次只回放一个 chunk，并截断到请求的字节数； 剩余部分留到下一次 read。这让测试可以精确地制造“响应被拆成多段”的场景。
• write 把客户端写出的所有字节累积进内部 Buffer，通过 written() 取回，因此它同时是一个 spy， 可以逐字节断言线上内容。
• chunk 用尽后 read 返回空字节，客户端据此判定为连接关闭。
• close 丢弃剩余的 chunk 和待读数据。

#九、测试与示例

#黑盒测试（memcached_test.mbt）

• 编码：存储命令行与数据块、CAS 令牌、空值、get/gets 多 key、 gat/gats（<exptime> 位于 key 之前）、touch、delete/incr/decr/quit、 version/stats/stats <section>/flush_all/verbosity 的可选参数、 cache_memlimit 与 slabs reassign/automove 的管理命令行、以及 noreply 一律追加在命令行末尾；
• 解码：七种状态行（含 OK）、计数器数字、单个/多个 VALUE 块、未命中（END）、 VERSION 行、STAT 块（含无值的 STAT 行被拒、END 前未结束则继续等待、只收到半行 VERSION 时等待）、数据块以字节数定帧（值内含 \r\n）、响应跨 feed 重组、单次 feed 多响应、服务器错误的三种类别、Remote 错误行被消费后后面那条应答仍读得出来（同一个 错误不会对每次 next() 重复抛出）、非法帧（未知行、字段数不对、数据块未以 CRLF 结尾）；
• 客户端：单连接上 set + get 的完整往返与线上字节断言、cas 透传令牌、set/cas 便捷方法 透传 flags/exptime（线上字节逐字节断言）、add/replace/append/prepend 各自驱动对应的 命令词、gets 带回每个块的 CAS 令牌、delete 与 decr 读回自己那条应答、计数器返回值、 大应答（5000 字节的块，超过一次 4096 字节的读取）被连接拆成多次 read 后照样重组、 touch/gat/gats 往返、version 与 stats 的取值、flush_all/verbosity/ cache_memlimit/slabs 系命令读回 OK、 send 写出 noreply 命令且一个字节都不读、有应答的命令不能 send、无应答的命令不能 execute、quit（含写入失败时仍释放连接，以及关闭也失败时就地吞掉、只报出导致放弃连接的那条 发送错误）、响应中途断连报 TransportError::Io、 未知行报 Malformed、key 长度与字符合法性边界（250 通过 / 251 拒绝 / 空串 / 空格 / 制表符 / 换行）、空 key 列表与管理命令的非法参数（负的 megabytes、小于 -1 的 slab source、 负的 slab target、超出 0..=2 的 automove 模式）在写出任何字节之前就被拒绝、声明的字节数远大于 可用数据时只是等待而不是错误分帧、始终无法定帧的应答被 with_limit 当场判为 Malformed 而不是无限缓冲、失步的连接经 Client::resync 清空残片后照常往返；
• 流水线批处理：三个请求（有应答 / noreply / 有应答）的槽位与请求一一对齐、线上字节逐字节 断言；用一个把 write/read 调用按顺序记下来的测试替身（TracingConnection）证明整批 先全部写完再开始读，以及全 noreply 的批次只写不读；空批次不写不读返回空；应答跨读边界 时在批次内照样重组；Remote 错误把后面的应答读完丢弃后抛出，因此紧接着的命令读到的是自己 的应答而不是留下的那条；Malformed 则当场停住、不做排空；批里混进非法请求或 quit 时一个 字节都没写出去；
• 缓冲上限与块上限：上限为 0 的解码器仍能解出已经完整的响应（上限只在等待时才起作用）， 而同样大小的一段残片会被判为 Desynchronised(0, 6) 并如实报出上限与已缓冲字节数；缓冲区 长度恰好等于上限时继续等待（判据是「超过」而不是「达到」），多一个字节才判失步；而块 连同它的头行与收尾的 END 都放不进上限时当场报 Malformed——连 0 上限的解码器遇到 VALUE k 0 1 也是这个结果，因为头本身就说出了这个块在此处不可能凑齐；Client::with_limit 在上限足够大时不影响正常往返，线上字节与默认解码器一致。

#白盒测试（memcached_wbtest.mbt）

• StorageOp::name：六个存储命令的命令词映射；
• find_crlf：首个分隔符的位置、空输入、只有 \r 的输入；
• 数字解析：is_decimal 对符号/字母/内嵌空格的拒绝，parse_decimal 的 u64 上界 （18446744073709551615 通过 / ...616 拒绝），parse_decimal_int 的 i32 上界 （2147483647 通过 / 2147483648 拒绝）；
• parse_value_header：四/五字段、非 ASCII key、字段数不对、非数字字段、超界值；头行的字节数由 调用方按它在线上的长度传入（decode_response 传的就是行尾分隔符的偏移），不再重新编码取长度； 以及 <bytes> 的块上限——它由传入的 limit 决定，且判据算的是「块 + 头行 + 块尾 \r\n + END 行」能否装进 limit（分帧部分直接取常量 VALUE_RETRIEVAL_FRAMING 的字节数，不手算）： memcached 自身的 1 MiB item 上限（1048576）连分帧也放得进 DEFAULT_BUFFER_LIMIT，属于 「还在路上」的块必须通过，而恰好等于上限的声明会被拒绝（分帧没有容身之处）；换成 limit=64 时 VALUE foo 0 41 的 14（头行）+ 41（数据）+ 9（VALUE_RETRIEVAL_FRAMING）= 64 恰好通过， 再多一个字节就被拒绝；
• 解码细节：decode_status 原样带回 offset、decode_line 把 UTF-8 key 还原成文本、 decode_response 对 64 个 VALUE 块的整段解码与消耗字节数、以及“响应不完整不是错误” （只返回 None 等待更多数据）；
• STAT 行：只在第一个空格处切分（值里可以带空格，如 libevent 2.1.12-stable）、 子命令把维度嵌进名字（items:1:number）、缺值/缺分隔符/非 STAT 行/空名字 （STAT pid 1）均报 Malformed；
• 错误消息的转义与截断：普通文本原样保留，回车换行等控制字符被转义成单行可读的形式， 0x7F 写成 \u{7f}，超过 64 个字符的部分被截断并以 ... 结尾；
• stats 的定帧：首行就属于数据段（STAT pid 1234\r\nEND\r\n 必须解出 1 条而不是 0 条）， 缺少末尾 END 时返回 None 继续等待，中途冒出 STORED 这类非 STAT/END 行才算错帧；
• VERSION 行：偏移量取前缀的字节长度，否则版本串会剩下一个前导空格；
• Decoder 的缓冲上限：limit() 默认是 DEFAULT_BUFFER_LIMIT、with_limit 如实回报； 未越界时只等待（并如实报告 buffered()），越界时抛 ProtocolError::Desynchronised(limit, buffered)；而头里声明的块连分帧都放不进 limit 时 不等缓冲填满就用 Malformed 报出，消息里同时给出声明字节数、计入分帧后的需求与上限； 多块检索逐头按整份 limit 判定、而不是按前面块用剩的额度，所以这道头检查对整段序列只是 必要条件——每个块单独都放得下、合起来超过 limit 的响应不会被它拦下：整段一次到齐时照常解出 全部块，同样的字节若缺了收尾的 END 堆在缓冲里，才由 next() 按 Desynchronised 报出； resync() 丢弃失步残片后，解码器能立刻从下一个完整响应上重新同步；
• expect_values / expect_status / expect_counter / expect_version / expect_stats： 响应种类不符即 Malformed；
• 校验：validate_key 对 0x1F、0x7F 等控制字符与长度边界的判定（含多字节字符按 UTF-8 字节计数的 249 通过 / 252 拒绝），并且逐个断言拒绝时的消息原文——空 key 那条不带 参数，超长那条报出 251 与 250 两个数，撞上制表符、空格、0x7F 时把违规字节转义后附在 key 后面；validate_request 覆盖每条带 key 的命令，以及三条管理命令的参数边界 （cache_memlimit 拒绝负数、slabs reassign 的 src 以 -1 为下限而 dst 以 0 为下限 且两者分别报出是哪一边出错、slabs automove 只收 0..=2）； stats 的段名另有一组用例——detail on、cachedump 1 100 这类多词段名通过，而空段名、 首尾空格、连续两个空格、含制表符的段名都拒绝；空段名与超长段名同走长度判据，报出实际字节数 与 1..250；首空格、尾空格、连续两个空格留下的空词收敛到同一条 stats section has an emptyword；非法字节被转义后随段名带回；
• 流水线用到的私有助手：Decoder 抛 Remote 前先把那一行消费掉（buffered() 只剩紧随的 8 字节，下一次 next() 读到的是它后面的 STORED），Malformed 则原样留在缓冲里 （buffered() 仍是 14 字节，因为没人知道下一个响应从哪里开始，只能交给 resync()）； 槽位表由 read_replies 直接驱动——[true, false, true] 只读两次，第二条响应落进第三个槽位、 中间那格是 None，证明「静默请求不占一次读」；remaining_reply_count 从某个槽位起只数仍被 欠着的应答（[true, false, true] 依次是 2 / 1 / 1 / 0）；validate_pipeline 对空批次放行、 对 quit 无论排在哪个位置都拒绝、并把单条请求的校验（如空 key 的 delete）应用到批次里的 每一个成员；discard_replies 读走指定条数后静默返回（第三条应答仍留给下一次读取），连接已死 时也静默停下，不把 TransportError 漏给调用方。

#运行方式

moon check                 # 类型检查（CI 的第一步）
moon build                 # 构建整个模块（含 cmd/main，CI 的第二步）
moon test                  # 跑测试（CI 的第三步）
moon coverage analyze      # 查看未被测试覆盖的行
moon run cmd/main          # 跑演示程序
moon info && moon fmt      # 更新接口文件并格式化

#十、边界与已知限制

• pipeline 不是事务，也不是万能的批入口：它只是把一批命令一次写完再一次读完，省掉往返 延迟，但不改变协议语义——批次里各条命令依旧彼此独立，服务器也不保证它们原子执行；quit 被明确拒绝（服务器在其后退场，后面写出去的请求再也拿不到应答，错误将无从归属）。批内若某条 命令回了 Remote 错误，pipeline 会先把剩余应答读完丢弃再抛出，因此连接仍停在一个干净的分帧 边界上，但那一批里已经成功执行的命令照样生效了，调用方不能据此认定整批未执行。
• 批次中途失败后 Client 不可复用：两种情形收场相同。其一是写出阶段失败——pipeline 一条条往外写，若写到第 k 条时通道断开，前 k-1 条已经在线上了，服务器会照常为它们各回一条； 其二是非 Remote 的解码失败（Malformed / Desynchronised）——那时读取循环停在中途， 线上仍欠着后面每个请求各一条应答。两种情形下，未读的应答都读不回也扔不掉：resync() 只清解码缓冲，清不掉线上字节。此后再用同一个 Client 发命令，读到的会是这批的残留应答。 只能丢弃该 Client 并重建连接；批次越长，这个窗口越大。这也让「先全校验、再开始写」多了一层 含义：校验拦下的批次，一个字节都还没出去，连接是干净的。
• noreply 的错误会错位：服务器对 noreply 命令仍然可能返回错误行（例如 CLIENT_ERROR bad data chunk、SERVER_ERROR out of memory）。send 不读这些字节，它们会留在 缓冲区里，被下一条 execute 当成自己的响应，从而报出位置不对的 Malformed 或 Remote。 文本协议的 noreply 只抑制正常应答，并不抑制错误；需要严格的错误归属时请用 execute。 混进 pipeline 时症状更隐蔽：多出来的错误行没有对应槽位，会顶替掉后面某条命令的应答，让整批 结果整体错位一格，pipeline 返回的数组看上去仍然“长度正确”。因此把 noreply 与有应答的 命令混在同一批里时，请只把 noreply 当作“我不关心它成功与否”的加速手段，不要依赖批次结果的 下标与命令严格对应；需要严格归属时，把 noreply 命令和其余命令分成两批（或改用 execute）。
• 失步要靠调用方恢复：Decoder 只抛出 ProtocolError::Desynchronised(limit, buffered)， 不会自己丢弃残片；要先显式 Client::resync()（或直接操作 Decoder::resync()，或另建 Client）才能重新同步，在此之前缓冲区里的字节始终还在。Remote 不属于失步：出错的那一行已经 被消费掉了，连接可以直接继续用；只有 Malformed 会原样留在缓冲里（没人知道下一个响应从哪里 开始），需要 resync() 才能继续。
• 有字节上限，没有时间上限：DEFAULT_BUFFER_LIMIT（8 MiB）拦的是“缓冲无限增长”， 不是“响应迟迟不来”。Connection::read 阻塞多久完全由实现决定，本库不做超时。同一个上限 也界定了 VALUE 头里 <bytes> 的合法范围：块要连同头行、块尾的 \r\n 与收尾的 END 行 一起装进缓冲区，装不下的声明会因为永远等不到数据而当场判为 Malformed（见第五节）。 因此服务端若配置了比当前上限更大的单条 item 上限，默认配置下本库无法表达——需要放宽带块时 用 Decoder::with_limit / Client::with_limit。
• 仍未覆盖的协议：二进制协议、meta 协议（mg/ms/md/ma）、SASL 认证、UDP 传输、 压缩值等都不支持；文本协议这边的管理命令覆盖 stats [<section>]（段名本身可带参数， 如 stats detail on）、cache_memlimit 与 slabs reassign/automove，lru_crawler、 lru tuner、shutdown 等仍未支持。
• 校验不做数值范围检查：flags、exptime、cas 的取值本身不校验，exptime 为负会直接 编码成 -1 交给服务器裁决；真正越界的是解码侧——parse_decimal 在 u64 上界之外报 Malformed 而不是静默回绕，parse_decimal_int 对超过 i32 上界的字段同样报错。
• 一次取回的 VALUE 块全部驻留内存：decode_value_blocks 已由递归改为循环，不再随块数 加深调用栈，但一个响应里的全部块仍会同时构造出来，缓冲区也会持有整段字节直到 next() 消费掉。
• 计数器命令对非数字值：memcached 会回 CLIENT_ERROR cannot increment or decrementnon-numeric value，在本库中表现为 ProtocolError::Remote(Client, ...)。
• quit 不读响应：这是协议约定（服务器不回复）；若调用方在 quit 之后继续用同一 Client，行为未定义。pipeline 因此在校验阶段就拒绝 quit，避免把“后面写出去的请求永远 等不到应答”这种状态带到运行期。
• ScriptedConnection 仅用于测试：它在预置的 chunk 回放完之后返回空字节，真实实现（socket 等）需要自行 实现 Connection 并遵守同样的约定——空结果表示对端关闭。