Files
clean-architecture-backend-…/src/adapter/inbound/websocket/AGENTS.md
T
DongHyeonka 08f932123a docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).

- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
  CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
  src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
  AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
  지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
  CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
  기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
  때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
  AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
  check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
  workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.

위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.

검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.

BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
2026-11-07 21:58:12 +09:00

8.1 KiB

adapter:inbound:websocket — 고를 때만 켜는 WebSocket·STOMP 경계

등록 정보

  • 모듈 ID: adapter-inbound-websocket
  • Gradle 경로: :adapter:inbound:websocket
  • 이 모듈만 시험: ./gradlew :adapter:inbound:websocket:test --console=plain
  • 실행 기준: Java 21. Spring Boot 버전은 src/gradle/libs.versions.toml이 정한다.
  • registry 정본: src/config/architecture/modules.json

패키지 루트: dev.caskeleton.adapter.inbound.websocket.

책임

이 leaf에는 서로 다른 범위 둘이 있고, 배포되는 기능 하나로 읽으면 안 된다.

  1. 골라 쓰는 STOMP·SockJS 채널 — stomp/**가 Spring 전송 설정, 타입 있는 app.websocket.* 설정, handshake principal·origin 검사, destination 정책, 정해진 클라이언트 안전 STOMP ERROR 대응, 할 수 있는 만큼만 하는(best-effort) 프로세스 안 이벤트 projection을 가진다.
  2. servlet handler 라이브러리 — servlet/, outbound/, budget/과 id record 둘 core/WebSocketConnectionId, protocol/WebSocketMessageId. 설정 키도 Spring 설정도 없다: 서비스 자신의 어댑터 leaf가 PlatformWebSocketHandler를 만들고 등록한다. README 「라이브러리 API」가 진입점과 배선을 적는다.

이 leaf는 command 중복을 걸러 내지 않고 저장소 SPI를 가지지 않는다. 예전 idempotency/ 패키지(command 원장, WebSocketActorReference, WebSocketEndpointName)는 2026-09-25에 지웠다. 많아야 한 번 돌아야 하는 command는 그 유스케이스 안에서 애플리케이션 IdempotencyExecutor를 거친다. 범위(scope)는 다시 연결해도 살아남는 값(endpoint + actor + 클라이언트 자신의 message id)이고, connection id가 아니다.

이 모듈은 출하하는 런타임 조립 둘 어디에도 없다. 등록되고 시험된다고 두 범위 중 어느 것도 켜지지 않는다.

허용

  • @DomainEvent 표지를 위한 :domain-core 등록 의존.
  • 저장소 BOM이 관리하는 Spring Boot WebSocket·validation starter.
  • 시험에서만: 내장 Tomcat·Jetty·SockJS·STOMP 클라이언트와 Testcontainers(Nginx lane).

금지

  • 어떤 adapter:outbound:* 모듈에든 직접 의존하기.
  • repository, Spring Data, 영속 엔티티, 업무 정책 접근.
  • @DomainEvent payload를 그대로 보내기, 리플렉션 기반 이벤트 직렬화.
  • 켜져 있을 때 wildcard·빈 handshake origin.
  • 익명 handshake, 아무 topic 구독, 클라이언트가 broker destination으로 보내기.
  • 이 골격 leaf 안의 운영 기능 @MessageMapping.
  • 모듈 안의 YAML 파일. 속성 값은 조립 루트가 가진다.
  • 이 leaf의 어떤 코드도 하지 않는 동작을 위한 설정 키·flag·catalog. handler가 강제하지 않는 한계는 WebSocketConnectionBudget의 필드가 아니다.
  • reactive(WebFlux) WebSocket 코드: 템플릿은 servlet만 쓴다.

타입 있는 설정 (app.websocket.*)

속성 트리 하나와 운영자 env 접두어 하나가 있다: app.websocket.* ↔ APP_WEBSOCKET_*. STOMP 채널만 설정한다. 기본 bootJar에는 이 leaf가 없으니, 이 값은 이 leaf를 채택한 조립에서만 뜻이 있다.

속성 env 기본값·역할
app.websocket.enabled APP_WEBSOCKET_ENABLED true. false이면 STOMP·SockJS 채널을 끈다
app.websocket.endpoint APP_WEBSOCKET_ENDPOINT /ws
app.websocket.allowed-origins APP_WEBSOCKET_ALLOWED_ORIGINS http://localhost:3000. 명시한 origin만
app.websocket.broadcast-destination APP_WEBSOCKET_BROADCAST_DESTINATION /topic/events
app.websocket.channel-queue-capacity APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY 10000. STOMP 채널마다(클라이언트 inbound, 클라이언트 outbound, broker) 거절하기 전에 쌓아 두는 메시지 수
app.websocket.message-size-limit APP_WEBSOCKET_MESSAGE_SIZE_LIMIT 64KB(Spring 기본값을 이제 명시한다)
app.websocket.send-buffer-size-limit APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT 512KB(Spring 기본값을 이제 명시한다)
app.websocket.send-time-limit APP_WEBSOCKET_SEND_TIME_LIMIT 10s(Spring 기본값을 이제 명시한다)
app.websocket.time-to-first-message APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE 60s(Spring 기본값을 이제 명시한다)
app.websocket.max-connections APP_WEBSOCKET_MAX_CONNECTIONS 1000. 노드마다 STOMP 세션 수. 그다음 것은 1013으로 닫는다

WebSocketSettings는 @Validated다. 켜진 상태의 잘못된 설정은 context 기동을 실패시킨다.

이 capability 채택하기

WebSocket은 기본 bootJar 안에 잠든 기능이 아니라 빌드 조립에서 고르는 것이다.

  1. 쓰는 조립의 의존성에 :adapter:inbound:websocket을 더하고 config/architecture/modules.json에 맞는 허용 edge를 더한다.
  2. 설정 등록은 capability 루트에 둔다. 출하하는 @ConfigurationPropertiesScan에 dev.caskeleton.adapter.inbound.websocket을 다시 더하지 않는다.
  3. STOMP·SockJS 채널은 이 leaf 자신의 AutoConfiguration.imports가 등록하고, leaf가 servlet classpath에 있으면 언제나 켜진다. wildcard가 아닌 origin 허용 목록을 정하고, 끄려면 app.websocket.enabled=false로 한다.
  4. handler 라이브러리는 README 「라이브러리 API」를 따른다. handler는 bean이어야 한다. 그래야 그 SmartLifecycle 멈춤(열린 모든 연결에 1001)이 web 서버가 멈추기 전에 돈다.
  5. 조립을 승격하기 전에 leaf lane과 저장소 conditional-transport 묶음을 돌린다: ./gradlew :adapter:inbound:websocket:test :adapter:inbound:websocket:systemTest :conditionalTransportQualification.

inbound 정책 (STOMP)

  • HTTP upgrade에는 이미 비어 있지 않은 Principal이 있어야 한다. 어댑터는 credential을 직접 인증하지 않는다.
  • STOMP SUBSCRIBE는 설정한 broadcast destination에만 허용한다.
  • 인증된 SEND는 /app/** 아래에만 허용한다.
  • 클라이언트가 /topic/**나 다른 destination으로 보내는 SEND는 거절한다.
  • 클라이언트에게 보이는 처리 실패는 모두 빈 payload와 정해진 message WEBSOCKET_REQUEST_REJECTED를 가진 ERROR frame이 된다. 그 error-code header는 cause chain에서 처음 나오는 ApiErrorCarrier가 실은 ApiErrorCode(IllegalArgumentException 뒤에 있어도), IllegalArgumentException이면 BAD_PARAMETER, 그 밖에는 WEBSOCKET_REQUEST_REJECTED다.

이벤트 projection 계약

나중의 기능이 정확히 하나의 @DomainEvent 클래스에 대해 LiveEventProjector<T> bean을 기여할 수 있다. broadcaster는 projector가 정확히 하나 맞을 때만 보낸다. projector가 없거나 둘 이상이거나, projection이 실패하거나, 이벤트 타입이 잘못됐거나, 필드가 null이거나, map이 한계를 넘으면 버린다. wire envelope에는 type, 한계 있는 문자열 fields, occurredAt만 있다. broker 채널은 자기 한계 있는 executor를 가지므로, simple broker가 구독자에게 퍼뜨리는 일은 도메인 이벤트를 발행한 스레드에서 돌지 않는다. broker queue가 차면 이벤트를 버린다(best-effort, R1).

템플릿에는 WebSocket 이벤트를 발행하거나 projector를 기여하는 기능이 없다.

증거와 한계

lane 증명하는 것
test STOMP 설정·정책, queue·writer·budget, handler 크기와 넘침 종료
systemTest 실제 Tomcat: STOMP 경계(WebSocketBoundaryQualificationTest), handler 런타임과 남용 계약, context를 닫으면 1001을 보냄
websocketJettyTest Jetty에서 handler 런타임 계약
websocketNginxTest 실제 Nginx 뒤의 upgrade·forwarding(Docker 필요. 없으면 실패한다)
websocketTransportQualificationTest STOMP 경계 시험을 건너뛰지 않고 실행

simple broker는 로컬·단일 프로세스·best-effort R1 증거일 뿐이다. broker relay, 여러 노드·durable 전달, 롤백에 안전한 발행, replay·resume은 주지 않는다.