trex-core/docs/srs/Integration/req-050_direct-broadcast-exchanges-and-binding.md

req-050: trex.direct(topic) + trex.broadcast(fanout) exchange + 바인딩

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

Intent

인스턴스 지정 라우팅과 전역 브로드캐스트를 위해 두 exchange 를 도입한다. trex.direct(topic)는 strategy/운영자가 특정 인스턴스에만 메시지를 보낼 때 routing key {instance_key}.{channel_type} 으로 라우팅하고, trex.broadcast(fanout)는 global kill-switch 등 전체 인스턴스 대상 제어를 모든 control 큐에 동시 전달한다(dcy-009 FR-3, FR-4). routing key 계약을 인터페이스로 정의한다.

Requirement

• topology.py 에 DIRECT_EXCHANGE = "trex.direct"(type topic, durable), BROADCAST_EXCHANGE = "trex.broadcast"(type fanout, durable) 상수와 routing key 빌더(direct_routing_key(instance_key, channel_type) → {instance_key}.{channel_type})를 추가한다.
• declare_topology(instance_key) 가 두 exchange 를 선언하고, 각 인스턴스의 intent/control/snapshot 큐를 trex.direct 에 routing key {instance_key}.intent/.control/.snapshot 으로 바인딩한다(FR-3).
• 각 인스턴스의 control 큐를 trex.broadcast(fanout)에 추가 바인딩(dual binding)한다(FR-4). 전역 제어 메시지는 trex.broadcast 로 publish 하면 모든 인스턴스 control 큐에 전달된다.
• default 인스턴스 하위호환: default 의 큐(리터럴명, REQ-049)도 동일 규칙으로 trex.direct(default.intent 등) + control dual binding 된다. 기존 직접 큐 publish 경로(reply-to RPC)는 유지되어 회귀가 없어야 한다(FR-5).
• routing key 계약은 docs/interface-contract.md 에 명시한다(REQ-051): directed = {instance_key}.{channel_type}, broadcast = fanout(키 무시).

Acceptance Criteria

1. Given declare_topology("inst-1"), When 선언, Then trex.direct(topic) + trex.broadcast(fanout) exchange 가 durable 로 선언된다.
2. Given declare_topology("inst-1"), When 바인딩 확인, Then trex.intent.req.inst-1/...control.../...snapshot... 가 trex.direct 에 routing key inst-1.intent/inst-1.control/inst-1.snapshot 으로 바인딩된다(FR-3).
3. Given direct_routing_key("inst-1","control"), When 호출, Then "inst-1.control" 을 반환한다.
4. Given inst-1/inst-2 두 인스턴스 큐가 선언됨, When trex.direct 에 inst-1.intent 로 publish, Then trex.intent.req.inst-1 에만 전달되고 ...inst-2 에는 전달되지 않는다(S-2).
5. Given control 큐 dual binding, When trex.broadcast 에 publish, Then trex.control.req.inst-1 과 ...inst-2 control 큐 모두에 전달된다(FR-4, S-3).
6. Given instance_key="default", When 전체 회귀, Then 기존 RPC(reply-to) 경로 동작 동일·회귀 없음(FR-5).

Impacted Area

• Docs:
  • docs/interface-contract.md — routing key 계약({instance_key}.{channel_type}, broadcast) (REQ-051 처리)
  • docs/runtime-flows.md — directed vs broadcast 라우팅 흐름 (REQ-051 처리)
• Modules:
  • trex_core/adapters/messaging/topology.py — DIRECT/BROADCAST exchange + routing key 빌더
  • trex_core/adapters/messaging/rabbitmq.py — exchange 선언 + 큐 바인딩(direct per-instance + control dual) + broadcast publish 경로
• Tests:
  • tests/adapters/messaging/ — exchange 선언 + 바인딩 + directed 라우팅 격리 + broadcast 전달(인프라 게이트)

Notes

• R-3(broadcast 중복 처리): kill-switch/pause 핸들러는 idempotent(REQ-036 패턴/advisory lock)라 중복 전달 무해.
• strategy 모듈(orb-v1) publish 코드 변경은 Out of Scope — 본 REQ 는 exchange/binding/routing key 계약만 정의(CONFIRM_STRATEGY_MODULE_OUT_OF_SCOPE).
• broadcast publish helper 는 transport 에 추가하거나 기존 publish 경로 재사용 — 구현에서 결정.

Change Log

CHG-20260607-01

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

Change Summary

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

Intent

• trex.direct/trex.broadcast exchange + 바인딩 + routing key 계약(FR-3/FR-4)을 Integration REQ 로 정규화.

Acceptance Criteria Delta

• Added: AC-1~6 전체

Impacted Area Delta

• Docs: interface-contract.md, runtime-flows.md (REQ-051)
• Modules: topology.py, rabbitmq.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-3/FR-4 와 일치. strategy publish 변경은 Out of Scope(계약만 정의) — blocker 아님.

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(routing key 단위 + 인프라 게이트: trex.direct/trex.broadcast 선언 + directed 라우팅 격리 S-2 + broadcast dual S-3, 301 passed)로 AC-1~6 충족.

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 배포 편성. strategy publish 변경은 별도(Out of Scope).