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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.9.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
@@ -60,6 +60,20 @@ lz4 배치 압축을 쓰려면 `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·지연이 중요하면

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

@@ -10,6 +10,20 @@ lz4 배치 압축을 쓰려면 `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·지연이 중요하면

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

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

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

@@ -1,6 +1,6 @@
 """배치 압축 코덱(0.8.0, 0.9.0 에서 gzip 을 빼고 lz4 를 넣었다). **내부 모듈이다** - 발행과 소비가 함께 쓴다.
 
-발행 v2 파티션 배치(= 저장 v4 배치)의 레코드 열을 압축하고 푼다. 와이어(엔진 CMPR-1):
+발행 v2 파티션 배치(= 저장 배치, 레코드 v4 / v5 공통)의 레코드 열을 압축하고 푼다. 와이어(엔진 CMPR-1):
 
 - 배치 헤더 52바이트는 압축하지 않는다. 레코드 열 ``[52, batchLength)`` 만 압축한다.
 - 헤더 ``attributes`` 의 하위 3비트가 코덱이다: 0 없음 / 3 lz4 / 4 zstd. 나머지 비트는 0 이다.

{jetstream_api-0.9.0 → jetstream_api-0.10.0}/ilink/common.py

@@ -252,10 +252,11 @@ class ILC:
     #: 0.7.0: 저장 v4 엔진은 보내지 않는다(배치 read 응답은 2042). 구독은 받지 않고 ILTopicFrameMsg 의 해석만 남긴다
     MIMQ_TOPIC_BATCH_MESSAGE = 2024
     #: 저장 v4 배치 read 응답(엔진 DESIGN-storv4 §3) = IL 프레임 하나. 본문(이진 BE) = u16 version=4, u16 partCount,
-    #: partCount x (i32 partition, i64 startOffset), i32 batchCount, v4 배치 x batchCount. 단건 read 는 그대로 2022 다.
+    #: partCount x (i32 partition, i64 startOffset), i32 batchCount, 배치 x batchCount. 단건 read 는 그대로 2022 다.
+    #: 0.10.0: 배치 헤더 magic 4 = 레코드 v4(i32 길이 칸), 5 = 레코드 v5(LEB128 길이 칸, 엔진 REC5-1) - 배치마다 가른다.
     MIMQ_TOPIC_BATCH_V4_MESSAGE = 2042
     #: 발행 v2 봉투(엔진 DESIGN-pubv2). IL 헤더 + 이진 big-endian 본문(version, acks, flags, corrId, topicEpoch,
-    #: 토픽, 파티션 배치 N개 - 배치 = 저장 v4 배치, CRC-32).
+    #: 토픽, 파티션 배치 N개 - 배치 = 저장 배치 헤더 52바이트 + 레코드 열, CRC-32). 0.10.0 부터 producer 는 magic 5(레코드 v5)만 쓴다.
     MIMQ_TOPIC_PUBLISH_V2_MESSAGE = 2040
     #: 발행 v2 ACK. corrId + 봉투 code / 사유 + 배치 수 + 배치마다 {partition, code, baseOffset, timestamp,
     #: expectedSeq, 사유}. 봉투 헤더를 못 읽으면 봉투 code / 사유만 싣고 배치 수 0 이다.

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

@@ -605,20 +605,148 @@ _V4_I = struct.Struct(">i")
 _V4_BH = struct.Struct(">qiqbbHIiqqi")
 
 
+def _records_v4(rb, r: int, rend: int, count: int, first: int, part: int, base: int, ts: int, make, append,
+                topic_name) -> int:
+    # 레코드 v4(배치 magic 4): [i32 keyLen][key][i32 propsLen][props][i32 valueLen][value], -1 = 없음(길이 칸이 레코드당
+    #   12바이트). 0.10.0 에 _decode 에서 떼어 냈다 - 검사와 오류 문구는 그대로다. first 앞 레코드는 길이만 걸어 넘긴다(키를
+    #   풀지 않는다). 돌려주는 값 = 레코드 열이 끝난 자리
+    i32 = _V4_I.unpack_from
+    for i in range(count):
+        if r + 4 > rend:
+            raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (4, r, rend))
+        (kl,) = i32(rb, r)
+        r += 4
+        if kl > 0:
+            if r + kl > rend:
+                raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (kl, r, rend))
+            key = rb[r:r + kl].decode("utf-8") if i >= first else None
+            r += kl
+        else:
+            key = ""
+        if r + 4 > rend:
+            raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (4, r, rend))
+        (pl,) = i32(rb, r)
+        r += 4
+        if pl > 0:
+            if r + pl > rend:
+                raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (pl, r, rend))
+            props = rb[r:r + pl]
+            r += pl
+        else:
+            props = None
+        if r + 4 > rend:
+            raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (4, r, rend))
+        (vl,) = i32(rb, r)
+        r += 4
+        if vl < 0:
+            raise ValueError("invalid record value length %d" % vl)
+        if r + vl > rend:
+            raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (vl, r, rend))
+        if i >= first:
+            append(make(part, base + i, ts, key, rb[r:r + vl], props, topic_name))
+        r += vl
+    return r
+
+
+def _v5_len(rb, r: int, rend: int, what: str):
+    # 0.10.0 레코드 v5 길이 칸 하나를 첫 바이트부터 읽는다 - (적힌 값 = 길이 + 1, 다음 자리). 한 / 두 바이트짜리는 부르는
+    #   쪽이 먼저 처리하고 여기서는 잘림 / 세 바이트 이상 / 넘침을 본다. 거절(엔진 REC5-1 1절): 5바이트를 넘는 부호화, 적힌 값이
+    #   2^31 이상, 잘림. 가장 짧은 부호화는 강제하지 않는다(쓰는 쪽은 늘 가장 짧게 쓴다)
+    at = r
+    v = 0
+    shift = 0
+    while True:
+        if r >= rend:
+            raise ValueError("invalid v5 varint (%s length truncated at %d, records end at %d)" % (what, at, rend))
+        c = rb[r]
+        r += 1
+        v |= (c & 0x7F) << shift
+        if c < 0x80:
+            break
+        shift += 7
+        if shift >= 35:
+            raise ValueError("invalid v5 varint (%s length longer than 5 bytes at %d)" % (what, at))
+    if v > 0x7FFFFFFF:
+        raise ValueError("invalid v5 varint (%s length field %d >= 2^31 at %d)" % (what, v, at))
+    return v, r
+
+
+def _records_v5(rb, r: int, rend: int, count: int, first: int, part: int, base: int, ts: int, make, append,
+                topic_name) -> int:
+    # 0.10.0 레코드 v5(배치 magic 5, 엔진 REC5-1): [uv keyLen+1][key][uv propsLen+1][props][uv valueLen+1][value],
+    #   uv = unsigned LEB128. 적힌 값 0 = 없음, 1 = 빈 값. 한 바이트 / 두 바이트짜리(적힌 값 16,383 까지 - 두 바이트에서는
+    #   넘침이 없다)는 여기서 곧바로 읽고, 그 밖(잘림 포함)은 _v5_len 이 거절 규칙과 함께 읽는다. 키 / 속성의 뜻은 v4 와 같다
+    #   (키 없음 / 빈 키 = "", 속성 없음 / 빈 속성 = None). 값 없음(0)은 거절한다(v4 의 valueLen < 0 과 같다). 잘린 본문 / 끝
+    #   자리 검사와 문구는 v4 와 같다
+    for i in range(count):
+        kl = rb[r] if r < rend else 0x80
+        if kl < 0x80:
+            r += 1
+        elif r + 1 < rend and rb[r + 1] < 0x80:
+            kl = (kl & 0x7F) | (rb[r + 1] << 7)
+            r += 2
+        else:
+            kl, r = _v5_len(rb, r, rend, "key")
+        if kl > 1:
+            kl -= 1
+            if r + kl > rend:
+                raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (kl, r, rend))
+            key = rb[r:r + kl].decode("utf-8") if i >= first else None
+            r += kl
+        else:
+            key = ""
+        pl = rb[r] if r < rend else 0x80
+        if pl < 0x80:
+            r += 1
+        elif r + 1 < rend and rb[r + 1] < 0x80:
+            pl = (pl & 0x7F) | (rb[r + 1] << 7)
+            r += 2
+        else:
+            pl, r = _v5_len(rb, r, rend, "props")
+        if pl > 1:
+            pl -= 1
+            if r + pl > rend:
+                raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (pl, r, rend))
+            props = rb[r:r + pl]
+            r += pl
+        else:
+            props = None
+        vl = rb[r] if r < rend else 0x80
+        if vl < 0x80:
+            r += 1
+        elif r + 1 < rend and rb[r + 1] < 0x80:
+            vl = (vl & 0x7F) | (rb[r + 1] << 7)
+            r += 2
+        else:
+            vl, r = _v5_len(rb, r, rend, "value")
+        if not vl:
+            raise ValueError("invalid v5 record value (absent - length field 0, record %d)" % i)
+        vl -= 1
+        if r + vl > rend:
+            raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (vl, r, rend))
+        if i >= first:
+            append(make(part, base + i, ts, key, rb[r:r + vl], props, topic_name))
+        r += vl
+    return r
+
+
 def _v4_tuple(partition, offset, timestamp, key, value, property_bytes, _topic_name):
     # records() 의 튜플 - _decode 의 make 자리에 들어간다
     return (partition, offset, timestamp, key, value, property_bytes)
 
 
 class ILTopicBatchV4Msg(ILInnerMsg):
-    """소비자 배치 read 응답(``MIMQ_TOPIC_BATCH_V4_MESSAGE`` 2042, 엔진 저장 v4). **수신 전용**이다.
+    """소비자 배치 read 응답(``MIMQ_TOPIC_BATCH_V4_MESSAGE`` 2042). **수신 전용**이다.
 
     본문은 이진 big-endian 이다 - ``u16 version=4 | u16 partCount | partCount x (i32 partition, i64 startOffset) |
-    i32 batchCount | v4 배치 x batchCount``. 배치는 발행 v2 의 파티션 배치와 같은 형식(52바이트 헤더 + 레코드)이고
+    i32 batchCount | 배치 x batchCount``(배치마다 레코드 magic 4 / 5). 배치는 발행 v2 의 파티션 배치와 같은 형식(52바이트 헤더 + 레코드)이고
     엔진이 baseOffset / timestamp 를 채웠다. 레코드 오프셋은 baseOffset + 순번, 시각은 배치 timestamp 다.
 
     0.8.0: 배치는 압축돼 있을 수 있다(헤더 attributes 하위 3비트 = 코덱: 0 없음 / 3 lz4 / 4 zstd). 엔진은 저장한
     바이트를 그대로 보내므로 배치마다 코덱을 보고 레코드 열을 푼다 - 한 응답에 코덱이 섞여도 된다.
+
+    0.10.0: 레코드 형식은 배치 헤더 magic 으로 가른다 - 4 는 길이 칸이 i32 셋(레코드당 12바이트), 5 는 길이 칸이
+    unsigned LEB128 셋(길이 + 1 을 1~5바이트로, 엔진 REC5-1)이다. 배치마다 보므로 한 응답에 섞여도 된다.
     """
 
     def __init__(self, content: bytes) -> None:
