msgpack

使用 Buffer 传输二进制 MessagePack，以 var 表达动态值。

版本 1.0.0 · C / xlang · 无扩展库依赖

当前冻结发布版的 XLang 字典传入 encode(var) 会在 foreign 容器边界报 NotImplementedError；下面的字典范例因此暂不能运行。2026-10-29 Windows/Linux 默认门禁均过前 43 阶段（含五个独立程序），第 44 阶段仍在该语言字典正例失败。C/标量与二进制通路的通过不代替完整语言容器和发布签收。

快速开始

import msgpack

var source = {"name": "xlang", "count": 7}
Buffer packed = msgpack.encode(source)
var document = msgpack.decode(packed)
println(document["name"])
assert msgpack.decode(msgpack.fromHex("c0")) == null

输出 xlang。合法 nil 返回 xlang 的 null；畸形输入抛 ValueError。

标准时间戳帧

import msgpack

var epoch = msgpack.decode(msgpack.fromHex("c80004ff00000000"))
assert epoch == time(0)
assert msgpack.toHex(msgpack.encode(epoch)) == "d6ff00000000"

时间戳类型 -1 按 4/8/12 字节载荷解释，不受 ext8/ext16/ext32 头部宽度影响；编码仍使用最短 timestamp32/64/96。其他完整但未建模的扩展类型抛 NotImplementedError；保留标记 c1、截断帧、非法时间戳长度和非整微秒抛 ValueError。超过载荷预算先报范围错误，不分配超限载荷。依据 MessagePack 官方规范。

成对 examples/timestamp_frames.xl 与 timestamp_frames_c.c 覆盖六入口和五行固定输出，包含非最短时间戳头、负时间、NUL 与非 UTF-8 二进制。新的 50,650 项帧/截断/分类检查和 18 条分配失败恢复路径通过；Python 标准库独立核对 530 个时间点、1,599 帧，GCC、TCC 直跑与独立程序逐字一致。此例不替换原语言字典正例。

接口与边界

入口	用途
`encode(value) / decode(Buffer)`	在 var 与 MessagePack 二进制之间转换。
`encodeBytes(Buffer) / decodeBytes(Buffer)`	直接处理 bin 字节串。
`toHex(Buffer) / fromHex(text)`	诊断或固定测试向量；HEX 文本拒绝内嵌 NUL，C 文本入口按 128 MiB 限界扫描。

映射 null、bool、int、uint64、float、UTF-8 字符串、字节、时间、数组和文本键字典。标准 uint64 可编码至 2^64-1；解码时不超过 INT64_MAX 的正整数沿用 int，超过时用 uint64，线格式不保留较小正整数的原始有符号类型。文本键和值均按显式长度处理，内嵌 NUL 不会截断；HEX 文本入口拒绝 NUL。time 使用标准 timestamp 扩展类型 -1 的 32/64/96 位布局；解码 float32 后转换为 xlang 浮点。时间精度为微秒，外部非整微秒纳秒值与超界时间报错，不静默舍入。其他 ext 类型及非文本映射键不在本包模型内。重复键、坏 UTF-8、截断和尾随字节报错。二进制输入/输出上限 64 MiB，调试用 HEX 文本上限 128 MiB；C 入口将缺失输入报为参数错误、超限报为范围错误；这些输入错误在 XLang 层抛 ValueError，分配故障另抛 MemoryError。整个文档的数组项与字典项合计最多 100 万，编解码采用相同预算；深度最多 64。

C 对照

#define XRT_MODULE_ALL
#include "xrt.h"
#include "msgpack_native.h"

int main(void)
{
    const unsigned char wire[] = {0xc0};
    xvalue* value = xmsgpack_decode(wire, sizeof(wire));
    if (value == NULL) return 1;
    int ok = xrtValueType(value) == XVALUE_NULL;
    xrtValueRelease(value);
    return ok ? 0 : 2;
}

xmsgpack_encode(NULL) 表示缺少参数，返回 NULL 并设置 XERR_ARGUMENT；传入 xrtValueNull() 才会编码合法 nil。C 解码失败返回 NULL，合法 nil 返回拥有型 XVALUE_NULL。拥有型 Buffer 和 HEX 字符串分别用 xrtBufferDestroy、xrtFree 释放。完整 C/XLang 对照范例位于 extlibs/msgpack/examples/。

examples/msgpack_c.c 可直接使用 xl run release/extlibs/msgpack/examples/msgpack_c.c 单文件执行；成对 C/XLang 范例覆盖六个公开入口，二进制样本含 NUL 与 0xFF，固定 bin8 线格式 c40300ff41。Windows/Linux 门禁将三条运行路径与独立预期输出对照，Linux ASan 还覆盖参数和文件写入失败时的释放路径。

验证状态

2026-10-21 XLang 六个公开入口的分配故障用例改为逐入口扫描到首次成功，并在每次失败后立即清除故障、重试。Windows/Linux 正式运行器均通过；包实现及线格式未改，完整 AOT 的共享阻断未变。

powershell -NoProfile -ExecutionPolicy Bypass -File release/extlibs/msgpack/test/check.ps1
bash release/extlibs/msgpack/test/check.sh

从仓库根目录执行；CC、PYTHON 可指定工具。缺少 Python 或 C 编译器明确失败，不静默跳过。默认门禁保留原语言容器正例为必过项；失败保留独占目录、原生日志与输入指纹。Linux 原生 C 测试开启 ASan/UBSan/泄漏检查，两平台均检查八个实际生成的 C 原型及 C/XLang 固定输出。包内详情源是维护源，未据此宣称外部官网已部署。

2026-10-19：Windows 严格 GCC、C/XLang 边界、固定种子畸形输入及双语范例通过；Linux 同一包级脚本完成 C ASan/UBSan、XLang 边界与 C/XLang 范例逐字节对照。六个公开入口的逐点分配故障扫描保留 XERR_MEMORY 并可恢复；新增文本键和值内嵌 NUL 的固定线格式和 XLang 往返验证。标准 timestamp 的 32/64/96 位固定向量及与 Python msgpack 1.2.3 的双向互通通过，非整微秒与超界时间明确拒绝。累计项数的编解码预算已统一并有红绿回归。当前发布版的最小 XLang 用例在将语言字典传给 msgpack.encode 时抛 NotImplementedError；原生入口未识别动态值的字典类型。完整 XLang 边界、双语和 AOT 门禁待共享 foreign var 容器投影修复后重跑；旧版共享缺符号不是当前首个阻断，不签收本版发布形态。详情见包内 README 和阻断复现。