Struct PimdirReader 

pub struct PimdirReader { /* private fields */ }

Available on crate feature client only.

A pimdir store opened to read: the projection every role shares, and no way to write it.

A reader owns nothing and takes no lock (spec §8), so any number of them run against a store an owner is syncing, and none of them waits. PimdirStore dereferences to one, which is what keeps the owner’s reads and a frontend’s the same reads.

Built with with_pending it also overlays the queue (spec §15.4), so a producer sees what it staged before the owner applies it.

Implementations

impl PimdirReader

pub fn object_stats(&self) -> Result<PimdirObjectStats, PimdirError>

How many objects are indexed and what they weigh in total.

pub fn live_bytes(&self) -> Result<u64, PimdirError>

The bytes held by objects at least one live item still binds.

An object a live and a retained item share counts here, since purging the retained one would not free it.

pub fn object_size(&self, hash: &str) -> Result<Option<u64>, PimdirError>

One object’s stored size.

pub fn retained_before(&self, cutoff: &str) -> Result<(u64, u64), PimdirError>

What a purge with this cutoff would retire: how many retained items, and the bytes their bodies weigh.

A preview, so a confirmation can say what is at stake; the purge itself is the authority, and the collector is what frees the bytes.

pub fn indexed_hashes(&self) -> Result<BTreeSet<String>, PimdirError>

Every hash the index knows, to diff against the blob directory: the index half of what PimdirBlobs::files reads from disk.

pub fn refcount_drift(&self) -> Result<Vec<PimdirRefcountDrift>, PimdirError>

The objects whose stored refcount disagrees with their references.

The expected count is exactly what the write path maintains incrementally: an item’s body, an item’s conflict copy, each source’s stored base, and each queue row pinning a body it enqueued. recompute_refcounts is what settles what this reports.

pub fn minted_keys(&self) -> Result<Vec<PimdirMinted>, PimdirError>

The minted keys each collection holds, where it holds any.

Not a defect and nothing to repair: two copies of one identity is redundancy, and the store holds both rather than judging them. It is reported because a collection whose count climbs every sync is a source handing over the same duplicate under a new handle each run, which an operator has no other way to see.

pub fn dangling(&self) -> Result<Vec<PimdirDangling>, PimdirError>

Every row pointing at something absent: a binding whose item is gone, an item or a queue row whose object is not indexed.

Only the first is repairable (clear_dangling_bindings); the other two still hold data, so they are reported and left alone.

impl PimdirReader

pub fn open(dir: impl AsRef<Path>) -> Result<Self, PimdirError>

Opens an existing store rooted at dir to read.

The database is opened with SQLITE_OPEN_READ_ONLY: nothing is created, so a missing database errors, one no owner has stamped yet is PimdirError::Uncreated, and any other schema version is refused with PimdirError::Version.

No lock is taken, so this never waits on a sync in flight and never keeps one out.

pub fn with_pending(self) -> Self

Reads through the queue’s pending actions as well as the committed rows (spec §15.4), so an action this process staged is visible before the store’s owner applies it.

The fold covers the actions that address an existing item: set-flags and update restate it, remove and move take it out of the collection, and move and copy bring it into the target. All of them keep the item’s public id, a seq following the link id store-wide (spec §9.1), so nothing here invents an identifier.

A queued create is not folded in: it has no seq until the owner applies it, and it is a request to create an item rather than one. pending_creates reports those.

A parked row is never folded either: its error says it will not be applied without an operator, and reading it as pending would promise otherwise.

A page keeps its meaning: it comes back short only where the collection ends, staged removals or not, so a caller pages the way it always did. The cost is that a read consults the queue, which is a handful of small statements over rows a sync drains, not a scan.

pub fn overlays_pending(&self) -> bool

Whether this reader folds the pending queue over its item reads.

impl PimdirReader

The client read surface: what a consumer projects into an envelope, a vCard or an event, and the queue and generation reads beside it.

pub fn hash_algo(&self) -> PimdirHashAlgo

The hash this store names its objects by (spec §5).

