XiHan Framework 处于预览阶段

查看获取方式
跳转到内容

TypeScript SDK ​

TypeScript SDK 是 XiHan Spec 的 TypeScript 实现:原语层、清单、调用上下文、管道、操作契约与进程外插件运行时。仓库是 XiHanFun/framework-sdk-typescript,规范以 submodule 放在仓库的 spec/。参考实现是 .NET(XiHan.Framework):规范写死的行为与 .NET 宿主相同,一致性由规范仓库的向量与黑盒运行器验证。ADR-0004 把 TypeScript 定为 Go 之后的第二个 SDK。

这一页讲安装、模块、最小示例、怎样写一个插件、与宿主共用的行为、TypeScript 的语言映射与设计取舍,以及一致性的现状。规范怎样组织、各语言 SDK 的对照见规范与多语言;宿主一侧怎样加载插件见进程外插件。

安装 ​

bash
pnpm add xihan-framework
pnpm add @grpc/grpc-js @bufbuild/protobuf   # 只在写插件时需要

还没有发布到 npm,发布前在本仓库里使用。

模块 ​

整个 SDK 是一个 npm 包 xihan-framework(与 crates.io、PyPI 上的包同名),各模块按子路径导入(xihan-framework/operation),没有根入口。全部是 ESM。核心五块运行时零第三方依赖,只用语言与平台内建的能力(AbortSignal、Web Crypto、TextDecoder、Intl),除 xihan-framework/manifest/node 外不引用 Node 专有模块,浏览器里也能用。进程外插件运行时 xihan-framework/plugin 只用于 Node,依赖 @grpc/grpc-js 与 @bufbuild/protobuf:它们是可选的 peerDependencies,用到插件时自己安装,其余子路径不加载它们。

子路径内容规范
xihan-framework/primitivesErrorInfo / 错误码、Result<T>、Maybe<T>、TypedId<Tag, V>、LifecycleState、PipelineStage、Stability、Baggage 键、消息键与模板、MessageCatalog、FrameworkErrorRFC-0001、RFC-0010、conventions/
xihan-framework/manifestxihan.manifest.json 的模型、按 Schema 读取、规范化输出与校验,能力声明与依赖文本;读取文件在 xihan-framework/manifest/nodeRFC-0002、manifest/manifest.schema.json
xihan-framework/invocationInvocationContext:取消与截止时间(AbortSignal)、W3C 追踪、已登记的 Baggage、类型化对象袋;超时与取消翻译为 KERNEL_TIMEOUT_001 / KERNEL_CANCELLED_001RFC-0003
xihan-framework/pipeline十一阶段的 PipelineBuilder:use / useAt / useNamedInstance、before / after、describe / dump、build;排序规则与错误码 KERNEL_PIPELINE_00xRFC-0004
xihan-framework/operationdefineContract、OperationRegistry、经完整管道执行的 OperationInvoker(XGI:JSON 请求与响应)与类型化入口 invokeTypedRFC-0011
xihan-framework/plugin进程外插件运行时 servePlugin(协议 xihan.plugin.v1):握手、配置(类型化读取 ConfigurationSection)、启停、健康与健康推送、Invoke 与事件投递,宿主回调客户端 findHost(Host.Invoke、Host.Publish),结构化的 stderr 日志 PluginLogger,消息目录 loadCatalog;只用于 NodeRFC-0017、plugin/

快速开始 ​

ts
import { InvocationContext } from 'xihan-framework/invocation';
import {
  defineContract,
  Expose,
  OperationInvoker,
  OperationRegistry,
  RequestShape,
  type RequestShapeType,
} from 'xihan-framework/operation';
import { middleware, PipelineBuilder, Placement } from 'xihan-framework/pipeline';
import { BaggageKey, ErrorInfo, PipelineStage, Result, writeJson } from 'xihan-framework/primitives';

// 请求的形状:调用器按它在文本顺序里核对载荷并构建请求(RFC-0011 规则 2)
const CreateOrder = RequestShape.object({ quantity: RequestShape.required(RequestShape.int32()) });
type CreateOrder = NonNullable<RequestShapeType<typeof CreateOrder>>; // { quantity: number }
interface OrderCreated { readonly id: string; readonly quantity: number }

// 契约带请求与响应类型;运行期只有 ID、稳定性、暴露的协议与授权要求
const createOrder = defineContract<CreateOrder, OrderCreated>({ id: 'orders.create', expose: [Expose.Http] });

const registry = new OperationRegistry();
registry.add({
  contract: createOrder,
  request: CreateOrder,
  handler: async (context, request) =>
    request.quantity > 0
      ? Result.ok({ id: `o-${context.tenant}`, quantity: request.quantity })
      : Result.fail(ErrorInfo.validation('ORDERS_VALIDATION_001', 'orders.quantity.invalid', { min: 1 })),
});

const builder = new PipelineBuilder().useAt(
  middleware('Audit', async (context, next) => next(context)),
  PipelineStage.Observe,
  Placement.End,
);
const invoker = new OperationInvoker(registry, builder);

