Icarus

일관성 코어 (Consistent Core) & 리스 (Lease)

Icarus8050 — Mon, 17 Aug 2026 20:58:48 +0900

일관성 코어 (Consistent Core) & 리스 (Lease)

1. 일관성 코어 — 합의는 클러스터 크기와 함께 스케일하지 않는다

문제

1,000노드 클러스터가 Raft를 직접 돌린다면 정족수가 501이다. 쓰기마다 501개의 ack를
기다려야 하고, 하트비트가 1,000개씩 오가며, 리더 선출 때는 1,000노드가 투표전을 벌인다.
정족수 기반 합의의 비용은 노드 수에 비례해 나빠지는데, 우리가 노드를 늘리는 이유는
데이터와 처리량 때문이지 합의 참여자를 늘리고 싶어서가 아니다. 요구가 어긋나 있다.

그런데 잘 보면, 큰 클러스터에서 강한 일관성이 필요한 데이터는 아주 작다. 어떤 노드가
살아있는가, 어떤 파티션을 어떤 노드가 담당하는가, 클러스터 설정값 — 메타데이터뿐이다.
실제 데이터 읽기/쓰기는 파티셔닝과 복제로 처리하면 되고, 거기엔 전 클러스터 합의가 필요
없다.

해법: 작은 합의 클러스터 + 큰 데이터 클러스터

┌─────────────────────────────────────┐
│  일관성 코어 (3~5 노드, Raft/Zab)      │  ← 메타데이터, 강한 일관성
│  멤버십 / 파티션 배정 / 설정 / 선출     │     쓰기 빈도 낮음, 데이터 작음
└───────────────┬─────────────────────┘
                │ 리스 갱신(하트비트), 감시(watch), 메타데이터 조회
┌───────────────┴─────────────────────┐
│  데이터 클러스터 (수백~수천 노드)        │  ← 실제 데이터, 파티셔닝/복제
└─────────────────────────────────────┘

실물로는 전부 아는 이름들이다. ZooKeeper(HBase, HDFS, 구세대 Kafka의 코어),
etcd(Kubernetes의 코어), Chubby(Google GFS/Bigtable의 코어, 이 패턴의 원조 논문),
그리고 Kafka KRaft의 컨트롤러 쿼럼(외부 코어 ZooKeeper를 쓰다가 같은 구조를 내부로
들여온 사례).

코어가 제공하는 세 가지 기능

첫째, 강한 일관성의 작은 KV 저장소. 메타데이터를 선형화 가능(linearizable)하게 읽고 쓸
수 있어야 한다. "파티션 7의 리더가 누구인가"에 대해 두 노드가 다른 답을 받으면 안 된다.
내부는 복제 로그 + 단일 갱신 큐 + 요청 대기 목록 — 앞선 글들의 파이프라인 그대로다.

둘째, 리스 기반 멤버십 관리. 데이터 노드는 코어에 자신을 등록하면서 TTL이 있는 리스를
받고, 주기적인 하트비트로 갱신한다. 갱신이 끊기면 코어는 그 노드를 죽은 것으로 간주한다
(2장에서 상세히 다룬다).

셋째, 상태 감시(State Watch). 클라이언트가 "이 키가 바뀌면 알려달라"고 등록해 두면
코어가 변경 시점에 통지를 밀어준다. 컨트롤러가 "노드 등록이 사라지면 파티션 재배정을
시작한다"처럼 반응형으로 동작하는 기반이다.

설계 원칙: 코어는 제어면이지 데이터 경로가 아니다

코어의 처리량은 3~5노드 합의 클러스터의 처리량이다. 데이터 요청이 매번 코어를 거치면
코어가 전체 시스템의 병목이자 단일 장애점이 된다. 그래서 실제 시스템들은 클라이언트가
파티션 배치 정보를 코어에서 한 번 읽어 캐시하고, 데이터 요청은 데이터 노드로 직행하며,
배치가 바뀌었을 때만(watch 통지 또는 요청 실패 시) 갱신한다. 코어에 담는 데이터는 메모리에
다 들어갈 만큼 작게, 쓰기 빈도는 "노드가 죽거나 설정이 바뀔 때" 수준으로 낮게 유지한다.
Kubernetes 운영에서 "etcd에 큰 오브젝트를 넣지 마라"가 철칙인 이유다.

2. 스플릿 브레인과 펜싱 — 코어와 데이터 노드 사이의 유령 리더

데이터 노드 D가 파티션 7의 리더로 배정되어 있고, 코어의 리스로 그 사실이 관리되고 있다고
하자. 그런데 D와 코어 사이의 네트워크만 끊겼다 — D는 멀쩡히 살아서 클라이언트 요청을
계속 받고 있다. 리스가 만료되면 코어는 D를 죽었다고 보고 파티션 7의 리더를 E로 재배정한다.

이 순간 파티션 7에 리더가 둘이 된다 — 스플릿 브레인이다. D는 자기가 강등된 것을
모르고(코어와 연락이 안 되니 통지받을 길이 없다) 계속 리더 행세를 하고, 클라이언트마다
다른 리더에 쓰면서 두 사본이 갈라진다.

해법의 방향: D를 멈추게 하는 게 아니라, 세상이 D를 거절하게 만든다

핵심 통찰 — D의 행동은 고칠 수 없다. 연락이 안 되는 노드에게 "너 강등됐어"를 전할
방법은 정의상 없다. 그래서 해법의 방향이 뒤집힌다.

코어가 파티션 리더를 배정할 때마다 단조 증가하는 세대 번호를 함께 발급한다. D는 세대
5의 리더였고 E는 세대 6의 리더다. 리더가 하는 모든 요청(팔로워 복제, 스토리지 쓰기)에 이
번호를 실어 보내게 하고, 받는 쪽은 자기가 본 최고 세대를 기억하며 그보다 낮은 세대의
요청을 거부한다.

E가 세대 6으로 활동 시작 → 레플리카들이 "최고 세대 = 6" 기록
D(세대 5)가 복제/쓰기 시도 → "세대 5 < 6" → 거부
D는 거부당하고서야 자신의 강등을 알게 됨 → 스스로 물러남

D의 쓰기는 접수까지는 될지 몰라도 커밋(복제 완료)이 불가능해진다. 이 용도의 세대 번호를
펜싱 토큰(fencing token) 이라 부른다. Chubby의 sequencer, Kafka의 leader
epoch/controller epoch, HDFS NameNode 페일오버의 fencing이 전부 이것이다.

방어는 두 겹이다. 1겹: D의 자진 사퇴(리스 TTL을 스스로 감시하다 갱신 실패 시 역할 중단
— 홀더와 코어의 시계 차이 때문에 코어는 ε 여유를 두고 재배정한다). 2겹: 펜싱 토큰(D가
어떤 이유로든 안 물러나도 세상이 거부한다). 1겹은 최적화이고 2겹이 안전망이다. "노드가
성실하게 행동한다"에 기대는 장치와 "노드가 무슨 짓을 해도 안전하다"인 장치를 구분하는 것이
중요하다.

3. 리스 (Lease)

문제: 분산 환경에서 "소유"는 어떻게 만료되는가

분산 환경에서 순수한 락은 치명적 결함이 있다. 락을 쥔 노드가 죽으면 락이 영원히
잠긴다. 해제해 줄 주체가 사라졌기 때문이다. 그룹 멤버십("나 살아있어"), 파티션 리더십도
본질이 같다. 소유자가 사라졌을 때 그 사실이 자동으로 무효화되는 메커니즘이 필요하다.

락에 유효기간(TTL)을 붙인 것이 리스다. "이 자원은 30초 동안 네 것이다. 계속 쓰려면
만료 전에 갱신해라. 갱신이 끊기면 자동 회수한다." DHCP가 IP 주소를 나눠주는 방식 그대로다.

구현: 리스는 일관성 코어의 복제된 상태다

클라이언트가 리스를 요청하면 코어의 리더는 이것을 복제 로그의 엔트리로 커밋한다. 코어
노드 전부가 "이 리스가 존재한다"에 합의한다. 갱신도, 만료에 의한 삭제도 로그를 탄다. 코어
리더가 죽어도 새 리더가 같은 로그에서 같은 리스 목록을 복원한다.

여기서 미묘한 설계 결정이 하나 있다. 시간을 재는 것은 오직 코어의 리더뿐이다.
팔로워들도 리스 데이터는 갖고 있지만, 각자 시계를 보며 만료를 독자 판단하지 않는다. 코어
노드들의 시계도 서로 어긋나 있기 때문이다. 각자 판정하면 노드마다 리스 목록이 달라지는 —
합의로 지켜온 일관성이 시계 때문에 깨지는 — 사태가 난다. 그래서 만료 판정은 리더가
내리고, 그 결정(삭제)을 로그로 복제한다. 팔로워에게 만료란 시계 이벤트가 아니라 로그
엔트리다. "시간에 대한 판단조차 단일 결정자를 거쳐 로그로 흐르게 한다" — 단일 갱신 큐의
철학이 시간 영역까지 확장된 모습이다.

또 하나, 리더가 경과 시간을 잴 때는 벽시계(wall clock)가 아니라 단조 시계(monotonic
clock) 를 써야 한다. 벽시계는 NTP 보정으로 뒤로 점프할 수 있고, 그 순간 모든 리스의 남은
시간이 왜곡된다. JVM이라면 System.currentTimeMillis()가 아니라 System.nanoTime()
기반으로 재야 한다는, 코드 리뷰에서 실제로 잡아내야 하는 디테일이다.

TTL의 딜레마

짧게(1~2초): 장애 감지가 빨라 페일오버가 빠르다. 대신 잠깐의 네트워크 딸꾹질, JVM의
stop-the-world GC 한 번에도 리스가 날아간다 — 멀쩡한 노드를 죽었다고 오판하고(false
positive) 불필요한 재배정 폭풍이 인다. 길게(30초~수 분): 오판은 줄지만 진짜 죽은
노드를 그만큼 늦게 알아챈다. 실제 시스템들은 수 초 단위(ZooKeeper 세션 타임아웃, etcd
리스)에서 시작해 워크로드에 맞춰 조정한다. 정답이 없는 감시 민감도의 튜닝 문제다.

GC 멈춤과 펜싱 — 자가 감시로도 못 잡는 경우

홀더가 stop-the-world GC로 30초 멈췄다 깨어나면, 자기 리스가 만료된 줄 모르고 "아직
리더"라며 행동을 재개한다. 시계가 아니라 실행 자체가 멈췄으니 자가 감시로도 못 잡는다.
그래서 최후의 방어선은 언제나 펜싱 토큰이다. 이 조합(리스 + 펜싱)이 "Redis 분산
락(Redlock)은 펜싱 없이는 안전하지 않다"는 Martin Kleppmann의 유명한 비판의 요지이기도
하다 — 리스만 있고 펜싱이 없는 분산 락은 GC 멈춤 하나에 뚫린다.

코어 리더 페일오버 — 연장은 안전하고 단축은 위험하다

코어의 리더가 죽고 새 리더가 선출됐다. 새 리더는 복제 로그에서 리스 목록을 복원했지만,
각 리스의 "남은 시간"은 죽은 리더의 메모리(단조 시계 기준)에만 있었고 로그에는 없다. 새
리더는 어떻게 해야 할까. (a) 로그의 리스 생성 시각 + TTL로 만료 시점을 계산한다? (b) 모든
리스의 TTL을 지금부터 처음부터 다시 센다?

답은 (b)다. 이유는 두 겹이다.

첫째, (a)는 위험한 게 아니라 사실상 불가능에 가깝다. 단조 시계는 기점(origin)이
프로세스마다 제멋대로라 노드 간 비교가 아예 무의미하다. 죽은 리더의 단조 시계 값은 새
리더에게 의미 없는 숫자다. 벽시계 타임스탬프를 쓰자니 두 리더 간 시계 오차와 역행 문제가
그대로 들어온다.

둘째 — 더 본질적으로 — 안전성이 비대칭이다. (b)는 리스를 실질적으로 연장하는
행위다. 연장의 최악 시나리오는 이미 죽은 홀더를 TTL 한 사이클 늦게 알아채는 것 — 성능
손해일 뿐 정합성은 안 깨진다. 살아있는 홀더들은 어차피 하트비트로 계속 갱신하니 영향이
없다. 반면 (a)가 잘못되어 남은 시간을 실제보다 짧게 계산하면, 멀쩡히 일하던 홀더의 리스를
조기 회수하고 재배정한다 — 스플릿 브레인을 코어가 직접 만들어내는 꼴이다.

원칙 한 줄: 리스는 연장은 언제나 안전하고, 단축은 언제나 위험하다. 모르겠으면
연장하라. 이 사고방식 — 불확실할 때 어느 방향의 오류가 안전한지 먼저 정하고 그쪽으로
넘어진다 — 는 commit-wait(모르면 기다린다), 리스 만료 판정의 ε 여유(모르면 늦게 회수한다)와
같은 계보다. 분산 시스템 설계 전반을 관통하는 태도다.

실물들

ZooKeeper — 세션이 곧 리스다. 세션이 살아있는 동안만 존재하는 임시 노드(ephemeral
node)로 멤버십과 락을 표현한다. etcd — 리스가 일급 API다(grant로 TTL 받고,
keepalive로 갱신하고, 키에 리스를 붙이면 만료 시 키 자동 삭제). Kubernetes — 이 위에
지어졌다. 컨트롤러들의 리더 선출이 coordination.k8s.io/Lease 오브젝트로 돌아가고,
kubelet의 노드 하트비트도 리스 갱신이다.

4. 정리

일관성 코어는 "강한 일관성이 필요한 것은 메타데이터뿐"이라는 관찰에서 출발해, 합의는
작은 클러스터(3~5노드)에 맡기고 큰 데이터 클러스터는 그 결과를 따르게 하는 분업 구조다.
코어는 제어면에만 두고 데이터 경로에서 치우는 것이 계율이다.

리스는 그 코어 위에서 "소유"와 "생존"을 시간 제한부 계약으로 만든 것이다. 만료 판정은
코어 리더가 단조 시계로 단독 수행해 로그로 복제하고, 페일오버 시에는 TTL을 다시 세며(연장은
안전, 단축은 위험), 홀더의 자진 사퇴(1겹)와 펜싱 토큰(2겹)으로 스플릿 브레인을 막는다.

앞서 배운 패턴들이 전부 부품으로 재등장했다. 코어의 내부는 복제 로그 + 단일 갱신 큐 + 요청
대기 목록이고, 펜싱 토큰은 세대 시계이며, 만료 판정의 여유는 시계 제한 대기다. 패턴들은
낱개가 아니라 조립품이다.

참고 자료

『30가지 패턴으로 배우는 분산 시스템 설계와 구현 기법』 — 일관성 코어, 리스

시계 제한 대기 (Clock-Bound Wait)

Icarus8050 — Mon, 17 Aug 2026 20:58:05 +0900

시계 제한 대기 (Clock-Bound Wait) — 시계 오차를 시간으로 지불하기

1. 문제: HLC로도 안 잡히는 순서가 있다

HLC의 인과율 보장에는 숨은 전제가 있다. 인과가 시스템이 볼 수 있는 메시지를 타고 흐를
때만 작동한다는 것이다. max 규칙이 시계를 당겨주는 것은 타임스탬프가 실려 다닐 때뿐이다.
그런데 현실의 인과는 시스템 밖으로도 흐른다.

10:00.000  클라이언트1 → 서버 A에 쓰기: X = 1
           A의 시계는 빠름 → 실제보다 미래의 타임스탬프 부여
10:00.001  클라이언트1이 클라이언트2에게 슬랙으로 알림: "X 썼어, 확인해봐"
10:00.002  클라이언트2 → 서버 B에 쓰기: Y = 1
           B의 시계는 느림 → X보다 작은 타임스탬프 부여

실제 세계에서는 X가 Y보다 명백히 먼저다(슬랙 메시지가 인과 사슬이다). 그러나 시스템 안에는
그 사슬의 흔적이 없다 — 클라이언트2는 A의 타임스탬프를 들고 오지 않았으므로 HLC가 당겨줄
것이 없다. 결과적으로 나중 사건 Y가 더 작은 타임스탬프를 받을 수 있다. 이제 누군가 그
사이 시점의 스냅샷을 읽으면 Y는 보이는데 X는 안 보인다. 인과적으로 뒤인 것이 보이면서 앞인
것이 안 보이는 이상한 스냅샷이다.

이것을 막는 성질을 외부 일관성(external consistency) 이라 한다. 실시간으로 먼저 커밋된
트랜잭션은 반드시 더 작은 타임스탬프를 가져야 한다는 요구다.

