iii Browser SDKiii-browser-sdk参考把浏览器标签页变成 iii Engine 上的 Worker【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文围绕 iii 0.12.0 文档中的 Browser SDK 参考页 展开系统讲解iii-browser-sdk的完整公共 API 面如何用一个 WebSocket 把浏览器标签页接入 iii engine、在页面中注册可被引擎回调的函数与自定义触发器、以三种动作模式同步 / 即发即忘 / 入队调用后端函数以及ChannelReader/ChannelWriter流式通道、连接状态与错误语义。读完后你将能在前端代码中直接使用registerWorker、registerFunction、trigger、TriggerAction等原语并理解这些接口在仓库源码 sdk/packages/node/iii-browser 中的真实落点。定位独立实现而非 Node SDK 的浏览器构建文档原文档明确了一个前提Browser SDK 是 Node SDK 之外的一个独立实现standalone implementation而不是 Node SDK 编译出来的浏览器产物。这一点在仓库中可以得到印证包目录独立存在sdk/packages/node/iii-browser包名为iii-browser-sdkpackage.json 的描述为 “III SDK for the browser — no OpenTelemetry, no Node.js dependencies”且devDependencies中没有 OpenTelemetry 相关依赖包声明type: module通过tsdown同时产出 ESM/CJSdist/index.mjs/dist/index.cjs可直接在任意现代浏览器环境中以原生WebSocket运行。这意味着浏览器端的取舍是刻意的去掉结构化 Logger 与 OpenTelemetry 导出面保留全部“Worker 原语”函数、触发器、通道使前端页面可以作为一个 iii Worker 参与整个系统的函数调用与事件驱动网络。安装与包结构安装方式来自文档原文npm install iii-browser-sdk从 package.json 的exports字段可以看到该包提供的四个入口导入路径内容iii-browser-sdk根入口registerWorker、TriggerAction、ChannelReader、ChannelWriter、IIIConnectionState等iii-browser-sdk/stream流式原语IStream、StreamChangeEvent等类型iii-browser-sdk/state状态原语类型iii-browser-sdk/helpers辅助工具根入口的实际导出清单可以在 src/index.ts 中逐条核对运行时值导出为ChannelReader/ChannelWriter、RegistrationRejectedError、EngineFunctions/EngineTriggers常量、registerWorker与TriggerAction类型导出则覆盖InitOptions、StreamChannelRef、TriggerRequest、ISdk、FunctionRef、Trigger、TriggerTypeRef、EnqueueResult、MessageType等。建立连接registerWorker与InitOptions文档签名function registerWorker(address: string, options?: InitOptions): ISdk;address是 engine 的 SDK WebSocket URL。调用时连接会自动建立没有单独的connect()步骤返回的ISdk实例携带文档中列出的全部方法。仓库包 README 给出最小示例import { registerWorker } from iii-browser-sdk const iii registerWorker(ws://remotehost:3111)InitOptions的可选字段结合文档与包内类型定义字段类型说明invocationTimeoutMsnumbertrigger()的默认超时毫秒默认30000reconnectionConfigPartialIIIReconnectionConfigWebSocket 重连行为配置IIIReconnectionConfig类型同样从包根导出headersRecordstring, string浏览器原生 WebSocket 不支持自定义请求头认证应改用查询参数或 Cookie注意部署侧的前置条件浏览器连接的是 engine 的 worker-manager 监听器。包 README 提示需要在 engine 配置中为一个公开监听了例如iii-worker-manager#browser配置 RBAC 保护且不应把私有监听器暴露给不可信的浏览器客户端。常用方法registerFunction在标签页中注册可调用的函数worker.registerFunction( functionId: string, handler: RemoteFunctionHandler, options?: RegisterFunctionOptions, ): FunctionRef;functionId唯一函数标识使用::做命名空间例如ui::show-notificationhandler异步处理函数(data: TInput) PromiseTOutput引擎侧任何 worker 都可以通过trigger回调它——这是“后端向浏览器推数据”的实时模式基础options可选的description、request_format/response_format、metadata返回值FunctionRef含id与unregister()可随时把函数从引擎注销。典型的浏览器侧函数注册来自 包 README 的 Hello Worldiii.registerFunction(ui::show-notification, async (data: { title: string; body: string }) { showToast(data.title, data.body) return { displayed: true } })registerTrigger把已注册函数绑定到触发器实例worker.registerTrigger(trigger: RegisterTriggerInput): Trigger;文档特别强调了一个 API 不对称点触发器没有顶层的unregisterTrigger方法注销必须通过返回句柄上的Trigger.unregister()完成。RegisterTriggerInput的字段为type触发器类型、function_id、config及可选id。registerTriggerType/unregisterTriggerType自定义触发器类型worker.registerTriggerTypeTConfig( triggerType: RegisterTriggerTypeInput, handler: TriggerHandlerTConfig, ): TriggerTypeRefTConfig; worker.unregisterTriggerType(triggerType: RegisterTriggerTypeInput): void;registerTriggerType让当前标签页声明并承载一种新的触发器类型handler是一个实现TriggerHandler的对象含registerTrigger/unregisterTrigger两个异步方法在触发器实例被引擎注册/注销时分别回调。返回的TriggerTypeRefTConfig提供id、registerTrigger、registerFunction、unregister等便捷方法免去每次重复填写type字段。浏览器是自定义触发器类型的自然宿主之一——例如把“倒计时结束”“用户点击”这类纯前端事件做成可被引擎调度的触发器类型。trigger调用已注册函数worker.triggerTInput, TOutput(request: TriggerRequestTInput): PromiseTOutput;TriggerRequest字段字段类型必填说明function_idstring是目标函数 IDpayloadTInput是调用载荷actionTriggerAction否路由动作省略即同步请求/响应timeoutMsnumber否覆盖InitOptions.invocationTimeoutMs的默认超时Promise 的解析语义随action变化文档原文要点同步调用解析为函数的返回值TriggerAction.Enqueue解析为一个EnqueueResult入队回执TriggerAction.Void解析为undefined。// 同步调用 const users await iii.trigger({ function_id: api::get::users, payload: {}, })shutdownworker.shutdown(): Promisevoid;断开与 engine 的连接并释放资源建议在页面卸载beforeunload等时机时调用。Trigger actionsVoid与EnqueueTriggerAction是一个运行时常量对象产出的值传给trigger的action字段TriggerAction.Void(); // fire-and-forget TriggerAction.Enqueue({ queue: math }); // route through iii-queue其底层类型是联合类型{ type: enqueue; queue: string } | { type: void }因此三种调用形态的完整示例为// 1) 同步请求/响应默认 const result await iii.trigger({ function_id: greet, payload: { name: World } }) // 2) 即发即忘 await iii.trigger({ function_id: send-email, payload: { to: userexample.com }, action: TriggerAction.Void(), }) // 3) 通过命名队列异步处理 const receipt await iii.trigger({ function_id: process-order, payload: { orderId: 123 }, action: TriggerAction.Enqueue({ queue: orders }), })Enqueue会把调用路由进 engine 的 iii-queue 子系统适合长耗时或可重试的任务回执EnqueueResult可用于幂等判断。Channels基于原生 WebSocket 的流式通道文档说明ChannelReader和ChannelWriter是包装 engine 流 WebSocket 的运行时类直接使用浏览器的原生 WebSocket APIStreamChannelRef是在 SDK 各调用之间传递、用于标识某个通道端点的可序列化类型type StreamChannelRef { channel_id: string; access_key: string; direction: read | write; }StreamChannelRef的字段含义access_key为访问凭证direction区分读/写端在包 README 与 0.11.0 版 自动生成 API 参考 中一致。通道端点本身由iii.createChannel(bufferSize)创建bufferSize缺省 64返回含reader/writer与readerRef/writerRef的对象两个 ref 可以放进调用载荷发给其他 worker实现跨 worker 的流式数据传输。读写端方法面文档列表与 src/channels.ts 源码逐一吻合类方法说明ChannelReaderonMessage(cb)注册文本消息回调ChannelReaderonBinary(cb)注册二进制帧回调Uint8ArrayChannelReaderreadAll()异步读取全部待发二进制数据ChannelReaderclose()关闭读端连接ChannelWritersendMessage(msg: string)发送文本消息ChannelWritersendBinary(data: Uint8Array)发送二进制数据ChannelWriterclose()关闭写端连接一个典型的本地读取用法源自包注释与 API 参考示例const channel await iii.createChannel() // 把 writer ref 传给另一个函数由它对端写入 await iii.trigger({ function_id: stream-producer, payload: { outputChannel: channel.writerRef }, }) channel.reader.onMessage((msg) { console.log(Received:, msg) })连接状态IIIConnectionState文档定义type IIIConnectionState | disconnected | connecting | connected | reconnecting | failed;该字面量类型别名从包根导出。src/index.ts 中可以看到它实际由iii-constants模块再导出连同IIIReconnectionConfig这五个状态覆盖了浏览器网络波动下的完整生命周期断线后 SDK 会进入reconnecting并按reconnectionConfig自动重连重连耗尽后落入failed。前端可以用该状态驱动 UI 上的连接指示器。Info 类型FunctionInfo与TriggerInfoFunctionInfofunction_id必填、可选description、可选request_format/response_format、可选metadataTriggerInfoid、trigger_type、function_id必填可选config/metadata。文档同时划清了一条边界WorkerInfo与WorkerMetadata不属于本 SDK。当浏览器客户端需要其他 worker 的元数据时应使用 engine 的 introspection 函数参见 engine-sdk 参考的 engine 发现函数一节即经由engine::workers::list等引擎内省函数完成而不是在 Browser SDK 中寻找。MessageType线协议帧枚举MessageType是一个运行时枚举命名了 SDK 与 engine 之间交换的每一类 wire frame调用方很少直接使用但在调试协议交互时有用。从 0.11.0 版 自动生成参考 可以列出其成员全集InvocationResult、InvokeFunction、RegisterFunction、RegisterService、RegisterTrigger、RegisterTriggerType、TriggerRegistrationResult、UnregisterFunction、UnregisterTrigger、UnregisterTriggerType、WorkerRegistered。这些帧名与包根导出的RegisterFunctionMessage、RegisterTriggerMessage、RegisterTriggerTypeMessage等消息类型一一对应每个*Message类型都携带message_type字段标注帧类型而RegisterFunctionOptions、RegisterTriggerInput等对外输入类型正是把message_type字段剥离后的Omit变体——调用方无需也不应手填message_type。本 SDK 不具备的能力面文档明确列出了两个“不在此 SDK 中”的表面理解它们能避免集成时的误用Logger。Browser SDK 不附带结构化 logger应使用浏览器内置console并依赖 iii-observability worker 提供的 OpenTelemetry 表面做导出。这与 package.json 中 “no OpenTelemetry” 的定位一致。Error class。不存在IIIError/IIIInvocationError类失败一律表现为携带Error实例的 rejected promise需要自行检查message以及附加的code字段获取 engine 错误码。try { await iii.trigger({ function_id: flaky::op, payload: {} }) } catch (err) { // err 是 Error 实例engine 错误码在 (err as any).code console.error((err as Error).message) }值得补充的是src/index.ts 还导出了RegistrationRejectedError用于函数/触发器注册被引擎拒绝如命名冲突的场景它是当前包内唯一显式导出的错误类型。工程验证路径如果想在自己的项目里核对本文行为仓库提供了完整的测试基建均为只读参考sdk/packages/node/iii-browser/tests/channels.test.ts、triggers.test.ts、trigger-types.test.ts 等单测基于mock-websocket验证线协议行为tests/integration 下的bridge.test.ts、channels.test.ts、trigger-type-lifecycle.test.ts等集成测试针对真实 engine 验证通道与触发器类型生命周期exports.test.ts 校验包根导出面与文档所述公共 API 保持一致。小结iii-browser-sdk的公共面可以归纳为一句话一个 WebSocket 连接 与 Node 端同构的 Worker 原语。registerWorker建立连接registerFunction/registerTrigger/registerTriggerType让浏览器标签页成为引擎可调度的 Workertrigger配合TriggerAction.Void()/TriggerAction.Enqueue()覆盖同步、即发即忘与队列三种调用模式ChannelReader/ChannelWriter提供基于原生 WebSocket 的双向流IIIConnectionState暴露五态连接生命周期而 Logger 与专用 Error class 是刻意裁剪掉的表面。所有接口细节都可以对照 sdk/packages/node/iii-browser 目录下的src/源码与tests/用例逐条验证。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考