const context = InvocationContext.create({ timeout: 2000, baggage: { [BaggageKey.Tenant]: 't1' } });
const response = await invoker.invoke(context, { id: 'orders.create', payload: '{"quantity":2}' });
// response.outcome.ok === true,response.payload === '{"id":"o-t1","quantity":2}'
const typed = await invoker.invokeTyped(context, createOrder, { quantity: 3 }); // Result<OrderCreated>
const wire = writeJson(typed); // 线上编码:数字按值模型写,不用 JSON.stringify

Result<T>、ErrorInfo、Maybe<T> 的 JSON 编码与 .NET 参考实现一致({"ok":true,"value":…} / {"ok":false,"error":{…}},没有值的成功是 {"ok":true})。写出用 writeJson,Result.parse / Result.parseMaybe / ErrorInfo.parse 从文本还原(fromJSON 系列收已解析的值,看不出重复成员,也分不出 2 与 2.0);JSON 文本的读取检查、线上编码、模板格式化、内核错误、清单的读写、载荷的解码、管道排序、生命周期迁移表、错误码、Baggage 键与值、traceparent、能力依赖的文法都由 spec/conformance/vectors 验证。

写一个插件 ​

插件是宿主启动的子进程:清单 xihan.manifest.json、启动入口与插件代码放在插件目录里,宿主以插件目录为工作目录启动清单的 entry。servePlugin 读工作目录里的清单与宿主下发的环境变量、监听本机端点、向 stdout 写握手行,然后服务到 Stop、stdin 关闭或 SIGTERM。宿主一侧怎样发现、启动、调用插件以及失败时怎样降级见进程外插件。

ts
import { defineContract, Expose, OperationRegistry, RequestShape } from 'xihan-framework/operation';
import { findHost, HealthStatus, servePlugin } from 'xihan-framework/plugin';
import { ErrorInfo, LifecycleState, Result } from 'xihan-framework/primitives';

const registry = new OperationRegistry();
registry.add({
  contract: defineContract<{ text: string | null }, { text: string }>({ id: 'echoes.create', expose: [Expose.Http] }),
  request: RequestShape.object({ text: RequestShape.required(RequestShape.string()) }),
  handler: async (context, request) =>
    request?.text
      ? Result.ok({ text: request.text })
      : Result.fail(ErrorInfo.validation('ECHOTS_VALIDATION_002', 'echots.text.missing', { operation: 'echoes.create' })),
});

await servePlugin({
  registry, // Invoke 经调用器与完整管道执行;操作 ID 都要写进清单 contributes.operations
  subscriptions: [{ topic: 'echo.events', handler: async (context, envelope) => Result.success() }],
  catalogs: [{ name: 'echots', locales: { 'en-US': { 'echots.text.missing': 'The text of {operation} is required.' } } }],
  hooks: {
    // configuration.section 是清单 contributes.config.section 节;values.number('retries') 等按 IConfiguration 的习惯读
    configure: (configuration) => Result.success(),
    health: () => ({ state: LifecycleState.Ready, items: [{ name: 'echo', status: HealthStatus.Healthy }] }),
  },
});
// 处理器里回调宿主:await findHost(context)?.invoke(context, 'orders.get', '{"id":"o-1"}')

清单的要点:

  • kind 为 plugin、isolation 为 out-of-process,primitives 为 1,不能写 contributes.pipeline(只有 Wasm 插件能贡献中间件)。声明与清单不符时 servePlugin 在监听之前在 stderr 记一条 error 日志并抛出,不写握手行。
  • entry 是相对插件目录的可执行文件,Windows 上没有扩展名时宿主补 .exe。Node 插件用启动脚本:Unix 上是带 shebang、可执行的 sh 脚本,Windows 上是 .cmd(开头写 @echo off,命令不回显到 stdout)。宿主只继承少数环境变量(handshake.md §1),脚本里写出 node 与入口的绝对路径,不依赖 NODE_PATH 之类。
  • 操作写进 contributes.operations,健康项写进 contributes.health,配置节写 contributes.config.section;回调宿主要在 permissions 里声明 capability:kernel.pipeline(Host.Invoke)或 capability:messaging.queue(Host.Publish)。
  • 握手行之后不要向 stdout 写任何东西,日志用 PluginLogger 写 stderr。

插件自己的端点按平台:Linux 与 macOS 上是 Unix 域套接字,放在本进程新建的私有目录里(mkdtemp,目录 0700、套接字 0600,停止后删除;临时目录的路径含空白时改放 /tmp,仍不行就用回环 TCP,因为握手行的地址不能含空白);Windows 上是命名管道 \\.\pipe\xihan-plugin-<随机>(Node 在 Windows 上没有 Unix 域套接字);network: 'tcp' 时只绑定 127.0.0.1,握手行写 127.0.0.1:<端口>。

命名管道的访问控制(handshake.md §4):Node 的 libuv 两样都给不了,既不能给管道设访问控制表,也不能拒绝远程客户端(不设 PIPE_REJECT_REMOTE_CLIENTS)。管道因此用 Windows 的缺省安全描述符:当前用户、管理员与 SYSTEM 可读写,其他用户只能只读打开、发不出请求,隔离与回环 TCP 一样靠会话令牌。需要只接受本机连接的改用回环 TCP(network: 'tcp')。

