Table of Contents

Class InboxEntry

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Represents a message entry in the inbox store for duplicate detection and processing tracking.

public sealed class InboxEntry
Inheritance
InboxEntry
Inherited Members
Extension Methods

Remarks

Each inbox entry tracks the complete lifecycle of an incoming message from receipt through processing completion for a specific handler. Entries are keyed by (MessageId, HandlerType), allowing the same message to be processed independently by multiple handlers.

This enables at-most-once processing semantics per handler and provides audit trails for message handling.

Constructors

InboxEntry()

Initializes a new instance of the InboxEntry class.

public InboxEntry()

InboxEntry(string, string, string, byte[], IDictionary<string, object>?)

Initializes a new instance of the InboxEntry class with specified values.

public InboxEntry(string messageId, string handlerType, string messageType, byte[] payload, IDictionary<string, object>? metadata = null)

Parameters

messageId string

The unique identifier of the message.

handlerType string

The deduplication scope this entry is keyed under, together with messageId.

messageType string

A type name for the message that the message type registry can resolve.

payload byte[]

The serialized message payload.

metadata IDictionary<string, object>

Additional message metadata.

Properties

CausationId

Gets or sets the causation identifier for tracing.

public string? CausationId { get; set; }

Property Value

string

The id of the message that caused this one, for distributed tracing and message flow tracking.

CorrelationId

Gets or sets the correlation identifier for tracing.

public string? CorrelationId { get; set; }

Property Value

string

Correlation ID for distributed tracing and message flow tracking.

HandlerType

Gets or sets the scope this message is deduplicated under, forming the composite key with MessageId.

public string HandlerType { get; set; }

Property Value

string

An opaque scope name. A caller that deduplicates per handler passes that handler's fully qualified type name, so one message can be processed independently by several handlers. The framework's own inbox writers deduplicate per message type and pass the message type's fully qualified name, so an entry written by the framework carries one scope per message type rather than one per handler.

LastAttemptAt

Gets or sets the timestamp of the last processing attempt.

public DateTimeOffset? LastAttemptAt { get; set; }

Property Value

DateTimeOffset?

UTC timestamp of the most recent processing attempt.

LastError

Gets or sets the error message if processing failed.

public string? LastError { get; set; }

Property Value

string

Error description or exception message, null if no error occurred.

MessageId

Gets or sets the unique identifier of the message.

public string MessageId { get; set; }

Property Value

string

The message identifier, typically a GUID or correlation ID.

MessageType

Gets or sets the name under which the message's .NET type is registered.

public string MessageType { get; set; }

Property Value

string

A type name the message type registry can resolve. The framework's own inbox writers store the simple name (Type.Name). An ambiguous simple name — one shared by two registered types — resolves to nothing rather than to either of them, so a collision fails loudly at resolution rather than deserializing the payload as the wrong type.

Metadata

Gets the additional message metadata including headers and context.

public IDictionary<string, object> Metadata { get; init; }

Property Value

IDictionary<string, object>

A dictionary containing headers, correlation IDs, tenant information, and other context data.

NextAttemptAt

Gets or sets the absolute time before which a failed entry must not be re-claimed for retry.

public DateTimeOffset? NextAttemptAt { get; set; }

Property Value

DateTimeOffset?

UTC timestamp computed as now + backoff(attempt) when the entry was marked failed with a backoff schedule, or null when no backoff is recorded (the entry is eligible as soon as the store's re-admission predicate otherwise allows). Honored by stores implementing IBackoffSchedulableInboxStore.

Payload

Gets or sets the serialized message payload.

public byte[] Payload { get; set; }

Property Value

byte[]

The message data as bytes, typically JSON or binary format.

ProcessedAt

Gets or sets the timestamp when the message processing was completed.

public DateTimeOffset? ProcessedAt { get; set; }

Property Value

DateTimeOffset?

UTC timestamp of successful processing completion, null if not yet processed.

ReceivedAt

Gets or sets the timestamp when the message was received.

public DateTimeOffset ReceivedAt { get; set; }

Property Value

DateTimeOffset

UTC timestamp of message receipt.

RetryCount

Gets or sets the number of processing attempts made.

public int RetryCount { get; set; }

Property Value

int

The retry count, starting from 0 for the first attempt.

Source

Gets or sets the message source or origin.

public string? Source { get; set; }

Property Value

string

Source system, queue, or endpoint that produced the message.

Status

Gets or sets the current processing status of the message.

public InboxStatus Status { get; set; }

Property Value

InboxStatus

The inbox status indicating the processing state.

TenantId

Gets or sets the tenant identifier for multi-tenant scenarios.

public string? TenantId { get; set; }

Property Value

string

Tenant ID for tenant isolation and routing.

Methods

IsEligibleForRetry(int, int)

Determines if the entry is eligible for retry processing.

public bool IsEligibleForRetry(int maxRetries = 3, int retryDelayMinutes = 5)

Parameters

maxRetries int

Maximum number of retry attempts allowed.

retryDelayMinutes int

Minimum delay between retry attempts in minutes.

Returns

bool

True if the entry can be retried, false otherwise.

MarkFailed(string)

Marks the entry as failed with the specified error.

public void MarkFailed(string error)

Parameters

error string

The error description.

Remarks

Processed is absorbing: this is a no-op on an entry that has already been processed. The transition is refused rather than applied because it is not recoverable in the layer above. A handler that outran its own lease can finish after a second processor has reclaimed the entry and finalized it; the late caller's finalize then reports "already processed" and its own error handling calls this method. Demoting the entry to Failed would make it re-admittable, so the next redelivery would run the handler a further time and IsProcessedAsync would answer false about a message that was in fact processed.

Consumers that need to distinguish "recorded the failure" from "the entry was already terminal" should read Status after the call.

MarkProcessed()

Marks the entry as successfully processed.

public void MarkProcessed()

Remarks

Idempotent: re-marking an already-processed entry leaves ProcessedAt at the instant the message was actually handled rather than restamping it.

MarkProcessing()

Marks the entry as currently being processed.

public void MarkProcessing()

Remarks

No-op once the entry is Processed. See MarkFailed(string) for why that state absorbs every later transition.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.