2. 열쇠: 시계를 "점"이 아니라 "구간"으로 읽는다

시계에 오차가 있다는 것을 인정한다면, 정직한 시계 API는 이렇게 생겨야 한다.

now() → [earliest, latest]    "진짜 현재 시각은 이 구간 안 어딘가에 있다"

동기화 오차의 상한이 ε이면, 서버가 시계에서 pt를 읽었을 때 구간은 [pt−ε, pt+ε]이고 폭은
2ε이다. Google Spanner의 TrueTime이 정확히 이 API이며, GPS 수신기와 원자시계를
데이터센터에 설치해 ε을 수 ms 이내로 눌러놓았다. 오차를 없앨 수는 없지만 오차의 크기를
보장할 수는 있다 — 이것이 이 패턴 전체의 토대다.

세 개의 시간축

이 패턴을 추론할 때는 시간축을 구분해야 길을 잃지 않는다.

진짜 시각(true time): 우주의 실제 시각. 아무도 직접 읽을 수 없다. 분석할 때 쓰는
기준축이며, "실시간 순서(real-time order)"를 판정하는 심판용 축이다.
각 서버의 시계: 서버가 실제로 읽는 값. 진짜 시각에서 ±ε 이내로 어긋나 있지만, 서버
자신은 얼마나·어느 방향으로 어긋났는지 모른다.

시계 동기화가 보장하는 것은 단 하나, |서버 시계 − 진짜 시각| ≤ ε 이다. 구간 시계는 이
보장을 이용해 "내 시계 읽기"로부터 "진짜 시각이 있을 수 있는 범위"를 역산한 것이다.

3. 해법: 불확실성 구간이 지나갈 때까지 기다린다 (commit-wait)

Spanner의 쓰기(커밋) 절차는 다음과 같다.

1. 커밋 시각 결정: ts = now().latest        (구간의 위쪽 끝)
2. 대기: now().earliest > ts 가 될 때까지    (≈ 2ε 만큼)
3. 그 후에야 커밋을 노출하고 클라이언트에 응답

2번의 대기가 끝난 시점에는 진짜 시각이 확실히 ts를 지났다 — earliest조차 ts보다 크므로,
구간 어디에 진실이 있든 ts는 과거다. 그 말은 곧 어느 노드의 시계로도 "지금"은 ts 이후
라는 뜻이다(모든 시계의 오차가 ε 이내라는 보장 덕분에). 따라서 이 응답을 받은 클라이언트가
어떤 경로로든(슬랙이든 전화든) 인과를 이어가 어느 서버에 쓰더라도, 그 쓰기는 반드시 ts보다
큰 타임스탬프를 받는다.

숫자로 돌려보기 (ε = 5ms)

서버 A(시계 5ms 빠름)와 서버 B(시계 4ms 느림)가 있다. A가 대기 없이 즉시 응답하는 경우:

진짜 시각   A의 시계(+5)   B의 시계(−4)   사건
─────────────────────────────────────────────────────────────
10:00.100   10:00.105     10:00.096     A: 시계에서 105를 읽음
                                        → 구간 [100, 110] 계산
                                        → ts = 110 부여, 대기 없이 즉시 응답
10:00.101   10:00.106     10:00.097     클라이언트1 → 클라이언트2 슬랙
10:00.103   10:00.108     10:00.099     B: 쓰기 요청 받음, 시계에서 099를 읽음
                                        → 구간 [094, 104] 계산
                                        → ts = 104 부여

X의 타임스탬프는 110, Y의 타임스탬프는 104. 진짜 시각 기준으로 X(100)가 Y(103)보다 명백히
먼저인데 타임스탬프는 역전됐다. 원인은 하나다. A는 자기 시계가 빠른 줄 모르고 구간의 위쪽
끝(110)을 찍었는데 그것은 진짜 시각보다 10ms 미래의 숫자였고, 그 미래가 오기 전에
응답해 버렸다.

commit-wait를 지키면: A의 대기 종료 조건은 "내 시계가 115를 넘을 때"(pt−5 > 110)이고, 그
순간 진짜 시각은 110이다. 즉 A는 자기 타임스탬프가 진짜로 과거가 된 뒤에야 응답한다. 이후 B가
쓰기를 받는 시점엔 진짜 시각이 110을 넘었으므로, B의 시계가 최대로 느려도(−5ms) 105 이상을
읽고 latest는 110 이상이 된다. 역전의 여지가 닫힌다.

몇 가지 관찰:

대기 시간은 정확히 2ε이다. "latest로 찍고, 그 latest가 earliest 밑으로 내려올 때까지"
— 구간 폭만큼 기다린다.
위험 구간은 ts부터가 아니라 조기 응답의 순간부터 열린다. 위험의 본질은 "ts가 미래인
채로 세상에 공개된 상태"이고, 그 상태는 응답 즉시 시작된다.
역전은 비대칭 문제다. 위 예에서 B의 시계가 느린 게 아니라 4ms 빨랐다면, 진짜 103에
시계는 107을 읽고 latest = 112 > 110이라 역전이 나지 않는다. 역전은 "인과적으로 뒤에 쓰는
쪽의 시계가 느릴 때"만 발생한다. 그러나 누구의 시계가 어느 방향으로 어긋났는지 아무도
모르므로, 최악의 경우를 가정하고 기다리는 것이다.
A는 진짜 시각을 한 번도 보지 못한 채, 자기 시계와 ε 보장만으로 "진짜 시각에 대한
성질"을 확보했다. 이 패턴의 우아한 부분이다.

비용도 명확하다. 모든 쓰기가 2ε만큼 느려진다. Google이 원자시계에 투자한 이유다 — ε이
250ms면 모든 커밋이 0.5초씩 걸려 상용화가 불가능하지만, 7ms면 감당할 만하다. 하드웨어
투자가 소프트웨어 지연시간으로 직접 환산되는, 보기 드물게 정직한 트레이드오프다.

4. 변주: 쓰기 대신 읽기가 기다린다 — CockroachDB

원자시계가 없는 CockroachDB는 같은 문제를 반대쪽에서 푼다. 쓰기는 기다리지 않고 커밋한다.
대신 읽기가 불확실성을 떠안는다. 타임스탬프 ts로 읽는 트랜잭션은 (ts, ts + max_offset]
구간을 불확실 구간으로 취급하고, 이 구간에 있는 값을 만나면 — 시계 오차 때문에 실제로는 내
읽기보다 과거일 수 있는 값이므로 — 읽기를 더 높은 타임스탬프로 재시작한다(uncertainty
restart).

Spanner:     쓰기마다 2ε 대기 (항상, 예측 가능)  — 작은 ε을 하드웨어로 확보
CockroachDB: 걸린 읽기만 재시작 (가끔, 불규칙)   — 하드웨어 없이, max_offset은 크게

최근에는 AWS가 Time Sync Service로 마이크로초급 시계 동기화를 EC2에 제공하고
ClockBound라는 구간 시계 라이브러리를 공개하면서, "원자시계급 ε"이 클라우드 범용 인프라가
되어가고 있다. 10년 전엔 Google만 할 수 있던 설계가 보편화되는 중이다.

5. 정리 — 시간 3부작의 완성

이 패턴이 하는 일은 한 문장이다. "시계 오차가 유계(ε)라면, 그 오차만큼 기다리는 것으로
시계 오차를 없앤 것과 같은 효과를 산다." 불확실성을 제거할 수 없으니 시간으로 지불한다.
어디서 지불할지 — 쓰기에서 항상(commit-wait) vs 읽기에서 가끔(read restart) — 이 구현
선택의 갈림길이다.

시간 도구들의 지도를 완성하면:

도구	잡는 것	못 잡는 것
램포트 시계 / HLC	시스템 안 인과 (메시지를 탄 인과)	동시성 감지, 시스템 밖 인과
버전 벡터	동시성 감지	실시각, 시스템 밖 인과
시계 제한 대기	시스템 밖으로 흐른 인과 (외부 일관성)	— (비용: 쓰기 지연 or 읽기 재시작)

한 줄 요약: 미래의 타임스탬프를 달았으면, 그 미래가 올 때까지 입을 다물어라.

참고 자료

『30가지 패턴으로 배우는 분산 시스템 설계와 구현 기법』 — 시계 제한 대기

램포트 시계 & 하이브리드 시계

Icarus8050 — Mon, 17 Aug 2026 20:55:49 +0900

램포트 시계 & 하이브리드 시계 — 분산 시스템에서 시간을 다루는 법

1. 문제: 분산 시스템에 "지금"은 없다

서버들의 물리 시계는 어긋난다. NTP로 동기화해도 수 ms의 오차(clock skew)가 남고,
가상머신에서는 시계가 멈췄다 튀기도 하며, NTP 보정 과정에서 한 노드의 시계가 뒤로
점프하기도 한다. 시계가 뒤로 가면 "나중 사건이 더 작은 타임스탬프"를 받아 순서가 꼬인다.

