Skip to content

feat(mqtt): dead-letter queue REST API #607

Description

@mkjsix

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions