refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -31,7 +31,7 @@ source:
 - **시작 검증기가 도는지는 그 능력에 자동설정 루트가 있는지와 일치한다**
  시작 검증기가 도는지를 자동설정 루트로 확인하는 절차다.
 - **하위 시스템 전체가 미배선인데 그것을 켜는 플래그는 시작 검사를 수행한다**
-  플래그와 실행의 어긋남이 반대 방향으로 나타난 사례다.
+  Redis에서는 설정이 보증을 요구하지만 startup probe가 자동설정 경로에 연결되지 않아 실행되지 않았다.

 ## 문제

@@ -77,7 +77,7 @@ OpenJDK : 21.0.12

 확인 메서드가 두 호출로 넷을 덮는다. 앞의 호출이 서버 버전과 배포 모드와 데이터베이스 번호와 명령 목록으로 능력을 판정하고, 뒤의 호출이 복제 배포의 쓰기 내구성을 요구한다.

-클래스 javadoc 이 왜 서버에 묻는지 적는다. 설정은 배포가 무엇을 의도하는지 말하고 서버만이 무엇이 참인지 말한다는 것, 관리형 Redis 가 광고하는 버전이 모듈의 존재를 뜻하지 않는다는 것, 그리고 복제 배포의 쓰기 내구성은 어떤 클라이언트도 보상할 수 없는 서버 설정이라는 것이다.
+클래스 javadoc은 설정이 배포 의도를 표현할 뿐 실제 서버 상태를 증명하지 못한다고 설명한다. 관리형 Redis의 광고 버전만으로 모듈 존재를 확정할 수 없고, 복제 쓰기 내구성은 서버 설정을 직접 읽어 확인해야 한다.

 같은 문단이 시점의 값도 적는다. 빠진 능력을 첫 요청에서 발견하면 장애이고, 여기서 발견하면 실패한 배포다.

@@ -95,7 +95,7 @@ OpenJDK : 21.0.12

 복제 최소 개수와 상한이 걸린 최대 지연이 그 상황을 호출자가 대응할 수 있는 거절로 바꾼다. 같은 승격이 그때는 2,086건 대신 한 건을 잃었다.

-그래서 그 설정 없는 복제 배포는 경고가 아니라 기동 실패라고 적는다. 보증을 무의미하게 만드는 설정은 조용히 성능을 낮추는 대신 컨텍스트를 멈춘다는 것이 이 SDK 의 원칙이라는 것이다.
+javadoc은 요구한 복제 보증을 무효화하는 서버 설정이 확인되면 경고만 남기지 않고 기동을 거부하도록 설계했다고 적는다.

 면제는 가능하다. 배포가 정말로 쓰기 하나를 잃어도 괜찮을 수 있고 이 SDK 가 서버를 소유하지 않기 때문이다. 다만 면제에는 명시적 설정이 필요해서, 그 거래가 사고 중에 발견되는 대신 기록으로 남는다.

@@ -105,7 +105,7 @@ OpenJDK : 21.0.12

 복제 개수만으로는 몇 개가 연결되어 있어야 하는지만 정해진다. 얼마나 뒤처져도 되는지는 최대 지연이 정하고, Redis 는 그 값 0 을 지연 요구 없음으로 다룬다.

-그래서 복제 둘을 요구하면서 지연 상한을 0 으로 둔 배포는, 임의로 뒤처진 복제 둘이 붙어 있기만 하면 쓰기를 받는다. 개수 요구가 없애려던 바로 그 노출이 그대로 남는다.
+그래서 복제 둘을 요구하면서 지연 상한을 0으로 둔 배포는, 두 replica가 연결돼 있기만 하면 지연 정도와 무관하게 쓰기를 받을 수 있다. replica 개수만 검사해서는 뒤처진 replica를 허용하는 위험을 막지 못한다.

 개수만 검사하던 동안 그 설정이 통과했다. 그러면서 실패 메시지는 운영자에게 지연 상한을 설정하라고 말하고 있었다.

@@ -22,7 +22,7 @@ source:

 # 명령 카탈로그와 admission 아홉 단계

-모든 Redis 명령이 하나의 승인 지점을 지나고, 그 지점은 정해진 순서로 검사한다. 순서의 기준은 비용이다. 명백히 거부될 명령은 무엇도 인코딩되거나 전송되기 전에 거부된다.
+이 문서는 `CommandPolicyGuard`를 통과하도록 설계된 guarded command path의 admission 순서를 설명한다. 실제 코드에는 semantic adapter가 gateway를 직접 호출해 이 경로를 우회하는 사례가 있으므로 현재 runtime 전체의 모든 Redis 명령이 하나의 승인 지점을 지난다고 말하지 않는다.

 ## 관계

@@ -39,12 +39,12 @@ source:

 이 SDK가 명령 하나를 내보내기 전에 지나는 단계의 설명이다 — 카탈로그 분류(BLOCKED·R3·R4 거부) · capability/최소 버전 확인 · permit provenance 검증 · 네임스페이스 검사 · Cluster 동일 슬롯 검사 · 요청 예산 · 정책 기반 레인·타임아웃 유도 · 실패 번역 · 관측.

-## 명령 입장의 단일 지점
+## 의도된 guarded command path의 입구

 :::evidence key="redis-admission-stages-diagram" alt="CommandPolicyGuard 에서 카탈로그를 통과하면 실행이고 미분류나 BLOCKED 이면 거절인 두 갈래가 나온다" caption="명령 입장의 단일 지점" zoom="false"
 :::

-그 위에 얹힌 계약은 gateway가 "everything routed through it has already passed `CommandPolicyGuard`"를 전제한다는 것이다 — 그래서 정책·permit·예산·타임아웃·관측을 자기 관심사로 두지 않는다.
+gateway 계약은 자신에게 도달한 호출이 이미 `CommandPolicyGuard`를 지났다고 전제한다. 그래서 guarded path 안에서는 정책·permit·예산·타임아웃·관측을 guard 쪽 책임으로 둔다. 다만 직접 gateway 호출이 존재하면 그 전제 자체가 깨지므로 이 그림은 전체 runtime topology가 아니라 의도된 guarded path를 나타낸다.

 ## CommandPolicyGuard 참조 위치