그런데 곰곰이 보면, 우리가 정말 필요한 것은 "몇 시 몇 분"이라는 절대 시각이 아니라 대부분
"어떤 사건이 어떤 사건보다 먼저였는가"라는 순서다. Lamport의 1978년 논문("Time, Clocks,
and the Ordering of Events")의 통찰이 바로 이것이다. 시계를 버리고 순서만 남기자.

happened-before 관계

사건 a가 사건 b보다 먼저 일어났다(happened-before, a → b) 고 말할 수 있는 경우는 세
가지뿐이다.

같은 프로세스에서 a가 b보다 먼저 실행됐다.
a가 메시지 송신이고 b가 그 메시지의 수신이다.
a → c이고 c → b인 c가 있다(추이성).

이 셋으로 연결되지 않는 두 사건은 동시(concurrent) 다.

2. 램포트 시계 (Lamport Clock)

규칙 세 개짜리 알고리즘

각 노드는 정수 카운터 하나를 들고, 규칙 세 개를 따른다.

1. 로컬에서 사건이 일어나면: counter += 1
2. 메시지를 보낼 때: counter를 메시지에 실어 보냄
3. 메시지를 받을 때: counter = max(내 counter, 받은 counter) + 1

3번이 핵심이다. 메시지를 받는 순간 상대의 시간까지 반영해 내 시계를 앞으로 당긴다.
이 규칙 덕분에 다음이 보장된다.

a → b 이면 L(a) < L(b)

인과적으로 앞선 사건은 반드시 더 작은 타임스탬프를 갖는다. 물리 시계 없이, 정수 하나로.

예제로 직접 돌려보기

노드 A, B, C의 카운터가 모두 0에서 시작한다.

A: a1 발생        → counter = 1          (a1 = 1)
   B에게 전송      → 메시지에 1을 실음
B: 수신 = b1      → max(0, 1) + 1 = 2   (b1 = 2)
   b2 발생        → counter = 3          (b2 = 3)
C: c1 발생        → counter = 1          (c1 = 1)   ← C는 아무와도 통신 없음
   c2 발생        → counter = 2          (c2 = 2)

인과 사슬 a1 → b1 → b2를 따라 타임스탬프가 1 < 2 < 3으로 증가하는 것을 확인할 수 있다.
a1과 c1이 같은 타임스탬프 1을 갖는 것도 눈여겨보자. 동시 사건에서는 자연스러운 일이다.

역은 성립하지 않는다 — 이 패턴의 가장 중요한 문장

위 예제에서 c2 = 2 < b2 = 3이다. 그렇다면 "c2가 b2보다 먼저 일어났다"고 결론 내릴 수
있을까? 없다. B와 C는 통신한 적이 없으므로 두 사건은 동시이고, 숫자의 대소는 인과에
대해 아무것도 말해주지 않는다.

a → b 이면 L(a) < L(b)        ← 보장됨
L(a) < L(b) 라고 a → b는 아님  ← 동시 사건도 대소는 생긴다

여기서 정밀한 구분이 필요하다. 타임스탬프의 값 비교는 언제나 가능하다(램포트 시계는
결정적 알고리즘이다). 알 수 없는 것은 값이 아니라 그 대소가 의미하는 바다. "비교할 수
없다"와 "비교할 수 있지만 인과로 해석하면 안 된다"는 다른 진술이고, 이 구분이 흐려지면 설계
실수로 이어진다. 예컨대 LWW에 램포트 타임스탬프를 쓰면 항상 승자를 고를 수는 있지만, 그
승자가 "진짜 나중 쓰기"라는 보장은 없다. 버전 벡터라면 이 경우를 충돌로 보고했을 것이다.

즉 램포트 시계는 동시성을 감지할 수 없다. 버전 벡터와의 관계는 압축의 트레이드오프다.
버전 벡터는 노드 수만큼의 공간을 쓰는 대신 인과 관계를 온전히 보존하고, 램포트 시계는 정수
하나로 압축하는 대신 동시성 정보를 버린다.

전순서 만들기

타임스탬프가 같은 두 사건은 노드 ID로 타이브레이크하면 모든 사건의 전순서(total order)
를 만들 수 있다: (counter, nodeId) 쌍으로 비교. "정답인 순서"가 아니라 "모두가 동의하는
임의의 순서"지만, 인과율을 위반하지 않는다는 것이 중요하다.

실전에서는 순수한 램포트 시계 그대로보다 그 아이디어가 스며든 형태로 만난다. MVCC 저장소의
버전 번호(Versioned Value 패턴), etcd의 revision 번호가 그 예다.

3. 하이브리드 시계 (Hybrid Logical Clock, HLC)

문제: 램포트 시계는 사람의 시간과 무관하다

램포트 시계의 값은 인과율은 지키지만 실제 시각과 아무 관계가 없는 정수다. 두 가지가
아쉽다. 첫째, "어제 오후 3시 시점의 데이터 상태를 보여줘" 같은 시각 기반 쿼리가
불가능하다 — 3시가 램포트 값 몇에 해당하는지 알 길이 없다. 둘째, 통신이 잦은 노드의
카운터만 치솟는 식으로 값이 물리적 시간과 제멋대로 어긋난다.

그렇다고 물리 시계로 돌아가면 원점이다. 시계는 어긋나 있고, NTP 보정으로 뒤로 점프하면
인과율이 깨진다. 원하는 것을 정리하면:

값이 실제 시각과 가깝고
인과율을 보존하며 (a → b이면 반드시 증가)
물리 시계가 뒤로 가도 절대 역행하지 않는 타임스탬프

이 셋을 동시에 잡는 것이 HLC다.

구조: 물리 시각 + 논리 카운터

HLC = (l, c)
  l: 지금까지 관측한 물리 시각의 최댓값   ← "대략 몇 시인지"
  c: 같은 l 안에서 순서를 세는 논리 카운터 ← "l이 못 전진할 때의 램포트 카운터"

동작 원리는 램포트 시계의 max 규칙을 물리 시계와 합친 것이다.

로컬 사건/송신 시: 내 물리 시계 pt를 읽어서, pt가 현재 l보다 크면 l = pt, c = 0으로
전진한다(정상 상황). pt ≤ l이면 — 시계가 뒤로 갔거나 같은 밀리초 안에 여러 사건이 난 경우 —
l은 그대로 두고 c만 올린다.

수신 시: 램포트의 max 규칙 그대로 l = max(내 l, 메시지의 l, 내 pt)를 취하고, 최댓값이
어디서 왔느냐에 따라 c를 정한다. 내 pt가 제일 크면 c = 0, 메시지의 l이 제일 크면
c = 메시지의 c + 1, 내 l과 같으면 c = max(내 c, 메시지의 c) + 1.

요컨대 "l은 최대한 물리 시각을 따라가되, 따라갈 수 없을 때만 c로 순서를 만든다" 이다.

class HybridClock(private val wallClock: () -> Long) {
    private var l = 0L  // 관측된 최대 물리 시각
    private var c = 0L  // 논리 카운터

    @Synchronized
    fun now(): HlcTimestamp {                    // 로컬 사건/송신
        val pt = wallClock()
        if (pt > l) { l = pt; c = 0 } else c++   // 시계 역행/정체 시 c로 전진
        return HlcTimestamp(l, c)
    }

    @Synchronized
    fun onReceive(remote: HlcTimestamp): HlcTimestamp {
        val pt = wallClock()
        val newL = maxOf(l, remote.l, pt)
        c = when (newL) {
            l, remote.l -> maxOf(if (newL == l) c else 0,
                                 if (newL == remote.l) remote.c else 0) + 1
            else -> 0                             // 내 물리 시계가 최신
        }
        l = newL
        return HlcTimestamp(l, c)
    }
}

비교는 (l, c) 사전순(l 먼저, 같으면 c)이다. 구현 디테일 하나 — l에 밀리초 48비트, c에
16비트를 쓰면 전체가 64비트 정수 하나에 들어간다. 기존에 타임스탬프를 long으로 저장하던
시스템에 그대로 끼워 넣을 수 있다는, 채택을 결정지은 실용적 장점이다.

시계 역행 시나리오 — l은 절대 뒤로 가지 않는다

노드 A의 HLC가 (10:00.005, 0)인 상태에서 NTP 보정으로 물리 시계가 10:00.002로 뒤로
점프했고, 직후 로컬 쓰기가 두 번 들어왔다고 하자.

현재 상태: l = 10:00.005, c = 0
물리 시계: 10:00.002로 역행

첫 번째 쓰기: pt(10:00.002) ≤ l(10:00.005) → l 유지, c++ → (10:00.005, 1)
두 번째 쓰기: pt 여전히 ≤ l               → l 유지, c++ → (10:00.005, 2)
...
물리 시계가 10:00.006 도달: pt > l → l = 10:00.006, c = 0

여기서 흔한 착각이 "물리 시계를 따라 (10:00.002, 0)을 발급한다"는 것인데, 그러면 이미
발급된 (10:00.005, 0)보다 작은 타임스탬프가 나중 쓰기에 붙는다. 이 타임스탬프로 MVCC
버전을 정렬하는 저장소라면 나중 쓰기가 과거에 삽입되는 것이고, 같은 노드 안에서조차
인과율이 깨진다. l은 "내 물리 시계"가 아니라 "관측된 물리 시각의 최댓값"이며, max로만
갱신되므로 구조적으로 역행이 불가능하다. c는 물리 시계의 역행·정체로부터 타임스탬프의
단조성을 지키는 완충재다.

무엇이 보장되는가

인과율: a → b이면 HLC(a) < HLC(b). 램포트 시계의 성질이 그대로 유지된다. 역은 여전히
성립하지 않는다 — HLC도 동시성 감지는 못 한다. 그것은 버전 벡터의 일이다.

물리 시각 근접성: 노드들의 시계가 NTP로 ε 이내로 동기화되어 있다면, l과 실제 시각의
차이도 ε 수준으로 유계다. "오후 3시 시점"을 HLC 값으로 번역하는 것이 (ε의 오차 안에서)
가능해지고, 시각 기반 스냅샷 읽기가 열린다.

단조성: 물리 시계가 뒤로 점프해도 HLC는 절대 뒤로 가지 않는다.

실전 — 누가 왜 쓰는가

MongoDB는 클러스터 시간(cluster time)으로 HLC를 쓰고, 세션의 인과적 일관성(causal
consistency)을 이것으로 구현한다. 클라이언트가 마지막으로 본 HLC를 들고 다니면서 "이 시각
이후의 상태를 보여달라"고 요구하는 방식이다. CockroachDB, YugabyteDB는 분산 트랜잭션의
타임스탬프 정렬과 MVCC 스냅샷에 쓴다.

비교 대상으로 Google Spanner의 TrueTime이 있다. Spanner는 데이터센터에 GPS·원자시계를
설치해 "지금 시각은 [t-7ms, t+7ms] 사이"라는 유계 불확실성 구간을 하드웨어로 보장받고,
커밋 시 그 구간만큼 기다려서(commit-wait) 전역 순서를 만든다. HLC는 그런 하드웨어 없이
소프트웨어만으로 비슷한 효과를 노리는 접근이다. 불확실성 구간을 기다리는 아이디어는 책의
다음 패턴인 시계 제한 대기(Clock-Bound Wait)로 이어진다.

4. 정리 — 세 시계의 지도

시간 관련 도구 세 개를 한 줄씩으로 정리하면:

도구	형태	인과율 보존	동시성 감지	실시각 근접
램포트 시계	정수 1개	O	X	X
버전 벡터	노드별 카운터 맵	O	O	X
하이브리드 시계	(물리 시각, 카운터)	O	X	O

HLC는 버전 벡터의 대체재가 아니라 램포트 시계의 상위 호환이다. 동시성 감지가 필요하면
여전히 버전 벡터(또는 그 정보를 보존하는 다른 수단)가 필요하고, "모두가 동의하는, 실시각에
가까운, 절대 역행하지 않는 순서"가 필요하면 HLC가 답이다.

참고 자료

『30가지 패턴으로 배우는 분산 시스템 설계와 구현 기법』 — 램포트 시계, 하이브리드 시계

버전 벡터 (Version Vector)

Icarus8050 — Sun, 9 Aug 2026 21:28:04 +0900

1. 배경: 리더가 없는 복제

리더 기반 복제는 순서가 하나이므로 충돌이라는 개념 자체가 없다. 대신 대가가 있다. 리더가
죽으면 선출까지 쓰기가 멈추고, 지리적으로 분산된 환경에서는 모든 쓰기가 리더까지 왕복해야
한다.

그래서 반대편 설계가 있다. 아무 레플리카나 쓰기를 받는다(leaderless / multi-master).
Amazon Dynamo 논문이 대표이고 Riak, Cassandra, DynamoDB가 이 계열이다. 가용성은
극대화되지만 새로운 문제가 생긴다. 같은 데이터가 서로 다른 노드에서 동시에 갱신되면,
누가 최신인지 어떻게 아는가?

타임스탬프(LWW)로는 왜 안 되는가

"타임스탬프 붙여서 늦은 쪽이 이긴다"(Last-Write-Wins)는 두 가지 문제가 있다. 첫째, 서버들의
물리 시계는 완벽히 동기화되지 않는다(clock skew). 시계가 빠른 노드의 쓰기가 항상 이기는
왜곡이 생긴다. 둘째, 더 근본적으로 — LWW는 충돌을 감지하는 게 아니라 은폐한다. 두
클라이언트가 동시에 다른 값을 썼다면 병합이 필요한 사건인데, LWW는 한쪽을 조용히 버린다.
데이터 유실이 정책으로 내장된 셈이다.

필요한 것은 "더 최신이다"와 "동시였다(concurrent)"를 구분하는 능력이다. 단일 버전
번호로는 안 된다. 노드 A에서 v2가 되고 노드 B에서도 v2가 되면, 같은 v2라도 전혀 다른
값인데 구분할 방법이 없다.

2. 버전 벡터: 노드별로 카운터를 분리한다

해법은 버전을 숫자 하나가 아니라 노드별 카운터의 맵으로 관리하는 것이다.

{A: 2, B: 1}   ← "노드 A가 2번, 노드 B가 1번 갱신에 관여한 버전"

규칙은 단순하다. 노드가 쓰기를 처리할 때 자기 카운터만 1 올린다. 값이 레플리카 간에
전파될 때 버전 벡터도 함께 다닌다.

비교 규칙

두 버전 벡터 V1, V2에 대해:

모든 성분에서 V1 ≤ V2이면 → V2가 V1의 후손이다. V2는 V1을 "본 뒤에" 만들어진
갱신이므로 V1을 V2로 덮어써도 안전하다.
서로 어느 쪽도 전부 크지 않으면 — 예컨대 {A:2, B:1}과 {A:1, B:2} —
동시(concurrent)다. 서로가 서로를 모른 채 만들어진 갱신이며, 이것이 감지된 충돌이다.

data class VersionVector(val versions: Map<String, Long>) {
    fun increment(nodeId: String) =
        VersionVector(versions + (nodeId to (versions[nodeId] ?: 0) + 1))

    fun descendsFrom(other: VersionVector): Boolean =
        other.versions.all { (node, v) -> (versions[node] ?: 0) >= v }

    fun isConcurrentWith(other: VersionVector): Boolean =
        !descendsFrom(other) && !other.descendsFrom(this)
}

시나리오

장바구니 데이터가 {A:1} 버전으로 두 레플리카에 있는 상태에서 네트워크가 분단된다.

초기: cart = [빵], VV = {A:1}          (A, B 양쪽에 복제된 상태)

분단 중:
  클라이언트1 → 노드 A: 우유 추가 → cart = [빵, 우유], VV = {A:2}
  클라이언트2 → 노드 B: 계란 추가 → cart = [빵, 계란], VV = {A:1, B:1}

분단 복구, 동기화:
  {A:2} vs {A:1, B:1} → 어느 쪽도 후손이 아님 → 동시! 충돌 감지

분단이 없었고 클라이언트2가 {A:2}를 읽은 뒤 썼다면 결과는 {A:2, B:1}이 되고, 이것은
{A:2}의 후손이므로 조용히 덮어쓴다. 인과 관계가 있으면 자동 병합, 없으면 충돌 보고 —
이것이 버전 벡터가 하는 일의 전부다.

연습: 세 벡터의 관계

V1 = {A:2, B:1}, V2 = {A:2, B:2}, V3 = {A:3, B:0}일 때:

V1 vs V2: 모든 성분에서 V1 ≤ V2 → V2가 V1의 후손
V2 vs V3: A는 V3가 크고 B는 V2가 크다 → 동시(충돌)
V1 vs V3: 마찬가지로 동시(충돌)

V3는 A 성분이 가장 크지만 B의 갱신을 본 적이 없다. "총합이 크다"거나 "한 성분이 앞선다"로는
아무것도 결정되지 않는다. 비교는 언제나 성분 전체로 한다.

3. "자기 카운터만 올린다"는 규칙이 왜 중요한가

이 규칙을 어기면 무엇이 깨지는지 시나리오로 보자.

초기: VV = {A:1}, 양쪽에 복제됨

분단 중:
  노드 A가 쓰기 처리 → 자기 카운터 올림 → {A:2}, 값 = X
  노드 B가 쓰기 처리 → 규칙 위반, A의 카운터를 올림 → {A:2}, 값 = Y

분단이 복구되면 {A:2} vs {A:2} — 서로 다른 두 값이 동일한 버전 벡터를 갖는다. 비교
결과는 "같음"이므로 충돌이 감지되지 않고, 동기화 과정에서 한쪽이 조용히 덮어써진다.
충돌이어야 할 것이 인과 관계로 위장되는 것(false merge / lost update)이다.

규칙의 본질은 이것이다. 각 슬롯의 주인이 유일한 증가자여야, 벡터가 "이 버전이 각 출처의
갱신을 몇 개까지 반영했는가"의 정직한 기록이 된다. 버전 벡터의 부분 순서(partial order)가
실제 사건의 happened-before 관계와 일치한다는 보장은 이 "단독 소유권" 전제 위에서만
성립한다.

4. 충돌을 감지한 다음 — 해소의 실제 흐름

버전 벡터는 충돌을 감지할 뿐 해결하지는 않는다. 해소는 별도의 사이클이 담당한다.
Dynamo/Riak 스타일의 흐름을 처음부터 끝까지 따라가 보자.

장바구니 cart = [빵], 버전 {C0:1}이 저장돼 있고, 클라이언트 C1과 C2가 둘 다 이 상태를
읽은 뒤 동시에 갱신한다(행위자를 클라이언트 ID로 두는 방식).

C1: [빵] 읽음(VV {C0:1}) → 우유 추가해서 쓰기 → {C0:1, C1:1}, 값 [빵, 우유]
C2: [빵] 읽음(VV {C0:1}) → 계란 추가해서 쓰기 → {C0:1, C2:1}, 값 [빵, 계란]

어느 쪽도 후손이 아니므로 동시다. 서버는 이 시점에 어느 쪽도 버리지 않고 둘 다
형제(siblings)로 보관한다. 해소는 다음 읽기 때 일어난다.

어떤 클라이언트가 읽기 요청
  ← 서버 응답: 값 [빵,우유] 그리고 [빵,계란] (형제 둘 다)
              + 인과 컨텍스트: {C0:1, C1:1, C2:1}   ← 두 벡터의 상한(supremum)

클라이언트: 애플리케이션 로직으로 병합 → [빵, 우유, 계란]
클라이언트: 병합 결과를 받은 컨텍스트와 함께 다시 쓰기
  → 새 버전: {C0:1, C1:1, C2:1, C3:1}

마지막 쓰기의 벡터는 두 형제 모두의 후손이므로, 서버는 형제 둘을 지우고 하나로
수렴시킨다. 충돌은 "읽기 → 클라이언트 병합 → 컨텍스트를 실은 재쓰기" 사이클로 해소된다.

여기서 중요한 프로토콜 규칙이 보인다. 쓰기는 반드시 "내가 읽었던 버전의 인과 컨텍스트"를
실어 보내야 한다. 서버는 이 컨텍스트로 "이 쓰기가 무엇을 본 상태에서 만들어졌는가"를
판별한다. 낙관적 락의 버전 토큰과 정확히 같은 역할 — JPA의 @Version을 분산 환경으로
일반화한 것이라 봐도 좋다.

병합 정책의 세 층

병합 자체는 시스템이 못 해준다. [빵, 우유]와 [빵, 계란]을 어떻게 합칠지는 도메인
지식이기 때문이다.

애플리케이션 병합 — 클라이언트 코드가 도메인 규칙으로 합친다. 유연하지만 모든
클라이언트가 병합 코드를 가져야 하고, 단순 합집합 병합은 "삭제한 상품이 부활하는"
문제(합집합은 삭제를 표현할 수 없다)를 조심해야 한다. Amazon 장바구니의 유명한 일화가 바로
이 사례다.

CRDT — 병합이 수학적으로 항상 안전하도록 자료구조 쪽을 설계한다(아래 6장).

LWW 폴백 — 형제 관리가 복잡하니 타임스탬프 큰 쪽을 채택한다. 간단하지만 애써 감지한
충돌을 도로 버리는 것이므로 유실이 허용되는 데이터에만 쓴다. Cassandra가 기본값으로 이
방식을 택했다 — 단순함을 얻고 조용한 유실을 대가로 치른 것이다.

5. 행위자(actor)를 누구로 할 것인가 — 서버 ID vs 클라이언트 ID

카운터의 주인을 누구로 하느냐가 감지 정밀도를 좌우한다.

서버 노드 ID를 행위자로 하면 벡터가 노드 수만큼만 자라서 컴팩트하다. 하지만 같은 노드가
서로 다른 두 클라이언트의 쓰기를 연달아 처리하면 {A:1} → {A:2} → {A:3}처럼 일렬로 쌓여서,
실제로는 동시였던 갱신이 인과 관계처럼 보일 수 있다(충돌 미감지).

클라이언트 ID를 행위자로 하면 행위자가 다르면 벡터가 반드시 갈라지므로 감지가
정확해진다. 대신 키 하나의 벡터가 그 키를 건드린 모든 클라이언트 수만큼 자란다. 모바일
사용자 수백만이 행위자라면 벡터가 값보다 커진다. 오래된 항목을 잘라내면(pruning) 인과
정보가 유실되어 거짓 충돌이 늘어난다.

Riak은 결국 "서버 ID를 쓰되, 같은 노드가 처리한 서로 다른 쓰기를 점(dot)으로 구분한다"는
dotted version vector로 정착했다. 서버 ID의 컴팩트함과 클라이언트 ID의 정밀함을 동시에
잡는 절충이다.

용어 정리: 벡터 시계와의 구분

벡터 시계(vector clock) 와 자주 혼용되지만 엄밀히는 다르다. 벡터 시계는 프로세스 간
이벤트의 인과 관계를 추적하는 범용 도구이고, 버전 벡터는 데이터 객체의 버전 계보를
추적하는 특수화된 응용이다. 구조는 같지만 목적과 갱신 규칙이 다르다.

6. CRDT (Conflict-free Replicated Data Type)

이름 그대로 "충돌이 아예 발생하지 않도록 설계된 복제 자료구조" 다. 버전 벡터 세계에서
병합은 애플리케이션이 짜야 하는 골칫거리였다. CRDT는 발상을 뒤집는다. 병합 함수가
수학적으로 항상 안전하도록 자료구조 쪽을 설계하면, 충돌 해소라는 문제 자체가 소멸한다.

병합 함수 merge(a, b)가 세 가지 성질을 만족하면 된다.

교환법칙: merge(a, b) = merge(b, a) — 합치는 순서 무관
결합법칙: 셋 이상을 어떤 짝으로 묶어 합쳐도 동일
멱등성: merge(a, a) = a — 같은 것을 두 번 합쳐도 무해

이 셋이 성립하면 레플리카들이 어떤 순서로, 몇 번씩 중복해서 상태를 교환해도 결국 전부
같은 값으로 수렴한다. 네트워크가 지연시키든 중복 전달하든 상관없어진다. 프로토콜을 정교하게
만드는 대신, 데이터에 좋은 성질을 부여해서 프로토콜이 대충해도 되게 만드는 접근이다.

가장 간단한 예: G-Counter

전역 카운터 하나를 두면 동시 증가가 충돌하지만, 노드별 카운터의 맵으로 바꾸고 각 노드는
자기 슬롯만 올리게 한다. 값 = 전체 슬롯의 합, 병합 = 슬롯별 max.

data class GCounter(val counts: Map<String, Long>) {
    fun increment(nodeId: String) =
        GCounter(counts + (nodeId to (counts[nodeId] ?: 0) + 1))

    fun value() = counts.values.sum()

    fun merge(other: GCounter) = GCounter(
        (counts.keys + other.counts.keys).associateWith {
            maxOf(counts[it] ?: 0, other.counts[it] ?: 0)  // 슬롯별 max
        }
    )
}

어디서 본 구조인가 — 버전 벡터와 완전히 같은 뼈대다. "노드별 슬롯 + 자기 슬롯만 증가 +
성분별 비교/병합". 사실 버전 벡터 자체가 CRDT의 성질을 갖는 구조이고, 두 주제는 같은 수학
위에 서 있다.

표준 레퍼토리

여기서 층층이 쌓아 올린다. 감소도 필요하면 증가용/감소용 G-Counter 두 개를 붙인
PN-Counter, 추가만 되는 집합 G-Set, 삭제까지 필요하면 각 원소에 고유 태그를 붙여
"내가 본 태그만 삭제"하게 한 OR-Set(장바구니의 "삭제 부활" 문제를 이것으로 푼다), 단일
값이면 타임스탬프 큰 쪽을 취하는 LWW-Register 등이 표준이다.

실전 사례로는 Riak 내장 데이터 타입, Redis Enterprise의 액티브-액티브 복제, 그리고 협업
편집기(Yjs, Automerge — Figma/Notion류 도구들의 기반)가 있다. 협업 편집은 "오프라인에서
편집하고 나중에 동기화"가 본질이라 CRDT의 주 무대가 됐다.

한계

모든 도메인이 교환·결합·멱등 병합으로 표현되는 것은 아니다. "재고가 0 미만이 되면 안 된다"
같은 전역 불변식은 CRDT로 지킬 수 없다. 두 레플리카가 각자 마지막 재고를 팔면 병합
결과는 -1이다. 그런 요구사항은 결국 합의(복제 로그) 세계로 돌아가야 한다. 도구 선택의
기준이 여기서 갈린다.

7. 정리 — 두 세계의 지도

복제 로그와 버전 벡터는 같은 문제("여러 노드의 갱신을 정합성 있게")에 대한 두 극단의 답이다.

복제 로그는 순서를 하나로 강제해서 충돌을 원천 봉쇄한다(일관성 우선, CP 성향). 버전
벡터는 충돌을 허용하되 정확히 감지해서 나중에 병합한다(가용성 우선, AP 성향). 그리고
CRDT는 병합 자체를 수학으로 자동화해서, 충돌 허용 세계의 병합 비용을 없앤다.

어느 쪽이 옳은 것이 아니라 트레이드오프의 양 끝이고, 실제 시스템은 요구사항 — 유실을 얼마나
허용하는가, 전역 불변식이 있는가, 가용성이 얼마나 중요한가 — 에 따라 이 사이 어딘가에 선다.

참고 자료

『30가지 패턴으로 배우는 분산 시스템 설계와 구현 기법』 — 버전 벡터
Martin Kleppmann, 『데이터 중심 애플리케이션 설계』 5장 (리더리스 복제, 동시 쓰기 감지)

단일 갱신 큐 & 요청 대기 목록

Icarus8050 — Sun, 19 Jul 2026 20:54:31 +0900

1. Pattern 11 — 단일 갱신 큐 (Singular Update Queue)

문제: 여러 스레드가 동시에 WAL에 쓰려고 한다

WAL은 append-only 로그라서 어차피 한 번에 하나씩, 순서대로 써야 한다. 가장 먼저 떠오르는
방법은 락이다. 그런데 여기서 정확히 짚어야 할 것이 있다. 락도 "한 번에 하나"는 보장한다.
락의 문제는 상호 배제가 아니라 기다리는 방식에 있다.

락 방식에서는 요청을 처리하는 스레드 자신이 락을 잡으려고 블로킹된다. 스레드 100개가
append를 시도하면 99개가 잠들어 있고, 락이 풀릴 때마다 깨어나기 경쟁(컨텍스트 스위칭)을
한다. 스레드는 잠들어 있는 동안에도 스택 메모리를 점유하고, 경합 비용은 동시성이 올라갈수록
커진다. 처리량은 정체되는데 지연시간만 늘어나는 최악의 조합이다.

해법: 큐 하나 + 전용 스레드 하나

요청 스레드들 ──▶ [ 작업 큐 ] ──▶ 전용 스레드 1개 ──▶ WAL / 상태 갱신
   (넣고 바로 리턴)                (하나씩 순서대로 꺼내 처리)

모든 갱신 요청을 큐에 넣고, 전용 스레드 하나가 순서대로 꺼내 처리한다. 요청 스레드는
큐에 넣고 즉시 리턴한다. 블로킹이 아니라 비동기다. 결과는 나중에 받을 수 있도록 작업에
CompletableFuture 같은 응답 핸들을 붙여둔다.

Kotlin 코루틴과 Channel로 표현하면 다음과 같다.

class SingularUpdateQueue<T, R>(
    private val handler: suspend (T) -> R,
    scope: CoroutineScope,
) {
    private data class Work<T, R>(val item: T, val result: CompletableDeferred<R>)
    private val channel = Channel<Work<T, R>>(capacity = 1000)  // bounded!

    init {
        scope.launch {                    // 소비자는 단 하나의 코루틴
            for (work in channel) {
                work.result.complete(handler(work.item))
            }
        }
    }

    suspend fun submit(item: T): Deferred<R> =
        CompletableDeferred<R>().also { channel.send(Work(item, it)) }
}

이 구조가 주는 네 가지 이점

첫째, 상태에 락이 아예 필요 없어진다. WAL 파일이든 인메모리 상태든 오직 한 스레드만
만지므로, 동기화 코드 없는 순수한 단일 스레드 로직으로 작성할 수 있다. 경합 버그(race
condition)의 가능성이 구조적으로 제거되고, 코드를 추론하기 쉬워진다.

둘째, 순서가 공짜로 보장된다. 큐는 FIFO이므로 들어온 순서가 곧 처리 순서다. 복제
로그처럼 "순서가 곧 정합성"인 시스템에서 이것은 부가 기능이 아니라 핵심 요구사항이다.

셋째, 배칭이 자연스러워진다. 지난 글에서 다룬 그룹 커밋을 떠올려 보자. 전용 스레드가
큐를 비울 때 "지금 쌓여 있는 것 전부"를 꺼내 한 번의 fsync로 묶는 것이 아주 쉽다. 락
방식에서는 이런 배칭을 구현하기가 몹시 어색하다. 부하가 높을수록 배치가 커져 처리량이
오히려 좋아지는, 부하에 우아하게 대응하는 특성이 생긴다.

넷째, 호출자가 블로킹되지 않는다. 요청 스레드는 큐에 넣고 다른 일을 하러 간다.
스레드가 잠들어서 낭비되는 일이 없다.

반드시 챙겨야 할 것 — 유한 큐와 배압(backpressure)

큐를 무한(unbounded)으로 두면 소비 속도보다 유입이 빠를 때 큐가 무한히 자라 OOM으로
죽는다. 큐는 반드시 크기를 제한하고, 가득 찼을 때의 정책을 정해야 한다. 넣는 쪽을 잠시
블로킹하거나(위 코드의 channel.send가 이 방식), 즉시 에러를 반환해 클라이언트가
재시도하게 하거나. 어느 쪽이든 "밀려드는 부하를 상류로 알리는" 배압이 있어야 시스템이
과부하에서 붕괴하지 않고 버틴다.

주의: 전용 스레드는 짧고 예측 가능한 일만

전용 스레드가 느린 I/O나 무거운 계산으로 막히면 시스템 전체의 처리량 상한이 거기서
결정된다. 무거운 작업(직렬화, 검증 등)은 이 스레드 밖에서 미리 준비해 오고, 큐의 소비자는
"순서가 중요한 최소한의 갱신"만 하는 것이 원칙이다.

실제 사례

Raft 구현체들의 로그 append, Kafka 브로커의 요청 처리가 이 구조다. 극단적으로 최적화한
예로 LMAX Disruptor(큐를 링 버퍼로 바꿔 GC와 캐시 미스까지 제거)가 있다. 사실 Node.js의
이벤트 루프나 액터 모델(Akka)의 메일박스도 같은 아이디어의 변주다. "상태는 한 스레드에
가두고, 접근은 메시지로".

2. Pattern 12 — 요청 대기 목록 (Request Waiting List)

문제: 응답은 "나중에, 다른 스레드에서" 완성된다

단일 갱신 큐에서 요청 스레드는 큐에 넣고 바로 리턴한다. 그러면 클라이언트에게 보낼 응답은
언제, 누가 완성하는가? 복제 로그와 결합하면 문제가 선명해진다. SET x = 10 요청이 리더에
도착한 뒤의 타임라인이다.

t1: 요청 도착 → 단일 갱신 큐에 투입, 요청 스레드는 리턴
t2: 전용 스레드가 WAL에 append (인덱스 42 부여)
t3: 팔로워들에게 복제 전파          ← 여기서부터 "기다림"
t4: 팔로워들의 ack가 하나둘 도착
t5: 과반수 달성 → HWM이 42를 통과 → 커밋!
t6: 이제야 클라이언트에게 성공 응답 가능

문제는 t3~t5 구간이다. 팔로워의 ack는 언제 올지 모르는 비동기 이벤트다. 요청 스레드가
폴링하며 블로킹 대기하면, 단일 갱신 큐로 애써 없앤 블로킹을 도로 들여오는 꼴이다. 게다가
t6 시점에 실행되고 있는 것은 원래 요청을 받았던 스레드가 아니라 팔로워의 ack를 처리하던
전혀 다른 스레드다.

해법: 요청을 키와 함께 걸어두고, 이벤트가 오면 깨운다

리더는 로그 인덱스를 키로 하는 대기 목록(맵) 을 유지한다.

WaitingList: { 로그 인덱스 → 미완성 응답(Future/콜백) }

t2에서 append하고 인덱스 42를 받는 순간, 응답 핸들을 키 42로 대기 목록에 등록해 두고
잊어버린다. 이후 ack를 처리하던 스레드가 t5에서 HWM을 42 이상으로 전진시키면, 대기
목록에서 인덱스 ≤ 42인 항목들을 전부 꺼내 future를 완성시킨다. 그 완성이 곧 클라이언트
응답 전송으로 이어진다.

class RequestWaitingList<R> {
    private val waiting = ConcurrentHashMap<Long, CompletableDeferred<R>>()

    fun waitFor(logIndex: Long): CompletableDeferred<R> =
        CompletableDeferred<R>().also { waiting[logIndex] = it }

    // HWM이 전진할 때마다 호출됨 (ack 처리 스레드에서)
    fun onHighWaterMarkAdvanced(hwm: Long, resultFor: (Long) -> R) {
        waiting.keys.filter { it <= hwm }.forEach { index ->
            waiting.remove(index)?.complete(resultFor(index))
        }
    }
}

핵심 구조를 한 문장으로 말하면 이렇다. "요청 접수"와 "응답 완성"을 서로 다른 스레드가
담당하도록 분리하고, 그 둘을 키(로그 인덱스)로 연결한다. 어떤 스레드도 기다리느라 잠들지
않는다. 모두가 이벤트에 반응만 할 뿐이다.

반드시 챙겨야 할 두 가지

만료(expiration). 과반수 ack가 영영 안 오면? (네트워크 분단으로 리더가 소수 쪽에
고립된 경우 — 지난 글의 그 시나리오다.) 대기 목록의 항목이 무한히 기다리면 클라이언트도
무한히 기다린다. 각 항목에 타임아웃을 걸고, 주기적으로 목록을 순회하며 만료된 요청은
에러로 완성시킨다. 클라이언트는 에러를 받고 재시도하고, 그 재시도는 멱등 수신자가 안전하게
처리한다.

리더 교체 시 정리. 리더가 팔로워로 강등되면 대기 목록에 남은 요청들은 완성될 가망이
없다. 목록 전체를 "리더 아님" 에러로 비워서 클라이언트가 새 리더로 재시도하게 만든다.
커밋되지 못한 로그 엔트리가 잘려나가는 것과 짝을 이루는 정리 작업이다.

실제 사례

가장 유명한 구현이 Kafka의 Purgatory(연옥 — 이름부터 "응답이 기다리는 곳"이다)다.
acks=all 프로듀서 요청은 ISR 전체의 복제가 끝날 때까지, 컨슈머의 long-poll fetch 요청은
새 데이터가 도착할 때까지 purgatory에서 대기한다. 수십만 건의 대기 요청에 타임아웃을
효율적으로 걸기 위해 계층형 타이밍 휠(hierarchical timing wheel)이라는 자료구조까지
동원한다. etcd도 같은 구조로 커밋 대기를 처리한다.

애플리케이션 레벨에서도 이 구조는 낯설지 않다. Spring의 DeferredResult, 코루틴의
suspendCancellableCoroutine으로 만드는 비동기 API가 정확히 같은 모양이다. 요청을 받은
스레드는 핸들만 등록하고 리턴하며, 완성은 나중에 다른 스레드(이벤트)가 한다.

3. 세 패턴이 만드는 하나의 파이프라인

Pattern 10, 11, 12를 겹쳐 놓으면 리더 노드의 쓰기 경로 전체가 블로킹 없는 이벤트
파이프라인이 된다.

클라이언트 요청
    │
    ▼
[단일 갱신 큐] ── 순서 보장, 락 제거, 배칭(그룹 커밋)
    │
    ▼
WAL append → 복제 전파          [요청 대기 목록에 (인덱스 → 응답 핸들) 등록]
    │
    ▼
과반수 ack → HWM 전진 ──────────▶ 대기 목록에서 해당 인덱스 완성 → 응답 전송

단일 갱신 큐가 순서를, 복제 로그가 내구성을, 요청 대기 목록이 비동기 응답을 담당한다.
어느 스레드도 다른 스레드를 기다리며 잠들지 않고, 각자 자기 이벤트에만 반응한다. 이것이
합의 기반 시스템들이 강한 일관성을 보장하면서도 높은 처리량을 내는 구조적 비결이다.

참고 자료

『30가지 패턴으로 배우는 분산 시스템 설계와 구현 기법』 — Pattern 11 단일 갱신 큐, Pattern 12 요청 대기 목록
Martin Thompson et al., "LMAX Disruptor: High performance alternative to bounded queues"
Apache Kafka 문서 — Request Purgatory, Hierarchical Timing Wheels

복제 로그 패턴

Icarus8050 — Sun, 19 Jul 2026 20:53:38 +0900

1. 시작하기 전에 — 장애 모델과 비잔틴 결함

분산 시스템의 모든 설계는 "어떤 장애까지 견딜 것인가"라는 가정 위에 서 있다. 장애 모델은 크게 두 급으로 나뉜다.

크래시 결함(Crash Fault) 은 노드가 그냥 멈추는 것이다. 프로세스가 죽거나, 느려지거나, 네트워크가 끊긴다. 중요한 것은 거짓말은 하지 않는다는 점이다. 응답을 한다면 그 내용은 올바르다.

비잔틴 결함(Byzantine Fault) 은 노드가 임의의(arbitrary) 동작을 하는 경우다. 잘못된 데이터를 보내거나, 노드 A에게는 "값이 1"이라 하고 노드 B에게는 "값이 2"라고 모순된 응답을 하거나, 프로토콜을 의도적으로 위반한다. 원인은 악의적 공격일 수도 있고, 메모리 비트 플립이나 심각한 버그일 수도 있다. 이름은 Lamport의 1982년 논문 "비잔틴 장군 문제"에서 왔다. 배신자 장군이 섞여 있어도 충직한 장군들이 같은 결론(공격/후퇴)에 도달할 수 있는가 하는 문제다.

실무적으로 중요한 포인트는 두 가지다.

첫째, 이 책의 패턴들(Raft 포함)은 비잔틴 결함을 다루지 않는다. 크래시 결함 모델을 가정한다. 크래시 결함은 f개의 장애를 허용하는 데 2f+1 노드면 충분하지만(과반수 정족수), 비잔틴 결함까지 견디려면 3f+1 노드와 PBFT 같은 훨씬 무거운 프로토콜이 필요하다. 사내 데이터센터처럼 모든 노드를 우리가 통제하는 환경에서 비잔틴 내성은 과한 비용이다. 서로 신뢰할 수 없는 참여자가 섞이는 블록체인 같은 환경에서 비로소 BFT가 필수가 된다.

둘째, 그렇다고 아무 방어도 없는 것은 아니다. 악의는 아니지만 "데이터가 잘못 전달되는" 문제는 저렴한 수단으로 막는다. 네트워크/디스크 손상은 체크섬(CRC) 으로, 외부 침입자는 TLS와 인증으로. "비잔틴 합의는 안 하지만, 흔한 비잔틴스러운 사고는 값싸게 걸러낸다"가 실무의 균형점이다.

2. WAL (Write-Ahead Log, 선행 기입 로그)

해결하려는 문제

서버가 데이터를 메모리에만 들고 있으면 프로세스가 죽는 순간 전부 사라진다. 그렇다고 상태가 바뀔 때마다 전체 자료구조(해시맵, B-Tree 등)를 디스크에 통째로 쓰는 것은 너무 비싸고, 쓰는 도중 크래시가 나면 파일이 반쯤 깨진 상태가 될 수도 있다.

핵심 아이디어

상태를 바꾸기 전에, 그 변경 내용(명령)을 append-only 로그 파일에 먼저 기록한다. 그래서 이름이 Write-Ahead Log다.

클라이언트 요청: SET name = "chulyun"
  1. 로그에 append: {seq: 42, cmd: SET, key: name, value: chulyun} + fsync
  2. 그 다음에 메모리 상태(KV 스토어)에 적용
  3. 클라이언트에 응답

서버가 재시작되면 로그를 처음부터 replay해서 메모리 상태를 복원한다. 즉 로그가 진실의 원천(source of truth)이고, 메모리 상태는 로그의 파생물이다.

왜 이게 빠른가? 로그는 항상 파일 끝에 순차적으로만 쓴다(sequential append). 디스크는 랜덤 I/O보다 순차 I/O가 압도적으로 빠르기 때문에, "매 변경마다 디스크에 쓴다"는 부담이 현실적으로 감당 가능해진다. Kafka가 디스크 기반으로도 엄청난 처리량을 내는 이유가 정확히 이것이다.

구현 시 챙겨야 하는 디테일

각 로그 엔트리에는 단조 증가하는 로그 순서 번호(log sequence number) 를 붙인다. 이 번호가 복제 로그, 로우/하이 워터 마크 같은 패턴들의 기반이 된다. 쓰다가 크래시가 나면 마지막 엔트리가 반쯤 잘린 채 남을 수 있으므로 엔트리마다 CRC(체크섬) 를 기록해 두고, 재시작 시 손상된 엔트리를 감지해 버린다. 로그는 무한히 자랄 수 없으니 세그먼트 분할(Segmented Log) + 스냅샷 + 로우 워터 마크 이전 세그먼트 삭제로 관리한다.

Kotlin으로 뼈대만 그리면 다음과 같다.

class WriteAheadLog(private val file: RandomAccessFile) {
    private var lastLogSequence = 0L

    fun append(command: ByteArray): Long {
        val entry = WalEntry(++lastLogSequence, command, crc32(command))
        file.seek(file.length())          // 항상 끝에만 append
        file.write(entry.serialize())
        file.fd.sync()                    // fsync — 내구성 보장 지점
        return entry.sequence
    }

    fun readAll(): List<WalEntry> = TODO("재시작 시 replay용, CRC 검증 포함")
}

fsync 배치 처리 — 무엇을 얻고 무엇을 잃는가

fsync를 매 append마다 하면 안전하지만 느리고, OS 페이지 캐시에만 쓰고 응답하면 빠르지만 전원 장애 시 유실된다. 배치로 모아서 fsync하면 디스크 I/O 횟수가 줄어 처리량이 올라가는데, 여기서 유실 위험이 생기느냐 마느냐는 배치 자체가 아니라 "클라이언트에게 언제 응답하느냐"가 결정한다.

방식 A — ack 먼저, fsync 나중. append 후 바로 성공 응답을 주고 fsync는 주기적으로 모아서 한다. 처리량과 지연시간 모두 좋지만, 크래시 시 "성공했다고 답해놓고 사라진 데이터"가 생긴다. Redis AOF의 appendfsync everysec가 이 모드다.

방식 B — 그룹 커밋(group commit). 여러 요청의 append를 모아 fsync 한 번을 하되, fsync가 끝난 뒤에야 해당 배치의 클라이언트들에게 응답한다. 처리량은 똑같이 올라가고 유실은 없다. 잃는 것은 개별 요청의 지연시간이다. Postgres의 그룹 커밋, Kafka 브로커가 이쪽이다.

정리하면 배치는 처리량을 사고, 그 대가로 지연시간을 지불할지(방식 B) 내구성을 지불할지(방식 A) 선택하는 문제다. "성공 응답 = fsync 완료"라는 계약만 지키면 배치 자체는 안전하다. 이 트레이드오프가 Kafka의 acks, Postgres의 synchronous_commit 같은 설정으로 그대로 노출된다.

3. 복제 로그 — WAL을 여러 노드에

복제 로그(Replicated Log)는 WAL을 한 대가 아니라 여러 노드에 같은 순서로 복제하는 패턴이다. 핵심 전제는 상태 머신 복제(State Machine Replication)다.

모든 노드가 동일한 로그를 가지면, 동일한 순서로 replay했을 때 동일한 상태가 된다.

"같은 순서 보장"을 하는 것이 Raft/Paxos 같은 합의 알고리즘이고, 이 글은 Raft를 골격으로 설명한다.

왜 리더가 필요한가

아무 노드나 로그에 쓸 수 있게 하면 순서를 합의하는 문제가 매 엔트리마다 발생한다. 그래서 문제를 둘로 쪼갠다. (1) 리더를 하나 뽑는다. (2) 그다음엔 리더 혼자 로그 순서를 결정하고, 나머지(팔로워)는 그대로 복제한다. 합의라는 비싼 작업을 "엔트리마다"가 아니라 "리더가 바뀔 때만" 하도록 만드는 구조다.

4. 리더 선출 (Leader Election)

선출은 언제, 어떻게 일어나는가

평상시 리더는 팔로워들에게 주기적으로 하트비트를 보낸다. 팔로워는 각자 선출 타임아웃(예: 150~300ms 사이 랜덤값)을 두고, 그동안 하트비트가 안 오면 리더가 죽었다고 판단해 스스로 후보(candidate) 가 되어 선거를 시작한다.

이때 등장하는 것이 세대 시계(Generation Clock), Raft 용어로는 term이다. 후보는 자신의 term을 1 올리고, 자신에게 투표한 뒤, 다른 노드들에게 투표 요청을 보낸다. 과반수(quorum) 의 표를 얻으면 그 term의 리더가 된다.

과반수가 중요한 이유는 어떤 term에도 리더가 둘일 수 없음을 보장하기 때문이다. 각 노드는 한 term에 딱 한 번만 투표하고(이 투표 기록은 WAL에 영속화된다), 과반수 집합 두 개는 반드시 겹치므로 두 후보가 동시에 과반을 얻는 것은 불가능하다.

아무나 리더가 되면 안 된다 — 투표 조건

단순히 "빨리 손든 노드가 리더"가 되면, 로그가 뒤처진 노드가 리더가 되어 이미 커밋된 엔트리를 덮어쓸 수 있다. 그래서 투표 요청에는 후보의 마지막 로그 엔트리의 term과 인덱스가 담기고, 투표자는 이렇게 판단한다.

후보의 로그가 내 로그보다 뒤처져 있으면 거부한다.
(마지막 엔트리의 term이 높은 쪽이 최신, term이 같으면 로그가 긴 쪽이 최신)

커밋된 엔트리는 정의상 과반수 노드에 존재한다. 리더가 되려면 과반수의 표가 필요하다. 두 과반수는 반드시 겹치므로, 커밋된 엔트리를 갖지 않은 후보는 그 엔트리를 가진 누군가에게 반드시 거부당해 리더가 될 수 없다. 과반수 두 개가 겹친다는 사실 하나로 "커밋된 데이터는 리더가 바뀌어도 유실되지 않는다"가 증명된다.

스플릿 보트와 유령 리더

타임아웃이 비슷하게 만료되면 여러 노드가 동시에 후보가 되어 표가 갈릴 수 있다(split vote). 아무도 과반을 못 얻으면 선거는 무산되고 각자 랜덤한 타임아웃 후 재시도한다. 이 랜덤화 덕분에 다음 라운드에서는 누군가 먼저 깨어나 표를 쓸어갈 확률이 높아져 몇 라운드 안에 수렴한다.

네트워크 분단 후 구버전 리더가 돌아오는 경우는 term이 해결한다. 모든 메시지에 term이 실려 다니므로, 구 리더는 자기보다 높은 term을 보는 순간 즉시 팔로워로 강등되고, 노드들은 낮은 term의 요청을 거부한다. 세대 시계가 "과거에서 온 유령 리더"를 걸러내는 것이다.

실무에서의 두 갈래

직접 선출을 구현하는 시스템(etcd, Consul, Kafka KRaft)이 있는가 하면, ZooKeeper의 임시 노드(ephemeral node)처럼 외부 코디네이터에 선출을 위임하는 시스템도 많다(구세대 Kafka, HBase). 데이터 노드가 수백 대라면 그들끼리 과반 투표는 비현실적이므로, "합의는 작은 클러스터(3~5대)에 맡기고 나머지는 그 결과를 따른다"는 분업이 일반적이다.

5. 로그 복제와 하이 워터 마크 (High-Water Mark)

정상 흐름

클라이언트 쓰기 요청이 오면 리더는 (1) 자기 WAL에 append하고, (2) 팔로워들에게 엔트리를 전파하고, (3) 과반수가 자기 로그에 썼다고 응답한 순간 그 엔트리를 커밋으로 선언한다. 이 "여기까지는 커밋됐다"는 인덱스가 하이 워터 마크(Raft의 commitIndex)다. 리더는 HWM을 넘긴 뒤에야 상태 머신에 엔트리를 적용하고 클라이언트에 성공을 응답한다.

팔로워는 HWM을 스스로 계산할 수 없다. 과반수가 어디까지 복제했는지는 리더만 알기 때문이다. 그래서 리더는 다음 복제 요청이나 하트비트에 HWM을 실어서(piggyback) 전파하고, 팔로워는 그것을 받고서야 해당 지점까지 상태 머신에 적용한다.

로그의 각 엔트리는 세 단계를 거친다.

appended(리더 로그에 기록됨, 아직 사라질 수 있음)
→ committed / HWM 통과(과반수 복제 완료, 유실 불가)
→ applied(상태 머신에 반영됨)

이 구분이 복제 로그 이해의 절반이다.

네트워크 분단 시나리오 — 왜 HWM 아래에서만 읽어야 하는가

5노드 클러스터가 2대/3대로 분단되고 기존 리더가 2대 쪽에 있다고 하자.

3대 쪽에서는 하트비트가 끊기므로 새 리더 선출이 일어난다(과반 3/5 달성 가능). 2대 쪽 구 리더는 자기가 강등된 것을 모르므로 쓰기 요청을 받으면 일단 로그에 append하고 복제를 시도한다. 하지만 과반수 응답을 영영 못 받으므로 그 엔트리는 커밋되지 못하고, 클라이언트는 타임아웃을 받는다. 즉 정확히는 "쓰기가 거부된다"기보다 "커밋이 불가능하다"이다. 로그에 적히는 것과 커밋되는 것은 다른 사건이다.

분단이 복구되면 구 리더는 새 리더의 높은 term을 보고 팔로워로 강등되고, 커밋되지 못한 엔트리들은 잘려나가고 새 리더의 로그로 덮어써진다. 만약 커밋 전 데이터를 클라이언트에게 보여줬다면 "분명히 읽었던 데이터가 사라지는" 일이 생긴다. HWM은 "여기까지는 어떤 장애가 나도 사라지지 않는다"는 경계선이고, 그래서 읽기도 HWM 아래에서만 서빙한다.

팔로워 로그가 어긋나 있을 때

리더는 복제 요청에 "이 엔트리 직전 엔트리의 (인덱스, term)"을 함께 보낸다. 팔로워는 자기 로그의 그 위치에 같은 (인덱스, term)이 없으면 요청을 거부하고, 리더는 한 칸씩 뒤로 물러나며 일치 지점을 찾아 그 이후를 자기 로그로 덮어쓴다. 이 일관성 검사 덕분에 "팔로워의 로그는 리더 로그의 접두사(prefix)와 항상 일치한다"는 불변식이 유지되고, 새로 합류하거나 오래 죽어 있던 노드도 자동으로 따라잡는다.

심화: 이전 term의 엔트리는 세어서 커밋하면 안 된다 (Raft Figure 8)

새 리더는 이전 term의 엔트리를 "과반수에 복제돼 있네?"라고 세어서 커밋 처리하면 안 된다. 연쇄적인 리더 교체 상황에서 그렇게 커밋한 엔트리가 나중에 덮어써지는 반례가 존재한다(Raft 논문 Figure 8). 대신 새 리더는 자기 term의 no-op 엔트리를 즉시 append해서 복제한다. 이 no-op이 커밋되는 순간, 로그 일치 특성(Log Matching)에 의해 그 앞의 모든 엔트리도 함께 커밋 확정된다. 커밋 여부를 "판정"하는 게 아니라, 새 커밋을 만들어 이전 것들을 딸려서 확정시키는 것이다.

이 규칙은 다음 심화 질문의 답이기도 하다.

Q. 리더가 정족수를 달성해 커밋했지만, 커밋 인덱스를 팔로워에게 전파하지 못한 채 다운됐다. 새 리더는 이 엔트리를 어떻게 처리하나?

먼저, 새 리더는 그 엔트리를 반드시 가지고 있다. 엔트리는 과반수에 존재하고, 당선에는 과반수의 표가 필요하며, 투표 조건 때문에 그 엔트리를 가진 노드들은 엔트리가 없는 후보를 거부한다. 두 과반수는 겹치므로 데이터 자체는 유실되지 않는다. 다만 새 리더는 그것이 커밋됐는지 모르므로, 자기 term의 no-op을 커밋시켜 이전 엔트리들을 딸려서 확정한다. 구 리더가 클라이언트에 성공 응답을 이미 보냈더라도 약속은 지켜지고, 응답을 못 보냈다면 클라이언트의 재시도를 멱등 수신자가 처리한다.

6. 재시도와 중복 — 멱등 수신자 (Idempotent Receiver)

클라이언트가 쓰기 요청을 보냈는데 응답을 못 받고 타임아웃되면 재시도한다. 이때 같은 명령이 로그에 두 번 적히는 것을 막아야 한다.

구체적인 처리 방식

1단계 — 클라이언트 등록. 클라이언트가 처음 접속하면 리더에 등록하고 고유한 클라이언트 ID를 받는다. 이 등록 자체도 로그 엔트리로 복제된다. 그래야 리더가 바뀌어도 새 리더가 클라이언트 정보를 안다.

2단계 — 요청 번호 부여. 클라이언트는 모든 요청에 (클라이언트 ID, 요청 시퀀스 번호)를 붙인다. 재시도할 때는 같은 시퀀스 번호를 그대로 다시 보낸다.

3단계 — 서버 측 중복 감지와 응답 캐시. 서버는 클라이언트별로 "마지막으로 처리한 시퀀스 번호와 그때의 응답"을 저장한다.

fun handle(request: ClientRequest): Response {
    val session = sessions[request.clientId]
        ?: return Response.sessionExpired()

    return when {
        // 이미 처리한 요청 → 재실행하지 않고 저장해 둔 응답을 그대로 반환
        request.sequenceNumber <= session.lastProcessedSeq ->
            session.cachedResponse(request.sequenceNumber)

        // 새 요청 → 로그에 복제하고, 적용 후 응답을 캐시에 저장
        else -> replicateAndApply(request).also {
            session.record(request.sequenceNumber, it)
        }
    }
}

핵심은 응답까지 저장한다는 점이다. 중복을 감지만 하고 버리면 클라이언트는 결과를 영영 못 받는다. 그리고 이 세션 상태도 상태 머신의 일부로 취급되어 로그 적용과 함께 갱신된다. 리더가 바뀌어도 새 리더가 같은 로그를 replay하면 같은 세션 상태를 갖게 되므로, 재시도가 어느 리더에게 가든 중복 실행되지 않는다.

4단계 — 상태 정리. 클라이언트가 "시퀀스 N까지 응답을 잘 받았다"고 알려주면(다음 요청에 piggyback) 그 이전 캐시는 버린다. 세션에는 리스(lease)/타임아웃을 걸어 하트비트가 끊긴 클라이언트의 상태를 만료시킨다. 만료 후 뒤늦게 도착한 재시도는 거부할 수밖에 없다. 완벽한 exactly-once는 무한한 상태 없이는 불가능하다는 한계가 여기서 드러난다.

왜 UUID가 아니라 시퀀스 번호인가

임의의 UUID 키로도 중복 감지는 되지만, 본 적 있는 키를 전부 집합으로 들고 있어야 한다. 단조 증가하는 시퀀스 번호를 쓰면 "클라이언트별 마지막 번호 하나"만 기억해도 그 이하는 전부 중복으로 판정할 수 있어 저장 공간이 극적으로 줄어든다. Kafka의 멱등 프로듀서가 (Producer ID, 파티션별 시퀀스 번호)로 중복 배치를 걸러내는 것이 정확히 이 방식이다.

전달 보장 의미론으로 정리

재시도를 안 하면 at-most-once(유실 가능), 재시도만 하면 at-least-once(중복 가능), 재시도 + 멱등 수신자 = 사실상 exactly-once다. 즉 exactly-once는 마법 같은 전송 프로토콜이 아니라 "at-least-once로 배달하고 수신 측에서 중복을 제거한다"는 조합으로 만들어진다.

실무에서 HTTP API에 쓰는 Idempotency-Key 헤더(Stripe, 토스페이먼츠 결제 API 등)가 이 패턴의 응용이다. 키 저장소가 복제 로그가 아니라 DB나 Redis일 뿐, "키로 중복 감지 + 저장된 응답 재반환"이라는 구조는 동일하다.

7. 심화: 클러스터 멤버십 변경 (Membership Change)

노드 구성은 고정이 아니다. 그리고 구성 변경은 보기보다 위험하다.

왜 위험한가

3대 클러스터 {A, B, C}에서 {A, B, C, D, E}로 한 번에 바꾼다고 하자. 구성 변경 정보가 노드마다 도착하는 시점이 다르므로, 어느 순간 A, B는 구 구성(정족수 2/3)으로, C, D, E는 신 구성(정족수 3/5)으로 동작할 수 있다. 그러면 {A, B}가 구 구성 기준 과반으로 리더를 뽑고, 동시에 {C, D, E}가 신 구성 기준 과반으로 또 다른 리더를 뽑는 스플릿 브레인이 가능해진다. 정족수의 안전성은 "모두가 같은 구성을 본다"는 전제 위에 있는데, 과도기에 그 전제가 깨진다.

해법: 구성 자체를 로그로 합의한다

멤버십 구성을 설정 파일이 아니라 복제 로그를 통해 합의되는 데이터로 취급한다. 그 위에서 두 가지 방식이 있다.

단일 서버 변경(single-server change) — 실무의 주류. 한 번에 노드를 딱 하나만 추가/제거한다. 한 대씩만 바꾸면 구 구성의 과반과 신 구성의 과반이 수학적으로 반드시 겹치므로 리더 둘이 나올 수 없다. 5대로 만들려면 두 번 반복하면 된다. etcd가 이 방식이다.

공동 합의(joint consensus) — Raft 논문의 원래 방식. 한 번에 여러 대를 바꿀 때 과도기에 C(old,new)라는 중간 구성을 거치며, 이 기간에는 구 구성과 신 구성 양쪽 모두에서 과반을 얻어야 커밋과 선출이 가능하다. 안전하지만 구현이 까다로워 실제로는 단일 서버 변경이 선호된다.

새 노드는 로그가 빈 채로 합류하므로 바로 투표권을 주면 정족수 분모만 늘려 가용성을 해친다. 그래서 etcd 같은 시스템은 학습자(learner) 노드로 먼저 붙여 투표권 없이 로그를 따라잡게 한 뒤 정식 멤버로 승격한다.

8. 정리

Pattern 10의 골격은 세 겹이다.

WAL이 "변경을 먼저 순차 로그에 기록"함으로써 단일 노드의 내구성과 성능을 잡고, 리더 선출이 로그 순서 결정권의 유일성을 보장하며(term + 과반수 + 투표 조건), 복제와 하이 워터 마크가 유실 없는 커밋 경계를 만든다. 그 위에 멱등 수신자가 재시도로 인한 중복을 제거해 exactly-once 의미론을 완성하고, 멤버십 변경조차 로그를 통한 합의로 처리된다.

그리고 이 모든 것은 "노드가 거짓말은 하지 않는다"는 크래시 결함 가정 위에 서 있다. Kafka의 ISR과 high watermark, etcd/Raft의 commitIndex, ZooKeeper의 Zab이 전부 이 구조의 변주다.

참고 자료

『30가지 패턴으로 배우는 분산 시스템 설계와 구현 기법』 — Pattern 10 복제 로그
Diego Ongaro, John Ousterhout, "In Search of an Understandable Consensus Algorithm" (Raft 논문)
Leslie Lamport et al., "The Byzantine Generals Problem" (1982)
Martin Kleppmann, 『데이터 중심 애플리케이션 설계』 8~9장

Kotlin inline 함수의 noinline과 crossinline

Icarus8050 — Sat, 9 May 2026 18:26:31 +0900

Kotlin 코드를 읽다 보면 noinline, crossinline이라는 키워드를 종종 마주친다. 자주 보긴 하는데, 막상 직접 inline 함수를 작성하다 컴파일 에러가 나면 "어, 이거 어떤 상황에 뭘 붙여야 하더라?" 하고 매번 다시 찾아보게 된다. 헷갈릴 때마다 또 검색하지 않으려고 정리해둔다.

1. inline 함수와 람다 인라이닝의 기본

inline 함수는 호출부에 함수 본문이 그대로 펼쳐진다. 람다 파라미터도 마찬가지로 호출부에 인라이닝되기 때문에, 람다는 함수 객체로 존재하지 않는다.

inline fun doSomething(block: () -> Unit) {
    block()
}

fun caller() {
    doSomething { println("hello") }
    // 컴파일 후엔 사실상 아래와 같다
    // println("hello")
}

이 인라이닝 덕분에 두 가지 특성이 생긴다.

람다 객체 생성 비용 제거 (성능 이점) — 일반 람다는 매 호출마다 함수 객체를 생성하지만, inline 람다는 그렇지 않다.
non-local return 허용 — 람다 안에서 return을 쓰면 람다를 호출한 함수가 아니라 람다를 감싼 외부 함수에서 리턴된다.

inline fun doSomething(block: () -> Unit) {
    block()
}

fun caller() {
    doSomething {
        return  // caller() 자체에서 return됨 (non-local return)
    }
    println("이 줄은 실행 안 됨")
}

non-local return은 forEach 같은 inline 함수를 for 루프처럼 자연스럽게 쓸 수 있게 해준다.

fun findUser(users: List<User>, targetId: Long): User? {
    users.forEach {
        if (it.id == targetId) return it  // findUser에서 바로 리턴
    }
    return null
}

다만 이 특성은 동시에 뒤에서 볼 crossinline이 필요해지는 원인이기도 하다. 람다 안의 return이 외부 함수를 종료시킨다는 약속 때문에, 람다가 다른 컨텍스트로 캡처되는 상황에서 문제가 생기기 때문이다.

이 두 가지 특성이 noinline과 crossinline이 존재하는 근본 이유다.

2. crossinline — non-local return을 금지한다

왜 필요한가

inline 함수 안에서 람다 파라미터는 직접 호출(block())만 인라이닝 가능하다. 그 외의 사용 — 다른 람다 안에서 호출하거나, 다른 함수에 인자로 넘기거나, 변수에 저장하는 것 — 은 모두 금지된다.

inline fun runInThread(block: () -> Unit) {
    Thread {
        block()  // ❌ 컴파일 에러
    }.start()
}

여기서 Thread { ... }에 전달된 { block() }은 별개의 람다다. 즉 block을 그 안에서 호출하는 건 "직접 호출"이 아니라 다른 실행 컨텍스트로 캡처되는 호출이다.

컴파일러가 이를 막는 이유는 non-local return의 위험 때문이다. block이 일반 inline 람다라면 안에서 return을 쓸 수 있어야 하고, 그 return은 "runInThread를 호출한 함수에서 return"을 의미한다. 그런데 block()이 Thread의 Runnable 안으로 들어가 별도 스레드에서 나중에 실행된다면, 그 시점에 호출자 함수는 이미 끝났을 수 있다. 거기서 호출자 함수를 종료시키는 return은 물리적으로 불가능하다.

fun caller() {
    runInThread {
        return  // 어떤 스레드에서, 언제, 무엇을 종료시킬 것인가?
    }
}

컴파일러는 이 모순을 막기 위해 "다른 람다 안으로 캡처되는 inline 람다"를 아예 금지한다.

해결: crossinline

crossinline을 붙이면 "이 람다는 non-local return을 포기한다"고 컴파일러에게 약속하는 것이고, 그 대가로 다른 람다 안으로 캡처될 수 있다.

inline fun runInThread(crossinline block: () -> Unit) {
    Thread {
        block()  // ✅ OK
    }.start()
}

fun caller() {
    runInThread {
        // return  // ❌ 여전히 컴파일 에러: crossinline 람다 안에서는 non-local return 불가
        println("OK")
    }
}

3. noinline — 인라이닝 자체를 제외한다

왜 필요한가

inline 람다는 함수 객체로 존재하지 않기 때문에, 람다를 변수에 저장하거나 다른 함수에 전달하거나 반환할 수 없다. 람다를 "값"으로 다뤄야 한다면 인라이닝을 포기해야 하고, 그게 noinline이다.

// ❌ 컴파일 에러
inline fun wrong(block: () -> Unit): () -> Unit {
    return block  // 인라이닝된 람다는 반환할 수 없음
}

// ✅ noinline으로 해결
inline fun right(noinline block: () -> Unit): () -> Unit {
    return block
}

사용 예

inline 함수에 람다 파라미터가 여러 개 있고, 그 중 일부만 다른 함수로 넘겨야 할 때 사용한다.

inline fun doSomething(
    block1: () -> Unit,
    noinline block2: () -> Unit
) {
    block1()              // 인라이닝됨
    saveForLater(block2)  // block2는 함수 객체로 존재하므로 전달 가능
}

fun saveForLater(action: () -> Unit) { /* ... */ }

4. 세 키워드 비교

키워드인라이닝non-local return람다를 값으로 다루기

키워드	인라이닝	non-local return	람다를 값으로 다루기
inline (기본)	O	O	O
noinline	X	X	O
crossinline	O	X	X

핵심은 두 가지 축의 조합이다.

인라이닝 여부 → 람다 객체 생성 비용 / 람다를 값으로 다룰 수 있는지
non-local return 허용 여부 → 람다가 다른 컨텍스트로 캡처될 수 있는지

5. 실무에서 마주치는 패턴

Executor에 작업 제출

inline fun submitAsync(executor: Executor, crossinline task: () -> Unit) {
    executor.execute { task() }  // 람다 안에서 task 호출 → crossinline 필수
}

재시도 + 폴백

inline fun <T> retryWithFallback(
    maxAttempts: Int,
    crossinline action: () -> T,           // 재시도 루프 안에서 실행 → crossinline
    noinline fallback: (Throwable) -> T    // 다른 함수로 전달 → noinline
): T {
    repeat(maxAttempts - 1) {
        try {
            return action()
        } catch (e: Exception) { /* 재시도 */ }
    }
    return runFallback(fallback)
}

fun <T> runFallback(fb: (Throwable) -> T): T = fb(RuntimeException("failed"))

하나의 함수에서 crossinline과 noinline이 함께 쓰이는 예다.

Spring Data JPA Custom Query Method는 왜 SimpleJpaRepository의 @Transactional을 상속받지 못할까

Icarus8050 — Mon, 4 May 2026 00:45:05 +0900

TL;DR

SimpleJpaRepository에는 클래스 레벨 @Transactional(readOnly = true)와 쓰기 메서드(save, delete*)에 메서드 레벨 @Transactional이 붙어 있다.
이 어노테이션들은 SimpleJpaRepository에 실제로 정의된 메서드를 호출할 때만 적용된다.
findByName(...), @Query("...") 같은 사용자 정의(custom) query method는 SimpleJpaRepository에 시그니처 자체가 없기 때문에, Spring Data가 사용하는 RepositoryAnnotationTransactionAttributeSource의 fallback 경로에서 조기 종료되어 트랜잭션 어트리뷰트가 매칭되지 않는다.
Repository proxy에 들러붙는 또 다른 interceptor인 TransactionInterceptor 역시 같은 이유로 매칭에 실패한다 (자세한 메커니즘은 본문 §3에서 설명).
결과: custom query method는 별도 선언이 없는 한 @Transactional이 적용되지 않는다.

1. 배경: Repository Proxy에는 두 개의 TransactionInterceptor가 있다

Spring Data JPA Repository는 JDK Proxy로 만들어진 advice chain을 가진다. 이 chain에 들어가는 트랜잭션 관련 advice는 두 가지 경로로 구성된다.

Path A. TransactionInterceptor

@EnableTransactionManagement이 import하는 ProxyTransactionManagementConfiguration에서 컨테이너 기동 시 한 번 만들어진다.

// AbstractTransactionManagementConfiguration 에서 설정
@Bean
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
public TransactionAttributeSource transactionAttributeSource() {
	// Accept protected @Transactional methods on CGLIB proxies, as of 6.0
	AnnotationTransactionAttributeSource tas = new AnnotationTransactionAttributeSource(false);
	// Apply default rollback rule, as of 6.2
	if (this.enableTx != null && this.enableTx.getEnum("rollbackOn") == RollbackOn.ALL_EXCEPTIONS) {
		tas.addDefaultRollbackRule(RollbackRuleAttribute.ROLLBACK_ON_ALL_EXCEPTIONS);
	}
	return tas;
}

// ProxyTransactionManagementConfiguration 에서 설정
@Bean
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
public TransactionInterceptor transactionInterceptor(TransactionAttributeSource transactionAttributeSource) {
	TransactionInterceptor interceptor = new TransactionInterceptor();
	interceptor.setTransactionAttributeSource(transactionAttributeSource);
	if (this.txManager != null) {
		interceptor.setTransactionManager(this.txManager);
	}
	return interceptor;
}

// ProxyTransactionManagementConfiguration 에서 설정
@Bean(name = TransactionManagementConfigUtils.TRANSACTION_ADVISOR_BEAN_NAME)
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
public BeanFactoryTransactionAttributeSourceAdvisor transactionAdvisor(
		TransactionAttributeSource transactionAttributeSource, TransactionInterceptor transactionInterceptor) {

	BeanFactoryTransactionAttributeSourceAdvisor advisor = new BeanFactoryTransactionAttributeSourceAdvisor();
	advisor.setTransactionAttributeSource(transactionAttributeSource);
	advisor.setAdvice(transactionInterceptor);
	if (this.enableTx != null) {
		advisor.setOrder(this.enableTx.<Integer>getNumber("order"));
	}
	return advisor;
}

모든 빈에 적용 가능. TransactionAttributeSourcePointcut 이 매칭되는 Bean/Method 에만 advice 가 끼어든다.
매칭 조건: 메서드 또는 (선언/타깃) 클래스에 @Transactional 이 발견되는가.

Path B. Per-Repository TransactionInterceptor

각 Repository 빈이 만들어질 때 TransactionalRepositoryProxyPostProcessor 가 추가한다.

@Override
public void postProcess(ProxyFactory factory, RepositoryInformation repositoryInformation) {

	TransactionInterceptor transactionInterceptor = new TransactionInterceptor();
	transactionInterceptor.setTransactionAttributeSource(
			new RepositoryAnnotationTransactionAttributeSource(repositoryInformation, enableDefaultTransactions));
	transactionInterceptor.setTransactionManagerBeanName(transactionManagerName);
	transactionInterceptor.setBeanFactory(beanFactory);
	transactionInterceptor.afterPropertiesSet();
	factory.addAdvice(transactionInterceptor);
}

Repository proxy마다 새 인스턴스가 만들어진다.
핵심: 표준 AnnotationTransactionAttributeSource가 아니라 **RepositoryAnnotationTransactionAttributeSource**가 들어간다.

같은 TransactionInterceptor 클래스지만 인스턴스가 다르고, 들고 있는 TransactionAttributeSource도 다르다. 이게 "@Transactional 마킹 유무에 따라 동작이 달라 보이는" 현상의 정체다.

2. computeTransactionAttribute()는 언제 호출되나

TransactionInterceptor가 메서드 호출을 가로챌 때, 어트리뷰트 lookup 이 트리거된다.

JDK Proxy.invoke()
 └─ TransactionInterceptor.invoke(MethodInvocation)
   └─ TransactionAspectSupport#invokeWithinTransaction()
     └─ getTransactionAttributeSource().getTransactionAttribute(method, targetClass)
       └─ AbstractFallbackTransactionAttributeSource#getTransactionAttribute()
         ├─ attributeCache(MethodClassKey) HIT → 그대로 반환
         └─ MISS → computeTransactionAttribute(method, targetClass) ← 여기
              └─ 결과를 attributeCache에 put

Proxy 생성 시점에는 호출되지 않는다. postProcess()는 wiring 만 한다.
런타임에 각 메서드 첫 호출 시 단 1회 실행되고, 이후엔 MethodClassKey 기준으로 캐시된다.
주의: null 반환도 캐시된다. 트랜잭션 어트리뷰트를 찾지 못한 경우, NULL_TRANSACTION_ATTRIBUTE가 캐시에 저장되어 같은 메서드의 두 번째 호출부터는 lookup 자체가 일어나지 않는다. 디버깅 시 "왜 브레이크포인트가 한 번만 걸리지?"의 답이다.

3. 두 interceptor 모두 왜 custom query method 를 잡지 못하나

Path A와 Path B를 각각 따져보자.

3.1. Path B (RepositoryAnnotationTransactionAttributeSource)의 lookup 로직

표준 AnnotationTransactionAttributeSource에 한 단계가 더 붙은 형태다.

@Override
protected TransactionAttribute computeTransactionAttribute(Method method, Class<?> targetClass) {
	// Don't allow no-public methods as required.
	if (allowPublicMethodsOnly() && !Modifier.isPublic(method.getModifiers())) {
		return null;
	}

	// The method may be on an interface, but we need attributes from the target class.
	// If the target class is null, the method will be unchanged.
	Method specificMethod = ClassUtils.getMostSpecificMethod(method, userClass);

	// If we are dealing with method with generic parameters, find the original method.
	specificMethod = BridgeMethodResolver.findBridgedMethod(specificMethod);
    
	TransactionAttribute txAtt = null;

	// (1) user interface 메서드의 @Transactional
	txAtt = findTransactionAttribute(specificMethod);

	if (txAtt != null) {
		return txAtt;
	}

	// (2) declaring class 레벨 @Transactional
	txAtt = findTransactionAttribute(specificMethod.getDeclaringClass());

	if (txAtt != null) {
		return txAtt;
	}

	if (!enableDefaultTransactions) {
		return null;
	}

	// (3) 구현 클래스(SimpleJpaRepository)에서 동일 시그니처 lookup
	Method targetClassMethod = repositoryInformation.getTargetClassMethod(method);

	if (targetClassMethod.equals(method)) {
		return null;  // ← 핵심 분기
	}

	// (4) 구현체 메서드의 @Transactional
	txAtt = findTransactionAttribute(targetClassMethod);

	if (txAtt != null) {
		return txAtt;
	}

	// (5) 구현체 클래스의 @Transactional
	txAtt = findTransactionAttribute(targetClassMethod.getDeclaringClass());

	if (txAtt != null) {
		return txAtt;
	}

	return null;
}

getTargetClassMethod(method)는 "user interface에 선언된 메서드와 같은 시그니처를 갖는 구현 클래스(SimpleJpaRepository)의 메서드"를 찾는다.

구현체에 동일 메서드가 있으면 다른 Method 객체를 반환 → (4), (5)로 진행 → SimpleJpaRepository의 어노테이션이 적용된다.
없으면 입력 메서드를 그대로 반환 → targetClassMethod.equals(method) == true → null 반환, 종료.

Custom query method는 후자다. 여기서 Path B는 끝난다.

3.2. 그럼 Path A는 왜 못 잡나

여기서 자연스러운 질문이 생긴다. "Path B가 fallback에서 끊긴다 치자. Path A의 표준 AnnotationTransactionAttributeSource도 결국 같은 AbstractFallbackTransactionAttributeSource를 상속하는데, 이건 왜 SimpleJpaRepository 의 클래스 레벨 @Transactional(readOnly = true)를 매칭시키지 못하는가?"

답은 fallback이 검사하는 타입 계층에 있다.

표준 fallback 순서는 다음과 같다.

specificMethod (가장 구체적인 메서드)의 어노테이션
specificMethod.getDeclaringClass()의 어노테이션
method (원본 인터페이스 메서드)의 어노테이션
method.getDeclaringClass()의 어노테이션

핵심은 getMostSpecificMethod(method, targetClass)가 무엇을 반환하느냐다. Repository proxy의 targetClass는 SimpleJpaRepository이지만, custom query method는 SimpleJpaRepository에 시그니처가 없다. 따라서 가장 구체적인 메서드는 user interface의 메서드 그대로다.

그러면 fallback이 순회하는 대상은:

user interface 메서드 → 어노테이션 없음
user interface (= UserRepository) → 어노테이션 없음
(1과 동일)
(2와 동일)

UserRepository는 JpaRepository 인터페이스 계층을 상속할 뿐, SimpleJpaRepository 구현 클래스를 상속하지 않는다. 따라서 SimpleJpaRepository의 클래스 레벨 @Transactional(readOnly = true)는 fallback이 닿는 타입 계층 어디에도 들어오지 않는다.

정리: Path B는 "구현체에 같은 시그니처가 없으면 조기 종료"라는 명시적 분기 때문에, Path A는 "fallback이 인터페이스 계층만 훑고 구현 클래스에 도달하지 못하기 때문에" 매칭에 실패한다. 두 interceptor의 실패 이유는 미묘하게 다르지만, 결과적으로 custom query method는 어느 쪽으로도 트랜잭션 어트리뷰트를 받지 못한다.

4. 메서드 종류별 @Transactional 상속 여부

메서드 종류 출처 SimpleJpaRepository의 어트리뷰트 상속

save, delete*	CrudRepository 선언 + SimpleJpaRepository에서 override (메서드 레벨 @Transactional 직접 부여)	✅
findById, findAll, count, existsById 등 read-only CRUD	CrudRepository 선언 + SimpleJpaRepository override (메서드 어노 없음, 클래스 레벨만 적용)	✅ — 클래스 레벨 @Transactional(readOnly = true) 상속
findByName, @Query("..."), derived query	user interface에만 존재	❌
@Modifying 붙은 custom query	user interface에만 존재	❌ — 별도 @Transactional 없으면 실행 시 InvalidDataAccessApiUsageException: No EntityManager with actual transaction available for current thread - cannot reliably process 'remove'/'persist' call 발생

5. 왜 이렇게 설계되었나

@Transactional은 메서드 단위 메타데이터다. 클래스 레벨 어노테이션이 자식 메서드 시그니처에 자동으로 "상속"되지 않는 이유는 명확하다.

SimpleJpaRepository의 @Transactional(readOnly = true)는 이 클래스에 실제로 정의된 메서드 호출에 한해 의미를 가진다.
Custom query method는 SimpleJpaRepository에 정의된 메서드가 아니다. 이름이 같다는 보장도 없고, 같다 한들 의미가 같다는 보장도 없다.
Spring Data가 fallback 경로를 만든 건 CRUD 메서드 override 한정 편의 기능이지, 사용자가 새로 만든 메서드까지 자동으로 묶어주려는 의도가 아니다.

6. 디버깅 진입 포인트

코드를 직접 따라가며 검증하고 싶다면 다음 위치에 브레이크포인트를 두면 된다.

컨테이너 기동 시 global interceptor 생성: ProxyTransactionManagementConfiguration#transactionInterceptor
Repository proxy 빌드 시 per-repo interceptor 추가: TransactionalRepositoryProxyPostProcessor#postProcess
런타임 어트리뷰트 lookup: AbstractFallbackTransactionAttributeSource#getTransactionAttribute
Spring Data 전용 lookup 로직: RepositoryAnnotationTransactionAttributeSource#computeTransactionAttribute

TransactionInterceptor 인스턴스가 두 개라는 사실은, 위 두 생성 지점에서 System.identityHashCode(this.transactionAttributeSource)를 비교해보면 즉시 확인된다.

캐시 동작 때문에 lookup 메서드의 브레이크포인트는 메서드당 단 한 번만 걸린다는 점도 기억해두자. 같은 메서드를 재호출하며 디버깅하려면 attributeCache를 직접 비우거나, 다른 메서드 호출로 전환해야 한다.

Consistency Core 정리

Icarus8050 — Sun, 3 May 2026 15:54:09 +0900

강한 일관성을 보장하려면 노드 간 합의(consensus)가 필요하고, 합의는 노드 수가 늘어날수록 비용이 폭증한다. 그렇다고 일관성을 포기하면 데이터 정합성이 깨지고, 합의 비용을 감수하면 확장성이 천장에 부딪힌다.

이 딜레마에 대한 정형화된 해법이 Consistency Core(일관성 코어) 패턴이다. 이미 우리가 쓰고 있는 Kafka, Kubernetes, HDFS 같은 시스템들이 모두 이 패턴의 구체적인 구현체다.

이 글에서는 Consistency Core 가 무엇이고, 왜 필요하며, Kafka KRaft 를 중심으로 실제로 어떻게 구현되는지 정리해본다.

문제 정의: 합의 비용은 노드 수에 비례하지 않는다

분산 합의 알고리즘(Raft, Paxos)은 quorum, 즉 과반수 노드의 동의가 있어야 진행된다. 노드 수가 늘어나면 quorum 확보 비용이 어떻게 변하는지 보자.

노드 수 Quorum 합의 특성

3	2	빠르고 안정적
5	3	운영하기 좋은 균형점
7	4	합의 속도 저하 시작
100	51	사실상 불가능

100대 노드가 모든 결정을 합의로 처리한다고 상상해보자. 매 결정마다 51대 이상의 응답을 기다려야 하고, 한 노드만 느려도 전체가 대기한다. 네트워크 round trip이 노드 수에 비례해 늘어나고, 장애 복구는 더 오래 걸린다.

그렇다고 강한 일관성을 포기할 수도 없다. 클러스터 멤버십, 리더 정보, 설정 같은 정보는 모든 노드가 같은 view를 가져야 시스템이 안전하게 동작한다.

핵심 아이디어: Consistency Core

강한 일관성이 정말로 필요한 부분만 작은 클러스터로 분리하고, 나머지는 그 코어를 참조하면서 약한 일관성으로 운영한다.

                  ┌──────────────────────┐
                  │  Consistency Core    │
                  │  (3~5 노드, Raft)    │
                  │  - 강한 일관성       │
                  │  - 적은 데이터       │
                  │  - 모든 결정의 진실  │
                  └──────────┬───────────┘
                             │ (메타데이터 조회/구독)
              ┌──────────────┼──────────────┐
              │              │              │
         ┌────▼────┐    ┌────▼────┐    ┌────▼────┐
         │ Worker  │    │ Worker  │    │ Worker  │
         │ Node 1  │    │ Node 2  │    │ ... N   │
         └─────────┘    └─────────┘    └─────────┘
            (대량 데이터, 약한 일관성, 수평 확장)

코어는 작게 유지해서 합의 비용을 낮추고, 워커는 코어의 결정을 따르면서 자유롭게 수평 확장한다. 책임이 명확하게 분리되는 게 핵심이다.

무엇이 코어에 들어가고 무엇이 워커로 빠지는가

코어가 책임지는 것 (강한 일관성 필요, 양은 적음)

클러스터 멤버십: 어떤 노드가 살아있는가
Leader/Owner 정보: 각 파티션의 리더는 누구인가
설정/스키마: 토픽 설정, 권한
글로벌 카운터: producer ID, transaction ID
Lock/Lease: 분산 락, 임시 소유권

이 데이터들의 공통점은 양은 적지만 모두가 동일한 view를 가져야 안전하다는 점이다. 두 노드가 동시에 자기를 leader 라고 믿으면 split-brain 이 발생하고, 같은 producer ID 가 두 곳에서 발급되면 데이터 정합성이 깨진다.

워커가 책임지는 것 (양은 많고, 약간의 stale read 허용 가능)

실제 메시지/데이터
사용자 트래픽 처리
대용량 저장

반대로 이런 데이터들은 양이 압도적으로 많지만 노드별로 잠시 다른 view 를 가져도 큰 문제가 안 된다. 정확히 말하면 다른 메커니즘(예: leader-follower replication)으로 일관성을 따로 보장한다.

실제 사례

Kafka (KRaft)

Kafka 의 KRaft 가 Consistency Core 패턴의 교과서적 구현이다.

KRaft Controllers (3~5대) ← Consistency Core
  - 토픽/파티션 메타데이터
  - Leader election
  - Broker 등록 정보
  - Configuration

Brokers (수십~수백대) ← Workers
  - 실제 메시지 데이터
  - Producer/Consumer 처리

컨트롤러 quorum은 Raft로 강한 일관성을 보장하지만, broker는 그렇지 않다. Broker는 컨트롤러로부터 metadata를 fetch해서 자기 메모리에 캐시하고, 그 정보를 바탕으로 자기 partition의 데이터를 처리한다.

KRaft 이전에는 ZooKeeper가 외부 Consistency Core 역할을 했다. KRaft는 그걸 Kafka 내부로 흡수한 것이다. 외부 의존성을 줄이고, 메타데이터 처리 경로를 단순화한 결과물이다.

Kubernetes

etcd (3~5대) ← Consistency Core
  - Pod, Service, ConfigMap 정의
  - 클러스터 상태
  - Lease (leader election용)

kubelet (수천 노드) ← Workers
  - 실제 컨테이너 실행
  - 사용자 워크로드

API server는 etcd를 거쳐 모든 결정을 내리고, kubelet은 그 결정을 받아서 자기 노드에서 실행한다. 수천 대의 워커 노드가 있어도 etcd는 3~5대로 유지된다.

HDFS

NameNode (1~2대 HA) ← Consistency Core
  - 파일/디렉터리 메타데이터
  - 블록 위치 정보

DataNode (수백~수천대) ← Workers
  - 실제 파일 블록 저장

NameNode가 모든 메타데이터의 진실의 근원이고, DataNode는 실제 데이터를 저장한다. NameNode가 SPOF가 되는 문제 때문에 HA 구성이 필수가 되었고, 이것도 결국 작은 코어를 더 안전하게 만드는 방향으로 진화한 사례다.

비교: Cassandra의 다른 선택

Cassandra는 Consistency Core를 의도적으로 두지 않는다. Gossip 프로토콜로 모든 노드가 P2P로 상태를 교환한다. 이건 다른 trade-off다. Single point of bottleneck은 없지만, 강한 일관성을 보장하기 어렵고 운영 복잡도가 올라간다. Metadata-heavy하지 않고 write-heavy한 워크로드엔 더 적합한 모델이다.

이게 시사하는 바는, Consistency Core가 만능이 아니라 특정 trade-off를 선택한 결과라는 점이다. 워크로드 특성에 따라 다른 선택지가 더 나을 수 있다.

KRaft에서 본 두 layer의 leader election

Consistency Core 패턴을 깊이 이해하려면 Kafka KRaft가 leader election을 어떻게 처리하는지 보는 게 좋다. 여기에는 두 층위의 leader election이 있는데, 이 둘을 구분하지 못하면 동작 모델이 흐려진다.

Layer 1: Controller Quorum 내부의 Raft Leader Election

누가: 컨트롤러 노드들끼리 (3~5대)
무엇을: 컨트롤러 quorum 의 active controller 결정
방법: Raft 알고리즘 (term 증가 → vote 요청 → quorum 동의)
언제: 컨트롤러 기동, active controller 장애

Term을 올리고 표를 받고 과반을 확보하는 Raft의 정통 election 절차를 따른다.

Layer 2: 각 Topic Partition 의 Leader 결정

누가: Active controller가 결정
무엇을: 각 partition의 leader broker와 ISR
방법: 선거가 아니라 active controller의 단독 결정 (assignment)
언제: Topic 생성, broker 장애, partition reassignment

Broker는 컨트롤러에게 "내가 leader 할게요"라고 요청하지 않는다. 컨트롤러가 메타데이터와 정책을 보고 일방적으로 결정하고, broker들은 metadata log를 fetch하다가 자기 역할 변경을 인지한다.

Broker 장애 시의 흐름을 보면 이 모델이 명확해진다.

1. Broker 1이 죽음 (이 broker가 partition-0의 leader였음)

2. Active Controller가 broker 1의 죽음을 감지
   - Heartbeat 타임아웃으로 fenced 상태 전환

3. Active Controller가 영향받는 partition 스캔
   - ISR이었던 [1,2,3] 중 broker 1 제외한 [2,3]에서 새 leader 선택
   - preferred replica 순서로 → broker 2

4. 새 결정을 metadata log에 record로 append
   PartitionChangeRecord(
     topic=UUID-A, partition=0,
     leader=2,           ← 새 leader
     isr=[2,3],
     leaderEpoch=1       ← epoch 증가
   )

5. Controller quorum 내부 Raft 합의 → commit

6. 모든 broker가 변경을 fetch하고 자기 역할 인지
   - Broker 2: "이제 내가 partition-0의 leader구나"
   - Broker 3: "leader가 broker 2로 바뀌었네, 거기로 fetch해야지"

왜 임명 모델인가

왜 Layer 2는 선거가 아니라 임명일까. 두 가지 이유가 있다.

첫째, Consistency Core가 이미 권위 있는 진실의 근원이다. Controller 는 모든 broker 의 상태, ISR, leader 정보를 알고 있다. 이미 가진 정보로 결정할 수 있는 일을 굳이 broker 들끼리 분산 합의로 풀 이유가 없다.

둘째, ISR 정책이 결정론적이다. Kafka 는 leader 후보 선택에 명확한 규칙이 있다. ISR에 속한 broker만 후보가 되고, preferred replica order 에 따라 선택된다. 같은 metadata 상태에서 controller가 계산하면 항상 같은 답이 나온다. 결정론적인 일에 굳이 vote 메커니즘을 쓸 필요가 없다.

일관성 코어가 권위를 갖고 결정하면, 워커 입장의 복잡한 분산 합의를 피할 수 있다. 덕분에 수만 개의 partition에 대한 leader 결정을 모두 broker 끼리 선거를 할 필요가 없다.

패턴의 trade-off

얻는 것

워커 노드는 거의 무한 수평 확장 가능
코어는 작아서 합의가 빠름
책임 분리가 명확 (메타데이터 vs 데이터)
운영 모델이 단순 (한 곳만 보면 시스템 상태를 알 수 있음)

잃는 것

코어가 critical path에 있음 → 장애 시 전체 영향
- HA 구성 필수 (3~5대 quorum)
코어 용량이 시스템 전체의 천장이 됨
- 메타데이터를 무한정 코어에 넣을 수 없음
워커는 코어 정보를 캐시해서 쓰므로 약간의 stale read 발생
- eventual consistency를 받아들이는 설계 필요
모든 메타데이터 변경이 코어를 거쳐야 하므로 throughput 한계 존재

참고

WAL Compaction 설계기

Icarus8050 — Sun, 3 May 2026 04:39:39 +0900

"30가지 패턴으로 배우는 분산 시스템 설계와 구현 기법" 책으로 스터디를 하면서 머릿속으로만 이해했던 개념들을 직접 코드로 옮겨보고 싶었다. 그래서 작은 인메모리 KV 스토어 peacock을 만들기 시작했다. WAL을 붙이고, 시간이 지나니 자연스럽게 "로그가 무한히 자라는 문제"에 부딪혔다. 이 글은 그 문제를 풀어가며 마주친 설계 결정들과, 그것을 어떻게 정리했는지에 대한 기록이다.

WAL이 뭔가?

Write-Ahead Log는 이름 그대로 "변경을 메모리에 적용하기 전에 디스크에 먼저 기록한다"는 패턴이다. 데이터베이스 엔진의 거의 표준적인 영속성 메커니즘이다. PostgreSQL, MySQL의 InnoDB, RocksDB, LevelDB, etcd 등 안정성을 따지는 거의 모든 storage system이 어떤 형태로든 WAL을 갖고 있다.

이게 왜 필요한지는 단순한 시나리오로 명확해진다.

Put("a", 1)  → 메모리 맵에 적용
Put("b", 2)  → 메모리 맵에 적용
☠️ 크래시
재시작 → 메모리는 휘발됐다. 데이터 손실.

메모리만 가진 시스템의 운명이다. 영속성을 더하려면 디스크에 뭔가 남겨야 하는데, 매 쓰기마다 메모리 맵 전체를 디스크에 dump하는 건 비용이 크다. 그래서 차선의 답은 "변경 자체"를 디스크에 append하는 것이다. 메모리 맵을 통째로 저장하지 않고, "이런 일이 일어났다"는 사실만 기록한다.

Put("a", 1)  → ① 디스크 로그에 "Put a=1" entry append
              ② 메모리 맵에 적용
Put("b", 2)  → ① 디스크 로그에 "Put b=2" entry append
              ② 메모리 맵에 적용
☠️ 크래시
재시작 → 디스크 로그를 처음부터 끝까지 읽어 entry 순서대로 다시 적용
       → 메모리 맵이 크래시 직전 상태로 복원됨

이게 WAL의 핵심 아이디어다. 메모리 상태는 휘발성이지만, 그 상태를 만든 변경 이력은 디스크에 영속화돼 있다. 재시작 시 이력을 처음부터 다시 적용하면 마지막 상태가 재구성된다.

메모리에 적용하기 전에 로그가 먼저 디스크에 도달해야 한다. 만약 메모리에 먼저 쓰고 로그를 나중에 쓴다면, 두 단계 사이에 크래시 시 메모리에는 적용됐지만 로그엔 없는 변경이 생긴다 — 재시작 시 이 변경이 사라져 inconsistency가 발생한다. 그래서 디스크 로그가 항상 "선행"한다.

peacock의 KV는 이 패턴 그대로다.

PUT(k, v) →  ① WAL에 entry append (디스크에 fsync까지)
            ② 메모리 맵에 적용
GET(k)    →  메모리 맵에서 직접 lookup

각 entry는 다음 바이너리 레이아웃으로 직렬화된다.

TotalLen(4) | CRC32(4) | Op(1) | Index(8) | TimeStamp(8) | DataLen(4) | Data(var)
                        ↑─────────────── CRC32 대상 ──────────────────↑

TotalLen: entry body의 바이트 수. 다음 entry로 점프할 때 사용.
CRC32: 본문 무결성 체크. 디스크가 일부만 fsync된 상태에서 크래시한 경우(tail truncation)를 감지한다.
Op: OpPut 또는 OpDelete.
Data: KV 레이어가 정의한 페이로드 (KeyLen | Key | Value).

여러 entry가 하나의 segment 파일(wal-NNNNNNNNNN.log)에 append되고, segment가 일정 크기를 넘기면 다음 시퀀스 파일로 roll된다. 파일 하나가 무한히 커지지 않게 자르는 단위다.

인메모리 맵은 그저 빠른 lookup만 신경 쓰면 되고, 영속성은 WAL이 다 알아서 한다.

그런데 이 단순함이 곧 한계가 된다.

어쩌다 compaction까지 왔나

같은 키를 100번 덮어쓰면 WAL에는 100개 entry가 쌓인다. 99개는 replay 시 읽히기만 하고 버려지는 죽은 데이터다.

Put("counter", 1)   → entry 0
Put("counter", 2)   → entry 1
...
Put("counter", 1000) → entry 999

재시작하면 1000개 entry를 다 읽어 999번의 무의미한 덮어쓰기를 거친 뒤에야 최종 상태(counter=1000)에 도달한다. 디스크 점유와 startup 시간이 운영 시간에 비례해 선형으로 증가한다.

해결의 방향은 둘 중 하나다.

Snapshot은 주기적으로 메모리 맵 전체를 디스크에 덤프하는 방식이다. snap만 있으면 그 시점 상태를 즉시 복원할 수 있어 단순하다. 그런데 snapshot을 만드는 동안 메모리 맵의 상태를 일관되도록 잠궈야 하는 게 문제점이 있다. 쓰기 잠금을 걸면 stall이 발생하고, deepCopy로 우회하면 큰 맵에서 메모리 spike와 복제 stall이 따라온다.

Compaction은 로그가 롤링되어 더 이상 Write 되지 않는 WAL segment 파일을 읽어서 최신 상태의 엔트리 로그만 남긴 새 파일을 Write한다. 과거의 segment는 더 이상 쓰이지 않으니 메모리 맵과 어떤 자원도 공유하지 않기 때문에 제거할 수 있다. 이 과정은 백그라운드 goroutine이 디스크만 I/O하고 끝낸다. 덕분에 writer를 잠그는 시간을 최소화 할 수 있게 된다.

사이드 프로젝트 성격의 간단한 서버라 Snapshot 방식으로도 충분하지만 이왕 해보는거 Compaction 방식으로 구현해 보고 싶어서 이 방식을 택했다.

Phase 1: 매니페스트 도입

compaction을 하려면 "지금 살아있는 segment 파일은 정확히 어떤 것들인가?"를 파악해야 한다.

첫 시도는 디렉터리에 있는 wal-*.log를 모두 시퀀스 번호로 읽는 것이었다. 평상시엔 동작한다. 그런데 compaction 도중 죽으면 끔찍해진다.

T0: [1.log, 2.log, 3.log, 4.log, 5.log] (활성=5)
T1: 압축 시작 → 새 체크포인트 작성 중
T2: ☠️ 크래시
디스크 상태:
  - 1.log ~ 4.log: 옛 데이터
  - 5.log: 활성
  - tmp 또는 부분 체크포인트 파일: 알 수 없는 상태

이걸 디스크 스캔으로 다시 열면, "어디까지가 권위 있는 데이터인가"를 알 수 없다. 부분 파일을 합법적인 segment로 오인하면 데이터가 망가진다.

그래서 manifest파일에 segment 목록을 관리하도록 했다. 이 파일이 "지금 살아있는 segment는 정확히 이것뿐이다"를 체크할 수 있게 해준다.

manifest 파일 (v1) 레이아웃:
  Magic         (4)  "PCKM"
  Version       (2)  uint16, 1
  Reserved      (2)  uint16, 0 고정
  Generation    (8)  uint64, 갱신마다 단조 증가
  SegmentCount  (4)  uint32
  Records       SegmentCount × Seq(int64, 8)
  CRC32         (4)

이 파일이 가리키지 않는 모든 디스크 상의 wal-*.log는 고아로 간주해 무시한다. compaction 도중 죽어 부분 파일이 떠 있어도 매니페스트가 그것을 가리키지 않으면 무시된다. 덕분에 "어떤 파일이 진짜인가"라는 모호함이 사라진다.

Phase 2: Compaction

매니페스트가 자리잡으면 compaction의 큰 그림은 단순하다.

1. 과거의 segment를 읽어 키별 최신 값을 빌드
2. 결과를 새 체크포인트 파일에 직렬화
3. 매니페스트 갱신 → {checkpointSeq, [active]}
4. 과거의 segment 파일 제거

체크포인트의 결정

처음엔 가볍게 가정했다. segment 파일이 [1, 2, 3, 4, 5(활성화 상태)] 있다고 생각했을 때, "압축 결과도 그냥 또 하나의 segment 파일이지." 즉 봉인 [1..4]를 압축하면 새 segment seq를 부여해서(예: max+1=6) wal-6.log로 저장.

하지만 활성이 5인데 압축 결과가 6이라면 파일명이 의미상 1..5의 데이터를 담고 있는데 현재 Write 중인 5보다 높은 seq를 가지므로 "더 새로운 데이터"라는 직관에 어긋난다.

세 가지 옵션을 두고 고민했다.

옵션 (a) 옛 source의 seq 상속 + 덮어쓰기. 활성 세그먼트 이전의 max seq를 그대로 받아 컴팩션하고 그 자리를 덮어쓴다. 즉, 4.log가 압축본으로 바뀐다. 하지만 운영자가 디스크를 봤을 때 wal-4.log가 원본인지 압축본인지 식별 불가능하다. 중간에 예상치 못한 문제로 종료가 되면 WAL 로그 자체가 깨질 수 있다.

옵션 (b) max+1 새 seq. 압축 결과가 새 seq를 받는다. 모든 파일이 다른 seq를 가져 운영 식별이 명확하지만, WAL의 seq 필드가 두 의미를 짊어지게 된다 — "활성 식별"과 "다음 할당 카운터". 분리하려면 두 필드 필요.

옵션 (c) 별도 명명: *.checkpoint. 압축 결과는 wal-N.checkpoint라는 다른 이름. seq 공간 자체가 분리.

Before: [1.log, 2.log, 3.log, 4.log, 5.log]  활성=5
After:  [4.checkpoint, 5.log]                활성=5, seq counter=5
다음 roll: [4.checkpoint, 5.log, 6.log]      활성=6

체크포인트 seq는 흡수한 마지막 봉인 seq를 상속하지만, 파일명 suffix가 달라 활성과 절대 충돌하지 않는다.

(c)를 택한 결정적 이유는 "체크포인트는 segment와 의미가 다르다"는 인식이었다. 체크포인트는 스냅샷이고 segment는 이력이다.

비용은 매니페스트 포맷 변경 한 번. 매니페스트가 체크포인트의 존재를 알아야 하니 v1에 CheckpointSeq 필드를 추가한 v2를 만들었다.

manifest v2:
  Magic | Version=2 | Reserved | Generation | CheckpointSeq(8) | SegmentCount | Seq... | CRC
                                              ↑ v2 신규

0이면 "체크포인트 없음", > 0이면 wal-NNN.checkpoint가 매니페스트 segments보다 먼저 replay된다.

Compaction commit point

매니페스트 갱신은 단일 commit point가 되어야 한다. 압축 commit은 단일 syscall이 아니다. 여러 단계가 순차적으로 일어난다.

1. tmp 파일에 체크포인트 entry들 쓰기 (bufio + Sync)
2. tmp.Close
3. os.Rename(tmp → wal-N.checkpoint)
4. writeManifest(새 매니페스트)   ← tmp + rename + dir-fsync
5. 옛 segment / 옛 체크포인트 unlink

POSIX는 단일 syscall만 atomic하므로 이 묶음을 통째로 atomic하게 만들 수 없다. 그런데 매니페스트 갱신(4)을 commit point로 정의하면 어디서 죽어도 안전하다.

죽는 시점	디스크 상태	매니페스트	결과
1 도중	부분 tmp	과거	tmp는 다음 시도에서 `O_TRUNC`로 덮임
1 후, 3 전	완전한 tmp	과거	tmp는 다음에 덮임
3 도중	rename atomic — 과거 또는 새 버전 체크포인트	과거	어느 쪽이든 매니페스트 밖 → 무시
3 후, 4 전	완전한 새 버전 체크포인트	과거	매니페스트 밖 → 고아 무시
4 도중	atomic	과거 또는 새 버전	둘 다 정확
4 후, 5 전	과거 segment 잔존	새 버전	매니페스트 밖
5 도중	일부 unlink	새 버전	매니페스트 밖

매니페스트 갱신 이전에 죽으면 압축은 무효, 이후에 죽으면 적용된다.

동시 호출 보호

(*WAL).Compact는 공개 API다. 두 goroutine이 동시에 호출하면 같은 sealed 파일을 두 번 처리하고 매니페스트 갱신이 충돌한다.

goroutine A: BeginCompaction() → sealed=[1,2,3,4] 스냅샷
goroutine B: BeginCompaction() → sealed=[1,2,3,4] 같은 스냅샷
A: 파일 read + checkpoint write
B: 파일 read + checkpoint write
A: CommitCompaction([1,2,3,4]) → 성공
B: CommitCompaction([1,2,3,4]) → 검증 실패 (sealed에 더 이상 없음)
   → B의 체크포인트는 매니페스트 밖이라 고아로 남음

정확성은 무너지지 않지만 디스크 leak와 운영 잡음이 발생한다. 이를 해결하기 위해 WAL에 compacting bool 필드를 두고 락 안에서 체크하도록 했다.

func (w *WAL) beginCompaction(trigger int) (compactionPlan, bool) {
    w.mu.Lock()
    defer w.mu.Unlock()

    if w.closed || w.compacting {
        return compactionPlan{}, false
    }
    w.compacting = true
    return plan, true
}

압축 본체는 compacting 플래그가 true인 상태에서 락 밖으로 나가서 진행된다. 그래서 Append/roll은 압축의 read 단계와 동시 진행 가능하고(자원이 다르니까), 충돌 구간은 commit 시점뿐이다.