Core Primitives
iii has three top-level primitives:
- Function: a named unit of work such as
orders::validate
- Trigger: an event source bound to a function
- Worker: a process that connects to the engine and executes functions
Use :: in function IDs, leading slashes in HTTP api_path, and expression for cron config.
Function Registration
Register local handlers when you control the implementation. Register HTTP-invoked functions when
iii should call an existing external endpoint.
| Shape |
Use for |
registerFunction(id, handler, options?) |
Local worker code |
registerFunction(id, HttpInvocationConfig, options?) |
Existing HTTP services |
registerTrigger({ type, function_id, config, metadata? }) |
Binding an event source |
trigger({ function_id, payload, action?, timeout? }) |
Calling any function by ID |
Functions and triggers can carry metadata for ownership, discovery, and generated skills. Do not put
secrets in metadata.
Workers and Registry
A worker is any process that connects to the engine and registers functions or trigger types. There
are two common paths:
| Task |
Use |
| Create your own worker |
Write SDK code that calls registerWorker, registerFunction, and registerTrigger |
| Add an existing capability |
Browse https://workers.iii.dev/, then call compose::add worker=<name> |
| Pin a worker version |
compose::add worker=<name>@<version> |
| Declare a local worker |
Add worker: path://./workers/my-worker under containers: |
| Reproduce a project |
Commit the exact versions in worker-compose.yaml |
The public worker registry at workers.iii.dev is for installable workers such as HTTP, state,
queue, pub/sub, cron, observability, sandbox, database, shell, console, and other capability
workers. Those workers may ship their own function-level skills; do not duplicate every capability
as a top-level iii skill.
Worker Manifest
Use iii.worker.yaml when iii should start a local worker project:
name: math-worker
runtime:
kind: python
package_manager: pip
entry: math_worker.py
scripts:
install: "pip install -r requirements.txt"
start: "python math_worker.py"
The manifest describes how to start the process. Once running, the WebSocket connection and function
registrations are what make the worker part of iii.
Live Engine Registry
The engine keeps a live registry of connected workers, registered functions, triggers, and trigger
types. Read it through the built-in discovery functions:
| Function |
Returns |
engine::workers::list |
Connected workers and metrics |
engine::functions::list |
Registered functions |
engine::triggers::list |
Registered triggers |
engine::trigger-types::list |
Advertised trigger types and schemas |
For topology changes, bind triggers to engine::workers-available or
engine::functions-available.
Built-In Trigger Shapes
| Trigger type |
Registration config |
Handler payload |
http |
{ api_path: "/orders/:id", http_method: "POST" } |
{ query_params, path_params, headers, path, method, body } |
cron |
{ expression: "0 0 9 * * * *" } |
{ trigger, job_id, scheduled_time, actual_time } |
durable:subscriber |
{ topic: "payments" } |
The queued message payload |
subscribe |
{ topic: "orders.created" } |
The published event payload |
state |
{ scope: "orders", key?: "order-123" } |
{ event_type, scope, key, old_value, new_value } |
stream |
{ stream_name, group_id, item_id? } |
Stream event details |
log |
{ level: "warn" } |
OpenTelemetry-style log data |
Add condition_function_id to built-in trigger config when the handler should only run if a boolean
condition function returns true.
Invocation Modes
| Mode |
Shape |
Use when |
| Sync |
trigger({ function_id, payload }) |
The caller needs the result |
| Void |
TriggerAction.Void() |
Optional side effect, no result needed |
| Enqueue |
TriggerAction.Enqueue({ queue }) |
Reliable async work with queue policy |
Use enqueue for work that must complete with retries. Use void for analytics, notifications, and
other non-critical side effects.
Code Examples
TypeScript
import { registerWorker, TriggerAction } from "iii-sdk";
const iii = registerWorker("ws://localhost:49134", { workerName: "orders-worker" });
iii.registerFunction("orders::validate", async (order) => {
if (!order.id) throw new Error("missing order id");
return { ...order, valid: true };
});
iii.registerFunction("orders::process", async (order) => {
const validated = await iii.trigger({ function_id: "orders::validate", payload: order });
await iii.trigger({
function_id: "orders::charge",
payload: validated,
action: TriggerAction.Enqueue({ queue: "payments" }),
});
return { accepted: true, orderId: validated.id };
});
iii.registerTrigger({
type: "http",
function_id: "orders::process",
config: { api_path: "/orders", http_method: "POST" },
});
Python
from iii import register_worker
iii = register_worker("ws://localhost:49134")
def validate(order):
if not order.get("id"):
raise ValueError("missing order id")
return {**order, "valid": True}
def process(order):
validated = iii.trigger({"function_id": "orders::validate", "payload": order})
iii.trigger({
"function_id": "orders::charge",
"payload": validated,
"action": {"type": "enqueue", "queue": "payments"},
})
return {"accepted": True, "orderId": validated["id"]}
iii.register_function("orders::validate", validate)
iii.register_function("orders::process", process)
iii.register_trigger({
"type": "http",
"function_id": "orders::process",
"config": {"api_path": "/orders", "http_method": "POST"},
})
Rust
use iii_sdk::{register_worker, InitOptions, RegisterFunction, TriggerAction};
use iii_sdk::protocol::{RegisterTriggerInput, TriggerRequest};
use serde_json::json;
let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());
iii.register_function(RegisterFunction::new("orders::validate", |order: serde_json::Value| {
if order["id"].is_null() {
return Err("missing order id".into());
}
Ok(json!({ "valid": true, "order": order }))
}))?;
let process_client = iii.clone();
iii.register_function(RegisterFunction::new_async("orders::process", move |order: serde_json::Value| {
let iii = process_client.clone();
async move {
let validated = iii.trigger(TriggerRequest::new("orders::validate", order)).await?;
iii.trigger(TriggerRequest {
function_id: "orders::charge".into(),
payload: validated.clone(),
action: Some(TriggerAction::Enqueue { queue: "payments".into() }),
timeout_ms: None,
}).await?;
Ok(json!({ "accepted": true, "order": validated }))
}
}))?;
iii.register_trigger(RegisterTriggerInput {
trigger_type: "http".into(),
function_id: "orders::process".into(),
config: json!({ "api_path": "/orders", "http_method": "POST" }),
metadata: None,
})?;
Advanced Primitive Patterns
- Custom triggers: use
registerTriggerType({ id, description }, handler) when the event source is
not built in. Keep listener setup in registerTrigger and cleanup in unregisterTrigger.
- Channels: use
createChannel() for binary or streaming data that should not be serialized into
JSON payloads. Pass readerRef or writerRef through a function payload.
- HTTP-invoked functions: use
HttpInvocationConfig for legacy APIs, third-party endpoints, or
immutable services. Use environment variable names for auth fields, not raw secrets.
- Schemas: Rust can derive request/response schemas with
schemars::JsonSchema; Python can use
type hints or Pydantic; Node can pass JSON Schema manually.
When to Use
- Use this skill for function registration, trigger binding, trigger payload shapes, invocation mode
decisions, worker creation, worker registry access, trigger conditions, custom trigger types,
channels, and HTTP-invoked functions.
- Use this when a task spans TypeScript, Python, or Rust examples for the same iii primitive.
Boundaries
- For engine ports, adapters, queue retry policy, worker manager, RBAC listeners, and deployment
config, use
iii-engine-config.
- For SDK-specific package exports and language caveats, use
iii-sdk-reference.
- For complete backend designs such as workflows, CQRS, agentic systems, and reactive apps, use
iii-architecture-patterns.
- For failed invocations, timeouts, RBAC denials, and retryability, use
iii-error-handling.
- Worker-backed capability details live with the worker docs, not as top-level iii skills.
1---
2name: iii-core-primitives
3description: >-
4 Use when registering iii functions, binding triggers, selecting sync/void/enqueue invocation,
5 creating workers, inspecting the live worker registry, installing registry workers, authoring
6 custom triggers, moving channel data, or adapting external HTTP functions across TypeScript,
7 Python, and Rust.
8metadata:
9 source: https://skillmd.com/skills/iii-hq/iii-core-primitives
10---
11
12# Core Primitives
13
14iii has three top-level primitives:
15
16- **Function**: a named unit of work such as `orders::validate`
17- **Trigger**: an event source bound to a function
18- **Worker**: a process that connects to the engine and executes functions
19
20Use `::` in function IDs, leading slashes in HTTP `api_path`, and `expression` for cron config.
21
22## Function Registration
23
24Register local handlers when you control the implementation. Register HTTP-invoked functions when
25iii should call an existing external endpoint.
26
27| Shape | Use for |
28| --- | --- |
29| `registerFunction(id, handler, options?)` | Local worker code |
30| `registerFunction(id, HttpInvocationConfig, options?)` | Existing HTTP services |
31| `registerTrigger({ type, function_id, config, metadata? })` | Binding an event source |
32| `trigger({ function_id, payload, action?, timeout? })` | Calling any function by ID |
33
34Functions and triggers can carry metadata for ownership, discovery, and generated skills. Do not put
35secrets in metadata.
36
37## Workers and Registry
38
39A worker is any process that connects to the engine and registers functions or trigger types. There
40are two common paths:
41
42| Task | Use |
43| --- | --- |
44| Create your own worker | Write SDK code that calls `registerWorker`, `registerFunction`, and `registerTrigger` |
45| Add an existing capability | Browse `https://workers.iii.dev/`, then call `compose::add worker=<name>` |
46| Pin a worker version | `compose::add worker=<name>@<version>` |
47| Declare a local worker | Add `worker: path://./workers/my-worker` under `containers:` |
48| Reproduce a project | Commit the exact versions in `worker-compose.yaml` |
49
50The public worker registry at `workers.iii.dev` is for installable workers such as HTTP, state,
51queue, pub/sub, cron, observability, sandbox, database, shell, console, and other capability
52workers. Those workers may ship their own function-level skills; do not duplicate every capability
53as a top-level iii skill.
54
55### Worker Manifest
56
57Use `iii.worker.yaml` when iii should start a local worker project:
58
59```yaml
60name: math-worker
61runtime:
62 kind: python
63 package_manager: pip
64 entry: math_worker.py
65scripts:
66 install: "pip install -r requirements.txt"
67 start: "python math_worker.py"
68```
69
70The manifest describes how to start the process. Once running, the WebSocket connection and function
71registrations are what make the worker part of iii.
72
73### Live Engine Registry
74
75The engine keeps a live registry of connected workers, registered functions, triggers, and trigger
76types. Read it through the built-in discovery functions:
77
78| Function | Returns |
79| --- | --- |
80| `engine::workers::list` | Connected workers and metrics |
81| `engine::functions::list` | Registered functions |
82| `engine::triggers::list` | Registered triggers |
83| `engine::trigger-types::list` | Advertised trigger types and schemas |
84
85For topology changes, bind triggers to `engine::workers-available` or
86`engine::functions-available`.
87
88## Built-In Trigger Shapes
89
90| Trigger type | Registration config | Handler payload |
91| --- | --- | --- |
92| `http` | `{ api_path: "/orders/:id", http_method: "POST" }` | `{ query_params, path_params, headers, path, method, body }` |
93| `cron` | `{ expression: "0 0 9 * * * *" }` | `{ trigger, job_id, scheduled_time, actual_time }` |
94| `durable:subscriber` | `{ topic: "payments" }` | The queued message payload |
95| `subscribe` | `{ topic: "orders.created" }` | The published event payload |
96| `state` | `{ scope: "orders", key?: "order-123" }` | `{ event_type, scope, key, old_value, new_value }` |
97| `stream` | `{ stream_name, group_id, item_id? }` | Stream event details |
98| `log` | `{ level: "warn" }` | OpenTelemetry-style log data |
99
100Add `condition_function_id` to built-in trigger config when the handler should only run if a boolean
101condition function returns `true`.
102
103## Invocation Modes
104
105| Mode | Shape | Use when |
106| --- | --- | --- |
107| Sync | `trigger({ function_id, payload })` | The caller needs the result |
108| Void | `TriggerAction.Void()` | Optional side effect, no result needed |
109| Enqueue | `TriggerAction.Enqueue({ queue })` | Reliable async work with queue policy |
110
111Use enqueue for work that must complete with retries. Use void for analytics, notifications, and
112other non-critical side effects.
113
114## Code Examples
115
116### TypeScript
117
118```typescript
119import { registerWorker, TriggerAction } from "iii-sdk";
120
121const iii = registerWorker("ws://localhost:49134", { workerName: "orders-worker" });
122
123iii.registerFunction("orders::validate", async (order) => {
124 if (!order.id) throw new Error("missing order id");
125 return { ...order, valid: true };
126});
127
128iii.registerFunction("orders::process", async (order) => {
129 const validated = await iii.trigger({ function_id: "orders::validate", payload: order });
130 await iii.trigger({
131 function_id: "orders::charge",
132 payload: validated,
133 action: TriggerAction.Enqueue({ queue: "payments" }),
134 });
135 return { accepted: true, orderId: validated.id };
136});
137
138iii.registerTrigger({
139 type: "http",
140 function_id: "orders::process",
141 config: { api_path: "/orders", http_method: "POST" },
142});
143```
144
145### Python
146
147```python
148from iii import register_worker
149
150iii = register_worker("ws://localhost:49134")
151
152def validate(order):
153 if not order.get("id"):
154 raise ValueError("missing order id")
155 return {**order, "valid": True}
156
157def process(order):
158 validated = iii.trigger({"function_id": "orders::validate", "payload": order})
159 iii.trigger({
160 "function_id": "orders::charge",
161 "payload": validated,
162 "action": {"type": "enqueue", "queue": "payments"},
163 })
164 return {"accepted": True, "orderId": validated["id"]}
165
166iii.register_function("orders::validate", validate)
167iii.register_function("orders::process", process)
168iii.register_trigger({
169 "type": "http",
170 "function_id": "orders::process",
171 "config": {"api_path": "/orders", "http_method": "POST"},
172})
173```
174
175### Rust
176
177```rust
178use iii_sdk::{register_worker, InitOptions, RegisterFunction, TriggerAction};
179use iii_sdk::protocol::{RegisterTriggerInput, TriggerRequest};
180use serde_json::json;
181
182let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());
183
184iii.register_function(RegisterFunction::new("orders::validate", |order: serde_json::Value| {
185 if order["id"].is_null() {
186 return Err("missing order id".into());
187 }
188 Ok(json!({ "valid": true, "order": order }))
189}))?;
190
191let process_client = iii.clone();
192iii.register_function(RegisterFunction::new_async("orders::process", move |order: serde_json::Value| {
193 let iii = process_client.clone();
194 async move {
195 let validated = iii.trigger(TriggerRequest::new("orders::validate", order)).await?;
196 iii.trigger(TriggerRequest {
197 function_id: "orders::charge".into(),
198 payload: validated.clone(),
199 action: Some(TriggerAction::Enqueue { queue: "payments".into() }),
200 timeout_ms: None,
201 }).await?;
202 Ok(json!({ "accepted": true, "order": validated }))
203 }
204}))?;
205
206iii.register_trigger(RegisterTriggerInput {
207 trigger_type: "http".into(),
208 function_id: "orders::process".into(),
209 config: json!({ "api_path": "/orders", "http_method": "POST" }),
210 metadata: None,
211})?;
212```
213
214## Advanced Primitive Patterns
215
216- **Custom triggers**: use `registerTriggerType({ id, description }, handler)` when the event source is
217 not built in. Keep listener setup in `registerTrigger` and cleanup in `unregisterTrigger`.
218- **Channels**: use `createChannel()` for binary or streaming data that should not be serialized into
219 JSON payloads. Pass `readerRef` or `writerRef` through a function payload.
220- **HTTP-invoked functions**: use `HttpInvocationConfig` for legacy APIs, third-party endpoints, or
221 immutable services. Use environment variable names for auth fields, not raw secrets.
222- **Schemas**: Rust can derive request/response schemas with `schemars::JsonSchema`; Python can use
223 type hints or Pydantic; Node can pass JSON Schema manually.
224
225## When to Use
226
227- Use this skill for function registration, trigger binding, trigger payload shapes, invocation mode
228 decisions, worker creation, worker registry access, trigger conditions, custom trigger types,
229 channels, and HTTP-invoked functions.
230- Use this when a task spans TypeScript, Python, or Rust examples for the same iii primitive.
231
232## Boundaries
233
234- For engine ports, adapters, queue retry policy, worker manager, RBAC listeners, and deployment
235 config, use `iii-engine-config`.
236- For SDK-specific package exports and language caveats, use `iii-sdk-reference`.
237- For complete backend designs such as workflows, CQRS, agentic systems, and reactive apps, use
238 `iii-architecture-patterns`.
239- For failed invocations, timeouts, RBAC denials, and retryability, use `iii-error-handling`.
240- Worker-backed capability details live with the worker docs, not as top-level iii skills.