Struct PoolStore 

pub struct PoolStore { /* private fields */ }

Implementations

impl PoolStore

pub fn delete_protection_status( &self, ) -> Result<Option<PoolDeleteProtectionStatus>, StoreError>

pub fn acquire_delete_protection( &self, lease_id: Hash, reason: &str, ) -> Result<PoolDeleteProtectionChange, StoreError>

pub fn hold_delete_protection( &self, lease_id: Hash, expected_record_sha256: Hash, ) -> Result<PoolDeleteProtectionGuard, StoreError>

Hold the exact durable delete-protection record against release while a long-running online retirement audit uses it as an append-only Pool authority. Ordinary writes and physical member moves remain available.

pub fn release_delete_protection( &self, lease_id: Hash, expected_record_sha256: Hash, ) -> Result<PoolDeleteProtectionChange, StoreError>

impl PoolStore

pub fn maintain( &self, max_items: usize, ) -> Result<PoolMaintenanceReport, StoreError>

pub fn maintain_with_batch_items( &self, max_items: usize, batch_items: usize, ) -> Result<PoolMaintenanceReport, StoreError>

impl PoolStore

pub fn balance_temperature(&self) -> Result<PoolTemperatureReport, StoreError>

impl PoolStore

pub fn open<P: AsRef<Path>>( path: P, config: PoolStoreConfig, ) -> Result<Self, StoreError>

pub fn stop_temperature_worker(&self) -> Result<(), StoreError>

Stop this process’s background temperature balancer.

Exact maintenance and recovery commands use this before taking catalog snapshots so the same Pool handle cannot relocate blobs behind their authority checks.

pub fn add_member( &self, config: PoolMemberConfig, ) -> Result<PoolMemberId, StoreError>

pub fn begin_drain(&self, id: PoolMemberId) -> Result<(), StoreError>

pub fn update_member_limits( &self, id: PoolMemberId, capacity_bytes: u64, max_read_concurrency: u32, max_write_concurrency: u32, ) -> Result<(), StoreError>

pub fn update_member_temperature_watermarks( &self, id: PoolMemberId, low_percent: u8, high_percent: u8, ) -> Result<(), StoreError>

pub fn remove_member(&self, id: PoolMemberId) -> Result<(), StoreError>

pub fn member(&self, id: PoolMemberId) -> Result<PoolMemberStatus, StoreError>

pub fn members(&self) -> Result<Vec<PoolMemberStatus>, StoreError>

pub fn blob_location( &self, hash: &Hash, ) -> Result<Option<PoolMemberId>, StoreError>

pub fn put_sync(&self, hash: Hash, data: &[u8]) -> Result<bool, StoreError>

pub fn put_many_report_sync( &self, items: &[(Hash, Vec<u8>)], ) -> Result<PutManyReport, StoreError>

pub fn put_many_optimistic_report_sync( &self, items: &[(Hash, Vec<u8>)], ) -> Result<PutManyReport, StoreError>

Insert a locally generated content-addressed batch while trusting catalogued committed locations. Pending locations still take the ordinary repair path; stored and moving locations need no payload read.

pub fn put_many_sync( &self, items: &[(Hash, Vec<u8>)], ) -> Result<usize, StoreError>

pub fn put_many_optimistic_sync( &self, items: &[(Hash, Vec<u8>)], ) -> Result<usize, StoreError>

pub fn get_sync(&self, hash: &Hash) -> Result<Option<Vec<u8>>, StoreError>

pub fn get_range_sync( &self, hash: &Hash, start: u64, end_inclusive: u64, ) -> Result<Option<Vec<u8>>, StoreError>

pub fn blob_size_sync(&self, hash: &Hash) -> Result<Option<u64>, StoreError>

pub fn exists(&self, hash: &Hash) -> Result<bool, StoreError>

pub fn existing_hashes_in_sorted_candidates( &self, sorted_hashes: &[Hash], ) -> Result<Vec<bool>, StoreError>

pub fn committed_hashes_in_sorted_candidates( &self, sorted_hashes: &[Hash], ) -> Result<Vec<bool>, StoreError>

Mark hashes whose pool catalog entries represent committed data.

Pending records deliberately return false so an interrupted migration supplies the source bytes again and lets the ordinary repair/finalize path complete them. Stored and moving records are already durable and can be skipped by an incremental migration without rereading payloads.

pub fn catalog_locations_in_sorted_candidates( &self, sorted_hashes: &[Hash], ) -> Result<Vec<PoolCatalogLocation>, StoreError>

Return the exact catalog state for one sorted source page using a single read transaction.

Migration reconciliation uses this to distinguish a terminal size-matched Stored record from Missing, crash-left Pending, and non-terminal Moving without loading target payload bytes.

pub fn scan_catalog_locations_after( &self, after: Option<Hash>, limit: usize, ) -> Result<Vec<(Hash, PoolCatalogLocation)>, StoreError>

Scan one bounded raw catalog page in hash order.

Online migration content audits use the raw catalog key as their resumable cursor. Pending and moving rows are returned explicitly: they are not terminal content authorities, but their keys must still advance the scan so a page containing only transient rows makes progress.

pub fn largest_member_map_size_bytes(&self) -> Result<Option<usize>, StoreError>

Largest map size among members that are available in this process.

The pool catalog is a separate LMDB environment and is intentionally not reported as blob capacity.

pub fn delete_sync(&self, hash: &Hash) -> Result<bool, StoreError>

pub fn delete_many_sync(&self, hashes: &[Hash]) -> Result<usize, StoreError>

Delete a batch with one transaction per affected member and one pool catalog transaction.

pub fn cleanup_stale_pending_exact_offline_sync( &self, expected: &[PoolStalePending], ) -> Result<PoolStalePendingCleanupReport, StoreError>

