trex-core/docs/batches/bat-047_20260619_event-publisher-connection-reliability/planning.md

BAT-047 Planning

• Status: confirmed
• Batch: BAT-047
• Profile: standard

Included REQ

• REQ-091: 이벤트 발행 재시도 + 강제 재연결 (idle 후 첫 발행 무유실)
• REQ-092: 발행 전용 연결 idle keepalive (서버 측 heartbeat 사망 예방)
• REQ-093: DLQ 가시성/경보 + emit 실패 경보 (trex.events.dlq 관측성)
• REQ-094: 이벤트 발행 신뢰성 baseline 문서 정합 (runtime-flows / project-structure / operations 갱신)

Delivery Plan

구현 순서는 의존성과 위험도 기준으로 아래와 같다.

1. REQ-092 keepalive 설계 확정(OQ-1): draft-batch-design에서 pika 스레드 소유 모델 기준으로 keepalive 실행 위치(별도 스레드 vs. execution-loop 틱) 결정. 이 결정이 REQ-092 구현 전제.

2. REQ-093 DLQ 가시성 방식 결정(OQ-3): draft-batch-design에서 dcy-029 로깅 자산 재사용 가능성 검토 후 메트릭/로그/소비자 중 택1. 이 결정이 REQ-093 DLQ 유입 관측 구현 전제.

3. REQ-093 NFR-2 타임아웃 수치 확정: design에서 단일 publish 경로 전체 블록 상한 수치 결정.

4. 구현(run-batch-implementation): 설계 결정 순서대로

   • Phase A: rabbitmq.py publish_event 재시도+강제 재연결(REQ-091) + _publish_dlq ERROR 로그(REQ-093)
   • Phase B: keepalive 구현(REQ-092) — OQ-1 결정 결과 적용
   • Phase C: daemon.py _make_event_emitter ERROR 경보 강화(REQ-093)
   • Phase D: 신규 테스트 작성 (half-open/재시도/keepalive/DLQ/emit ERROR AC 커버)

5. REQ-094 baseline 문서 정합: 구현 완료 후 runtime-flows.md, project-structure.md, operations.md 갱신.

선행 조건: REQ-091~093은 코드 범위가 분리되어 있어 병렬 구현 가능하나, keepalive(REQ-092)와 emit 경보(REQ-093)는 OQ-1/OQ-3 설계 결정이 전제여서 설계 완료 후 시작.

Dependencies

• Internal:
  • trex_core/adapters/messaging/rabbitmq.py — 변경 대상 핵심 파일 (BAT-007에서 도입됨)
  • trex_core/runtime/daemon.py — _make_event_emitter 변경 대상
  • tests/adapters/messaging/ — 기존 messaging 회귀 스위트(현재 537 passed) 전체 통과 유지 필수
  • tests/application/test_messaging_event_publisher.py — 기존 회귀 유지
  • dcy-029(BAT-045/046) — 구조화 로깅 인프라 자산(OQ-3 재사용 검토 대상)
• External:
  • pika BlockingConnection API(process_data_events, close, BlockingConnection) — 버전 고정 (pyproject.toml 기준)
  • RabbitMQ broker — 통합 테스트는 TREX_RABBITMQ_TEST_URL skip(CI 환경 없으면 skip, unit은 mock 기반)

Design Gate

• Design Required Before Implementation: yes
• Reason:
  • OQ-1(keepalive 실행 위치): pika 스레드 비안전성이 명시적 스레드 소유 모델 결정을 요구한다. 설계 없이 구현하면 다른 스레드에서 I/O 호출 시 연결 손상 리스크가 있다.
  • OQ-3(DLQ 가시성 방식): 메트릭/로그/소비자 데몬 중 선택이 구현 구조를 결정한다. 특히 소비자 데몬 방식이면 별도 스레드/모듈이 추가된다.
  • NFR-2(타임아웃 수치): execution-loop 블록 상한 수치가 코드에 상수로 박힌다. 설계에서 확정해야 AC-3 기준이 명확해진다.
  • architecture impact가 runtime-flows(keepalive 틱, 재시도 경로)이므로 standard profile design이 필요하다.

Milestones

1. draft-batch-design 완료 — OQ-1(keepalive 위치), OQ-3(DLQ 방식), NFR-2(타임아웃 수치) 확정
2. run-batch-implementation 완료 — 신규 테스트 포함, 기존 회귀 537 passed 유지
3. draft-batch-verification 완료 — AC별 커버 확인, baseline 문서 정합 확인
4. QC reviewer 검증 대기 (confirm-batch-verification은 팀장 게이트)

Risks

• R-1(High): M1 라이브 trex-core — wire 계약·consume/RPC 경로 회귀 시 orb(라이브)·tsl(M2)에 즉시 영향. 완화: 변경을 publish_event/_publish_dlq/_make_event_emitter 경로에 국소화. declare_topology/consume_rpc_forever/consume_events_forever/call_rpc 경로 불변. 기존 회귀 스위트 전체 통과 강제.
• R-2(Medium): pika 스레드 비안전성 — keepalive가 발행 전용 연결 소유 스레드 밖에서 실행되면 연결 손상. 완화: OQ-1을 design에서 확정, AC-2/AC-3(스레드 안전성) 테스트로 검증.
• R-3(Medium): 재시도 at-least-once — 중복 이벤트 발행 가능. 완화: OQ-2는 delivery 검증(소비자 orb/tsl 멱등성 확인)으로 추적. 전이 이벤트는 멱등 적용 가능 추정.
• R-4(Low): keepalive process_data_events(time_limit=0) 틱이 execution-loop와 같은 스레드에서 실행될 경우 루프 지연 유발 가능. 완화: NFR-2 타임아웃 수치를 design에서 확정, AC-4(블록 상한) 테스트로 검증.