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

{jetstream_api-0.8.0/jetstream_api.egg-info → jetstream_api-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.8.0
+Version: 0.9.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,35 @@ 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.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 +135,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 / 전체]`)을 내고 연결을 닫습니다. 전에는 보낼 자리가 날 때까지 기다릴 때마다 한도를 새로 주어, 상대가

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/README.md

@@ -4,11 +4,35 @@ 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.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)에서만 받습니다. 그보다 옛 엔진은 압축 배치를 알아보지 못해
@@ -61,11 +85,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 / 전체]`)을 내고 연결을 닫습니다. 전에는 보낼 자리가 날 때까지 기다릴 때마다 한도를 새로 주어, 상대가

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/ilink/__init__.py

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/ilink/_codec.py

@@ -1,42 +1,44 @@
-"""배치 압축 코덱(0.8.0). **내부 모듈이다** - 발행과 소비가 함께 쓴다.
+"""배치 압축 코덱(0.8.0, 0.9.0 에서 gzip 을 빼고 lz4 를 넣었다). **내부 모듈이다** - 발행과 소비가 함께 쓴다.
 
 발행 v2 파티션 배치(= 저장 v4 배치)의 레코드 열을 압축하고 푼다. 와이어(엔진 CMPR-1):
 
 - 배치 헤더 52바이트는 압축하지 않는다. 레코드 열 ``[52, batchLength)`` 만 압축한다.
-- 헤더 ``attributes`` 의 하위 3비트가 코덱이다: 0 없음 / 1 gzip / 4 zstd. 나머지 비트는 0 이다.
+- 헤더 ``attributes`` 의 하위 3비트가 코덱이다: 0 없음 / 3 lz4 / 4 zstd. 나머지 비트는 0 이다.
 - ``recordCount`` 는 원래 레코드 수, ``batchLength`` 는 압축한 뒤 길이(52 + 압축 길이)이고, 배치 CRC 는 압축한
   바이트 ``[28, batchLength)`` 가 대상이다(압축 -> 헤더 -> CRC 순서).
-- gzip 은 gzip 틀(RFC 1952) 멤버 하나이고 뒤에 남는 바이트가 없어야 한다. zstd 는 표준 프레임이고 이어 붙인
-  여러 프레임도 받는다. 푼 크기 상한은 128MiB 다.
-
-zstd 모듈은 필수 의존성이 아니다. 처음 쓸 때 표준 라이브러리 ``compression.zstd``(파이썬 3.14+)를 먼저, 없으면
-``zstandard`` 패키지를 찾는다. 둘 다 없으면 zstd 를 고른 producer 생성과 zstd 배치 수신이 설치 안내를 담은 오류로
-멈춘다. gzip 은 표준 라이브러리 zlib 만 쓴다.
+- lz4 는 표준 LZ4 frame 이고 zstd 는 표준 프레임이다. 둘 다 이어 붙인 여러 frame 을 받고, 끝난 뒤 남는 바이트는
+  거절한다. 푼 크기 상한은 128MiB 다.
+- lz4 frame 은 블록 독립이어야 한다 - 엔진이 블록 연결형 frame 을 발행에서 거절한다(``lz4: linked blocks not supported``).
+  producer 는 64KB 독립 블록으로 만들고 원문 크기를 frame 에 싣는다. 체크섬은 쓰지 않는다(배치 CRC 가 압축 바이트를 덮는다).
+
+lz4 / zstd 모듈은 필수 의존성이 아니다. lz4 는 ``lz4`` 패키지(``pip install "jetstream-api[lz4]"``), zstd 는 표준
+라이브러리 ``compression.zstd``(파이썬 3.14+)를 먼저, 없으면 ``zstandard`` 패키지를 찾는다. 모듈이 없으면 그 코덱을
+고른 producer 생성과 그 코덱 배치 수신이 설치 안내를 담은 오류로 멈춘다.
 """
 
 from __future__ import annotations
 
 import threading
-import zlib
 
 from .exception import ILOperationException
 
 #: 코덱 번호(배치 헤더 attributes 의 하위 3비트)
 CODEC_NONE = 0
-CODEC_GZIP = 1
+CODEC_LZ4 = 3
 CODEC_ZSTD = 4
 #: attributes 에서 코덱을 뽑는 마스크
 CODEC_MASK = 0x07
 #: 설정 이름 -> 코덱 번호
-CODECS = {"none": CODEC_NONE, "gzip": CODEC_GZIP, "zstd": CODEC_ZSTD}
+CODECS = {"none": CODEC_NONE, "lz4": CODEC_LZ4, "zstd": CODEC_ZSTD}
 #: 코덱 번호 -> 설정 이름
 CODEC_NAMES = {v: k for k, v in CODECS.items()}
 
-# 레벨의 기본값과 범위는 Kafka compression.gzip.level / compression.zstd.level 과 같다(kafka-clients 4.3.1 확인,
-# 사용자 결정 2026-09-13): gzip -1(= zlib 기본 6) 또는 1~9, zstd 기본 3 / -131072(ZSTD_minCLevel)~22
-GZIP_LEVEL_DEFAULT = -1
-GZIP_LEVEL_MIN = 1
-GZIP_LEVEL_MAX = 9
+# 레벨의 기본값과 범위는 Kafka compression.lz4.level / compression.zstd.level 과 같다(kafka-clients 4.3.1 확인,
+# 사용자 결정 2026-09-13 / 2026-09-14): lz4 기본 9 / 1~17, zstd 기본 3 / -131072(ZSTD_minCLevel)~22.
+# lz4 레벨의 뜻도 Kafka 와 같다 - 9 는 빠른 압축기(레벨을 쓰지 않는다), 9 가 아니면 그 레벨의 LZ4HC
+LZ4_LEVEL_DEFAULT = 9
+LZ4_LEVEL_MIN = 1
+LZ4_LEVEL_MAX = 17
 ZSTD_LEVEL_DEFAULT = 3
 ZSTD_LEVEL_MIN = -131072
 ZSTD_LEVEL_MAX = 22
@@ -44,9 +46,16 @@ ZSTD_LEVEL_MAX = 22
 #: 푼 레코드 열의 크기 상한(바이트). 엔진과 같은 128MiB 다. 시험이 낮출 수 있게 모듈 변수로 둔다(호출 때 읽는다)
 MAX_RAW = 128 * 1024 * 1024
 
+#: lz4 모듈이 없을 때 오류 문구에 싣는 설치 안내
+LZ4_HINT = 'pip install "jetstream-api[lz4]"'
 #: zstd 모듈이 없을 때 오류 문구에 싣는 설치 안내
 ZSTD_HINT = 'pip install "jetstream-api[zstd]", or use Python 3.14+ (standard library compression.zstd)'
 
+#: LZ4 frame 머리의 magic(0x184D2204, 리틀 엔디언)
+_LZ4_MAGIC = bytes((0x04, 0x22, 0x4D, 0x18))
+#: 원문 크기를 믿을 수 없는 lz4 frame 을 조금씩 풀 때 한 번에 받는 출력 크기(바이트) - lz4.frame 은 이만큼을 미리 잡는다
+_LZ4_STEP = 1024 * 1024
+
 #: zstandard 백엔드가 한 번에 먹이는 압축 입력 크기(바이트). 그 API 는 출력 상한을 받지 않아 입력을 잘게 먹이며
 #: 출력을 센다 - 넘침은 이 크기가 만들 수 있는 출력만큼으로 묶인다
 _ZSTANDARD_FEED = 4096
@@ -57,37 +66,35 @@ def check_type(codec) -> str:
     """압축 코덱 이름을 검사한다.
 
     Args:
