Guest→Host 系统调用负载契约 v1#
适用范围#
本文档规定 MuduDB guest→host 系统调用所使用的、由项目自有的二进制线格式。
该线格式保留 Phase 1 引入的 16 字节头部,并用 MessagePack 编码消息体。
MessagePack 布局是项目可控的:它派生自
mudu_binding/wit/ 中的权威 WIT 定义,由 mgen
生成到 Rust 的自定义 serde 实现以及 C# 的自定义 MessagePack formatter。
实现仅把 rmp_serde(或 C#/AssemblyScript/Python 端的等效 MessagePack 运行时)作为底层编解码器;
不使用默认的 rmp_serde derive 行为,因为后者会把 Rust 枚举变体序列化成 map 或字符串,
无法在不同 guest 语言之间保持稳定。
权威的 syscall 边界是 uni-syscall.wit
中声明的 WIT 函数接口。本文所述的头部与 MessagePack 消息体是运行时内部对那些 WIT 函数调用的
序列化;guest 代码应直接调用 WIT 函数,由生成的绑定处理线格式。
逻辑数据模型仍是现有的 mudu_binding::universal 类型族;本契约定义这些类型的线编码。
状态:已实现并稳定。 全部 23 种消息类型由宿主路由器
mudu_binding/src/codec/syscall_payload/
编解码,并在 runtime_wasm(kernel_sync / kernel_async)中分发。guest 端实现覆盖
workspace Rust guest、独立 Rust SDK、C# SDK、AssemblyScript 以及 Python(工具/测试验证绑定)。
已废弃的 UniDatTypeId / UniMuTypeFamily 枚举不属于本契约,且已从绑定层删除。
当类型族值需要跨边界传递时,由 UniDataType / UniScalar 承载。
注册表#
属性 |
值 |
|---|---|
格式族 |
|
魔数 |
|
当前版本 |
|
支持范围 |
|
注册表 |
|
运行时只解码当前版本。遇到不支持的版本时以 ErrorCode::UnsupportedFormatVersion
快速失败。格式版本变更时,MPK 包会针对匹配的运行时重新构建;运行时不保留旧版解码器。
同一版本同时钉入每个 MPK 包:package.manifest.json 携带 syscall_abi_version: u32
字段。打包器(mpm_build)总是写入 SYSCALL_PAYLOAD_CURRENT_VERSION(1);
runtime_wasm/src/service/app_package.rs
中的加载器对缺失字段默认取 1,并在版本不匹配时以
ErrorCode::UnsupportedFormatVersion 拒绝。FormatKind::SyscallPayload 已注册进全局
CompatibilityRouter(mudu_kernel/src/compat.rs),
v1 恒等迁移处理器位于
mudu_binding/src/codec/syscall_payload/migrate/;
迁移单元是完整帧(含 16 字节头部)。
版本历史#
版本 |
日期 |
摘要 |
|---|---|---|
1 |
2026-07-01 |
16 字节头部(魔数、版本、标志、消息类型)加上 MessagePack 消息体。MessagePack 布局由 |
1(原地修订) |
2026-09-11 |
record/请求体从位置数组改为整数键 MessagePack map(字段号/参数号 = WIT 声明顺序 1-based,protobuf 风格);解码宽松化(接受任意整数宽度、跳过未知 map 键、缺失字段取类型默认值,proto3 语义)。variant |
负载布局#
每个系统调用请求与每个系统调用响应都编码为一条自描述消息:
+--------------------------------+
| Header(16 字节) |
+--------------------------------+
| Body(可变,MessagePack) |
+--------------------------------+
头部之外没有额外的长度前缀;WIT 传输层负责投递精确的字节区间。
头部#
所有头部字段均为大端。
偏移 |
大小 |
字段 |
描述 |
|---|---|---|---|
0 |
4 |
|
魔数 |
4 |
4 |
|
负载格式版本。当前值: |
8 |
4 |
|
保留。必须为 |
12 |
4 |
|
消息类型判别值。线头部仍保留该字段用于路由,但合法取值集合由 |
version 是负载格式版本,而非 WIT 接口版本。它只在编码规则本身变化时
递增——例如整数语义、帧头布局、map/数组结构规则的变化。schema 演进(追加字段、
追加 message_kind、追加 variant tag)由字段号机制在版本内吸收,不递增 version。
uni-syscall.wit 中的 WIT 函数接口是存在哪些系统调用、以及它们的请求/响应类型的权威定义。
运行时把每个 WIT 函数映射到同一条内部 16 字节头部 + MessagePack 路径;因此 message_kind
判别值作为实现细节保留,用于运行时路由。
当前 syscall 消息类型#
Kind |
WIT function |
|---|---|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 |
|
11 |
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
|
消息体编码#
消息体是单个 MessagePack 值。具体字节序列由 mgen 模板控制,不得从通用的
rmp_serde 默认行为推断。
权威来源#
权威模式是 mudu_binding/wit/ 下的 WIT 文件集合:
WIT 文件 |
Rust 生成类型 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
syscall 函数接口 |
mgen 读取这些 WIT 文件并输出语言相关的源文件。Rust 使用
mudu_gen/templates/rust/ 中的模板;C# 使用
mudu_gen/templates/csharp/ 中的模板。
MessagePack 编码规则#
生成代码遵守以下规则,覆盖所有默认 rmp_serde 行为:
WIT 构造 |
MessagePack 编码 |
|---|---|
|
MessagePack map,键为字段号(声明顺序 1-based 的整数),值为对应字段的编码。编码时按键号升序写出全部字段。 |
WIT func 参数列表 |
与 record 相同:参数号(声明顺序 1-based)为键的 MessagePack map。 |
|
两元素 MessagePack 数组 |
|
裸 |
|
编码后的 |
|
|
|
MessagePack 数组 |
|
MessagePack str。 |
|
func 级为 MessagePack bin;record 上下文中为 MessagePack 整数数组(因此 |
原始标量( |
标准 MessagePack 整数/浮点/布尔/字符串表示。 |
|
与 |
所有消息体值都经过每种语言唯一的手写通用运行时(Rust 端为
mudu_binding::universal::mp_wire):它按 rmp_serde 1.3.1 的规则做规范编码(最短整数、
str8/bin8 阈值),并做宽松解码——接受任意 MessagePack 宽度的整数(收窄时做范围检查)、
map 中未知键跳过、缺失字段取类型默认值(proto3 语义)、map 键顺序任意;record/request
的结构(必须是 map)、tuple 长度、未知 variant 标签仍然严格拒绝。C#、AssemblyScript
与 Python 端使用从同一份 WIT 生成的等价运行时代码。
OID / UniOid#
OID 是逻辑上的 128 位对象标识符(mudu::common::id::OID)。在线编码为含有两个
u64 字段的 record,即 MessagePack map {1: h, 2: l}。解码器将逻辑
OID 重建为 ((h as u128) << 64) | (l as u128)。
变体标签表#
以下标签派生自 mudu_binding/wit/ 中的 WIT 声明。
此处列出仅为方便查阅,WIT 文件仍是权威来源。
UniScalarValue — variant 标签:
标签 |
变体 |
负载 |
|---|---|---|
0 |
|
|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
|
|
5 |
|
|
6 |
|
|
7 |
|
|
8 |
|
|
9 |
|
|
10 |
|
|
11 |
|
|
12 |
|
|
13 |
|
|
14 |
|
|
15 |
|
|
16 |
|
|
17 |
|
|
18 |
|
|
19 |
|
|
20 |
|
|
注意:WIT uni-scalar-value 用 blob 表示二进制标量负载;UniScalarValue::Blob
承载 Vec<u8>。U128 / I128 使用 16 字节大端字节数组,以便在不支持原生 128 位整数
MessagePack 类型的 guest 语言之间保持可移植性。
UniDataValue — variant 标签:
标签 |
变体 |
负载 |
|---|---|---|
0 |
|
|
1 |
|
|
2 |
|
|
3 |
|
|
UniDataValueField 是 record,线形状为 {1: field_name: string, 2: field_value: UniDataValue}。
UniDataType — variant 标签:
标签 |
变体 |
负载 |
|---|---|---|
0 |
|
|
1 |
|
|
2 |
|
|
3 |
|
|
4 |
|
|
5 |
|
|
6 |
|
|
7 |
|
|
注意:box<T> 不是独立变体。它仅在 WIT 中作为递归类型(array、option)的语法糖出现,
在线上是透明的。
UniScalar — WIT enum,裸 u32 判别值:
值 |
名称 |
值 |
名称 |
|
|---|---|---|---|---|
0 |
|
11 |
|
|
1 |
|
12 |
|
|
2 |
|
13 |
|
|
3 |
|
14 |
|
|
4 |
|
15 |
|
|
5 |
|
16 |
|
|
6 |
|
17 |
|
|
7 |
|
18 |
|
|
8 |
|
19 |
|
|
9 |
|
20 |
|
|
10 |
|
UniScalar 与 UniScalarValue 现在使用相同的标签编号。
复合类型布局#
每个 record/variant 的 MessagePack 编码遵循上述通用规则。以下列出字段号与负载形状, 供快速参考(record 的键为声明顺序 1-based 字段号):
UniOid—{1: h: u64, 2: l: u64}。UniSqlStmt—{1: sql_string: string}。UniSqlParam—{1: params: list<UniDataValue>, 2: param_names: option<list<string>>}。UniTupleRow—{1: fields: list<UniDataValue>}。UniFieldAttr—{1: attr_name: string, 2: attr_value: string}。UniRecordField—{1: field_name: string, 2: field_type: UniDataType, 3: field_attrs: list<UniFieldAttr>}。UniRecordType—{1: record_name: string, 2: record_fields: list<UniRecordField>}。UniResultType—{1: ok: option<UniDataType>, 2: err: option<UniDataType>}。UniResultSet—{1: eof: bool, 2: row_set: list<UniTupleRow>, 3: cursor: list<u8>}。UniError—{1: err_code: u32, 2: err_msg: string, 3: err_src: string, 4: err_loc: string, 5: err_details: list<u8>}。UniQueryArgv—{1: oid: UniOid, 2: query: UniSqlStmt, 3: param_list: UniSqlParam, 4: param_desc: option<UniRecordType>}。UniCommandArgv—{1: oid: UniOid, 2: command: UniSqlStmt, 3: param_list: UniSqlParam, 4: param_desc: option<UniRecordType>}。UniQueryResult—{1: tuple_desc: UniRecordType, 2: result_set: UniResultSet}。UniCommandResult—{1: affected_rows: u64}。UniCommandReturn— variant:ok(UniCommandResult)或err(UniError)。UniQueryReturn— variant:ok(UniQueryResult)或err(UniError)。UniSessionOpenArgv— 当前为手写 Rust record,线形状为{1: worker_id: UniOid}。它尚未对应独立的 WIT 文件;若未来纳入 WIT,编码规则与本节相同。
与旧版 session 编解码器的关系#
全部 23 种类型——包括 KV 系统调用(Open…Range)——现在都通过
mudu_binding/src/codec/syscall_payload/
中的带帧 MessagePack 路径编解码:每个负载包进 16 字节头部,错误使用项目控制的 MessagePack
Result<T, E> 编码,替代旧版 MERR 魔数逃逸。此前 handle_sys_session.rs 中的手写二进制
session 编解码器遵循的约定与本契约的基础类型一致;统一迁移到项目控制的 MessagePack 路径的
Phase 2 工作已完成。
完整性机制#
魔数校验: 解码器拒绝魔数不为
0x4D53_5350的消息。版本校验: 解码器拒绝任何超出
[1, 1]的版本,映射为ErrorCode::UnsupportedFormatVersion。标志校验: 解码器拒绝任何非零
flags值。消息类型校验: 解码器拒绝未知/
0的message_kind值。长度校验: 解码器要求头部至少 16 字节。
MessagePack 结构校验: 解码器拒绝格式错误的 MessagePack 负载、消息体尾部多余字节、 未知变体标签,以及不是 map 的 record/请求体。map 内部的解码是宽松的(未知键跳过、 缺失字段取默认值、整数宽度任意),但收窄溢出与类型不符仍被拒绝。
UTF-8 校验:
string字段必须为合法 UTF-8。
消息体结构性解码失败映射为 ErrorCode::Decode。魔数不匹配经兼容性注册表映射为
ErrorCode::CorruptedData。
兼容矩阵#
读方 \ 写方 |
v1 |
|---|---|
v1 |
兼容 |
仅支持版本 1。
升级与回滚规则#
先区分两类变化:
编码规则变更(整数语义、帧头布局、map/数组结构规则等)——递增
version, 按下述升级流程处理。schema 演进(追加字段/参数、追加
message_kind、追加 variant tag)——在版本 内由字段号机制吸收,不递增version,也不要求重建已部署的 MPK:旧包与新包靠宽松解码(未知键跳过、 缺失字段默认)继续互通;只有需要使用新字段的 guest 才重新生成绑定并重打包。
规则:
升级(编码规则变更): 未来的 v2 会更改头部
version。引入 v2 时,MPK 包针对 匹配的运行时重新构建,离线迁移处理器转换已存的 fixture/测试数据。无旧版解码器: 运行时只解码当前版本。版本不支持的消息以
ErrorCode::UnsupportedFormatVersion快速失败。无跨编码版本 MPK 支持: 包在每次 ABI 版本递增时重新构建;版本机制的存在是为了让 未来的编码规则升级显式可控,而非保留跨版本兼容性。
废弃策略#
版本 1 仅在满足以下条件后方可废弃:
所有 guest 绑定(Rust、C#、AssemblyScript、Python)都能发出并接受后继编码版本(v2)。
新版本已作为默认至少一个发布周期。
MPK 包已针对新运行时重新构建。
废弃针对的是编码版本;版本内 schema 演进(字段号追加)不产生可废弃的旧版本。
参考#
注册表:
mudu/src/compat/mod.rsWIT 模式源:
mudu_binding/wit/Syscall 函数接口:
mudu_binding/wit/uni-syscall.wit宿主带帧编解码器(权威):
mudu_binding/src/codec/syscall_payload/mgenRust 模板:mudu_gen/templates/rust/mgenC# 模板:mudu_gen/templates/csharp/universal类型族(Rust):mudu_binding/src/universal/旧版手写 KV 编解码器:
mudu_binding/src/codec/handle_sys_session.rsSQL 请求/响应编解码器:
mudu_binding/src/codec/handle_sys_incoming.rs、handle_sys_outcoming.rs宿主系统调用入口:
runtime_wasm/src/interface/kernel_sync.rs、kernel_async.rs集成指南:
doc/cn/abi/guest_host_abi.cn.md