Java SDK
framework-sdk-java 是 XiHan Spec 的 Java 实现:原语层、清单、调用上下文、管道、操作契约与进程外插件运行时。用它可以把与 .NET 宿主(参考实现 XiHan.Framework)相同的原语用在 JVM 应用里,也能写在 .NET 宿主里运行的 Java 插件。规范以 submodule 放在仓库的 spec/,规范写到的行为与 .NET 一致,由规范仓库的一致性向量与黑盒运行器验证;规范怎样组织、各语言 SDK 的现状见规范与多语言。
安装
需要 JDK 21+。Maven 坐标 com.xihanfun:xihan-framework(Maven Central 命名空间 com.xihanfun 已验证,尚未发布):
<dependency>
<groupId>com.xihanfun</groupId>
<artifactId>xihan-framework</artifactId>
<version>${xihan-framework.version}</version>
</dependency>插件运行时的依赖
插件运行时另用 grpc-java 与 protobuf-java。它们在本构件里是可选依赖(<optional>true</optional>,模块描述里是 requires static),不传递给使用者,其余包不引用它们;写插件的应用自己加上,版本与 SDK 仓库 pom.xml 的 grpc.version、protobuf.version 相同(生成代码要求 protobuf-java 不低于生成它的版本):
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-netty-shaded</artifactId>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-protobuf</artifactId>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-stub</artifactId>
<version>${grpc.version}</version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>${protobuf.version}</version>
</dependency>在模块路径上用插件运行时,这些自动模块(io.grpc、io.grpc.stub、io.grpc.protobuf、io.grpc.netty.shaded、com.google.protobuf、com.google.common)要进入模块图:应用自己 requires 它们,或用 --add-modules。
模块
整个 SDK 是一个 Maven 构件 com.xihanfun:xihan-framework,与其他语言的 SDK 一样只有一个包,JPMS 模块名 com.xihanfun.framework,按 Java 包划分:
| Java 包 | 内容 | 规范 |
|---|---|---|
com.xihanfun.framework.primitives | Error / ErrorCode、Result<T>、Maybe<T>、TypedId<Tag, V>、LifecycleState、PipelineStage、Stability、BaggageKeys、消息键与模板(MessageTemplate、MessageCatalog、MessageScope)、FrameworkException、FrameworkInfo | RFC-0001、RFC-0010、conventions/ |
com.xihanfun.framework.primitives.json | 线上 JSON 编码:Jackson 模块 PrimitivesModule | RFC-0001「线上编码」 |
com.xihanfun.framework.manifest | xihan.manifest.json 的模型、按 Schema 严格读取、规范化输出与校验,能力声明与依赖文本 | RFC-0002、manifest/manifest.schema.json |
com.xihanfun.framework.invocation | Context:取消与截止时间(按令牌归因为 KERNEL_TIMEOUT_001 / KERNEL_CANCELLED_001,可登记回调)、W3C 追踪、已登记的 Baggage、对象袋 Items、按派生传递的值 | RFC-0003 |
com.xihanfun.framework.pipeline | 十一阶段的 PipelineBuilder:use / useAt / useNamedInstance、before / after(类型名或实例名)、describe / dump、build;排序规则与错误码 KERNEL_PIPELINE_00x | RFC-0004 |
com.xihanfun.framework.operation | OperationContract、OperationSchema、OperationHandler<Req, Res>、容量 10000 的 OperationRegistry、经完整管道执行的 OperationInvoker(XGI:JSON 请求与响应,另有类型化入口) | RFC-0011 |
com.xihanfun.framework.plugin | 进程外插件运行时:PluginRuntime.serve(PluginOptions)、生命周期回调 PluginHooks(配置、启动、停止、健康)、事件订阅 Subscription 与 EventHandler、握手交出的消息目录 PluginCatalog、宿主回调 Host(Host.Invoke 与批量的 Host.Publish)、stderr 的 JSON 行日志 PluginLogger;协议代码在不导出的 com.xihanfun.framework.plugin.v1 | RFC-0017、plugin/plugin.proto、plugin/handshake.md、plugin/lifecycle.md、plugin/invocation.md |
包之间的依赖方向:plugin → operation → pipeline → invocation → primitives,plugin → manifest → primitives。外部依赖只有 jackson-databind,模块描述里是 requires transitive。
快速开始
在 Java 应用里用原语:
record CreateOrder(int quantity) { }
record OrderCreated(String id, int quantity) { }
OperationRegistry registry = new OperationRegistry();
registry.add(OperationContract.of("orders.create").withStability(Stability.EXPERIMENTAL).withExpose(Expose.HTTP),
CreateOrder.class, OrderCreated.class,
(context, request) -> request.quantity() > 0
? Result.ok(new OrderCreated("o-" + context.correlation().orElse(""), request.quantity()))
: Result.fail(Error.validation("ORDERS_VALIDATION_001", "orders.quantity.invalid", Map.of("quantity", request.quantity()))));
PipelineBuilder pipeline = new PipelineBuilder()
.useAt(Middleware.of("Observe", (context, next) -> next.invoke(context)), PipelineStage.OBSERVE, Placement.END, PipelineBuilder.APP_OWNER);
OperationInvoker invoker = new OperationInvoker(registry, pipeline);
Context context = Context.builder().timeout(Duration.ofSeconds(2)).baggage(BaggageKeys.CORRELATION, "c1").build();
OperationResponse response = invoker.invoke(context, OperationRequest.of("orders.create", "{\"quantity\":2}"));
// response.payloadText() == Optional[{"id":"o-c1","quantity":2}]- 可恢复失败返回
Result/Error,不抛异常。错误码按<领域大写>_<KIND>_<NNN>,文案用消息键 + 语言文件(RFC-0010),Error.message()在没有已解析文案时按MessageScope的进程默认目录解析,翻译不出时用 SDK 自带的内核消息英文模板(KernelMessages,与kernel-messages.json逐字相同),再退回键 (参数)的描述。 - 配置错误(清单不合法、管道成环、操作重复登记、登记表已满)抛出带错误码的
FrameworkException;参数格式不合法这类调用方的编程错误抛IllegalArgumentException,状态不允许抛IllegalStateException。消息是英文句子,标识符加单引号。 Result<T>、Error、Maybe<T>、TypedId的 JSON 编码按 RFC-0001「Result」:new ObjectMapper().registerModule(new PrimitivesModule());从线上收到的文本用PrimitivesJson.read(mapper, bytes, type)读,它先过共同的 JSON 文本检查。生命周期迁移表、管道阶段顺序、错误码、Baggage 键与值、能力依赖文法、JSON 文本检查、线上编码、消息模板、内核错误、清单的读取与写出、载荷解码与管道排序都由spec/conformance/vectors验证,期望值逐字相等。
写一个插件
宿主一侧怎样发现、启动与降级进程外插件,见进程外插件;这一节讲用本 SDK 写插件一侧。
插件是宿主启动的子进程:main 里登记操作与订阅,交给 PluginRuntime.serve,它读宿主下发的环境变量、监听本机端点、向 stdout 写一行握手行,然后服务到 Stop 完成、stdin 关闭或收到 SIGTERM:
public final class GreetingPlugin {
record Greet(String name) { }
record Greeting(String text) { }
public static void main(String[] args) throws Exception {
OperationRegistry registry = new OperationRegistry();
registry.add(OperationContract.of("greetings.create").withStability(Stability.EXPERIMENTAL).withExpose(Expose.HTTP),
Greet.class, Greeting.class,
(context, request) -> Result.ok(new Greeting("hello, " + request.name())));
PluginRuntime.serve(PluginOptions.builder()
.operations(registry)
.subscribe(Subscription.of("greetings.requested"), (context, envelope, attempt) -> Result.success())
.catalog(PluginCatalog.load("greetings", locale -> GreetingPlugin.class.getResourceAsStream("Localization/" + locale + ".json")))
.build());
}
}清单 xihan.manifest.json 放在插件目录里,运行时从工作目录(即插件目录)读它,握手时原样交给宿主,宿主核对它与目录里的文件逐字段一致:
{
"$schema": "https://spec.xihanfun.com/manifest/v1.json",
"id": "xihan.samples.greeting",
"version": "0.1.0",
"primitives": "1",
"stability": "experimental",
"kind": "plugin",
"isolation": "out-of-process",
"contributes": { "operations": [ "greetings.create" ], "health": [ "greeting" ] },
"permissions": [ "capability:kernel.pipeline" ],
"activation": [ "onStartup" ],
"entry": "greeting"
}kind是plugin、isolation是out-of-process;不写contributes.pipeline(只有 Wasm 插件能贡献中间件);primitives等于本 SDK 支持的原语层大版本1;登记的操作不重复且都在contributes.operations里,订阅的(主题,类型)不重复。不合即拒绝启动(handshake.md§1):不监听、不写握手行,在 stderr 记一条error,serve抛出带错误码的FrameworkException(如PLUGINS_VALIDATION_001、PLUGINS_VALIDATION_004)。- 回调报的健康项要出现在
contributes.health,不在的丢掉、同名只记一条warning;回调宿主要在permissions里声明capability:kernel.pipeline(Host.Invoke)或capability:messaging.queue(Host.Publish),并由宿主在Configure里授予:运行时发出回调之前在本地核对,缺一即PLUGINS_DENIED_002+plugins.callback.denied、不发请求。 entry是相对插件目录的可执行文件(Windows 上没有扩展名时宿主补.exe)。Java 插件的entry指向启动脚本:Unix 上是带 shebang、可执行的 sh 脚本,Windows 上是.cmd。宿主只继承handshake.md§1 列出的环境变量,JAVA_HOME不在其中,所以脚本里写java的绝对路径与完整的类路径,例如exec /opt/java/bin/java -cp '/opt/greeting/lib/*' GreetingPlugin "$@"。- 处理器里用
Host.of(context)回调宿主:invoke(context, "orders.create", payload)经宿主的完整管道调用操作,publish(context, envelopes)批量发布、逐项结果。
用规范仓库的黑盒运行器验证(需要 Go,参数见规范仓库的 conformance/README.md):
cd spec/conformance
go run ./cmd/xihan-conformance plugin --dir <插件目录> --sample 'greetings.create={"name":"hi"}'完整的示例在 examples/echo:回声、经宿主回调转发、故意崩溃(验证时排除)、列出收到的事件四个操作,一个事件订阅、一个健康项与配置节 XiHan:Echo。测试 EchoConformanceTest 把它放进临时目录、按当前平台生成启动脚本,再从 submodule 运行黑盒运行器跑全部用例。
与宿主共用的行为
按规范 ADR-0233、ADR-0235、ADR-0236、ADR-0237 统一的行为,各语言 SDK 与 .NET 相同:
文本、编码与消息
- JSON 文本:Result 与 Error 的线上编码、操作载荷与清单先过同一遍检查(
JsonText.check,向量json-text.json):语法按 RFC 8259(无注释、尾逗号、NaN、前导零、正号、多根值,空文本与只有空白也不合法),文本是 UTF-8、开头的 BOM 是语法错误;嵌套不超过 64 层;字符串与成员名必须是合法 Unicode(拒绝非法 UTF-8、过长编码、编码成 UTF-8 的代理项、原始控制字符、非法转义、孤立的代理项转义);任何一层都不能有重复成员(按转义还原后比较)。语法错误优先,位置只写$;否则写第一处重复的路径。Jackson 会跳过 BOM、按字节猜 UTF-16、放过孤立的代理项,所以这一遍不经 Jackson。 - 线上编码:无值成功(
Result<Unit>)只写{"ok":true};Result<Maybe<T>>的无值是"value":null。Error的message必填,且至少含一个空白之外的字符:空串与只有空白都不合法(上一版只拒绝空串)。空白是 RFC-0001「空白字符」的 25 个码位,按这张表判断,不用Character.isWhitespace或String.isBlank:它们不含 U+0085、U+00A0、U+2007、U+202F,却含 U+001C–U+001F。Error.literal与withText的文案、FrameworkException的说明(它是toError()的文案)同样,不合时抛IllegalArgumentException。messageKey、details、inner缺失表示没有,写成null不合法;未知成员忽略。重复成员在任何一层都不合法,含value、details与inner的内部(上一版不查value里面);解码器自己核对重复、64 层与孤立的代理项,不看ObjectMapper的配置。数字按值模型:64 位范围内的整数写法原样往返(9007199254740993 不会变成 9007199254740992),其余是双精度浮点;细节里整数值的浮点写成2.0、-0.0、1.0E17,非有限的写成字符串"NaN"、"Infinity"、"-Infinity"(以前细节里不许放非有限值)。 - 模板:消息键最长 128 个字符。说明符只认
^[DdFfNnXx][0-9]{0,2}$:D与X只用于整数,X只用于非负整数,F与N用于整数与浮点,不适用或不认的(E2、G、0.00、yyyy、D100、带空格)一律按无格式写出(上一版精度可到 99)。F与N按精确十进制展开、正好一半取偶(0.125 写F2得0.12,2.675 写F2得2.67),写出全部整数位,负数舍入成零保留负号。数组与对象写成紧凑 JSON,对象成员按名字的 UTF-16 码元序排列,超过 64 层的容器写null(上一版用 Java 的toString)。浮点 1e-4 ≤ |x| < 1e17 不用指数,范围外写1E+17、9.9E-05、5E-324,负零-0。Describe的参数按名字的序数顺序。 - 区域:
MessageTemplate.format(template, arguments, locale)/tryFormat(…, locale)/text(value, locale)与MessageCatalog.resolve(key, locale, arguments)按区域取小数点与分组符:de-DE、es-ES、pt-BR 是,与.,fr-FR 是,与 U+202F,ru-RU 是,与 U+00A0,其余区域与不给区域是.与,;区域名不区分大小写。小数点用在无格式的浮点(含指数的尾数,de-DE 的 1.5e20 写1,5E+20)与F、N上,分组符只用在N上;整数无格式时不分组,D、X与数组、对象里的数字不随区域变化。Error.message()按MessageScope的进程默认区域取符号,回退到内置 en-US 模板时也一样。 - 内核错误:错误码、消息键与参数照
kernel-messages.json,内置的英文模板与它逐字相同,含清单读取的 9 个键,所以清单读取失败的message是与 .NET 相同的英文句子;kernel.operation.type_mismatch只带id(上一版带 Java 的类型名expected/actual)。配置期的重复登记与登记表已满仍抛FrameworkException,toError()交出带键与参数的错误。
调用器与载荷
- 调用器的内置步骤:位置与 .NET 的内置中间件相同,都按归属
xihan.kernel.core(OperationInvoker.KERNEL_OWNER)放在所在阶段的Beginning,与同位置的其他中间件按归属的序数序、同归属按登记顺序排列(内置步骤登记在使用者的中间件之后)。Observe 阶段翻译异常(KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception,FrameworkException的错误进inner,取消引起的异常按令牌归因,java.lang.Error不翻译),只接住排在它之后的异常:Ingress 阶段与 Observe 阶段Beginning上归属排在它之前(如app)的中间件抛出的异常原样交给调用方。Resilience 阶段核对截止时间,进入时已到即KERNEL_TIMEOUT_001+kernel.invocation.deadline_before_start(上一版在第一个中间件之前核对,已撤回);下游把取消写成了结果(KERNEL_CANCELLED_001)而截止令牌已触发时改报KERNEL_TIMEOUT_001+kernel.invocation.deadline_exceeded,调用方同时取消也一样(RFC-0003 规则 1;上一版原样返回取消),抛出的取消在 Observe 阶段按同一规则归因。Validate 阶段解码原始调用的载荷,类型化调用跳过。进入管道前只核对未登记(KERNEL_NOTFOUND_001)与类型化调用的类型不符(KERNEL_VALIDATION_002),按这个顺序。调用器复制使用者的PipelineBuilder(copy())再加内置步骤,不改动它。 - 响应的编码:XGI 入口在管道结束之后才把响应编码成载荷,中间件看到的是编码之前的结果;
Operations.findResponse(context)给出 handle 阶段执行成功的响应对象(上一版的findResponsePayload给载荷,已撤回)。写不出时(类型化的浮点成员是 NaN 或无穷、序列化不支持的值)以KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception结束,异常链上有FrameworkException时它的错误进inner,不抛给调用方,没有载荷(上一版是Error.literal的英文消息)。NaN 不写成字符串:编码时关掉 Jackson 的WRITE_NAN_AS_STRINGS,写出的文本再过共同的 JSON 文本检查。类型化入口不编码。 - 取消只经令牌:调用器与内置步骤不中断线程、不取消 future,只让上下文的令牌触发;令牌触发之后处理器照常返回结果的,调用以那个结果结束。处理器要尽早结束时自己看
context.cancellation()、onCancelled或awaitCancellation。 - 载荷解码:先过共同检查(语法错误写
$,重复成员写第一处重复的路径,先于一切类型问题);空载荷等价于{},只有空白是语法错误(上一版当作{});然后按请求类型以文本顺序核对(RequestShape,不靠 Jackson 的读取顺序):成员名区分大小写、未知成员忽略、数字不从字符串读、整数不接受1.0与1e2、超出类型范围即不符、浮点接受整数写法且 1e400 上溢为无穷、1e-400 为 0;必填成员缺少时在所在对象结束时报该对象的路径。载荷的文本按 JSON 值比较,空白、转义与数字的写法不是契约;任意 JSON 类型的成员(JsonNode、Object)原样保留读到的值:超出双精度的整数精确,2.0与2、-0.0与0分得开,1e400、1e-400这类双精度表示不了的数保留原文的精确十进制,写回时 JSON 值相等,不变成null、无穷或 0。reason只写路径:载荷是null、不是对象或根上就不合时写$;成员名含.、空格、'、/、"、[、]、(、)、\、制表、换行、回车、换页、退格、U+0085、U+2028、U+2029 时写$['名字'],其余写$.名字。
清单与文法
- 清单的读取:按 JSON 文本 → 字面量
null→ 按 Schema 逐项核对 → 跨字段约束的顺序,每一步只报第一处问题,错误码都是KERNEL_CAPABILITY_006(上一版是PRIMITIVES_VALIDATION_001加英文消息):kernel.manifest.invalid_json(reason是$或第一处重复的路径)、kernel.manifest.empty(根是null,没有参数)、kernel.manifest.invalid(reason是第一处问题的路径:成员按文本顺序,每个成员依次查 Schema 之外 →null→ 类型 → 取值,对象查完后再按required的顺序查缺少的成员);跨字段约束按primitives.manifest.isolation_required→isolation_not_allowed→duplicate_provides→duplicate_requires→duplicate_bindings的顺序,参数只有id。ManifestJson.read(byte[])不跳过 BOM;readFile按 UTF-8 读并跳过开头的 UTF-8 BOM,文件不存在为kernel.manifest.file_missing(参数path,以前抛IOException)。接口版本不带前导零、不超过 2147483647,只有依赖的版本可带一个^;中间件名非空,contributes.health按^[a-z][a-z0-9.-]*$核对,contributes.permissions重复时报第二次出现的项;写了空数组的activation不合法。非 Wasm 插件贡献中间件交给宿主在发现时拒绝,读取与构建清单不再核对(与 .NET 一致)。Manifest.Builder.build()的跨字段约束带同样的消息键与id,错误码是PRIMITIVES_VALIDATION_001。 - 清单的写出:
ManifestJson.write的排版照 RFC-0002「写出」逐字固定:两个空格缩进、LF、末尾不换行、": ";$schema总写https://spec.xihanfun.com/manifest/v1.json,列表总写(空列表写[]),role缺省写provider、activation缺省写["onStartup"],依赖总写optional、绑定总写required、中间件总写before/after,contributes总写;字符串只转义"、\、控制字符与孤立的代理项(<、&、U+2028 与非 ASCII 原样)。上一版省略缺省值并转义<>&。Manifest按生效的值比较(不看$schema,没写的角色、激活事件、贡献点与绑定的required按缺省),写出的清单再读一遍与原来的相等。 - 文法:规范的正则都按整串匹配,结尾的换行不例外(
xihan.tenant\n、带换行的traceparent不通过);Java 一律用Matcher.matches()。能力依赖的版本不接受前导零、+、空白与超过 2147483647 的值。
上下文与管道
- Baggage 值:已登记键的值要非空、按 UTF-16 码元计最多 256、不含 U+0000–U+001F 与 U+007F–U+009F。外部输入
Context.builder().baggage(…)丢弃不合的成员、已有的同名值保留;程序内派生withBaggage给已登记的键一个不合的值抛IllegalArgumentException(上一版是去掉这个键)。xihan.idempotency-key两种情形都例外。 - 追踪:
traceparent只认^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$、标识不能全零,不合法的当作没给;只取采样位,写出只写00/01(上一版整字节保留标志、有traceFlags(),已撤回);没有上游时写01。 - 管道:重复登记、未知阶段、约束主体未登记或按名字有歧义在登记时报;约束目标未登记或有歧义、跨阶段与成环在排序(
describe/dump/build)时报。排序与 .NET 一样逐个阶段处理:阶段内按基准次序逐个主体解析它的约束(先 before 再 after,各按声明顺序),解析完再排序,所以几处错误同时存在时报的是同一个。按名字的约束与 .NET 同一种匹配:按名字登记的实例只认实例名,没有名字的登记认中间件名(上一版中间件名也能对上按名字登记的实例)。错误消息是 .NET 的英文原文,按名字登记的实例写成类型名[名字],成环时按基准次序列出全部仍被卡住的中间件,如Middleware ordering constraints in stage 'validate' form a cycle: 'Guard[a]', 'Guard[b]'.。
插件
- 插件的启动与握手(RFC-0017,
plugin/handshake.md):监听之前核对清单与声明,不合即拒绝启动。握手行的地址不含空白,空白是 RFC-0001「空白字符」的集合(与 .NET 正则的\s相同,含 U+0085、U+00A0、U+2007、U+202F、U+3000,不含 U+001C–U+001F 与 U+200B,与Character.isWhitespace不同);tcp只写127.0.0.1:<端口>。解析握手行与端点的代码按同一文法:地址是一个或多个空白之外的字符(非 ASCII 字母与;可以出现),tcp只认127.0.0.0/8的四段点分十进制(不带前导零)或[::1],端口 1–65535、不带正负号与前导零(向量handshake-lines.json)。宿主的每个 RPC 先按常数时间核对元数据xihan-plugin-session:必须恰好一个值,没有、不匹配或有两个及以上(即使其中一个正确)都以Unauthenticated拒绝、不执行;令牌先于一切,含次序核对与流式调用读第一帧。握手选宿主列表里最高的共同版本(向量protocol-versions.json),没有交集以FailedPrecondition拒绝、状态不变;primitives写清单的值,manifest写清单文件原文并去掉开头的 UTF-8 BOM,只声明一元操作,订阅按声明的顺序、mode总写competing或broadcast,catalogs只发作者自己的目录,SDK 运行时的目录不随握手发送。 - 插件的次序与生命周期(
lifecycle.md§7):Handshake只在Declared、Configure只在Resolved、Start只在Configured接受,各一次;Stop在Declared、Draining、Stopped与另一次停止进行中都不接受;不在次序表里的组合以FailedPrecondition拒绝、什么都不做、状态不变。配置节为空等同{},不是 JSON 对象(过共同的 JSON 读取检查)时不调配置回调,以PLUGINS_UNEXPECTED_001+plugins.process.failed(phase为configure,reason为the configuration is not a JSON object)进入Failed。启动回调成功后进入Started,立即求一次健康回调,按结果进入Ready、Degraded或Failed(没有健康回调、回调报其他状态即Ready,回调抛出即Degraded),然后才应答Start。只有Ready与Degraded可服务,其余状态的调用与投递以PLUGINS_UNAVAILABLE_001+plugins.process.unavailable(state是状态名)失败。Health任何状态都可调用:Start之前报本地状态(Declared、Resolved或Configured),没有健康项、不调回调;Ready与Degraded期间每次都求一次健康回调,回调报的Ready、Degraded、Failed按合法迁移改变状态(Failed不再回来),报其他状态的不改变状态,回调抛出时这一次的结果是Degraded、没有健康项,错误为plugins.process.failed(phase为health),状态也与报了Degraded一样迁到Degraded,之后的结果照常决定状态;Draining、Stopped、Failed不再调健康回调。WatchHealth先推当前状态,之后状态、健康项或错误变化时推,可服务期间每 10 秒求一次健康回调,进入Draining时推一次,应答Stop之后结束流(上一版每秒核对一次、进入Draining即结束流)。 - 插件的停止与收尾(
lifecycle.md§7.5–§7.7):启动回调没成功过时Stop不调停止回调,应答ok,以退出码 0 退出;Started、Ready、Degraded进入Draining(健康回调报过Failed的不迁移)、拒绝新调用,等在途调用到宽限期(grace_seconds为 0 按 5 秒),到时触发它们的取消信号、不再等,然后调停止回调(reason原样交给作者)、应答、进入Stopped、退出。停止回调在进程里最多调一次,返回失败或抛出时写进StopResponse.status,照常退出(上一版Configure调用过就调停止回调)。stdin 读到结尾或读出错与 SIGTERM 都是收尾请求:可服务的插件进入Draining(其他状态不迁移),立即触发全部在途调用的取消信号并等它们结束,启动回调成功过而停止回调还没调过的调一次(reason为shutdown);从收到起最多 3 秒,到时不论是否完成都以退出码 0 结束进程,进行中的Stop同样受这 3 秒限制。生命周期与健康回调抛出时reason是异常的简单类型名(如IllegalStateException,匿名类取去掉包名的二进制名如EchoPlugin$1),不带异常的文本,异常只写进 stderr。 - 插件的调用与投递(
invocation.md§1–§4):Invoke依次核对令牌、操作在握手声明里(否则Unimplemented)、可服务(否则PLUGINS_UNAVAILABLE_001),然后还原上下文,经调用器与完整管道执行,空载荷等同{}(上一版先报未就绪)。InvokeStream读第一帧:流在第一帧之前结束或第一帧不是start为InvalidArgument,第一帧是start一律Unimplemented,不论操作是否声明、插件是否就绪;本 SDK 不提供流式操作的公开 API。上下文:trace_parent按 RFC-0003 的文法,不合即没有父 Span;trace_state不进上下文;Baggage 只留已登记的键;deadline按严格文法读(向量deadlines.json,Instant精确到纳秒,九位小数不截断),读不出当作没有,生效的截止时间取它与 gRPC 截止时间中较早的一个;gRPC 取消即上下文取消。HandleEvent依次核对令牌、有envelope且mode是空、competing或broadcast(否则InvalidArgument)、按(主题,方式,类型)找订阅(一个也没有为KERNEL_NOTFOUND_001+plugins.event.unsubscribed,参数id、topic、type、mode,空方式写competing)、可服务,然后按声明顺序依次交给每个匹配的订阅,第一个失败即终止并作为结果(上一版只交给第一个),处理器抛出为KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception。 - 插件的错误、消息键与日志(
invocation.md§3、§8):写出的Error里带消息键的text留空,由宿主按目录翻译成调用方的语言,只有自由文本错误写text(上一版按XIHAN_PLUGIN_LOCALE渲染);details按值模型写出,没有时为空;inner照写。读宿主写来的错误:code不合错误码文法时换成PLUGINS_UNEXPECTED_001+plugins.process.failed(phase一律为invoke,Host.Publish的结果也一样;reason为invalid error code '<code>';原来的inner丢掉);message_key合文法的按键处理、不取text,否则成为自由文本错误(文案取text,为空或只有空白时取code);details为空、只有空白、是空对象{}、通不过共同 JSON 读取检查、不是对象,或任何一层有读成双精度会溢出的数时当作没有细节(下溢读成 0,超出 64 位的整数读成双精度),inner同此(上一版整个错误换成plugins.process.failed);ok为假却没有错误、或整个status缺失为plugins.process.failed(phase为操作 ID 或publish,reason为the host reported a failure without an error)。向量error-reading.json。运行时的七个消息键、参数(就是details的成员)与错误码照plugin-messages.json,PluginMessages带与参考实现相同的 10 种区域目录供本地渲染。stderr 每行一个 JSON 对象(level、message与作用域属性),java.util.logging的根日志也改写成这种行。 - 回调(
invocation.md§5、handshake.md§4):启动时解析XIHAN_PLUGIN_HOST_ADDRESS:一个或多个<network> <address>,以;分隔,任何一项不合法整个值就不合法(向量host-addresses.json);按宿主的偏好取第一个本 SDK 能连的端点(回环 TCP,Linux 上有 epoll 时另有 Unix 域套接字;grpc-java 连不了命名管道),之后不换。宿主总在列表最后给出一个回环 TCP,所以 Windows 上的 .NET 宿主(命名管道加回环 TCP)也能回调。变量缺失、不合法或没有能连的项时照常服务,启动时 stderr 记一条warning,每次回调都以PLUGINS_UNAVAILABLE_001+plugins.host.unavailable(reason为no supported callback endpoint)失败、不发请求(上一版变量不合法即拒绝启动)。发出之前在本地按宿主的顺序核对:所需权限(Host.Invoke为capability:kernel.pipeline,Host.Publish为capability:messaging.queue)既在清单permissions里、也在Configure授予的权限里,否则PLUGINS_DENIED_002+plugins.callback.denied;回调上下文的xihan.tenant是此刻在处理的某个调用或投递的租户,否则PLUGINS_DENIED_002+plugins.callback.tenant_denied;最后,回调上下文的截止时间已过或已被取消时也不发请求,结果与映射表相应的一行相同(截止时间已过为KERNEL_TIMEOUT_001,已被取消为KERNEL_CANCELLED_001);Host.Publish这些都是整批的结果。顺序是端点、权限、租户、截止时间与取消。信封的xihantenant不在本地核对,交给宿主逐项判定(上一版本地逐项核对)。回调的元数据取自所在的调用上下文:当前 Span 的 traceparent、UTC 七位小数加+00:00的deadline、已登记的 Baggage、空的trace_state,gRPC 截止时间与deadline相同,带会话令牌;调用方取消上下文即取消回调,截止时间到了不在本地取消,由 grpc-java 按同一个截止时间以DeadlineExceeded结束,结果只按映射表、不另按时钟或令牌改写。gRPC 状态按 §5 的表映射(向量callback-status.json):Unauthenticated为plugins.callback.session_invalid,PermissionDenied为plugins.callback.denied,DeadlineExceeded为KERNEL_TIMEOUT_001,上下文的取消信号已触发的Cancelled为KERNEL_CANCELLED_001,其余Cancelled、Unavailable与连接失败为plugins.host.unavailable(reason为<状态名>: <说明>,状态名是 PascalCase),Host.Invoke的Unimplemented为kernel.operation.unknown、InvalidArgument为kernel.operation.invalid_payload(reason为状态的说明),其余(含Host.Publish的这两种)为plugins.process.failed(phase为操作 ID 或publish)。Host.Publish的 RPC 失败时每一项都是同一个错误,结果数与信封数不同时每一项都是plugins.process.failed(reason为the host returned <n> results for <m> envelopes)。
语言映射
Java 的写法与规范的对应:
- 模板参数的值模型(RFC-0010「模板」):
null是空;Boolean是布尔;String、其他CharSequence与Character是字符串;Byte、Short、Integer、Long、AtomicInteger、AtomicLong是 64 位整数,BigInteger在 64 位范围内是整数、超出时是双精度浮点;Double是浮点,Float与BigDecimal先换成最接近的double(0.1f写0.10000000149011612,new BigDecimal("2.50")写2.5);键都是String的Map是对象,Collection与 Java 数组(含基本类型数组)是数组。模型之外的值(枚举、UUID、java.time的类型、键不全是字符串的Map等)写成toString()的文本,嵌在数组或对象里时写成这段文本的 JSON 字符串;它们不跨语言,插件要跨语言格式化时先转成字符串。 - 线上编码的数字:
Error.details()里放Integer/Long/BigInteger/Float/Double/BigDecimal都可以,写出时按上面的值模型;读回来时 64 位范围内的整数是Integer或Long,其余是Double,非有限值读回来是字符串。Result.value的内容由值类型自己的 Jackson 配置写出;读取时超出 64 位的整数按值模型先成为浮点,再交给值类型。 - 载荷的请求类型:用记录或带 Jackson 注解的类声明。必填成员写
@JsonProperty(required = true),可选成员不加注解(缺少时取 Java 的缺省值:基本类型为 0 /false,引用类型为null)。String、List/ 数组 / 其他集合、Map、嵌套的记录与JsonNode/Object接受null(等于没有值);整数、浮点与布尔不论是基本类型还是包装类型(Long、Double、Boolean)都不接受null,它们的列表项与字典值同样不接受。认不出的类型(枚举、java.time、Optional、原语的Maybe/TypedId与其他自定义解码器、多态类型)在读到的位置单独交给 Jackson,失败时报 Jackson 给出的路径;byte[]照 Jackson 读 Base64 字符串。 - 文本与字节:
JsonText.check(String)、ManifestJson.read(String)、PrimitivesJson.read(mapper, String, …)先把字符串编成 UTF-8;字符串里有孤立的代理项(编不成 UTF-8)按语法错误处理,不像String.getBytes那样换成?。 - 同名的
Error:com.xihanfun.framework.primitives.Error与java.lang.Error同名,在用到它的文件里显式导入;它不是Throwable,误用在编译期就报错。 - 插件的回调与钩子:
PluginHooks的方法都有缺省实现,返回Result<Unit>,失败原样交给宿主;抛出(或返回null)时为PLUGINS_UNEXPECTED_001+plugins.process.failed,reason是异常的简单类型名,FrameworkException也一样,它的错误不进inner(上一版reason是带包名的类名或异常消息)。health()返回空表示没有健康回调。PluginConfiguration.decode(type)先过共同的 JSON 文本检查,再按 Jackson 读:成员名按 ASCII 不区分大小写:交给 Jackson 之前按目标类型的属性逐层(记录与普通类、列表、数组、字典的值)把成员名改写成属性名,原样相同的优先,只把A–Z当作与小写相同,所以 U+212A(开尔文符号)不当作k、非 ASCII 字母的大小写不算相同(上一版用 Jackson 的ACCEPT_CASE_INSENSITIVE_PROPERTIES,它按 Unicode 换小写);改写只换名字,数字保留原文;字符串叶子读成数字时按 JSON 数字的文法(" 7"、+7、07、NaN都不行,通过的文本当作同一个 JSON 数字读),读成布尔时只认true、false(ASCII 不区分大小写,ſ这类大小写映射到 ASCII 的字符不算);未知成员忽略。事件处理器抛出的异常翻译为KERNEL_UNEXPECTED_001。运行时交给处理器与钩子的上下文里总有Host(没有可用的回调端点时回调失败,而不是Host.of为空);Host.invoke返回OperationResponse,Host.publish返回与信封一一对应的List<Result<Unit>>。收尾时限由规范定为 3 秒,PluginOptions.Builder.shutdownGrace已删除。收到 SIGTERM 时关闭钩子收尾后以Runtime.halt(0)结束进程(不这样 JVM 以 143 退出);服务期间作者自己调用System.exit也会经过这个钩子,同样以退出码 0 结束。
设计取舍
并发:虚拟线程上的同步签名,不用 CompletableFuture。 中间件、处理器与调用器都是同步方法(Result<Unit> invoke(Context, Step)、Result<Res> handle(Context, Req)),按 Java 21 虚拟线程(JEP 444)设计:阻塞等待 I/O 时虚拟线程让出载体线程,不占平台线程,调用栈与异常栈可读,不需要把每一层都改成回调链。为此:构建出的 Step、OperationInvoker、OperationRegistry 不可变或线程安全,可以被任意多个线程同时使用;Context 不可变、按派生传递,每次操作调用的状态随派生的上下文传递(Context.withValue),嵌套与并发调用互不干扰;锁一律用 ReentrantLock,不在 synchronized 里阻塞(Java 21 上 synchronized 会钉住虚拟线程)。
取消与截止时间自己建模。 Context 有两个令牌:截止令牌由定时器在截止时间触发,外部令牌由 CancellableContext.cancel() 触发;父级取消连带子级,子级取消不影响父级。归因只看令牌(RFC-0003 规则 1、RFC-0004、ADR-0095):截止令牌已触发即 KERNEL_TIMEOUT_001,不论调用方是否也已取消;只有外部令牌触发时为 KERNEL_CANCELLED_001。onCancelled 登记回调(已取消时立即执行),awaitCancellation 在虚拟线程上等待;withCancellation / withDeadline / withTimeout 返回的 CancellableContext 用完要关闭(try-with-resources),免得长寿命的父级积攒已结束的子级。
JSON:Jackson。 Java 标准库没有 JSON;XGI 载荷、清单读取与线上编码都需要它。选 jackson-databind 是因为它是 JVM 上事实标准、本身是 JPMS 模块、支持记录类型,grpc-java 等常用库的使用者通常已经有它。原语核心类型不依赖 Jackson(RFC-0001:原语层不含序列化代码):共同的 JSON 文本检查 JsonText 是手写的逐字节检查器,编码在 primitives.json 包里;manifest 只用树模型按 Schema 逐项核对(ManifestShape)、不做反射绑定,写出是手写的排版;operation 用 OperationJson.newMapper()——注册原语编码、忽略未知字段、类型不符一律失败——并在反序列化之前按请求类型以文本顺序核对载荷(RequestShape),报错的先后不随 Jackson 的内部路径变。模块路径上的应用要把请求与响应类型所在的包 opens 给 com.fasterxml.jackson.databind。
可空性。 公开成员不接受也不返回 null:可能没有的值以 Optional 返回(findBaggage、find、tenant()),需要线上编码的数据字段用 Maybe(编码为值或 null,对象里缺这个字段也解码为无值),集合没有时是空集合;参数传 null 抛 NullPointerException。
有界。 对象袋最多 1024 个条目、Baggage 最多 180 个、按派生的值最多 256 个键、操作登记表 10000 个操作,超出是编程或配置错误。管道的中间件与顺序约束不设上限,与 .NET 的 PipelineBuilder 一致:它们由代码在启动时登记,不来自外部输入(上一版限 1024 个中间件与 4096 条约束,已撤回)。
插件运行时:grpc-java,生成代码提交进仓库。 传输是 grpc-java 的 Netty 传输(grpc-netty-shaded,自带改了包名的 Netty,不与应用自己的 Netty 冲突)加 protobuf-java,服务端以 Executors.newVirtualThreadPerTaskExecutor() 执行每一次调用,处理器、钩子与回调都可以阻塞。协议代码由 spec/plugin/plugin.proto 生成并提交进 src/main/java/com/xihanfun/framework/plugin/v1,不在每次构建时生成:构建不需要下载 protoc 的原生程序、各平台一致,生成物可以审阅;plugin.proto 没有 Java 选项,protocol 配置先复制一份并在末尾补上 java_package 与 java_outer_classname,CI 重新生成后核对没有差异。生成代码不放宽门禁,照样过 -Xlint:all -Werror 与 doclint。端点:Linux 上 grpc-netty-shaded 自带的 epoll 原生库可用时(x86_64、aarch_64)监听 Unix 域套接字,套接字放进本进程新建的私有目录(名字随机、0700,套接字 0600);Windows、macOS 与其余情形监听回环 TCP 127.0.0.1 的随机端口(规范允许,同机的其他用户连得上,隔离只靠会话令牌)。本 SDK 不监听命名管道,所以不涉及命名管道的访问控制。回调同样只能连回环 TCP 与 Linux 上的 Unix 域套接字(grpc-java 不支持命名管道):宿主按规范总在回调端点列表的最后给出回环 TCP,Windows 上的 .NET 宿主因此也能回调。JDK 23 起 Netty 用到的 sun.misc.Unsafe 内存访问会在 stderr 打告警,启动脚本里加 --sun-misc-unsafe-memory-access=allow 即可(JDK 21 没有这个选项)。运行时自己的消息键(plugins.*)是规范定下、与宿主共用的键(invocation.md §8),宿主有它们的目录,所以带这些键的错误 text 留空、目录不随握手发送;PluginMessages 的 10 种区域语言文件(文案与参考实现相同)供插件在本地渲染。
一致性
按 RFC-0024「实现钉规范」与「一致性档」:
- 认领的档:
core与plugin(规范仓库的conformance/profiles.json)。 - 缺口:无;认领的档的向量全部回放,
plugin运行器子命令通过。 - 规范版本:钉在仓库
spec/子模块指向的 framework-spec 提交;发版时子模块必须正好在规范标签上。 - 成熟度:在有钉在规范标签上的发布版之前是 Experimental。
- 已有的:原语、清单、调用上下文、管道、操作与进程外插件运行时(
plugin,xihan.plugin.v1,grpc-java)可用,示例插件examples/echo通过规范仓库黑盒运行器的全部用例(Linux 上经 Unix 域套接字,Windows 上经回环 TCP 与.cmd启动脚本);远程 Provider 的操作集(如caching.distributed@1)尚未提供。
怎样验证:
- 测试按仓库根的相对路径直接读取
spec/conformance/vectors,期望值逐字相等;VectorCoverageTest按档表核对认领的档:规范在认领的档里新增向量时它失败,要么补上回放,要么列为缺口并写明理由。 EchoConformanceTest用 submodule 里的黑盒运行器跑示例插件的全部用例,运行器与锁定的规范是同一个提交;CI 在 Linux 与 Windows 上都跑。- 自己的插件用上文「写一个插件」里的命令验证。
破坏性改动与迁移
行为上对齐规范与 .NET 的变化,在上文各条以「(上一版…)」注明。需要使用者改代码的有:
- 上一版的
findResponsePayload(给出载荷)已撤回:改用Operations.findResponse(context),它给出 handle 阶段执行成功的响应对象,XGI 入口在管道结束之后才把响应编码成载荷。 - 追踪的
traceFlags()已撤回:只保留采样位,写出只写00/01。 PluginOptions.Builder.shutdownGrace已删除:收尾时限由规范定为 3 秒。withBaggage给已登记的键一个不合的值时抛IllegalArgumentException(上一版是去掉这个键)。Error的文案为空或只有空白都不合法:Error.literal、withText与FrameworkException的说明不合时抛IllegalArgumentException,空白按 RFC-0001「空白字符」的 25 个码位判断。- 清单读取失败的错误码都是
KERNEL_CAPABILITY_006加kernel.manifest.*的消息键(上一版是PRIMITIVES_VALIDATION_001加英文消息);ManifestJson.readFile在文件不存在时抛带kernel.manifest.file_missing(参数path)的FrameworkException(上一版抛IOException)。 kernel.operation.type_mismatch的参数只有id(上一版带 Java 的类型名expected/actual)。- 插件钩子抛出时
reason是异常的简单类型名(上一版是带包名的类名或异常消息);PluginConfiguration.decode的成员名只按 ASCII 不区分大小写(上一版用 Jackson 的ACCEPT_CASE_INSENSITIVE_PROPERTIES)。
