trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dc68e644d7ebf3d821e46e7d581921df77e45ae3
trex-core/docs/srs/Interface/req-049_instance-key-dynamic-queue-naming.md
T
genichinandClaude Opus 4.8 9f83c64a40 feat(multi-instance): dcy-009 BAT-013 — RabbitMQ 다중 인스턴스 토폴로지 (REQ-048~051) 
dcy-009(다중 인스턴스 RabbitMQ 토폴로지) 전체 SDLC: draft-req → confirm-req →
draft-batch(BAT-013) → run-batch-delivery → confirm-req-implemented.

- REQ-048 (Configuration): DaemonInstanceConfig.from_toml + DaemonConfig.from_config
  (env 병합, portfolio_hub_token 주입) + 데몬 --config 필수 argparse + .gitignore 인스턴스
  TOML + config/instance.example.toml
- REQ-049 (Interface): topology 동적 큐명 빌더 intent/snapshot/control_queue(instance_key)
  — default=리터럴 큐명(하위호환), named=`{base}.{instance_key}` + daemon per-instance 구독
- REQ-050 (Integration): trex.direct(topic)/trex.broadcast(fanout) exchange +
  declare_topology(instance_key) per-instance binding + control dual binding + direct_routing_key
- REQ-051 (Documentation): interface-contract/runtime-flows/project-structure 정합

하위호환: instance_key="default" → 기존 리터럴 큐명·RPC 경로 무회귀(FR-5).
split-brain 방지(NFR-3): 인스턴스 전용 큐. 민감값(NFR-4): TOML + gitignore.

검증: 신규 9 단위 + RabbitMQ 라우팅 2, 단위 271 passed,
인프라 게이트 301 passed(directed 격리 S-2 + broadcast dual S-3 + default 무회귀 S-4),
ruff clean. REQ-048~051 Implemented, BAT-013 release-candidate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-07 15:10:36 +09:00

5.7 KiB
Raw Blame History

req-049: instance_key 기반 동적 큐명 + default 하위호환

  • Status: Implemented
  • Type: Interface
  • Priority: High
  • Owner: project maintainers

Intent

다중 인스턴스가 동일 RabbitMQ 에서 경쟁 소비(round-robin)로 split-brain 을 일으키지 않도록, 수신 큐명을 instance_key 기반으로 인스턴스별 분리한다. topology.py 의 고정 큐명 상수를 동적 함수로 교체하고, declare_topology(instance_key) + 각 consumer 가 인스턴스 전용 큐를 구독하게 한다. instance_key="default" 는 기존 리터럴 큐명을 그대로 사용해 하위호환을 보장한다(dcy-009 FR-2, FR-5, NFR-1/2/3).

Requirement

  • topology.py 의 고정 큐명 상수(SNAPSHOT_REQ_QUEUE 등)를 동적 빌더 함수로 교체/보강한다: intent_queue(instance_key), snapshot_queue(instance_key), control_queue(instance_key).
    • 하위호환 규칙: instance_key in (None, "default") 이면 기존 리터럴 큐명(trex.intent.req / trex.snapshot.req / trex.control.req)을 반환한다. 그 외에는 {base}.{instance_key} 를 반환한다(FR-5: default 무회귀).
  • rabbitmq.py declare_topology(instance_key=...) 가 인스턴스 전용 큐를 선언한다. daemon.py 의 intent/snapshot/control consumer 가 동일 instance_key 의 전용 큐를 consume_rpc_forever 로 구독한다.
  • daemon.py 는 설정(REQ-048 TOML)에서 읽은 instance_key 를 큐 선언/구독에 일관되게 전달한다.
  • 기존 pika BlockingConnection per-thread 패턴을 유지한다 — 큐 분리로 인해 추가 스레드/커넥션을 만들지 않는다(NFR-2). 워커 스레드 수 불변.