pub fn blobs(&self) -> PimdirBlobs

A blob handle over this store’s object directory, bound to the hash the store names its bodies by.

Independent of the SQLite connection, so a body can be read while the store is mutably borrowed servicing a sync.

pub fn hash(&self, bytes: &[u8]) -> ReplicaHash

The content hash of a whole body, under this store’s algorithm.

pub fn hasher(&self) -> PimdirHasher

An incremental hasher for a body streamed into the blob store rather than held whole in memory, paired with PimdirBlobs::writer.

pub fn collection_account( &self, collection: &str, ) -> Result<Option<Option<String>>, PimdirError>

The account a collection is grouped under.

The outer Option is whether the collection exists, the inner one whether it is grouped: Ok(None) for an unknown collection, Ok(Some(None)) for one in a single-account store.

pub fn collection_kind( &self, collection: &str, ) -> Result<Option<String>, PimdirError>

The declared media type of a collection, or None if the store has never seen it. An empty string means the collection exists but was created lazily by a sync before any ensure_collection declared its kind.

pub fn list_collections(&self) -> Result<Vec<PimdirCollection>, PimdirError>

Lists every collection in the store (client read surface).

Ordered by sort_order then id, unordered collections last. A direct getter: it observes the shared truth and never mutates, and writes go through io-replica’s write.

pub fn list_collections_by_account( &self, account: Option<&str>, ) -> Result<Vec<PimdirCollection>, PimdirError>

Lists one account’s collections, the filter axis of a merged view (spec §9.2).

None selects the collections of a single-account store, matching on IS so a NULL account matches itself; = would match nothing.

pub fn list_accounts(&self) -> Result<Vec<String>, PimdirError>

The accounts owning at least one collection.

Not a configured roster: a store learns an account only through its collections (spec §9.2), so one with none yet does not appear here and a consumer holding the real roster reads its own config.

pub fn link_placements( &self, link_id: &str, ) -> Result<Vec<PimdirPlacement>, PimdirError>

Every live placement of one identity, with the collection and account it sits in (spec §9.2).

The store reports where a link id occurs and takes no position on whether the placements are one thing. A mail view lists them, two receipts of a newsletter having two read states; a contact view may offer to merge them. Both read these rows.

pub fn object_placements( &self, hash: &str, ) -> Result<Vec<PimdirPlacement>, PimdirError>

Every live placement of one body, by content hash: the dedup axis rather than the identity one, so it pairs placements two servers gave different link ids.

pub fn list_items( &self, collection: &str, after: Option<&str>, limit: usize, ) -> Result<Vec<PimdirItem>, PimdirError>

A keyset page of a collection’s live items (client read surface).

after is the exclusive lower bound on link_id, None starting from the beginning; at most limit items come back ordered by link_id, so the last item’s link_id is the next page’s cursor. Tombstones are excluded, and each item carries its level, so a body’s absence shows without probing the blobs.

pub fn list_items_page_asc( &self, collection: &str, after: Option<(&str, i64)>, limit: usize, ) -> Result<Vec<PimdirItem>, PimdirError>

A keyset page of a collection’s live items in the kind’s own ascending order (spec §9.3): A to Z for contacts, earliest first for mail and calendars.

after is the previous page’s last (sort_key, seq), None starting from the beginning. The pair is the cursor because a sort key is not unique and seq, unique per collection, is what makes the page total: no item is skipped or repeated across a boundary.

pub fn list_items_page_desc( &self, collection: &str, after: Option<(&str, i64)>, limit: usize, ) -> Result<Vec<PimdirItem>, PimdirError>

The same page descending: newest first for mail and calendars, Z to A for contacts.

None starts from the end, which the statement expresses by binding a key above every representable one, so a caller never invents that sentinel itself.

pub fn get_item( &self, collection: &str, seq: i64, ) -> Result<Option<PimdirItem>, PimdirError>

One live item by its public id (collection, seq), or None. A tombstoned item reads as None, and the returned item carries its internal link_id for the caller to edit by.

