[Test] 다중 Worker Job Claim 정합성 검증

[Gimini-3]

목적

여러 Worker가 동시에 PENDING Embedding Job을 Claim해도 한 Job의 소유권이 정확히 한 번만 Commit되고, 대량 Queue가 중복과 누락 없이 완전히 소진되는지 실제 OpenSQL에서 검증합니다.

Closes #52

변경 내용

• claimConcurrencyTest 전용 Gradle Task 추가
  • claim-concurrency Tag만 실행
  • 일반 test와 build에서는 무거운 동시성 테스트 제외
• 실제 OpenSQL 기반 EmbeddingJobClaimConcurrencyIntegrationTest 추가
  • ACTIVE Worker 100개가 PENDING Job 하나를 동시에 Claim
  • ACTIVE Worker 20개가 PENDING Job 1,000개를 빈 Queue까지 반복 Claim
• Thread 준비와 시작 시점을 CountDownLatch로 제어
• Spring Transaction Proxy를 통과하는 실제 EmbeddingJobClaimService 호출
• 응답과 최종 DB의 Worker, Claim Token, Lease를 Job별로 비교
• Job별 LOCKED 이벤트 중복·누락 검증
• 제한 시간 공유, Executor 종료, Thread 오류 집계 추가
• 수동 DB 확인 시 테스트 스키마를 보존하는 명시적 환경 변수 제공
• Docker 준비부터 5회 반복, HTML/XML 리포트, SQL 검증, 오류 해결, 자원 정리까지 포함한 상세 가이드 작성

동시 실행 개념

• Task: Worker가 실행할 Claim 코드 단위
• Executor: Thread Pool을 관리하며 Task를 실행하는 관리자
• readyLatch: 모든 Task의 출발 준비 완료를 확인하는 카운터
• startLatch: 준비된 Task를 거의 동시에 출발시키는 시작 신호
• Claim: Job 처리 권한과 소유권을 현재 Worker에 기록하는 동작

Executor가 Task들을 실행
→ 각 Task가 readyLatch 감소
→ 각 Task가 startLatch 앞에서 대기
→ 모든 Task가 준비되면 startLatch 개방
→ 모든 Task가 거의 동시에 Claim 시도

시나리오 A — 단일 Job 경쟁

PENDING Job 1개
ACTIVE Worker 100개
Java Thread 100개
Hikari Connection Pool 20개

검증 결과:

Claim 성공 1
빈 결과 99
예외 0
LOCKED 이벤트 1
응답 Worker/Token/Lease = 최종 DB 소유권

시나리오 B — Queue 완전 소진

PENDING Job 1,000개
ACTIVE Worker 20개
Java Thread 20개
Hikari Connection Pool 20개

검증 결과:

성공 Claim 1,000
고유 Job ID 1,000
중복 Claim 0
누락 Job 0
최종 PENDING 0
최종 PROCESSING 1,000
불완전 소유권 0
LOCKED 이벤트 1,000
이벤트 중복·누락 Job 0
중복 Claim Token 0

동시성 경계

100개의 Java Worker 요청을 그대로 100개의 DB Connection으로 연결하지 않고 Hikari Pool을 20개로 제한했습니다. 실제 애플리케이션처럼 Connection Pool Backpressure가 있는 상태에서 요청 Burst가 소유권 정합성을 깨뜨리지 않는지 검증합니다.

Worker별 Claim 건수의 균등성이나 TPS·P95는 합격 기준이 아닙니다. SKIP LOCKED의 공정성과 성능 비교는 별도의 처리량·Lock 경합 성능 테스트 범위입니다.

실제 검증 환경

OpenSQL: PostgreSQL 14.6
pgvector: 0.8.0
Host: Apple Silicon arm64
Container: linux/amd64
Java: Temurin 17.0.18
Hikari Maximum Pool Size: 20

검증 결과:

• claimConcurrencyTest 최초 실행 통과
• claimConcurrencyTest 5회 연속 5/5 통과
• 스키마 보존 후 수동 SQL 검증 통과
  • PROCESSING 1,000
  • 불완전 소유권 0
  • LOCKED 이벤트 1,000
  • 이벤트 중복·누락 0
  • 중복 Token 0
• ./gradlew clean build 통과
  • 기존 테스트 199개
  • Failure 0
  • Error 0

실행 가이드

docs/test-results/gimin-#52-embedding-job-claim-concurrency.md에 다음 내용을 포함했습니다.

• Task, Executor, readyLatch, startLatch, Claim 개념
• OpenSQL Image 확인과 빌드
• 격리 컨테이너·전용 볼륨 생성 명령
• OpenSQL Ansible 초기화 대기 방법
• 대상 docgrid Database에 실제 SQL을 실행하는 준비 상태 확인
• 모든 환경 변수
• 두 시나리오 개별 실행 명령
• 전체 Task와 5회 반복 명령
• HTML/XML 리포트 위치
• 테스트 스키마 보존과 수동 SQL 검증
• Docker, 포트, pgvector, Hikari, Worker DEAD 오류 해결
• 테스트 컨테이너·볼륨·환경 변수 정리