回调宿主的端点(handshake.md §4):XIHAN_PLUGIN_HOST_ADDRESS 是宿主按偏好排序、以 ; 分隔的一个或多个端点,最后一项总是回环 TCP。本 SDK 取第一个 @grpc/grpc-js 能连的项,之后不换:实测 Windows 上能连命名管道与回环 TCP、连不上 Unix 域套接字,其他系统上能连 Unix 域套接字与回环 TCP。所以 Windows 上宿主给出命名管道时经命名管道回调,排在前面的是本 SDK 连不上的项时经回环 TCP 回调。变量缺失、不合法或没有能连的项时插件照常服务,启动时在 stderr 记一条 warning,每次回调都以 PLUGINS_UNAVAILABLE_001 + plugins.host.unavailable(reason 为 no supported callback endpoint)失败、不发请求;findHost 在插件运行时交给处理器的上下文里总能取到客户端。

流式操作的契约还没有定义(RFC-0017「非目标」),插件只声明一元操作,InvokeStream 读第一帧后以 InvalidArgument 或 Unimplemented 结束。收尾的时限:Stop 按宿主给的宽限(为 0 时 5 秒)等在途调用;stdin 关闭与 SIGTERM 立即取消在途调用,最多 3 秒后以退出码 0 退出(lifecycle.md §7.5、§7.7)。

用规范仓库的黑盒运行器验证(需要 Go,在规范子模块里运行):

bash
cd spec/conformance
go run ./cmd/xihan-conformance plugin --dir <插件目录> --config '{"greeting":"hello"}' \
  --sample 'echoes.create={"text":"hi"}' --exclude echoes.crash

完整的示例在 examples/echo:四个操作(含故意崩溃、验证时排除的 echoes.crash)、一个订阅、健康项、配置与宿主回调。test/plugin-conformance.test.ts 把它放进临时目录、生成启动脚本,用运行器跑全部用例。

与宿主共用的行为 ​

以下行为按规范(ADR-0233、ADR-0235、ADR-0236、ADR-0237)定死,各语言 SDK 与 .NET 宿主相同。

  • JSON 文本(RFC-0001「JSON 文本」):Result 与 Error 的线上编码、操作载荷与清单都先过 readJsonText 的共同检查。语法按 RFC 8259(没有注释、尾逗号、NaN、前导零、正号、多个根值,空文本与只有空白也不是 JSON,开头的 BOM 是语法错误),嵌套不超过 64 层,字符串必须是合法的 Unicode(严格的 UTF-8,没有原始控制字符、非法转义与孤立的代理项),任何一层都不能有重复的成员名(按转义还原后比较,"a" 与 "a" 重复)。语法错误不论在哪里都优先,位置只写 $;重复成员写第一处重复的路径($.a[0].b)。
  • Result 与 Error 的读写(RFC-0001「Result」):无值成功只写 {"ok":true},读取时带了 value 即拒绝,{} 与 null 也一样;有值成功的 value 必填、不能是 null(值类型是 Maybe 时用 Result.fromJSONMaybe,null 即无值)。Error 的 message 必填,至少含一个空白之外的字符,为空或只有空白都不合法;空白是 RFC-0001「空白字符」写死的 25 个码位,不用 JavaScript 的 \s 与 trim(它们不认 U+0085、却认 U+FEFF)。ErrorInfo.literal 与 withText 的文案为空或只有空白时同样抛出 FrameworkError。messageKey、details、inner 写了就必须合法,写成 null 不合法;未知成员忽略。数字按值模型往返:64 位范围内的整数精确(9007199254740993 不会变成 9007199254740992),整数值的浮点写成 2.0、-0.0、1E+17,非有限的浮点写成字符串 "NaN"、"Infinity"、"-Infinity"。
  • 模板(RFC-0010「模板」):{{ / }} 转义;参数值为 null 写空串、不算缺值,undefined 算缺值。值先归到值模型(空、布尔、字符串、64 位整数、双精度浮点、数组、对象):数组与对象写成紧凑的 JSON,对象成员按名字的 UTF-16 码元序,嵌套的数字不随区域变化,超过 64 层的容器写 null。说明符只认 ^[DdFfNnXx][0-9]{0,2}$(D、F、N 不区分大小写,X / x 定十六进制的大小写,精度至多两位、可有前导零),E2、G、0.00、yyyy、D100、带空格的一律按无格式;D 与 X 只用于整数,X 只用于非负整数,F 与 N 用于整数与浮点,不适用时按无格式。F 与 N 按值的精确十进制展开舍入、正好一半时取偶(0.125 写 F2 得 0.12,2.675 得 2.67),写出全部整数位,负数舍入成零与负零都保留负号。浮点在 1e-4 ≤ |x| < 1e17 内写最短往返的十进制,范围外写 1E+17、9.9E-05、5E-324,负零写 -0,另有 NaN、Infinity、-Infinity。区域只改小数点与分组符,取规范的固定表(de-DE、es-ES、pt-BR 是 , 与 .,fr-FR 是 , 与 U+202F,ru-RU 是 , 与 U+00A0,其余与不给区域按不变文化),区域名不区分大小写;小数点用在无格式的浮点(含指数的尾数)与 F、N 上,分组符只用在 N 上。formatMessage、tryFormatMessage 与 formatValue 带区域,MessageCatalog 按命中的区域取符号。Describe 的参数按名字的序数顺序排列,与区域无关。消息键最长 128 个字符。
  • 内核错误(RFC-0011「错误码」):码、消息键、参数与 en-US 模板照 kernel-messages.json,SDK 自带这组英文模板(builtInMessages,另有清单读取的 kernel.manifest.* 与 primitives.manifest.*),ErrorInfo.message 在进程默认目录解析不出时用它;宿主收到错误后按键用自己的目录翻译。kernel.operation.type_mismatch 只带 id。配置期的重复登记与登记表已满以 FrameworkError 抛出,同样带 messageKey 与 details。
  • 调用器(RFC-0011 规则 2、5、9、10):进入管道前只核对未登记(KERNEL_NOTFOUND_001),类型化调用再核对契约(KERNEL_VALIDATION_002)。管道里有三个内置步骤,与 .NET 内核的内置中间件同名、同位置,都按归属 xihan.kernel.core 放在所在阶段的 Beginning(BuiltInStep、KernelOwner),与同位置的其他中间件按归属的序数序排序:Observe 阶段的 ObserveMiddleware 把排在它之后抛出的异常翻译为 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception(调用已中止时抛出的中止按取消归因),排在它之前的(Ingress 阶段,或 Observe 阶段 Beginning 上归属排在它之前的,如缺省的 app)抛出的异常原样从 invoke 抛给调用方;Resilience 阶段的 DeadlineMiddleware 进入时截止时间已到即 KERNEL_TIMEOUT_001 + kernel.invocation.deadline_before_start,进入时不核对取消,途中照 .NET 归因:下游抛出的中止成为超时或取消的结果,截止信号已触发时写成结果的 KERNEL_CANCELLED_001 按超时报告;Validate 阶段的 ValidationMiddleware 解码原始调用的载荷,类型化调用跳过。管道以成功结束而没有响应时返回 KERNEL_UNEXPECTED_001 + kernel.operation.no_response。XGI 入口在管道结束之后才把响应编码成载荷,中间件经 findOperationResponse 看到编码之前的对象;数字按值模型写,非有限的浮点(类型化的值不写成 null 或字符串)与循环引用写不出时以 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception 结束,FrameworkError 放进 inner,不抛给调用方,没有载荷。取消与截止时间只经 signal 通知(RFC-0003 第 1 条):调用器不与信号赛跑、不丢弃处理器的 Promise,信号触发之后处理器照常返回结果的,调用以那个结果结束。
  • 载荷的解码(RFC-0011 规则 2):长度为零的载荷等价于 {},只有空白不是 JSON。先过共同检查(语法错误的 reason 是 $,重复成员是它的路径),再按请求的形状在文本顺序里报第一处问题:成员名区分大小写,未知成员忽略,数字不从字符串读,整数不接受 1.0 与 1e2、超出范围即不符,浮点接受整数写法、上溢为无穷;字符串、数组、对象与任意 JSON 接受 null,整数、浮点、布尔不接受;必填成员缺少时在所在对象结束时报该对象的路径($、$.inner),值为 null 也算出现。载荷的文本按 JSON 值比较,空白、转义与数字的写法不是契约;任意 JSON 类型的成员原样保留读到的值,写回时 JSON 值相等(1e400 不变成 null 或无穷,超出双精度的整数精确,2.0 与 2 的区别保留)。
  • 调用上下文(RFC-0003、conventions/baggage-keys.md):已登记 Baggage 键的值为空、超过 256 个 UTF-16 码元或含控制字符时,由一组 Baggage 构造上下文(外部输入)丢弃该成员,withBaggage 逐项派生则抛出参数错误,幂等键两种情形都例外;traceparent 只认版本 00 与小写十六进制、全零的标识不合法,不合法的当作没给,采样只看标志的最低位,写出时只写 00 或 01,没有上游的根调用写 01。
  • 管道(RFC-0004 排序规则第 7、8 条):before / after 的两端是中间件名:按名字登记的实例名,或没有名字、只登记一次的中间件的类型名(按名字登记的实例不能按类型名指到);重复登记、未知阶段、约束主体未登记或有歧义在登记时立即报,约束目标未登记、有歧义、跨阶段与成环在排序时报。错误消息是与 .NET 逐字相同的英文原文,按名字登记的实例写成 类型名[名字],成环时按基准次序列出全部仍被卡住的中间件。
  • 清单(RFC-0002 解析规则 2 与「写出」):readManifest 返回 Result<Manifest>,错误码都是 KERNEL_CAPABILITY_006,按 JSON 文本(kernel.manifest.invalid_json,reason 是 $ 或第一处重复的路径)→ 字面量 null(kernel.manifest.empty)→ 按 Schema 逐项核对(kernel.manifest.invalid,reason 是第一处问题的路径:成员按文本顺序,每个成员依次查 Schema 之外的成员、null、类型、取值,对象的成员查完后按 required 的顺序报缺少的成员)→ 跨字段约束(primitives.manifest.*,参数只有 id)的顺序报第一处。接口版本不带前导零、不超过 2147483647,只有 requires[].version 可带一个 ^;中间件名至少一个字符,contributes.health 符合 ^[a-z][a-z0-9.-]*$,贡献的权限码重复时报第二次出现的项。readManifestFile 跳过开头的 UTF-8 BOM,文件不存在为 kernel.manifest.file_missing(参数 path);readManifest 收的文本不跳过 BOM。writeManifest 的排版逐字照规范:两个空格缩进、LF、末尾不换行、列表总写、缺省值写出、字符串只转义必须转义的字符。只有 Wasm 插件能贡献中间件由宿主在发现时核对,读清单时不核对。
  • 文法的匹配(RFC-0001「文法的匹配」):消息键、错误码、Baggage 键、清单与能力 ID、操作 ID、traceparent 等文法都按整串匹配,结尾的换行不例外。JavaScript 的 $ 在没有 m 标志时只匹配输入的末尾,本 SDK 的正则都不带 m,所以天然是整串匹配。

插件协议 ​

插件一侧的行为按 RFC-0017、规范的 plugin/ 与 ADR-0237:

  • 会话令牌:每个 RPC(含 Handshake 与流式调用)先按常数时间核对元数据 xihan-plugin-session,没有、不匹配或不止一个值(即使其中一个对)都以 Unauthenticated 结束、不执行;令牌先于一切处理,含流式调用读第一帧与调用次序的核对(handshake.md §4,ADR-0202)。
  • 启动:监听与写握手行之前核对清单与声明(handshake.md §1):kind 为 plugin、isolation 为 out-of-process、没有 contributes.pipeline、primitives 等于本 SDK 的原语层大版本 1、操作都在 contributes.operations 里(登记表本身不收重复的 ID)、订阅的主题合文法、方式为空、competing 或 broadcast 且(主题,类型)不重复、目录有 en-US。不合即在 stderr 记一条 error 日志并以 FrameworkError 抛出,不监听、不写握手行。健康项由健康回调在运行期给出,清单 contributes.health 之外的在上报时丢掉(见下)。
  • 握手行与端点(handshake.md §2):地址的空白是 RFC-0001「空白字符」,即 .NET 正则 \s 的集合(U+0009–U+000D、U+0020、U+0085、U+00A0、U+1680、U+2000–U+200A、U+2028、U+2029、U+202F、U+205F、U+3000;JavaScript 的 \s 不含 U+0085、却含 U+FEFF,所以逐个码元比较),其余字符(含中文路径)都可以出现在地址里;tcp 只认 127.0.0.0/8 里四段、不带前导零的点分十进制或 [::1],端口 1–65535、不带正负号与前导零。本 SDK 自己生成的地址不含空白,tcp 只写 127.0.0.1:<端口>。parseHandshakeLine、parseEndpoint、parseHostAddresses、selectHostEndpoint 回放 handshake-lines.json 与 host-addresses.json。
  • 握手(handshake.md §3):选宿主列表里最高的共同版本,没有即 FailedPrecondition;primitives 写清单的值,manifest 是清单原文去掉开头的 BOM,只声明一元操作(带 Schema),订阅按声明顺序、mode 总写 competing 或 broadcast,catalogs 只有作者自己的目录:运行时的 plugins.* 由宿主提供,不随握手发送。
  • 调用次序(lifecycle.md §7.1):Handshake 只在 Declared、Configure 只在 Resolved、Start 只在 Configured 接受,Stop 在 Declared、Draining、Stopped 与已经接受过一次 Stop 时拒绝;不在表里的以 FailedPrecondition 拒绝、什么都不做、状态不变。Health、WatchHealth、Invoke、InvokeStream、HandleEvent 任何状态都接受。
  • 配置(§7.2):configuration 为空等同 {};通不过共同的 JSON 读取检查或不是对象时不调配置回调,以 PLUGINS_UNEXPECTED_001 + plugins.process.failed(phase 为 configure,reason 为 the configuration is not a JSON object)失败、进入 Failed。PluginConfiguration.section 是原样的配置节,values 是类型化读取 ConfigurationSection:成员名按 ASCII 不区分大小写匹配,number 把字符串叶子按 JSON 数字的文法读成数字,boolean 只认 true、false(ASCII 不区分大小写),读不成时为 undefined。配置回调返回失败带那个错误进 Failed。
  • 启动与就绪(§7.3):启动回调成功后进入 Started,有健康回调时立即求一次、按结果进入 Ready、Degraded 或 Failed(报其他状态按 Ready,抛出按 Degraded),没有健康回调即 Ready,然后才应答。只有 Ready 与 Degraded 可服务,其余状态下的调用与投递为 PLUGINS_UNAVAILABLE_001 + plugins.process.unavailable(state 是状态名,如 Configured、Draining、Failed)。
  • 健康(§7.4):Start 之前报本地状态(Declared、Resolved、Configured)、没有健康项、不调回调;可服务期间每次 Health 求一次健康回调,只有它报的 Ready、Degraded、Failed 改变状态(Failed 不再回来,之后不再调回调);清单之外的健康项丢掉,同一个名字只记一条 warning;回调抛出时这一次是 Degraded,error 为 plugins.process.failed(phase 为 health),没有健康项,状态也迁到 Degraded,之后的结果照常决定状态。WatchHealth 先推当前状态,状态、健康项或错误变化时推,可服务期间每 10 秒(healthInterval)重新求一次回调,进入 Draining 推一次,应答 Stop 之后结束流。
  • 停止(§7.5):启动回调没成功过的(Resolved、Configured,或在那之前进入 Failed)不调停止回调,应答 ok;Started、Ready、Degraded 进入 Draining、拒绝新调用,等在途调用到宽限期(grace_seconds 为 0 按 5 秒),到时触发它们的取消信号、不再等,然后调停止回调(reason 原样),应答,进入 Stopped;启动成功过后进入 Failed 的不迁移状态,照样调停止回调。停止回调在进程里最多调一次,返回失败或抛出时写进 StopResponse.status,都照常以退出码 0 退出。
  • 收尾(§7.7):stdin 读到结尾(或出错)与 SIGTERM 都是收尾请求:可服务的进入 Draining,立即触发全部在途调用的取消信号并等它们,启动回调成功过、停止回调还没调过的调一次(reason 为 shutdown);从收到起最多 3 秒,到时不论完成与否以退出码 0 退出,正在处理的 Stop 同样受这 3 秒限制。运行时收尾之后不留下自己的句柄,作者的代码仍让进程活着时 1 秒后以退出码 0 退出;在同一个进程里运行插件的测试用 exit 选项接住。
  • 回调抛出的 reason(§7.6):生命周期与健康回调抛出时错误不带异常文本(文本只写进 stderr 日志),reason 是异常的简单类型名:构造函数的名字(TypeError、作者自己的异常类名),抛出原始值时是包装类型名(String、Number),null 与 undefined 写它们自己。
  • Invoke(invocation.md §1):会话令牌之后依次是操作不在握手声明里 gRPC Unimplemented、不可服务 plugins.process.unavailable、按 §2 还原上下文、经调用器与完整管道执行,空载荷等同 {}。InvokeStream 读第一帧:流在第一帧之前结束或第一帧不是 start 为 InvalidArgument,是 start 为 Unimplemented,不论操作是否声明、插件是否就绪;本 SDK 不提供流式操作的 API。
  • 调用上下文(invocation.md §2):trace_parent 按 RFC-0003 的文法取,不合即没有父 Span;trace_state 不进上下文,回调时写空;Baggage 只保留已登记的键,xihan.principal 原样交给作者;deadline 按严格的文法读(年 0001–9999、月日按公历、不认闰秒,换算成 UTC 之后在范围内),读不出当作没有,生效的截止时间取它与 gRPC 截止时间中较早的。JavaScript 的时钟精度是毫秒,第三位之后的小数截断、不进位。回调写 deadline 用 UTC、七位小数、+00:00(毫秒之后补零),gRPC 调用的截止时间与它相同。回放 deadlines.json。
  • Error 的写出与读入(invocation.md §3):写出时带消息键的错误 text 留空,由宿主按调用方的语言翻译,作者用 withText 填的文案也不写;只有自由文本错误(ErrorInfo.literal)写 text;details 是按值模型写出的 JSON 对象文本,没有为空;inner 照写。读入宿主写来的错误:码不合文法时整个换成 plugins.process.failed(phase 为 invoke,reason 为 invalid error code '<code>');键合文法按键还原、不留宿主的文案,否则是自由文本(text,为空或只有空白时取码);码不合文法时 phase 一律为 invoke(Host.Publish 的结果也一样),原来的 inner 丢掉;details 为空、只有空白、是空对象 {}、通不过共同的 JSON 读取检查、不是对象,或任何一层有读成双精度会溢出(±∞)的数时当作没有细节,下溢的数读成 0、超出 64 位的整数读成双精度(写回时仍是浮点),inner 同此;ok 为假却没有 error、或整个 status 缺失,为 plugins.process.failed(phase 为操作 ID 或 publish,reason 为 the host reported a failure without an error)。回放 error-reading.json。
  • HandleEvent(invocation.md §4):会话令牌 → 没有信封或方式不是空、competing、broadcast 为 gRPC InvalidArgument → 按(主题,方式,类型)找订阅,一个也没有为 KERNEL_NOTFOUND_001 + plugins.event.unsubscribed(id、topic、type、mode,空方式写 competing),不改交给另一种方式的处理器 → 不可服务为 plugins.process.unavailable → 还原上下文,匹配的订阅按声明顺序依次执行,第一个失败即终止并作为结果;处理器抛出为 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception(调用已中止时抛出的中止按取消归因,FrameworkError 的错误放进 inner)。
  • 回调(invocation.md §5):Host.Invoke 与 Host.Publish 发出之前按宿主的顺序在本地核对,不合即不发请求:所需权限(capability:kernel.pipeline、capability:messaging.queue)既在清单 permissions 里、也在 Configure 的 granted_permissions 里,否则 PLUGINS_DENIED_002 + plugins.callback.denied;上下文的 xihan.tenant 必须是插件此刻正在处理的某个调用或投递的租户(含调用结束后在后台回调),否则 plugins.callback.tenant_denied(ADR-0195);最后,回调上下文的截止时间已过或已被取消时也不发请求,结果与映射表相应的一行相同(截止时间已过按 DeadlineExceeded,已被取消按「Cancelled,取消信号已触发」)。有没有可用的端点排在这几项之前。Host.Publish 是批量:这两项、没有可用端点与 RPC 失败都是整批的结果(每项同一个错误),信封的 xihantenant 不在本地核对、交给宿主逐项判定;结果数与信封数不同时每项都是 plugins.process.failed(phase 为 publish)。元数据取自所在的调用上下文(上下文按 RFC-0003 写出的 traceparent,与其他载体同一取法;截止时间、已登记的 Baggage、空的 trace_state),带会话令牌。gRPC 状态只按 §5 的表映射、不另按时钟或令牌改写结果(回放 callback-status.json):上下文到了截止时间交给 gRPC 自己的截止时间、报 DeadlineExceeded,只有调用方取消时才取消回调;Unauthenticated 为 plugins.callback.session_invalid,PermissionDenied 为 plugins.callback.denied,DeadlineExceeded 为 KERNEL_TIMEOUT_001,调用方已取消的 Cancelled 为 KERNEL_CANCELLED_001,没有取消的 Cancelled、Unavailable 与连接失败为 PLUGINS_UNAVAILABLE_001 + plugins.host.unavailable(reason 为 <状态名>: <说明>),Host.Invoke 的 Unimplemented 与 InvalidArgument 为 kernel.operation.unknown 与 kernel.operation.invalid_payload,其余为 plugins.process.failed(phase 为操作 ID 或 publish)。
  • 日志与消息键:日志写 stderr,一行一个 JSON 对象:level(trace / debug / information / warning / error / critical)、message,其余是作用域属性(invocation.md §6)。运行时只用规范的七个消息键(invocation.md §8:plugins.process.unavailable、plugins.process.failed、plugins.event.unsubscribed、plugins.host.unavailable、plugins.callback.denied、plugins.callback.tenant_denied、plugins.callback.session_invalid),details 就是模板参数、不另加成员;目录 pluginMessages 带参考实现的 10 种区域,只用于插件这一侧的本地渲染与日志,回放 plugin-messages.json。

