Delayed Messages

Overview

A delivery delay holds a queue message out of consumers' reach for a fixed window after it's sent — the message is accepted and persisted immediately, but invisible to pollers until the delay expires. It's the building block for scheduled work — a reminder to fire in an hour, a retry with back-off, a task queued for off-peak processing — without standing up a separate scheduler or cron service.

Set it with .delay_seconds(...) on QueueMessageBuilder before sending; the broker does the waiting. The send result's delayed_to field returns the Unix timestamp when the message becomes visible, so you can log or monitor exactly when delivery will happen. Until then, any poll against that channel simply returns nothing for that message — it isn't hidden in a separate place, it's the same queue, just not yet eligible for delivery.

Gotchas: the delay is set once at send time and can't be extended or shortened afterward — if you need a different wait, send a new message. A long delay still counts as an in-flight, persisted message, so it survives a broker restart, but it also occupies queue storage for the whole waiting period. Don't confuse this with a visibility timeout after delivery — that's a separate mechanism for redelivery on failed acknowledgment, not initial availability.

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 channel = "rust-queues.delayed-messages";

    let msg = QueueMessageBuilder::new()
        .channel(channel)
        .body(b"delayed-task".to_vec())
        .delay_seconds(10)
        .build();

    let result = client.send_queue_message(msg).await?;
    println!(
        "Sent delayed message: id={}, delayed_to={}",
        result.message_id, result.delayed_to
    );

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

How It Works

• delay_seconds(10) makes the message invisible for 10 seconds after sending.
• The delayed_to field in the result shows the Unix timestamp when the message becomes visible.
• 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
• Delay Policy