calternal_imap::store

Authenticated message provider boundary (#428/#486, DESIGN §§9, 53). The session never accepts a User ID in a command: its provider is bound to one authenticated User. UIDs name immutable revisions; deleting a replaced UID cannot trash the current revision. Filesystem writes belong to the Notes Plugin.

Source: crates/calternal-imap/src/store.rs

Structs

AppendResult

pub struct AppendResult

The UIDPLUS receipt names the committed replacement or conflicted copy.

Fields

• pub uidvalidity: u32
• pub uid: u32

Source: crates/calternal-imap/src/store.rs:318

CopyResult

pub struct CopyResult

UIDPLUS mapping for a committed or durably queued COPY/MOVE (#486, §53). Parallel vectors name corresponding immutable source and destination UIDs.

Fields

• pub uidvalidity: u32
• pub sources: Vec<u32>
• pub destinations: Vec<u32>

Source: crates/calternal-imap/src/store.rs:325

MailboxRevision

pub struct MailboxRevision

Durable mailbox revision. Sessions use it to skip unchanged refreshes.

Fields

• pub uidvalidity: u32
• pub highest_modseq: u64

Implements: Clone, Copy, Debug, Eq, PartialEq

Source: crates/calternal-imap/src/store.rs:56

MailboxStatus

pub struct MailboxStatus

Selected-folder counters and revision clock for STATUS without loading message bodies; provider defaults preserve small in-memory stores (#780).

Fields

• pub uidvalidity: u32
• pub highest_modseq: u64
• pub uidnext: u32
• pub messages: u64
• pub unseen: u64: UNSEEN stays a counter so STATUS does not require MIME reads (#1038).
• pub deleted: u64

Implements: Clone, Copy, Debug, Eq, PartialEq

Source: crates/calternal-imap/src/store.rs:44

Message

pub struct Message

One live mailbox copy. Source stays private to the authenticated session.

Fields

• pub uid: u32
• pub modseq: u64
• pub identity: String
• pub source: Arc<str>: Shared immutable bytes for this committed source revision (#808).
• pub deleted: bool
• pub internal_date: i64: Unix seconds served as INTERNALDATE. Notes use their creation time; Mail uses the cached upstream received time (#428/#486, DESIGN §53).

Implements: Clone, Debug

Source: crates/calternal-imap/src/store.rs:13

MessageMetadata

pub struct MessageMetadata

Exact wire metadata can be served without downloading attachment bytes (#684, DESIGN §53). Headers include their terminating empty line.

Fields

• pub size: u32
• pub headers: Vec<u8>

Source: crates/calternal-imap/src/store.rs:27

Snapshot

pub struct Snapshot

Consistent selected view and per-User revision clock; UIDNEXT never decreases.

Fields

• pub uidvalidity: u32
• pub highest_modseq: u64
• pub uidnext: u32
• pub messages: Vec<Message>

Implements: Clone, Debug

Source: crates/calternal-imap/src/store.rs:34

Enums

FlagMode

pub enum FlagMode

IMAP flag intent independent of the wire codec (#486, DESIGN §53).

Variants

• Replace
• Add
• Remove

Implements: Clone, Copy

Source: crates/calternal-imap/src/store.rs:333

Traits

Changes

pub trait Changes: Send

A per-User subscription, kept alive for the whole authenticated connection. Lag wakes reconciliation; it must never disclose another User’s event data.

Changes::changed

fn changed(&mut self) -> StoreFuture<'_, ()>;

No doc comment.

Source: crates/calternal-imap/src/store.rs:313

NotesStore

pub trait NotesStore: Send + Sync

Commands use virtual mailbox names and provider-bound immutable identities. Notes checks Home identities; Mail checks owner-scoped provider coordinates (#428/#486, DESIGN §§9, 53). Defaults keep the Notes bridge contract.

NotesStore::validate_mailbox

fn validate_mailbox(&self, mailbox: &str) -> Result<(), &'static str>

Validate a display mailbox without creating a filesystem path (#486). Notes remains the default; a Mail provider validates its own namespace.

NotesStore::mailbox_flags

fn mailbox_flags(&self, _mailbox: &str) -> (&'static str, &'static str)

Advertise the provider’s supported and permanent flags (#486). Static wire atoms cannot include client-controlled protocol bytes.

NotesStore::mailbox_attributes

fn mailbox_attributes(&self, _mailbox: &str) -> &'static str

Static LIST attributes identify a provider’s special-use destinations (#486/#1032, RFC 6154). Defaults preserve the Notes namespace. These wire atoms must never contain mailbox labels or other client input.

NotesStore::message_flags

fn message_flags(&self, message: &Message) -> Vec<String>

Return the flags of this exact provider revision (#486). Notes has no read/unread state; the default preserves its always-Seen projection.

NotesStore::cache_flags

fn cache_flags(&self, message: &mut Message, flags: &[String])

Update the selected revision’s flag projection after committed STORE (#486). Notes has deletion intent only; Mail preserves its native JSON.

NotesStore::subscribe

fn subscribe(&self) -> Box<dyn Changes>;

No doc comment.

NotesStore::render

fn render<'a>(&'a self, message: &'a Message) -> StoreFuture<'a, Vec<u8>>

Render one immutable revision. A Home provider can restore the accepted Apple HTML/CID wrapper while keeping Markdown authoritative (#428 D9).

NotesStore::metadata

fn metadata<'a>(&'a self, message: &'a Message) -> StoreFuture<'a, MessageMetadata>

Notes derive exact metadata from their generated wrapper. Mail overrides this with sync-time headers and size; body cache limits do not apply (#684).

NotesStore::served

fn served<'a>(&'a self, message: &'a Message) -> StoreFuture<'a, ()>

Record that message was sent to an Apple client as a full body. The Home provider keeps this durably so an APPEND on a later connection can prove which revision it edited (#428 live Mac run). Failure only loses merge evidence; the APPEND then keeps both versions.

NotesStore::folders

fn folders(&self) -> StoreFuture<'_, Vec<String>>

Return virtual Tag folders, including persistent empty folders (#428).

NotesStore::create_folder

fn create_folder<'a>(&'a self, mailbox: &'a str) -> StoreFuture<'a, ()>

Save an empty folder as User metadata; never make a Home directory from the virtual mailbox spelling (#428 D2).

NotesStore::select

fn select<'a>(&'a self, mailbox: &'a str) -> StoreFuture<'a, Snapshot>;

No doc comment.

NotesStore::status

fn status<'a>(&'a self, mailbox: &'a str) -> StoreFuture<'a, MailboxStatus>

Read only the selected mailbox counters; the fallback keeps existing providers correct while the Home-backed Notes provider uses its Index.

NotesStore::revision

fn revision<'a>(&'a self, mailbox: &'a str) -> StoreFuture<'a, Option<MailboxRevision>>

Read a cheap durable clock before rebuilding a snapshot. None retains the prior full-refresh behavior for providers without a revision source.

NotesStore::append

fn append<'a>(
        &'a self,
        mailbox: &'a str,
        base: Option<&'a (String, Message)>,
        message: &'a crate::mime::NoteMessage,
    ) -> StoreFuture<'a, AppendResult>

APPEND applies a fetched base or creates a conflicted copy. An absent base must never authorize overwriting an existing identity (#428 D8).

NotesStore::accepts_raw_append

fn accepts_raw_append(&self, _mailbox: &str) -> bool

Mail accepts exact MIME drafts without Apple Note validation (#486, DESIGN §53). Notes keeps its existing parse and merge path by default.

NotesStore::append_raw

fn append_raw<'a>(
        &'a self,
        mailbox: &'a str,
        raw: &'a [u8],
        flags: &'a [String],
        internal_date: Option<i64>,
    ) -> StoreFuture<'a, Option<AppendResult>>

A queued APPEND can omit APPENDUID until the provider assigns a UID. Flags and the optional received time came from the checked wire codec.

NotesStore::transfer

fn transfer<'a>(
        &'a self,
        mailbox: &'a str,
        destination: &'a str,
        messages: &'a [Message],
        moving: bool,
    ) -> StoreFuture<'a, Option<CopyResult>>

Queue a whole COPY/MOVE command atomically (#486, DESIGN §53). Source messages are immutable selected revisions. A queued operation need not provide COPYUID before upstream assigns destination UIDs.

NotesStore::flag

fn flag<'a>(
        &'a self,
        mailbox: &'a str,
        message: &'a Message,
        deleted: bool,
    ) -> StoreFuture<'a, ()>

Deleted flags belong to one immutable mailbox revision. Replaced UIDs remain harmless even when Apple deletes them after a successful APPEND.

NotesStore::flag_if

fn flag_if<'a>(
        &'a self,
        mailbox: &'a str,
        message: &'a Message,
        deleted: bool,
        unchanged_since: Option<u64>,
    ) -> StoreFuture<'a, Option<u64>>

CONDSTORE compares the current MODSEQ inside the same flag transaction. None means the UID is newer than UNCHANGEDSINCE and must be reported as MODIFIED, without a mutation (#428).

NotesStore::store_flags

fn store_flags<'a>(
        &'a self,
        mailbox: &'a str,
        message: &'a Message,
        mode: FlagMode,
        flags: &'a [String],
        unchanged_since: Option<u64>,
    ) -> StoreFuture<'a, Option<(u64, Vec<String>)>>

Apply the full IMAP flag operation (#486, DESIGN §53). The default keeps Notes’ deletion-only semantics and revision-safe CONDSTORE check. Mail overrides this to atomically queue flags and return committed state.

NotesStore::expunge

fn expunge<'a>(&'a self, mailbox: &'a str, message: &'a Message) -> StoreFuture<'a, bool>

Trash only the still-current Note revision, under the filesystem writer lock. True removes the selected UID; false retains a live UID when another connection cleared its deletion intent (#428).

Source: crates/calternal-imap/src/store.rs:64

Type aliases

StoreFuture

pub type StoreFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, &'static str>> + Send + 'a>>;

Futures keep the provider independent of a particular Index backend.

Source: crates/calternal-imap/src/store.rs:9