Struct DeadLetterQueue 

pub struct DeadLetterQueue { /* private fields */ }

Queue for messages that could not be delivered.

Bounded FIFO queue: when full, the oldest entry is evicted. Queryable by target PID, reason variant, and time range.

When an optional ChainManager is attached, every intake is recorded as an ipc.dead_letter event in the ExoChain audit trail.

Implementations

impl DeadLetterQueue

pub fn new(max_size: usize) -> Self

Create a new dead letter queue with the given capacity.

pub fn with_default_capacity() -> Self

Create a dead letter queue with the default capacity (10,000).

pub fn with_chain(self, cm: Arc<ChainManager>) -> Self

Attach a chain manager for audit logging (builder pattern).

When set, every intake call emits an ipc.dead_letter event to the ExoChain.

pub fn intake(&self, message: KernelMessage, reason: DeadLetterReason)

Intake a message that could not be delivered.

If the queue is at capacity, the oldest entry is evicted (FIFO). When a ChainManager is attached, the dead letter is recorded as an ipc.dead_letter chain event.

pub fn len(&self) -> usize

Number of dead letters currently in the queue.

pub fn is_empty(&self) -> bool

Whether the queue is empty.

pub fn capacity(&self) -> usize

Maximum capacity of the queue.

pub fn query_by_target(&self, pid: Pid) -> Vec<DeadLetter>

Query dead letters by target PID.

pub fn query_by_reason(&self, reason_name: &str) -> Vec<DeadLetter>

Query dead letters by reason variant name.

pub fn query_by_time_range( &self, since: DateTime<Utc>, until: DateTime<Utc>, ) -> Vec<DeadLetter>

Query dead letters within a time range (inclusive).

pub fn take_for_retry(&self, msg_id: &str) -> Option<DeadLetter>

Remove and return a dead letter by message ID for retry.

The retry_count on the returned letter is incremented.

pub fn re_add(&self, letter: DeadLetter)

Re-add a letter that failed retry back into the queue.

pub fn snapshot(&self) -> Vec<DeadLetter>

Get all dead letters (snapshot).

pub fn clear(&self)

Clear all dead letters.