proxywhirl.cache.manager

Cache management for proxy storage with multi-tier support.

This module provides the CacheManager class for managing cached proxies across three storage tiers: L1 (memory), L2 (JSONL files), and L3 (SQLite).

Classes

CacheManager	Manages multi-tier caching of proxies with automatic promotion/demotion.
TTLManager	Manages TTL-based expiration with hybrid lazy + background cleanup.

Module Contents

class proxywhirl.cache.manager.CacheManager(config)

Manages multi-tier caching of proxies with automatic promotion/demotion.

Orchestrates caching across three tiers:

• L1 (Memory): Fast in-memory cache using OrderedDict (LRU)

• L2 (Disk): Persistent cache with configurable backend (JSONL for <10K entries, SQLite for larger caches with O(log n) lookups)

• L3 (SQLite): Database cache for cold storage with full queryability

Supports TTL-based expiration, health-based invalidation, and graceful degradation when tiers fail.

Example

>>> # Default JSONL backend
>>> config = CacheConfig()
>>> manager = CacheManager(config)

>>> # SQLite backend for large caches
>>> from proxywhirl.cache.models import L2BackendType
>>> config = CacheConfig(l2_backend=L2BackendType.SQLITE)
>>> manager = CacheManager(config)

Initialize cache manager with configuration.

Parameters:

config (proxywhirl.cache.models.CacheConfig) – Cache configuration with tier settings

clear()

Clear all entries from all tiers.

Thread-safe: Uses lock to ensure atomic clearing across all tiers.

Returns:

Total number of entries cleared

Return type:

int

delete(key)

Delete entry from all tiers.

Thread-safe: Uses lock to ensure atomic deletion across all tiers.

Parameters:

key (str) – Cache key to delete

Returns:

True if deleted from at least one tier, False if not found

Return type:

bool

export_to_file(filepath)

Export all cache entries to a JSONL file.

Parameters:

filepath (str) – Path to export file

Returns:

Dict with ‘exported’ and ‘failed’ counts

Return type:

dict[str, int]

static generate_cache_key(proxy_url)

Generate cache key from proxy URL.

Uses SHA256 hash for consistent, URL-safe keys.

Parameters:

proxy_url (str) – Proxy URL to hash

Returns:

Hex-encoded SHA256 hash (first 16 chars)

Return type:

str

get(key)

Retrieve entry from cache with tier promotion.

Checks L1 → L2 → L3 in order. Promotes entries to higher tiers on hit. Updates access_count and last_accessed on successful retrieval.

Thread-safe: Uses lock to prevent race conditions during promotion and expiration.

Parameters:

key (str) – Cache key to retrieve

Returns:

CacheEntry if found and not expired, None otherwise

Return type:

proxywhirl.cache.models.CacheEntry | None

get_statistics()

Get current cache statistics.

Returns:

CacheStatistics with hit rates, sizes, and tier status

Return type:

proxywhirl.cache.models.CacheStatistics

invalidate_by_health(key)

Mark proxy as unhealthy and evict if failure threshold reached.

Increments the failure_count for the proxy and sets health_status to UNHEALTHY. If failure_count reaches the configured failure_threshold, the proxy is removed from all cache tiers.

Thread-safe: Uses lock throughout entire operation to prevent TOCTOU race conditions.

Parameters:

key (str) – Cache key to invalidate

Return type:

None

Note

• If health_check_invalidation is disabled, still tracks failures but doesn’t evict

• Logs at DEBUG level for failures, INFO level for evictions

• Updates statistics for health-based evictions

• RACE-001 fix: Holds lock throughout entire operation to prevent race between get and update/delete operations

put(key, entry)

Store entry in all enabled tiers.

Writes to all tiers for redundancy. Credentials are automatically redacted in logs.

Thread-safe: Uses lock to ensure atomic writes across all tiers.

Parameters:

• key (str) – Cache key

• entry (proxywhirl.cache.models.CacheEntry) – CacheEntry to store

Returns:

True if stored in at least one tier, False otherwise

Return type:

bool

warm_from_file(file_path, ttl_override=None)

Load proxies from a file to pre-populate the cache.

Supports JSON (array), JSONL (newline-delimited), and CSV formats. Invalid entries are skipped with warnings logged.

Parameters:

• file_path (str) – Path to file containing proxy data

• ttl_override (int | None) – Optional TTL in seconds (overrides default_ttl_seconds)

Returns:

Counts for loaded, skipped, and failed entries.

Return type:

dict[str, int]

class proxywhirl.cache.manager.TTLManager(cache_manager, cleanup_interval=60)

Manages TTL-based expiration with hybrid lazy + background cleanup.

Combines two cleanup strategies: - Lazy expiration: Check TTL on every get() operation - Background cleanup: Periodic scan of all tiers to remove expired entries

cache_manager

Reference to parent CacheManager

cleanup_interval

Seconds between background cleanup runs

enabled

Whether background cleanup is running

cleanup_thread

Background thread for cleanup

Initialize TTL manager.

Parameters:

• cache_manager (CacheManager) – Parent CacheManager instance

• cleanup_interval (int) – Seconds between cleanup runs

start()

Start background cleanup thread.

Return type:

None

stop()

Stop background cleanup thread.

Return type:

None