-        codec (str): ``"none"`` / ``"gzip"`` / ``"zstd"`` - 소문자 그대로다(``"GZIP"`` 은 받지 않는다).
+        codec (str): ``"none"`` / ``"lz4"`` / ``"zstd"`` - 소문자 그대로다(``"LZ4"`` 는 받지 않는다).
 
     Returns:
         str: 받은 이름 그대로.
 
     Raises:
-        ValueError: 문자열이 아니거나 세 값 밖일 때.
+        ValueError: 문자열이 아니거나 세 값 밖일 때(``"gzip"`` / ``"snappy"`` 포함).
     """
     # 자바 ILTopicCodec.codecOf 와 Kafka compression.type 처럼 소문자 이름만 받는다(두 언어가 같은 설정을 같게 받는다)
     if not isinstance(codec, str) or codec not in CODECS:
-        raise ValueError("compressionType must be none / gzip / zstd (got %r - lz4 and snappy are not supported)"
+        raise ValueError("compressionType must be none / lz4 / zstd (got %r - gzip and snappy are not supported)"
                          % (codec,))
     return codec
 
 
-def check_gzip_level(level) -> int:
-    """gzip 레벨을 검사한다.
+def check_lz4_level(level) -> int:
+    """lz4 레벨을 검사한다.
 
     Args:
-        level (int): ``-1`` (zlib 기본 레벨 6) 또는 ``1`` ~ ``9``.
+        level (int): ``1`` ~ ``17``. ``9`` (기본)는 빠른 압축기이고, 그 밖의 값은 그 레벨의 LZ4HC 다.
 
     Returns:
         int: 받은 레벨 그대로.
 
     Raises:
-        ValueError: 정수가 아니거나 범위 밖일 때(``0`` 도 받지 않는다).
+        ValueError: 정수가 아니거나 범위 밖일 때.
     """
-    if isinstance(level, bool) or not isinstance(level, int) or not (
-            level == GZIP_LEVEL_DEFAULT or GZIP_LEVEL_MIN <= level <= GZIP_LEVEL_MAX):
-        raise ValueError("compressionGzipLevel must be -1 (zlib default, 6) or %d..%d (got %r)"
-                         % (GZIP_LEVEL_MIN, GZIP_LEVEL_MAX, level))
+    if isinstance(level, bool) or not isinstance(level, int) or not (LZ4_LEVEL_MIN <= level <= LZ4_LEVEL_MAX):
+        raise ValueError("compressionLz4Level must be %d..%d (got %r)" % (LZ4_LEVEL_MIN, LZ4_LEVEL_MAX, level))
     return level
 
 