语言映射 ​

规范要求各 SDK 写明本语言的值怎样归到值模型、请求类型怎样声明(RFC-0010「模板」、RFC-0011 规则 2)。

  • 数字:安全整数的 number(负零除外)与 64 位范围内的 bigint 是整数;其余 number(小数、负零、NaN、无穷、超出安全整数的值)、超出 64 位的 bigint 与 Float64 是双精度浮点。number 分不出 2 与 2.0,所以值恰好是整数的浮点装进 Float64(new Float64(2),Number(v) 与算术照常可用)。
  • 读到的 JSON 数字:整数写法(没有小数点与指数)且在 64 位范围内是整数,安全整数读成 number,其余读成 bigint,-0 读成整数 0;其余是浮点,值恰好是安全整数(2.0、1e2、0.0)时读成 Float64,否则读成 number(-0.0 是负零)。换成数值再写出时十进制值与原文不同的(1e400、1e-400、超出 64 位的整数、多于双精度的有效数字)读成保留原文的 JsonNumber:值模型里是浮点(Number(v) 上溢为无穷、下溢为 0),写出时照原文,所以任意 JSON 的成员写回时 JSON 值相等。
  • 写出:writeJson 按 JSON.stringify 的规则写(先调用 toJSON,写不出时同样抛 TypeError),只是数字按值模型:整数写十进制,浮点写文本形式并给整数值补 .0,JsonNumber 照原文(缺省模式下上溢的按值模型写成 "Infinity");非有限值缺省写成字符串(无类型的值,如错误细节),{ nonFinite: 'reject' } 时写不出(类型化的值,如操作的响应)。JSON.stringify 写不出 bigint,也会把 2.0 写成 2、把 NaN 写成 null,线上编码不要用它。
  • 对象的顺序:JavaScript 对象把整数样式的键("1")提到前面。要按文本顺序报错的检查(载荷、清单)用 readJsonText 读出的 JsonMembers,它保留文档顺序;toJsonValue 转成普通对象。名为 __proto__ 的成员是普通成员,不改原型。
  • 模板里的其他值:字符串原样;数组、类型化数组、Set 与其他可迭代对象是数组;普通对象、JsonMembers 与 Map 是对象(Map 的键按文本形式写成名字);嵌套的 undefined 写 null;Date 写 toISOString();类实例、symbol 与函数写 String(value)。这些语言自己的文本不跨语言,插件要跨语言格式化时先转成字符串。
  • 请求的形状:RequestShape 相当于 .NET 的序列化元数据。string() 读成 string | null(接受 null);boolean()、int32()(number)、int64()(bigint)、float64()(number)不接受 null;array(item)、record(value)、object(members) 与 json() 接受 null。对象成员缺省是可选的,没有给出时不出现在结果里;RequestShape.required(shape) 声明必填,只要求出现,值为 null 也算出现。RequestShape.custom(decode) 相当于自定义转换器:形状核对跳过它,构建时转换,抛出 RequestDecodeError(path) 时取它的路径(用 JsonPath 从给出的位置往下拼)。RequestShapeType<typeof S> 取出形状读出的类型。
  • 清单的模型:readManifest 读出的 Manifest 补齐缺省值(role、activation、各列表、requires[].optional、bindings[].required),与 .NET 的 Manifest 一致;$schema 不在模型里,写出时总写 manifestSchemaUri。程序里构造的清单可以不写可选成员,writeManifest 写出后按 readManifest 再读一遍核对,读不回来即抛出带同样码、键与参数的 FrameworkError。

