trex-core/docs/discovery/dcy-009_20260607_multi-instance-rabbitmq-topology.md

0. 문서 상태

• 상태: confirmed
• 문서 ID: dcy-009_20260607_multi-instance-rabbitmq-topology
• 이슈명: 인스턴스별 독립 RabbitMQ 채널 토폴로지 — trex-core 다중 인스턴스 운영을 위한 Topic Exchange + Fanout Exchange per-instance 큐 분리
• 작성 시각(KST): 2026-06-07
• 마지막 갱신 시각(KST): 2026-06-07 (draft-req: REQ-048~051 생성)
• 대체됨: 없음
• 후속 Discovery 참조: 없음
• 생성된 REQ 참조: REQ-048, REQ-049, REQ-050, REQ-051

1. 계획 상태 요약

• 연계 문서 현황:
  • 관련 참조 파일: trex_core/adapters/messaging/topology.py, trex_core/adapters/messaging/rabbitmq.py, trex_core/runtime/daemon.py, trex_core/runtime/config.py, trex_core/application/watchdog.py
  • 관련 TODO/메모: dcy-006(RabbitMQ 도입, confirmed)에서 단일 인스턴스 기준 토폴로지 설계 완료. 다중 인스턴스 시 split-brain 문제와 per-instance 설정 파일 관리는 dcy-006 범위 밖이었음.
• 해석:
  • trex-core는 현재 고정 큐명과 단일 .env 기반 설정으로 운영되며, 다중 인스턴스를 동일 RabbitMQ에 연결하면 경쟁 소비로 인해 WatchdogStore split-brain·SafetySellService 중복 발동·이벤트 중복 발행 문제가 발생한다.
  • 이번 Discovery는 인스턴스별 TOML 설정 파일(instance_key, portfolio_hub_token 포함)을 도입하고, instance_key 기반 큐명 suffix화 + trex.direct(topic) + trex.broadcast(fanout) exchange 도입으로 인스턴스별 독립 채널을 확보하는 것을 목표로 한다.

2. 요구사항 판정 결과

• 판정: 신규
• 근거
  • dcy-006(RabbitMQ 도입)은 단일 인스턴스 기준 초기 큐/exchange 설계를 다뤘으며 이미 confirmed + delivered 상태다. 다중 인스턴스 토폴로지와 per-instance TOML 설정 파일은 dcy-006의 연장이 아닌 별도 인프라 변경 주제다.
  • 현재 어떤 Discovery/REQ도 instance_key, per-instance TOML 설정 파일, Topic exchange 기반 directed routing, Fanout exchange 기반 broadcast를 다루지 않는다.

3. 문제점의 요약

• 현재 상태
  • trex_core/adapters/messaging/topology.py: 모든 큐명이 리터럴 상수(SNAPSHOT_REQ_QUEUE = "trex.snapshot.req" 등)로 하드코딩. 인스턴스 suffix 없음.
  • trex_core/adapters/messaging/rabbitmq.py: declare_topology()가 고정 큐명으로 직접 큐를 선언한다. 제어 명령용 directed exchange나 broadcast exchange는 없다.
  • trex_core/runtime/daemon.py: "single-writer" 설계 명시. 3개 consumer 스레드(intent/snapshot/pause)가 고정 큐명을 구독. 인스턴스 식별자 개념 없음.
  • trex_core/runtime/config.py: DaemonConfig.from_env()가 모든 설정을 환경 변수에서 읽는다. TREX_PORTFOLIO_HUB_TOKEN을 포함한 민감값이 .env에 위치한다. per-instance 설정 파일 로더 없음.
  • trex_core/application/watchdog.py: WatchdogStore._store: dict[str, datetime] — 프로세스 내 in-memory 저장. 다중 인스턴스 간 공유 불가.
  • 문제: 다중 인스턴스를 동일 큐에 연결하면 RabbitMQ가 round-robin으로 메시지를 분배 → snapshot RPC를 받지 못한 인스턴스의 WatchdogStore가 갱신되지 않아 split-brain 발생 → 해당 인스턴스가 모든 슬롯을 watchdog 만료로 판정해 false safety-sell 발동 위험.
