Rust SDK
Rust SDK 是 XiHan Spec 的 Rust 实现,仓库是 XiHanFun/framework-sdk-rust:提供原语层、清单、调用上下文、管道与操作契约,以及进程外插件运行时(cargo feature plugin),语义与线上编码按规范的 RFC。参考实现是 .NET(XiHan.Framework),规范写到的行为与 .NET 宿主一致。规范以 submodule 放在仓库的 spec/,一致性由规范仓库的向量验证:测试直接读取 spec/conformance/vectors/,不复制向量文件。
这一页讲安装、模块、最小示例、怎样写一个插件、与宿主共用的行为、Rust 的语言映射与设计取舍,以及一致性的现状。规范怎样组织、各语言 SDK 的对照见规范与多语言;宿主一侧怎样加载插件见进程外插件。
安装
cargo add xihan-framework写插件时打开 feature plugin:
cargo add xihan-framework --features pluginplugin 模块是可选的:它带来 tonic、prost 与 tokio,不打开这个 feature 时这些依赖都不进来,其余模块也不依赖任何异步运行时。最低 Rust 版本见仓库 Cargo.toml 的 rust-version(edition 2024 的要求)。
还没有发布到 crates.io,那里的版本只是名字占位。
模块
整个 SDK 是一个 crate xihan-framework,各语言的 SDK 都只有一个包;领域词与规范术语表(conventions/vocabulary.md)一致,只换本语言的大小写风格。
| 模块 | 内容 | 规范 |
|---|---|---|
primitives | Error / 错误码、Result<T>(标准库 Result<T, Error>)与线上编码 WireResult、Maybe<T>(Option<T>)、TypedId<Tag, V>、LifecycleState、PipelineStage、Stability、Baggage 键与值约束、消息键与模板(可按区域取数字符号)、Catalog 与进程默认解析器、FrameworkError;primitives::json:JSON 文本的共同读取检查(向量 primitives/json-text.json)、按值模型读入(json::from_slice)与写出(json::Model、json::to_value) | RFC-0001、RFC-0010、conventions/ |
manifest | xihan.manifest.json 的模型、读取、按规范排版的写出与校验,能力声明与依赖文本(版本不带前导零、不超过 2147483647);读取按 RFC-0002 解析规则 2 的顺序(向量 manifest/manifests.json):JSON 文本 → null → 按 Schema 逐项核对 → 跨字段约束,错误都是 KERNEL_CAPABILITY_006,带消息键与路径或清单 ID | RFC-0002、manifest/manifest.schema.json |
invocation | Context:可等待、父子传播的 CancellationToken,后台定时器触发的截止时间,W3C 追踪(traceparent 只认版本 00 与小写十六进制,不合法的当作没有给出;采样只看最低位,写出 00 或 01,没有上游时写 01)、已登记的 Baggage(已登记键的值非空、按 UTF-16 码元最多 256、不含控制字符,幂等键除外:构建上下文时按外部输入丢弃不合的成员、保留原值,with_baggage 给出不合的值即 panic)、按类型存取的对象袋;超时与取消只按截止令牌归因为 KERNEL_TIMEOUT_001 / KERNEL_CANCELLED_001 | RFC-0003 |
pipeline | 十一阶段的 Builder:use_middleware / use_at / use_named_instance、before / after(按名字登记的实例用实例名,其余用中间件名;约束的主体在声明时必须已登记)、describe / dump / build;排序规则、错误码 KERNEL_PIPELINE_00x 与错误消息的英文原文(向量 pipeline/ordering.json,按名字登记的实例写成 中间件名[实例名]):登记方法以 &mut self 返回 Result,重复登记、约束主体未登记在登记时即报,约束目标未登记、跨阶段与成环在排序时报;中间件与终点都是异步的 | RFC-0004 |
operation | Contract、Schema、异步 Handler<Req, Res>、容量 10000 的 Registry、经完整管道执行的 Invoker(XGI:JSON 请求与响应;另有不经 JSON 的类型化入口);管道里带三个内置步骤,位置与 .NET 的内置中间件相同;内核错误的码、键、参数与 en-US 模板同向量 kernel-messages.json(type_mismatch 只带 id);载荷先过共同的 JSON 读取检查,按文本顺序报第一处问题,reason 是 JSON 路径(向量 operations/payload-reasons.json);任意 JSON 的成员用 json::Json 原样保留数字;响应在管道结束之后才编码,写不出时报 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception;中间件以成功短路而没有响应时报 KERNEL_UNEXPECTED_001 + kernel.operation.no_response | RFC-0011 |
plugin(feature plugin) | 进程外插件运行时:Plugin 读清单与宿主下发的环境变量,在监听之前核对声明,监听本机端点、向 stdout 写握手行,以 gRPC 服务端提供 xihan.plugin.v1 的 Plugin 服务(握手、配置、启停、健康与健康推送、调用、事件投递),每个 RPC 先按常数时间核对会话令牌;生命周期按 lifecycle.md §7 的次序表、配置节、就绪、健康、停止与收尾执行,状态机用 LifecycleState;Invoke 经 operation::Invoker 与完整管道执行,上下文从 InvocationMetadata 还原;Host 回调 Host.Invoke 与 Host.Publish,发出之前在本地核对权限与租户,gRPC 状态按规范的表映射;Logger 往 stderr 写 JSON 行日志;plugin::v1 是 plugin.proto 的生成代码;向量 plugin/ 下的 handshake-lines.json、host-addresses.json、protocol-versions.json、deadlines.json、plugin-messages.json、callback-status.json | RFC-0017、plugin/handshake.md、plugin/lifecycle.md、plugin/invocation.md、plugin/plugin.proto |
快速开始
use std::sync::Arc;
use std::time::Duration;
use serde::{Deserialize, Serialize};
use xihan_framework::invocation::Context;
use xihan_framework::operation::{self, Contract, EXPOSE_HTTP, Invoker, Registry, Request};
use xihan_framework::pipeline::{self, APP_OWNER, Builder, Placement};
use xihan_framework::primitives::{BAGGAGE_TENANT, Error, PipelineStage, Stability};
#[derive(Clone, Deserialize)]
struct CreateOrder {
quantity: u32,
}
#[derive(Serialize)]
struct OrderCreated {
quantity: u32,
tenant: Option<String>,
}
async fn run() -> Result<(), Box<dyn std::error::Error>> {
let registry = Arc::new(Registry::new());
registry.add(
Contract::new("orders.create").with_stability(Stability::Experimental).with_expose([EXPOSE_HTTP]),
operation::handler_fn(|ctx: &Context, request: CreateOrder| {
Box::pin(async move {
if request.quantity == 0 {
return Err(Error::validation("ORDERS_VALIDATION_001", "orders.quantity.invalid").with_detail("quantity", 0));
}
Ok(OrderCreated { quantity: request.quantity, tenant: ctx.tenant().map(str::to_owned) })
})
}),
)?;
let observe = pipeline::from_fn("Observe", |ctx, next| {
Box::pin(async move {
let outcome = next.run(ctx).await;
if let Err(error) = &outcome {
eprintln!("{} failed: {error}", ctx.trace_id());
}
outcome
})
});
let mut builder = Builder::new();
builder.use_at(observe, PipelineStage::Observe, Placement::End, APP_OWNER)?;
print!("{}", builder.dump()?); // observe Observe
let invoker = Invoker::new(registry, &builder)?;
let ctx = Context::builder().timeout(Duration::from_secs(2)).baggage(BAGGAGE_TENANT, "t1").build();
let payload = invoker.invoke(&ctx, Request::new("orders.create", r#"{"quantity":2}"#)).await?;
assert_eq!(payload, br#"{"quantity":2,"tenant":"t1"}"#);
Ok(())
}- 中间件、处理器与管道终点返回
BoxFuture(Pin<Box<dyn Future + Send>>),写Box::pin(async move { … });本 crate 不依赖任何异步运行时,future 交给 tokio、futures::executor::block_on或任何执行器。Invoker::invoke与invoke_typed的签名写明返回Send的 future,invoke_owned返回'static的 future,可以直接tokio::spawn。 - 可恢复失败返回
Err(Error),错误码按<领域大写>_<KIND>_<NNN>,文案用消息键 + 参数(Error::validation(code, key).with_detail(…));Error::message先按primitives::set_default_messages设置的解析器解析,再按 SDK 自带的 en-US 模板(primitives::builtin_catalog(),即 SDK 与宿主共用的内核错误,逐字同向量kernel-messages.json),都没有时是「键 (参数)」。配置期有登记键的错误(如操作重复登记)以FrameworkError::with_message带上键与参数,to_error()一并转出。 - 编程错误(不合文法的错误码、消息键或 Baggage 键)panic,各函数的文档写明 panic 条件;panic 的内容是
FrameworkError本身(std::panic::panic_any),不是字符串,接住后用downcast_ref::<FrameworkError>()取出;标准库缺省的 panic hook 对它只打印Box<dyn Any>,要看到码与说明就装自己的 hook。来自不可信输入的值先用is_error_code、is_baggage_key_well_formed判断,或用Error::try_new。清单校验、管道排序、操作登记等配置期失败返回FrameworkError。 Context的截止时间由进程里一个后台线程(xihan-deadline-timer,第一次登记截止时间时启动)按时触发;Context::done()在调用方取消或到达截止时间时完成,Context::cancellation()给出KERNEL_TIMEOUT_001(kernel.invocation.deadline_exceeded)或KERNEL_CANCELLED_001(kernel.invocation.cancelled)。调用器的管道里有三个内置步骤,都按归属xihan.kernel.core(operation::KERNEL_OWNER)放在所在阶段的Beginning,与同位置的中间件按 RFC-0004 排序:Observe 阶段的ObserveMiddleware把排在它之后的中间件与处理器的 panic 翻译成KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception(内容是FrameworkError时它进inner),排在它之前的 panic 原样交给调用方;Resilience 阶段的DeadlineMiddleware在进入时按时钟核对截止时间,已到即报KERNEL_TIMEOUT_001+kernel.invocation.deadline_before_start,后面的中间件与处理器不执行(Ingress 与 Observe 阶段照常执行),下游把取消写成KERNEL_CANCELLED_001的结果而截止令牌已触发时改报KERNEL_TIMEOUT_001+kernel.invocation.deadline_exceeded(RFC-0003 规则 1);Validate 阶段的ValidationMiddleware解码原始调用的载荷,类型化调用跳过。进管道前只核对未登记与类型化调用的类型不符,按这个顺序。panic 的翻译要panic = "unwind"。XGI 入口在管道结束之后才把响应编码成载荷,中间件经operation::with_response看到的是编码之前的对象(类型化调用的响应同样写进这个位置,与 .NET 的FindOperationResponse一样,只是不编码);写不出(类型化的浮点是 NaN 或无穷、序列化不支持的值、序列化时 panic)时调用以KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception结束,不抛给调用方。取消与截止时间只经令牌通知:调用器与内置步骤不中止处理器、不丢弃它的 future,令牌触发之后处理器照常返回的结果就是调用的结果,处理器把取消写成结果(Err(ctx.cancellation()…))时才按令牌归因。
写一个插件
宿主一侧怎样声明、启动与降级插件见进程外插件;这一节是插件一侧用 Rust 的写法。
cargo add xihan-framework --features plugin
cargo add tokio --features macros,rt
cargo add serde --features deriveuse std::sync::Arc;
use serde::{Deserialize, Serialize};
use xihan_framework::operation::{self, Contract, Registry};
use xihan_framework::plugin::{MANIFEST_FILE_NAME, Plugin};
#[derive(Deserialize)]
struct Ping {
text: String,
}
#[derive(Serialize)]
struct Pong {
text: String,
}
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let registry = Arc::new(Registry::new());
registry.add(
Contract::new("pings.create"),
operation::handler_fn(|_ctx, ping: Ping| Box::pin(async move { Ok(Pong { text: ping.text }) })),
)?;
// 握手交给宿主的清单必须与插件目录里的文件一致:工作目录就是插件目录,直接读它
Plugin::from_manifest_file(MANIFEST_FILE_NAME)?.with_operations(registry).serve().await?;
Ok(())
}插件目录里放可执行文件与清单 xihan.manifest.json:
{
"id": "xihan.samples.ping",
"version": "1.0.0",
"primitives": "1",
"stability": "experimental",
"kind": "plugin",
"isolation": "out-of-process",
"contributes": { "operations": [ "pings.create" ] },
"entry": "ping"
}同一段代码是 plugin 模块文档的示例,在 --features plugin 下编译。完整的示例是仓库的 examples/echo(操作、事件订阅、健康项、配置与宿主回调)。
- 清单与启动前的核对:
kind为plugin、isolation为out-of-process,entry是相对插件目录的可执行文件(Windows 上没有扩展名时宿主补.exe),primitives等于本 SDK 实现的原语层大版本1;登记的每个操作都要在contributes.operations里,健康项在contributes.health里(不在的在上报时丢掉,同一个名字只告警一次),回调宿主要在permissions里声明capability:kernel.pipeline(Host.Invoke)或capability:messaging.queue(Host.Publish);进程外插件不能写contributes.pipeline(只有 Wasm 插件能贡献中间件)。Plugin::start在监听与写握手行之前按 RFC-0002 读清单并核对上面这些、订阅的主题文法与(主题,类型)对不重复、消息目录有en-US,不合即在 stderr 记一条error日志、不监听,返回FrameworkError(宿主看到的是进程在握手之前退出)。握手交出清单的primitives、清单原文(去掉开头的 BOM,宿主逐字段核对它与目录里的文件)、只有一元操作的声明、按声明顺序的订阅(mode总写competing或broadcast)与插件自己的消息目录。 - 端点:Unix 上是 Unix 域套接字,放在临时目录下新建的私有目录里(目录
0700、名字随机、已经存在就换个名字,套接字0600;临时目录的路径含空白或不是 UTF-8 时改用/tmp,握手行的地址不含空白),停止后连同目录删掉;Windows 上是命名管道\\.\pipe\xihan-plugin-<随机>,拒绝远程客户端,用系统缺省的安全描述符:本用户、管理员与 SYSTEM 能读写,其他本机用户只能以只读打开、发不出请求(本 crate 禁用unsafe,设不了只含当前用户的访问控制表),所以与回环 TCP 一样,隔离靠会话令牌;with_network(Network::Tcp)改成只绑定127.0.0.1的回环 TCP,同机的其他用户连得上,隔离只靠会话令牌。 - 回调端点:
XIHAN_PLUGIN_HOST_ADDRESS是按宿主的偏好排序、以;分隔的一个或多个<network> <address>(plugin::parse_host_addresses,任何一项不合法整个值就不合法),运行时按顺序取第一个本平台能连的项(Network::supported():Unix 上是unix与tcp,Windows 上是npipe与tcp;宿主在 Windows 上给的是命名管道加回环 TCP,用前者,只有回环 TCP 时就经回环 TCP 回调),之后不换。变量缺失、不合法或没有能连的项时照常服务,启动时在 stderr 记一条warning,回调都以PLUGINS_UNAVAILABLE_001+plugins.host.unavailable(reason为no supported callback endpoint)失败、不发请求。 - 生命周期(
lifecycle.md§7):每个 RPC(含Handshake,以及流式调用读第一帧之前)先按常数时间核对元数据xihan-plugin-session,必须恰好有一个值并且相同,没有或有两个以上(即使其中一个对)都以Unauthenticated拒绝、不执行。次序:Handshake只在Declared,Configure只在Resolved,Start只在Configured,Stop在Declared、Draining、Stopped与停止中之外的状态,不合的以FailedPrecondition拒绝、状态不变;Health、调用与投递任何状态都可以。配置节为空等同{},不是 JSON 对象(先过共同的 JSON 读取检查)时不调Hooks::configure,以PLUGINS_UNEXPECTED_001+plugins.process.failed(phase为configure)进入Failed;Configuration::section是原文,Configuration::decode是类型化读取:成员名按 ASCII 不区分大小写,宿主写成字符串的叶子可以读成数字(按 JSON 数字的文法)与布尔(true/false,不区分大小写)。Hooks::start成功后进入Started,有健康回调时立即求一次,按结果进入Ready、Degraded或Failed(报其他状态的按Ready,panic 的按Degraded),没有即Ready,然后才应答;只有Ready与Degraded可服务,其余状态的调用与投递以PLUGINS_UNAVAILABLE_001+plugins.process.unavailable(state是状态名)失败。Health在Start之前报本地状态、没有健康项、不调回调,可服务期间每次求一次Hooks::health,只有它报的Ready、Degraded、Failed改变状态(Failed不再回来),它 panic 与报了Degraded一样:这一次的结果是Degraded、没有健康项,状态迁到Degraded,之后的结果照常决定状态;WatchHealth先推当前状态,变化时推,可服务期间每 10 秒求一次回调,进入Draining时推一次,应答Stop后结束。钩子返回的错误原样进status;panic 为plugins.process.failed,reason是panic(Rust 没有异常),panic 的内容只写进 stderr。 - 停止与收尾:启动钩子没成功过时
Stop不调Hooks::stop、应答ok;否则可服务的进入Draining、拒绝新调用,等在途调用到宽限(grace_seconds,0 按 5 秒),宽限到了触发它们的取消令牌、不再等,再调Hooks::stop(进程里最多一次,失败或 panic 只写进StopResponse.status),应答之后停止服务,serve返回Ok,进程以退出码 0 退出。stdin 关闭与 SIGTERM(Unix):可服务的进入Draining,立即触发全部在途调用的取消令牌并等它们结束,启动成功过的调一次Hooks::stop(reason为shutdown);从收到起最多 3 秒,到时不论完成与否以退出码 0 退出,正在处理的Stop同样受这个时限。Running::shutdown按同样的步骤收尾,但不结束进程。 - 调用与投递:
Invoke依次核对:未声明的操作以Unimplemented结束,不可服务为PLUGINS_UNAVAILABLE_001,然后经调用器与完整管道执行(插件进程里的管道用with_pipeline给),payload为空等同{}。上下文从InvocationMetadata还原:追踪取trace_parent(不合 RFC-0003 的文法即开始新的追踪),trace_state不进上下文,Baggage 只收已登记的键,deadline按规范的严格文法读、读不出当作没有,生效的截止时间取它与 gRPC 截止时间中较早的;宿主取消调用、停止的宽限到了或收尾时上下文的令牌触发,处理器照常在独立任务里跑完。业务失败放进Status.error:带消息键的错误text留空,由宿主按调用方的区域翻译,只有自由文本错误写text,details是 JSON 对象文本,gRPC 状态保持OK。HandleEvent依次:没有信封或方式不是空、competing、broadcast为InvalidArgument;按(主题,方式,类型)找订阅,一个也没有为KERNEL_NOTFOUND_001+plugins.event.unsubscribed;不可服务为PLUGINS_UNAVAILABLE_001;匹配的订阅按声明顺序依次执行,第一个失败即结果,处理器 panic 为KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception。不支持流式:流式操作契约的 RFC 之前插件不实现流式调用、不声明流式操作,SDK 也没有流式操作的 API;InvokeStream读第一帧,流在第一帧之前结束或第一帧不是start为InvalidArgument,是start为Unimplemented。 - 回调:处理器经
plugin::host(ctx)(调用之外经Configuration::host())取Host;invoke与publish带会话令牌,metadata取自所在的调用上下文(当前 Span 的 traceparent、UTC 七位小数加+00:00的截止时间、已登记的 Baggage、空的trace_state),gRPC 截止时间与deadline相同。发出之前依次核对,不合即不发请求:先是有没有可用的回调端点(见第 3 条);再按宿主的顺序,权限要在清单permissions里并且已被授予,否则PLUGINS_DENIED_002+plugins.callback.denied,上下文的xihan.tenant只能是宿主此刻交给本插件的某个调用或投递的租户,否则PLUGINS_DENIED_002+plugins.callback.tenant_denied;最后,回调上下文的截止时间已到(截止令牌已触发,或按时钟已过)按DeadlineExceeded(KERNEL_TIMEOUT_001),已被取消按「Cancelled,取消信号已触发」(KERNEL_CANCELLED_001),发出之后上下文取消时放弃这次调用、结果同此。Host.Publish这些都是整批的结果,信封的xihantenant不在本地核对、交给宿主逐项判定。宿主的 gRPC 状态只按invocation.md§5 的表映射(向量callback-status.json),不另按时钟或令牌改写,超时的归因交给插件自己管道里的截止时间步骤;连接失败按Unavailable,tonic 按截止时间在本端中止调用时报的Cancelled(Timeout expired)按DeadlineExceeded;Host.Publish的 RPC 失败时每一项都是同一个错误,结果数与信封数不同时每一项都是plugins.process.failed;宿主写来的Error按invocation.md§3 读入(向量error-reading.json):错误码不合文法时换成plugins.process.failed(phase一律为invoke,丢掉原来的inner),带键的错误不取text,键不合文法时是自由文本错误,details为空、只有空白、是空对象、通不过共同的 JSON 读取检查、不是对象或有读成双精度会溢出的数时当作没有细节;ok为假却没有error、或整个status缺失时是plugins.process.failed(phase为操作 ID 或publish)。 - 日志与消息键:
Logger往 stderr 写一行一个 JSON 对象(level为trace/debug/information/warning/error/critical,message,其余成员是作用域属性,运行时的每行带plugin)。运行时与宿主共用invocation.md§8 的 7 个消息键:plugins.process.unavailable、plugins.process.failed、plugins.event.unsubscribed、plugins.host.unavailable、plugins.callback.denied、plugins.callback.tenant_denied、plugins.callback.session_invalid,参数就是错误的details。宿主有它们的目录,运行时不随握手发送;SDK 自带同样的 10 种区域文案(plugin::runtime_catalog()),en-US 模板并进primitives::builtin_catalog(),要按别的区域在本地渲染时把它的to_catalog()交给primitives::set_default_messages。插件自己的目录用MessageCatalog(至少要有en-US,目录名不能是 SDK 名)。 - 验证:用规范仓库的黑盒运行器跑全部用例(需要 Go):
cd spec/conformance
go run ./cmd/xihan-conformance plugin --dir <插件目录> --exclude <会崩溃的操作 ID> --sample '<操作 ID>=<请求 JSON>'与宿主共用的行为
线上编码
线上编码与 .NET 参考实现一致:
use xihan_framework::primitives::{Error, WireResult};
let ok = serde_json::to_string(&WireResult(Ok::<_, Error>(7))).unwrap();
assert_eq!(ok, r#"{"ok":true,"value":7}"#);
let failed = serde_json::to_string(&WireResult(Err::<u32, _>(Error::literal("ORDERS_CONFLICT_001", "stale")))).unwrap();
assert_eq!(failed, r#"{"ok":false,"error":{"code":"ORDERS_CONFLICT_001","message":"stale"}}"#);读写按 RFC-0001「Result」与向量 wire-encoding.json:不带值的成功 Result<()> 只写 {"ok":true},读入时带了 value 即拒绝;有值成功的 value 必填,只有值类型是 Maybe<T>(Option<T>)时可以是 null;Error 的 code 与 message 必填,message 不能为空或只有空白(RFC-0001「空白字符」写死的 25 个码位,按显式的表判断、不用 char::is_whitespace),可选成员写成 null 不合法;Error::literal 与 Error::with_text 同样把这样的文案当作参数非法:它们 panic,try_literal 与 try_with_text 返回 PRIMITIVES_VALIDATION_001;Result 与 Error 只收 JSON 对象,未知成员忽略。Maybe<T> 有值为值本身、无值为 null;TypedId 编码为底层值。线上文本用 primitives::json::from_slice 读:它先过共同的 JSON 读取检查(RFC 8259、64 层、合法 Unicode、任何一层的重复成员,含值、细节与内部错误里面),数字按值模型(64 位范围内的整数原样往返,-0 是整数 0);直接用 serde_json::from_str 读不到这些检查。值经 json::Model 写出:整数值的浮点仍写成浮点(2.0、-0.0、1e+17),非有限的浮点写成字符串 NaN、Infinity、-Infinity。
消息模板
消息模板按 RFC-0010「模板」与向量 message-templates.json:{name} / {0},{{、}} 转义;值的文本形式是字符串原样、布尔 true / false、null 为空串、浮点在 1e-4 ≤ |x| < 1e17 时写最短往返的十进制(2.0 写 2),范围之外写 1E+17、9.9E-05,负零写 -0,数组与对象写紧凑 JSON(成员按名字的 UTF-16 码元序,超过 64 层的容器写 null)。说明符只认 ^[DdFfNnXx][0-9]{0,2}$:D、X / x 只用于整数(X 只用于非负整数),F、N 用于整数与浮点,正好一半时取偶、写出全部整数位;其余说明符(E2、0.00、yyyy-MM-dd、D100)与不适用的情形一律按无格式输出,宿主也一样。format_message 等按不变文化;format_message_in / try_format_message_in / format_value_in 按区域取小数点与分组符(规范的固定表:de-DE、es-ES、pt-BR 是 , 与 .,fr-FR 是 , 与 U+202F,ru-RU 是 , 与 U+00A0,其余区域同不变文化),Catalog 按请求的区域格式化。Describe 的参数按名字的序数顺序(UTF-16 码元),按不变文化。
清单
清单用 manifest::read 读入、manifest::write 按规范的排版写出(两空格缩进、LF、末尾不换行、成员顺序固定、列表总写、缺省值写出),各语言逐字相同;读出时与 .NET 的类型化模型一样填上缺省值(role 为 provider、activation 为 ["onStartup"]、绑定的 required 为 true、contributes 为空,$schema 不保留),写出的清单再读回来与原来的相等;读取失败的 message 是 kernel-messages.json 里清单错误的 en-US 模板。
语言映射
规范留给各语言写明的映射。
请求类型的成员
RFC-0011 规则 2。载荷按 serde 读入请求类型:成员名区分大小写,未知成员忽略(不要加 deny_unknown_fields),数字不从字符串读,整数不接受 1.0 与 1e2、超出类型的范围即不符,浮点接受整数写法、1e400 为无穷、1e-400 为 0,对象位置只收 JSON 对象。
| 规范 | Rust |
|---|---|
必填,不接受 null | 不带缺省值的非 Option 成员:n: i64 |
必填,接受 null | #[serde(deserialize_with = "operation::nullable")] name: Option<String>:缺少即不符,null 为 None |
可选,不接受 null(整数、浮点、布尔) | #[serde(default)] count: i64:缺少取缺省值,null 不符 |
可选,接受 null(字符串、数组、对象) | Option<T>:缺少与 null 都是 None |
接受 null 的数组项 | Vec<Option<String>> |
| 任意 JSON | primitives::json::Json(照原文保留数字),接受 null 表示没有时 Option<Json>;serde_json::Value 会把 1e400 读成 null、把超出 64 位的整数读成近似值 |
缺少必填成员在所在对象结束时报该对象的路径(根上为 $),类型不符按文本顺序报第一处;这两条都由 serde 派生的读入顺序给出,自定义的 Deserialize 要照样在读完对象之后再报缺少的成员。
值模型
RFC-0010「模板」。模板参数与错误细节是 serde_json::Value:
- 整数:
Value里i64范围内的整数是整数;u64的上半段(大于i64::MAX)是双精度浮点;i128/u128经json::to_value转,64 位之外的是双精度浮点。 - 浮点:
f64原样;f32先换成最接近的f64(Value::from(0.1f32)与json::to_value(&0.1f32)都是0.10000000149011612)。Value装不下非有限的浮点:Value::from(f64::NAN)是null,json::to_value(&f64::NAN)是字符串"NaN";读入时上溢的数(1e400)进f64成员是无穷,进Value是null,进json::Json照原文保留。类型化的响应里非有限的浮点写不出(调用以未处理失败结束),不写成null或字符串;只有无类型的值(错误细节、模板参数、WireResult的值)按值模型写成字符串。 - 字符:
char经json::to_value是一个字符的字符串。映射:BTreeMap<String, _>、HashMap<String, _>与结构体是对象,Vec、数组、元组是数组。 - 模型之外的类型(
chrono的时间、uuid::Uuid、枚举等):先按它们的Serialize(json::to_value,时间与 UUID 通常是字符串、单元枚举是变体名)或to_string()(Display)转成值,SDK 不另行格式化;要跨语言格式化时先转成字符串。
文法
规范里的正则都是手写的逐字节判定,整串匹配,结尾的换行不算匹配。
设计取舍
依赖:
| crate | 用途 |
|---|---|
serde(derive)、serde_json(raw_value) | Result / Error / Maybe 的线上编码、XGI 载荷编解码、清单读写;serde_json::Value 是错误细节与模板参数的值类型;raw_value 让 json::Json 照原文写出 |
getrandom | 追踪 ID、Span ID 与插件端点名的随机数 |
serde_path_to_error | 载荷不合法时给出出错位置的 JSON 路径($.lines[1].quantity):RFC-0011 规则 2 要求 reason 只写路径,serde_json 本身只报行列 |
tonic(codegen、server、channel)、tonic-prost、prost | 只在 feature plugin:xihan.plugin.v1 的 gRPC 服务端与回调客户端、protobuf 编解码;tonic 较新的补丁版本要求更高的 Rust 版本,依赖按 rust-version 解析到兼容的版本,生成代码也由同一版本的生成器生成(见仓库的 Cargo.toml 与 tools/protogen/Cargo.toml) |
tokio、tokio-stream、hyper-util | 只在 feature plugin:监听端点、在途调用、健康推送、停止宽限与 SIGTERM,回调时自建连接;只用到当前线程的运行时,多线程与否由插件作者选 |
JSON 文本的共同读取检查是自带的逐字节读取器(primitives::json),读出保留文档顺序的值树,再经自带的 serde Deserializer 读入目标类型:serde_json 对重复成员取最后一个、不查孤立的代理项转义、把 -0 读成浮点、对 1e400 报错,Value 又按键排序,都与规范不符。
规范里的文法(错误码、消息键、Baggage 键、清单各字段、traceparent 等)是手写的逐字节判定,不依赖正则库;取消令牌与截止时间是自带的轻量实现,不依赖异步运行时。没有开发依赖:一致性测试借 RawValue 按原文取出向量里的清单,保留成员在文档里的顺序;测试用自写的最小执行器运行 future。
协议代码 src/plugin/generated/xihan.plugin.v1.rs 由 spec/plugin/plugin.proto 生成并提交,使用者不需要 protoc。
一致性
按 RFC-0024,实现认领若干一致性档,只对认领的档负责(档表在规范仓库的 conformance/profiles.json):
- 认领的档:
core与plugin。 - 缺口:无。
- 钉的规范版本:仓库
spec/子模块指向的规范标签,规范的版本规则见规范与多语言。
原语、清单、调用上下文、管道、操作与进程外插件运行时可用,通过规范仓库 conformance/vectors/ 下 primitives(含 json-text.json)、manifest、pipeline、operations 与 plugin(握手行、回调端点列表、版本协商、截止时间、消息键、回调失败的映射、读入 Error)的全部向量;示例 echo 通过黑盒运行器 xihan-conformance plugin 的全部用例。在有钉在规范标签上的发布版之前,成熟度是 Experimental。
怎样验证:测试直接读取 spec/conformance/vectors/;tests/conformance_vectors.rs 按档表核对认领的档要求的每个向量要么被回放、要么列为缺口,规范在认领的档里新增向量时它失败;tests/plugin_conformance.rs 构建示例 echo,用黑盒运行器跑全部用例。CI 在 ubuntu 与 windows 上跑这些测试,另以最低 Rust 版本构建库。
尚未提供:
- 流式操作:操作契约(RFC-0011)还没有流式形态,插件不实现流式调用,
InvokeStream读第一帧之后一律拒绝(invocation.md§1); - Wasm 插件 ABI(RFC-0018,
xihan_*导出、xihan导入,WASI preview 1 reactor),样板在 XiHan.Framework 的samples/EchoWasmPlugin,见Wasm 插件; - 远程 Provider 的操作集(RFC-0019,首个是
caching.distributed@1)。
破坏性改动与迁移
暂无条目:crate 还没有发布过正式版本,crates.io 上只有名字占位的版本。发布之后,每个版本的破坏性改动与迁移方式记在这里。
