Peek Messages

Overview

Peeking lets you look at what's sitting in a queue without touching it — the messages stay exactly where they are, still waiting for whichever consumer eventually receives them. It's the tool you reach for when you need visibility into queue state — checking backlog depth, inspecting payloads while debugging a stuck pipeline, or building an operational dashboard — without risking a collision with real consumers competing for the same work.

peekQueueMessages { } is a variant of the same request receiveQueuesMessages { } uses, just in read-only mode: the broker returns a snapshot of messages currently queued, marked by the isPeek flag on the response, but never locks or removes them — so no acknowledgment is needed or even possible.

Gotchas: peeked messages aren't reserved for you — a consumer can receiveQueuesMessages and remove them the instant after you peek, so treat the count as a point-in-time estimate, not a guarantee. Peek also won't surface messages already locked inside another consumer's in-flight receive, and it's not a substitute for receiving when you actually intend to process what you see.

Prerequisites

• KubeMQ server running on localhost:50000
• Kotlin SDK installed (implementation("io.kubemq.sdk:kubemq-sdk-kotlin:1.0.1"))

Code

package io.kubemq.sdk.examples.queues

import io.kubemq.sdk.client.KubeMQClient
import io.kubemq.sdk.queues.queueMessage
import kotlinx.coroutines.runBlocking

private const val ADDRESS = "localhost:50000"
private const val CLIENT_ID = "kotlin-queues-peek-messages"
private const val CHANNEL = "kotlin-queues.peek-messages"

fun main() = runBlocking {
    val client = KubeMQClient.queues {
        address = ADDRESS
        clientId = CLIENT_ID
    }

    client.use {
        // Send messages
        repeat(3) { i ->
            client.sendQueuesMessage(queueMessage {
                channel = CHANNEL
                body = "Peek msg #${i + 1}".toByteArray()
            })
        }
        println("Sent 3 messages.")

        // Peek -- non-destructive read (messages remain in queue)
        val peekResp = client.peekQueueMessages {
            channel = CHANNEL
            maxNumberOfMessages = 5
            waitTimeSeconds = 3
        }
        println("\nPeeked ${peekResp.messages.size} messages (isPeek=${peekResp.isPeek}):")
        peekResp.messages.forEach { println("  ${String(it.body)}") }

        // Verify messages are still in queue by receiving them
        val recvResp = client.receiveQueuesMessages {
            channel = CHANNEL
            maxItems = 10
            waitTimeoutMs = 3000
            autoAck = true
        }
        println("\nAfter peek, received ${recvResp.messages.size} messages (still in queue).")

        println("Done.")
    }
}

How It Works

• peekQueueMessages { } performs a non-destructive read -- messages remain in the queue.
• The isPeek flag on the response confirms it was a peek operation.
• After peeking, messages can still be received normally with receiveQueuesMessages.
• Useful for monitoring queue depth or inspecting messages without consuming them.

Related

• Send & Receive
• Poll Mode
• Queues Reference