docs/architecture/workers.mdx
A Worker is any process that connects to the iii Engine over WebSocket using an SDK and registers Functions. The Engine routes incoming triggers to the correct Worker, which executes the handler and optionally returns a result.
Workers are independent processes — they can be written in any language, run anywhere, and crash without affecting other Workers.
graph LR
E[Engine]
subgraph W1[Worker A]
F1([Function A])
F2([Function B])
end
subgraph W2[Worker B]
F3([Function C])
end
W1 -- registerFunction --> E
W2 -- registerFunction --> E
E -- trigger --> W1
E -- trigger --> W2
flowchart TD
Start(("registerWorker()")) --> Connecting
Connecting -->|WebSocket open| Connected
Connected -->|"Register
functions & triggers"| Registering
Registering -->|All registered| Ready
Ready -->|Invocation received| Executing
Executing -.-> RS[Result sent]
Ready -->|shutdown| ShuttingDown
ShuttingDown --> End((Exit))
Ready -->|Connection lost| Disconnected
Disconnected -->|Auto-reconnect| Reconnecting
Reconnecting -->|Reconnected| Connected
Reconnecting -->|Max retries| Failed
A Worker is simply any collection of registered Functions and Triggers that has registered itself with the iii engine. See How to use Functions and Triggers for details on registering functions within workers. Read below for Worker responsibilities and configuration.
| Responsibility | Description |
|---|---|
| Function hosting | Register Functions with the Engine and execute them when triggered |
| SDK connection | Connect to the Engine via WebSocket, auto-reconnect on disconnect |
| Language runtime | Run in their own process in any iii-sdk supported language |
| Isolation | Workers are independent processes. A crash in one Worker doesn't propagate to others |
The second argument to registerWorker() configures the Worker's behavior:
| Option | Type | Default | Description |
|---|---|---|---|
workerName | string | ${hostname}:${pid} | Name shown in the iii Console and listWorkers() |
invocationTimeoutMs | number | 30000 | Default timeout for trigger() calls in milliseconds |
enableMetricsReporting | boolean | true | Report CPU, memory, and event loop metrics to the Engine |
reconnectionConfig | object | see below | WebSocket reconnection behavior |
otel | object | auto | OpenTelemetry configuration. Set { enabled: false } to disable |
Workers reconnect automatically on disconnect using exponential backoff:
| Field | Default | Description |
|---|---|---|
initialDelayMs | 1000 | First retry delay |
maxDelayMs | 30000 | Maximum retry delay cap |
backoffMultiplier | 2 | Multiplier applied to delay each attempt |
jitterFactor | 0.3 | Random jitter 0–1 to prevent thundering herd |
maxRetries | -1 | Maximum attempts. -1 = infinite |
Python naming: Python uses snake_case for these fields:
initial_delay_ms,max_delay_ms,backoff_multiplier,jitter_factor,max_retries.
import { registerWorker } from 'iii-sdk'
const iii = registerWorker('ws://localhost:49134', {
workerName: 'user-service',
invocationTimeoutMs: 10000,
reconnectionConfig: {
initialDelayMs: 500,
maxDelayMs: 10000,
maxRetries: 10,
},
})
When a Worker connects, the SDK sends its metadata to the Engine via engine::workers::register:
runtime: 'node' | 'python' | 'rust'
version: SDK version
name: workerName
os: platform + arch
The Engine assigns a worker_id and the Worker's status transitions through:
connecting → connected → available / busy → disconnected
On disconnect — clean or crash — the Engine automatically removes all the Worker's registered Functions and Triggers. On reconnect, the SDK re-registers everything automatically.
You can inspect all connected Workers at runtime:
const workers = await iii.listWorkers()
// returns WorkerInfo[] with: id, name, runtime, version, os,
// status, connected_at_ms, function_count, functions[], active_invocations
workers = iii.list_workers()