pub fn seq_for_link( &self, collection: &str, link_id: &str, ) -> Result<Option<i64>, PimdirError>

Resolves an item’s public id (seq) from its internal link_id, the inverse of get_item, for a consumer that just staged an add and wants the id it now shows under.

pub fn item_bindings( &self, collection: &str, link_id: &str, ) -> Result<BTreeMap<ReplicaSourceId, ReplicaSourceBinding>, PimdirError>

Every source’s binding of one item, keyed by source: the handle it is bound to, the base the last sync agreed on, and the conflict its own sync is stuck on (spec §13).

The same shape a hub carries per item, read for one item rather than a collection: an operator asking why a placement stopped moving is asking about exactly these columns, and nothing else exposes them.

pub fn list_conflicts( &self, account: Option<&str>, ) -> Result<Vec<PimdirConflict>, PimdirError>

The bindings waiting for a decision, across one account’s collections, ordered by collection then link id then source.

None lists a single-account store whole, the account grouping nothing there. Each row carries the three bodies the divergence is between, so a resolver holding no credentials reads base, local and remote from the store alone (spec §13).

The question a sync answers at the end of every run, and the one a listing command asks directly. Both are served by the partial index over the flag, so a store with nothing outstanding pays for an empty index rather than for a pass over every collection.

pub fn distinct_sources(&self) -> Result<Vec<String>, PimdirError>

The distinct source names the store has synced against, across all collections. A client attributes its writes with this: a store synced as a single source has exactly one, so the app writes as it without configuration.

pub fn count_items(&self, collection: &str) -> Result<u64, PimdirError>

A collection’s live (non-tombstone) item count (client read surface).

pub fn list_retained( &self, collection: &ReplicaCollectionId, after: Option<i64>, limit: usize, ) -> Result<Vec<PimdirItem>, PimdirError>

A keyset page of a collection’s retained items.

after is the exclusive lower bound on the public seq, None starting from the beginning; at most limit items come back ordered by seq, so the last item’s seq is the next page’s cursor. The only read that returns retained items: a caller presents them as a trash view, never merged into the live listing.

pub fn count_retained( &self, collection: &ReplicaCollectionId, ) -> Result<i64, PimdirError>

A collection’s retained item count, the counterpart of count_items.

pub fn retained_bytes(&self) -> Result<u64, PimdirError>

The bytes retention is holding across the whole store, each distinct body counted once.

An upper bound on what a purge would reclaim: a body a live item also points at keeps that reference and survives the sweep. Reported so an operator can price a retention duration.

pub fn generation(&self, collection: &str) -> Result<Option<i64>, PimdirError>

A collection’s handle-space epoch (spec §12), or None when the store has never seen it. Starts at 1, bumped only by write_rekeyed, so a frontend derives an IMAP UIDVALIDITY from it alone.

pub fn queued_collections(&self) -> Result<Vec<String>, PimdirError>

The collections with pending (non-parked) queue work, for the owner’s drain loop.

pub fn pending_actions( &self, collection: &str, ) -> Result<Vec<PimdirPendingAction>, PimdirError>

A collection’s pending (non-parked) actions in append order, decoded (spec §15.4): a frontend overlays them on its item projection for read-your-writes. An undecodable payload errors, and the owner’s next drain parks such a row.

pub fn parked_actions(&self) -> Result<Vec<PimdirParkedAction>, PimdirError>

Every parked action across the store, in append order, for status surfaces and operator repair. Parked rows are skipped by the drain and never silently deleted.

impl PimdirReader

pub fn pending_creates( &self, collection: &str, ) -> Result<Vec<PimdirPendingAction>, PimdirError>

The queued creates targeting a collection, in append order (spec §15.4).

Reported apart from the items because a create has no public id until the owner applies it, so there is nothing to address it by and no envelope to put it in. A consumer surfaces them its own way: a count under a listing, a queue view of its own, or the operator CLI’s.

pub fn count_pending_creates( &self, collection: &str, ) -> Result<usize, PimdirError>

How many creates the collection has queued, the count a listing reports so a staged item reads as queued rather than as lost.