Sub-issue of #601.
Summary
Expose a REST API to inspect, replay, and discard batches that failed MongoDB persistence and were written to the dead-letter log by MqttMongoWriter.
Motivation
The v1 MqttMongoWriter (#601) logs failed write batches to a file after exhausting retries. During a prolonged MongoDB outage this file can grow large and requires SSH access to inspect. A REST API lets ops teams manage dead-letter entries from any HTTP client or monitoring tool.
Proposed API
GET /mqtt/dead-letter — list failed batches (paginated, newest first)
GET /mqtt/dead-letter/{id} — inspect one batch (topic, message count, first/last receivedAt, failure reason)
POST /mqtt/dead-letter/{id}/replay — retry inserting the batch into MongoDB now
DELETE /mqtt/dead-letter/{id} — discard permanently
DELETE /mqtt/dead-letter — discard all (with confirmation header required)
Dead-letter entries are persisted to a local append-only file in v1. This API reads and manages that file. An optional persist-to-mongo: true flag on mqtt-mongo-writer stores dead-letter entries in a restheart.mqtt-dead-letter collection instead, making them queryable via the standard MongoDB REST API.
Scope
- New
MqttDeadLetterService implementing JsonService.
- Secured by default (
secure=true); requires admin role.
- Replay triggers the same
insertMany + retry path as the normal drain loop.
- Unit tests for file parsing, pagination, and replay logic; integration test for replay against a live MongoDB instance.
Dependencies
Sub-issue of #601.
Summary
Expose a REST API to inspect, replay, and discard batches that failed MongoDB persistence and were written to the dead-letter log by
MqttMongoWriter.Motivation
The v1
MqttMongoWriter(#601) logs failed write batches to a file after exhausting retries. During a prolonged MongoDB outage this file can grow large and requires SSH access to inspect. A REST API lets ops teams manage dead-letter entries from any HTTP client or monitoring tool.Proposed API
Dead-letter entries are persisted to a local append-only file in v1. This API reads and manages that file. An optional
persist-to-mongo: trueflag onmqtt-mongo-writerstores dead-letter entries in arestheart.mqtt-dead-lettercollection instead, making them queryable via the standard MongoDB REST API.Scope
MqttDeadLetterServiceimplementingJsonService.secure=true); requiresadminrole.insertMany+ retry path as the normal drain loop.Dependencies