@@ -642,8 +770,10 @@ class ILTopicBatchV4Msg(ILInnerMsg):
             ValueError: 형식이 깨졌거나 배치 CRC 가 맞지 않을 때. 압축 배치를 풀지 못할 때 - 모르는 코덱
                 ``MIMQE_TOPIC_UNSUPPORTED_CODEC (codec N)``, zstd 모듈이 없음 ``MIMQE_NOT_SUPPORTED`` (설치 안내
                 ``pip install "jetstream-api[zstd]"`` 를 싣는다), 깨졌거나 잘렸거나 128MiB 를 넘음
-                ``MIMQE_TOPIC_CODEC_ERROR (...)``, 푼 레코드 수 / 길이가 헤더와 다름. 배치를 풀지 못한 오류는 문구에 그
-                배치의 파티션과 baseOffset 을 싣는다(``(partition P, base B)``).
+                ``MIMQE_TOPIC_CODEC_ERROR (...)``, 푼 레코드 수 / 길이가 헤더와 다름, 레코드 v5 길이 칸이 깨짐
+                ``invalid v5 varint (...)``(5바이트를 넘음 / 적힌 값 2^31 이상 / 잘림) 또는 값 없음
+                ``invalid v5 record value (absent ...)``. 배치를 풀지 못한 오류는 문구에 그 배치의 파티션과 baseOffset 을
+                싣는다(``(partition P, base B)``).
         """
         return self._decode(_v4_tuple, None)
 
@@ -681,7 +811,6 @@ class ILTopicBatchV4Msg(ILInnerMsg):
         out = []
         append = out.append
         mv = memoryview(b)
-        i32 = _V4_I.unpack_from
         head = _V4_BH.unpack_from
         crc32 = zlib.crc32
         decompress = _codec.decompress
@@ -695,7 +824,7 @@ class ILTopicBatchV4Msg(ILInnerMsg):
                 self._cut(first_at, p, start, dead, exc, fails)
                 return out
             base, blen, ts, magic, attr, _resv, crc, part, _pid, _base_seq, count = head(b, p)
-            if magic != 4 or blen < 52 or blen > n - p or count < 0:
+            if (magic != 5 and magic != 4) or blen < 52 or blen > n - p or count < 0:
                 exc = ValueError("invalid topic batch header (magic %d, length %d, records %d)" % (magic, blen, count))
                 if fails is None:
                     raise exc
@@ -724,40 +853,9 @@ class ILTopicBatchV4Msg(ILInnerMsg):
                     r = p + 52
                     rend = end
                 first = 0 if low is None or low <= base else low - base
-                for i in range(count):
-                    if r + 4 > rend:
-                        raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (4, r, rend))
-                    (kl,) = i32(rb, r)
-                    r += 4
-                    if kl > 0:
-                        if r + kl > rend:
-                            raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (kl, r, rend))
-                        key = rb[r:r + kl].decode("utf-8") if i >= first else None
-                        r += kl
-                    else:
-                        key = ""
-                    if r + 4 > rend:
-                        raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (4, r, rend))
-                    (pl,) = i32(rb, r)
-                    r += 4
-                    if pl > 0:
-                        if r + pl > rend:
-                            raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (pl, r, rend))
-                        props = rb[r:r + pl]
-                        r += pl
-                    else:
-                        props = None
-                    if r + 4 > rend:
-                        raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (4, r, rend))
-                    (vl,) = i32(rb, r)
-                    r += 4
-                    if vl < 0:
-                        raise ValueError("invalid record value length %d" % vl)
-                    if r + vl > rend:
-                        raise ValueError("truncated topic batch (need %d bytes at %d, have %d)" % (vl, r, rend))
-                    if i >= first:
-                        append(make(part, base + i, ts, key, rb[r:r + vl], props, topic_name))
-                    r += vl
+                # 0.10.0: 배치마다 magic 으로 레코드 형식을 가른다(4 = i32 길이 칸, 5 = LEB128 길이 칸 - 한 응답에 섞여도 된다)
+                r = (_records_v5 if magic == 5 else _records_v4)(rb, r, rend, count, first, part, base, ts, make, append,
+                                                                 topic_name)
                 if r != rend:
                     if codec:
                         raise ValueError("topic batch length mismatch (records end at %d of %d decompressed bytes, codec %d)"

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

@@ -300,8 +300,9 @@ class ILProducerConfig:
 
         Note:
             봉투는 준비된 파티션 배치들을 이 크기까지 싣는다. 레코드 하나가 혼자 실린 봉투
-            (봉투 헤더 24 + 토픽 이름 + 배치 헤더 52 + 레코드 고정 12 + key + 속성 + 값)가 이 값보다
-            크면 :meth:`ILTopicProducer.send` 가 즉시 거부한다. key 와 속성은 각각 99,999바이트까지다.
+            (봉투 헤더 24 + 토픽 이름 + 배치 헤더 52 + 레코드 길이 칸 셋 + key + 속성 + 값)가 이 값보다
+            크면 :meth:`ILTopicProducer.send` 가 즉시 거부한다. 길이 칸은 key / 속성 / 값마다 1~5바이트다(0.10.0
+            레코드 v5 - 126바이트까지 1바이트, 16,382바이트까지 2바이트). key 와 속성은 각각 99,999바이트까지다.
 
             배치는 토픽의 세그먼트 크기(SEGMENTBYTES, producer 생성 때 받아 둔다)에도 맞춰 끊는다 -
             엔진은 레코드마다 약 (160 + 토픽 이름 길이) 바이트를 더 붙여 저장하므로 그만큼을 더해
@@ -1047,12 +1048,14 @@ def _extract_leader_hint(exc: Exception) -> str | None:
 _IDEM_PROTOCOL = "3"
 
 # 발행 v2 와이어(엔진 DESIGN-pubv2 2장). 숫자는 모두 이진 big-endian 이다.
-#: 파티션 배치 헤더 = 저장 v4 배치 헤더
+#: 파티션 배치 헤더 = 저장 배치 헤더(v4 / v5 가 같다)
 _BATCH_HEADER = 52
 #: 배치 CRC 가 덮는 구간의 시작(partition 칸부터 배치 끝까지)
 _CRC_FROM = 28
-#: 레코드 고정 칸: keyLen 4 + propsLen 4 + valueLen 4
-_RECORD_OVERHEAD = 12
+#: 0.10.0: 배치 머리 magic - 레코드 v5(엔진 REC5-1). 쓰기는 v5 만 한다(소비 쪽은 4 / 5 둘 다 읽는다)
+_MAGIC = 5
+#: 레코드 v5 의 가장 작은 크기: 길이 칸 셋이 각 1바이트(key 없음 / 속성 없음 / 빈 값)
+_RECORD_MIN = 3
 #: 봉투 본문 고정 칸: version 1 + acks 1 + flags 2 + corrId 8 + topicEpoch 8 + topicLen 2 + batchCount 2(토픽 바이트 제외)
 _ENVELOPE_FIXED = 24
 #: 1단계 엔진이 v3 레코드로 옮길 수 있는 key / props 길이 상한(v3 칸 폭 5자리)
@@ -1071,11 +1074,12 @@ _SIZE_SUSPECT_BYTES = ILC.MIMQ_MIN_MAX_FRAME_LENGTH
 #: 재시도 보호: 큰 봉투에 실려 응답 없이 끊긴 뒤 혼자 보냈는데도 또 끊긴 배치는 실패로 올린다(연속 횟수).
 _SIZE_DROP_LIMIT = 2
 
-_I32 = struct.Struct(">i")
-#: 0.7.3: 레코드를 배치 버퍼에 곧바로 붙일 때 - (keyLen, propsLen, valueLen) / (propsLen, valueLen)
-_III = struct.Struct(">iii")
-_II = struct.Struct(">ii")
-_NEG1 = _I32.pack(-1)
+#: 0.10.0 레코드 v5 길이 칸 = unsigned LEB128(한 바이트에 7비트, 낮은 자리 먼저, 윗비트 1 = 다음 바이트 있음)로 적은
+#: 길이 + 1(0 = 없음, 1 = 빈 값). 늘 가장 짧게 쓴다. 한 바이트짜리(적는 값 127 까지)는 이 표에서 꺼낸다
+_UV1 = tuple(bytes((i,)) for i in range(0x80))
+#: 없음 칸 하나 / 둘(key 없음 + 속성 없음)
+_ABSENT = _UV1[0]
+_ABSENT2 = _UV1[0] * 2
 _U16 = struct.Struct(">H")
 #: 배치 헤더 앞 24바이트: baseOffset(엔진이 채움), batchLength, timestamp(엔진이 채움), magic, attributes, reserved
 _HEAD_A = struct.Struct(">qiqbbH")
@@ -1105,6 +1109,39 @@ _CODE_NAMES = {
 }
 
 
+#: 0.10.0: 속성 없는 레코드의 머리 조각 캐시. 값 길이 -> [속성 없음 0][값 길이 칸] / [key 없음 0][속성 없음 0][값 길이 칸].
+#: 같은 크기 값이 되풀이되는 흔한 경우 길이 칸을 만들지 않고 한 조각으로 붙인다(0.9.0 의 pack 한 번보다 싸다).
+#: 여러 producer 가 함께 쓴다 - dict 한 번의 읽기 / 쓰기라 잠금 없이 둔다. 4096개가 차면 비운다
+_HEAD1: dict = {}
+_HEAD2: dict = {}
+_HEAD_CACHE_MAX = 4096
+
+
+def _heads(vl: int) -> tuple:
+    """속성 없는 레코드의 머리 조각 둘(key 있음 / 없음)을 만들어 캐시에 넣는다(0.10.0). ``vl`` = 값 길이."""
+    vh = _uv(vl + 1)
+    if len(_HEAD1) >= _HEAD_CACHE_MAX:
+        _HEAD1.clear()
+        _HEAD2.clear()
+    h1 = _HEAD1[vl] = _ABSENT + vh
+    h2 = _HEAD2[vl] = _ABSENT2 + vh
+    return h1, h2
+
+
+def _uv(n: int) -> bytes:
+    """레코드 v5 길이 칸 하나(0.10.0). ``n`` = 길이 + 1 을 가장 짧은 LEB128 로 적는다(1~5바이트)."""
+    if n < 0x80:
+        return _UV1[n]
+    if n < 0x4000:
+        return _U16.pack(0x8000 | ((n & 0x7F) << 8) | (n >> 7))
+    out = bytearray()
+    while n >= 0x80:
+        out.append((n & 0x7F) | 0x80)
+        n >>= 7
+    out.append(n)
+    return bytes(out)
+
+
 def _ascii(value: int, width: int) -> bytes:
     """IL 헤더 숫자 칸: 좌측 정렬 ASCII 10진 + 나머지 0x00."""
     return str(value).encode("ascii").ljust(width, b"\x00")
@@ -1323,7 +1360,7 @@ class ILTopicProducer:
         self._max_env_content = min(cfg.get_max_request_size(),
                                     cfg.get_max_frame_length() - ILC.SZ_IL_HEADER)
         #: 배치 하나가 레코드를 더 받지 않는 크기 = min(batchSize, 봉투 본문 상한 - 봉투 고정 칸)
-        self._batch_limit = max(_BATCH_HEADER + _RECORD_OVERHEAD,
+        self._batch_limit = max(_BATCH_HEADER + _RECORD_MIN,
                                 min(cfg.get_batch_size(),
                                     self._max_env_content - _ENVELOPE_FIXED - len(self._topic_bytes)))
         #: 레코드 1건의 엔진 저장 부담 = 160 + 토픽 이름 바이트
@@ -1360,7 +1397,7 @@ class ILTopicProducer:
         self._used = 0
         self._sticky = -1
         self._sticky_bytes = 0
-        #: 키 캐시(0.7.2, 0.7.3 에 모양을 바꿈). 키(str) -> [UTF-8 바이트, 레코드 앞머리(keyLen+key), 파티션, 그때의 파티션 수].
+        #: 키 캐시(0.7.2, 0.7.3 에 모양을 바꿈). 키(str) -> [UTF-8 바이트, 레코드 앞머리(v5 길이 칸 + key), 파티션, 그때의 파티션 수].
         #: 파티션 수가 바뀌면 비운다. 256바이트를 넘는 키는 넣지 않는다, 16384개가 차면 비운다
         self._key_parts: dict = {}
         #: 깨울 신호를 이미 보냈고 I/O 스레드가 아직 비우지 않았다(0.7.2 - 신호를 합친다)
@@ -1599,14 +1636,14 @@ class ILTopicProducer:
             raise ILOperationException(
                 "MIMQE_INVALID_ARGUMENT (record topic '%s' is not the producer topic '%s' - a producer publishes"
                 " only to the topic it was created for)" % (record.topic, self.topic))
-        # 0.7.3: 키 캐시 항목 [UTF-8 바이트, 레코드 앞머리(keyLen+key), 파티션, 그때의 파티션 수]. 바이트 / 앞머리는 파티션
+        # 0.7.3: 키 캐시 항목 [UTF-8 바이트, 레코드 앞머리(v5 길이 칸 + key), 파티션, 그때의 파티션 수]. 바이트 / 앞머리는 파티션
         #   수와 무관해 잠금 밖에서 읽고, 파티션은 잠금 안에서만 읽고 쓴다(파티션 수가 다르면 다시 계산)
         key_s = record.key
         if key_s:
             ent = self._key_parts.get(key_s)
             if ent is None:
                 key = key_s.encode("utf-8")
-                ent = [key, _I32.pack(len(key)) + key, -1, -1]
+                ent = [key, _uv(len(key) + 1) + key, -1, -1]
                 if len(key) <= _KEY_CACHE_MAX_KEY:
                     kp = self._key_parts
                     if len(kp) >= _KEY_CACHE_MAX:
@@ -1629,7 +1666,21 @@ class ILTopicProducer:
         if pl > _MAX_PROPS_BYTES:
             raise ILOperationException("MIMQE_MSG_SIZE_OVER (properties too large: %d bytes > %d)" % (pl, _MAX_PROPS_BYTES))
         vl = len(value)
-        rec_size = _RECORD_OVERHEAD + kl + pl + vl
+        # 0.10.0 레코드 v5: [길이 칸][key][길이 칸][속성][길이 칸][값], 길이 칸 = 길이 + 1 의 LEB128(1~5바이트). key 칸은 키 캐시
+        #   항목의 앞머리(ent[1])를 그대로 쓴다. 크기 검사(maxRequestSize / maxFrameLength / 세그먼트 / bufferMemory / batchSize)는
+        #   이 부호화 길이 그대로 센다. 속성 없는 흔한 경우는 [속성 없음][값 길이 칸] 머리를 값 길이별 캐시(_HEAD1 / _HEAD2)에서
+        #   꺼내 한 조각으로 붙인다
+        if props:
+            ph = _uv(pl + 1)
+            vh = _uv(vl + 1)
+            head = None
+            rec_size = (len(ent[1]) if ent is not None else 1) + len(ph) + pl + len(vh) + vl
+        elif ent is None:
+            head = _HEAD2.get(vl) or _heads(vl)[1]
+            rec_size = len(head) + vl
+        else:
+            head = _HEAD1.get(vl) or _heads(vl)[0]
+            rec_size = len(ent[1]) + len(head) + vl
         # 이 레코드 혼자 실린 봉투의 본문 크기
         alone = self._alone_base + rec_size
         if alone > self._max_request_size:
@@ -1713,16 +1764,17 @@ class ILTopicProducer:
                     self._queued += 1
                     self._used += _BATCH_HEADER
                     wake = True
-                # 0.7.3: 레코드를 따로 만들지 않고 배치 버퍼에 곧바로 붙인다(속성 없는 흔한 경우는 pack 한 번). 와이어 바이트는 같다
+                # 0.7.3: 레코드를 따로 만들지 않고 배치 버퍼에 곧바로 붙인다. 0.10.0: 길이 칸은 위에서 만든 v5 칸(head 또는 ph / vh)
                 buf = b.buf
-                if not props:
-                    if ent is None:
-                        buf += _III.pack(-1, -1, vl)
-                    else:
+                if head is not None:
+                    if ent is not None:
                         buf += ent[1]
-                        buf += _II.pack(-1, vl)
+                    buf += head
                 else:
-                    buf += b"".join((_I32.pack(kl) if key else _NEG1, key or b"", _I32.pack(pl), props, _I32.pack(vl)))
+                    buf += ent[1] if ent is not None else _ABSENT
+                    buf += ph
+                    buf += props
+                    buf += vh
                 buf += value
                 self._used += rec_size
                 future = ILPublishFuture(self._delivery_timeout_ms, b.result, b.count)
@@ -2143,13 +2195,13 @@ class ILTopicProducer:
         buf = b.buf
         body = b.body
         if body is None:
-            _HEAD_A.pack_into(buf, 0, 0, len(buf), 0, 4, 0, 0)
+            _HEAD_A.pack_into(buf, 0, 0, len(buf), 0, _MAGIC, 0, 0)
             _HEAD_B.pack_into(buf, _CRC_FROM, b.partition, use_pid, b.base_seq if use_pid >= 0 else -1, b.count)
             _CRC.pack_into(buf, 24, zlib.crc32(memoryview(buf)[_CRC_FROM:]) & 0xFFFFFFFF)
         else:
             # 0.8.0 압축 배치: batchLength = 52 + 압축 길이, attributes = 코덱, recordCount = 원래 건수,
             #   CRC = [28, 52) 헤더 + 압축한 바이트(엔진 CMPR-1). 헤더를 다시 쓸 때마다(pid / baseSeq) CRC 도 다시 센다
-            _HEAD_A.pack_into(buf, 0, 0, _BATCH_HEADER + len(body), 0, 4, b.attr, 0)
+            _HEAD_A.pack_into(buf, 0, 0, _BATCH_HEADER + len(body), 0, _MAGIC, b.attr, 0)
             _HEAD_B.pack_into(buf, _CRC_FROM, b.partition, use_pid, b.base_seq if use_pid >= 0 else -1, b.count)
             _CRC.pack_into(buf, 24,
                            zlib.crc32(body, zlib.crc32(memoryview(buf)[_CRC_FROM:_BATCH_HEADER])) & 0xFFFFFFFF)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.9.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
@@ -60,6 +60,20 @@ lz4 배치 압축을 쓰려면 `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·지연이 중요하면

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jetstream-api"
-version = "0.9.0"
+version = "0.10.0"
 description = "Python client API for iLink M.O.M. (Message Oriented Middleware)"
 authors = [{name = "snowjeans"}]
 readme = "README.md"