Acceptance Criteria

  1. Given instance_key="inst-1", When intent_queue("inst-1")/snapshot_queue/control_queue, Then 각각 trex.intent.req.inst-1/trex.snapshot.req.inst-1/trex.control.req.inst-1 를 반환한다.
  2. Given instance_key="default"(또는 None), When 동일 빌더, Then 기존 리터럴 trex.intent.req/trex.snapshot.req/trex.control.req 를 반환한다(하위호환).
  3. Given declare_topology("inst-1"), When 선언, Then *.inst-1 인스턴스 전용 큐가 선언된다(S-1 일부).
  4. Given instance_key="default" 데몬, When 전체 pytest 스위트 실행, Then 회귀 없음(FR-5/NFR-1, 기존 큐명 테스트 통과).
  5. Given 데몬 기동, When 워커 스레드 확인, Then per-thread connection 패턴 유지 + 스레드 수 불변(NFR-2).
  6. Given instance_key="inst-1" 와 inst-2 동시 운영(전용 큐 분리), When 각자 큐만 소비, Then 한 인스턴스의 snapshot/intent 소비가 다른 인스턴스 큐에 영향을 주지 않는다(NFR-3 split-brain 방지 기반).

Impacted Area

  • Docs:
    • docs/runtime-flows.md, docs/project-structure.md — 동적 큐명/토폴로지 (REQ-051 처리)
  • Modules:
    • trex_core/adapters/messaging/topology.py — 동적 큐명 빌더(default 하위호환)
    • trex_core/adapters/messaging/rabbitmq.py — declare_topology(instance_key)
    • trex_core/runtime/daemon.py — consumer 가 instance_key 전용 큐 구독
  • Tests:
    • tests/adapters/messaging/ — 큐명 빌더(default vs named) + declare/consume 분리 + 기존 회귀

Notes

  • 하위호환 핵심: default = 리터럴 큐명(특수 처리)이라 기존 테스트/배포 무영향. FR-2 의 suffix 규칙은 named instance 에 적용.
  • NFR-3(split-brain 방지)는 인스턴스 전용 큐로 구조적으로 달성 — 다중 인스턴스 e2e 는 verification 에서 확인.
  • exchange/binding(트래픽 라우팅)은 REQ-050.

Change Log

CHG-20260607-01

  • Date: 2026-06-07
  • Author: Justin Ko

Change Summary

  • dcy-009(confirmed) → REQ-049 초안 생성.

Intent

  • instance_key 동적 큐명 + default 하위호환(FR-2/FR-5)을 Interface REQ 로 정규화.

Acceptance Criteria Delta

  • Added: AC-1~6 전체

Impacted Area Delta

  • Docs: runtime-flows.md, project-structure.md (REQ-051)
  • Modules: topology.py, rabbitmq.py, daemon.py
  • Tests: tests/adapters/messaging

Delivery Trace Delta

  • Batches: none (미할당)
  • Releases: none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: confirm-req 로 승인.

CHG-20260607-02

  • Date: 2026-06-07
  • Author: Justin Ko

Change Summary

  • Proposed → Approved (confirm-req).

Intent

  • 승인 게이트 통과: 필수 필드·구체 AC·Impacted Area·Change Log 완비. dcy-009(confirmed) FR-2/FR-5 와 일치. default 하위호환 규칙 명확.

Acceptance Criteria Delta

  • (변경 없음)

Impacted Area Delta

  • (변경 없음)

Delivery Trace Delta

  • Batches: none (미할당)
  • Releases: none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: suggest-batch-reqs / draft-batch 로 delivery 편성.

CHG-20260607-03

  • Date: 2026-06-07
  • Author: Justin Ko

Change Summary

  • Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-013 release-candidate).

Intent

  • BAT-013 verification 의 AC↔evidence(빌더 단위 named suffix/default 리터럴 + declare_topology(instance_key) + 전체 301 passed 로 default 무회귀)로 AC-1~6 충족. NFR-1/2/3 흡수.

Acceptance Criteria Delta

  • (변경 없음)

Impacted Area Delta

  • (변경 없음)

Delivery Trace Delta

  • Batches: BAT-013 (release-candidate)
  • Releases: none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current (Implemented)
  • Follow-up Action: draft-release 로 BAT-013 배포 편성.
Reference in New Issue View Git Blame Copy Permalink