@@ -108,34 +115,103 @@ def check_zstd_level(level) -> int:
     return level
 
 
-# ── gzip ─────────────────────────────────────────────────────────────────
-def gzip_compress(data, level: int = GZIP_LEVEL_DEFAULT) -> bytes:
-    """gzip 틀(RFC 1952) 멤버 하나로 압축한다. 스레드마다 새 압축 객체를 쓰므로 어느 스레드에서 불러도 된다.
+# ── lz4 백엔드 ───────────────────────────────────────────────────────────
+class _Lz4:
+    """``lz4`` 패키지의 ``lz4.frame`` 백엔드(``pip install "jetstream-api[lz4]"``)."""
 
-    Args:
-        data (bytes | bytearray | memoryview): 압축할 바이트.
-        level (int): ``-1`` (zlib 기본 레벨 6) 또는 ``1`` ~ ``9``.
+    name = "lz4"
 
-    Returns:
-        bytes: gzip 멤버 하나.
-    """
-    c = zlib.compressobj(level, zlib.DEFLATED, 31)      # wbits 16 + 15 = gzip 틀(엔진 inflateInit2(16 + MAX_WBITS))
-    return c.compress(data) + c.flush()
+    def __init__(self, frame) -> None:
+        self._f = frame
 
+    def compress(self, data, level: int) -> bytes:
+        """frame 하나로 압축한다(64KB 독립 블록, 원문 크기를 싣고 체크섬은 쓰지 않는다).
 
-def _gunzip(data, limit: int) -> bytes:
-    d = zlib.decompressobj(31)                          # gzip 틀만 받는다(zlib 틀 / raw deflate 는 오류)
-    try:
-        out = d.decompress(data, limit + 1)
-    except zlib.error as exc:
-        raise ValueError("MIMQE_TOPIC_CODEC_ERROR (gzip: %s)" % exc) from None
-    if len(out) > limit:
-        raise ValueError("MIMQE_TOPIC_CODEC_ERROR (gzip: decompressed size over %d bytes)" % limit)
-    if not d.eof:
-        raise ValueError("MIMQE_TOPIC_CODEC_ERROR (gzip: truncated)")
-    if d.unused_data:
-        raise ValueError("MIMQE_TOPIC_CODEC_ERROR (gzip: %d trailing bytes after the gzip member)" % len(d.unused_data))
-    return out
+        Args:
+            data (bytes | bytearray | memoryview): 압축할 바이트.
+            level (int): lz4 레벨(``1`` ~ ``17``). ``9`` 는 빠른 압축기, 그 밖은 그 레벨의 LZ4HC 다.
+
+        Returns:
+            bytes: LZ4 frame 하나.
+        """
+        f = self._f
+        # Kafka Lz4BlockOutputStream 과 같은 뜻 - 기본 9 = 빠른 압축기(lz4.frame 레벨 0), 그 밖은 HC(레벨 그대로).
+        #   lz4.frame 은 3 이상이 HC 이고 1~2 는 빠른 압축기와 같다(자바 lz4-java 는 1~2 도 HC 계열 - 라이브러리 차이).
+        #   block_linked 기본값이 True(연결형)라 반드시 끈다 - 자바 lz4-java 는 연결형 frame 을 풀지 못한다
+        return f.compress(data, compression_level=0 if level == LZ4_LEVEL_DEFAULT else level,
+                          block_size=f.BLOCKSIZE_MAX64KB, block_linked=False,
+                          content_checksum=False, block_checksum=False, store_size=True)
+
+    def decompress(self, data, limit: int) -> bytes:
+        """이어 붙인 frame 을 모두 푼다. 원문 크기가 없는 frame 도 된다.
+
+        Args:
+            data (bytes | memoryview): LZ4 frame(들).
+            limit (int): 푼 크기 상한(바이트).
+
+        Returns:
+            bytes: 푼 바이트.
+
+        Raises:
+            ValueError: 깨졌거나 잘렸거나 뒤에 남는 바이트가 있거나 상한을 넘을 때(``MIMQE_TOPIC_CODEC_ERROR (lz4: ...)``).
+        """
+        f = self._f
+        rest = memoryview(data)
+        if not len(rest):
+            raise ValueError("MIMQE_TOPIC_CODEC_ERROR (lz4: truncated)")
+        over = "MIMQE_TOPIC_CODEC_ERROR (lz4: decompressed size over %d bytes)" % limit
+        out = []
+        total = 0
+        frames = 0
+        while True:
+            # lz4.frame.decompress() 는 첫 frame 만 풀고 뒤 frame / 쓰레기를 조용히 버리므로 쓰지 않는다. 풀개 하나는 frame
+            #   하나만 풀고 남은 바이트(unused_data)를 돌려준다 - 다음 frame 은 새 풀개로 푼다.
+            # lz4.frame 은 max_length 만큼 출력을 **미리 잡는다**(상한 128MiB 를 그대로 주면 배치마다 128MiB 를 잡는다). 그래서 frame
+            #   머리의 원문 크기가 있으면 상한과 먼저 견주고 그 크기로 한 번에 잡는다. 머리 값은 믿을 수 없는 입력이라, 이 frame 에 남은
+            #   압축 바이트로 만들 수 있는 크기(lz4 는 약 255배를 넘지 않는다)보다 크면 원문 크기가 없는 frame 처럼 조금씩 푼다
+            n = len(rest)
+            csize = None
+            if n >= 14 and rest[0:4] == _LZ4_MAGIC and rest[4] & 0x08:
+                csize = int.from_bytes(rest[6:14], "little")
+                if csize > limit - total:
+                    raise ValueError(over)
+            d = f.LZ4FrameDecompressor()
+            try:
+                if csize is not None and csize <= n * 255 + 65536:
+                    # 원문 크기와 다르면 lz4 가 오류(ERROR_frameSize_wrong)를 낸다 - +1 은 넘치는 것을 자르지 않고 보게 한다
+                    parts = [d.decompress(rest, max_length=csize + 1)]
+                    got = len(parts[0])
+                else:
+                    parts = []
+                    got = 0
+                    piece = d.decompress(rest, max_length=_LZ4_STEP)
+                    while True:
+                        parts.append(piece)
+                        got += len(piece)
+                        if total + got > limit:
+                            raise ValueError(over)
+                        if d.eof or d.needs_input:
+                            break
+                        piece = d.decompress(b"", max_length=_LZ4_STEP)
+            except RuntimeError as exc:
+                if frames:
+                    raise ValueError("MIMQE_TOPIC_CODEC_ERROR (lz4: %d trailing bytes after the lz4 frame - %s)"
+                                     % (len(rest), exc)) from None
+                raise ValueError("MIMQE_TOPIC_CODEC_ERROR (lz4: %s)" % exc) from None
+            total += got
+            if total > limit:
+                raise ValueError(over)
+            out.extend(parts)
+            if not d.eof:
+                # 상한까지 풀 자리를 주었으므로 여기서 멈춘 것은 입력이 끝났기 때문이다. 앞 frame 이 끝난 뒤라면 frame 이
+                #   되지 못한 뒤 바이트다(엔진처럼 거절)
+                if frames:
+                    raise ValueError("MIMQE_TOPIC_CODEC_ERROR (lz4: %d trailing bytes after the lz4 frame)" % len(rest))
+                raise ValueError("MIMQE_TOPIC_CODEC_ERROR (lz4: truncated)")
+            frames += 1
+            rest = d.unused_data
+            if not rest:
+                return b"".join(out)
 
 
 # ── zstd 백엔드 ──────────────────────────────────────────────────────────
