iii-custom-triggers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Custom Triggers

自定义触发器

Comparable to: Custom event adapters, webhook receivers

类似功能：自定义事件适配器、webhook接收器

Key Concepts

核心概念

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

registerTriggerType(id, handler) defines a new trigger type with
```
registerTrigger
```
and
```
unregisterTrigger
```
callbacks
The handler receives a TriggerConfig containing
```
id
```
,
```
function_id
```
, and
```
config
```
When the external event fires, call
```
iii.trigger(function_id, event)
```
to invoke the registered function
unregisterTriggerType cleans up when the trigger type is no longer needed
Do not reuse built-in trigger type names:
```
http
```
,
```
cron
```
,
```
queue
```
,
```
state
```
,
```
stream
```
,
```
subscribe
```

当任务需要时使用以下概念，并非所有自定义触发器都需要包含全部概念。

registerTriggerType(id, handler) 用于定义新的触发器类型，包含
```
registerTrigger
```
和
```
unregisterTrigger
```
回调函数
处理器会接收包含
```
id
```
、
```
function_id
```
和
```
config
```
的TriggerConfig配置
当外部事件触发时，调用
```
iii.trigger(function_id, event)
```
来执行已注册的函数
unregisterTriggerType 用于在触发器类型不再需要时清理资源
请勿复用内置触发器类型名称：
```
http
```
、
```
cron
```
、
```
queue
```
、
```
state
```
、
```
stream
```
、
```
subscribe
```

Architecture

架构

External event source (webhook, file watcher, IoT, CDC, etc.) → Custom trigger handler (registerTriggerType) → iii.trigger(function_id, event) → Registered function processes the event

iii Primitives Used

使用的iii原语

Primitive	Purpose
`registerTriggerType(id, handler)`	Define a new trigger type with lifecycle hooks
`unregisterTriggerType(id)`	Clean up a custom trigger type
`TriggerConfig: { id, function_id, config }`	Configuration passed to the trigger handler
`iii.trigger(function_id, event)`	Fire the registered function when the event occurs

原语	用途
`registerTriggerType(id, handler)`	定义带有生命周期钩子的新触发器类型
`unregisterTriggerType(id)`	清理自定义触发器类型
`TriggerConfig: { id, function_id, config }`	传递给触发器处理器的配置
`iii.trigger(function_id, event)`	事件发生时触发已注册的函数

Reference Implementation

参考实现

See ../references/custom-triggers.js for the full working example — a custom trigger type that listens for external events and routes them to registered functions.

Also available in Python: ../references/custom-triggers.py

Also available in Rust: ../references/custom-triggers.rs

完整可运行示例请查看 ../references/custom-triggers.js —— 这是一个监听外部事件并将其路由到已注册函数的自定义触发器类型。

同时提供Python版本：../references/custom-triggers.py

以及Rust版本：../references/custom-triggers.rs

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization

registerTriggerType(id, { registerTrigger, unregisterTrigger })

— define the custom trigger

```
registerTrigger(config)
```
— called by iii when a function subscribes to this trigger type
```
unregisterTrigger(config)
```
— called by iii when a function unsubscribes

iii.trigger(config.function_id, eventPayload)

— fire the target function

Cleanup logic in
```
unregisterTrigger
```
(close connections, remove listeners, clear intervals)
```
const logger = new Logger()
```
— structured logging

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

```
registerWorker(url, { workerName })
```
—— 工作器初始化

registerTriggerType(id, { registerTrigger, unregisterTrigger })

—— 定义自定义触发器

```
registerTrigger(config)
```
—— 当函数订阅此触发器类型时，由iii调用
```
unregisterTrigger(config)
```
—— 当函数取消订阅此触发器类型时，由iii调用

iii.trigger(config.function_id, eventPayload)

—— 触发目标函数

```
unregisterTrigger
```
中的清理逻辑（关闭连接、移除监听器、清除定时器）
```
const logger = new Logger()
```
—— 结构化日志

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Choose a unique trigger type name that describes your event source (e.g.
```
file-watcher
```
,
```
mqtt
```
,
```
db-cdc
```
)
In
```
registerTrigger
```
, start the listener (open socket, poll endpoint, subscribe to topic)
In
```
unregisterTrigger
```
, tear down the listener to avoid resource leaks
Store active listeners in a map keyed by
```
config.id
```
for clean unregistration
Pass relevant event data in the payload when calling
```
iii.trigger(function_id, event)
```

当任务适用时，可采用以下适配方式：

选择一个能描述事件源的唯一触发器类型名称（例如
```
file-watcher
```
、
```
mqtt
```
、
```
db-cdc
```
）
在
```
registerTrigger
```
中启动监听器（打开套接字、轮询端点、订阅主题）
在
```
unregisterTrigger
```
中销毁监听器，避免资源泄漏
将活跃监听器存储在以
```
config.id
```
为键的映射中，以便干净地取消注册
调用
```
iii.trigger(function_id, event)
```
时，在负载中传递相关事件数据

Pattern Boundaries

模式边界

If the task uses built-in HTTP routes, prefer
```
iii-http-endpoints
```
.
If the task uses built-in cron schedules, prefer
```
iii-cron-scheduling
```
.
If the task uses built-in queue triggers, prefer
```
iii-queue-processing
```
.
Stay with
```
iii-custom-triggers
```
when iii has no built-in trigger type for the event source.

如果任务使用内置HTTP路由，优先使用
```
iii-http-endpoints
```
。
如果任务使用内置 cron 调度，优先使用
```
iii-cron-scheduling
```
。
如果任务使用内置队列触发器，优先使用
```
iii-queue-processing
```
。
当iii没有针对该事件源的内置触发器类型时，才使用
```
iii-custom-triggers
```
。

When to Use

使用场景

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

当任务主要涉及iii引擎中的
```
iii-custom-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技能更适合时，不得应用此技能。
在应用此技能中的示例之前，务必验证环境和安全约束。