ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

iii Engine 线协议深度解析:端口拓扑、消息帧语义与调用生命周期

iii Engine 线协议深度解析:端口拓扑、消息帧语义与调用生命周期 iii Engine 线协议深度解析端口拓扑、消息帧语义与调用生命周期【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文围绕 iii 引擎engine与 SDK Worker 之间交换的线级协议wire-level protocol展开先讲清引擎的端口拓扑与连接建立流程再逐帧拆解Message枚举定义的 14 种协议帧的 JSON 形态与字段语义最后覆盖 trigger actions 路由、调用生命周期、引擎内置发现函数与开箱即用的 OTel 指标。读完后你不仅能读懂引擎与任意语言 Worker 之间的通信契约还能在需要手写客户端、调试注册失败或对接 Prometheus 时直接参照源码定位问题。需要说明的是绝大多数项目通过语言 SDKNode、Python、Rust、Browser接入永远不会直接接触本协议但下面所有帧结构都是这些 SDK 最终序列化的“事实来源”理解了它也就理解了 SDK 的底层行为。1. 端口拓扑四个端口的职责划分iii 采用 WebSocket 路由的 worker mesh 模型一个 engine 进程持有所有已连接 worker、其暴露的函数Function与触发器Trigger的实时注册表worker 是独立 OS 进程打开到引擎的 WebSocket 完成注册没有任何 worker 之间的直接通信所有调用都经引擎路由——这一点在 engine_fn 模块说明中有明确表述。引擎自身绑定三个端口并伴随 observability worker 的一个端口端口绑定方表面3111engineREST API。3112engineStream APIWebSocket消费者侧流订阅。49134engineSDK WebSocket即iii_sdk::register_worker打开的通道。9464iii-observabilityworkerPrometheus metrics 端点通常与引擎同一容器暴露。Console UI 运行在3113端口由iii console单独启动。从源码看49134是各组件默认连接引擎的 SDK 端口外部 worker 的默认地址即ws://127.0.0.1:49134见 engine/src/workers/external.rs队列 bridge 适配器的bridge_url默认值同样是ws://localhost:49134见 engine/src/workers/queue/config.rs而 Stream API 的3112端口则出现在引擎配置与重写逻辑中如 engine/src/workers/config_rewrite.rs。这意味着同一套默认值贯穿引擎本地回环与远程桥接两种部署形态。2. 连接流程从注册到双向通信Worker 打开 SDK WebSocket默认ws://127.0.0.1:49134发送其内存中持有的全部注册声明每个它打算暴露的RegisterFunction、RegisterTrigger与RegisterTriggerType。随后 worker 调用engine::workers::register发布自身元数据runtime、version、OS、PID、isolation引擎以携带所分配 UUID 的WorkerRegistered { worker_id }帧应答。此后连接变为双向引擎向 worker 推送InvokeFunction帧worker 则回推InvocationResult、追加注册或注销声明。源码中的连接契约细节协议帧的完整定义位于 engine/src/protocol.rs 中的Message枚举serde 标签化、小写编码。除了文档表中的帧源码还展示了若干与连接治理相关的机制WorkerRegistered携带reattach_token引擎在注册应答中下发一个仅通过该连接自身 socket 传递的 secretReattach帧engine/src/protocol.rsworker 重连时以第一条消息身份发送previous_worker_id与reattach_token引擎随即让旧连接按正常断连流程退役使注册重放registration replay落在干净状态上而不是与旧连接清理逻辑竞争。token 是必需的——worker id 是公开可发现的而 token 只在该连接自己的 socket 上发送过因此旧引擎遇到未知消息类型只会告警并忽略保持版本偏斜安全version-skew safeRegistrationRejected帧携带code、namespace、owner_worker_id等字段用于拒绝命名空间冲突等注册。这套重连语义解释了为什么 worker 网络重启后已注册的函数与触发器能够“无缝”回到注册表而不是需要 SDK 层面重新发明状态恢复。3. 消息类型全集每一帧都是按message_type区分的 JSON 对象。完整集合定义于Message帧方向用途RegisterFunctionworker - engine让某个函数可通过function_id被调用。UnregisterFunctionworker - engine移除一个先前注册的函数。RegisterTriggerworker - engine将函数绑定到一个 trigger 实例。UnregisterTriggerworker - engine移除一个 trigger 绑定。TriggerRegistrationResultengine - workerRegisterTrigger的确认 / 错误。RegisterTriggerTypeworker - engine声明 worker 提供的一种新 trigger 类型。RegisterServiceworker - engine将相关函数归组到一个 service id 之下。InvokeFunctionengine - worker携带 payload 调用一个已注册函数。InvocationResultworker - engine把函数结果或错误带回。WorkerRegisteredengine - worker确认 worker并附带分配的worker_id。Ping/Pong双向活性探测避免空闲连接超时。4. 各帧的 JSON 形态与字段语义4.1RegisterFunction{ message_type: register_function, id: math::add, description: Add two numbers., request_format: { type: object, properties: { a: { type: number }, b: { type: number } } }, response_format: { type: object, properties: { c: { type: number } } }, metadata: { owner: math-team }, invocation: null }字段说明对照 engine/src/protocol.rs 的定义id必填函数标识采用service::name形式的命名约定description、request_format、response_formatJSON Schema、metadata均可选它们喂给 iii console 与 agent 可读的 skillsinvocation保留给外部 HTTP 函数。源码中它对应HttpInvocationRef结构engine/src/protocol.rsurl必填method缺省为POST并可选timeout_ms、headers与auth。对于进程内 handler保持null。4.2RegisterTrigger{ message_type: register_trigger, id: math::addhttp, trigger_type: http, function_id: math::add, config: { api_path: /math/add, http_method: POST }, metadata: null }config是按 trigger 类型区分的配置其形状由声明该trigger_type的 worker 决定例如http触发器由iii-http声明。引擎以TriggerRegistrationResult帧应答其中携带可选的error: ErrorBody。源码中RegisterTrigger还有两个可选的加性字段engine/src/protocol.rsnamespacetrigger 的目标函数在该命名空间中解析缺省为引擎默认命名空间且与注册连接的命名空间相互独立trigger_namespace在哪个命名空间查找trigger_type的 provider——缺省不是“默认”而是让引擎按“注册连接命名空间优先、默认命名空间兜底”的顺序解析。这正是项目可以提供自己的 provider 覆盖引擎内置同名类型、而尚未迁移的 worker 仍能无感命中引擎内置版本的机制来源。两个字段对旧版对端保持线兼容不发送即不解析。4.3RegisterTriggerType{ message_type: register_trigger_type, id: webhook, description: HTTP webhook trigger, trigger_request_format: { type: object, ...: ... }, call_request_format: { type: object, ...: ... } }trigger_request_format是该 trigger 每次绑定所用config的 JSON Schema——即上一节RegisterTrigger.config的校验依据call_request_format是 trigger 触发时投递给绑定函数 payload 的 JSON Schema。从源码结构看该帧同样支持namespace字段缺省表示“注册连接的命名空间”所有 SDK 的期望从而避免两个项目声明同类型 id 时互相覆盖引擎内置 provider 则注册在默认命名空间中供 TriggerRegistry 的解析逻辑兜底查找。4.4InvokeFunction{ message_type: invoke_function, invocation_id: 9f3c…, function_id: math::add, data: { a: 2, b: 3 }, traceparent: 00-…, baggage: kv,…, action: { type: void } }invocation_id在Void调用中省略worker 没有可应答的结果通道traceparent与baggage携带 W3C trace context用于跨进程分布式追踪action是路由标志见 Trigger actions缺省 /null表示同步调用。对照 源码定义InvokeFunction还有两个可选项metadata是每次调用的元数据侧车作为独立参数投递给目标 handler而非折叠进datanamespace是路由目标命名空间缺省为默认命名空间两者对不发送它们的旧版对端均保持线兼容。4.5InvocationResult成功{ message_type: invocation_result, invocation_id: 9f3c…, function_id: math::add, result: { c: 5 }, error: null, traceparent: 00-…, baggage: kv,… }失败{ message_type: invocation_result, invocation_id: 9f3c…, function_id: math::add, result: null, error: { code: invocation_failed, message: boom, stacktrace: TraceError: … } }引擎当前会发出的ErrorBody.code取值包括invocation_failed——handler 抛出异常invocation_stopped——所属 worker 在调用进行中断开引擎取消在途调用并向调用方暴露该码function_not_found——目标函数不存在function_not_invokable——函数不可被调用例如外部 HTTP 函数不可在引擎侧直接触发TIMEOUT——客户端侧超时FORBIDDEN——RBAC 拒绝。5. Trigger actions 与调用生命周期InvokeFunction.action在 Rust 侧对应TriggerAction枚举engine/src/protocol.rs按type标签化并以小写编码上线线上形状含义省略 /null同步调用worker 以InvocationResult应答。{ type: void }fire-and-forget无invocation_id无应答。{ type: enqueue, queue: math }经由指定名称的队列路由由iii-queueworker 提供。对应三种生命周期同步引擎分配invocation_id把InvokeFunction转发给所属 worker并等待匹配的InvocationResultVoid引擎不带invocation_id转发且永不期待应答Enqueue引擎把调用移交给队列 worker队列 worker 将其持久化并按队列的重试策略在订阅侧重新调用目标函数——即失败重试与削峰由队列策略承担而不是调用方。6. 引擎发现函数与发现触发器引擎在engine::*命名空间下注册了一组内置函数用于内省与 worker 生命周期管理定义于 engine 的engine_fn模块模块说明见 engine/src/workers/engine_fn/README.md函数用途engine::channels::create创建流式 channel 的 reader / writer 对。engine::functions::list列出全部已注册函数可按include_internal过滤。engine::workers::list列出所有已连接 worker 及其指标。engine::triggers::list列出全部已注册 trigger可按include_internal过滤。engine::trigger-types::list列出全部已注册 trigger 类型及其 config / call request schema。engine::workers::register发布调用方 worker 的元数据runtime、version、OS、PID、isolation。与之配套的两个发现触发器触发器触发时机engine::functions-available函数被注册或注销。engine::workers-availableworker 连接或断开。这使得控制台、agent harness 等无需轮询即可对拓扑变化做响应式反应——例如 harness 监听到engine::workers-available后重新拉取engine::functions::list刷新工具清单。7. 引擎内置指标OTel 名称、单位与实现位置以下指标由引擎自身发出与 worker 使用哪种语言 SDK 无关。名称与单位来自 engine/src/workers/observability/metrics.rs 中EngineMetrics::new()的构造代码——每个指标都通过全局 OTel meter 注册并声明 description 与 unit最终由iii-observabilityworker 经9464端口的 Prometheus 表面导出。调用维度指标类型单位iii.invocations.totalcounterinvocationsiii.invocation.durationhistogramsecondsiii.invocation.errors.totalcountererrorsWorker 全局维度指标类型单位iii.workers.activegaugeworkersiii.workers.spawns.totalcounterworkersiii.workers.deaths.totalcounterworkersiii.workers.by_statusgaugeworkers单 worker 维度指标类型单位iii.worker.memory.heap.bytesgaugebytesiii.worker.memory.rss.bytesgaugebytesiii.worker.cpu.percentgauge%iii.worker.event_loop.lag.msgaugemsiii.worker.uptime.secondsgauges需要说明的边界这些指标名、仪器类型counter/gauge/histogram与单位是引擎源码中的硬事实而 traces、logs、采样规则、告警与 rollup 等观测内省能力则端到端由iii-observabilityworker 负责引擎本身只承担“发数”一侧。8. 小结与进一步阅读协议的唯一事实来源是 engine/src/protocol.rs 中的Message枚举14 种帧覆盖注册、调用、结果、心跳与重连治理手写客户端的最小可行路径是连接ws://127.0.0.1:49134→ 发送全部RegisterFunction/RegisterTrigger/RegisterTriggerType→ 处理WorkerRegistered→ 应答后续InvokeFunction注意action为void时不应也无法应答排查注册问题优先看RegistrationRejected的code与namespace字段排查在途失败则对照第 4.5 节的错误码表更多上下文可参考 engine-sdk 原始文档、engine_fn 模块说明以及语言 SDK 文档Node / Python / Rust / Browser。适用前提本文以当前仓库中docs/0-12-0版本文档与 engine 源码为准端口默认值与错误码集合可能随版本演进接入前建议以目标版本的 protocol.rs 为最终依据。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表