Skip to content

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

@mkjsix

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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions