Files
clean-architecture-backend-…/docs/adr/ADR-WS-002-resume-and-cluster.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

4.8 KiB

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

  • 상태: 대체됨
  • 작성일: 2026-08-25
  • 요약: resume·cluster 상태는 캐시로 다룬다는 결정이다. 그 기능은 2026-09-25에 지웠다.
  • 현재 정본: src/adapter/inbound/websocket/README.md
  • 대체됨: docs/capability-status.md

ADR-WS-002: resume와 cluster 상태는 cache이고, cache로 다룬다

  • 상태: 대체됨 2026-09-25 — advanced.resume, advanced.cluster, advanced.presence를 지웠다: 아무것도 그것을 조립하지 않았다(docs/capability-status.md를 본다).
  • 날짜: 2026-08-25
  • 범위: adapter:inbound:websocket — advanced.resume, advanced.cluster, advanced.presence

배경

Advanced Task 2–8은 모두 상태처럼 보이지만 상태가 아닌 것 셋을 더한다: client가 어디까지 왔는지 말하는 resume token, 어느 노드가 세션을 가졌는지 말하는 cluster index, 그 index에서 끌어낸 presence 요약.

하나하나가 과거에 대한 진술이다. resume token은 연결이 끊기기 전에 만들어졌다. index 항목은 그 뒤에 죽었을 수 있는 노드가 썼다. presence는 index를 읽은 것이고 그것의 틀린 점을 모두 물려받는다. 이 ADR이 막으려는 실패는 그중 어느 것이든 지금의 사실로 다루는 것이다. 부르는 자리에서는 하나같이 사실처럼 읽히기 때문이다.

결정

resume은 token이 주장하는 것이 아니라 replay 저장소가 실제로 가진 것으로 묶는다. ResumeCoordinator는 위치를 받아 주기 전에 ReplayAvailability를 묻는다. 저장소가 이미 버린 위치를 대는 token은 빈틈을 메운 stream이 아니라 다시 맞추기를 낸다. 대안 — token을 믿기 — 은 구멍 난 stream을 소리 없이 전달하고, client가 그것이 완전하다고 믿으므로 명시적 다시 맞추기보다 나쁘다.

cluster index 항목은 관찰 시각을 싣고, 읽을 때마다 그것과 대조한다. ExternalSessionSummary.staleAt은 「index가 edge-2라고 한다」를 「언제 기준으로」에 답하지 않고는 쓸 수 없게 하려고 있다. 보고를 멈춘 노드의 항목은 그 노드가 세션을 가졌다는 증거가 아니다.

durable fan-out의 중복은 message id가 아니라 stream 위치로 거른다. 계약이 at-least-once이므로 재전달은 보통 동작이다: 재배포, 느린 소비자, broker rebalance가 모두 그것을 낳는다. FanoutDeduplicator는 (stream, position)을 키로 쓰고 compute 아래에서 high-water mark를 올리므로, 소비자 스레드 둘이 같은 위치를 둘 다 전달할 수 없다.

presence에는 상태가 둘이 아니라 넷이다. OFFLINE은 보고된 사실이고, STALE은 사실이 없는 것이다. 둘을 합치면 Redis partition 동안 모든 사용자를 연결 끊김으로 알리는데, 실제로 일어난 일은 index가 어두워졌고 연결은 멀쩡한 것이다.

보안에 관련된 어떤 것도 presence에 기대면 안 된다. 노드가 보고를 멈추게 할 수 있는 공격자는 누가 있는지에 대한 플랫폼의 믿음을 움직일 수 있다. presence는 「초록 점을 보여 줄까」에 답한다.

결과

  • 받아 줄 수 없는 resume은 client에게 다시 맞추기로 보인다. client는 그것을 구현해야 한다. 플랫폼이 소리 없이 시늉하는 모드는 없다.
  • cluster index를 읽을 때마다 시계가 필요하다. 일부러 둔 마찰이다.
  • PresenceSummary.classify는 stale 창 이상인 idle 창을 거절한다. 그렇지 않으면 IDLE에 닿을 수 없고, 호출자는 상태 셋짜리를 가지고 넷짜리 모델이라고 믿는다.
  • fan-out envelope은 한계 있는 참조와 catalog로 인코딩한 문서를 싣고, 업무 객체는 싣지 않는다. rolling deploy에서는 코드 두 버전이 같은 envelope을 읽는다.

따져 본 대안

  • resume token을 믿는다. 버렸다: 빈틈을 완전한 stream과 구별할 수 없게 만든다.
  • message id로 중복을 거른다. 버렸다: 재전달하는 broker는 id를 다시 만들 수 있고, 재시도하는 producer는 반드시 그렇게 한다. 위치가 순서가 실제로 가진 성질이다.
  • online boolean 하나. 위 partition 경우 때문에 버렸다.
  • presence를 세션 index와 따로 쓴다. 버렸다: 「누가 연결돼 있나」의 정본이 둘이면 어긋나고, 그 어긋남은 보이지 않는다 — 둘 다 그럴듯해 보이고 아무것도 둘을 맞추지 않는다.