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

{jetstream_api-0.7.4 → jetstream_api-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.7.4
+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,10 @@ 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
 Requires-Dist: docstring_parser>=0.16; extra == "test"
 Dynamic: license-file
@@ -49,11 +53,96 @@ Dynamic: license-file
 Python으로 작성된 ILink 클라이언트 API입니다.
 
 ## 시스템 요구 사항
-시스템에 python 13 이상, pip가 설치되어 있어야 합니다.
+시스템에 Python 3.9 이상, pip가 설치되어 있어야 합니다. 필수 의존성은 없습니다(표준 라이브러리만 씁니다).
+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)에서만 받습니다. 그보다 옛 엔진은 압축 배치를 알아보지 못해
+  거절합니다. 기본값은 압축하지 않음(`none`)이라 설정하지 않으면 동작이 그대로입니다.
+- **producer 설정** - 뜻과 기본값이 Kafka `compression.type` / `compression.gzip.level` / `compression.zstd.level` 과 같습니다:
+  - `compressionType("none" | "gzip" | "zstd")` (`compression_type`) - 기본 `"none"`. 소문자 그대로 씁니다(자바 / Kafka 와 같습니다).
+    `lz4` / `snappy` 는 지원하지 않습니다(`ValueError`).
+  - `compressionGzipLevel(n)` (`compression_gzip_level`) - `-1`(zlib 기본 레벨 6, 기본값) 또는 `1`~`9`.
+  - `compressionZstdLevel(n)` (`compression_zstd_level`) - `-131072`~`22`, 기본 `3`.
+  - 게터 `get_compression_type()` / `get_compression_gzip_level()` / `get_compression_zstd_level()`
+    (camelCase `getCompressionType()` / `getCompressionGzipLevel()` / `getCompressionZstdLevel()`).
+  - 범위 밖 값은 빌더에서 곧바로 `ValueError` 입니다. 직접 대입(`cfg.compressionType = "lz4"`)은 producer 생성 때
+    (`validate()`) 막습니다. 설정은 예전처럼 producer 생성 때 복사합니다.
+- **zstd 는 선택 설치입니다**: `pip install "jetstream-api[zstd]"`(`zstandard>=0.22`). 파이썬 3.14 이상이면 표준 라이브러리
+  `compression.zstd` 를 먼저 쓰므로 설치하지 않아도 됩니다. gzip 은 표준 라이브러리(zlib)만 씁니다 - 필수 의존성은 여전히
+  없습니다. zstd 모듈이 없으면 `compressionType("zstd")` producer 생성이 연결하기 전에 `ILOperationException`
+  (`MIMQE_NOT_SUPPORTED (compressionType zstd: no zstd module - pip install ...)`)으로 멈추고, zstd 배치를 받은 구독 read 는
+  `ILException`(원인 `MIMQE_NOT_SUPPORTED (codec 4 zstd: no zstd module - pip install ...)`)입니다(자바와 같은 사유). 이 read
+  오류는 `MIMQC_USER_FAULT` / `MIMQE_NOT_SUPPORTED` 이고 그 배치에서 멈춥니다(아래 "풀지 못한 배치").
+- **발행**: 파티션 배치를 보낼 때 레코드 열만 한 번 압축합니다(배치 헤더 52바이트는 그대로, `recordCount` 는 원래 건수, 배치
+  CRC 는 압축한 바이트가 대상). 재전송(연결 끊김, 순서 오류 재번호, PID 재발급)은 같은 압축 바이트에 헤더와 CRC 만 새로
+  씁니다. 압축해도 줄지 않는 배치(이미 압축된 자료, 무작위 바이트)는 압축하지 않고 보냅니다 - 한 토픽에 섞여도 됩니다.
+  `batchSize` 와 레코드 크기 검사(`maxRequestSize`, `maxFrameLength`, 토픽 세그먼트, `bufferMemory`)는 압축 **전** 크기로
+  셉니다(Kafka 와 같습니다). 봉투에 배치를 채울 때는 압축한 **뒤** 길이로 세므로 봉투 하나에 배치가 더 실립니다.
+- **압축은 producer 의 I/O 스레드가 합니다**: `send()` 는 예전처럼 배치 버퍼에 붙이기만 합니다. zlib / zstd 는 압축하는 동안
+  GIL 을 놓으므로 `send()` 를 부르는 스레드와 겹쳐 돕니다. 대신 producer 하나의 압축은 한 스레드라, 느린 코덱(gzip 레벨 6 은
+  텍스트 배치에서 대략 60~70MB/s - 엔진 설계 문서의 측정)은 그 producer 의 발행 천장이 될 수 있습니다. zstd 나 낮은 gzip
+  레벨을 쓰거나 producer 를 늘리세요(한 토픽에 1~4개 안내는 그대로입니다).
+- **소비**: 구독 read(배치 read 2042)와 패턴 구독(다중 토픽 read 2046)이 배치마다 코덱을 보고 풉니다. 한 토픽 / 한 응답에
+  무압축 / gzip / zstd 배치가 섞여도 됩니다. 오프셋과 커서 앞 레코드 빼기는 그대로입니다.
+- **풀지 못한 배치는 그 자리에서 멈춥니다(stop-in-place)**: 풀지 못하는 배치 - 모르는 코덱 `MIMQE_TOPIC_UNSUPPORTED_CODEC (codec N)`,
+  zstd 모듈 없음, 깨짐 / 잘림 / 뒤에 남은 바이트 / 푼 크기 128MiB 초과 `MIMQE_TOPIC_CODEC_ERROR (gzip: ...)` / `(zstd: ...)`, 배치
+  CRC 불일치, 푼 레코드 수 / 길이가 헤더와 다름 - 를 만나도 응답 전체를 버리지 않습니다. 버리면 엔진 읽기 위치만 지나가 그 응답의
+  다른 배치까지 건너뛰고 다음 AUTO 커밋이 그 구간을 덮습니다(유실). Kafka 컨슈머처럼 그 자리에서 멈춥니다:
+  - 그 배치(파티션 P, baseOffset B) 앞에 푼 레코드와 같은 응답의 **다른 파티션** 레코드는 여느 때처럼 줍니다(`COMMIT_AUTO` 커밋은
+    앱에 준 것만). 같은 응답의 P 뒤 배치는 버리고, P 는 구독 연결로 B 로 되감습니다(`offset:B;partition:P` seek - 커서가 B 보다
+    뒤면 커서로). 원인이 풀릴 때까지 P 는 서 있고 아무것도 건너뛰지 않습니다.
+  - 오류는 read 에 `ILException` 으로 옵니다. 이번 호출에 줄 레코드가 있으면 그것을 돌려주고 **다음** read 가 올리며, 없으면
+    곧바로 올립니다. 되감았으므로 그 뒤 read 도 같은 오류입니다 - zstd 모듈을 설치하거나 `seek_to_offset` 으로 그 배치를 넘기면
+    풀립니다(그 파티션을 seek 하면 미뤄 둔 오류도 지웁니다). 다른 파티션이 바빠도 오류가 묻히지 않습니다(레코드를 돌려준 다음
+    호출은 늘 오류입니다).
+  - 분류: zstd 모듈 없음 / 모르는 코덱은 설치·설정 문제라 `MIMQC_USER_FAULT` / `MIMQE_NOT_SUPPORTED`, 깨진 자료는 예전처럼
+    `MIMQC_FATAL_ERROR` / `MIMQE_INTERNAL_ERROR` 입니다. 사유 문구(파티션, baseOffset, 되감은 자리 또는 되감기 거절 사유)는
+    `get_report_msg()` 와 원인(`__cause__`)에 있습니다.
+  - 되감기 seek 가 거절되면(재배정 뒤 이 멤버 것이 아님 4161, 수동 배정 밖) 그대로 둡니다 - 새 주인이 커밋된 자리부터 다시
+    읽습니다. 오류는 같게 올리고 문구에 거절 사유를 적습니다.
+  - `COMMIT_IMMEDIATE` 는 엔진이 읽는 순간 커밋했지만 되감으므로 이 멤버가 그 배치를 다시 받습니다(그 배치만 at-least-once).
+    다시 받기 전에 멤버가 끝나면 그 배치는 다시 오지 않을 수 있습니다(IMMEDIATE 는 at-most-once).
+  - `listen()` 은 받은 레코드를 콜백한 뒤 `on_error` 로 알리고 멈춥니다(요청을 되풀이하며 돌지 않습니다). 패턴 구독은 그 토픽을
+    떼어 내지 않고 그 파티션만 되감으며, 같은 응답의 다른 토픽 레코드는 그대로 줍니다.
+  - 패턴 구독 `read_batch` 는 요청 실패(요청 전체 거절 / 통신 실패)에서도 이 호출에서 이미 모은 레코드를 돌려주고 오류는 다음
+    호출이 올립니다(예전 판은 모은 레코드를 버렸는데 AUTO 커밋 좌표는 이미 병합돼 있어 앱이 못 본 레코드가 커밋됐습니다).
+- **NIO 커넥터 송신은 기한 하나를 씁니다**(`TCPConnectorNIO`, `set_conn` 으로 고른 경우만): 송신 한 번 전체가 접속 대기 시간
+  (최소 1 s)을 기한으로 씁니다. 기한이 지나면 `MIMQE_SESSION_TIMEOUT`(`write waiting time has exceeded the time limit : [Nms]
+  / written : [n / 전체]`)을 내고 연결을 닫습니다. 전에는 보낼 자리가 날 때까지 기다릴 때마다 한도를 새로 주어, 상대가
+  조금씩만 읽으면 송신이 끝없이 길어졌습니다. 기본(블로킹) 커넥터는 그대로입니다.
+- **교차 검증 도구** `tests/cmpr_vectors.py`: `write <dir>` 는 실제 producer 인코딩 경로로 만든 배치(`py-none` / `py-gzip` /
+  `py-zstd` `.batch`)와 기대 레코드(`.json`)를 쓰고, `check <dir>` 는 디렉터리의 모든 `*.batch` 를 실제 소비 파싱 경로로 풀어
+  짝 `.json` 과 대조합니다. 자바 쪽 같은 도구가 쓴 `java-*.batch` 도 함께 검사합니다.
+
 ## 0.7.4 변경 - 패턴 토픽 떼어 내기 = 그룹 탈퇴(LEAVE), seek 규칙 (자바 v2.3.5 와 같음)
 
 - **엔진 요구**: 아래 새 동작은 **엔진 7.0.1.3417 이상**(CONSGRP-1)에서 나옵니다. 그보다 옛 엔진에서는 그룹 탈퇴 요청을 조용히