[PR #3449] raw_block checkpoint payload zlib 압축

[!tldr] 업무 관점 takeaway Daejun의 PR #3449는 checkpoint payload를 zlib으로 압축해 동일 ceiling 안에 ~5배 더 많은 인덱스 엔트리를 수용한다. 이로 인해 Std SSD(1.92~7.68TB)의 S2 overflow 문제가 사실상 해소됐다. HC SSD(15/30TB)는 여전히 ceiling에 닿는다. 코드리뷰 지적사항: 테스트가 private 멤버를 직접 호출하는 ERROR급 문제 1건 포함.

PR: #3449 — OPEN
브랜치: priv/dp/checkpoint_compression
커밋: 197dfc8a

한 줄 주장

체크포인트 payload는 key prefix가 반복되는 JSON이라 압축률이 높다. zlib level 1 압축으로:

더 많은 항목이 동일 메타데이터 컨테이너에 들어감 — 기존 overflow 억제
write amplification 감소 — 매 체크포인트 사이클에 쓰는 바이트 수 감소

구현 방식

payload 앞에 magic tag b"LMCZ1\x00" 추가 → recovery 시 codec 자동 감지
구버전(uncompressed) payload는 항상 {(0x7B)로 시작 → magic tag 충돌 없음 (하위 호환 O)
CRC는 저장된 bytes(압축 후)에 대해 계산 → torn-write 감지 유지
zlib level 1: 대부분의 압축 이득을 얻고 높은 레벨 대비 CPU 절감

RawBlockCheckpointCompression = Literal["none", "zlib"]
DEFAULT_CHECKPOINT_COMPRESSION: RawBlockCheckpointCompression = "zlib"

# RawBlockCoreConfig에 추가된 필드
meta_checkpoint_compression: RawBlockCheckpointCompression = DEFAULT_CHECKPOINT_COMPRESSION

변경 파일

파일	내용
`raw_block/core.py`	압축 타입, 상수, 인코딩/디코딩 메서드, config 필드
`raw_block/__init__.py`	새 public 심볼 export
`raw_block_l2_adapter.py`	adapter config에 `meta_checkpoint_compression` 추가
`rust_raw_block_backend.py`	extra config key 지원
`docs/design/...raw_block.md`	설계 문서 업데이트
`tests/`	압축 roundtrip, 하위호환, oversize, corrupt payload 테스트

S2 overflow와의 관계

압축률 실측 ~4.6×, capacity +5.5×:

디바이스	압축 전 overflow	압축 후 overflow
Std SSD 3.84TB	YES	NO (해소)
Std SSD 7.68TB	YES	NO (해소)
HC SSD 15TB	YES	YES (여전히)
HC SSD 30TB	YES	YES (여전히)

→ S2 트랙: "단계 1 PR 불요, HC SSD 전용 단계 2 저우선"으로 축소.

코드리뷰 지적사항

ERROR — 머지 전 필수 수정

1. 테스트가 private 멤버를 직접 접근 (코딩 스탠다드 §5.2 위반)

test_rust_raw_block_backend.py에서 core._select_latest_checkpoint(), core._rawdev(), core1._decode_checkpoint_payload(...), core1._write_checkpoint(...), _CHECKPOINT_COMPRESS_MAGIC 상수를 직접 호출/import.

수정 방향: behavior 기반으로 재작성 — put_many → checkpoint_now() → close → reopen → indexed_key_count() / exists_many() 패턴으로 검증.

2. _decode_checkpoint_payload 예외 계약 불일치

docstring에 Raises: zlib.error 명시하지만 유일한 호출자가 except Exception:으로 묵살. 수정 방향: (a) None 반환으로 변경 또는 (b) docstring에서 Raises 항목 제거.

3. validate_checkpoint_compression 이중 호출

raw_block_l2_adapter.py에서 from_dict()와 __init__() 양쪽에서 검증. 다른 필드들은 from_dict에서 추출만 하고 변환/검증은 __init__에 맡기는 패턴인데 이 필드만 예외. → from_dict에서 값 추출만, 검증은 __init__으로.

WARNING

4. cast() 대신 타입 내로잉 활용 가능

frozenset membership check로는 mypy가 narrowing 못해 cast 사용. if value == "none": return "none" 패턴이 더 타입 안전.

5. _encode_checkpoint_payload docstring에 제어 필드 미언급

"controlled by self.meta_checkpoint_compression" 한 줄 추가하면 흐름 추적 용이.

다운그레이드 주의

압축된 체크포인트는 이 기능 이전 버전에서 읽을 수 없음. 다운그레이드 전 "none"으로 변경 후 체크포인트 1회 실행 필요.

한 줄 주장​

구현 방식​

변경 파일​

S2 overflow와의 관계​

코드리뷰 지적사항​

ERROR — 머지 전 필수 수정​

WARNING​

다운그레이드 주의​

관련 페이지​