TT Lab
블로그 시작하기
배우기 러닝패스 코스

필드 번호를 바꿨더니 옛 클라이언트가 조용히 틀린 값을 읽었다

옛 클라이언트 앞에서 스키마를 바꾼다

TT Lab 에서 이어서 보기

목표

v1 스키마를 코드에 박아 둔 "옛 클라이언트" 를 그대로 둔 채 스키마를 v2 로 바꿉니다. 새 필드를 새 번호로 더하고, 지운 필드를 reserved 로 봉인하고, 일부러 번호를 바꾼 바이트를 옛 클라이언트가 어떻게 오류 없이 틀리게 읽는지 재현합니다. 그 뒤 기본값과 presence 의 함정을 실측하고, optional 과 reserved 를 갖춘 최종 스키마와 호환성 표를 남깁니다.

왜 중요한가

클라이언트와 서버는 절대 같은 순간에 배포되지 않습니다. 롤백도 있고, 로그에 남은 옛 바이트도 있습니다. 그래서 스키마 변경의 안전은 "컴파일이 되는가" 가 아니라 "옛 바이너리가 새 바이트를, 새 바이너리가 옛 바이트를 옳게 읽는가" 로 판단해야 합니다. 와이어에는 이름이 없고 번호만 있으므로, 번호를 바꾸는 것은 필드를 지우고 새로 만드는 것과 같습니다 — 그런데 파서는 아무 오류도 내지 않고 바뀐 번호의 값을 옛 이름으로 읽습니다. 이 실습은 그 사건을 재현해서 기억에 새기는 것이 목적입니다.

단계

  1. python3 /opt/app/grpc/old_client.py /opt/app/grpc/order_v1.bin 을 돌려 출력 네 줄을 /root/grpc/evolve/01-old.txt 에 그대로 저장하세요.
  2. /root/grpc/evolve/v2.proto 를 쓰세요. syntax = "proto3"; 로 시작하고 message Order 에 v1 의 int32 id = 1; int32 qty = 2; string note = 3; 을 그대로 두고 int64 unit_price 와 string currency 를 새 번호로 더합니다.
  3. v2.proto 에서 note 를 지우고 reserved 3; 과 reserved "note"; 를 남기세요. 나머지는 그대로입니다.
  4. /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 에 저장하세요.
  5. /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> 한 줄을 적으세요.
  6. 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> 네 줄을 적으세요.
  7. 최종 /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>; 가 들어갑니다.
  8. /root/grpc/evolve/compat.md 에 마크다운 표를 쓰세요. 첫 열은 add-new-number remove-and-reserve reuse-number renumber int32-to-string rename-only 여섯 키, 둘째 열은 safe 또는 unsafe, 셋째 열은 이유 한 줄입니다.
  9. incident gc-zero-dropped 로 사건을 내세요 — 세 창고에서 재고를 0 으로 맞춘 갱신만 반영되지 않습니다. 창고마다 원인을 가려 /root/incident/gc-zero-dropped/report.txt 에 <warehouse>: <code> 와 evidence: <tap-line> 을 적고, 0 이 병합기에 닿게 고친 뒤 gz-sync 로 다시 병합하세요.

참고

옛 클라이언트로 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 으로 덮지 않는지도 확인하세요.