# 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 배포 편성.