Publish/subscribe normally delivers a matching MQTT message to every subscriber. Work queues need a different contract: one available worker receives a job, the application reports the outcome, failed work is retried, and repeatedly failing work is moved aside for inspection.
Sagüin's queue channel adds that contract to a configured region of the MQTT topic space. Publishers may be MQTT 5 or MQTT 3.1.1 clients; workers need MQTT 5.
Why a shared subscription is not the whole queue
An MQTT shared subscription distributes live messages across group members. It is useful for load balancing, but application work often needs more than distribution:
- a job must survive when no worker is connected;
- accepting the MQTT delivery and completing the business operation are separate events;
- a worker can disconnect or time out after receiving work;
- attempts need to be counted;
- exhausted work needs a dead-letter destination;
- an operator needs to see why a job stopped retrying.
A durable queue records those states explicitly. In Sagüin, a delivery to a worker is an attempt, and the worker's hold on the job lasts the channel's visibility_timeout; it is not an execution. If the hold ends without an answer, the job can be offered again while the first worker may still be running. A worker may see the same job more than once, so workers have to be idempotent.
Configure a queue-shaped topic range
A queue channel claims the topics matched by its filter:
channels:
device-work:
type: queue
filter: fleet/+/work/+
visibility_timeout: 30s
retry:
max_attempts: 5
mode: exponential
delay: 5s
dlq_retention_period: 30d
A publisher can send a job to a normal topic such as fleet/truck-17/work/reindex. At QoS 1, Sagüin stores the job before it sends the PUBACK.
The full set of queue keys covers retention, the hold, retries and the dead-letter channel's retention; the configuration reference has each with its default. Validate the actual configuration with saguin --check-config before deployment.
The lifecycle of one job
The queue's useful unit is the application outcome:
- A publisher writes a job to a queue-owned topic.
- The broker stores it and makes it available. Jobs are offered oldest first; once retries begin, order is not guaranteed.
- One worker, chosen round-robin among those connected, with room and allowed by the
acl_file, receives an attempt. Its hold starts at its PUBACK. - The worker performs the external operation.
- The worker answers
ackorreturnon$saguin/queue/<channel>/response, with the attempt's Correlation Data. - An acknowledged job is finished; its record stays for the queue's readers until retention removes it. A returned job, or one whose hold ran out, is offered again after the wait
retry.modesets. - A job whose last attempt fails moves to the dead-letter channel as
attempts_exhausted.
Retention never deletes an unfinished job: it moves it to the dead-letter channel, <channel>__dlq, in one transaction, as expired past the queue's retention_period or evicted past its retention_bytes. The moved job's topic gains the prefix __dlq/, and it carries saguin-dlq-reason and the rest of the saguin-dlq- properties. The dead-letter channel is an append channel that readers start at the floor, and only the broker writes to it.
Design workers for at-least-once execution
No broker can prove that an external side effect completed merely because a connection disappeared. A worker might update a database and then lose its link before reporting success. The hold may later run out and the job may be offered again.
Use an idempotency key carried in the payload or MQTT properties, then make the downstream operation safe to repeat. Every offer carries the job record's saguin-id and, in saguin-attempt, which attempt it is, counting from 1. Common patterns include:
- a database uniqueness constraint on the job identifier;
- an upsert instead of an unconditional insert;
- recording completed commands before acknowledging them;
- making the target operation converge on a desired state.
Exactly-once language tends to hide this boundary. Sagüin states it directly: queue processing is at least once.
Bounds, and what happens at them
A bounded queue is safer than an apparently infinite one. Held jobs do not count toward retention_bytes, so a queue never refuses a publish for being full: past its bounds, its oldest unfinished jobs move to the dead-letter channel instead. A full disk is the one storage refusal a publisher sees, with reason code 0x97; the broker refuses rather than acknowledging data it cannot keep. When the broker's own work falls behind delivery, it holds publishers back until it catches up.
Watch the unfinished jobs by state in saguin_queue_jobs, failed attempts by cause (return, timeout, worker_gone) in saguin_queue_attempts_failed_total, and dead letters by reason in saguin_queue_dead_lettered_total. The operations route queues/<channel> lists a queue's unfinished jobs with their attempts and state, never a payload. A rising queue is usually a capacity or downstream-health signal, not something to solve by making every bound unbounded.
When to use another channel
Use append when every durable consumer should see every record. Use latest when only the current value of each topic matters. Use ordinary broadcast or MQTT shared subscriptions when live delivery is enough and application acknowledgements, retries and dead letters would add machinery without value.
Read Delivery, Queue jobs for the exact attempt, hold and retry rules, Channels for dead-lettering, and Restart for what a restart keeps: attempt counts and retry times are restored, holds are not, so a job a worker held is offered again. The Sagüin examples provide runnable clients against a real broker.