[Fix] Worker 종착 상태 전이 보호

[Gimini-3]

변경 사항

• Worker 정상 종료 UPDATE 대상을 ACTIVE, IDLE로 제한했습니다.
• WorkerNode.markStopped()와 markDead()가 종착 상태인 DEAD, STOPPED를 서로 덮어쓰지 않도록 방어했습니다.
• ACTIVE/IDLE → STOPPED/DEAD, DEAD → DEAD, STOPPED → STOPPED 상태 전이 테스트를 추가했습니다.
• Worker 생명주기 설계 문서와 동시성 학습 기록을 실제 조건에 맞게 수정했습니다.

원인

기존 정상 종료 조건은 status <> STOPPED였습니다. 따라서 이미 비정상 종료로 확정된 DEAD Worker에 뒤늦은 종료 요청이 오면 STOPPED로 변경되어 장애 상태가 정상 종료 상태로 덮어써질 수 있었습니다.

영향

• ACTIVE, IDLE Worker의 정상 종료는 기존처럼 STOPPED와 stopped_at을 기록합니다.
• DEAD Worker의 종료 요청과 STOPPED Worker의 반복 종료는 갱신 행 수 0을 반환하며 기존 상태와 시각을 보존합니다.
• 향후 Heartbeat 만료 확정에서도 STOPPED Worker를 DEAD로 덮어쓰지 않습니다.

검증

• Worker Entity·Service 및 비DB Worker 도메인 테스트 7개 클래스 통과
• compileJava, compileTestJava 통과
• WorkerNodeRepositoryTest는 테스트 코드 추가와 컴파일까지 확인했으나 로컬 PostgreSQL 연결 거부로 실행하지 못했습니다.

Closes #50

Summary by CodeRabbit

• 버그 수정

  • 워커 종료 처리와 하트비트가 동시에 발생해도 상태가 일관되게 유지됩니다.
  • 이미 DEAD 또는 STOPPED 상태인 워커가 정상 종료 요청으로 덮어써지지 않습니다.
  • 종료 시각이 불필요하게 변경되지 않도록 개선했습니다.
  • 활성 상태의 워커만 하트비트 및 상태 전환 대상이 됩니다.

• 테스트

  • 워커 상태 전환, 중복 종료 요청, 늦은 하트비트 상황에 대한 검증을 강화했습니다.

• 문서

  • 워커 생명주기와 상태 전이 규칙, 동시성 처리 기준을 보완했습니다.

[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: 079dfb06-6586-4693-8226-047aa4f37fb2

📥 Commits

Reviewing files that changed from the base of the PR and between 0796816 and 6980679.

📒 Files selected for processing (8)

• .dev/learnings/worker-heartbeat-stop-race.md
• docs/design/gimin-#39-worker-node-heartbeat.md
• src/main/java/com/opensource/docgrid/domain/worker/entity/WorkerNode.java
• src/main/java/com/opensource/docgrid/domain/worker/repository/WorkerNodeRepository.java
• src/main/java/com/opensource/docgrid/domain/worker/service/command/WorkerNodeCommandService.java
• src/test/java/com/opensource/docgrid/domain/worker/entity/WorkerNodeTest.java
• src/test/java/com/opensource/docgrid/domain/worker/repository/WorkerNodeRepositoryTest.java
• src/test/java/com/opensource/docgrid/domain/worker/service/command/WorkerNodeCommandServiceTest.java

---

📝 Walkthrough

Walkthrough

Worker의 상태 전이를 ACTIVE/IDLE에서만 수행하도록 Entity와 조건부 Repository UPDATE를 강화했다. Service는 허용 상태 목록을 전달하며, 테스트와 설계 문서는 DEAD·STOPPED 상태 보존 및 반복 종료 검증을 반영한다.

Changes

Worker 생명주기 상태 보호

Layer / File(s)	Summary
Entity 상태 전이 방어 src/main/java/com/opensource/docgrid/domain/worker/entity/WorkerNode.java, src/test/java/com/opensource/docgrid/domain/worker/entity/WorkerNodeTest.java, docs/design/...	isLive()를 기준으로 Heartbeat 갱신과 DEAD/STOPPED 전이를 ACTIVE 또는 IDLE 상태에서만 수행하고, 터미널 상태의 기존 값과 stoppedAt을 보존한다.
조건부 종료 갱신 연계 src/main/java/com/opensource/docgrid/domain/worker/repository/WorkerNodeRepository.java, src/main/java/com/opensource/docgrid/domain/worker/service/command/WorkerNodeCommandService.java, src/test/java/com/opensource/docgrid/domain/worker/{repository,service}/...	markStopped가 id, instance_id, ACTIVE/IDLE 상태를 만족하는 행만 갱신하도록 변경하고, Service와 테스트가 LIVE_STATUSES 및 갱신 row count를 반영한다.
경쟁 조건 검증 계약 .dev/learnings/worker-heartbeat-stop-race.md, docs/design/...	Heartbeat와 정상 종료 경쟁 시 STOPPED로 수렴하며, DEAD·STOPPED Worker의 반복 종료가 0건 갱신과 기존 종료 시각 보존으로 검증되도록 문서화했다.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

정상 종료 조건부 갱신 흐름

sequenceDiagram
  participant WorkerNodeCommandService
  participant WorkerNodeRepository
  participant Database
  WorkerNodeCommandService->>WorkerNodeRepository: markStopped with LIVE_STATUSES
  WorkerNodeRepository->>Database: Conditional UPDATE
  Database-->>WorkerNodeRepository: Affected row count
  WorkerNodeRepository-->>WorkerNodeCommandService: Success or failure

Loading

Possibly related PRs

• DocGrid/backend#40: Worker 등록·Heartbeat·정상 종료의 조건부 업데이트 설계와 동일 영역을 확장한다.
• DocGrid/backend#46: Heartbeat 경쟁 조건 설계를 WorkerNode와 markStopped 구현 및 테스트로 구체화한다.

✨ 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 fix/50

---

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.}