> ## Documentation Index
> Fetch the complete documentation index at: https://motiadev-add-real-system-tutorial-round-2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Queue
> Queue worker for async job processing with named queues, retries, and dead-letter support.
A worker for asynchronous job processing. It supports two modes: **topic-based queues** (register a consumer per topic, emit events) and **named queues** (enqueue function calls via `TriggerAction.Enqueue`, no trigger registration).
```
iii-queue
```
For step-by-step instructions, see [Use Topic-Based Queues](../how-to/use-topic-queues) and [Use Named Queues](../how-to/use-named-queues). For DLQ management, see [Manage Failed Triggers](../how-to/dead-letter-queues).
## Queue Modes
### Topic-based queues
Register consumers for a topic and emit events to it. Messages are delivered using **fan-out per function**: every distinct function subscribed to a topic receives a copy of each message. When multiple replicas of the same function are running, they compete on a shared per-function queue — only one replica processes each message.
1. **Register a consumer** with `registerTrigger({ type: 'durable:subscriber', function_id: 'my::handler', config: { topic: 'order.created' } })`. This subscribes the handler to that topic.
2. **Emit events** by calling `trigger({ function_id: 'iii::durable::publish', payload: { topic: 'order.created', data: payload } })` or `trigger({ function_id: 'iii::durable::publish', payload: { topic, data }, action: TriggerAction.Void() })` for fire-and-forget. The `iii::durable::publish` function fans out the payload to every subscribed function.
3. **Action on the trigger**: the handler receives the `data` as its input. Optional `queue_config` on the trigger controls per-subscriber retries and concurrency.
The producer knows the topic name; consumers register to receive it. Queue settings can live at the trigger registration site.
If functions `A` and `B` both subscribe to topic `order.created`, each message published to that topic is delivered to **both** `A` and `B`. If function `A` has 3 replicas running, only one replica of `A` processes each message — they compete on a shared queue. This gives you pub/sub-style fan-out with the durability and retry guarantees of a queue.
### Named queues
Define queues in `iii-config.yaml`, then enqueue function calls directly. No trigger registration needed.
1. **Define queues** in `queue_configs` (see [Configuration](#configuration)).
2. **Enqueue a function call** with `trigger({ function_id: 'orders::process', payload, action: TriggerAction.Enqueue({ queue: 'payment' }) })`. The engine routes the job to the named queue and invokes the function when a worker consumes it.
3. **Action on the trigger**: the target function receives `payload` as its input. Retries, concurrency, and FIFO are configured centrally in `iii-config.yaml`.
The producer targets the function and queue explicitly. Queue configuration is centralized. For a hands-on walkthrough, see [Use Named Queues](../how-to/use-named-queues).
### When to use which
| | Topic-based | Named queues |
| ------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Producer** | Calls `trigger({ function_id: 'iii::durable::publish', payload: { topic, data } })` | Calls `trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) })` |
| **Consumer** | Registers `registerTrigger({ type: 'durable:subscriber', config: { topic } })` | No registration — function is the target |
| **Delivery** | Fan-out: each subscribed function gets every message; replicas compete | Single target function per enqueue call |
| **Config** | Optional `queue_config` on trigger | `queue_configs` in `iii-config.yaml` |
| **Use case** | Durable pub/sub with retries and fan-out | Direct function invocation with retries, FIFO, DLQ |
Both modes are valid. Named queues offer config-driven retries, concurrency, and FIFO ordering.
Named queues use the `Enqueue` trigger action. For a full comparison of synchronous, Void, and Enqueue invocation modes, see [Trigger Actions](../how-to/trigger-actions).
## Sample Configuration
```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
- name: iii-queue
config:
queue_configs:
default:
max_retries: 5
concurrency: 5
type: standard
payment:
max_retries: 10
concurrency: 2
type: fifo
message_group_field: transaction_id
adapter:
name: builtin
config:
store_method: file_based
file_path: ./data/queue_store
```
## Configuration
A map of named queue configurations. Each key is the queue name referenced in `TriggerAction.Enqueue({ queue: 'name' })`. Define a queue named `default` in config for the common case; reference it as `TriggerAction.Enqueue({ queue: 'default' })`.
The transport adapter for queue persistence and distribution. Defaults to `builtin` when not specified.
## Queue Configuration
Each entry in `queue_configs` defines an independent named queue with its own retry, concurrency, and ordering settings.
Maximum delivery attempts before routing the job to the dead-letter queue. Defaults to `3`.
Maximum number of jobs processed simultaneously from this queue. Defaults to `10`. For FIFO queues, the engine overrides this to `prefetch=1` to guarantee ordering — see the note below.
Delivery mode: `standard` (concurrent, default) or `fifo` (ordered within a message group).
Required when `type` is `fifo`. The JSON field in the job payload whose value determines the ordering group. Jobs with the same group value are processed strictly in order. The field must be present and non-null in every enqueued payload.
Base retry backoff in milliseconds. Applied with exponential scaling: `backoff_ms × 2^(attempt − 1)`. Defaults to `1000`.
Worker poll interval in milliseconds. Defaults to `100`.
When `type` is `fifo`, the engine sets `prefetch=1` regardless of the `concurrency` value. This ensures only one job is in-flight at a time, which is required for strict ordering. FIFO queues also retry failed jobs inline (blocking the queue) rather than in parallel.
## Standard vs FIFO Queues
| Dimension | Standard | FIFO |
| ------------------------- | ---------------------------------------------- | -------------------------------------------------------- |
| **Processing model** | Up to `concurrency` jobs in parallel | One job at a time (prefetch=1) |
| **Ordering** | No guarantees — jobs may complete in any order | Strictly ordered within a message group |
| **`message_group_field`** | Not required | Required — must be present and non-null in every payload |
| **Throughput** | High — scales with `concurrency` | Lower — trades throughput for ordering |
| **Use cases** | Email sends, image processing, notifications | Payments, ledger entries, state machines |
| **Retries** | Retried independently, other jobs continue | Retried inline — blocks the queue until success or DLQ |
### Standard queue flow
Jobs are dequeued and processed concurrently. Each job is independent.
```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
sequenceDiagram
participant P as Producer
participant E as Engine
participant Q as Queue
participant F1 as Worker 1
participant F2 as Worker 2
participant F3 as Worker 3
P->>E: Enqueue Job A
P->>E: Enqueue Job B
P->>E: Enqueue Job C
E->>Q: Store A, B, C
par Concurrent processing
Q->>F1: Job A
Q->>F2: Job B
Q->>F3: Job C
end
F2-->>Q: ACK (B finishes first)
F1-->>Q: ACK (A finishes second)
F3-->>Q: ACK (C finishes third)
```
### FIFO queue flow
Jobs within the same message group are processed one at a time, strictly in order.
```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
sequenceDiagram
participant P as Producer
participant E as Engine
participant Q as FIFO Queue
participant F as Worker
P->>E: Enqueue Job 1 (group: acct_A)
P->>E: Enqueue Job 2 (group: acct_A)
P->>E: Enqueue Job 3 (group: acct_A)
E->>Q: Store 1, 2, 3
Q->>F: Job 1
F-->>Q: ACK
Note over Q,F: Job 2 starts only after Job 1 completes
Q->>F: Job 2
F-->>Q: ACK
Q->>F: Job 3
F-->>Q: ACK
```
## Adapters
### builtin
Built-in in-process queue. No external dependencies. Suitable for single-instance deployments — messages are not shared across engine instances.
```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
name: builtin
config:
store_method: file_based # in_memory | file_based
file_path: ./data/queue_store # required when store_method is file_based
```
Persistence strategy: `in_memory` (lost on restart) or `file_based` (durable across restarts). Defaults to `in_memory`.
Path to the queue store directory. Required when `store_method` is `file_based`.
### redis
Uses Redis as the queue backend for topic-based pub/sub. Enables message distribution across multiple engine instances.
The Redis adapter supports publishing to named queues but does not implement named queue consumption, retries, or dead-letter queues. It is suitable for topic-based pub/sub only. For full named queue support in multi-instance deployments, use the [RabbitMQ adapter](#rabbitmq).
```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
name: redis
config:
redis_url: ${REDIS_URL:redis://localhost:6379}
```
The URL of the Redis instance to connect to.
### rabbitmq
Uses RabbitMQ as the queue backend. Supports durable delivery, retries, and dead-letter queues across multiple engine instances.
The engine owns consumer loops, retry acknowledgement, and backoff logic — RabbitMQ is used as a transport only. Retry uses explicit ack + republish to a retry exchange with an `x-attempt` header, keeping compatibility with both classic and quorum queues.
```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
name: rabbitmq
config:
amqp_url: ${RABBITMQ_URL:amqp://localhost:5672}
```
The AMQP URL of the RabbitMQ instance to connect to.
#### Queue naming in RabbitMQ
For each named queue defined in `queue_configs`, iii creates the following RabbitMQ resources:
| Resource | Format | Example (`payment`) |
| -------------- | ------------------------------------- | -------------------------------------- |
| Main exchange | `iii.__fn_queue::` | `iii.__fn_queue::payment` |
| Main queue | `iii.__fn_queue::.queue` | `iii.__fn_queue::payment.queue` |
| Retry exchange | `iii.__fn_queue::::retry` | `iii.__fn_queue::payment::retry` |
| Retry queue | `iii.__fn_queue::::retry.queue` | `iii.__fn_queue::payment::retry.queue` |
| DLQ exchange | `iii.__fn_queue::::dlq` | `iii.__fn_queue::payment::dlq` |
| DLQ queue | `iii.__fn_queue::::dlq.queue` | `iii.__fn_queue::payment::dlq.queue` |
Each named queue creates six RabbitMQ objects to support delayed retry and dead-lettering. For the design rationale, see [Queue Architecture](../architecture/queues).
#### Topic-based queue naming in RabbitMQ
For topic-based queues, iii uses a **fanout exchange** per topic. Each subscribed function gets its own queue and DLQ bound to the exchange:
| Resource | Format | Example (topic `order.created`, function `notify::email`) |
| ------------------ | --------------------------------- | --------------------------------------------------------- |
| Fanout exchange | `iii..exchange` | `iii.order.created.exchange` |
| Per-function queue | `iii...queue` | `iii.order.created.notify::email.queue` |
| Per-function DLQ | `iii...dlq` | `iii.order.created.notify::email.dlq` |
RabbitMQ's fanout exchange natively delivers a copy of each published message to every bound queue, providing fan-out delivery.
## Adapter Comparison
| | builtin | rabbitmq | redis |
| --------------------------- | ------- | -------- | ----------------- |
| **Retries** | Yes | Yes | No |
| **Dead-letter queue** | Yes | Yes | No |
| **FIFO ordering** | Yes | Yes | No |
| **Named queue consumption** | Yes | Yes | No (publish only) |
| **Topic-based pub/sub** | Yes | Yes | Yes |
| **Multi-instance** | No | Yes | Yes |
| **External dependency** | None | RabbitMQ | Redis |
### Choosing an adapter
| Scenario | Recommended Adapter | Why |
| -------------------------- | ------------------------ | -------------------------------------------- |
| Local development | `builtin` (`in_memory`) | Zero dependencies, fast iteration |
| Single-instance production | `builtin` (`file_based`) | Durable across restarts, no external infra |
| Multi-instance production | `rabbitmq` | Distributes messages across engine instances |
Regardless of which adapter you choose, retry semantics, concurrency enforcement, and FIFO ordering behave identically — the engine owns these behaviors, not the adapter.
For step-by-step queue setup, see [Use Named Queues](../how-to/use-named-queues) and [Use Topic-Based Queues](../how-to/use-topic-queues).
## Builtin Functions
The queue worker registers the following functions automatically when it initializes. These are callable via `trigger()` from any SDK or via the `iii trigger` CLI command.
### iii::durable::publish
Publishes a message to a topic-based queue. The message is fanned out to every distinct function subscribed to that topic. Replicas of the same function compete on a shared per-function queue.
| Field | Type | Description |
| ------- | -------- | ------------------------------------------------- |
| `topic` | `string` | The topic to publish to (required, non-empty) |
| `data` | `any` | The payload delivered to each subscribed function |
Returns `null` on success.
### iii::queue::redrive
Moves all messages from a named queue's dead-letter queue back to the main queue. Each message gets its attempt counter reset to zero.
**Input:**
| Field | Type | Description |
| ------- | -------- | ------------------------------------------------------------------ |
| `queue` | `string` | The named queue whose DLQ should be redriven (required, non-empty) |
**Output:**
| Field | Type | Description |
| ---------- | -------- | --------------------------------------------------- |
| `queue` | `string` | The queue name that was redriven |
| `redriven` | `number` | The number of messages moved back to the main queue |
**CLI example:**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii trigger \
--function-id='iii::queue::redrive' \
--payload='{"queue": "payment"}'
```
For a complete guide on inspecting DLQ messages before redriving, see [Manage Failed Triggers](../how-to/dead-letter-queues).
## Queue Flow
### Retry and dead-letter flow
When a job fails, the engine retries it with exponential backoff. After all retries exhaust, the job moves to the DLQ.
```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
sequenceDiagram
participant Q as Queue
participant E as Engine
participant F as Target Function
participant DLQ as Dead Letter Queue
Q->>E: Job available (attempt 1)
E->>F: Invoke with payload
F-->>E: Error
Note over E: Wait backoff_ms × 2^0 = 1s
Q->>E: Job available (attempt 2)
E->>F: Invoke with payload
F-->>E: Error
Note over E: Wait backoff_ms × 2^1 = 2s
Q->>E: Job available (attempt 3 / max_retries)
E->>F: Invoke with payload
F-->>E: Error
E->>DLQ: Route to dead-letter queue
Note over DLQ: Job preserved for inspection or redrive
```
### Topic-based queue flow (fan-out)
When a message is published to a topic, the engine fans it out to every distinct function subscribed to that topic. Replicas of the same function compete on their shared per-function queue.
```mermaid theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
sequenceDiagram
participant P as Producer
participant E as Engine
participant Q1 as order.created::notify::email
participant Q2 as order.created::audit::log
participant E1 as notify::email (replica 1)
participant E2 as notify::email (replica 2)
participant A1 as audit::log
Note over Q1,Q2: Both functions subscribed to topic "order.created"
P->>E: iii::durable::publish({ topic: "order.created", data })
par Engine copies message to each function's queue
E->>Q1: push(data)
E->>Q2: push(data)
end
Note over Q1,E2: Replicas compete — only one processes the message
Q1->>E1: deliver
E1-->>Q1: Ack
Q2->>A1: deliver
A1-->>Q2: Ack
P->>E: iii::durable::publish({ topic: "order.created", data })
par
E->>Q1: push(data)
E->>Q2: push(data)
end
Note over Q1,E2: This time replica 2 wins
Q1->>E2: deliver
E2-->>Q1: Ack
Q2->>A1: deliver
A1-->>Q2: Ack
```