Skip to content

feat(word): harden distributed single-flight with redisson and redis client unification#328

Merged
SolfE merged 7 commits into
developfrom
word-singleflight-distributed-hardening
May 20, 2026
Merged

feat(word): harden distributed single-flight with redisson and redis client unification#328
SolfE merged 7 commits into
developfrom
word-singleflight-distributed-hardening

Conversation

@SolfE
Copy link
Copy Markdown
Member

@SolfE SolfE commented May 20, 2026

Summary

word 동적 AI 생성 경로의 single-flight 중복 완화 구조를 추가/안정화하고, Redis 락 및 Redis 클라이언트 경로를 Redisson 중심으로 정리했습니다.

Problem

  • 멀티 인스턴스 환경에서 동일 단어 요청이 동시에 들어오면 AI 호출이 중복될 수 있음
  • follower 대기/leader 실패 처리 정책이 부족해 timeout/실패 전파가 불명확함
  • Lettuce/Redisson 혼용으로 Redis 경로가 분산되어 운영 복잡도가 높음

Solution

  • Redis 기반 single-flight coordinator를 도입해 leader/follower 흐름으로 중복 호출을 완화
  • leader 실패/대기 timeout을 명시적 예외로 분리해 WordService에서 처리
  • 락 경로를 Redisson으로 전환하고 Redis 공통 경로(Bucket4j 포함)를 Redisson+Jedis 기반으로 통일
  • single-flight 관련 TTL 기본값을 운영 관점에서 재조정

Changes

  • WordSingleFlightRedisCoordinator, WordSingleFlightProperties, timeout/failure 예외 추가
  • WordService에 single-flight 실행 및 예외 매핑 반영
  • RedisConfigRedissonClient 추가, JedisConnectionFactory 기반으로 정리
  • Bucket4jConfig를 Redisson CAS 기반 proxy manager로 전환
  • build.gradle에서 Lettuce 의존 제거 및 Redisson/Jedis 의존 정리
  • 단위/통합 테스트 추가 및 관련 테스트 코드 마이그레이션

Example

  • 동일 (word, targetLanguage, promptVersion, model, schemaVersion) 키 요청이 동시 유입되면
    • 1개 요청만 leader로 AI 호출 실행
    • 나머지는 follower로 결과 key 또는 pub/sub done 신호를 대기 후 동일 결과를 재사용

Related Issues

  • 미정

SolfE added 7 commits May 9, 2026 01:20
- introduce Redis lock + result key + Pub/Sub coordinator

- apply dedup to word lookup/create flows

- keep admin force reanalyze as fresh AI call

- add configurable single-flight properties
- verify concurrent dedup and leader failure propagation

- verify real redis cross-coordinator dedup behavior
- add dedicated timeout exception for single-flight wait

- map timeout to WORD_ANALYSIS_TIMEOUT without invalid cache write

- add regression test for timeout handling
…lures

- map leader replay failures to temporary analysis timeout

- skip invalid-word cache increment for replayed transient failures

- normalize dedup key casing with Locale.ROOT
@SolfE SolfE merged commit e399ec2 into develop May 20, 2026
1 check passed
@SolfE SolfE deleted the word-singleflight-distributed-hardening branch May 20, 2026 12:57
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 04dafa282d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/main/java/com/linglevel/api/word/service/WordService.java
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant