Trigger Types
Trigger Types define different ways to invoke functions in the iii Engine.
What are Trigger Types?
A Trigger Type is a mechanism that can initiate function execution. The iii Engine supports multiple trigger types, each serving different use cases:
- API: HTTP requests
- Event: Published events on topics
- Cron: Scheduled time-based execution
- Log: System log events
- Streams: Stream connection lifecycle (join/leave)
Core Trigger Types
API Trigger (api)
Executes functions in response to HTTP requests.
Provided by: REST API Module
Configuration:
{
trigger_type: 'api',
config: {
api_path: '/users/:id',
http_method: 'GET'
}
}Input: ApiRequest with path params, query params, body, headers
Output: ApiResponse with status, body, headers
REST API Module
Learn more about the API trigger
Event Trigger (event)
Executes functions when events are published to subscribed topics.
Provided by: Event Module
Configuration:
{
trigger_type: 'event',
config: {
subscribes: ['user.created', 'user.updated']
}
}Input: Event payload (any JSON data)
Output: Function result (optional, fire-and-forget pattern supported)
Event Module
Learn more about the Event trigger
Cron Trigger (cron)
Executes functions on a time-based schedule using cron expressions.
Provided by: Cron Module
Configuration:
{
trigger_type: 'cron',
config: {
cron: '0 2 * * *' // Every day at 2 AM
}
}Input: Cron execution context (timestamp, trigger info)
Output: Function result
Cron Module
Learn more about the Cron trigger
Log Trigger (log)
Executes functions when log entries match specified criteria.
Provided by: Logging Module
Configuration:
{
trigger_type: 'log',
config: {
level: 'error' // info, warn, error, debug
}
}Input: Log entry with trace_id, message, level, function_name, date
Output: Function result (useful for alerting, metrics)
Logging Module
Learn more about the Log trigger
Stream Triggers (streams:join, streams:leave)
Executes functions when clients connect to or disconnect from streams.
Provided by: Stream Module
Configuration:
// Join trigger
{
trigger_type: 'streams:join',
config: {} // No config needed
}
// Leave trigger
{
trigger_type: 'streams:leave',
config: {} // No config needed
}Input: Subscription info with stream_name, group_id, item_id, context
Output: Function result (useful for access control, analytics)
Stream Module
Learn more about Stream triggers
Trigger Type Comparison
| Trigger Type | Use Case | Synchronous | Multiple Subscribers |
|---|---|---|---|
| api | HTTP endpoints | ✓ Yes | ✗ No (1:1 mapping) |
| event | Pub/sub messaging | ✗ No | ✓ Yes |
| cron | Scheduled tasks | ✗ No | ✗ No (distributed lock) |
| log | Log monitoring | ✗ No | ✓ Yes |
| streams:join | Stream connections | ✗ No | ✓ Yes |
| streams:leave | Stream disconnections | ✗ No | ✓ Yes |
Registering Trigger Types
Trigger types are registered by Core Modules during engine initialization:
Workers can then register triggers using these types:
bridge.registerTrigger({
trigger_type: 'api', // Must be a registered trigger type
function_path: 'users.create',
config: {
/* trigger-specific config */
},
})Custom Trigger Types
Modules can register custom trigger types by implementing the trigger interface:
pub struct CustomModule {
// Module state
}
impl CoreModule for CustomModule {
fn name(&self) -> &str {
"custom"
}
async fn register_trigger_type(&self, registry: &TriggerRegistry) {
registry.register("custom:trigger", CustomTriggerHandler);
}
}Usage Patterns
HTTP API Endpoints
// Register function
bridge.registerFunction({
function_path: 'api.getUser',
handler: async (req) => ({
status: 200,
body: { user: { id: req.path_params.id } },
}),
})
// Register API trigger
bridge.registerTrigger({
trigger_type: 'api',
function_path: 'api.getUser',
config: {
api_path: '/users/:id',
http_method: 'GET',
},
})Event-Driven Workflows
// Emit events
await bridge.invokeFunction({
function_path: 'event.emit',
data: {
topic: 'order.placed',
data: { orderId: '123', amount: 99.99 },
},
})
// Subscribe to events
bridge.registerFunction({
function_path: 'notifications.sendOrderEmail',
handler: async (data) => {
await sendEmail(data)
},
})
bridge.registerTrigger({
trigger_type: 'event',
function_path: 'notifications.sendOrderEmail',
config: {
subscribes: ['order.placed'],
},
})Scheduled Jobs
bridge.registerFunction({
function_path: 'jobs.dailyReport',
handler: async () => {
const report = await generateReport()
await sendReport(report)
},
})
bridge.registerTrigger({
trigger_type: 'cron',
function_path: 'jobs.dailyReport',
config: {
cron: '0 9 * * *', // Every day at 9 AM
},
})