iii-functions-and-triggers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Functions & Triggers

函数与触发器

Comparable to: Serverless function runtimes, Lambda, Cloud Functions

可类比于：Serverless函数运行时、Lambda、Cloud Functions

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every worker needs all of them.

A Function is an async handler registered with a unique ID
A Trigger binds an event source to a function — types include http, queue, cron, state, stream, and subscribe
Functions invoke other functions via
```
trigger()
```
regardless of language or worker location
The engine handles serialization, routing, and delivery automatically
HTTP-invoked functions wrap external endpoints as callable function IDs
Functions can declare request/response formats for documentation and discovery — auto-generated from types in Rust (via
```
schemars::JsonSchema
```
) and Python (via type hints / Pydantic), or manually provided in Node.js

当任务需要时使用以下概念，并非每个工作器都需要全部概念。

Function 是一个注册了唯一ID的异步处理器
Trigger 将事件源绑定到函数——类型包括http、queue、cron、state、stream和subscribe
函数可通过
```
trigger()
```
调用其他函数，不受语言或工作器位置限制
引擎自动处理序列化、路由和交付
HTTP调用的函数会将外部端点包装为可调用的函数ID
函数可声明请求/响应格式用于文档和发现——在Rust中通过
```
schemars::JsonSchema
```
自动生成，在Python中通过类型提示/Pydantic自动生成，在Node.js中手动提供

Architecture

架构

registerWorker()

connects the worker to the engine,

registerFunction

defines handlers,

registerTrigger

binds event sources to those handlers, and the engine routes incoming events to the correct function. Functions can invoke other functions across workers and languages via

trigger()

registerWorker()

用于将工作器连接到引擎，

registerFunction

定义处理器，

registerTrigger

将事件源绑定到这些处理器，引擎负责将传入事件路由到正确的函数。函数可通过

trigger()

跨工作器和语言调用其他函数。

iii Primitives Used

使用的iii原语

Primitive	Purpose
`registerWorker(url, options?)`	Connect worker to engine
`registerFunction({ id }, handler)`	Define a function handler
`registerTrigger({ type, function_id, config })`	Bind an event source to a function
`trigger({ function_id, payload })`	Invoke a function synchronously
`trigger({ ..., action: TriggerAction.Void() })`	Fire-and-forget invocation
`trigger({ ..., action: TriggerAction.Enqueue({ queue }) })`	Durable async invocation via queue

原语	用途
`registerWorker(url, options?)`	将工作器连接到引擎
`registerFunction({ id }, handler)`	定义函数处理器
`registerTrigger({ type, function_id, config })`	将事件源绑定到函数
`trigger({ function_id, payload })`	同步调用函数
`trigger({ ..., action: TriggerAction.Void() })`	即发即弃式调用
`trigger({ ..., action: TriggerAction.Enqueue({ queue }) })`	通过队列实现持久化异步调用

Reference Implementation

参考实现

TypeScript: ../references/functions-and-triggers.js
Python: ../references/functions-and-triggers.py
Rust: ../references/functions-and-triggers.rs

Each reference shows the same patterns (function registration, trigger binding, cross-function invocation) in its respective language.

TypeScript: ../references/functions-and-triggers.js
Python: ../references/functions-and-triggers.py
Rust: ../references/functions-and-triggers.rs

每个参考示例都展示了相同的模式（函数注册、触发器绑定、跨函数调用），对应各自的语言。

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

registerWorker('ws://localhost:49134', { workerName: 'my-worker' })

— connect to the engine

registerFunction({ id: 'namespace::name' }, async (input) => { ... })

— register a handler

registerTrigger({ type: 'http', function_id, config: { api_path, http_method } })

— HTTP trigger

registerTrigger({ type: 'queue', function_id, config: { topic } })

— queue trigger

registerTrigger({ type: 'cron', function_id, config: { expression } })

— cron trigger

registerTrigger({ type: 'state', function_id, config: { scope, key } })

— state change trigger

registerTrigger({ type: 'stream', function_id, config: { stream } })

— stream trigger

registerTrigger({ type: 'subscribe', function_id, config: { topic } })

— pubsub subscriber

Cross-language invocation: a TypeScript function can trigger a Python or Rust function by ID

使用此模式的代码通常包含以下相关内容：

registerWorker('ws://localhost:49134', { workerName: 'my-worker' })

— 连接到引擎

registerFunction({ id: 'namespace::name' }, async (input) => { ... })

— 注册处理器

