docs(keycloak-session-store): import the session-storage lab as a new project

The keycloak project ended with four open questions that design could not settle. A two-VM lab was built to answer them by measurement, and this is that material: 26 experiments, 125 raw command outputs, 22 browser captures. Follows the import procedure in README.md. source/ the originating repository verbatim — 78 documents, 28 SVGs, 8 manifests, plus .source-revision recording the commit final/ the SSOT document.md 729 lines written from the 29 experiment documents, not concatenated: what was predicted, what was measured, and where the measurement itself was wrong evidence/raw 125 outputs, flattened to <experiment>__<file> because the originals collided (01-baseline.txt appeared three times) and the audit only globs the top level evidence/meta one per raw file; command and exitCode are null and the README says why rather than inventing them evidence/browser 22 captures assets/ three diagrams through techviz .techviz/ their VizSpecs A separate project rather than an addition to keycloak: the B-layer answers that project's four questions, but the A, C and D layers are about cluster failure, SSO and operations, and one document.md should hold one subject. The four question records there can point here through 관계. Recorded rather than papered over: only three of the 28 diagrams were remade. The repository forbids hand-drawn SVG and forbids titles inside the canvas; all 28 originals carry both, so converting them is redrawing, not reformatting. They stay in source/ and the gap is written into the document. verify-pipeline.py passes. audit-records.py reports no issues. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-04 22:51:59 +09:00
parent 43bccd08a8
commit b2963105a8
5017 changed files with 372751 additions and 4943 deletions
@@ -0,0 +1,118 @@
+---
+kind: CASE
+slug: a-circuit-breaker-permit-that-leaks-on-local-rejection
+title: 로컬 거부 경로에서 회로 브레이커 permission이 반환되지 않는다
+topic: http-failure-classification
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: case:a-circuit-breaker-permit-that-leaks-on-local-rejection
+evidenceCapturedOn: 2026-09-02
+body: case-a-circuit-breaker-permit-that-leaks-on-local-rejection.body.md
+assets:
+  - key: a-circuit-breaker-permit-that-leaks-on-local-rejection
+    file: ../../../final/evidence/rendered/a-circuit-breaker-permit-that-leaks-on-local-rejection.svg
+evidence:
+  - ../../../final/evidence/raw/a-circuit-breaker-permit-that-leaks-on-local-rejection.txt
+source:
+  - 원본 분석 절은 analysis/11 §22 이다. permission 획득·반환 경로의 전수 추적은 그 분석이 인용하는 원시 증거 170 번 §8.1 에 있다.
+---
+
+# 로컬 거부 경로에서 회로 브레이커 permission이 반환되지 않는다
+
+회로 브레이커 permission을 얻은 뒤 rate limiter나 bulkhead가 요청을 거부하면 그 permission이 반환되지 않는다. HALF_OPEN 상태에서는 시험 슬롯이 영구히 소비되어, 회복한 업스트림에 대해 회로가 닫히지 않을 수 있다.
+
+## 관계
+
+- **전송 실패의 단계와 범주 — AttemptStage와 FailureCategory**
+  이 파이프라인이 그 분류를 만들기 전에 지나는 승인 계층이다.
+
+## 문제
+
+요청 하나가 실행되기 전에 세 가드를 차례로 지난다. 회로 브레이커가 permission 을 주고, rate limiter 가 토큰을 주고, bulkhead 가 슬롯을 준다.
+
+뒤의 두 가드가 거부하면 그 경로는 예외를 던지고 끝난다. 그 사이에 이미 받아 둔 회로 permission 을 돌려주는 호출이 없다.
+
+## 결론
+
+경로 확인으로 확정한 결함이다. 회로가 반쯤 열린 상태에서만 발생한다.
+
+업스트림 장애로 회로가 열린다. 대기 후 반쯤 열린 상태로 바뀌고, 트래픽이 돌아온다. 그 순간 평상시 부하에 맞춰 사이징된 로컬 rate limiter 나 bulkhead 가 거부하기 시작하고, 거부마다 시험 슬롯 하나가 사라진다.
+
+거부가 허용된 시험 호출 수만큼 쌓이면 브레이커는 성공도 실패도 못 본 채 그 상태에 머문다. 회복한 업스트림에 대해 회로가 닫히지 않는다.
+
+수정하려면 인터페이스에 permission 반환 연산을 추가하고, rate limiter 와 bulkhead 가 요청을 거부하는 두 경로에서 그 연산을 호출해야 한다.
+
+## 검증 환경
+
+OpenJDK : 21.0.12
+Gradle : 9.0.0
+Spring Boot : 4.0.8
+Resilience4j : 2.2.0
+확인 방식 : 파이프라인 진입부의 예외 경로 추적, 인터페이스 연산 전수 확인, 반환 연산 이름 검색
+소스 수정 : x
+
+## 재현 조건
+
+1. AttemptResiliencePipeline.execute 의 83행부터 97행까지를 읽고, 세 가드의 거부 경로에서 회로 브레이커 연산이 호출되는지 확인한다.
+2. AttemptCircuitBreaker 의 추상 연산을 전수 확인한다. 넷이며 반환 연산이 없다.
+3. releasePermission 을 코드베이스에서 검색한다. Java 매치가 0 이다.
+4. AttemptResiliencePipelineTest 에서 회로 permission 반환을 단언하는 테스트가 있는지 확인한다.
+
+## 본문
+
+<!-- body:start -->
+
+`AttemptResiliencePipeline.execute` 진입부에서 세 가드가 차례로 실행된다. 83행이 회로 permission 을 얻고, 88행이 rate limiter 를, 93행이 bulkhead 를 본다.
+
+83행을 통과한 뒤 88행과 93행이 거부하면 그 두 경로는 예외를 던지고 끝난다. 회로 permission 이 돌아오지 않는다.
+
+## 반환할 연산 자체가 인터페이스에 없다
+
+:::evidence key="a-circuit-breaker-permit-that-leaks-on-local-rejection" alt="코드베이스에서 AttemptResiliencePipeline 의 가드와 반납 지점, AttemptCircuitBreaker 의 추상 연산 전수, releasePermission 검색 결과를 뽑은 출력 26줄. 인터페이스의 연산 넷과 Java 코드 매치 0, 그리고 그 이름이 설계 문서에만 남아 있다는 것이 그 출력에 그대로 보인다." caption="세 가드 · 정상 경로 반납 · AttemptCircuitBreaker 연산 넷 · releasePermission 검색 — 26줄 · exit 0" zoom="true"
+:::
+
+`AttemptCircuitBreaker` 의 추상 연산은 넷이다 — `tryAcquirePermission` · `onSuccess` · `onError` · `state`. 획득은 있고 반환은 없다.
+
+`releasePermission` 은 `src` 아래 Java 파일에서 매치가 0 이다. 저장소 전체로 넓히면 한 곳에 나오는데, 그것은 이 능력의 설계 문서다. 즉 이름이 설계 단계에서는 존재했고 구현에는 들어오지 않았다.
+
+로컬 거부 경로가 부르는 것을 잊은 것이 아니라, 부를 수 있는 연산이 없다.
+
+## 같은 거부 경로에서 rate 토큰은 돌려준다
+
+94행이 이 판정을 뒷받침한다. bulkhead 가 거부하는 경로는 `rateLimiter.onCompleted()` 를 불러 rate 토큰을 명시적으로 반환한다. 저자가 permit 반환을 의식하고 있었다는 증거다.
+
+정상 경로에도 같은 의식이 보인다. `releaseAttemptPermits()` 가 `bulkhead.release()` 와 `rateLimiter.onCompleted()` 를 함께 부른다 — 자료의 120행이 그 두 번째 호출이다. 세 가드 중 둘은 정상 경로에서도 거부 경로에서도 반납되고, 회로만 어느 쪽에서도 반납되지 않는다.
+
+## 이 결함은 HALF_OPEN 에서만 값을 갖는다
+
+Resilience4j 의 `tryAcquirePermission()` 은 반쯤 열린 상태에서 허용된 시험 호출 수 중 하나를 소비한다. 그 슬롯은 `onSuccess` · `onError` · `releasePermission` 중 하나로만 돌아온다. 아무것도 부르지 않으면 슬롯은 영구히 소비된다.
+
+닫힌 상태에서는 permission 이 계수를 소비하지 않으므로 같은 코드가 무해하다. 그래서 이 결함은 코드가 아니라 상태에 걸려 있고, 평상시 테스트로는 드러나지 않는다.
+
+## 조건들이 우연히 겹치지 않는다
+
+시험 슬롯이 열리는 시점은 업스트림이 회복을 시작한 시점이고, 트래픽이 돌아오는 시점도 같다. 평상시 부하에 맞춰 사이징된 로컬 가드는 그 순간에 거부하기 시작한다.
+
+거부마다 슬롯 하나가 사라진다. 허용된 시험 호출 수만큼 거부가 나면 브레이커는 성공도 실패도 관측하지 못한 채 그 상태에 머문다. `maxWaitDurationInHalfOpenState` 기본값이 0 — 무한 대기 — 이므로 시간이 그것을 풀어 주지도 않는다.
+
+## 테스트가 그 공백을 그대로 보여 준다
+
+인접한 두 성질에는 테스트가 있다.
+
+- `openCircuitDoesNotConsumeRateOrBulkheadPermit` — 회로가 거부할 때 뒤의 둘을 소비하지 않는다
+- `bulkheadRejectionReleasesTheRateLimiterAndIsNotACircuitError` — bulkhead 거부가 rate 를 돌려준다
+
+둘째 테스트가 단언하는 이벤트 순서는 `circuit-enter` · `rate-enter` · `bulkhead-reject` · `rate-exit` 다. 회로를 돌려주는 이벤트가 그 목록에 없다. 88행의 rate limiter 거부 경로에는 테스트가 아예 없다.
+
+## 수정
+
+`AttemptCircuitBreaker` 에 `releasePermission()` 을 더해 Resilience4j 의 같은 이름 연산에 위임하고, `alwaysClosed()` 구현에서는 아무것도 하지 않게 둔다. 그리고 두 로컬 거부 경로에서 그것을 부른다.
+
+## 확인하지 못한 것
+
+시험 슬롯 고갈을 반복 호출로 재현해 보지는 않았다. 회로가 닫히지 않는 상태를 런타임에서 관측한 것은 아니다.
+
+Resilience4j 의 상태별 permission 회계와 무한 대기 기본값은 그 라이브러리의 문서화된 동작을 근거로 삼았고, 이 회차에 라이브러리 코드를 실행해 확인하지는 않았다.
+
+<!-- body:end -->
@@ -0,0 +1,156 @@
+---
+kind: CASE
+slug: a-red-test-misread-as-a-product-defect
+title: 붉은 테스트를 제품 결함으로 읽은 오진 — 듀얼스택 localhost가 TLS 실패를 버린다
+topic: http-failure-classification
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: case:a-red-test-misread-as-a-product-defect
+evidenceCapturedOn: 2026-09-02
+body: case-a-red-test-misread-as-a-product-defect.body.md
+assets:
+  - key: a-red-test-misread-as-a-product-defect
+    file: ../../../final/evidence/rendered/a-red-test-misread-as-a-product-defect.svg
+  - key: a-red-test-misread-as-a-product-defect-host-control
+    file: ../../../final/evidence/rendered/a-red-test-misread-as-a-product-defect-host-control.svg
+evidence:
+  - ../../../final/evidence/raw/a-red-test-misread-as-a-product-defect.txt
+  - ../../../final/evidence/raw/a-red-test-misread-as-a-product-defect-host-control.txt
+source:
+  - 분석 문서는 httpclient 어댑터 편 §51 이다. 그 절이 앞선 P1 진단을 철회하고 교체하며, 근거로 측정 기록 EVD-332 를 든다. 강등이 패밀리별 실패 양상이 다를 때만 일어난다는 완화 조건과, 저장소가 IP 스택 선호를 고정하지 않아 듀얼스택에서 항상 실패한다는 판정도 그 절의 하위 항목이다. 교차 스코프 문서 §1 과 §5 가 이 번복을 저장소 전체 관점과 측정 방법 양쪽에서 다시 다룬다.
+---
+
+# 붉은 테스트를 제품 결함으로 읽은 오진 — 듀얼스택 localhost가 TLS 실패를 버린다
+
+mTLS 계약 테스트 3건이 실패한다. 앞선 판정은 이것을 P1 제품 결함으로 올렸지만, 예외 사슬을 실제로 출력해 보니 원인은 테스트 픽스처가 쓰는 호스트명이었다.
+
+## 관계
+
+- **전송 실패의 단계와 범주 — AttemptStage와 FailureCategory**
+  이 사례가 다루는 분류 모델이다. 여기서 두 축을 채우는 정보가 어떻게 사라지는지 보인다.
+- **분류기는 엔진이 남긴 것만 볼 수 있다**
+  이 사례에서 끌어낸 규칙이다. 분기 순서가 아니라 사슬에 무엇이 남았는가가 결정한다.
+- **런타임의 모양에 대한 주장은 런타임에서 확인한다**
+  이 오진 자체에서 끌어낸 규칙이다. 코드를 읽어 얻은 사슬 모양은 가설이었다.
+- **재시도 안전성은 증거에 기반해 판정한다**
+  이 사례가 그 결정의 취약점을 보여 준다. 증거를 만드는 계층이 정보를 버리면 판정이 틀린 입력 위에 선다.
+
+## 문제
+
+httpclient 어댑터의 테스트가 283건 중 3건 실패한다. 셋 다 같은 줄에서 같은 메시지로 실패한다.
+
+expected: TLS_HANDSHAKE
+ but was: CONNECT
+
+분류가 곧 재시도 안전성인 모듈이다. 영구 TLS 실패는 재시도되지 않고 연결 실패는 재시도된다.
+
+앞선 판정에서 이 건은 P1 제품 결함 자리에 있었다. 근거는 분류기의 분기 순서였다. Apache 가 TLS 실패를 연결 예외로 감싸면 앞선 분기가 뒤의 분기를 가린다는 것이다. 그 판정은 사슬을 읽어서가 아니라 분기 순서를 읽어서 나왔다.
+
+## 결론
+
+제품 결함이 아니다. 원인은 테스트 픽스처가 돌려주는 호스트명이다.
+
+호스트명은 이 컨테이너에서 두 주소로 풀리고, 목 서버는 IPv4 루프백에만 바인딩한다. Apache 의 연결 오퍼레이터는 해석된 주소를 순회하면서 마지막이 아닌 주소의 실패를 버리고 다음으로 넘어간다.
+
+첫 주소에서 핸드셰이크가 깨지고 그 예외가 버려진다. 듣는 소켓이 없는 두 번째 주소에서 거부가 나고, 뒤에 남은 주소가 없어 그 거부가 최종 결과가 된다. 분류기에 도달하는 유일한 예외가 그것이다.
+
+접속 호스트만 IPv4 주소로 바꾸면 세 건 모두 영구 TLS 실패로 분류된다.
+
+남는 판정은 둘이다. 픽스처가 호스트명을 쓰는 것은 P3 이다. 다중 주소 호스트에서 패밀리별 실패 양상이 다르면 영구 TLS 실패가 재시도 가능한 범주로 강등되는 성질은 P2 기록이며, 이 모듈에서 고칠 수 없다.
+
+## 검증 환경
+
+OpenJDK : 21.0.12
+Gradle : 9.0.0
+Spring Boot : 4.0.8
+Apache HttpClient : httpclient5 5.5.2, httpcore5 5.3.6
+MockWebServer : okhttp 4.12.0, okhttp-tls 4.12.0
+/etc/hosts : 127.0.0.1 localhost 와 ::1 localhost 양쪽 존재
+preferIPv4Stack 설정 : x
+소스 수정 : x
+
+## 재현 조건
+
+1. httpclient 어댑터의 테스트를 모듈 전체로 실행한다. 283건 중 3건이 같은 줄에서 실패한다.
+2. 그 줄이 단언 블록의 몇 번째인지, 그 앞줄이 통과하는지 확인한다.
+3. 픽스처의 URI 메서드가 무엇을 돌려주는지, 그 호스트명이 몇 개의 주소로 풀리는지 확인한다.
+4. 같은 서버와 같은 신뢰 재료로 접속 호스트만 바꿔 세 경우를 각각 실행하고, 예외 사슬과 분류 결과를 비교한다.
+
+## 본문
+
+<!-- body:start -->
+
+httpclient 어댑터의 mTLS 계약 테스트 다섯 건 중 세 건이 실패한다. 신뢰할 수 없는 CA, 만료된 인증서, 호스트명 불일치다.
+
+## 멈추는 자리는 범주가 아니라 단계다
+
+:::evidence key="a-red-test-misread-as-a-product-defect" alt="이 리비전에서 모듈 전체 테스트를 실행해 283건 중 3건이 같은 줄에서 실패하는 것을 보인 출력과, 멈추는 자리가 두 번째 단언임을 실제 행 번호로 보인 단언 블록, 픽스처가 호스트명을 돌려주는 메서드, 이 컨테이너의 hosts 항목과 자바가 그 호스트명에서 얻는 주소 둘과 IP 스택 선호 설정 수, 그리고 영구 범주 목록과 재시도 엔진의 가드 순서를 뽑은 출력 55줄. 실패가 범주가 아니라 단계 단언에서 나고 호스트명이 주소 둘로 풀린다는 것이 그 출력에 보인다." caption="모듈 전체 283 중 3 실패 · 멈추는 자리는 168행 단계 단언 · 픽스처의 호스트명 · 주소 둘 · 영구 범주 목록과 가드 순서 — 55줄" zoom="true"
+:::
+
+단언 블록은 잡은 예외를 분류기에 넣고 넷을 차례로 확인한다. 첫 줄은 통과한다 — 증거가 "보내지 않음"인 것은 맞다.
+
+두 번째 줄에서 멈춘다. 단계가 TLS 핸드셰이크여야 하는데 연결이다. 범주 단언은 실행되지도 않는다.
+
+분류가 곧 재시도 안전성인 모듈이라 이 차이는 크다. 영구 범주는 거부되고, 연결 범주는 허용된다.
+
+## 분기 순서를 읽어서는 답이 나오지 않는다
+
+앞선 판정은 이것을 제품 결함으로 올렸다. 근거는 분류기가 원인 사슬을 바깥에서 안으로 훑으며 첫 매치를 돌려준다는 것, 그리고 연결 규칙이 TLS 규칙보다 앞에 있다는 것이었다.
+
+그 추론은 사슬의 모양을 가정한다.
+
+## 사슬에 SSL 예외가 없었다
+
+떠 보니 원인 사슬은 둘뿐이었다. 접근 예외와 연결 거부다.
+
+분류기는 자기가 받은 것을 정확히 분류했다. 정보는 도착하기 전에 이미 사라졌다.
+
+## 사라진 자리는 이름 해석이다
+
+픽스처의 URI 메서드가 호스트명 localhost 를 돌려준다. 이 컨테이너의 hosts 파일은 그 이름을 IPv4 와 IPv6 양쪽에 주고, 자바도 두 주소를 돌려준다. 저장소 어디에도 IP 스택 선호를 고정하는 설정이 없다.
+
+목 서버는 IPv4 루프백에만 바인딩한다. Apache 의 연결 오퍼레이터는 해석된 주소를 차례로 시도하는데, 마지막 주소가 아니면 실패를 로그로만 남기고 다음으로 넘어간다. 그 자리 로그 문구가 두 갈래로 나뉜다 — 마지막이면 "작업을 종료한다", 아니면 "다음 주소로 연결을 재시도한다".
+
+첫 주소에서 TCP 는 붙고 핸드셰이크가 깨진다. 그 실패가 버려진다. 두 번째 주소에는 듣는 소켓이 없어 TCP 가 거부되고, 마지막이므로 승격된다.
+
+## 접속 호스트만 바꾸면 셋 다 영구가 된다
+
+:::evidence key="a-red-test-misread-as-a-product-defect-host-control" alt="같은 서버와 같은 신뢰 재료로 접속 호스트만 호스트명과 IPv4 주소로 바꿔 세 경우를 각각 실행한 결과. 호스트명 쪽은 세 건 모두 연결 거부 두 단계로 끝나 재시도 가능으로 분류되고, IPv4 주소 쪽은 세 건 모두 핸드셰이크 실패가 사슬에 남아 영구로 분류된다." caption="접속 호스트만 바꾼 대조 — 호스트명 셋은 CONNECT · IPv4 셋은 TLS_PERMANENT" zoom="true"
+:::
+
+같은 서버와 같은 신뢰 재료로 URI 의 호스트만 바꿨다. 호스트명 쪽은 세 건 모두 연결 거부 두 단계로 끝나고 재시도 가능으로 분류된다. IPv4 주소 쪽은 세 건 모두 핸드셰이크 실패가 사슬에 남고 영구로 분류된다.
+
+사슬의 모양은 셋이 같지 않다. 신뢰할 수 없는 CA 와 만료 인증서는 PKIX 검증 실패가 다섯 단계로 남고, 만료 쪽 끝에는 만료 시각이 붙는다. 호스트명 불일치는 세 단계이고 PKIX 가 아니라 주체 대체 이름 불일치다.
+
+## 통과하는 두 건은 서로 다른 이유로 통과한다
+
+클라이언트 인증서를 제시하는 건은 첫 주소에서 핸드셰이크가 성공하고 루프가 즉시 반환한다. 두 번째 주소를 시도하지 않는다.
+
+클라이언트 인증서가 없는 건은 다르다. TLS 1.3 에서 클라이언트가 자기 몫을 끝낸 뒤 서버가 거절하므로 실패가 연결 루프 밖에서 터지고 핸드셰이크 예외가 그대로 남는다. 그리고 그 테스트는 예외의 종류가 아니라 예외가 났는지만 단언한다.
+
+처음 눈에 띈 차이는 실패하는 세 건만 클라이언트 인증을 요구하지 않는 픽스처를 쓴다는 점이었다. 그것은 원인이 아니라 상관이었다.
+
+## 픽스처를 고치는 것만으로는 부족하다
+
+테스트 실패 자체는 환경에 달려 있다. localhost 가 IPv4 로만 풀리는 환경에서는 세 건 모두 통과한다. 저장소가 IP 스택 선호를 고정하지 않으므로, 듀얼스택 컨테이너나 CI 에서는 산발이 아니라 항상 빨갛다.
+
+고칠 것은 픽스처가 호스트명을 돌려준다는 점이고 이쪽은 P3 다. 다만 IPv4 리터럴을 돌려주는 것만으로는 안 된다. 서버 인증서의 주체 대체 이름이 localhost 하나뿐이라, 주소를 거기 함께 넣지 않으면 지금 통과하는 mTLS 건이 이름 불일치로 빨개진다.
+
+## 남는 성질은 이 모듈에서 고칠 수 없다
+
+듀얼스택 업스트림에서 한쪽 주소 패밀리가 TLS 를 영구 거절하고 다른 쪽이 연결을 거부하면, 절대 검증되지 않을 인증서에 대한 호출이 연결 실패로 분류된다.
+
+강등은 패밀리별 실패 양상이 다를 때만 일어난다. 인증서 자체가 신뢰 불가면 보통 두 패밀리 모두 TLS 에서 실패하고, 그때는 마지막 주소의 예외도 핸드셰이크 예외라 올바르게 분류된다.
+
+강등이 일어나면 영구 범주였을 때 즉시 거부됐을 호출이 재시도 대상이 된다. 엔진의 가드 순서상 최대 시도 횟수와 예산이 먼저 자르므로 무한히 도는 것은 아니다. 그 한도까지는 돈다.
+
+분류기가 볼 수 있는 정보를 Apache 의 다중 주소 루프가 이미 버렸기 때문에, 이 모듈 안에서 막을 방법이 없다.
+
+## 확인하지 못한 것
+
+나머지 두 분류기는 같은 절차로 확인하지 못했다. 앞선 판정이 남긴 "다른 두 분류기도 같은 문제가 있는가"라는 항목은 전제가 반증되어 소멸하지만, 두 분류기 자체를 측정한 것은 아니다.
+
+ReactorFailureClassifier 와 JdkFailureClassifier 는 같은 방식으로 실행해 보지 않았다. 위 대조는 세 건을 각각 두 호스트로 실행한 것이고, 목 서버가 IPv4 에만 바인딩한다는 것은 그 결과에서 역추론했다.
+
+<!-- body:end -->