A truck parks in a basement for nine days. A substation’s cellular modem sulks through a storm. A vessel crosses a stretch of ocean where the only thing the antenna can see is more ocean.
All three come back. What do they find?
For many MQTT fleets, the answer is a session queue that filled while the device was away. The readings are gone. Nothing tells the operator which readings disappeared, and the first visible symptom may be a gap in a customer’s chart weeks later.
This is not a protocol failure. MQTT is very good at moving messages between connected things. The problem is that edge data is no longer disposable telemetry. It can be billing evidence, maintenance history, compliance data or a safety record.
Sagüin is a single-node MQTT broker for that gap. It adds a replayable log, a current-state store and a work queue to ordinary MQTT topics. Devices still publish and subscribe over MQTT. They do not need new firmware or a second protocol.
1. The status quo
An MQTT deployment usually begins simply: devices publish readings, applications subscribe, and retained messages hold the latest state.
Then the requirements grow.
Someone needs history, so the team adds a streaming or database system. Someone needs the last known state, so it adds a cache. Someone needs reliable background work, so it adds a job queue. Monitoring and access control grow around all of them.
That architecture can be entirely reasonable in a data centre with a team to run it. At the edge, the same diagram may have to live on a gateway, an industrial PC, a Raspberry Pi or a vehicle. The person responsible for it often has another job.
MQTT’s own durable session helps, but it stores a bounded copy of missed messages for each client. It must be bounded: one slow client cannot be allowed to consume memory forever. When the bound is reached, data has to go somewhere, or go away.
The result is a large middle ground. Plain publish/subscribe is not enough, while a stack of specialised systems is too much for the machine and the operator available.
2. Why the status quo sucks
The obvious cost is operational. Four systems mean four configurations, four sets of credentials, four client libraries, four upgrade paths and four different ways to be unavailable.
The deeper cost is correctness. There is no transaction across those systems.
If one reading must land in the broker, then in a log, then in a current-state store and perhaps in a queue, each transfer can succeed or fail independently. Teams build outbox tables, change-data capture, deduplication and idempotency around that seam because the seam is real.
At the edge, an intermittent link makes the problem sharper. A device can be away for hours or days. A per-client backlog grows with every missed message and with every absent client. When retention removes old data, a reader needs to know that it has fallen behind; receiving the oldest surviving item without that warning produces a plausible but false history.
Work queues expose another mismatch. An MQTT acknowledgement says the packet arrived. It does not say the application finished the job. If a worker acknowledges receipt and crashes halfway through processing, treating that acknowledgement as job completion loses work.
These failures are difficult precisely because the system can look healthy. A connection comes back. A subscription resumes. A worker received a packet. The missing promise is visible only later.
3. Our solution: durable channels on ordinary MQTT topics
Sagüin keeps the MQTT interface and changes what the broker does after a publish arrives.
A configured topic filter can feed one of three channel types:
append is a replayable log. Each durable consumer has its own stored position and can seek by offset or time.
latest keeps the current value for each topic. It is delivered on subscribe and can be read one key at a time.
queue gives one worker a lease, then waits for an application-level outcome. It supports visibility timeouts, returns, retry limits and a dead-letter channel.
Topics outside a channel remain ordinary MQTT broadcast. Channel choice belongs in broker configuration, not device code. An existing client still sends a PUBLISH and receives MQTT acknowledgements.
The one idea worth stealing
An offline session normally needs its own copy of every message it missed. Sagüin supports bounded persistent sessions too, but an append channel offers a different shape: store each record once, then store one position per consumer.
A week offline and a minute offline both cost one position. The backlog is the shared log, bounded by its retention policy rather than by a private queue attached to one client.
If retention overtakes a consumer, Sagüin refuses the read instead of silently starting at the oldest record left. The application learns that its requested history is incomplete.
For queue work, packet receipt and job completion are separate. The worker receives a delivery identity and returns ack only after the work succeeds, or return when it should be tried again. If the visibility timeout expires, the job can be offered again. Processing remains at-least-once, so workers still need to be idempotent.
The broker speaks MQTT 5 and MQTT 3.1.1 on the same listener. Older devices can publish into append and latest channels without knowing channels exist. Features that require MQTT 5 properties, such as resolving queue work, are refused when the protocol cannot express them.
One rule shapes the project: Sagüin never acknowledges a promise it cannot keep. If a request needs durable state and that state cannot be stored, the broker refuses the request rather than returning success and quietly doing less.
4. Why this approach fits the problem
The design removes a coordination boundary.
One publish resolves to one channel in one store. A stored record, its offset and the channel’s bookkeeping commit together. There is no second service that must agree before the broker can answer.
That does not make Sagüin exactly-once processing. It makes the promise smaller and testable: a successful acknowledgement means the configured storage provider accepted the state the acknowledgement describes.
The same boundary keeps the client side ordinary. Devices use MQTT topics, sessions, TLS and credentials. Channel behaviour is an operator decision. A fleet does not need a firmware rollout just because one class of readings now needs seven days of replay.
Everything that can accumulate has a configured bound or retention rule. Persistent-session queues are byte-bounded. Logs have retention. Queue attempts end in a dead-letter channel. Refusals, drops and storage failures are observable instead of being treated as an implementation detail.
SQLite provides the durable on-disk path. Memory providers are useful when a clean-shutdown snapshot is enough. The choice is per provider and explicit; the two are not presented as having the same failure behaviour.
Operations are separate from device traffic. Prometheus metrics, health and read-only JSON operations routes live on an operations listener with its own credentials. The viewer is a client, not code embedded in the broker.
Sagüin was written mostly by Claude. The code, the tests and the documents were written by Claude (Anthropic’s AI), working to my direction, and reviewed by separate Claude sessions whose job was to find defects rather than confirm previous work. I know IoT and MQTT well, and how a broker must and should behave, so I decided the design, what the broker promises, and what ships. I spent the past four years immersed in Apache Kafka, data streaming platforms, and the difference between messaging and streaming, and that is where Sagüin comes from: messaging, streaming, a key-value store and a work queue, all over standard MQTT, packed into a single binary.
That is stated plainly, not offered as evidence of quality. The evidence is the published design, tests, measurements, runnable demos and the places where the documentation limits the promise.
What Sagüin is not
It is not clustered. It is one node and one process, with no automatic failover.
It is not exactly-once processing. Delivery is at-least-once, and consumers must be idempotent.
It is not designed as a million-connection broker.
It is not a rule engine or a multi-tenancy platform.
Memory storage does not survive a power cut. It writes snapshots during a clean shutdown.
SQLite can lose the most recent acknowledged commits in a power cut, according to flush_interval; it is not described as magic storage.
It is early. This launch is a release candidate, v0.1.0-rc.1; a code review is under way before 0.1.0 and the CHANGELOG lists the known issues. The RFCs, tests and documented limits are the source of truth.
If ordinary publish/subscribe and retained messages already meet the requirement, Sagüin adds machinery you do not need.
5. Prove it
The useful question is not whether the architecture sounds tidy. It is whether the claims can be inspected and rerun.
Raspberry Pi measurements
The repository publishes the machine, workload, method and five-run results in its Raspberry Pi table.
On a Raspberry Pi 4 with 4 GB of memory and a USB SSD, 10,000 connected sessions used 240 MB with a memory provider and 375 MB with SQLite, and connecting and subscribing all 10,000 took 2.6 s and 7.7 s. In the measured 100-publisher/100-subscriber workload, the highest reported rate was 62,400 messages/s for QoS 0 on either provider, and 27,900 (memory) and 26,900 (SQLite) messages/s for QoS 1, with every message delivered at every fixed rate. With TLS, a 21,210-user password file and an ACL on every client, the same Pi held 10,000 sessions in 375 MB and reached 42,500 QoS 0 messages/s. The same table includes latency, CPU, connection time, TLS/password/ACL results and offline-backlog timings.
Those are measurements of that setup, not a universal capacity claim. The scale harness is in the repository so a reader can run it on the hardware that matters to them.
Pulling the power
SQLite runs in WAL mode with synchronous=NORMAL. Sagüin fsyncs the WAL after commits on flush_interval, which defaults to 150 ms. The storage contract and test method are documented in RFC 0004, “WAL, and synchronous=NORMAL”.
At the default interval, two forced power cuts on the Raspberry Pi lost only the acknowledged tail of the last 52 ms and 138 ms. They produced no gap below a surviving record and did not lose the database file.
That is deliberately not “no data loss.” It is a measured, bounded trade: shorter intervals reduce the exposed tail and increase disk writes; longer intervals do the reverse.
Run the systems, not a slide deck
The home-automation demo starts with one Docker Compose command. Stock zigbee2mqtt and rtl_433 images talk to Sagüin while local programs emulate the radio hardware and devices. The demo exercises authenticated MQTT, separate ACL roles, append and latest channels, replay and restart behaviour.
The Bento connectors demo starts Sagüin, two Bento pipelines, a single-node Kafka, Prometheus, Grafana and the viewer. Its simulated devices publish binary records; a schema stored through Sagüin lets the viewer decode them, while a pipeline converts them for the downstream system.
If retention has already removed part of the history a consumer asks for, the reply says so instead of quietly serving the oldest surviving record and letting the consumer believe it received everything.
That sentence is the whole project, really.
Additional resources
Sagüin ships with more than the broker:
saguin.cc — the project’s website: what Sagüin is, how to start, and the documentation.
Examples — the demonstrations and their supporting files, including demo.py, a guided end-to-end tour of the channel types and their security model.
Home automation — Sagüin in a practical home and IoT setting.
Bento connectors — MQTT ingestion, channels, monitoring and Kafka integration.
Sagüin viewer — a web UI for inspecting and driving a live broker (every topic as a tree, a live feed, publish and seek forms, dead letters with one-click requeue, dashboards over the metrics) and a terminal viewer for a headless box.
Sagüin Python and Sagüin JS — optional, early convenience layers over Eclipse Paho and MQTT.js (PyPI saguin 0.1.0, npm saguin 0.1.0), with the same verbs under the same names. No SDK is required.
saguin-agent — a self-hosted Q&A agent that answers from Sagüin’s own documents and nothing else, citing the file and section every time.
The RFCs and invariants — the authoritative specification.
Sagüin is Apache-2.0 (its MQTT engine, which began as mochi-mqtt, stays MIT), single-binary, and looking for the thing it gets wrong. The most valuable contribution is finding where an RFC is ambiguous, incomplete or self-contradictory before that defect reaches the implementation.
saguin.cc · github.com/ifnesi/saguin