@@ -279,12 +355,22 @@ class _ZstandardZstd:
 
 
 _UNPROBED = object()
-#: zstd 백엔드. _UNPROBED = 아직 찾지 않음, None = 없음. 시험이 가짜 백엔드로 바꿔 끼울 수 있다
+#: lz4 / zstd 백엔드. _UNPROBED = 아직 찾지 않음, None = 없음. 시험이 가짜 백엔드로 바꿔 끼울 수 있다
+_lz4_state = _UNPROBED
 _zstd_state = _UNPROBED
 _probe_lock = threading.Lock()
 
 
-def _probe():
+def _probe_lz4():
+    """``lz4.frame`` 을 찾는다. 없으면 None."""
+    try:
+        import lz4.frame as frame               # type: ignore[import-not-found]
+    except ImportError:
+        return None
+    return _Lz4(frame)
+
+
+def _probe_zstd():
     """표준 라이브러리(3.14+) -> zstandard 순으로 찾는다. 없으면 None."""
     try:
         from compression import zstd as mod     # type: ignore[import-not-found]
@@ -299,6 +385,22 @@ def _probe():
     return _ZstandardZstd(mod2)
 
 
+def lz4_backend():
+    """lz4 백엔드를 돌려준다. 처음 부를 때 찾는다.
+
+    Returns:
+        object | None: ``compress(data, level)`` / ``decompress(data, limit)`` 를 가진 백엔드. 없으면 None.
+    """
+    global _lz4_state
+    s = _lz4_state
+    if s is _UNPROBED:
+        with _probe_lock:
+            if _lz4_state is _UNPROBED:
+                _lz4_state = _probe_lz4()
+            s = _lz4_state
+    return s
+
+
 def zstd_backend():
     """zstd 백엔드를 돌려준다. 처음 부를 때 찾는다.
 
@@ -310,18 +412,18 @@ def zstd_backend():
     if s is _UNPROBED:
         with _probe_lock:
             if _zstd_state is _UNPROBED:
-                _zstd_state = _probe()
+                _zstd_state = _probe_zstd()
             s = _zstd_state
     return s
 
 
 # ── 발행 / 소비 쪽 입구 ───────────────────────────────────────────────────
-def compressor(codec: str, gzip_level: int, zstd_level: int):
+def compressor(codec: str, lz4_level: int, zstd_level: int):
     """producer 가 쓸 (코덱 번호, 압축 함수) 를 만든다. 압축 함수는 레코드 열 바이트를 받아 압축한 bytes 를 돌려준다.
 
     Args:
-        codec (str): ``"none"`` / ``"gzip"`` / ``"zstd"``.
-        gzip_level (int): gzip 레벨(``-1`` 또는 ``1`` ~ ``9``).
+        codec (str): ``"none"`` / ``"lz4"`` / ``"zstd"``.
+        lz4_level (int): lz4 레벨(``1`` ~ ``17``).
         zstd_level (int): zstd 레벨(``-131072`` ~ ``22``).
 
     Returns:
@@ -329,14 +431,17 @@ def compressor(codec: str, gzip_level: int, zstd_level: int):
 
     Raises:
         ValueError: 코덱 이름이나 레벨이 틀렸을 때.
-        ILOperationException: ``"zstd"`` 인데 zstd 모듈이 없을 때 - ``MIMQE_NOT_SUPPORTED (...)`` 에 설치 안내를 싣는다.
+        ILOperationException: 고른 코덱의 모듈이 없을 때 - ``MIMQE_NOT_SUPPORTED (...)`` 에 설치 안내를 싣는다.
     """
     c = CODECS[check_type(codec)]
     if c == CODEC_NONE:
         return CODEC_NONE, None
-    if c == CODEC_GZIP:
-        glv = check_gzip_level(gzip_level)
-        return CODEC_GZIP, lambda data: gzip_compress(data, glv)
+    if c == CODEC_LZ4:
+        llv = check_lz4_level(lz4_level)
+        lbe = lz4_backend()
+        if lbe is None:
+            raise ILOperationException("MIMQE_NOT_SUPPORTED (compressionType lz4: no lz4 module - %s)" % LZ4_HINT)
+        return CODEC_LZ4, lambda data: lbe.compress(data, llv)
     zlv = check_zstd_level(zstd_level)
     be = zstd_backend()
     if be is None:
@@ -348,20 +453,23 @@ def decompress(codec: int, data) -> bytes:
     """배치 하나의 레코드 열을 푼다. 푼 크기는 :data:`MAX_RAW` 까지다.
 
     Args:
-        codec (int): 배치 헤더 attributes 의 하위 3비트(``1`` gzip / ``4`` zstd).
+        codec (int): 배치 헤더 attributes 의 하위 3비트(``3`` lz4 / ``4`` zstd).
         data (bytes | memoryview): 압축된 레코드 열(``[52, batchLength)``).
 
     Returns:
         bytes: 푼 레코드 열.
 
     Raises:
-        ValueError: 모르는 코덱(``MIMQE_TOPIC_UNSUPPORTED_CODEC (codec N)``), zstd 모듈 없음(``MIMQE_NOT_SUPPORTED``,
+        ValueError: 모르는 코덱(``MIMQE_TOPIC_UNSUPPORTED_CODEC (codec N)``), 코덱 모듈 없음(``MIMQE_NOT_SUPPORTED``,
             설치 안내를 싣는다),
             깨졌거나 잘렸거나 뒤에 남는 바이트가 있거나 상한을 넘을 때(``MIMQE_TOPIC_CODEC_ERROR (...)``).
     """
     limit = MAX_RAW
-    if codec == CODEC_GZIP:
-        return _gunzip(data, limit)
+    if codec == CODEC_LZ4:
+        lbe = lz4_backend()
+        if lbe is None:
+            raise ValueError("MIMQE_NOT_SUPPORTED (codec 3 lz4: no lz4 module - %s)" % LZ4_HINT)
+        return lbe.decompress(data, limit)
     if codec == CODEC_ZSTD:
         be = zstd_backend()
         if be is None:

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/ilink/msg.py

@@ -617,7 +617,7 @@ class ILTopicBatchV4Msg(ILInnerMsg):
     i32 batchCount | v4 배치 x batchCount``. 배치는 발행 v2 의 파티션 배치와 같은 형식(52바이트 헤더 + 레코드)이고
     엔진이 baseOffset / timestamp 를 채웠다. 레코드 오프셋은 baseOffset + 순번, 시각은 배치 timestamp 다.
 
-    0.8.0: 배치는 압축돼 있을 수 있다(헤더 attributes 하위 3비트 = 코덱: 0 없음 / 1 gzip / 4 zstd). 엔진은 저장한
+    0.8.0: 배치는 압축돼 있을 수 있다(헤더 attributes 하위 3비트 = 코덱: 0 없음 / 3 lz4 / 4 zstd). 엔진은 저장한
     바이트를 그대로 보내므로 배치마다 코덱을 보고 레코드 열을 푼다 - 한 응답에 코덱이 섞여도 된다.
     """
 
@@ -632,7 +632,7 @@ class ILTopicBatchV4Msg(ILInnerMsg):
     def records(self) -> list:
         """레코드를 배치 순서대로 푼다. 파티션의 startOffset 보다 앞선 레코드는 뺀다(첫 배치는 커서 앞 레코드를
         담을 수 있다). 배치 CRC(범위 [28, batchLength), 압축 배치면 압축한 바이트)를 검증하고, 압축 배치는 레코드 열을
-        풀어서 읽는다(0.8.0 - gzip / zstd, 푼 크기 128MiB 까지).
+        풀어서 읽는다(0.8.0, 0.9.0 부터 lz4 / zstd - 푼 크기 128MiB 까지).
 
         Returns:
             list: ``(partition, offset, timestamp, key, value, property_bytes)`` 튜플 목록. key 는 없으면 ``""``,

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/ilink/producer.py

@@ -57,7 +57,7 @@ class ILProducerConfig:
         "acks", "lingerMs", "batchSize", "maxInFlight", "retries",
         "deliveryTimeoutMs", "requestTimeoutMs", "retryBackoffMs",
         "bufferMemory", "maxBlockMs", "maxRequestSize", "maxFrameLength", "enableIdempotence",
-        "compressionType", "compressionGzipLevel", "compressionZstdLevel",
+        "compressionType", "compressionLz4Level", "compressionZstdLevel",
     ))
 
     def __init__(self) -> None:
@@ -91,11 +91,12 @@ class ILProducerConfig:
         self._enableIdempotence = True
         #: 멱등을 사용자가 정했는지. 정하지 않았으면 acks=0 이나 maxInFlight > 5 에서 저절로 꺼진다
         self._idempotenceSet = False
-        # 0.8.0: 배치 압축. 이름과 기본값이 Kafka compression.type / compression.gzip.level / compression.zstd.level 과 같다
-        #: 파티션 배치 압축 코덱 "none" / "gzip" / "zstd". 기본 "none"
+        # 0.8.0: 배치 압축. 이름과 기본값이 Kafka compression.type / compression.lz4.level / compression.zstd.level 과 같다
+        #   (0.9.0: gzip 을 빼고 lz4 를 넣었다 - 사용자 결정 2026-09-14)
+        #: 파티션 배치 압축 코덱 "none" / "lz4" / "zstd". 기본 "none"
         self._compressionType = "none"
-        #: gzip 레벨 -1(= zlib 기본 6) 또는 1~9. 기본 -1
-        self._compressionGzipLevel = _codec.GZIP_LEVEL_DEFAULT
+        #: lz4 레벨 1~17. 기본 9(= 빠른 압축기, 9 가 아니면 그 레벨의 LZ4HC)
+        self._compressionLz4Level = _codec.LZ4_LEVEL_DEFAULT
         #: zstd 레벨 -131072~22. 기본 3
         self._compressionZstdLevel = _codec.ZSTD_LEVEL_DEFAULT
 
@@ -368,16 +369,17 @@ class ILProducerConfig:
         """파티션 배치의 압축 코덱을 정한다. (기본 ``"none"`` - 압축하지 않는다)
 
         Args:
-            codec (str): ``"none"`` / ``"gzip"`` / ``"zstd"`` - 소문자 그대로 쓴다(``"GZIP"`` 은 받지 않는다).
-                ``"gzip"`` 은 표준 라이브러리(zlib)만 쓴다. ``"zstd"`` 는 zstd 모듈이 있어야 한다 -
-                ``pip install "jetstream-api[zstd]"`` 로 설치하거나, 파이썬 3.14 이상이면 표준 라이브러리
-                ``compression.zstd`` 를 먼저 쓴다.
+            codec (str): ``"none"`` / ``"lz4"`` / ``"zstd"`` - 소문자 그대로 쓴다(``"LZ4"`` 는 받지 않는다).
+                클라이언트 CPU·지연이 중요하면 ``"lz4"``, 디스크·용량이 중요하면 ``"zstd"`` 를 고른다.
+                ``"lz4"`` 는 lz4 모듈이 있어야 한다 - ``pip install "jetstream-api[lz4]"``.
+                ``"zstd"`` 는 zstd 모듈이 있어야 한다 - ``pip install "jetstream-api[zstd]"`` 로 설치하거나,
+                파이썬 3.14 이상이면 표준 라이브러리 ``compression.zstd`` 를 먼저 쓴다.
 
         Returns:
             ILProducerConfig: 체이닝을 위해 자기 자신.
 
         Raises:
-            ValueError: 세 값 밖일 때(``"lz4"`` / ``"snappy"`` 는 지원하지 않는다).
+            ValueError: 세 값 밖일 때(``"gzip"`` / ``"snappy"`` 는 지원하지 않는다).
 
         Note:
             파티션 배치를 보낼 때 레코드 열만 **한 번** 압축한다(배치 헤더 52바이트는 그대로). 재전송은 같은 압축
@@ -386,23 +388,21 @@ class ILProducerConfig:
             세고, 봉투에 배치를 채울 때(:meth:`maxRequestSize`)는 압축한 **뒤** 길이로 센다. 압축은 producer 의
             I/O 스레드가 한다.
 
-            **엔진 7.0.1.3419 이상**(CMPR-1)이 필요하다 - 그보다 옛 엔진은 압축 배치를 알아보지 못해 거절한다.
-            압축 배치를 받는 구독자도 0.8.0 이상이어야 한다(엔진은 배치 read 에 저장한 바이트를 풀지 않고 보낸다).
-            옛 판 중에는 엔진 단건 read 를 쓰는 0.6.x 의 ``read()`` 만 압축 토픽을 읽는다(0.7.x 는 ``read()`` 도 배치 read 라서
-            형식 오류로 멈춘다).
+            구독자는 받은 압축 배치를 스스로 푼다(엔진은 배치 read 에 저장한 바이트를 풀지 않고 보낸다).
 
-            zstd 를 골랐는데 zstd 모듈이 없으면 producer 생성이 연결하기 전에 ``ILOperationException``
-            (``MIMQE_NOT_SUPPORTED``, 설치 안내를 싣는다)으로 멈춘다.
+            lz4 / zstd 를 골랐는데 그 모듈이 없으면 producer 생성이 연결하기 전에 ``ILOperationException``
+            (``MIMQE_NOT_SUPPORTED``, 설치 안내를 싣는다)으로 멈춘다. 구독자도 그 코덱의 배치를 받으면 같은 사유로
+            그 파티션에서 멈춘다 - 발행하는 코덱의 모듈을 구독하는 쪽에도 설치한다.
         """
         self._compressionType = _codec.check_type(codec)
         return self
 
-    def compressionGzipLevel(self, level: int) -> "ILProducerConfig":
-        """gzip 압축 레벨을 정한다. (기본 ``-1`` = zlib 기본 레벨 6)
+    def compressionLz4Level(self, level: int) -> "ILProducerConfig":
+        """lz4 압축 레벨을 정한다. (기본 ``9`` = 빠른 압축기)
 
         Args:
-            level (int): ``-1`` 또는 ``1`` ~ ``9``. 클수록 더 줄지만 느리다. ``0`` (압축 안 함)은 받지 않는다 -
-                압축하지 않으려면 ``compressionType("none")``.
+            level (int): ``1`` ~ ``17``. Kafka ``compression.lz4.level`` 과 뜻이 같다 - ``9`` (기본)는 빠른 압축기이고,
+                ``9`` 가 아닌 값은 그 레벨의 LZ4HC(훨씬 느리고 조금 더 준다)다. 레벨 12 이상은 결과가 같다.
 
         Returns:
             ILProducerConfig: 체이닝을 위해 자기 자신.
@@ -411,9 +411,10 @@ class ILProducerConfig:
             ValueError: 정수가 아니거나 범위 밖일 때.
 
         Note:
-            :meth:`compressionType` 이 ``"gzip"`` 일 때만 쓰인다.
+            :meth:`compressionType` 이 ``"lz4"`` 일 때만 쓰인다. 파이썬 lz4 모듈은 레벨 1~2 를 빠른 압축기와 같게
+            다룬다(자바 lz4-java 는 1~2 도 HC 계열이다 - 라이브러리 차이). 빠른 lz4 를 쓰려면 기본값 9 를 그대로 둔다.
         """
-        self._compressionGzipLevel = _codec.check_gzip_level(level)
+        self._compressionLz4Level = _codec.check_lz4_level(level)
         return self
 
     def compressionZstdLevel(self, level: int) -> "ILProducerConfig":
@@ -496,9 +497,9 @@ class ILProducerConfig:
         """:meth:`compressionType` 의 snake 별칭."""
         return self.compressionType(codec)
 
-    def compression_gzip_level(self, level: int) -> "ILProducerConfig":
-        """:meth:`compressionGzipLevel` 의 snake 별칭."""
-        return self.compressionGzipLevel(level)
+    def compression_lz4_level(self, level: int) -> "ILProducerConfig":
+        """:meth:`compressionLz4Level` 의 snake 별칭."""
+        return self.compressionLz4Level(level)
 
     def compression_zstd_level(self, level: int) -> "ILProducerConfig":
         """:meth:`compressionZstdLevel` 의 snake 별칭."""
@@ -616,17 +617,17 @@ class ILProducerConfig:
         """파티션 배치 압축 코덱. 기본 ``"none"``.
 
         Returns:
-            str: ``"none"`` / ``"gzip"`` / ``"zstd"`` (소문자).
+            str: ``"none"`` / ``"lz4"`` / ``"zstd"`` (소문자).
         """
         return self._compressionType
 
-    def get_compression_gzip_level(self) -> int:
-        """gzip 압축 레벨. 기본 -1(zlib 기본 레벨 6).
+    def get_compression_lz4_level(self) -> int:
+        """lz4 압축 레벨. 기본 9(빠른 압축기).
 
         Returns:
-            int: ``-1`` 또는 ``1`` ~ ``9``.
+            int: ``1`` ~ ``17``.
         """
-        return self._compressionGzipLevel
+        return self._compressionLz4Level
 
     def get_compression_zstd_level(self) -> int:
         """zstd 압축 레벨. 기본 3.
@@ -650,7 +651,7 @@ class ILProducerConfig:
     getMaxFrameLength = get_max_frame_length
     isIdempotenceEnabled = is_idempotence_enabled
     getCompressionType = get_compression_type
-    getCompressionGzipLevel = get_compression_gzip_level
+    getCompressionLz4Level = get_compression_lz4_level
     getCompressionZstdLevel = get_compression_zstd_level
 
     def validate(self) -> None:
@@ -671,9 +672,9 @@ class ILProducerConfig:
                 "enableIdempotence requires maxInFlight <= 5 (the engine remembers the last 5 batches"
                 " per partition; Kafka has the same limit)"
             )
-        # 0.8.0: 직접 대입(cfg.compressionType = "lz4")은 빌더의 검사를 거치지 않는다 - 여기서 다시 본다
+        # 0.8.0: 직접 대입(cfg.compressionType = "gzip")은 빌더의 검사를 거치지 않는다 - 여기서 다시 본다
         self._compressionType = _codec.check_type(self._compressionType)
-        _codec.check_gzip_level(self._compressionGzipLevel)
+        _codec.check_lz4_level(self._compressionLz4Level)
         _codec.check_zstd_level(self._compressionZstdLevel)
 
 
@@ -1295,7 +1296,7 @@ class ILTopicProducer:
         self.config.validate()
         cfg = self.config
         # 0.8.0: 배치 압축 - (코덱 번호, 압축 함수). none 이면 압축 함수가 None 이다. zstd 모듈이 없으면 연결하기 전에 여기서 멈춘다
-        self._codec_id, self._compress = _codec.compressor(cfg.get_compression_type(), cfg.get_compression_gzip_level(),
+        self._codec_id, self._compress = _codec.compressor(cfg.get_compression_type(), cfg.get_compression_lz4_level(),
                                                             cfg.get_compression_zstd_level())
         self.topic = topic
         self._topic_bytes = topic.encode("utf-8")

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/ilink/topic.py

@@ -731,7 +731,7 @@ class ILTopicSubscription:
 
     .. note:: 풀지 못한 배치는 그 자리에서 멈춘다 (0.8.0)
 
-        read 응답의 배치를 풀지 못하면(zstd 모듈 없음, 모르는 코덱, 깨진 gzip / zstd 스트림, 배치 CRC 불일치, 레코드 수 /
+        read 응답의 배치를 풀지 못하면(lz4 / zstd 모듈 없음, 모르는 코덱, 깨진 lz4 / zstd 스트림, 배치 CRC 불일치, 레코드 수 /
         길이 불일치) 응답 전체를 버리지 않고 배치마다 가른다. 그 배치(파티션 P, baseOffset B)보다 앞에 푼 레코드와 같은
         응답의 다른 파티션 레코드는 여느 때처럼 준다(``COMMIT_AUTO`` 커밋은 앱에 준 것만). 같은 응답에 실린 P 의 뒤 배치는
         버리고 P 는 이 구독의 연결로 B 로 되감는다(``offset:B;partition:P`` seek - 커서가 B 보다 뒤면 커서로). 그래서 원인이

{jetstream_api-0.8.0 → jetstream_api-0.9.0/jetstream_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.8.0
+Version: 0.9.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,35 @@ 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.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 +135,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 / 전체]`)을 내고 연결을 닫습니다. 전에는 보낼 자리가 날 때까지 기다릴 때마다 한도를 새로 주어, 상대가

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/jetstream_api.egg-info/requires.txt

@@ -1,4 +1,7 @@
 
+[lz4]
+lz4>=4.0
+
 [test]
 docstring_parser>=0.16
 

{jetstream_api-0.8.0 → jetstream_api-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jetstream-api"
-version = "0.8.0"
+version = "0.9.0"
 description = "Python client API for iLink M.O.M. (Message Oriented Middleware)"
 authors = [{name = "snowjeans"}]
 readme = "README.md"
@@ -24,6 +24,8 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
+# 0.9.0: lz4 배치 압축(compressionType("lz4") 발행 / lz4 배치 수신). 없으면 lz4 를 쓸 때만 오류가 난다.
+lz4 = ["lz4>=4.0"]
 # 0.8.0: zstd 배치 압축(compressionType("zstd") 발행 / zstd 배치 수신). 파이썬 3.14+ 는 표준 라이브러리 compression.zstd 를
 # 먼저 쓰므로 이 extra 가 없어도 된다. 둘 다 없으면 zstd 를 쓸 때만 오류가 난다 - 런타임 필수 의존성은 여전히 없다.
 zstd = ["zstandard>=0.22"]