Cache Architecture

ProxyWhirl uses a three-tier cache hierarchy to balance speed, persistence, and scale. For TOML options, see Configuration.

Why Three Tiers?

Single-tier caching forces a speed vs durability tradeoff. ProxyWhirl uses automatic promotion and demotion across tiers:

Typical workloads see 80%+ L1 hits — the database is touched on cold starts and misses only.

Alternatives rejected: single SQLite (too slow per lookup), two-tier without warm cache (higher L3 load), Redis/Memcached (external dependency for single-process use).

Data Flow

Read path (promotion):

Request → L1 miss → L2 miss → L3 hit → promote to L2 + L1
L2 hit → promote to L1
L1 hit → update LRU

Eviction path (demotion):

L1 full → LRU evict → demote to L2
L2 full → FIFO evict → demote to L3
L3 → TTL expiry → delete

Hot proxies bubble up; cold proxies sink without being lost.

Credential Security

Set PROXYWHIRL_CACHE_ENCRYPTION_KEY (Fernet key) for production. Without it, L2/L3 may store credentials in plaintext.

Graceful Degradation

Each tier tracks consecutive failures and auto-disables after three failures:

• L2 disk full → L1 + L3 continue
• L3 locked → L1 + L2 continue
• All tiers fail → operations proceed without cache (slower but functional)

Inspect per-tier health via CacheManager.get_stats().

TTL

1. Lazy expiration — every get() checks TTL before return.
2. Background cleanup (optional) — TTLManager bulk-purges expired L2/L3 entries.

Thread Safety

CacheManager uses an RLock for cross-tier ops. Per-tier mechanisms:

• L1 — manager lock
• L2 — portalocker file locks (multi-process safe)
• L3 — SQLite connection locking

See Also

• Configuration — cache_* fields
• Troubleshooting — corruption and rebuild
• Retry & Failover — health invalidation
• ADR-001: Three-Tier Cache