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,60 @@
+---
+kind: REFERENCE
+slug: deadline-narrows-in-three-stages
+title: 데드라인은 호출 예산에서 시작해 세 단계로 좁힌다
+topic: transaction-deadline-and-pool
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:deadline-narrows-in-three-stages
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+---
+
+# 데드라인은 호출 예산에서 시작해 세 단계로 좁힌다
+
+## 목적
+
+상위 호출자가 포기한 뒤에도 하위 작업이 계속 돌아 자원을 점유하는 것을 막는다.
+
+## 규칙
+
+1. 출발점은 호출 예산이다
+   상위 호출자가 기다릴 수 있는 시간에서 시작한다. 하위가 스스로 정한 값에서 시작하지 않는다.
+
+2. 획득 시간을 뺀다
+   커넥션이나 슬롯을 얻는 데 든 시간은 이미 예산에서 소비된 것이다. 그것을 빼지 않으면 남은 시간이 없는 채로 작업을 시작한다.
+
+3. 각 단계는 앞 단계보다 작다
+   호출 예산보다 트랜잭션 타임아웃이 작고, 그보다 데이터베이스 로컬 타임아웃이 작다.
+
+4. 가장 안쪽이 먼저 끊는다
+   데이터베이스가 먼저 끊어야 애플리케이션이 그 실패를 분류할 기회를 갖는다. 반대면 쿼리가 결과를 받을 사람 없이 계속 돈다.
+
+5. 계산을 자기 타입에 둔다
+   값이 여러 곳에서 계산되면 그중 하나가 획득 시간을 빼는 것을 잊는다.
+
+## 적용 조건
+
+트랜잭션과 원격 호출처럼 시간이 걸리는 모든 하위 작업
+
+풀에서 자원을 얻어 쓰는 경로
+
+## 예외
+
+배치나 백그라운드 작업처럼 상위 호출자가 없는 경우는 예산의 출발점이 다르다. 그때는 그 작업 자체의 상한이 출발점이다.
+
+## 예시
+
+데드라인 계산기가 획득 봉투를 포함하는 형태와 포함하지 않는 형태를 나눠 갖는다.
+
+로컬 타임아웃을 거는 방법은 데이터베이스마다 달라서 설정기가 따로 있다.
+
+## 관계
+
+- **호출 예산에서 DB 로컬 타임아웃까지의 데드라인 전파**
+  이 규칙이 나온 개념이다.
+- **쓰기 트랜잭션에는 유한 타임아웃이 필수다**
+  마지막 단계가 비어 있을 때의 규칙이다.
+- **재시도 가능성은 멱등성과 실패 범주를 함께 봐야 정해진다**
+  데드라인이 재시도 판정의 입력이 되는 지점이다.
+
@@ -0,0 +1,58 @@
+---
+kind: REFERENCE
+slug: session-scoped-settings-outlive-the-transaction
+title: 세션 스코프 설정은 풀로 돌아간 커넥션에 남는다
+topic: transaction-deadline-and-pool
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:session-scoped-settings-outlive-the-transaction
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+---
+
+# 세션 스코프 설정은 풀로 돌아간 커넥션에 남는다
+
+## 목적
+
+한 트랜잭션을 위해 건 세션 설정이 커넥션과 함께 풀로 돌아가, 무관한 다음 작업에 적용되는 것을 막는다.
+
+## 규칙
+
+1. 세션 스코프와 트랜잭션 스코프를 구별한다
+   세션 스코프로 설정하면 커넥션이 살아 있는 동안 유지된다. 트랜잭션이 끝나도 사라지지 않는다.
+
+2. 가능하면 로컬 스코프를 쓴다
+   트랜잭션 로컬로 설정하면 커밋이나 롤백과 함께 사라진다.
+
+3. 로컬이 불가능하면 반납 전에 되돌린다
+   설정을 건 쪽이 그것을 지우는 책임을 갖는다. 다음 사용자가 지울 것이라고 가정하지 않는다.
+
+4. 데이터베이스마다 방법이 다르다
+   같은 개념의 설정이라도 문법과 스코프가 다르므로 설정기를 데이터베이스별로 둔다.
+
+5. 테넌트나 사용자 컨텍스트를 세션에 남기지 않는다
+   커넥션이 풀에서 재사용되면 다른 테넌트의 요청이 앞 요청의 컨텍스트를 물려받는다.
+
+## 적용 조건
+
+커넥션 풀을 쓰는 모든 데이터베이스 접근
+
+로컬 타임아웃 검색 경로 역할 테넌트 컨텍스트 같은 세션 설정
+
+## 예외
+
+풀을 쓰지 않고 요청마다 새 커넥션을 여는 구성은 이 규칙의 대상이 아니다. 그 경우 다른 비용이 든다.
+
+## 예시
+
+로컬 타임아웃 설정기가 PostgreSQL 과 H2 로 나뉘어 있다. 설정 문법이 다르고 세션에 남는 방식도 다르기 때문이다.
+
+멀티테넌시에서 테넌트 컨텍스트를 세션에 남기면 풀 재사용이 곧 테넌트 경계 위반이 된다.
+
+## 관계
+
+- **호출 예산에서 DB 로컬 타임아웃까지의 데드라인 전파**
+  로컬 타임아웃을 거는 지점이다.
+- **connection-timeout이 5s 문자열로 출하되어 prod와 dev 배포가 전부 시작에 실패했다**
+  같은 설정 계층의 다른 함정이다.
+
@@ -0,0 +1,55 @@
+---
+kind: REFERENCE
+slug: write-transactions-need-a-finite-timeout
+title: 쓰기 트랜잭션에는 유한 타임아웃이 필수다
+topic: transaction-deadline-and-pool
+project: clean-architecture-backend-template
+status: 게시 전
+sourceRevision: 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916
+rootTreeNode: reference:write-transactions-need-a-finite-timeout
+verifiedOn:            # 이 기록은 이번 회차에 실행 확인을 하지 않았다
+---
+
+# 쓰기 트랜잭션에는 유한 타임아웃이 필수다
+
+## 목적
+
+타임아웃 없는 쓰기 트랜잭션이 잠금을 무한히 들고 있어, 다른 쓰기 전부를 막는 것을 방지한다.
+
+## 규칙
+
+1. 쓰기 경로에 무한 대기를 두지 않는다
+   타임아웃이 없으면 잠금 대기가 끝나지 않는다.
+
+2. 기본값을 무한으로 두지 않는다
+   설정하지 않았을 때의 동작이 무한 대기면, 설정을 잊은 배포가 가장 위험한 배포가 된다.
+
+3. 읽기와 쓰기의 상한을 따로 둔다
+   읽기가 길어지는 것과 쓰기가 길어지는 것은 영향 범위가 다르다.
+
+4. 타임아웃 값을 타입으로 강제한다
+   설정 값이 비어 있을 수 있는 형태면 그 경로가 언젠가 무한이 된다.
+
+## 적용 조건
+
+잠금을 잡는 모든 쓰기 트랜잭션
+
+여러 인스턴스가 같은 행을 경합하는 구조
+
+## 예외
+
+관리자가 명시적으로 실행하는 일회성 마이그레이션이나 백필은 상한이 다를 수 있다. 그 경우 실행 절차에 그 사실이 있어야 한다.
+
+## 예시
+
+트랜잭션 템플릿이 모드마다 미리 만들어져 있고 전부 같은 격리 수준에 고정되어 있다. 데드라인은 실행 시점에 계산되어 전달된다.
+
+풀 커넥션 타임아웃은 기본 30 초 대신 짧은 값으로 고정한다. 풀이 고갈된 스레드를 오래 붙잡지 않고 빠르게 거절하기 위해서다.
+
+## 관계
+
+- **데드라인은 호출 예산에서 시작해 세 단계로 좁힌다**
+  이 규칙이 속한 전파 구조다.
+- **커밋 모호성 판정은 넓혀도 좁혀도 해롭다**
+  타임아웃이 만드는 실패를 어떻게 분류할지 다룬 규칙이다.
+