VarInt 인코더 / 디코더

VarInt 인코더 / 디코더가 동작하는 방식

도구가 하는 일

VarInt 도구는 부호 없는 정수를 Protobuf 스타일의 LEB128 가변 길이 정수로 인코딩하고, 이진 VarInt 스트림을 다시 정수 목록으로 디코딩합니다. 각 값은 크기에 따라 1~10바이트로 인코딩되며, 각 바이트의 최상위 비트가 뒤에 더 많은 바이트가 오는지 여부를 나타냅니다. 출력은 테스트와 픽스처에 쉽게 포함할 수 있도록 바이트 배열, 16진수, 또는 Base64로 표시됩니다.

개발자들이 흔히 사용하는 사례

Protobuf 와이어 포맷 페이로드를 디버깅하는 엔지니어는 전체 Protobuf 런타임을 띄우지 않고도 VarInt 인코드/디코드를 사용해 필드 태그와 부호 없는 정수 필드 값을 확인합니다. 비트코인 및 기타 암호화폐 개발자는 VarInt로 인코딩된 스크립트 길이와 트랜잭션 개수를 파싱합니다. 또한 작은 수에 대해 매우 압축적인 LEB128을 채택한 커스텀 이진 프로토콜을 리버스 엔지니어링할 때도 유용합니다.

데이터 형식, 타입 또는 변형

LEB128(Little-Endian Base 128)은 바이트당 7비트의 페이로드를 내보내며, 최상위 비트는 연속(continuation) 플래그로 동작합니다. 작은 수(0~127)는 1바이트를 사용하고, 16,383까지는 2바이트를 사용하는 식으로 확장됩니다. 입력은 공백, 쉼표, 또는 줄바꿈으로 구분된 10진수를 받습니다. 출력은 16진수, Base64, 그리고 원시 바이트 배열 표기로 제공됩니다. 부호 있는 정수는 먼저 ZigZag 변환 (n << 1) ^ (n >> 31)을 적용하여 인코딩할 수 있습니다.

흔한 함정과 엣지 케이스

JavaScript 숫자 정밀도는 2^53 − 1에서 끝나며, Number.MAX_SAFE_INTEGER를 초과하는 값은 안전하게 인코딩할 수 없습니다. 잘린 VarInt 스트림(종료 바이트 누락)은 부분적으로 디코딩되며 오프셋을 나타내는 오류를 반환합니다. 음수는 직접 인코딩할 수 없으므로 먼저 ZigZag 인코딩을 사용하세요. Base64 패딩이 제거되었을 수 있는 스크린샷에서 VarInt 바이트를 복사하는 것은 피하세요. 패딩이 누락되면 바이트 경계가 달라집니다.

코드 대신 이 도구를 사용해야 하는 경우

디버깅 중이거나 테스트를 작성하는 동안 Protobuf 와이어 바이트를 빠르게 확인하려면 브라우저 도구를 사용하세요. 프로덕션 인코딩에는 언어별 네이티브 VarInt 라이브러리(npm의 `varint`, Go의 encoding/binary에 있는 `binary.varint`, Python의 google.protobuf.internal에 있는 `decode_varint`)를 사용하세요. 이들은 스트리밍, 오류 복구, ZigZag 변환을 한 번의 호출로 처리합니다.