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<&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 register_alias(&self, category: &Category, alias: &str, sanitized: &str)

Register alias as an additional original that maps to the same sanitized replacement under category.

Structured processors use this to record the source-escaped form of a discovered value — e.g. the JSON value a"b appears in the raw bytes as a\"b. The format-preserving scanner matches against raw input bytes, so without the alias the escaped occurrence would not be redacted. Aliasing (rather than a fresh mapping) keeps the escaped occurrence consistent with the parsed value’s token.

First-writer-wins: an existing mapping for alias is left unchanged. Allowlisted or empty aliases are ignored. Like Self::get_or_insert, the new entry participates in Self::iter_since.

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(&self)

Remove all mappings, zeroizing the original plaintexts.

Takes &self so it is usable on a shared Arc<MappingStore>. Only call this after all concurrent readers and writers have finished — DashMap::clear acquires shard locks one at a time, so a concurrent get_or_insert racing with clear will observe a partially-cleared store.

Breaking change in 0.13.0: the signature changed from clear(&mut self) to clear(&self).

pub fn snapshot(&self) -> StoreSnapshot

Snapshot the current insertion count.

Returns a StoreSnapshot 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.

Breaking change in 0.13.0: previously returned usize; now returns StoreSnapshot.

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

Iterate over entries added at or after the given snapshot.

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

Breaking change in 0.13.0: the parameter type changed from usize to StoreSnapshot.

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.

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.