시행착오 반영

첫 실행에서 Hikari connection-timeout을 60s 문자열로 설정해 ApplicationContext Binding이 실패했습니다. HikariDataSource의 해당 속성이 밀리초 long을 받는 것을 실제 Context에서 확인하고 60000으로 수정했습니다.

또한 OpenSQL 초기화 중 pg_isready는 docgrid Database 생성 전에도 Server 준비를 반환할 수 있어, 가이드에서는 실제 docgrid에 SELECT 1이 성공할 때까지 기다리도록 했습니다.

Production 영향

Production Service, Repository, Entity, Migration은 변경하지 않습니다. 테스트 Task, 통합 테스트, 재현 문서, 학습 기록만 추가합니다.

Summary by CodeRabbit

• 테스트

  • 다중 Worker 환경에서 임베딩 작업이 중복 없이 정확히 한 번만 선점되는지 검증하는 동시성 통합 테스트를 추가했습니다.
  • 단일 작업 및 1,000개 작업 시나리오에서 소유권, 잠금 이벤트, 누락 여부를 자동 검증합니다.
  • 기본 테스트와 동시성 테스트를 분리해 선택적으로 실행할 수 있습니다.

• 문서

  • 동시성 테스트의 실행 방법, 검증 기준, 환경 설정 및 문제 해결 절차를 문서화했습니다.
  • 테스트 결과와 주요 운영 관찰 사항을 기록했습니다.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 797545d5-03bf-4f3b-9be7-9277ae509523

📥 Commits

Reviewing files that changed from the base of the PR and between f68060d and b14b8d9.

📒 Files selected for processing (4)

• .dev/learnings/embedding-job-claim-concurrency-test.md
• build.gradle
• docs/design/gimin-#52-embedding-job-claim-concurrency.md
• src/test/java/com/opensource/docgrid/domain/embedding/integration/EmbeddingJobClaimConcurrencyIntegrationTest.java

---

📝 Walkthrough

Walkthrough

다중 Worker가 Embedding Job을 동시에 Claim하는 통합 테스트와 전용 Gradle 실행 태스크를 추가했습니다. 단일 Job 경쟁 및 1,000개 Job 소진 시 소유권, Lease, Token, 상태와 LOCKED 이벤트의 정합성을 OpenSQL에서 검증하며 실행·진단 절차도 문서화했습니다.

Changes

Embedding Job Claim 동시성 검증

Layer / File(s)	Summary
통합 테스트 기반과 데이터 계약 src/test/java/com/opensource/docgrid/domain/embedding/integration/EmbeddingJobClaimConcurrencyIntegrationTest.java	통합 테스트 태그, Spring 컨텍스트, 동적 Hikari 설정, 테스트 데이터 초기화와 Claim·Worker·소유권 결과 record를 구성합니다.
동시 실행과 테스트 데이터 구성 src/test/java/com/opensource/docgrid/domain/embedding/integration/EmbeddingJobClaimConcurrencyIntegrationTest.java	ready/start latch, 공유 데드라인, Executor 종료 제어와 DB 시딩을 통해 제한된 Connection Pool 환경에서 동시 Claim을 수행합니다.
Claim 시나리오와 소유권 검증 src/test/java/com/opensource/docgrid/domain/embedding/integration/EmbeddingJobClaimConcurrencyIntegrationTest.java	단일 Job에서 성공 1건과 빈 결과 99건을 검증하고, 1,000개 Job의 중복·누락 없는 소진 및 최종 상태·소유권·LOCKED 이벤트를 집계합니다.
전용 실행과 재현 절차 build.gradle, docs/design/gimin-#52-embedding-job-claim-concurrency.md, .dev/learnings/embedding-job-claim-concurrency-test.md	기본 테스트에서 태그를 제외하고 전용 claimConcurrencyTest 태스크를 추가했으며, OpenSQL 준비부터 실행·SQL 검증·실패 진단·정리 절차를 기록합니다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Test as EmbeddingJobClaimConcurrencyIntegrationTest
  participant Workers as Active Workers
  participant Service as EmbeddingJobClaimService
  participant DB as OpenSQL
  Test->>Workers: 동시 Claim 작업 시작
  Workers->>Service: PENDING Job Claim 요청
  Service->>DB: FOR UPDATE SKIP LOCKED 및 상태 저장
  DB-->>Service: Job 소유권과 LOCKED 이벤트 반환
  Service-->>Workers: Claim 결과 반환
  Test->>DB: 최종 상태·소유권·이벤트 검증

Loading

Possibly related PRs

• DocGrid/backend#49: PENDING Job Claim, Lease Lock, claim_token 구현을 이 통합 테스트가 검증 대상으로 사용합니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch test/52

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}