Struct MappingStore 

pub struct MappingStore { /* private fields */ }

Thread-safe concurrent one-way replacement store.

Caches forward mappings for per-run consistency (same input always produces the same output within a run). There is no reverse map, no journal, and no persistence — replacements are one-way only.

See the module-level documentation for concurrency and memory details.

Implementations

impl MappingStore

pub fn new( generator: Arc<dyn ReplacementGenerator>, capacity_limit: Option<usize>, ) -> Self

Create a new, empty mapping store.

Arguments

• generator — replacement strategy (HMAC or random).
• capacity_limit — optional max number of unique mappings.

pub fn new_with_allowlist( generator: Arc<dyn ReplacementGenerator>, capacity_limit: Option<usize>, allowlist: Arc<AllowlistMatcher>, ) -> Self

Create a new store with an allowlist. Values matching the allowlist are returned unchanged and never recorded in the forward map.

pub fn allowlist(&self) -> Option<&Arc<AllowlistMatcher>>

Return the allowlist attached to this store, if any.

pub fn get_or_insert( &self, category: &Category, original: &str, ) -> Result<CompactString>

Get or create the sanitized replacement for (category, original).

This is the primary API for one-way sanitization.

Hot-path allocation: When the value is already cached, this method is allocation-free. The inner DashMap::get accepts &str directly via ZeroizingString: Borrow<str>, so no temporary String is constructed.

Thread-safety: Uses DashMap::entry() which holds a shard-level lock only for the duration of the insert closure. The generator is called inside the lock, but generation is fast (one HMAC or one RNG call). Capacity enforcement uses compare_exchange to prevent TOCTOU over-insertion.

Per-run consistency: Once a value is mapped, all subsequent lookups return the same sanitized value (first-writer-wins).

Errors

Returns SanitizeError::CapacityExceeded if the store has reached its configured capacity limit.

pub fn forward_lookup( &self, category: &Category, original: &str, ) -> Option<CompactString>

Look up an existing forward mapping without creating one.

pub fn len(&self) -> usize

Number of unique mappings in the store.

pub fn is_empty(&self) -> bool

Whether the store is empty.

pub fn clear(&mut self)

Remove all mappings, zeroizing the original plaintexts.

This is useful for resetting the store between runs without dropping and recreating it.

pub fn snapshot(&self) -> usize

Snapshot the current insertion count.

Returns an opaque usize that can be passed to Self::iter_since to iterate only the entries added after this point — useful for finding which mappings a structured processor pass discovered without building a full HashSet of all existing keys.

O(1), no allocation.

pub fn iter_since( &self, snapshot: usize, ) -> impl Iterator<Item = (Category, CompactString, CompactString)> + '_

Iterate over entries added at or after the given snapshot.

snapshot is the value returned by a previous call to Self::snapshot. Entries whose insertion index is ≥ snapshot are yielded; older entries are skipped. Still O(n) in total store size, but avoids allocating a HashSet of all prior keys.

Implementation note: the inner .collect::<Vec<_>>() inside the flat_map is required to release the DashMap shard lock before yielding items — it allocates one Vec per category shard visited.

pub fn iter( &self, ) -> impl Iterator<Item = (Category, CompactString, CompactString)> + '_

Iterate over all mappings. Yields (category, original, sanitized).

Note: iteration over DashMap is not snapshot-consistent if concurrent inserts are happening. Call this after all workers have finished.

Implementation note: allocates one Vec per category shard to release the DashMap shard lock between categories.

Trait Implementations

impl Drop for MappingStore

Zeroize original keys stored in the forward map on drop. Dropping the outer DashMap triggers Arc::drop for each inner map; when the last Arc drops, ZeroizingString::drop runs for every key, overwriting the plaintext before the memory is freed.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.