Offline-first message buffer with sequence-number-ordered replay for ManagedClient
- Dominant language
- C#
- Stars
- 5.1k
- Forks
- 1.2k
- PR merge metrics
- No merged PRs in 30d
Description
## Problem Statement
When an MQTT client reconnects after a connectivity
outage, the .NET MQTTnet library provides no built-in
mechanism to:
1. **Buffer messages locally** during the outage without
blocking the application
2. **Persist buffered messages to disk** so they survive
process restarts
3. **Replay messages in guaranteed chronological order**
when connectivity is restored
The MQTTnet wiki explicitly acknowledges this gap:
> "It is recommended to use the regular client and
> doing the reconnect stuff etc. via your own code."
However, most developers implementing their own reconnect
logic make a critical mistake: they replay in FIFO queue
order or timestamp order. During connectivity outages,
device clocks drift from NTP synchronization — meaning
timestamps become unreliable for ordering. Messages
replayed in timestamp order arrive at downstream
consumers out of sequence after clock correction.
## Real-World Impact
In enterprise IoT deployments across geographically
distributed locations — financial services, healthcare,
industrial safety — this silent data loss has direct
compliance and operational consequences.
We observed message loss rates of 0.3%–4.7% across
branch locations before solving this problem.
## The Key Insight — Sequence Numbers Not Timestamps
The correct solution assigns a monotonically increasing
sequence number at write time — immune to clock drift —
and uses that for ordering rather than device timestamps.
## Reference Implementation
I have built an open source .NET library addressing
this gap:
GitHub: https://github.com/rambudithe/EdgeSyncBuffer
NuGet: https://www.nuget.org/packages/EdgeSync.Buffer
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.