设计取舍 ​

  • 规范里的 Error 在这里叫 ErrorInfo,免得遮蔽全局的 Error;它不是异常,不 throw。可恢复失败经 Result 返回(含读不出来的清单与不合法的载荷),参数非法、程序里构造的清单写不出、管道登记冲突这类编程错误抛出 FrameworkError(带 code,消息是英文句子)。
  • Result<T> 与 Maybe<T> 是判别联合:if (result.ok) result.value、if (maybe.hasValue) maybe.value。成功值与 Some 的值不能为 null 或 undefined,没有值的成功是 Result<void>(Result.success())。
  • 枚举是冻结的常量对象加同名的字面量联合类型(PipelineStage.Observe === 'observe'),JSON 里就是名字;需要序号时用 lifecycleStateOrdinal 等函数。
  • TypedId<'order'> 是品牌类型,运行期就是底层的字符串或数值,标签不上线。
  • InvocationContext 不可变,withBaggage 等方法派生新的上下文;取消与截止时间是 signal(AbortSignal.any 合并调用方的信号与 AbortSignal.timeout),可以直接传给 fetch 等接口。截止信号已触发即报超时,调用方同时取消也一样(RFC-0003 第 1 条)。
  • 中间件、步、处理器与调用器都返回 Promise。查找以 find 开头,没有时返回 undefined。
  • 插件协议的代码由 ts-proto 从 spec/plugin/plugin.proto 生成在 src/plugin/gen:消息的编解码用 @bufbuild/protobuf 的 wire 运行时,服务定义直接给 @grpc/grpc-js,枚举生成冻结的常量对象,Node 照样直接剥离类型运行。生成代码不是公开入口,xihan-framework/plugin 的类型(Envelope、PluginHealth、PluginConfiguration 等)不暴露 protobuf 类型。生命周期回调与事件处理器返回 Result,抛出的异常只把文本写进日志、不写上线:生命周期与健康回调按 plugins.process.failed(reason 是简单类型名)返回,事件处理器按未处理异常返回。