• 기대 상태
  • 각 인스턴스는 자신의 TOML 설정 파일을 가진다. instance_key와 portfolio_hub_token은 TOML에 기입하며 .env에 넣지 않는 것을 원칙으로 한다.
  • instance_key 기반 큐명 suffix(trex.intent.req.{instance_key})로 인스턴스별 독립 큐를 선언한다.
  • trex.direct(topic exchange) 도입: strategy 모듈이 특정 인스턴스에만 메시지를 전달할 때 routing key {instance_key}.{channel_type}으로 publish.
  • trex.broadcast(fanout exchange) 도입: 전역 제어 명령(global kill-switch 등)을 모든 인스턴스의 control 큐에 동시 전달.
• 이해관계자
  • 운영자(Justin Ko): 인스턴스별 TOML 설정 파일 관리 및 다중 포트폴리오 분산 운영 담당
  • 전략 모듈 개발자(orb-v1): routing key를 instance_key 기준으로 publish하도록 인터페이스 계약 변경 인지 필요
  • trex-core 데몬 운영자: --config {path}.toml CLI 인자로 인스턴스별 설정 파일 지정 + 큐 모니터링
• 제약사항
  • pika BlockingConnection은 thread-safe하지 않다 — 현재 consumer 스레드별 독립 Connection 패턴은 변경 없이 유지해야 한다.
  • 기존 durable 큐(trex.intent.req 등)가 이미 RabbitMQ 서버에 선언되어 있을 수 있다 → 새 큐명으로 전환 후 자연 소멸을 허용하며, RabbitMQ admin console에서 적절한 시점에 수동 삭제한다(OQ-1 Answered).
  • strategy 모듈(orb-v1)이 routing key 변경에 맞게 publish 코드를 업데이트해야 한다 — 인터페이스 계약 정의가 선행되어야 한다.
  • portfolio_hub_token과 instance_key는 .env에 넣지 않는다 — 기존 config.py의 from_env() 패턴 단독으로는 이 원칙을 지킬 수 없으므로 TOML 로더가 필수다.

주요 사용자 시나리오

• orb-v1 전략이 2개의 portfolio를 독립적으로 운영하려는 경우 — 인스턴스A(instance_key: inst-1)와 인스턴스B(instance_key: inst-2)를 각자의 TOML 파일로 구동해 WatchdogStore/SafetySellService 독립 동작을 보장한다.
• 전체 인스턴스에 global kill-switch를 발동하는 경우 — trex.broadcast exchange에 publish하면 모든 인스턴스의 control 큐에 동시 전달되어 인스턴스별 명시 없이 전역 제어가 가능하다.
• 단일 인스턴스 운영을 유지하면서 향후 다중 인스턴스로 전환하는 경우 — TOML 파일에 instance_key = "default"로 두고, 추후 인스턴스별 키를 달리해 큐를 분리한다.

4. 이번에 정의할 변경

• per-instance TOML 설정 파일 도입: 데몬 기동 시 --config <path>.toml CLI 인자로 인스턴스별 TOML 파일을 지정한다. 최소 필수 필드: instance_key(인스턴스 식별자), portfolio_hub_token(portfolio-hub 인증 토큰). 이 두 값은 .env에 넣지 않는 것을 원칙으로 한다. config.py에 DaemonInstanceConfig.from_toml(path) 로더를 추가하고, 기존 DaemonConfig.from_env()와 병합해 최종 설정을 구성한다.
• 큐명 동적화 및 instance_key 기반 suffix: topology.py의 고정 큐명 상수를 {base_name}.{instance_key} 형식의 동적 함수로 교체한다. daemon.py가 TOML에서 읽은 instance_key를 declare_topology(instance_key)에 전달한다.
• trex.direct(topic exchange) 도입 + per-instance 큐 바인딩: trex.direct exchange(type: topic, durable)를 신설하고, 각 인스턴스의 intent/control/snapshot 큐를 routing key {instance_key}.intent, {instance_key}.control, {instance_key}.snapshot으로 바인딩한다.
• trex.broadcast(fanout exchange) 도입 + control 큐 dual binding: trex.broadcast exchange(type: fanout, durable)를 신설하고, 각 인스턴스의 control 큐를 이 exchange에 추가 바인딩한다. global kill-switch 등 전체 인스턴스 대상 제어 명령은 이 exchange에 publish한다.
• baseline 문서 갱신: docs/runtime-flows.md와 docs/project-structure.md에 multi-instance topology 구조와 TOML 기반 기동 흐름을 반영한다.

