Dead Letter Policy

Overview

A dead-letter policy protects a queue from poison messages — a record that fails processing over and over because of a malformed payload, a consumer bug, or a downstream dependency that is down. Without one, that message is redelivered forever: it blocks head-of-line delivery, burns your consumers' retry budget, and can stall an entire queue behind a single bad record.

With a policy attached, KubeMQ counts each failed delivery and, once the message crosses max_receive_count, automatically moves it to the dead-letter channel you name with max_receive_queue on the QueueMessageBuilder. The main queue keeps flowing while the failure is quarantined for inspection or replay.

Gotchas: the receive count increments on every failed delivery — an explicit nack, an expired transaction, or a visibility timeout — not just deliberate rejections, so set the ceiling above your normal retry budget. The dead-letter channel is an ordinary queue with no special behavior: nothing drains it for you, so monitor it and build a reprocessing path or failures pile up silently. The policy is set at send time and travels with the message, so the producer, not the consumer, decides the retry ceiling.

Prerequisites

• KubeMQ server running on localhost:50000
• Rust SDK installed (cargo add kubemq)

Code

use kubemq::prelude::*;
use kubemq::QueueMessageBuilder;

#[tokio::main]
async fn main() -> kubemq::Result<()> {
    let client = KubemqClient::builder()
        .host("localhost")
        .port(50000)
        .build()
        .await?;

    let msg = QueueMessageBuilder::new()
        .channel("rust-queues.dead-letter-policy")
        .body(b"policy-message".to_vec())
        .max_receive_count(2)
        .max_receive_queue("rust-queues.dead-letter-policy.dlq")
        .build();

    let result = client.send_queue_message(msg).await?;
    println!("Sent with DLQ policy: id={}", result.message_id);

    client.close().await?;
    Ok(())
}

How It Works

• max_receive_count and max_receive_queue are set via the message builder.
• The server tracks delivery attempts and routes to the dead-letter queue when exceeded.
• Review timeouts, channel names, and client IDs before running against shared environments.
• Run the program while the server from the prerequisites is available.

Related

• Queues overview
• Rust SDK Reference
• Dead Letter Queue