jetstream-api 0.8.0__tar.gz → 0.10.0__tar.gz

{jetstream_api-0.8.0 → jetstream_api-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.8.0
+Version: 0.10.0
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -40,6 +40,8 @@ Classifier: Topic :: System :: Networking
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
+Provides-Extra: lz4
+Requires-Dist: lz4>=4.0; extra == "lz4"
 Provides-Extra: zstd
 Requires-Dist: zstandard>=0.22; extra == "zstd"
 Provides-Extra: test
@@ -52,11 +54,49 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 
 ## 시스템 요구 사항
 시스템에 Python 3.9 이상, pip가 설치되어 있어야 합니다. 필수 의존성은 없습니다(표준 라이브러리만 씁니다).
-zstd 배치 압축을 쓰려면 `pip install "jetstream-api[zstd]"` 로 설치합니다(Python 3.14 이상은 표준 라이브러리로 됩니다).
+lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치 압축을 쓰려면 `pip install "jetstream-api[zstd]"` 로
+설치합니다(zstd 는 Python 3.14 이상이면 표준 라이브러리로 됩니다). 둘 다 쓰려면 `pip install "jetstream-api[lz4,zstd]"` 입니다.
 
 ## 설치 방법
 pip install jetstream-api
 
+## 0.10.0 변경 - 토픽 레코드 v5: 길이 칸 varint (자바 v2.6.0 과 같음)
+
+- **레코드 v5**: producer 가 파티션 배치를 magic 5 로 씁니다. 레코드의 길이 칸 셋(key / 속성 / 값)이 4바이트 고정에서
+  unsigned LEB128(길이 + 1, 1~5바이트)로 바뀌었습니다 - 126바이트까지 1바이트, 16,382바이트까지 2바이트입니다. 배치 헤더
+  52바이트, CRC, 압축 코덱과 압축 범위, 오프셋, 멱등 seq 는 그대로입니다.
+- **레코드당 저장 바이트 감소**: 값 100B + uuid 키 36B + 속성 없음 = 148 → 139B(-6.1%), 값 1KB = 1,072 → 1,064B(-0.75%).
+  압축을 켜면 차이는 거의 없습니다.
+- **소비는 배치마다 magic 을 봅니다**: 4(i32 길이 칸)와 5 를 모두 풀고, 한 응답에 섞여 있어도 됩니다.
+- **깨진 v5 레코드**: 길이 칸이 5바이트를 넘거나, 적힌 값이 2^31 이상이거나, 잘렸거나, 값이 없으면(적힌 값 0) 그 배치는
+  0.8.0 의 "풀지 못한 배치" 규칙대로 그 자리에서 멈춥니다(`MIMQC_FATAL_ERROR` / `MIMQE_INTERNAL_ERROR`). 사유는
+  `invalid v5 varint (...)` / `invalid v5 record value (absent ...)` 입니다.
+- **공개 API 변화 없음**: 설정 / 메서드 / 반환 모양이 그대로입니다. 크기 검사(`maxRequestSize` / `maxFrameLength` /
+  `bufferMemory` / `batchSize`)는 v5 부호화 길이로 셉니다 - 같은 설정에 레코드가 조금 더 들어갑니다.
+
+## 0.9.0 변경 - 압축 코덱 lz4 / zstd, gzip 제거 (자바 v2.5.0 과 같음)
+
+- **코덱은 `none` / `lz4` / `zstd` 입니다**: gzip 을 빼고 lz4 를 넣었습니다(사용자 결정). 클라이언트 CPU·지연이 중요하면
+  `lz4`, 디스크·용량이 중요하면 `zstd` 를 고르세요. 기본값은 여전히 압축하지 않음(`none`)입니다.
+- **공개 API 제거**: `compressionGzipLevel()` / `compression_gzip_level()` / `get_compression_gzip_level()` /
+  `getCompressionGzipLevel()`. `compressionType("gzip")` 은 `ValueError`
+  (`compressionType must be none / lz4 / zstd (got 'gzip' - gzip and snappy are not supported)`)입니다.
+- **추가**: `compressionType("lz4")`, `compressionLz4Level(n)` (`compression_lz4_level`) - `1`~`17`, 기본 `9`, 게터
+  `get_compression_lz4_level()` / `getCompressionLz4Level()`. 뜻은 Kafka `compression.lz4.level` 과 같습니다 - `9`(기본)는
+  빠른 압축기이고, `9` 가 아닌 값은 그 레벨의 LZ4HC(훨씬 느리고 조금 더 줄입니다)입니다. 레벨 12 이상은 결과가 같습니다.
+  파이썬 lz4 모듈은 레벨 1~2 를 빠른 압축기와 같게 다룹니다(자바 lz4-java 는 1~2 도 HC 계열 - 라이브러리 차이).
+- **lz4 는 선택 설치입니다**: `pip install "jetstream-api[lz4]"`(`lz4>=4.0`). 모듈이 없으면 `compressionType("lz4")` producer
+  생성이 연결하기 전에 `ILOperationException`(`MIMQE_NOT_SUPPORTED (compressionType lz4: no lz4 module - pip install
+  "jetstream-api[lz4]")`)으로 멈추고, lz4 배치를 받은 구독 read 는 원인 `MIMQE_NOT_SUPPORTED (codec 3 lz4: no lz4 module - ...)`
+  로 그 배치에서 멈춥니다(zstd 모듈 없음과 같은 `MIMQC_USER_FAULT` / `MIMQE_NOT_SUPPORTED`). 발행하는 코덱의 모듈을 구독하는
+  쪽에도 설치하세요.
+- **lz4 와이어**: 배치 attributes 코덱 3, 표준 LZ4 frame(`lz4` 명령과 같은 틀)입니다. producer 는 64KB **독립 블록** + 원문
+  크기로 만들고 체크섬은 넣지 않습니다(배치 CRC 가 압축 바이트를 덮습니다) - 자바 v2.5.0 도 같은 틀로 만듭니다. 소비는
+  이어 붙인 frame 을 모두 풀고, 잘림 / frame 뒤에 남은 바이트 / 푼 크기 128MiB 초과 / 깨진 frame 은
+  `MIMQE_TOPIC_CODEC_ERROR (lz4: ...)` 로 그 배치에서 멈춥니다(0.8.0 의 "풀지 못한 배치" 규칙 그대로).
+- 압축은 예전처럼 producer 의 I/O 스레드가 하고, 줄지 않는 배치는 압축하지 않고 보냅니다. lz4 모듈도 압축하는 동안 GIL 을
+  놓습니다.
+
 ## 0.8.0 변경 - 배치 압축 gzip / zstd (자바 v2.4.0 과 같음)
 
 - **엔진 요구**: 압축 배치는 **엔진 7.0.1.3419 이상**(CMPR-1)에서만 받습니다. 그보다 옛 엔진은 압축 배치를 알아보지 못해
@@ -109,11 +149,6 @@ pip install jetstream-api
     떼어 내지 않고 그 파티션만 되감으며, 같은 응답의 다른 토픽 레코드는 그대로 줍니다.
   - 패턴 구독 `read_batch` 는 요청 실패(요청 전체 거절 / 통신 실패)에서도 이 호출에서 이미 모은 레코드를 돌려주고 오류는 다음
     호출이 올립니다(예전 판은 모은 레코드를 버렸는데 AUTO 커밋 좌표는 이미 병합돼 있어 앱이 못 본 레코드가 커밋됐습니다).
-- **옛 클라이언트**: 엔진은 배치 read 에 저장한 바이트를 그대로 보내므로, 압축 토픽을 소비하는 구독자는 **0.8.0 / 자바 v2.4.0
-  이상**이어야 합니다. 압축을 켜기 전에 그 토픽의 소비자를 먼저 올리세요. 옛 판 중 압축 토픽을 읽는 것은 엔진 단건 read 를
-  쓰는 판뿐입니다 - 파이썬 0.6.x 의 `read()`, 자바 v2.2.x 의 prefetch 를 끈 `read()`(엔진이 풀어서 줍니다). 파이썬 0.7.x 와
-  자바 v2.3.x 는 `read()` 도 배치 read 라서 압축 배치에서 형식 오류(`MIMQC_FATAL_ERROR (MIMQE_INTERNAL_ERROR)`, 원인
-  `truncated topic batch ...`)로 멈춥니다 - 조용히 틀린 레코드를 주지는 않습니다(pv2test 엔진 7.0.1.3419 실측).
 - **NIO 커넥터 송신은 기한 하나를 씁니다**(`TCPConnectorNIO`, `set_conn` 으로 고른 경우만): 송신 한 번 전체가 접속 대기 시간
   (최소 1 s)을 기한으로 씁니다. 기한이 지나면 `MIMQE_SESSION_TIMEOUT`(`write waiting time has exceeded the time limit : [Nms]
   / written : [n / 전체]`)을 내고 연결을 닫습니다. 전에는 보낼 자리가 날 때까지 기다릴 때마다 한도를 새로 주어, 상대가