Technical Reference Guide

Peek-Lock and Message Settlement Workflows

In enterprise messaging architectures, message processing integrity is paramount. Azure Service Bus implements two distinct consumption modes: **Receive-and-Delete** (destructive, single-settled read) and **Peek-Lock** (non-destructive, double-settled read). This guide explores the technical details of the Peek-Lock state machine, lock renewal dynamics, and manual message disposal behaviors implemented in the Bussin browser-native console.

Peek-Lock vs. Receive-and-Delete

The standard connection configuration dictates how the broker and the client settle transfer frames under the AMQP 1.0 specification:

Receive-and-Delete (At-Most-Once): The broker immediately settles the message transfer upon dispatch. The message is deleted from the broker before the client begins execution, risking data loss if the consumer crashes mid-transaction.
Peek-Lock (At-Least-Once): The broker locks the message for exclusive consumption by the client link for a specified duration (default is 30 seconds). The message remains on the broker but is hidden from other consumers, allowing safe, transactional settlement once processing is successfully verified.

Understanding AMQP Message Settlement States

When you lock and retrieve a message using Bussin's interactive console, you can manually trigger explicit disposal actions. Each maps directly to standard AMQP frame settlement states:

1. Complete (`Accepted`)

Acknowledges successful message processing. The browser client sends an `Accepted` disposition frame to the broker, which permanently deletes the message from the queue or subscription partition.

2. Abandon (`Released`)

Indicates a processing failure where the message should be re-attempted. The client sends a `Released` disposition frame. The broker immediately unlocks the message, making it visible to other active consumers. The message's `DeliveryCount` is incremented. If it exceeds the entity's `MaxDeliveryCount` limit, the broker automatically dead-letters the message.

3. Dead-Letter (`Rejected`)

Signals a permanent, unrecoverable failure (e.g., custom payload schema violations). The client sends a `Rejected` disposition frame containing custom error detail headers (`DeadLetterReason` and `DeadLetterErrorDescription`). The broker relocates the message to the entity's dead-letter sub-queue (`$DefaultDeadLetterQueue`) for isolated audit.

4. Defer (`Modified` with `undeliverable-here`)

Suspends immediate message delivery without processing or rejecting it. The broker preserves the message in the queue but holds it aside. It cannot be consumed by standard lock loops and must be retrieved explicitly by its `SequenceNumber` via a direct management-plane call.

// Conceptual AMQP Message Settlement State Transition
[Active Queue] ──(Receive & Lock)──> [Locked State (In Flight)]
                                           │
         ┌───────────────┬─────────────────┼────────────────┐
         ▼               ▼                 ▼                ▼
     Accepted        Released           Rejected         Modified
    (Complete)      (Abandon)        (Dead-Letter)       (Defer)
         │               │                 │                │
         ▼               ▼                 ▼                ▼
     [Deleted]     [Re-queued]         [To DLQ]        [Held Aside]

Lock Duration and Lock Renewal Mechanics

Every Peek-Lock transaction is bound by the queue or subscription's configured `LockDuration`. If the lock expires before the client settles the message, the broker automatically releases the message back to the active queue. This is a critical safeguard against consumer crashes.

In Bussin, lock parameters are managed via protocol-native variables:

Lock Expiry Tracking: The browser UI actively displays the remaining lock lease time, calculated directly from the AMQP message's `LockedUntilUtc` system property.
Lock Duration Extension: For extensive manual diagnostics, developers can trigger lock renewals. Bussin leverages management-plane links to execute `RenewMessageLockAsync` updates, renewing the lock lease without losing current sequence offsets.

Aesthetic Tip: When using the Bussin active explorer, utilize the message preview blade to review the absolute system timestamp values of `LockedUntilUtc`, `SequenceNumber`, and `PartitionKey` in real-time.

Next Steps

Continue exploring browser-native workflows by reviewing our guide on Dead-letter queue inspection and recovery, validate routing rules in Topic and subscription monitoring, or examine our AMQP protocol glossary.