一致性 ​

一致性档按 RFC-0024 划分,档表是规范的 conformance/profiles.json。

项现状
认领的档core 与 plugin
缺口无
钉的规范版本仓库 spec/ 子模块指向的提交;发预发布或正式版时子模块必须正好在规范标签上
成熟度Experimental:在有钉在规范标签上的发布版之前都是

原语、清单、调用上下文、管道与操作五个模块可用;进程外插件运行时 plugin(xihan.plugin.v1,基于 @grpc/grpc-js)可用,示例插件 echo 通过规范仓库黑盒运行器 xihan-conformance plugin 的全部用例(Windows 与 Linux)。

怎样验证:test/conformance-vectors.test.ts 读 spec/conformance/profiles.json,认领的档要求的每个向量要么被测试回放、要么列为缺口并写理由,规范在认领的档里新增向量时它失败;test/plugin-conformance.test.ts 用黑盒运行器跑示例插件 echo,CI 在 Windows 与 Linux 上都跑。

不提供的部分:

  • 流式操作的契约还没有定义(RFC-0017「非目标」),本 SDK 不实现流式调用,InvokeStream 读第一帧后以 InvalidArgument 或 Unimplemented 结束。
  • 远程 Provider 操作集(如 caching.distributed@1)仍未提供。
  • 规范列为宿主能力、语言 SDK 可以不提供的部分本 SDK 不提供:管道的运行期改动(UseOwned / RemoveOwnedBy)、Schema 校验、响应过滤与幂等回放还原响应(RFC-0004、RFC-0011 规则 10)。

破坏性改动与迁移 ​

本 SDK 还没有发布到 npm,目前没有需要迁移的破坏性改动。之后公开 API 或可观察行为有破坏性改动时,在这一节逐条写明旧行为、新行为与调用方怎么改。

Released under The MIT License