Global Cache Management
Relevant source files
The following files were used as context for generating this wiki page:
The Global Cache Management system in CodeBot is a centralized infrastructure designed to enhance performance and reduce database load across the Telegram Bot and the Web Application. Utilizing Redis as the primary storage backend, the system provides efficient data retrieval for frequently accessed resources, such as user statistics, search results, and file lists.
The management architecture includes automated maintenance routines, predictive cache warming for active users, and a comprehensive administrative interface for real-time monitoring and inspection. By abstracting Redis operations through a specialized CacheManager, the project ensures thread-safe access and robust failover mechanisms, including a "No-Op" mode for environments where Redis is unavailable.
Sources: cache_manager.py, webapp/README.md:120-130, main.py:2315-2330
## Core Architecture and Components
The cache system is built around a singleton CacheManager that acts as the primary gateway for all caching operations.
### The Cache Manager
The CacheManager class encapsulates the Redis client and provides high-level methods for data persistence. It supports "Safe Mode," which can disable specific maintenance tasks, and an "Enabled" flag to handle graceful degradation when Redis connection fails.
Key capabilities include:
- Dynamic Caching: Storing objects with specific categories and metadata for targeted invalidation.
- Fail-Open Logic: If Redis is disconnected, the system logs the failure but allows the application to continue by fetching data directly from the primary database.
- Stale Cleanup: A background process that scans and removes expired keys to prevent memory exhaustion.
Sources: cache_manager.py:10-50, main.py:2145-2160
### Cache Inspector Service
The CacheInspectorService provides an administrative backend for the Web Application. it allows authorized users to:
- Retrieve global Redis statistics (memory usage, hit rate, connected clients).
- Scan keys based on specific patterns (e.g.,
user:*). - View metadata for individual cache entries, including TTL (Time to Live) and size in bytes.
Sources: services/cache_inspector_service.py:15-45, webapp/templates/admin_cache_inspector.html:290-310
## Cache Lifecycle and Operations
The lifecycle of a cached item involves proactive warming, periodic maintenance, and explicit or TTL-based invalidation.
### Logic Flow: Cache Access
When a request is made for data (e.g., user stats or file lists), the application follows a standard provider pattern.
This diagram represents the standard retrieval flow implemented across bot handlers and web routes to minimize database latency.
Sources: cache_manager.py:60-80, main.py:2315-2340
### Automated Maintenance Jobs
CodeBot utilizes the Telegram Bot's JobQueue to run background tasks that ensure cache health.
| Job Name | Interval | Purpose |
|---|---|---|
cache_maintenance | 10 Minutes | Scans Redis for stale keys and clears them based on a TTL threshold. |
cache_warming | 15 Minutes | Identifies the top active users from the last 7 days and pre-renders their stats and file lists into Redis. |
Sources: main.py:2170-2185, main.py:2315-2325, main.py:2460-2475
## Administrative Tools
The system provides interfaces for both bot admins and web admins to interact with the global cache.
### Bot Commands
The cache_commands.py module registers specialized handlers for the Telegram Bot interface.
/cache_stats: Displays real-time metrics including total keys, used memory, and the hit/miss ratio./clear_cache: Allows a user to manually invalidate their own cached data.
Sources: cache_commands.py:15-35, cache_manager.py:100-115
### Web Inspector Interface
The Admin Cache Inspector UI (available at /admin/cache-inspector) provides a visual dashboard for Redis management.
The diagram shows the relationship between the service backend and the data structures presented in the admin_cache_inspector.html template.
Sources: services/cache_inspector_service.py:50-70, webapp/templates/admin_cache_inspector.html:320-340
## Configuration and Scaling
Cache behavior is governed by environment variables and internal thresholds to ensure stability under load.
### Key Configuration Constants
| Variable | Default Value | Description |
|---|---|---|
CACHE_MAINT_MAX_SCAN | 1000 | Max number of keys to check in a single maintenance pass. |
CACHE_MAINT_TTL_THRESHOLD | 60s | Keys with TTL less than this are considered candidates for early cleanup. |
CACHE_WARMING_BUDGET | 5.0s | Max time allowed for the warming job to prevent CPU spikes. |
REDIS_URL | N/A | Connection string for the Redis instance. |
Sources: main.py:2145-2155, main.py:2330-2345, webapp/README.md:120-135
### Cache Warming Logic
The _cache_warming_job in main.py uses a predictive approach. It queries MongoDB for the most active users and pre-caches the following:
- API Stats: JSON results for
/api/stats. - Search Suggestions: Common keywords and top tags used by the user.
- Core Pages: The HTML content for the
/filesroute to allow near-instant page loads.
Sources: main.py:2350-2400, main.py:2410-2430
## Summary
The Global Cache Management system provides a robust performance layer for CodeBot. By combining a singleton CacheManager with automated warming and maintenance jobs, the system balances high availability with resource efficiency. Administrators can monitor these operations through the bot or the specialized Web UI, ensuring the Redis backbone remains healthy as the user base scales.
Sources: cache_manager.py, main.py:2480-2490