Files
clean-architecture-backend-…/docs/adr/ADR-WS-002-resume-and-cluster.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

3.7 KiB
Raw Blame History

ADR-WS-002: Resume and cluster state are caches, and are treated as caches

  • Status: Superseded 2026-09-25 — advanced.resume, advanced.cluster and advanced.presence were removed: nothing assembled them (see docs/capability-status.md).
  • Date: 2026-08-25
  • Scope: adapter:inbound:websocket — advanced.resume, advanced.cluster, advanced.presence

Context

Advanced Tasks 2–8 add three things that all look like state and are not: a resume token that says where a client got to, a cluster index that says which node holds a session, and a presence summary derived from that index.

Each is a statement about the past. The resume token was minted before the disconnect; the index entry was written by a node that may since have died; presence is a read of the index and inherits everything wrong with it. The failure this ADR exists to prevent is treating any of them as current fact, because each reads as one at the call site.

Decision

Resume is bounded by what the replay store actually holds, not by what the token claims. ResumeCoordinator consults ReplayAvailability before honouring a position. A token that names a position the store has evicted produces a resynchronise, not a gap-filled stream. The alternative — trusting the token — silently delivers a stream with a hole in it, which is worse than an explicit resynchronise because the client believes it is complete.

Cluster index entries carry an observation time and are checked against it on every read. ExternalSessionSummary.staleAt exists so that "the index says edge-2" cannot be used without also answering "as of when". An entry whose node stopped reporting is not evidence that the node holds the session.

Durable fan-out is deduplicated by stream position, not by message id. At-least-once is the contract, so redelivery is normal operation: a redeploy, a slow consumer or a broker rebalance all produce it. FanoutDeduplicator keys on (stream, position) and advances a high-water mark under compute, so two consumer threads cannot both deliver the same position.

Presence has four states, not two. OFFLINE is a reported fact; STALE is the absence of one. Collapsing them reports every user as disconnected during a Redis partition, when what happened is that the index went dark and the connections are fine.

Nothing security-relevant may depend on presence. An attacker who can make a node stop reporting can move the platform's belief about who is present. Presence answers "show a green dot".

Consequences

  • A resume that cannot be honoured is visible to the client as a resynchronise. Clients must implement one; there is no mode in which the platform silently pretends.
  • Every read of the cluster index needs a clock. This is deliberate friction.
  • PresenceSummary.classify refuses an idle window at or past the stale window, because otherwise IDLE is unreachable and the caller believes it has a four-state model when it has three.
  • Fan-out envelopes carry a bounded reference and the catalog-encoded document, never a business object. A rolling deploy has two versions of the code reading the same envelope.

Alternatives considered

  • Trust the resume token. Rejected: it makes a gap indistinguishable from a complete stream.
  • Deduplicate by message id. Rejected: a broker that redelivers may re-mint ids, and a producer that retries certainly does. Position is the property the ordering actually has.
  • A single online boolean. Rejected for the partition case above.
  • Write presence separately from the session index. Rejected: two sources of truth for "who is connected" drift, and the drift is invisible — both look plausible and nothing reconciles them.