registerTrigger({ type: 'http', function_id, config: { api_path, http_method } })

— HTTP触发器

registerTrigger({ type: 'queue', function_id, config: { topic } })

— 队列触发器

registerTrigger({ type: 'cron', function_id, config: { expression } })

— cron触发器

registerTrigger({ type: 'state', function_id, config: { scope, key } })

— 状态变更触发器

registerTrigger({ type: 'stream', function_id, config: { stream } })

— 流触发器

registerTrigger({ type: 'subscribe', function_id, config: { topic } })

— 发布订阅订阅器

跨语言调用：TypeScript函数可通过ID触发Python或Rust函数

Request/Response Format (Auto-Registration)

请求/响应格式（自动注册）

Functions can declare their input/output schemas for documentation and discovery:

Rust: Derive
```
schemars::JsonSchema
```
on handler input/output types —
```
RegisterFunction::new()
```
auto-generates JSON Schema (Draft 7) from the type
Python: Use type hints (Pydantic models or primitives) on handler parameters and return types —
```
register_function()
```
auto-extracts JSON Schema (Draft 2020-12)
Node.js: Pass
```
request_format
```
/
```
response_format
```
manually in the registration message (e.g., via Zod's
```
toJSONSchema()
```
)

函数可声明其输入/输出模式用于文档和发现：

Rust: 在处理器输入/输出类型上派生
```
schemars::JsonSchema
```
—
```
RegisterFunction::new()
```
会从类型自动生成JSON Schema（Draft 7）
Python: 在处理器参数和返回类型上使用类型提示（Pydantic模型或基本类型） —
```
register_function()
```
会自动提取JSON Schema（Draft 2020-12）
Node.js: 在注册消息中手动传入
```
request_format
```
/
```
response_format
```
（例如，通过Zod的
```
toJSONSchema()
```
）

Adapting This Pattern

适配此模式

Use the adaptations below when they apply to the task.

Replace placeholder handler logic with real business logic (API calls, DB queries, LLM calls)
Use
```
namespace::name
```
convention for function IDs to group related functions
For HTTP endpoints, configure
```
api_path
```
and
```
http_method
```
in the trigger config
For durable async work, use
```
TriggerAction.Enqueue({ queue })
```
instead of synchronous trigger
For fire-and-forget side effects, use
```
TriggerAction.Void()
```
Multiple workers in different languages can register functions that invoke each other by ID

当任务适用时，可进行以下适配：

用真实业务逻辑（API调用、数据库查询、LLM调用）替换占位处理器逻辑
使用
```
namespace::name
```
约定作为函数ID，对相关函数进行分组
对于HTTP端点，在触发器配置中设置
```
api_path
```
和
```
http_method
```
对于持久化异步任务，使用
```
TriggerAction.Enqueue({ queue })
```
替代同步触发
对于即发即弃的副作用，使用
```
TriggerAction.Void()
```
不同语言的多个工作器可注册函数，并通过ID相互调用

Pattern Boundaries

模式边界

For HTTP endpoint specifics (request/response format, path params), prefer
```
iii-http-endpoints
```
.
For queue processing details (retries, concurrency, FIFO), prefer
```
iii-queue-processing
```
.
For cron scheduling details (expressions, timezones), prefer
```
iii-cron-scheduling
```
.
For invocation modes (sync vs void vs enqueue), prefer
```
iii-trigger-actions
```
.
Stay with
```
iii-functions-and-triggers
```
when the primary problem is registering functions, binding triggers, or cross-language invocation.

若涉及HTTP端点细节（请求/响应格式、路径参数），优先使用
```
iii-http-endpoints
```
。
若涉及队列处理细节（重试、并发、FIFO），优先使用
```
iii-queue-processing
```
。
若涉及cron调度细节（表达式、时区），优先使用
```
iii-cron-scheduling
```
。
若涉及调用模式（同步、即发即弃、入队），优先使用
```
iii-trigger-actions
```
。
当主要需求是注册函数、绑定触发器或跨语言调用时，使用
```
iii-functions-and-triggers
```
。

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-functions-and-triggers
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

当任务主要涉及iii引擎中的
```
iii-functions-and-triggers
```
时，使用此技能。
当请求直接要求此模式或等效实现时触发。

Boundaries

边界限制

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.

切勿将此技能作为无关任务的通用 fallback。
当更具体的iii技能更合适时，不得应用此技能。
在应用此技能的示例前，务必验证环境和安全约束。