State, Cache, and Queues (Valkey)
Relevant source files
The following files were used as context for generating this wiki page:
Athena utilizes Valkey as its primary infrastructure for managing volatile state, caching, and background job queuing. As a bancho-compatible server, Athena must handle real-time session data, player presence, and multiplayer match states that require high-throughput and low-latency access. By offloading this state to Valkey, the server supports horizontal scaling, ensuring that multiple app processes can share a consistent view of the world without relying on process-local globals.
The integration is built on the valkey-glide driver, which provides a high-performance Python client for interacting with Valkey instances. This infrastructure component is central to the project's "Two-Process Model," where the main app process handles immediate responses and the worker process consumes heavy tasks from Valkey-backed queues.
Sources: AGENTS.md:162-164, README.md:15-18, README.md:52-54
Architecture and Integration
Athena's architecture treats Valkey as an infrastructure boundary. It is decoupled from the core business logic through the use of repositories and dependency injection.
Infrastructure Role
Valkey serves four primary roles within the Athena ecosystem:
- Volatile State: Storing active user sessions, player presence, and current chat channel memberships.
- Packet Queues: Buffering binary packets for stable clients during polling cycles.
- Job Brokering: Acting as the message broker for
taskiq, facilitating communication between the app and worker processes. - Pub/Sub: Handling real-time event distribution across different server nodes.
Sources: AGENTS.md:162-164, AGENTS.md:231-233, README.md:52-54
Component Relationship
The following diagram illustrates how Valkey sits at the center of the Athena multi-process architecture:
This diagram shows Valkey acting as the shared state layer between different runtime processes.
Sources: AGENTS.md:231-233, README.md:33-40
Configuration and Connectivity
Valkey connectivity is managed through Pydantic-based settings, ensuring type safety and environmental validation.
Connection Parameters
The system requires a VALKEY_URL environment variable, which follows the redis:// URI scheme. The configuration is validated during application startup to prevent runtime failures due to misconfiguration.
| Field | Type | Default | Description |
|---|---|---|---|
valkey_url | ValkeyDsn | Required | Connection string (e.g., redis://localhost:6379) |
session_ttl | int | 300 | Expiration time for sessions in seconds |
packet_queue_max_size | int | 4096 | Max packets buffered per user |
Sources: src/osu_server/config.py:35-50, src/osu_server/config.py:27-28
Health Monitoring
The system includes a dedicated health check endpoint (GET /health) that actively pings the Valkey instance to ensure connectivity. If the Valkey client fails to respond to a ping() command, the server reports an unhealthy status and returns a 503 Service Unavailable response.
Sources: tests/unit/transports/test_health.py:157-195
Implementation Patterns
Dependency Injection
Athena uses Dishka for dependency composition. The Valkey client (typically an instance of GlideClient) is registered within the APP scope, meaning it is long-lived and shared across requests within a single process.
# Example of how Valkey might be resolved via Dishka
async def get_valkey_client(container: AsyncContainer):
valkey = await container.get(GlideClient)
# ... use client ...
Sources: AGENTS.md:94-98, tests/unit/transports/test_health.py:78-83
Volatile State Management
Unlike durable data stored in PostgreSQL (such as user accounts or beatmap metadata), volatile state in Valkey is expected to be transient. However, because it is stored out-of-process, restarts of the application process do not result in the loss of player sessions or match states.
Sources: AGENTS.md:231-233, README.md:52-54
Summary
The Valkey-based infrastructure in Athena is the backbone of the server's real-time capabilities. By centralizing sessions, presence, and packet queues in Valkey, Athena achieves a stateless application tier that is ready for horizontal scaling while maintaining the low latency required for a bancho-compatible experience.
Sources: README.md:15-18, AGENTS.md:231-233