DongHyeonkaandClaude Opus 5
b2963105a8
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>
3.5 KiB
kind, slug, title, topic, project, status, sourceRevision, rootTreeNode, decisionStatus, decidedOn, source
| kind | slug | title | topic | project | status | sourceRevision | rootTreeNode | decisionStatus | decidedOn | source | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| PROJECT_DECISION | retry-safety-is-decided-by-evidence | 재시도 안전성은 증거에 기반해 판정한다 | http-failure-classification | clean-architecture-backend-template | 게시 전 | 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916 | decision:retry-safety-is-decided-by-evidence | ADOPTED | 2026-08-30 |
|
재시도 안전성은 증거에 기반해 판정한다
결정문
재시도 여부는 무엇이 실패했는지가 아니라 무엇이 관측됐는지로 판정한다.
판단 이유
같은 예외라도 요청이 서버에 닿았는지에 따라 재시도의 의미가 완전히 달라진다. 닿지 않았으면 재시도는 첫 시도이고, 닿았을지도 모르면 재시도는 중복이다. 예외 타입은 그 구분을 담지 않으므로, 관측된 진행 정도를 별도의 값으로 기록하고 그것을 판정 입력으로 삼는다.
이 판정을 보수적으로 유지하는 것이 핵심이다. 전송되지 않았다는 판정은 단계 실패가 그것을 증명할 때만 쓰고, 일반적인 엔진 입출력 실패는 결코 그 판정으로 승격되지 않는다. 모호한 것을 전송되지 않음으로 추측하는 것이 타임아웃을 중복 결제로 바꾸는 경로다.
같은 원칙이 이 저장소의 gRPC 쪽에도 별도 ADR 로 채택되어 있다. 거기서는 전송 증거와 업무 증거와 스트림 증거를 세 축으로 나누고 축 사이의 추론을 금지한다. HTTP 쪽의 이 결정은 그 셋 중 전송 축에 해당한다.
영향
감수하는 것
재시도 가능한 실패를 재시도하지 않는 경우가 생긴다. 증거가 모호하면 안전한 쪽으로 판정하므로, 실제로는 전송되지 않았는데 재시도를 포기하는 호출이 있다.
분류기마다 이 증거를 정확히 채워야 한다. 엔진별 분류기가 늘어날 때마다 같은 판정 품질을 유지해야 하는 비용이 붙는다.
증거를 만드는 계층이 정보를 버리면 판정 전체가 틀린 입력 위에 선다. 이 취약점은 실제로 관측되었다. 다중 주소 호스트에서 연결 루프가 앞선 주소의 실패를 버리면, 영구 실패가 재시도 가능한 범주로 내려온다. 분류기 안에서는 고칠 수 없다.
얻는 것
같은 실패에 대해 Apache JDK Reactor Netty Jetty 가 동일한 재시도와 관측 동작을 낸다.
재시도 정책이 HTTP 메서드 같은 간접 신호에 기대지 않는다.
근거
- 전송 실패를 단계와 범주 두 축으로 모델링한다 이 결정이 만들어 내는 자료 구조다. TransportFailure 의 notSent 와 sentNoResponse 팩토리, 그리고 ExecutionEvidence 의 네 값이 결정의 구현체다.
- 재시도 가능성은 멱등성과 실패 범주를 함께 봐야 정해진다 이 결정을 재시도 결정표로 옮긴 규칙이다.
- 붉은 테스트를 제품 결함으로 읽은 오진 이 결정의 취약점이 실제로 드러난 사례다.