필드 번호를 바꿨더니 옛 클라이언트가 조용히 틀린 값을 읽었다
옛 클라이언트 앞에서 스키마를 바꾼다
목표
v1 스키마를 코드에 박아 둔 "옛 클라이언트" 를 그대로 둔 채 스키마를 v2 로 바꿉니다.
새 필드를 새 번호로 더하고, 지운 필드를 reserved 로 봉인하고, 일부러 번호를
바꾼 바이트를 옛 클라이언트가 어떻게 오류 없이 틀리게 읽는지 재현합니다. 그 뒤
기본값과 presence 의 함정을 실측하고, optional 과 reserved 를 갖춘 최종
스키마와 호환성 표를 남깁니다.
왜 중요한가
클라이언트와 서버는 절대 같은 순간에 배포되지 않습니다. 롤백도 있고, 로그에 남은 옛 바이트도 있습니다. 그래서 스키마 변경의 안전은 "컴파일이 되는가" 가 아니라 "옛 바이너리가 새 바이트를, 새 바이너리가 옛 바이트를 옳게 읽는가" 로 판단해야 합니다. 와이어에는 이름이 없고 번호만 있으므로, 번호를 바꾸는 것은 필드를 지우고 새로 만드는 것과 같습니다 — 그런데 파서는 아무 오류도 내지 않고 바뀐 번호의 값을 옛 이름으로 읽습니다. 이 실습은 그 사건을 재현해서 기억에 새기는 것이 목적입니다.
단계
python3 /opt/app/grpc/old_client.py /opt/app/grpc/order_v1.bin을 돌려 출력 네 줄을/root/grpc/evolve/01-old.txt에 그대로 저장하세요./root/grpc/evolve/v2.proto를 쓰세요.syntax = "proto3";로 시작하고message Order에 v1 의int32 id = 1; int32 qty = 2; string note = 3;을 그대로 두고int64 unit_price와string currency를 새 번호로 더합니다.- v2.proto 에서
note를 지우고reserved 3;과reserved "note";를 남기세요. 나머지는 그대로입니다. /root/grpc/evolve/make_v2.py에서/opt/app/grpc/pbmini.py로id=9001, qty=2, unit_price=15000, currency="KRW"를 v2.proto 의 번호대로 인코딩해/root/grpc/evolve/order_v2.bin에 저장하고, 옛 클라이언트로 그 파일을 읽은 출력을/root/grpc/evolve/04-old-reads-v2.txt에 저장하세요./opt/app/grpc/renumbered.bin은/opt/app/grpc/renumbered.proto(번호를 다시 매긴 스키마)로 만든 같은 주문입니다. 옛 클라이언트로 읽은 출력을/root/grpc/evolve/05-renumbered.txt에 저장하고, 그 아래에truth: id=<true-id> qty=<true-qty>한 줄과why: <why-no-error>한 줄을 적으세요.- pbmini 로
id=9002, currency="KRW"이고qty=0인 주문을 두 가지로 만드세요./root/grpc/evolve/06-zero.bin은 암묵적 presence(0 이면 보내지 않음),/root/grpc/evolve/06-zero-explicit.bin은 명시적 presence(0 도 보냄)./root/grpc/evolve/06-presence.txt에implicit=<hex>explicit=<hex>implicit_qty=<qty-read-by-old-client>explicit_qty=<qty-read-by-old-client>네 줄을 적으세요. - 최종
/root/grpc/evolve/Order.proto를 쓰세요.optional int32 qty = 2;,reserved 3;+reserved "note";,unit_price·currency, 그리고message Customer { string name = 1; int32 tier = 2; }와 Order 의Customer customer = <new-number>;가 들어갑니다. /root/grpc/evolve/compat.md에 마크다운 표를 쓰세요. 첫 열은add-new-numberremove-and-reservereuse-numberrenumberint32-to-stringrename-only여섯 키, 둘째 열은safe또는unsafe, 셋째 열은 이유 한 줄입니다.incident gc-zero-dropped로 사건을 내세요 — 세 창고에서 재고를 0 으로 맞춘 갱신만 반영되지 않습니다. 창고마다 원인을 가려/root/incident/gc-zero-dropped/report.txt에<warehouse>: <code>와evidence: <tap-line>을 적고, 0 이 병합기에 닿게 고친 뒤gz-sync로 다시 병합하세요.
참고
- 규칙의 원본: proto3 언어 안내 — 메시지 타입 갱신, 필드 presence.
old_client.py는 v1 스키마를 코드에 박아 둔 프로그램입니다. 출력은id=qty=note=unknown=네 줄입니다. 6단계에서 두 파일을 각각 읽혀 보세요.- pbmini 사용:
import sys; sys.path.insert(0, "/opt/app/grpc"); import pbmini as pb; pb.encode_message([(1, "int32", 9001), (2, "int32", 2)]). - 채점기는 .proto 를 관대하게 읽습니다(주석·공백 자유). 그러나 번호 재사용, reserved 누락, 타입 변경은 반드시 떨어집니다.
- 8단계의
rename-only는 바이너리 와이어 기준입니다 — 와이어에 이름이 없으니 이름만 바꾸는 것은 바이트에 영향이 없습니다(JSON·텍스트 형식에서는 다릅니다). - 9단계는 사건입니다. 6단계에서 본 「0 을 보낸 것과 안 보낸 것」 이 현장에서는 스키마·송신 코드·중간 홉 어디서든 갈립니다. 병합기·중계기는 이미 배포된 프로그램이라 바꿀 수 없고,
patches.json·base.json·stock.json을 손으로 맞추는 것은 고친 것이 아닙니다. 가격만 바꾸는 갱신이 수량을 0 으로 덮어서도 안 됩니다. 이 실습은 60분 안팎이고 세션이 끝나면/root의 작업물이 사라지니, 길어지면 세션을 연장하세요.
옛 클라이언트로 v1 바이트를 읽는다
python3 /opt/app/grpc/old_client.py /opt/app/grpc/order_v1.bin 의 출력 네 줄을 /root/grpc/evolve/01-old.txt 에 그대로 저장하세요.
방향: 옛 클라이언트는 .proto 를 다시 읽지 않고, 번호 1·2·3 을 id·qty·note 라고 믿고 읽습니다. 그 출력을 기록으로 남깁니다.
도구: 디렉터리 만들기와 셸 리디렉션 >.
구체: 손으로 옮겨 적지 말고 출력을 그대로 저장하세요 — 채점기가 같은 명령을 다시 돌려 비교합니다.
새 필드는 새 번호로
/root/grpc/evolve/v2.proto 에 v1 의 세 필드를 그대로 두고 int64 unit_price 와 string currency 를 새 번호로 더하세요.
방향: 있던 필드의 번호·이름·타입은 한 글자도 바꾸지 않고, 새 필드는 지금까지 쓰인 적 없는 번호를 받습니다.
도구: proto3 문법 — syntax = "proto3";, message Order { <type> <name> = <number>; }.
구체: 19,000–19,999 는 구현이 예약한 구간이라 쓸 수 없고, 1–15 는 태그가 한 바이트라 자주 쓰는 필드에 좋습니다. unit_price 는 int64, currency 는 string 입니다.
지운 번호를 봉인한다
v2.proto 에서 note 를 지우고 reserved 3; 과 reserved "note"; 를 남기세요.
방향: 지우는 것 자체는 와이어에 안전합니다. 위험은 나중에 누가 그 번호를 다시 쓰는 것이고, reserved 는 protoc 이 그것을 거절하게 하는 장치입니다.
도구: reserved <number>; 와 reserved "<name>";.
구체: 번호와 이름은 한 문장에 섞어 쓸 수 없어 두 줄로 씁니다. message 블록 안 어디에 있어도 됩니다.
v2 바이트를 옛 클라이언트가 읽는다
/root/grpc/evolve/make_v2.py 에서 pbmini 로 id=9001, qty=2, unit_price=15000, currency="KRW" 를 v2.proto 의 번호대로 인코딩해 /root/grpc/evolve/order_v2.bin 에 저장하고, 옛 클라이언트로 읽은 출력을 /root/grpc/evolve/04-old-reads-v2.txt 에 저장하세요.
방향: 새 번호로 더한 필드는 옛 클라이언트에게 모르는 필드입니다 — 와이어 타입으로 길이를 알아 건너뛰고, 아는 필드는 옳게 읽습니다.
도구: pbmini 의 encode_message([(field, kind, value), ...]) 와 옛 클라이언트.
구체: 번호는 2단계 v2.proto 에서 고른 그대로 쓰고, 지운 note 는 넣지 않습니다. 옛 클라이언트 출력의 unknown= 줄에 새 번호 둘이 보여야 합니다.
번호를 바꾼 바이트를 옛 클라이언트가 읽는다
옛 클라이언트로 /opt/app/grpc/renumbered.bin 을 읽은 출력을 /root/grpc/evolve/05-renumbered.txt 에 저장하고, truth: id=<true-id> qty=<true-qty> 와 why: <why> 두 줄을 덧붙이세요.
방향: 누군가 번호를 다시 매겼습니다. 와이어에는 번호만 있으니 옛 클라이언트는 번호 1 을 여전히 id 로 읽습니다.
도구: /opt/app/grpc/renumbered.proto, 옛 클라이언트, 그리고 renumbered.proto 의 번호대로 직접 읽은 값.
구체: 같은 주문을 그 스키마로 직렬화한 것이 renumbered.bin 입니다. 와이어 타입이 같은 VARINT 라 오류도 경고도 없습니다 — truth 줄은 renumbered.proto 대로 읽은 진짜 값입니다.
qty=0 은 보낸 것인가 안 보낸 것인가
id=9002, currency="KRW", qty=0 인 주문을 /root/grpc/evolve/06-zero.bin(암묵적 presence, 0 은 보내지 않음)과 /root/grpc/evolve/06-zero-explicit.bin(명시적 presence, 0 도 보냄)으로 만들고, /root/grpc/evolve/06-presence.txt 에 implicit= explicit= implicit_qty= explicit_qty= 네 줄을 적으세요.
방향: proto3 의 라벨 없는 스칼라는 기본값(0, 빈 문자열)을 직렬화하지 않습니다. optional 이 붙으면 0 도 보냅니다.
도구: pbmini 로 메시지 두 개를 만들고, 바이트를 .hex() 로 보고, 각각을 옛 클라이언트로 읽습니다.
구체: 명시적 쪽에는 필드 2 레코드 10 00 두 바이트가 더 실립니다. 그런데 옛 클라이언트는 두 경우 모두 qty=0 으로 읽습니다 — 그 구별 불가가 optional 이 필요한 이유입니다.
optional 과 reserved 를 갖춘 최종 스키마
/root/grpc/evolve/Order.proto 를 쓰세요 — optional int32 qty = 2;, reserved 3; + reserved "note";, int64 unit_price·string currency, message Customer { string name = 1; int32 tier = 2; } 와 Order 의 Customer customer = <new-number>;.
방향: optional 은 0 과 「없음」 을 가르고, reserved 는 지운 번호를 봉인하고, 서브메시지는 별도 message 를 타입으로 씁니다.
도구: optional 라벨, reserved, message Customer { ... } 와 Order 안에서 그 타입을 쓰는 필드.
구체: customer 의 번호는 지금까지 쓰인 적 없고 reserved 도 아닌 것이어야 합니다. 바이너리 와이어에서 라벨을 붙이는 것 자체는 바이트를 바꾸지 않습니다(0 을 보내게 될 뿐입니다).
호환성 표를 쓴다
/root/grpc/evolve/compat.md 에 마크다운 표를 쓰세요. 첫 열은 add-new-number remove-and-reserve reuse-number renumber int32-to-string rename-only, 둘째 열은 safe/unsafe, 셋째 열은 이유입니다.
방향: 이 실습에서 직접 본 것을 정리하는 단계입니다 — 각 행의 근거가 앞 단계 하나씩입니다.
도구: 4단계(새 번호로 추가), 3단계(지우고 reserved), 5단계(번호 바꿈)의 결과와 와이어 타입 표.
구체: 타입 변경은 와이어 타입이 바뀌면(VARINT → LEN) 옛 파서가 다른 뜻으로 읽고, 이름만 바꾸는 것은 바이너리 와이어에 이름이 없으니 바이트가 같습니다. 판정 낱말은 safe 또는 unsafe 하나만 — 채점기는 행에서 처음 나오는 것을 봅니다.
사건: 0 으로 맞춘 갱신만 사라진다
incident gc-zero-dropped 를 실행하세요. 세 창고(icn·pus·gmp)에서 재고를 0 으로 맞춘 갱신만 반영되지 않습니다 — 다른 갱신은 멀쩡하고 오류도 없습니다. 창고마다 원인을 가려 /root/incident/gc-zero-dropped/report.txt 에 <warehouse>: <code> 세 줄을 적으세요. 코드는 implicit-presence · merge-skips-zero · omit-empty · relay-reserialize · wrong-number 중 하나입니다. 창고마다 고치기 전 gz-tap 출력에서 0 이 사라진 자리를 보여 주는 줄 하나(0 으로 맞춘 갱신의 stage=sent 또는 stage=recv)를 evidence: <tap-line> 로 붙이세요. 틀린 코드로 세 번 채점하면 사건이 잠겨 다시 내야 합니다(원인이 새로 정해집니다). 그리고 0 이 병합기에 닿게 송신기 쪽(/srv/gz/<warehouse>/producer.*)을 고친 뒤 gz-sync 로 다시 병합하세요.
방향: 증상은 셋이 같지만 0 이 사라지는 홉이 다릅니다 — 송신기가 아예 싣지 않는가(보낸 바이트에 10 00 이 없음), 실었는데 중간에서 사라지는가(보낸 것에는 있고 받은 것에는 없음).
도구: gz-tap <warehouse> 의 stage=sent·stage=recv 두 줄을 나란히, 그리고 producer.proto 의 qty 라벨과 producer.conf 의 omit_empty·route. 중계기 두 판의 스키마는 /opt/fixtures/grpcc/gz/ 에 있습니다.
구체: 싣지 않았다면 스키마(라벨)와 설정(생략 목록) 중 어느 쪽인지, 사라졌다면 어느 판의 중계기를 거쳤는지 봅니다. 고친 뒤에는 gz-sync 를 다시 돌려야 stock.json 이 바뀌고, 가격만 바꾼 갱신이 수량을 0 으로 덮지 않는지도 확인하세요.