영향 범위

• 코드 영향:
  • trex_core/runtime/config.py: DaemonInstanceConfig dataclass 추가(instance_key, portfolio_hub_token). from_toml(path) 로더 추가. 기존 DaemonConfig.from_env()는 유지하되, TOML 로더와 병합하는 from_config(toml_path) 팩토리 추가.
  • trex_core/adapters/messaging/topology.py: 고정 큐명 상수 → 동적 함수(intent_queue(instance_key) 등). DIRECT_EXCHANGE, BROADCAST_EXCHANGE 상수 추가.
  • trex_core/adapters/messaging/rabbitmq.py: declare_topology(instance_key) signature 변경. topic/fanout exchange 선언 + per-instance 큐 바인딩 로직 추가.
  • trex_core/runtime/daemon.py: --config CLI 인자 파싱. TOML에서 instance_key 읽기. 큐 선언/구독 시 instance_key 전달.
  • 진입점(trex_core/__main__.py 또는 동등): --config <path> CLI 인자 추가.
• 문서 영향:
  • docs/runtime-flows.md: multi-instance topology 흐름 추가(directed vs broadcast 분기), TOML 기반 기동 절차 반영
  • docs/project-structure.md: topology.py 역할 변경(동적 큐명 빌더), 설정 파일 계층 반영
  • docs/interface-contract.md: routing key 계약 갱신 — {instance_key}.{channel_type} 규칙 추가
• 운영 영향:
  • 인스턴스별 TOML 파일 생성 및 관리 필요(instance_key, portfolio_hub_token 포함)
  • 기존 trex.intent.req 등 old 큐는 새 큐 전환 후 자연 소멸을 허용한다. RabbitMQ admin console에서 적절한 시점에 수동 삭제(OQ-1 Answered).
  • TREX_PORTFOLIO_HUB_TOKEN env var는 TOML로 이관 후 .env에서 제거 필요

5. 요구사항 목록

기능 요구사항

• FR-1: 데몬 기동 시 --config <path>.toml CLI 인자는 필수다. 인자 없이 기동하면 오류 메시지를 출력하고 즉시 종료한다. TOML 파일에서 최소 instance_key와 portfolio_hub_token을 읽는다. 이 두 값은 .env에서 읽지 않는다.
• FR-2: instance_key 값을 기반으로 모든 수신 큐명을 {base}.{instance_key} 형식으로 suffix화한다.
• FR-3: trex.direct(type: topic, durable) exchange를 선언하고, 각 인스턴스의 intent/control/snapshot 큐를 routing key {instance_key}.intent, {instance_key}.control, {instance_key}.snapshot으로 바인딩한다.
• FR-4: trex.broadcast(type: fanout, durable) exchange를 선언하고, 각 인스턴스의 control 큐를 이 exchange에 추가 바인딩(dual binding)한다. 전체 인스턴스 대상 제어 명령은 이 exchange에 publish한다.
• FR-5: instance_key = "default" 단일 인스턴스 운영 시 기존 intent/snapshot/control RPC 경로와 동작이 동일하게 유지된다(하위 호환 검증 기준: 기존 테스트 스위트 회귀 없음).
• FR-6: docs/runtime-flows.md와 docs/project-structure.md를 multi-instance topology 및 TOML 기반 기동 기준으로 갱신한다.

비기능 요구사항

