[Feat] Worker 등록 및 Heartbeat 구현

[Gimini-3]

작업 내용

• 애플리케이션 시작 시 인덱싱 Worker 인스턴스를 등록합니다.
• 주기적으로 Heartbeat를 갱신하고 정상 종료 시 STOPPED 상태를 기록합니다.
• instance_id를 추가해 동일한 역할명의 여러 Worker 실행 인스턴스를 구분합니다.
• Heartbeat 만료 시간을 기준으로 조회 시 실질적인 DEAD 상태를 계산합니다.
• 관리자용 GET /admin/workers 조회 API를 추가합니다.
• Worker 생명주기, Repository 조건부 갱신, 관리자 API 테스트를 추가합니다.

설계 배경

Heartbeat와 종료 처리가 경쟁할 때 오래된 엔티티 저장으로 STOPPED 상태가 되돌아가지 않도록, Heartbeat는 ACTIVE 또는 IDLE 행의 시간 컬럼만 갱신하는 조건부 UPDATE를 사용합니다. Worker 기능은 기본적으로 비활성화하고 Worker 역할의 배포에서만 명시적으로 활성화합니다.

영향

• 신규 Flyway Migration: V31__add_worker_instance_id.sql
• 신규 설정: indexing.worker.enabled, name, heartbeat-interval, dead-threshold
• 신규 관리자 API: GET /admin/workers
• 후속 Job Claim과 Lease Lock에서 사용할 Worker 식별 기반을 제공합니다.

검증

• ./gradlew clean build
• OpenSQL 및 MinIO Compose 환경에서 전체 157개 테스트 통과
• git diff --check

Closes #39

Summary by CodeRabbit

• 새로운 기능

  • 워커가 시작·상태 갱신·정상 종료를 자동으로 기록합니다.
  • 관리자 전용 워커 목록 조회 기능을 추가했습니다.
  • 하트비트가 일정 시간 없으면 워커 상태를 DEAD로 표시합니다.
  • 여러 실행 인스턴스를 구분하고 호스트 정보를 제공합니다.

• 버그 수정

  • 종료된 워커가 늦은 하트비트로 다시 활성화되는 문제를 방지했습니다.

• 문서

  • 워커 등록, 하트비트, 종료 및 관리자 조회 설계를 문서화했습니다.

[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: 9d976b24-173d-4fa9-839f-20c12428c09d

📥 Commits

Reviewing files that changed from the base of the PR and between 3d0d08d and dac25db.

📒 Files selected for processing (24)

• .dev/learnings/worker-heartbeat-stop-race.md
• docs/gimin-#39-worker-node-heartbeat.md
• src/main/java/com/opensource/docgrid/domain/worker/config/IndexingWorkerProperties.java
• src/main/java/com/opensource/docgrid/domain/worker/config/WorkerConfig.java
• src/main/java/com/opensource/docgrid/domain/worker/config/WorkerSchedulingConfig.java
• src/main/java/com/opensource/docgrid/domain/worker/controller/WorkerAdminController.java
• src/main/java/com/opensource/docgrid/domain/worker/converter/WorkerNodeConverter.java
• src/main/java/com/opensource/docgrid/domain/worker/dto/response/WorkerNodeResponse.java
• src/main/java/com/opensource/docgrid/domain/worker/entity/WorkerNode.java
• src/main/java/com/opensource/docgrid/domain/worker/lifecycle/WorkerHeartbeatScheduler.java
• src/main/java/com/opensource/docgrid/domain/worker/lifecycle/WorkerLifecycleManager.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/main/java/com/opensource/docgrid/domain/worker/service/query/WorkerNodeQueryService.java
• src/main/resources/application.yml
• src/main/resources/db/migration/V31__add_worker_instance_id.sql
• src/test/java/com/opensource/docgrid/domain/worker/controller/WorkerAdminControllerTest.java
• src/test/java/com/opensource/docgrid/domain/worker/entity/WorkerNodeTest.java
• src/test/java/com/opensource/docgrid/domain/worker/fixture/WorkerNodeFixture.java
• src/test/java/com/opensource/docgrid/domain/worker/lifecycle/WorkerHeartbeatSchedulerTest.java
• src/test/java/com/opensource/docgrid/domain/worker/lifecycle/WorkerLifecycleManagerTest.java
• src/test/java/com/opensource/docgrid/domain/worker/repository/WorkerNodeRepositoryTest.java
• src/test/java/com/opensource/docgrid/domain/worker/service/command/WorkerNodeCommandServiceTest.java
• src/test/java/com/opensource/docgrid/domain/worker/service/query/WorkerNodeQueryServiceTest.java

---

📝 Walkthrough

Walkthrough

Worker 인스턴스 식별자와 상태 제약, 등록·Heartbeat·종료 생명주기, 만료 상태 계산, 관리자 조회 API 및 관련 테스트가 추가되었습니다.

Changes

Worker heartbeat feature

Layer / File(s)	Summary
Worker 계약 및 설정 docs/gimin-#39-worker-node-heartbeat.md, src/main/java/com/opensource/docgrid/domain/worker/config/*, src/main/java/com/opensource/docgrid/domain/worker/entity/WorkerNode.java, src/main/resources/db/migration/*	instance_id 유일성, 상태 제약, Worker 설정 검증, Heartbeat 및 effective status 판정 규칙이 정의되었습니다.
Worker 생명주기 및 Heartbeat 갱신 .dev/learnings/*, src/main/java/com/opensource/docgrid/domain/worker/lifecycle/*, src/main/java/com/opensource/docgrid/domain/worker/repository/*, src/main/java/com/opensource/docgrid/domain/worker/service/command/*, src/test/java/com/opensource/docgrid/domain/worker/{entity,fixture,lifecycle,repository,service/command}/*	애플리케이션 시작 시 등록하고, 주기적으로 조건부 Heartbeat을 수행하며, 종료 시 STOPPED로 갱신하는 흐름이 추가되었습니다.
관리자 Worker 조회 src/main/java/com/opensource/docgrid/domain/worker/controller/*, src/main/java/com/opensource/docgrid/domain/worker/converter/*, src/main/java/com/opensource/docgrid/domain/worker/dto/response/*, src/main/java/com/opensource/docgrid/domain/worker/service/query/*, src/test/java/com/opensource/docgrid/domain/worker/controller/*, src/test/java/com/opensource/docgrid/domain/worker/service/query/*	GET /admin/workers가 effective status와 Worker 정보를 반환하며, 관리자 권한 및 만료 Heartbeat 판정을 테스트합니다.

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

Sequence Diagram(s)

sequenceDiagram
  participant Application
  participant WorkerLifecycleManager
  participant WorkerNodeCommandService
  participant WorkerNodeRepository

  Application->>WorkerLifecycleManager: ApplicationReadyEvent
  WorkerLifecycleManager->>WorkerNodeCommandService: register(instanceId, host information)
  WorkerNodeCommandService->>WorkerNodeRepository: save ACTIVE worker
  Application->>WorkerLifecycleManager: ContextClosedEvent
  WorkerLifecycleManager->>WorkerNodeCommandService: stop(workerId, instanceId)
  WorkerNodeCommandService->>WorkerNodeRepository: markStopped STOPPED worker

Loading

Possibly related PRs

• DocGrid/backend#6: 기존 worker_nodes 저장 구조와 WorkerNode 기반 위에 이번 Worker 생명주기 및 instance_id 변경이 추가되었습니다.

Suggested labels: ✨ Feature

✨ 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 codex/39-worker-node-heartbeat

---

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