Skip to main content

Documentation Index

Fetch the complete documentation index at: https://iii.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
What a Trigger is

A Trigger is a binding that tells iii when to invoke a Function. The Trigger declares a type (the kind of event that causes it to fire), a configuration (the per-type details, like an HTTP path or a cron expression), and the function ID it invokes. When the corresponding event happens, the Trigger fires and the Engine routes the invocation to a Worker that provides the Function. HTTP requests, cron schedules, queue messages, state changes, log events, and stream events all become Function invocations through Triggers.

​
Trigger types

worker.trigger() and the iii trigger CLI command can invoke any registered Function via its function_id (see Functions / Direct invocation). The trigger types described below are how Functions get bound to other event sources (HTTP requests, cron schedules, queue messages, etc.). Workers can define their own trigger types.
Trigger types come from connected Workers. A Worker that can source events declares one or more trigger types alongside their configuration schemas. The iii-http Worker provides the http trigger type. The iii-cron Worker provides the cron trigger type. The iii-state Worker provides the state trigger type. A Trigger of a given type can only be registered while a Worker advertising that type is connected, because that Worker is what produces the events that fire it.

​
Trigger components

A Trigger has three parts: a type (the kind of event, like http or cron), a config (the per-type details, like an HTTP path or a cron expression), and a function_id (the Function to invoke). Together they tell iii what event to listen for, how to listen, and what to call when the event happens.

​
Conditional triggers

A Trigger can also specify an optional condition_function_id, which can be any gating function that returns truthy/falsey result. If specified the Engine invokes the condition function first and the function_id’s handler will only execute if the condition function returns a truthy value. Since Triggers are concerned with “when to do” and Functions are concerned with “what to do” these conditional functions preserve that separation: the Function stays focused on its work instead of accumulating per-Trigger guards that the developer has to link specific invocation paths. Using condition functions correctly helps maintain Worker and Function composability.

​
Trigger pipeline

When a Trigger fires, the Engine looks up its function_id in the live registry, finds a Worker that currently provides the Function, and dispatches the invocation. The function handler sees the payload alone, never the source of the Trigger or the type of event that fired it.

​
Trigger Actions

Functions invocation can be controlled via Trigger Actions. The default, synchronous mode blocks until the Function returns its result or the configured timeout fires. The fire-and-forget mode (TriggerAction.Void) returns immediately, scheduling the Function to run without waiting for a result. Synchronous invocations are appropriate when the caller needs the value the Function returns. Fire-and-forget is for side-effect work where the caller does not need to wait.
Workers can also define their own TriggerActions. The iii-queue Worker provides TriggerAction.Enqueue({queue}), which routes the invocation through a named queue with retries. See iii-queue for the queue mechanics.

​
Trigger lifecycle

Triggers move through four states. registered means the Trigger has been declared with the Engine. active means the Trigger is currently listening for its event. invoked means an event has fired the Trigger. unregistered means the Trigger has been removed. When the Worker that owns a Trigger disconnects, all of its Triggers are unregistered automatically along with its Functions.

​
Trigger conditions

A Trigger can carry an optional condition_function_id that runs before the handler. When the Trigger fires, the Engine invokes the condition function with the same payload the handler would receive. If the condition returns a truthy value, the handler runs; if not, the invocation is skipped. Use this when the same event source should sometimes fire the Function and sometimes not, without splitting the Trigger into separate event-source registrations.