107 lines
5.3 KiB
Markdown
107 lines
5.3 KiB
Markdown
# ADR-007: Redis Usage (Where, When, and How) + Admin Configuration Capabilities
|
||
|
||
**Status:** Proposed
|
||
**Date:** 2026-08-02
|
||
**Author:** AI Assistant (following AGENTS.md and previous ADRs)
|
||
**Related ADRs:** [ADR-001](./ADR-001.md), [ADR-003](./ADR-003-tech-stack.md), [ADR-005](./ADR-005-admin-moderation-analytics.md), [ADR-006](./ADR-006-data-storage.md)
|
||
|
||
## Context
|
||
|
||
Redis is planned for several real-time and transient use cases in the chat and playout services. ADR-005 and ADR-006 require that the admin interface be able to view Redis statistics and adjust configuration values (rate limits, TTLs, presence expiry, etc.) with full audit logging.
|
||
|
||
We must explicitly document:
|
||
|
||
- Exact use cases for Redis.
|
||
- Configuration policies (TTL, persistence, high availability).
|
||
- Graceful degradation if Redis is unavailable.
|
||
- Admin interface capabilities to inspect and modify Redis settings.
|
||
|
||
## Decision Drivers
|
||
|
||
1. **Performance** – Redis is ideal for presence, rate limiting, and pub/sub.
|
||
2. **Simplicity** – Use a single Redis instance initially; document scaling path.
|
||
3. **Observability** – Admin UI must provide real-time visibility and configuration controls.
|
||
4. **Reliability** – Define fallback behavior (e.g., disable rate limiting if Redis is down).
|
||
5. **Auditability** – All configuration changes made via admin UI must be logged.
|
||
|
||
## Decision
|
||
|
||
**Use Redis 7+** as the primary in-memory store with the following defined use cases:
|
||
|
||
**Defined Use Cases**:
|
||
|
||
- **Presence**: Track online users per room (SET with TTL).
|
||
- **Rate Limiting**: Per-user and per-IP rate limits using Redis INCR + EXPIRE.
|
||
- **Pub/Sub**: Broadcast chat messages and moderation events to connected WebSocket clients.
|
||
- **Cache**: Short-lived cache for playout status and "now playing" metadata (from ADR-001).
|
||
- **Session Data**: Temporary admin session tokens (if not using JWT).
|
||
|
||
**Configuration Policies**:
|
||
|
||
- Default TTL for presence: 60 seconds (refreshed on activity).
|
||
- Rate limit windows: 10 requests per 10 seconds per user (configurable via admin UI).
|
||
- Persistence: RDB snapshots every 15 minutes + AOF for safety.
|
||
- High Availability: Start with single instance; add Sentinel or Cluster in v2.
|
||
- Fallback: If Redis is unavailable, disable real-time presence and rate limiting but continue basic chat functionality (with warning in logs and admin UI).
|
||
|
||
**Admin Interface Capabilities** (extension of ADR-005):
|
||
|
||
- Dedicated "Redis Configuration" tab in the admin dashboard.
|
||
- View real-time stats: memory usage, connected clients, key counts, hit/miss ratio, slow log.
|
||
- Adjustable parameters: rate limit thresholds, presence TTL, cache TTL, pub/sub channel prefixes.
|
||
- Actions: Flush specific keys/patterns, trigger save, view slow log, test connectivity.
|
||
- All changes are audited to the moderation log (with before/after values) and require confirmation.
|
||
|
||
**Folder Placement** (per ADR-002):
|
||
|
||
- Redis client wrapper in `backend/shared/redis/`.
|
||
- Admin UI components in `frontend/admin/system/redis/`.
|
||
- Configuration defaults in `backend/shared/config/redis.go`.
|
||
|
||
## Rationale
|
||
|
||
- Redis is the standard choice for the real-time features required by the chat system (ADR-001).
|
||
- Explicit documentation of use cases and fallback behavior prevents misuse.
|
||
- Admin interface capabilities fulfill the requirement from the TODO plan and ADR-005, giving operators full control without SSH access.
|
||
- Starting simple (single instance) aligns with ADR-003's operational simplicity goal while providing a clear scaling path.
|
||
|
||
## Consequences
|
||
|
||
**Positive**:
|
||
|
||
- Clear, auditable, and configurable Redis usage.
|
||
- Admin UI provides powerful observability and tuning without restarting services.
|
||
- Graceful degradation path defined.
|
||
|
||
**Negative / Risks**:
|
||
|
||
- Redis becomes a single point of failure for presence and rate limiting (mitigated by fallback logic).
|
||
- Memory usage must be monitored (admin UI will surface this).
|
||
- Configuration changes via admin UI must be carefully validated to prevent accidental DoS or data loss.
|
||
|
||
**Alternatives Considered**:
|
||
|
||
- No Redis (use only PostgreSQL) – rejected for performance on real-time features.
|
||
- Dragonfly or KeyDB – rejected to stay with mature, well-supported Redis.
|
||
- In-memory Go maps only – rejected for lack of persistence and cross-process sharing.
|
||
|
||
## Implementation Plan
|
||
|
||
1. Create this ADR-007 (done).
|
||
2. Implement Redis client wrapper with configuration reload support.
|
||
3. Build the admin UI tab for Redis stats and configuration (linked to ADR-005).
|
||
4. Add fallback logic in chat and playout services when Redis is unavailable.
|
||
5. Update `docker-compose.yml` to include Redis with persistence.
|
||
6. Add monitoring (Prometheus exporter) and admin audit logging for configuration changes.
|
||
7. Write tests for rate limiting, presence, and admin configuration flows.
|
||
|
||
## References
|
||
|
||
- ADR-001: Chat features requiring presence, rate limiting, and pub/sub.
|
||
- ADR-003: Go preference and operational simplicity.
|
||
- ADR-005: Admin interface foundation – this ADR extends it with Redis and storage configuration capabilities.
|
||
- ADR-006: Data storage decision (Redis complements the primary SQL store).
|
||
- arc42 documentation: Cross-cutting Concepts (caching, monitoring, security) and Deployment View.
|
||
|
||
This completes the documentation for data storage and caching decisions. All admin capabilities are now traceable before implementation begins.
|