Files
clean-architecture-backend-…/docs/adr/ADR-WS-003-stomp-and-broker-relay.md
T
DongHyeonka 59dff0041c ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +09:00

5.4 KiB
Raw Blame History

결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 대체됨
  • 작성일: 2026-08-25
  • 요약: STOMP를 목적지 목록이 있는 고급 어댑터로 둔다는 결정이다. 그 고급 STOMP는 2026-09-25에 지웠다.
  • 현재 정본: src/adapter/inbound/websocket/README.md
  • 대체됨: docs/capability-status.md

ADR-WS-003: STOMP는 destination catalog를 선언한 Advanced 어댑터다

  • 상태: 대체됨 2026-09-25 — advanced.stomp와 advanced.stomp.rabbit을 지웠다. stomp 패키지가 유일한 STOMP 채널이다 (docs/capability-status.md를 본다).
  • 날짜: 2026-08-25
  • 범위: adapter:inbound:websocket — advanced.stomp, advanced.stomp.rabbit

배경

Advanced Task 9–13은 플랫폼 자신의 프로토콜 옆에 STOMP 1.2를 더하고, RabbitMQ broker relay와 노드를 가로지르는 user destination도 더한다.

이 leaf는 이미 더 오래된 STOMP-over-SockJS 채널(stomp, app.websocket.enabled로 막는다)을 싣는다. 한 context 안의 @EnableWebSocketMessageBroker 설정 둘은 시끄럽게 충돌하지 않는다 — 둘 다 configurer를 기여하고, 둘 다 configureMessageBroker를 부르며, 결과 broker는 마지막에 돈 쪽의 것이다. 오류도 로그도 없다.

STOMP는 client에게서 오는 자유 문자열인 destination 모델도 가져온다. catalog가 없으면 닿을 수 있는 destination 집합은 broker가 받는 모든 것이고, simple broker에게 그것은 모든 문자열이다.

결정

Advanced 어댑터는 advanced와 따로 둔 자기 모듈(advanced-stomp)이다. 순수할 수 없는 유일한 Advanced capability다 — 여기서 STOMP는 곧 Spring Messaging 타입이다 — 그리고 advanced에 접어 넣으면 그 모듈의 모든 capability에 대해 순수성을 느슨하게 만든다.

relay는 그다음 모듈(advanced-stomp-rabbit)이다. 어댑터는 프로토콜을 파싱한다. relay는 남의 broker에 TCP 연결을 열고 모든 전달을 그것에 기대게 만든다. 피해 범위가 다르고, 결정이 다르고, 모듈이 다르다.

destination은 operation마다 선언한다. StompDestinationCatalog는 (operation, destination)을 필요한 권한에 대응시킨다. 선언하지 않은 것은 거절한다. SUBSCRIBE와 SEND는 따로 선언한다. feed를 읽는 것과 거기에 게시하는 것은 다른 권리이기 때문이다.

인가 판정은 interceptor 메서드가 아니라 값이다. StompAuthorizationPolicy가 StompAuthorizationDecision을 돌려주고, StompSecurityInterceptor는 꺼내서 강제하기만 한다. MessageChannel을 거쳐서만 닿는 규칙은 누가 channel을 만들어 둔 경우만 시험된다.

STOMP runtime은 하나만 돌 수 있다. StompBrokerExclusivity는 두 채널이 모두 켜졌을 때, 두 broker가 모두 켜졌을 때, 또는 뒤에 broker 없이 어댑터가 켜졌을 때 context를 실패시킨다.

RECEIPT는 절대 커밋으로 올리지 않는다. StompEvidence에는 단계가 여섯 있고 StompAckPolicy.evidenceForReceipt()는 PROTOCOL_RECEIPT로 고정이다. receipt는 프로토콜 계층이 쓰고, 그 계층은 일이 성공했는지 아무것도 모른다.

simple broker는 할 수 없는 것을 선언한다. SimpleBrokerProfile은 cluster 지원이나 durable ack를 주장하며 만들 수 없고, local·test 밖에서 켜기를 거절한다 — 여러 노드 배포에서 그것은 오류를 내지 않고, 게시한 노드에 있는 사용자 일부에게만 전달한다.

풀리지 않은 user destination은 한 번 broadcast한 뒤 dead-letter로 보낸다. MultiNodeUserDestination은 broadcast를 거쳐 온 메시지와 그렇지 않은 메시지를 구별한다. 그렇지 않으면 모든 노드가 풀 수 없는 메시지를 받을 때마다 다시 broadcast한다.

결과

  • Advanced STOMP를 켜려면 옛 채널을 꺼야 한다. 둘을 함께 돌리는 옮기기 길은 없다. 배타성 검사가 그것을 새벽 3시가 아니라 기동 때 분명히 한다.
  • 배포는 자기 catalog를 써야 한다. 일부러 기본값이 없다: 빈 catalog는 모든 frame을 거절해서 고장 난 어댑터처럼 읽히고, 비어 있지 않은 기본 catalog는 아무도 고르지 않은 destination을 게시한다.
  • relay의 비용은 인증된 세션마다 broker 연결 하나 + 시스템 연결 하나다. brokerConnectionsFor는 첫 장애 전에 그것을 계산하려고 있다.
  • user destination metric은 destination이 아니라 UserDestinationAction으로 tag를 단다 — user destination은 구조상 사용자 식별자를 담는다.

따져 본 대안

  • 기존 stomp 패키지를 넓힌다. 버렸다: 그것은 Stable이고, WS-ARCH-6은 Stable 모듈이 Advanced 모듈 이름을 대는 것을 금지한다. 옛 채널을 profile로 움직이게 하려면 그 edge가 필요했다.
  • relay를 포함한 advanced-stomp 모듈 하나. 버렸다: relay는 따로 정할 운영 결정이고, 그것만 따로 거절할 수 있어야 한다.
  • wildcard 권한으로 선언하지 않은 destination을 허용한다. 버렸다: wildcard가 기본이 되고 catalog는 문서가 된다.