Module strategy 

Pluggable replacement strategies.

This module provides the Strategy trait and five built-in implementations that can be composed with the mapping engine via StrategyGenerator, an adapter that implements ReplacementGenerator.

Design Note

This is the extensibility layer for library consumers who need custom replacement logic. The CLI binary uses crate::generator::HmacGenerator and crate::generator::RandomGenerator directly with category-aware formatters for performance and simplicity. Both paths share the same ReplacementGenerator interface. See ARCHITECTURE.md section 2 for details on the dual-path design.

Architecture

┌──────────────────────┐
│    MappingStore       │  ← owns Arc<dyn ReplacementGenerator>
└──────────┬───────────┘
           │ calls generate(category, original)
           ▼
┌──────────────────────┐
│  StrategyGenerator   │  ← adapter: produces entropy, delegates to Strategy
│  (ReplacementGenerator)│
└──────────┬───────────┘
           │ calls replace(original, &entropy)
           ▼
┌──────────────────────┐
│   dyn Strategy       │  ← pure function of (original, entropy) → String
│                      │
│  RandomString        │
│  RandomUuid          │
│  FakeIp              │
│  PreserveLength      │
│  HmacHash            │
└──────────────────────┘

Deterministic Mode

Strategies are pure functions of (original, entropy). Determinism is controlled by the entropy source inside StrategyGenerator:

• Deterministic (EntropyMode::Deterministic): entropy is derived via HMAC-SHA256 keyed with a fixed seed — same seed + same input → same replacement across runs.
• Random (EntropyMode::Random): entropy comes from OS CSPRNG — each call produces a fresh value (but the MappingStore still caches the first result per unique input for per-run consistency).

The HmacHash strategy is an exception: it carries its own HMAC key and is deterministic by construction regardless of the entropy mode.

Extensibility

To add a new replacement strategy:

1. Create a struct implementing Strategy.
2. Return a unique name from Strategy::name.
3. Implement Strategy::replace as a pure function of (original, entropy).
4. Wrap it in a StrategyGenerator to use with MappingStore.

Third-party crates can implement Strategy without modifying this crate, since the trait is public and object-safe.

Structs

FakeIp

Generates a fake IPv4 address in the 10.0.0.0/8 reserved range.

HmacHash

HMAC-SHA256 hash strategy — deterministic by construction.

PreserveLength

Generates a replacement with the same byte length as the original.

RandomString

Generates an alphanumeric string from entropy bytes.

RandomUuid

Generates a UUID v4–formatted string from entropy bytes.

StrategyGenerator

Adapter that bridges a Strategy into the ReplacementGenerator interface consumed by MappingStore.

Enums

EntropyMode

How entropy is produced for strategies.

Traits

Strategy

A pluggable replacement strategy.