ADR-0007: Cache & Queue: Redis¶
Umbra 의 세션 저장, asynq 큐 백엔드, idempotency 체크를 단일 Redis 인스턴스로 제공한다. 호스팅은 Upstash.
Status¶
Accepted
- Decided at — 2026-04-13
- Decided by — Pablo
Context¶
Umbra 는 다음 용도의 저장소가 필요하다.
- 세션 저장소 — Discord OAuth2 세션, TTL 기반 만료
- 작업 큐 백엔드 — asynq 가 Redis 를 필수 요구
- Idempotency 체크 — Toss 웹훅 중복 처리 방지 (SET NX)
- 권한 캐시 — 라이선스 조회 결과 단기 캐싱 (TTL 60s)
후보: Redis (Upstash / Redis Cloud / self-hosted), Valkey, Memcached, PostgreSQL (LISTEN/NOTIFY + unlogged table).
Decision¶
Redis 를 채택한다. 호스팅은 Upstash Redis (Tokyo 리전).
단일 Redis 인스턴스가 위 4가지 용도를 모두 담당한다.
선택 근거:
- asynq 필수 의존성 — asynq 는 Redis 전용. 다른 큐 라이브러리로 교체하지 않는 한 Redis 가 필요
- Upstash pay-as-you-go — MVP 트래픽에 적합한 과금
- TLS 기본 제공 — 보안 설정 부담 ↓
- 여러 용도 통합 — 세션, 큐, idempotency 를 하나로 관리. MVP 인프라 복잡도 최소화
Consequences¶
Positive¶
- 단일 Redis 로 세션/큐/idempotency/캐시 모두 처리 → 인프라 단순
- Upstash 가 TLS, 백업, 리전 분산을 관리 → 운영 부담 0
- asynq 와 1급 통합
Negative¶
- 단일 장애 지점 (Redis 다운 시 세션, 큐, idempotency 모두 영향)
- Upstash pay-as-you-go 는 트래픽 급증 시 비용 예측 어려움 (Fixed plan 고려)
- 네트워크 latency (Fly.io nrt ↔ Upstash nrt 는 1~5ms)
Neutral¶
- 각 용도의 Key 네임스페이스 분리 (
session:*,asynq:*,idem:*,perm:*) - 중요 데이터는 Redis 에 저장하지 않음 (source of truth 는 항상 PostgreSQL)
Alternatives considered¶
Alternative 1: Valkey (Redis fork)¶
Pros
- Redis 와 호환 (OSS 라이선스 자유)
Cons
- Upstash 같은 관리형 서비스 생태계 미성숙
- Luxtra 팀이 차별점을 체감할 상황 없음
Why rejected — 현재 Redis 이점 그대로 쓰면 충분. Valkey 는 관리형 제공처가 성숙하면 재평가.
Alternative 2: Memcached¶
Pros
- 캐시 전용으로 빠름
Cons
- 작업 큐 기능 없음 → asynq 사용 불가
- Persistence 없음 → 세션 용도 부적합
Why rejected — Umbra 의 다수 용도를 커버 못함.
Alternative 3: PostgreSQL (LISTEN/NOTIFY + unlogged tables)¶
Pros
- 인프라 하나로 통합 가능
Cons
- asynq 가 PostgreSQL 백엔드 미지원 → River 로 교체 필요
- 세션 조회 성능은 Redis 대비 열세
- PostgreSQL 부하 집중
Why rejected — asynq 선택(ADR-0015)과 결합됨. River 전환 시 재평가 가능하나 MVP 에서 그 비용 부담이 큼.
Compliance¶
- Redis key 는 네임스페이스 prefix 로 분리 (
session:{id},asynq:queues:...,idem:webhook:{event_id},perm:guild:{id}) - TTL 을 적절히 설정 (세션 7일, idempotency 24시간, 권한 캐시 60초)
- 프로덕션 Redis URL 은 TLS 필수 (
rediss://) - 크리티컬 데이터는 Redis 에만 저장하지 않음 (항상 PostgreSQL 동시 기록)
Revisit triggers¶
- Redis 비용이 예산을 초과하면 Upstash Fixed plan 또는 self-hosted 전환 검토
- 단일 장애 지점이 SLA 를 위협하면 HA 구성 (Upstash Pro 또는 Redis Cluster)
- 용도가 많아져 key 수가 폭증하면 용도별 Redis 분리