Struct Mailbox 

pub struct Mailbox { /* private fields */ }

One session’s Maildir.

Implementations

impl Mailbox

pub fn open(root: &Path, address: &MailAddress) -> Result<Self>

Open (creating when absent) the mailbox of address under root.

pub fn address(&self) -> &MailAddress

Address this mailbox belongs to.

pub fn request_wake(&self, id: &str) -> Result<()>

Retain a wake separately from the envelope: queue-only mail never requests one.

pub fn pending_wakes(&self) -> Result<Vec<String>>

Retained terminal deliveries, independent of whether a hook read the envelope.

pub fn acknowledge_wake(&self, id: &str)

A confirmed wake consumes only the requests observed before that wake.

pub fn wake_state(&self, id: &str) -> WakeState

How a wake’s delivery has gone so far: its failed attempts and when the next is due (epoch ms), kept in the wake itself so a restarted watcher waits as the last one did. A fresh wake has made no attempt and is due now.

pub fn set_wake_state(&self, id: &str, state: &WakeState) -> Result<()>

Record a failed attempt at a wake’s delivery and when the next is due.

pub fn expire_wake(&self, id: &str, expiry: &WakeExpiry) -> Result<()>

End a wake whose delivery never succeeded within its bound: the wake goes, the message stays filed and unread (a session that runs again reads its unread mail first), and the expiry is kept as this mailbox’s record.

pub fn expired(&self) -> Vec<WakeExpiry>

The expired wakes this mailbox records, oldest first.

pub fn deliver(&self, envelope: &Envelope) -> Result<PathBuf>

File envelope. Returns the path it is filed under; an envelope whose id is already filed is not written again.

pub fn deliver_read(&self, envelope: &Envelope) -> Result<PathBuf>

File an envelope that has already reached its reader by another door (a runtime’s own input), so the thread keeps it without offering it again. Deduplicates on the id like Self::deliver.

pub fn file_read(&self, envelope: &Envelope) -> Result<PathBuf>

Self::deliver_read for a caller that has just listed the mailbox and knows the id is not filed: many at once, without a search each.

pub fn list(&self) -> Result<Vec<StoredEnvelope>>

Every envelope in the mailbox, oldest first.

pub fn unread(&self) -> Result<Vec<StoredEnvelope>>

Envelopes not yet handed on, oldest first. The user’s own turns are not among them: they are not the reader’s to read, their door delivers them (Self::user_turns).

pub fn user_turns(&self) -> Result<Vec<StoredEnvelope>>

The user’s own turns still waiting for their door, oldest first.

pub fn claim_user_turn( &self, stored: &StoredEnvelope, ) -> Result<Option<StoredEnvelope>>

Take one of the user’s waiting turns for typing, so a second typer (the machine’s watcher beside a direct delivery) does not type it too: moved into claimed/ under this process’s pid. None when another typer took it first. Hand it on and acknowledge it, or release it to wait again.

pub fn release(&self, claimed: &StoredEnvelope) -> Result<()>

Return a claimed envelope to waiting, as it was before it was claimed.

pub fn mark_read(&self, stored: &StoredEnvelope) -> Result<()>

Record that a waiting envelope reached its reader by its door.

pub fn find(&self, id: &str) -> Result<Option<StoredEnvelope>>

The envelope filed under id, in either state.

pub fn find_prefix(&self, prefix: &str) -> Result<Vec<StoredEnvelope>>

The envelopes whose id starts with prefix, in either state.

pub fn find_prefixes( &self, prefixes: &[&str], ) -> Result<Vec<(usize, StoredEnvelope)>>

The messages whose id starts with any of prefixes, in one pass over the mailbox, each with the index of the prefix it matched (a message matching two prefixes is listed twice).

pub fn subscribe_idle(&self, subscription: &IdleSubscription) -> Result<()>

Record (or update) a subscription on this mailbox’s session.

pub fn subscriptions(&self) -> Result<Vec<IdleSubscription>>

The idle subscriptions waiting on this mailbox’s session.

pub fn remove_subscription(&self, message_id: &str) -> Result<()>

Remove one subscription. Fails when another watcher removed it first, so a notice is sent at most once.

pub fn claim_unread( &self, via: &str, caller: Option<&str>, ) -> Result<Vec<StoredEnvelope>>

Take every unread envelope for this mailbox’s own reader, oldest first: only the recipient (the session or operator the mailbox belongs to) claims, through message inbox, message wait, its read_messages tool or an operator’s own sessions.inbox; anyone else’s read only looks and never consumes. via names the door and caller the reader; each claim is recorded (claims/<id>.json: pid, door, caller, recipient), which is what makes the message delivered for the mailbox’s carrier.

Each is moved into claimed/ under this process’s pid, so a second reader does not take it too. Hand each one on, then acknowledge it. Claims left by readers that are no longer running are returned to new/ first, so their messages are offered again.

pub fn record_claim(&self, id: &str, claim: &Claim) -> Result<()>

Record who took a message to its reader: a claim by the recipient itself, or a hand-over to the recipient’s door (recipient: true). Kept beside the mailbox (claims/<id>.json), the latest claim per message.

pub fn claim_of(&self, id: &str) -> Option<Claim>

The latest recorded claim of a message, when it has one.

pub fn delivered_to_recipient(&self, id: &str) -> bool

Whether a message reached its recipient: the recipient claimed it, or its door was handed it. A message read any other way is not delivered, and its carrier still hands it over.

pub fn acknowledge(&self, claimed: &StoredEnvelope) -> Result<()>

Record that a claimed envelope reached its reader.

Trait Implementations

impl Clone for Mailbox

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Mailbox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.