Clear one exact, bounded set of crash-abandoned Pending records.

This is deliberately narrower than Self::delete_many_sync: every live location must still equal the authorized (hash, member, size), no hash may be pinned or owned by a move, and no member may contain a physical record for the hash. The catalog and all secondary indexes change in one transaction and are force-synced before success.

A caller must stop and fence every Pool writer before its strict read-only audit and keep that fence through this call. This includes clones and handles in this process: a writer can commit Pending, pause before entering its member gate, and otherwise resume after cleanup. Catalog and member LMDB environments do not provide one atomic cross-environment transaction, so this method intentionally makes no online-safety claim.

pub fn pin_sync(&self, hash: &Hash) -> Result<(), StoreError>

pub fn unpin_sync(&self, hash: &Hash) -> Result<(), StoreError>

pub fn pin_count_sync(&self, hash: &Hash) -> Result<u32, StoreError>

pub fn touch_accessed_sync( &self, hash: &Hash, now: u64, ) -> Result<bool, StoreError>

pub fn touch_many_accessed_sync( &self, hashes: &[Hash], now: u64, ) -> Result<usize, StoreError>

pub fn last_accessed_at_sync( &self, hash: &Hash, ) -> Result<Option<u64>, StoreError>

pub fn many_last_accessed_at_sync( &self, hashes: &[Hash], ) -> Result<Vec<(Hash, u64)>, StoreError>

pub fn list(&self) -> Result<Vec<Hash>, StoreError>

pub fn stats(&self) -> Result<StoreStats, StoreError>

pub fn writable_physical_stats(&self) -> Result<StoreStats, StoreError>

Return conservative physical usage for quota admission without scanning the logical Pool catalog.

Every member LMDB maintains its own totals transactionally, so summing those counters is constant in the member count and remains accurate across processes and mixed binary versions. Blobs temporarily duplicated during a move are counted in both members, which is intentionally conservative for writable-space admission. Missing member statistics fail closed rather than undercounting storage.

pub fn force_sync(&self) -> Result<(), StoreError>

pub fn catalog_map_size_bytes(&self) -> u64

Current LMDB virtual map size for the Pool catalog.

pub fn validate_controlled_member_state_exact(&self) -> Result<(), StoreError>

Exhaustively prove every controlled member’s physical indexes and persisted aggregate counters before the first migration mutation.

Controlled reopen performs only constant-time structural checks so bounded mapping epochs do not rescan the complete target. The caller must hold the external writer fence while this one full proof runs and must keep that fence held until migration completion.

pub fn validate_controlled_authority(&self) -> Result<(), StoreError>

Revalidate every controlled catalog/member authority without forcing unrelated writer commits to storage.

This is sufficient before advancing a migration cursor when the migration observed exact Stored rows and performed no target writes. Any batch that attempted target writes must use Self::validate_controlled_authority_and_sync instead.

pub fn validate_controlled_authority_and_sync(&self) -> Result<(), StoreError>

Revalidate every controlled authority and force the catalog/member commits durable before an external migration cursor may advance.

Trait Implementations

impl Clone for PoolStore

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Deref for PoolStore

type Target = PoolStoreInner

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Store for PoolStore

fn put<'life0, 'async_trait>( &'life0 self, hash: Hash, data: Vec<u8>, ) -> Pin<Box<dyn Future<Output = Result<bool, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Store data by its hash Returns true if newly stored, false if already existed

fn put_many<'life0, 'async_trait>( &'life0 self, items: Vec<(Hash, Vec<u8>)>, ) -> Pin<Box<dyn Future<Output = Result<usize, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Store multiple blobs. Returns the number of newly stored items.

fn put_many_optimistic<'life0, 'async_trait>( &'life0 self, items: Vec<(Hash, Vec<u8>)>, ) -> Pin<Box<dyn Future<Output = Result<usize, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Store a locally generated content-addressed batch without requiring an implementation to reread bytes for hashes it already tracks.

fn get<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 Hash, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Retrieve data by hash Returns data or None if not found

fn get_range<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 Hash, start: u64, end_inclusive: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Retrieve a byte range from a blob by hash.

fn blob_size<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 Hash, ) -> Pin<Box<dyn Future<Output = Result<Option<u64>, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Return the stored blob size in bytes.

fn has<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 Hash, ) -> Pin<Box<dyn Future<Output = Result<bool, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Check if hash exists

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 Hash, ) -> Pin<Box<dyn Future<Output = Result<bool, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Delete by hash Returns true if deleted, false if didn’t exist

fn delete_many<'life0, 'async_trait>( &'life0 self, hashes: Vec<Hash>, ) -> Pin<Box<dyn Future<Output = Result<usize, StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Delete multiple hashes and return the number that existed.

fn stats<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = StoreStats> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Get storage statistics

fn pin<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 Hash, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Pin a hash (increment ref count). Pinned items are not evicted.

fn unpin<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 Hash, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Unpin a hash (decrement ref count). Item can be evicted when count reaches 0.

fn pin_count(&self, hash: &Hash) -> u32

Get pin count for a hash. 0 = not pinned.

fn flush_pending<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<usize, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Flush writes retained by an overlay store.

fn flush_pending_if_needed<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<usize, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Flush at an intermediate memory boundary. Buffered stores may retain a bounded amount between boundaries; callers must still explicitly flush all pending writes before returning a committed root.

fn set_max_bytes(&self, _max: u64)

Set maximum storage size in bytes. 0 = unlimited.

fn max_bytes(&self) -> Option<u64>

Get maximum storage size. None = unlimited.

fn evict_if_needed<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Evict unpinned items if over storage limit. Returns number of bytes freed.

fn is_pinned(&self, hash: &[u8; 32]) -> bool

Check if hash is pinned (pin count > 0)