• NFR-1: instance_key = "default" TOML로 배포된 환경에서 토폴로지 변경 후 재시작 시 동작 회귀가 없어야 한다(pytest 전체 통과 기준).
• NFR-2: 기존 pika BlockingConnection per-thread 패턴을 유지한다. exchange 바인딩 추가로 인해 추가 스레드 또는 커넥션을 생성하지 않는다.
• NFR-3: 인스턴스별 독립 큐 사용 시 WatchdogStore, SafetySellService가 자신의 인스턴스 슬롯만 처리하므로 split-brain이 발생하지 않는다(다중 인스턴스 e2e 시나리오 통과).
• NFR-4: portfolio_hub_token과 instance_key가 코드/env/로그에 평문으로 노출되지 않는다. TOML 파일은 git에 커밋하지 않는다(.gitignore 추가).

범위 경계

• In Scope
  • per-instance TOML 설정 파일 로더(instance_key, portfolio_hub_token)
  • instance_key 기반 큐명 suffix화
  • trex.direct(topic exchange) 신설 + per-instance 큐 바인딩
  • trex.broadcast(fanout exchange) 신설 + control 큐 dual binding
  • daemon.py/topology.py/rabbitmq.py/config.py/진입점 변경
  • 인터페이스 계약(docs/interface-contract.md) routing key 규칙 추가
  • docs/runtime-flows.md, docs/project-structure.md 갱신
  • .gitignore에 *.toml 또는 config/*.toml 추가(인스턴스 설정 파일 git 제외)
• Out of Scope
  • 전체 설정을 TOML로 일원화(KIS 자격증명 등 나머지 env var의 TOML 이관 — 별도 논의)
  • strategy 모듈(orb-v1) 코드 변경 — 인터페이스 계약만 정의, 구현은 strategy 모듈 범위
  • WatchdogStore Redis 외부화 — competing consumer 방식(별도 Discovery)
  • active-passive failover / leader election
  • 기존 old 큐 자동 삭제 스크립트 — 운영 절차로 처리
  • 인스턴스↔portfolio 매핑 레지스트리 (trex-core 내부 DB 불필요)

6. 리스크/가정 목록

리스크

• R-1 (Medium): strategy 모듈이 routing key를 변경하지 않으면 다중 인스턴스 환경에서 메시지가 올바른 인스턴스에 도달하지 않는다.
  • 완화 방안: 인터페이스 계약에 routing key 규칙을 명시한다. instance_key = "default" 단일 인스턴스 시에는 routing key default.intent 등으로 publish하면 하위 호환 유지 가능.
• R-2 (Medium): 기존 durable 큐(trex.intent.req 등)가 RabbitMQ에 잔류하면 새 큐로 전환 후 old 큐에 consumer가 없어진다.
  • 완화 방안: 자연 소멸 허용. 배포 후 old 큐에 새로 publish되는 메시지가 없으므로 메시지 누적 없음. 적절한 시점에 RabbitMQ admin console에서 수동 삭제(OQ-1 Answered).
• R-3 (Low): trex.broadcast exchange 메시지가 모든 인스턴스에 동시 전달되므로 인스턴스별로 동일 제어 명령을 중복 처리한다.
  • 완화 방안: kill-switch/pause 핸들러에 idempotency 보장(REQ-036 패턴, DB advisory lock). 중복 처리는 무해하게 동작.
• R-4 (Low): TOML 설정 파일이 실수로 git에 커밋되면 portfolio_hub_token 등 민감값이 노출된다.
  • 완화 방안: .gitignore에 인스턴스 TOML 경로 추가(FR-1 범위). TOML 파일은 배포 전용 경로에 위치시킨다.

가정

• A-1: 현재 배포 환경은 단일 인스턴스 운영이다. 다중 인스턴스 전환은 향후 필요 시점에 진행한다.
• A-2: strategy 모듈(orb-v1)은 인터페이스 계약 변경에 맞춰 routing key를 업데이트할 수 있다.
• A-3: 인스턴스별 담당 portfolio 매핑은 TOML 설정 또는 strategy 모듈의 routing 설정으로 관리한다. trex-core 내부에 레지스트리 DB를 두지 않는다.
• A-4: portfolio_hub_token과 instance_key를 .env에서 TOML로 이관하면 기존 .env 기반 배포 스크립트를 수정해야 한다. KIS 자격증명 등 나머지 env var는 이번 범위에서 이관하지 않는다.
• A-5: TOML 파일 경로는 --config CLI 인자로 지정한다. --config 인자는 필수이며, 지정하지 않으면 데몬이 오류 메시지를 출력하고 즉시 종료한다(OQ-2 Answered). 기본값 fallback은 제공하지 않는다.

오픈 질문

• OQ-1: 기존 durable 큐(trex.intent.req 등) 처리 방식 — 자연 소멸(수동 삭제) vs 배포 절차에 명시적 삭제 포함?
  • 상태: Answered
  • 결정: 자연 소멸 허용. 배포 후 old 큐에 새로 publish되는 메시지는 없으므로 메시지 누적 없음. RabbitMQ admin console에서 적절한 시점에 수동 삭제. 배포 절차에 명시적 삭제 단계를 추가하지 않는다.
  • 반영 위치: R-2 완화 방안
• OQ-2: --config 인자 없이 데몬 기동 시 동작 — 오류 종료(필수) vs instance_key = "default" 기본값으로 기동?
  • 상태: Answered
  • 결정: --config 필수. 인자 없이 기동 시 오류 메시지 출력 후 즉시 종료. 기본값 fallback 없음. 인스턴스 식별이 보장되지 않은 상태로 기동하는 것은 다중 인스턴스 환경에서 split-brain 위험을 내포하므로 명시적 실패가 안전하다.
  • 반영 위치: A-5, FR-1

오픈 질문 처리 기준

• Open: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
• Deferred: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.

7. 초기 성공 기준

• S-1: --config inst-1.toml(instance_key = "inst-1")으로 인스턴스 기동 시 trex.intent.req.inst-1, trex.snapshot.req.inst-1, trex.control.req.inst-1 큐가 RabbitMQ에 선언되고, trex.direct exchange에 올바른 routing key로 바인딩된다.
• S-2: instance_key = "inst-1"과 instance_key = "inst-2" 인스턴스를 동시 기동했을 때, inst-1 routing key로 publish된 메시지가 trex.intent.req.inst-1 큐에만 전달된다.
• S-3: trex.broadcast exchange에 publish된 제어 메시지가 trex.control.req.inst-1과 trex.control.req.inst-2 큐 모두에 전달된다.
• S-4: instance_key = "default" TOML로 기동 시 기존 pytest 스위트(단위 + 회귀) 전체 통과 — 동작 회귀 없음.
• S-5: portfolio_hub_token이 .env에 없고 TOML에서만 읽혀 PortfolioHubConfig.token에 올바르게 주입된다.

측정 방식 및 데이터 출처

• S-1 측정 방식: RabbitMQ Management API(GET /api/queues, GET /api/bindings) 또는 pika 큐 선언 성공 로그 / 데이터 출처: 통합 테스트 또는 manual e2e
• S-2 측정 방식: 두 인스턴스 기동 후 inst-1 routing key로 intent publish → trex.intent.req.inst-1 메시지 카운트 +1, trex.intent.req.inst-2 카운트 0 확인 / 데이터 출처: RabbitMQ Management API 또는 통합 테스트
• S-3 측정 방식: broadcast exchange에 publish → 두 인스턴스 control 큐 모두 메시지 카운트 +1 / 데이터 출처: 통합 테스트 또는 manual e2e
• S-4 측정 방식: pytest 전체 실행 → 0 failures / 데이터 출처: pytest 출력
• S-5 측정 방식: .env에 TREX_PORTFOLIO_HUB_TOKEN 미설정 상태에서 TOML로 기동 → PortfolioHubConfig.token 값 확인 / 데이터 출처: 단위 테스트(config loader)

8. REQ로 넘기기 전 확인 체크

• 범위(In Scope/Out of Scope) 확정
  • 기준: OQ-1(old 큐 처리) Answered, OQ-2(TOML 필수) Answered
• 성공 지표의 측정 방식/데이터 출처 확정
  • 기준: S-1S-5 각각 테스트 또는 e2e 근거 확정 — S-1S-5 측정 방식 및 데이터 출처 섹션 7에 전부 기입됨
• High 영향 리스크 우선순위 및 해소 책임자 지정
  • 기준: R-1~R-4 전부 Medium/Low — High 영향 리스크 없음. 모든 리스크에 완화 방안 기입됨. REQ 단계 인계 확정.
• 모든 오픈 질문(OQ) Open 상태 없음 확인
  • 기준: OQ-1, OQ-2 모두 Answered
• Freeze 확정 담당자(CONFIRMED_BY) 지정
  • 기준: Justin Ko 확인 — Section 11 Confirmed By: Justin Ko

9. 파일 처리 결과

• 처리 결과: 생성
• 생성 경로: docs/discovery/dcy-009_20260607_multi-instance-rabbitmq-topology.md
• 참조 문서:
  • trex_core/adapters/messaging/topology.py (고정 큐명 상수 현황 — 변경 대상)
  • trex_core/adapters/messaging/rabbitmq.py (declare_topology 현황 — 변경 대상)
  • trex_core/runtime/daemon.py (consumer thread 현황 — instance_key 추가 대상)
  • trex_core/runtime/config.py (DaemonConfig.from_env() — TOML 로더 추가 대상)
  • docs/discovery/dcy-006_20260605_strategy-module-rabbitmq-transport.md (원래 RabbitMQ 도입 Discovery — 참조 기준)
  • docs/runtime-flows.md (baseline 문서 — 갱신 대상, FR-6)
  • docs/project-structure.md (baseline 문서 — 갱신 대상, FR-6)

10. 사용자 결정 필요 항목 요약

CONFIRM

• CONFIRM_STRATEGY_MODULE_OUT_OF_SCOPE: 확인됨. strategy 모듈(orb-v1)의 routing key 구현 변경은 이번 Discovery 범위 밖. trex-core는 exchange·바인딩 계약만 정의하며, strategy 모듈의 publish 코드 변경은 별도 Discovery 또는 REQ에서 다룬다(Section 5 Out of Scope 반영).
• CONFIRM_ENV_RESIDUAL: 확인됨. KIS 자격증명(TREX_KIS_*), PostgreSQL DSN, TREX_RABBITMQ_URL 등 기존 env var는 이번 범위에서 .env 유지. TOML 이관 대상은 portfolio_hub_token과 instance_key만(Section 5 Out of Scope + A-4 반영).

DATA

• DATA_TOML_SCHEMA_FULL: REQ 단계 확정. 최소 필드: instance_key (string), portfolio_hub_token (string). 추가 필드는 REQ 단계 스키마 정의에서 확정한다.
• DATA_MULTI_INSTANCE_TRIGGER_TIMING: REQ/배포 단계 계측 항목. Discovery 단계 범위 밖. 실제 다중 인스턴스 운영 계획은 배포 시점 REQ에서 반영한다.

11. Discovery Freeze

섹션 참조

• 범위: # 5. 요구사항 목록 > 범위 경계
• 리스크/오픈 질문: # 6. 리스크/가정 목록
• 성공 기준: # 7. 초기 성공 기준
• 인계 전 확인: # 8. REQ로 넘기기 전 확인 체크
• 사용자 결정 필요: # 10. 사용자 결정 필요 항목 요약

Freeze 플래그

• Handoff Decision: REQ Drafting 진행 가능
• Handoff Rationale: TOML 설정 파일 도입 + instance_key 기반 토폴로지 설계 완료. OQ-1(old 큐 자연 소멸), OQ-2(TOML 필수) 모두 Answered. CONFIRM/DATA 항목은 REQ 단계에서 확정 가능 — confirm-discovery 후 REQ 초안 작성 진행 가능.
• Ready for REQ Drafting: true
• Confirmed By: Justin Ko
• Confirmed At (KST): 2026-06-07