iii 创建 Worker 完全指南：以 Worker 为单位扩展 iii 系统的核心能力

iii 创建 Worker 完全指南以 Worker 为单位扩展 iii 系统的核心能力【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii在 iii 中任何一项新能力——队列、调度器、HTTP 边缘、浏览器标签页、Agent、CRM 集成或沙箱——都不是通过修改引擎来添加的而是通过编写一个连接 Engine 并注册 Triggers 与 Functions 的 Worker 来实现。本文围绕 iii 官方文档 Creating Workers / Overview 展开完整覆盖 Worker 的心智模型、如何复用现有 Worker、以及从脚手架到注册 Function/Trigger 的完整实操路径并结合当前仓库的引擎源码与 SDK 实现给出源码级佐证。读完本文你将掌握“为什么加 Worker 而不是改 Engine”的设计逻辑并能独立完成一个 Worker 的创建、连接与能力注册。Worker 是 iii 中的“服务”能力的唯一单元iii 的核心设计立场是Worker 是系统中的能力单元Worker 本身就是服务。当你需要新行为时正确做法是编写一个新的 Worker或从 registry 安装一个现成的而不是给 Engine 打补丁、添加插件或 fork 引擎。Engine 是一个固定的协调者fixed coordinator它只做两件事在 Worker 之间路由调用invocation维护一份实时注册表live registry记录每个 Worker 当前提供什么。这意味着让 iii 系统“做有用的事”的一切逻辑都运行在 Worker 内部。因此“加一个 Worker”几乎是对“我如何给 iii 加上 X 功能”这个问题的通用答案——缺失的能力由 Worker 填补而非由 iii 本体的变更填补。四个构件的心智模型理解 Worker 的定位需要先建立 ii iii 系统的四个基本构件详见 Understanding iii / OverviewWorker任何连接到 Engine 并向其注册 Triggers 和 Functions 的实体。Worker 可以运行在任何地方笔记本、容器、浏览器标签页、microVM和任何语言只要它能向 Engine 打开一个 WebSocket 连接。FunctionWorker 内部的一个具名处理器接收 payload 并返回结果。Function 标识符遵循service::name约定如math::add、state::get保证跨 Worker 重启和跨语言边界稳定。Trigger导致 Function 运行的“绑定”。Trigger 由三部分组成type事件类型如 http、cron、queue message、state change、config每类型的细节如 HTTP 路径或 cron 表达式、function_id要调用的 Function。Engine单进程协调者。它接受 Worker 连接、维护所有已注册 Function 和 Trigger 的注册表并把每次调用路由到当前提供目标 Function 的那个 Worker。从这个模型可以推出一条重要结论Worker 与 Worker 之间没有任何直连流量。以 Quickstart 为例caller-worker调用math::add时请求经由 Engine 查表后路由到math-workerEngine 的 Quickstart 拓扑图 中每条箭头都是 Worker 与 Engine 之间的 WebSocket 连接。Worker 概念被刻意收窄它不是微服务、不是任务运行器、也不是 sidecar而是 Engine 实时注册表中的一个参与者。一个长期运行、每秒处理数千次调用的 Worker与一个连接、注册、执行一次就退出的短期 Worker在 Engine 眼里待遇完全相同。同时Worker 被设计为彼此隔离的独立进程——一个 Worker 崩溃时它的 Functions 和 Triggers 从路由表中移除其他 Worker 继续服务故障不传播。复用优先在现有 Worker 之上构建绝大多数你将要创建的 Worker 都会复用一到多个现有 Worker 来完成基础能力——一个 HTTP 端点、一个键值存储、一个队列、调度、可观测性、沙箱——而不是从零自建。文档给出的建议是先伸手拿现成的再考虑自己写。最常用的“公共 Worker”Common Workers在 Creating Workers 章节中被单列它们各自对应仓库中的一篇专题文档公共 Worker能力对应文档HTTP将 Functions 暴露为 HTTP 端点docs/creating-workers/http.mdxQueues带重试与死信队列的异步作业处理docs/created-workers/queues.mdxObservability跨 Worker 的 traces、metrics 与 logsdocs/creating-workers/observability.mdxSandboxes在隔离 microVM 中运行不受信任或短生命周期的代码docs/creating-workers/sandboxes.mdxAccess Control通过 RBAC 门控的监听器接受不受信任的连接docs/creating-workers/worker-manager.mdx除了本地文档外完整的 Worker 目录还发布在官方 registry 站点workers.iii.dev。文档的建议是如果你的 Worker 需要某个通用能力先去这两个地方找找不到再自己写。源码佐证引擎如何“固定”而不改从当前仓库源码结构看这个“Engine 永不改变、能力全部来自 Worker”的设计是真实落地的。引擎的内置 Worker 都位于 engine/src/workers/ 目录下每个内置 Worker 是一个独立模块各自携带iii.worker.yaml清单与 skills 元数据engine/src/workers/registry.rs——实时注册表本身维护连接 Worker 与所注册 Function/Trigger 的状态engine/src/workers/queue/、engine/src/workers/observability/、engine/src/workers/stream/——分别对应队列、可观测性、流式 Worker 的实现engine/src/workers/worker/——iii-worker-manager即 Access Control 一节中用于 RBAC 门控的 Worker其中 rbac_config.rs 与 rbac_session.rs 从源码结构看承担了 RBAC 策略与会话管理engine/src/workers/engine_fn/——Engine 自身暴露的发现类 Functions如engine::workers::list的宿主。值得注意的是引擎同时把部分原语下沉为库级内置模块如 engine/src/builtins/ 下的kv、queue、pubsub_lite、queue_kv这与文档中“键值存储、队列是现成 Worker 能力”的表述相互印证。构建 Worker从脚手架到连接 Engine官方文档将“如何构建 Worker”拆为三个子主题每个主题对应一篇独立 how-to子主题解决的问题对应文档Workers把 Worker 连接到 Engine 并部署docs/creating-workers/workers.mdxTriggers声明是什么让这些 Functions 运行docs/creating-workers/triggers.mdxFunctions注册一个 Worker 贡献的 Functionsdocs/creating-workers/functions.mdx1. 脚手架iii worker initiii worker init从零创建一个独立的 Worker它会写出一个安装了 iii SDK 的语言特定项目目录、一份iii.worker.yaml清单以及可供你替换的 Function 与 Trigger 注册示例代码。# 交互式提示选择语言 iii worker init my-worker # 全脚本化传 --language 跳过提示 iii worker init my-worker --language typescript关键参数说明来自 Workers 文档支持的语言typescriptts、javascriptjs、pythonpy、rustrs位置参数NAME作为目标目录可用--directory覆盖默认情况下向非空目录初始化会失败用--allow-non-empty可放宽程序入口通常位于src/index.ext或src/main.ext具体随语言模板略有差异。需要强调一个前提iii worker init只是便利设施不是必需。一个 Worker 的定义是“任何使用 iii SDK、连接 iii 实例并调用registerWorker()的代码”。你可以手写它、跑在裸金属或自己的虚拟化环境里、部署到任何地方iii worker只是创建和运行 Worker 的一种方式。若要安装 registry 中现成的 Worker则使用iii worker add例如 http Worker 页面中的iii worker add http。2. 连接 EngineWebSocket 与III_URLWorker 通过 WebSocket 连接 Engine。约定是通过环境变量III_URL传入引擎地址也可以显式传给register_worker。这条连接串是 Worker 与其加入的 iii 实例之间唯一的耦合点——因此 Worker 进程可以部署在网络上任何可达的位置。三种 SDK 的最小连接示例继承自 Workers 文档// Node / TypeScript import { registerWorker } from iii-sdk; const url process.env.III_URL; if (!url) throw new Error(III_URL must be set); const worker registerWorker(url, { workerName: my-worker, workerDescription: One-line summary of what this worker does, });# Python import os from iii import register_worker, InitOptions worker register_worker( os.environ.get(III_URL), InitOptions( worker_namemy-worker, worker_descriptionOne-line summary of what this worker does, ), )// Rust use iii_sdk::runtime::WorkerMetadata; use iii_sdk::{InitOptions, register_worker}; let url std::env::var(III_URL).expect(III_URL must be set); let worker register_worker( url, InitOptions { metadata: Some(WorkerMetadata { name: my-worker.into(), description: Some(One-line summary of what this worker does.into()), ..Default::default() }), ..Default::default() }, );从源码看Node SDK 的registerWorker正是从 sdk/packages/node/iii/src/index.ts 导出的核心入口其Configuration options passed to registerWorker中url字段即 Engine 的 WebSocket 地址如ws://localhost:49134与文档描述一致。安全前提上面的直连方式是全信任连接适用于你自行运行的 Worker。对于不受信任的 Worker浏览器客户端或第三方应通过iii-worker-manager的 RBAC 监听器连接并用 auth function 做门控参见 Access Control 文档。3. 注册 Function 与 TriggerWorker 向系统贡献能力的方式是注册 Function每个 Function 有一个service::name形式的id这是 Trigger 引用它时使用的function_id、一个接收 payload 并返回结果的 handler以及可选的 request/response JSON Schema。最小 Function 注册示例继承自 Functions 文档import { registerWorker } from iii-sdk; const url process.env.III_URL; if (!url) throw new Error(III_URL must be set); const worker registerWorker(url); worker.registerFunction(math::add, async (payload: { a: number; b: number }) { return { c: payload.a payload.b }; });def add_handler(payload: dict) - dict: return {c: payload[a] payload[b]} worker.register_function(math::add, add_handler)worker.register_function(math::add, RegisterFunction::new(|input: AddInput| { Ok(serde_json::json!({ c: input.a input.b })) }));几个文档明确指出的要点不同 Trigger 类型期望不同的 payload 形状cron调用 Function 时不带参数http则提供包含body、headers等属性的标准 HTTP 风格 payload。每种类型的预期 payload 以其发布 Worker 的文档为准。Schema 目前只是契约文档附带的 request/response schema 会存入 Function、显示在 console 与iii trigger --help中但引擎暂不做运行时校验不会拒绝不匹配的 payload。registerFunction返回带unregister()的句柄可在运行时把 Function 从引擎移除Worker 断开时其全部 Function 自动移除。Function 注册后自动获得“直接调用”能力任何连接的 Worker 可用worker.trigger()、CLI 可用iii trigger math::add a2 b3直接调用它无需显式注册 Trigger。Trigger 的职责则是把 Function 绑定到外部事件源。以http类型为例继承自 Triggers 文档worker.registerTrigger({ type: http, function_id: math::add, config: { api_path: /math/add, http_method: POST }, });worker.register_trigger({ type: http, function_id: math::add, config: {api_path: /math/add, http_method: POST}, })use iii_sdk::RegisterTriggerInput; use serde_json::json; worker.register_trigger(RegisterTriggerInput { trigger_type: http.into(), function_id: math::add.into(), config: json!({ api_path: /math/add, http_method: POST }), metadata: None, })?;这里体现了一个重要机制Trigger 类型来自已连接的 Worker。http Worker 提供http类型、cron Worker 提供cron类型、state Worker 提供state类型——因为真正产生这些事件、负责触发调用的就是发布类型的 Worker。文档同时说明可以在发布方 Worker 连接之前就注册到某个 Trigger 类型引擎会乐观地保存绑定等发布方加入后自动激活。同一个 Function 可以被任意多个 Trigger 指向一个业务 Function 可以同时被 HTTP 请求、cron 计划和队列消息调用函数代码不变只是注册了多个 Trigger。4. 端到端示例把 Function 变成 HTTP 端点把上面三块拼起来就是 HTTP 文档给出的完整路径启动引擎如未运行iii --config config.yaml脚手架一个 Worker 并编辑其源码注册 Function 并绑定httpTriggeriii worker init my-worker --language typescriptimport { registerWorker } from iii-sdk; const url process.env.III_URL; if (!url) throw new Error(III_URL must be set); const worker registerWorker(url, { workerName: my-worker }); worker.registerFunction(http::add, async (payload: { body: { a: number; b: number } }) ({ status_code: 200, body: { c: payload.body.a payload.body.b }, headers: { Content-Type: application/json }, })); worker.registerTrigger({ type: http, function_id: http::add, config: { api_path: /math/add, http_method: POST }, });将 Worker 加入并启动iii worker add ./my-worker在引擎的 HTTP 端口默认3111上调用暴露的路径curl -X POST http://localhost:3111/math/add -H content-type: application/json -d {a:2,b:3}整个链路中httpWorker 持有 HTTP socket请求到达POST /math/add时它查表后发起针对http::add的调用Engine 将其路由到提供该 Function 的 Worker响应再原路返回——被调用的 Function 始终只看到 payload从不感知 HTTP。源码级延伸Worker 生命周期与注册表清理文档的 Workers 子页 还描述了连接之后的生命周期值得纳入实操知识状态机connecting → connected → available / busy → disconnected。connecting是 WebSocket 握手connected表示已加入 Engine 注册表available/busy描述是否正在处理调用disconnected是连接关闭后的终态。Engine 跟踪这些转移并通过发现类 Functions 暴露给其他 Worker。检查实时注册表调用engine::workers::list、engine::functions::list、engine::triggers::list、engine::registered-triggers::list四个 Function 可分别查看全部连接 Worker含指标、已注册 Function、已发布 Trigger 类型含 config 与调用 schema和已注册 Trigger 实例。断连清理Worker 的 WebSocket 关闭后其 Functions 与 Triggers 自动离开注册表进行中的调用被取消并向调用方返回invocation_stopped错误调用方应捕获该错误并按取消处理可订阅engine::workers-available/engine::functions-available事件感知拓扑变化后再重试。优雅关停调用 SDK 的shutdownRust 为shutdown_async().await可确定性地关闭连接比进程直接退出更快达到清理状态这对 Kubernetes Job、serverless 容器等一次性/临时 Worker 尤其有用。从引擎源码结构看这些行为由 engine/src/workers/registry.rs注册表维护与 engine/src/workers/reload.rsWorker 重载管理等模块承担而 engine/src/workers/ws_handler.rs 位于worker即 worker-manager目录下从源码结构看可推断其服务于经 RBAC 监听器接入的 Worker 连接处理与文档中“不受信任连接应经 worker-manager 门控”的指引对应。总结以 Worker 为单位的扩展方法论回到 Creating Workers / Overview 的核心论断iii 把“Unix 给进程的单一接口、React 给组件的单一接口”延伸为给所有软件类别的单一接口——Worker。掌握这条主线后的实操清单是需要新能力时先查 Common Workers 与官方 Worker registry复用优先确需自建时用iii worker init脚手架或手写任何能调用registerWorker的代码通过III_URL建立 WebSocket 连接用registerFunction贡献service::name形式的 Function用registerTrigger把它绑定到 http/cron/queue/state 等事件源涉及不受信任连接时改走 iii-worker-manager 的 RBAC 监听器用engine::*::list系列 Function 与engine::*-available事件持续观测实时注册表。Engine 本身无需任何修改系统的能力面随每个新 Worker 的加入而增长——这正是“Effortlessly compose, extend, and observe every service in real time”这句话在 iii 中的落地方式。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考