jetstream-api 0.6.8__tar.gz → 0.6.9__tar.gz

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.6.8
+Version: 0.6.9
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -54,6 +54,18 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.6.9 변경 - 파티션을 클라이언트가 정한다 (엔진 7.0.1.3401 이상 필요)
+
+엔진이 더는 파티션을 고르지 않습니다. 이 판부터 producer 와 관리 API 단건 발행이 파티션을 정해 보냅니다(Kafka 와 같은 방식).
+
+- **키가 있으면** Kafka 와 같은 murmur2 로 **UTF-8 키 바이트**를 해시해 정합니다. 같은 키는 파이썬·자바 어느 클라이언트든 같은 파티션으로 갑니다.
+- **키가 없으면** producer 는 한 파티션에 `batchSize` 바이트씩 붙였다가 다음 파티션으로 넘깁니다(Kafka 3.3+ 균일 스티키). 관리 API 단건 발행은 토픽별 라운드로빈입니다.
+- 토픽의 파티션 수는 처음 보낼 때 한 번 묻습니다. **알 수 없으면(없는 토픽 등) `send()` 가 예외를 던집니다.** `acks=0` 도 같습니다.
+- 멱등 발행(`enableIdempotence(True)`)은 (토픽, 파티션)마다 번호를 매깁니다. 한 레코드가 거절돼도(너무 큼 등) 뒤 레코드는 계속 적재되고, 여러 건을 한 봉투에 묶어 보냅니다.
+- `maxRequestSize`(기본 1MB)는 레코드 한 건과 **봉투 하나의 크기**를 함께 묶습니다.
+
+★ 그 이전 엔진에서는 발행이 모두 실패합니다(파티션 수를 물을 수 없다). 그런 엔진에는 0.6.8 을 쓰십시오.
+
 ## 0.2.0 신규 - pub/sub 토픽
 
 큐에 더해 **pub/sub 토픽**을 지원합니다. 발행된 메시지는 retention 정책이 지울 때까지 보존되어

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/README.md

@@ -8,6 +8,18 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.6.9 변경 - 파티션을 클라이언트가 정한다 (엔진 7.0.1.3401 이상 필요)
+
+엔진이 더는 파티션을 고르지 않습니다. 이 판부터 producer 와 관리 API 단건 발행이 파티션을 정해 보냅니다(Kafka 와 같은 방식).
+
+- **키가 있으면** Kafka 와 같은 murmur2 로 **UTF-8 키 바이트**를 해시해 정합니다. 같은 키는 파이썬·자바 어느 클라이언트든 같은 파티션으로 갑니다.
+- **키가 없으면** producer 는 한 파티션에 `batchSize` 바이트씩 붙였다가 다음 파티션으로 넘깁니다(Kafka 3.3+ 균일 스티키). 관리 API 단건 발행은 토픽별 라운드로빈입니다.
+- 토픽의 파티션 수는 처음 보낼 때 한 번 묻습니다. **알 수 없으면(없는 토픽 등) `send()` 가 예외를 던집니다.** `acks=0` 도 같습니다.
+- 멱등 발행(`enableIdempotence(True)`)은 (토픽, 파티션)마다 번호를 매깁니다. 한 레코드가 거절돼도(너무 큼 등) 뒤 레코드는 계속 적재되고, 여러 건을 한 봉투에 묶어 보냅니다.
+- `maxRequestSize`(기본 1MB)는 레코드 한 건과 **봉투 하나의 크기**를 함께 묶습니다.
+
+★ 그 이전 엔진에서는 발행이 모두 실패합니다(파티션 수를 물을 수 없다). 그런 엔진에는 0.6.8 을 쓰십시오.
+
 ## 0.2.0 신규 - pub/sub 토픽
 
 큐에 더해 **pub/sub 토픽**을 지원합니다. 발행된 메시지는 retention 정책이 지울 때까지 보존되어

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/ilink/__init__.py

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

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/ilink/admin.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import random
 import time
 import uuid
 
@@ -16,6 +17,7 @@ from .exception import (
     ILTimeoutException,
 )
 from .msg import ILDataMsg, ILMsg, ILMsgUtil, ILReportMsg, JMSHeader
+from .partitioner import partition_for_key
 from .properties import (
     ILClusterDefDiag,
     ILClusterPeerDef,
@@ -1020,7 +1022,8 @@ class ILAdminService:
             맞추지 않으므로 그대로 두면 이중화가 사라진다. 성공 직후
             :meth:`getLastClusterWarning` 을 확인하라 - 전파에 실패한 주소가
             ``MIMQW_CLUSTER_NOT_PROPAGATED (호스트:포트)`` 로 남는다(둘 이상이면
-            쉼표로 이어진다. **엔진 rev 3385+**).
+            쉼표로 이어진다. **엔진 rev 3385~3390** - rev 3391 이상은 서비스 간
+            전파가 없어 이 경고도 오지 않는다).
 
         Example::
 
@@ -1261,6 +1264,15 @@ class ILAdminService:
     def getLastClusterWarning(self) -> str:
         """마지막 클러스터 변경이 남긴 **경고**. 없으면 빈 문자열.
 
+        .. warning:: 엔진 rev 3391 이상에서는 **늘 빈 문자열이다**
+
+            클러스터 재설계 2단계(엔진 이력 218 CLSDEF2-1)에서 서비스 사이의 정의
+            전파와 ``MIMQW_CLUSTER_NOT_PROPAGATED`` 가 함께 없어졌다. 정의는 판사만
+            갖고, 판사 ilcc 가 조정자에게 내려 준다. 그래서 지금 엔진은 이 자리에
+            경고를 싣지 않는다. **빈 문자열이 "다 심겼다" 는 뜻이 아니다** - 확인할
+            것이 없어 비어 있을 뿐이다. 정의가 맞는지는 판사에서 ``DIAG CLUSTER`` 로
+            본다. 아래 설명은 **rev 3385~3390 엔진**의 동작이다.
+
         :meth:`createCluster` / :meth:`removeCluster` / :meth:`setClusterProperty`
         는 **성공했더라도** 정의를 세 서비스에 다 심지 못했을 수 있다. 그때 서버가
         응답에 경고를 실어 보내는데, 이 메서드가 그 원문을 돌려준다.
@@ -3210,6 +3222,10 @@ class ILAdminQmgr:
         #: 엔진 버전 문자열. 계열을 봐야 하는 게이트가 쓴다
         #: (:meth:`ILC.is_set_homepath_safe`) - 리비전만으로는 계열이 안 갈린다.
         self.version = version
+        #: v0.6.9 IDEMP: 관리 API 단건 발행용 - 토픽별 파티션 수(TOPIC_METADATA 릴레이)와
+        #: 키 없는 레코드의 라운드로빈 위치.
+        self._topic_partitions: dict[str, int] = {}
+        self._round_robin: dict[str, int] = {}
 
     @staticmethod
     def main(args: list[str]) -> None:
@@ -6463,7 +6479,7 @@ class ILAdminQmgr:
                 만 1~47바이트로 받고 ``.`` / ``..`` 는 거절한다(Kafka 토픽 이름 규칙과
                 같다). 그 이전 엔진은 47바이트 상한만 검사한다. 엔진은 **생성할 때만**
                 검사하므로 이미 있는 토픽은 이름과 상관없이 계속 쓸 수 있다.
-            options (str): ``key=value`` 를 ``,`` 로 이은 문자열. 기본 ``""`` 는
+            options (str): ``key=value`` 를 ``;`` 로 이은 문자열. 기본 ``""`` 는
                 엔진 기본값이다. 예 ``"partitions=3"``, ``"retentionms=86400000"``.
                 **파티션 수는 만든 뒤 바꿀 수 없으니** 여기서 정해야 한다.
 
@@ -6536,7 +6552,7 @@ class ILAdminQmgr:
 
         Args:
             topicName (str): 대상 토픽 이름.
-            options (str): ``key=value`` 를 ``,`` 로 이은 문자열.
+            options (str): ``key=value`` 를 ``;`` 로 이은 문자열.
                 예 ``"retentionms=604800000"``. **파티션 수는 바꿀 수 없다.**
 
         Raises:
@@ -6706,6 +6722,68 @@ class ILAdminQmgr:
         """
         return self.service.inquire_data_or_report(self.qmgrName, code, ext, *args)
 
+    def _partition_count(self, topicName: str, refresh: bool = False) -> int:
+        """토픽의 파티션 수(내부용). 처음 한 번 TOPIC_METADATA 를 릴레이로 묻고 이 핸들에 캐시한다.
+
+        flush 창의 ``MIMQE_TOPIC_FLUSHED`` 는 100ms 간격으로 5초까지 다시 묻는다(flush 는 파티션 수를
+        바꾸지 않는다).
+        """
+        if not refresh:
+            n = self._topic_partitions.get(topicName)
+            if n is not None:
+                return n
+        for attempt in range(51):
+            res = self._relayTopic(ILC.MIMQ_TOPIC_METADATA, None, topicName, "", "")
+            if res.getType() != ILC.MIMQ_REPORT_MESSAGE:
+                raise ILOperationException(
+                    "MIMQE_INVALID_MSG_FORMAT (topic metadata : msg type %d)" % res.getType())
+            rep = res.getReportMsg()
+            if rep.getCode() == ILC.MIMQ_SUCCESSFUL_TOPIC_OPERATION:
+                try:
+                    n = int((rep.getArg1() or "").strip())
+                except ValueError:
+                    n = -1
+                if n < 1:
+                    raise ILOperationException(
+                        "MIMQE_INVALID_MSG_FORMAT (topic metadata : partitions %r)" % rep.getArg1())
+                self._topic_partitions[topicName] = n
+                return n
+            reason = rep.getArg2() or ""
+            if "MIMQE_TOPIC_FLUSHED" in reason and attempt < 50:
+                time.sleep(0.1)
+                continue
+            raise ILOperationException(reason or "topic metadata failed (code=%d)" % rep.getCode())
+
+    def _choose_partition(self, topicName: str, key: str, partition: int | None) -> int:
+        """관리 API 단건 발행의 파티션(내부용). 엔진은 명시 파티션이 없는 발행을 거절한다(IDEMP).
+
+        명시 파티션 > 키의 murmur2(UTF-8, producer 와 같은 :mod:`ilink.partitioner` - 같은 키는 같은
+        파티션) > 키가 없으면 토픽별 라운드로빈. 한 번 부르면 레코드 하나라 producer 처럼 스티키로
+        모을 것이 없다. 시작 위치는 무작위다 - 핸들을 새로 얻어 한 건씩 보내는 쓰임에서 늘 파티션 0 에
+        몰리지 않게 한다.
+        """
+        cached = topicName in self._topic_partitions
+        n = self._partition_count(topicName)
+        if partition is not None and partition >= 0:
+            if partition >= n and cached:
+                n = self._partition_count(topicName, refresh=True)  # 다시 만들어져 늘었을 수 있다
+            if partition >= n:
+                raise ILOperationException(
+                    "MIMQE_INVALID_ARGUMENT (Partition : %d, Available : 0~%d)" % (partition, n - 1))
+            return partition
+        if key:
+            return partition_for_key(key, n)
+        p = self._round_robin.get(topicName)
+        if p is None:
+            p = random.randrange(n)
+        p %= n
+        self._round_robin[topicName] = (p + 1) % n
+        return p
+
+    def _forget_partitions(self, topicName: str) -> None:
+        """토픽이 없거나 파티션 범위 오류면 캐시를 버린다(내부용). 다음 발행이 다시 묻는다."""
+        self._topic_partitions.pop(topicName, None)
+
     def get_qmgr_name(self) -> str:
         """이 핸들이 다루는 큐 관리자 이름.
 
@@ -6816,8 +6894,9 @@ class ILAdminQmgr:
         Args:
             topicName (str): 대상 토픽 이름.
             value (bytes): payload. 빈 값도 허용한다(컴팩션 tombstone).
-            key (str): 파티션 라우팅 키. **UTF-8 69바이트 이하.** 비우면 서버가 고른다.
-            partition (int | None): 파티션 직접 지정. None(기본)이면 서버가 정한다.
+            key (str): 파티션 라우팅 키. **UTF-8 69바이트 이하.** 같은 키는 producer 와 같은
+                파티션으로 간다. 비우면 토픽별 라운드로빈.
+            partition (int | None): 파티션 직접 지정. None(기본)이면 키로 정한다.
 
         Returns:
             tuple[int, int, int]: ``(offset, timestamp, partition)``.

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/ilink/admintopic.py

@@ -503,9 +503,11 @@ class ILAdminTopic:
         Args:
             value (bytes): payload. **빈 값도 허용**한다(컴팩션 tombstone).
             key (str): 파티션 라우팅 키. **UTF-8 로 69바이트 이하**여야 한다.
-                빈 문자열(기본)이면 서버가 라운드로빈으로 고른다.
+                같은 키는 producer 와 같은 파티션으로 간다(murmur2, UTF-8). 빈 문자열(기본)이면
+                이 API 가 토픽별 라운드로빈으로 고른다.
             partition (int | None): 파티션을 직접 고를 때 지정. None(기본)이면
-                키 해시나 라운드로빈으로 서버가 정한다.
+                키 해시나 라운드로빈으로 이 API 가 정한다. 토픽의 파티션 수는 처음 한 번 묻고
+                관리 큐 관리자 핸들에 캐시한다.
 
         Returns:
             tuple[int, int, int]: ``(offset, timestamp, partition)``. timestamp 는
@@ -538,7 +540,9 @@ class ILAdminTopic:
                 "MIMQE_INVALID_ARGUMENT (key over %d bytes : %d)"
                 % (MAX_KEY_BYTES, len(key.encode("utf-8")))
             )
-        options = "" if partition is None else "partition=%d" % partition
+        # v0.6.9 IDEMP: 엔진은 명시 파티션이 없는 발행을 거절한다 - 파티션은 이 API 가 정해 싣는다.
+        part = self.adminQmgr._choose_partition(self.name, key or "", partition)
+        options = "partition=%d" % part
         res = self.adminQmgr._relayTopic(
             ILC.MIMQ_TOPIC_PUBLISH_ONE, bytes(value or b""),
             self.name, key or "", options,
@@ -547,7 +551,10 @@ class ILAdminTopic:
             raise ILMsgTypeException(res.getType(), "msg type must be [MIMQ_REPORT_MESSAGE]")
         report = res.getReportMsg()
         if report.getCode() != ILC.MIMQ_SUCCESSFUL_TOPIC_PUBLISH:
-            raise ILOperationException(report.getArg2())
+            reason = report.getArg2() or ""
+            if "MIMQE_OBJECT_NOT_FOUND" in reason or "MIMQE_INVALID_ARGUMENT (Partition" in reason:
+                self.adminQmgr._forget_partitions(self.name)    # 다시 만들어졌을 수 있다 - 다음 발행이 다시 묻는다
+            raise ILOperationException(reason)
         return (int(report.getArg1() or "0"),
                 int(report.getArg2() or "0"),
                 int(report.getArg3() or "0"))

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/ilink/common.py

@@ -439,6 +439,10 @@ class ILC:
     #: 관리 연결(ilsvc 릴레이)로 레코드 **한 건**을 발행한다. 엔진 rev 3295 신설.
     #: arg1=토픽, arg2=키(<=69바이트), arg3="partition=N"(생략 가능), extension=페이로드.
     MIMQ_TOPIC_PUBLISH_ONE = 3390
+    #: 토픽 메타데이터 조회(IDEMP, 엔진 이력 246). arg1=토픽. 성공 4156 이면 arg1=파티션 수,
+    #: arg2=epoch. 실패 4157 이면 arg2=사유(없는 토픽은 MIMQE_OBJECT_NOT_FOUND, flush 창이면
+    #: MIMQE_TOPIC_FLUSHED - 재시도할 수 있다). 데이터 연결과 관리 연결 릴레이 둘 다 받는다.
+    MIMQ_TOPIC_METADATA = 3397
 
     # 토픽 응답 코드
     MIMQ_SUCCESSFUL_TOPIC_OPERATION = 4156

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/ilink/msg.py

@@ -819,8 +819,35 @@ class ILTopicFrameMsg(ILInnerMsg):
         ba[msg_size] = 0x0A
         return bytes(ba)
 
+    #: PUBLISH 프레임(헤더 포함) 안 고정 칸의 시작 위치. 헤더 25 + 토픽 70 + corrId 20 + ackMode 1 = 116.
+    PUBLISH_PARTITION_OFFSET = 116
+    PUBLISH_PID_OFFSET = 126
+    PUBLISH_SEQ_OFFSET = 146
+
+    @staticmethod
+    def patchPidSeq(buf: bytearray, frame_start: int, pid: int, seq: int) -> None:
+        """직렬화된 PUBLISH 프레임의 pid/seq 칸을 **제자리에서** 덮어쓴다.
+
+        멱등 seq 는 봉투를 만들 때 매긴다(재번호 때문에 send 시점에는 정할 수 없다). 두 칸은
+        고정 위치라 프레임을 다시 직렬화하지 않고 바꿀 수 있다.
+
+        Args:
+            buf (bytearray): 프레임이 들어 있는 버퍼(봉투 조립 버퍼).
+            frame_start (int): 버퍼 안에서 그 프레임이 시작하는 위치(헤더 첫 바이트).
+            pid (int): producer id.
+            seq (int): 이 (토픽, 파티션)의 seq.
+        """
+        for off, value in ((ILTopicFrameMsg.PUBLISH_PID_OFFSET, pid),
+                           (ILTopicFrameMsg.PUBLISH_SEQ_OFFSET, seq)):
+            raw = str(value).encode("ascii")
+            if len(raw) > 20:
+                raise ValueError("pid/seq over 20 digits: %d" % value)
+            start = frame_start + off
+            buf[start:start + 20] = raw + b"\x00" * (20 - len(raw))
+
     create_publish = createPublish
     build_batch_publish_envelope = buildBatchPublishEnvelope
+    patch_pid_seq = patchPidSeq
 
     # ── 발행 프레임 필드 지정 (Java 의 setter 대응) ──────────────────────
     def setAckMode(self, ack_mode: str) -> None:

jetstream_api-0.6.9/ilink/partitioner.py

@@ -0,0 +1,78 @@
+"""토픽 파티셔너 - 키로 파티션 번호를 정한다(Kafka ``DefaultPartitioner`` 와 같은 규칙).
+
+엔진은 발행 레코드의 파티션을 고르지 않는다(IDEMP 설계 v0.4, 사용자 결정). 발행 경로
+(producer, 관리 API 단건 발행)가 **이 모듈 하나로** 파티션을 정해 명시 파티션으로 싣는다.
+그래서 같은 키는 어느 경로로 보내도 같은 파티션으로 간다.
+
+- 해시는 Kafka ``org.apache.kafka.common.utils.Utils.murmur2`` 와 비트 단위로 같다
+  (seed ``0x9747b28c``). 골든 벡터 ``tests/data/murmur2_golden.txt`` 는 Kafka 3.9 jar 에서 뽑았다.
+- 키는 **UTF-8 바이트**로 해시한다. 자바 클라이언트도 같은 바이트를 쓴다.
+- 파티션 = ``to_positive(murmur2(UTF-8 키)) % 파티션 수``.
+
+**응용이 직접 부를 일은 없다** - 라이브러리 내부에서 쓴다.
+"""
+
+from __future__ import annotations
+
+_M = 0x5BD1E995
+_SEED = 0x9747B28C
+_MASK = 0xFFFFFFFF
+
+
+def murmur2(data: bytes) -> int:
+    """Kafka ``Utils.murmur2`` 와 같은 32비트 해시(부호 있는 정수)를 돌려준다.
+
+    Args:
+        data (bytes): 해시할 바이트.
+
+    Returns:
+        int: -2^31 ~ 2^31-1 범위의 해시(자바 int 와 같은 값).
+    """
+    length = len(data)
+    h = (_SEED ^ length) & _MASK
+    n4 = length // 4
+    for i in range(n4):
+        i4 = i * 4
+        k = data[i4] | (data[i4 + 1] << 8) | (data[i4 + 2] << 16) | (data[i4 + 3] << 24)
+        k = (k * _M) & _MASK
+        k ^= k >> 24
+        k = (k * _M) & _MASK
+        h = (h * _M) & _MASK
+        h ^= k
+    rem = length % 4
+    base = length & ~3
+    if rem >= 3:
+        h ^= data[base + 2] << 16
+    if rem >= 2:
+        h ^= data[base + 1] << 8
+    if rem >= 1:
+        h ^= data[base]
+        h = (h * _M) & _MASK
+    h ^= h >> 13
+    h = (h * _M) & _MASK
+    h ^= h >> 15
+    return h - (1 << 32) if h & 0x80000000 else h
+
+
+def to_positive(value: int) -> int:
+    """Kafka ``Utils.toPositive`` - 부호 비트를 떼어 0 이상으로 만든다."""
+    return value & 0x7FFFFFFF
+
+
+def partition_for_key(key: str | bytes, num_partitions: int) -> int:
+    """키가 있는 레코드의 파티션 번호.
+
+    Args:
+        key (str | bytes): 레코드 키. 문자열이면 UTF-8 로 바꿔 해시한다.
+        num_partitions (int): 토픽의 파티션 수(1 이상).
+
+    Returns:
+        int: 0 ~ num_partitions-1.
+
+    Raises:
+        ValueError: 파티션 수가 1 미만일 때.
+    """
+    if num_partitions < 1:
+        raise ValueError("num_partitions must be >= 1: %r" % (num_partitions,))
+    raw = key.encode("utf-8") if isinstance(key, str) else bytes(key)
+    return to_positive(murmur2(raw)) % num_partitions

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/ilink/producer.py

@@ -11,14 +11,17 @@
 
 from __future__ import annotations
 
+import random
+import re
 import threading
 import time
 import uuid
 
 from .common import ILC
 from .connectivity import TCPConnector
-from .exception import ILException, ILOperationException
+from .exception import ILException, ILOperationException, ILSessionException
 from .msg import ILMsg, ILMsgUtil, ILTopicFrameMsg, encode_property
+from .partitioner import partition_for_key
 
 
 def _corr_id() -> str:
@@ -256,7 +259,8 @@ class ILProducerConfig:
         self._maxBlockMs = max(0, n); return self
 
     def maxRequestSize(self, n: int) -> "ILProducerConfig":
-        """레코드 1건의 **프레임** 크기 상한(바이트). (기본 1048576 = 1MB)
+        """레코드 1건의 **프레임** 크기 상한이자 **봉투 하나의 크기 상한**(바이트).
+        (기본 1048576 = 1MB, Kafka ``max.request.size`` 와 같은 뜻)
 
         Args:
             n (int): 프레임 크기 상한(**바이트**). **1024 미만은 1024 로 보정된다.**
@@ -271,6 +275,9 @@ class ILProducerConfig:
             이 값 이하여도 토픽의 세그먼트 크기(SEGMENTBYTES)보다 큰 레코드는 서버가
             받지 않는다(``acks=1`` 이면 그 레코드만 ``MIMQE_TOPIC_MESSAGE_TOO_LARGE`` 로
             실패한다).
+
+            v0.6.9 부터 **봉투 하나(레코드 프레임의 합)도 이 값을 넘지 않게** 나눠 보낸다.
+            기본값이면 봉투가 약 4만 건을 넘지 않아 엔진의 봉투 건수 상한(10만 건)에 닿지 않는다.
         """
         self._maxRequestSize = max(1024, n); return self
 
@@ -428,10 +435,10 @@ class ILProducerConfig:
         return self._maxBlockMs
 
     def get_max_request_size(self) -> int:
-        """레코드 1건 프레임 상한(바이트). 기본 1048576.
+        """레코드 1건 프레임 상한이자 봉투 크기 상한(바이트). 기본 1048576.
 
         Returns:
-            int: 레코드 1건 프레임 상한(바이트). 기본 1048576.
+            int: 레코드 1건 프레임 상한이자 봉투 크기 상한(바이트). 기본 1048576.
         """
         return self._maxRequestSize
 
@@ -478,11 +485,14 @@ class ILProducerRecord:
             topic (str): 발행 대상 토픽 이름. **필수.** 와일드카드는 쓸 수 없다
                 (패턴은 구독 전용이다).
             key (str): 파티셔닝 키. 기본 ``""``. 같은 키는 항상 같은 파티션으로
-                가므로 **키 단위 순서가 보장된다.** 비우면 서버가 분산 배치한다.
+                가므로 **키 단위 순서가 보장된다.** 파티션은 producer 가 Kafka 와 같은
+                murmur2 로 **UTF-8 키 바이트**를 해시해 정한다. 비우면 producer 가 한
+                파티션에 ``batchSize`` 바이트씩 붙였다가 다음 파티션으로 넘긴다(균일 스티키).
             value (bytes): payload. 기본 ``b""``. ``bytes``/``bytearray`` 가 아니면
                 ``str()`` 후 UTF-8 로 인코딩한다.
             partition (int): 파티션 번호를 직접 지정한다. 기본 ``-1`` = 미지정
-                (서버가 키 해시로 정함). 토픽의 파티션 수 범위를 벗어나면 서버가 거절한다.
+                (producer 가 키로 정한다). 토픽의 파티션 수 범위를 벗어나면 ``get()`` 이
+                ``MIMQE_INVALID_ARGUMENT`` 로 실패한다.
             properties (dict | None): 레코드에 딸려 가는 문자열 키/값 메타데이터.
                 기본 None. 구독측에서 ``ILTopicMsg.get_property(key)`` 로 읽는다.
                 순서를 유지하려면 ``dict`` 삽입 순서를 그대로 쓴다.
@@ -497,7 +507,7 @@ class ILProducerRecord:
         """파티션을 직접 지정한다.
 
         Args:
-            n (int): 파티션 번호. ``-1`` 이면 미지정(서버가 키 해시로 정함).
+            n (int): 파티션 번호. ``-1`` 이면 미지정(producer 가 키로 정한다).
 
         Returns:
             ILProducerRecord: 체이닝을 위해 자기 자신.
@@ -774,6 +784,27 @@ def _extract_leader_hint(exc: Exception) -> str | None:
     return hint
 
 
+#: INIT_PRODUCER_ID 로 맞추는 멱등 프로토콜 판. "2" = seq 는 (토픽, 파티션) 범위이고 모든 발행이
+#: 명시 파티션을 싣는다(엔진 IDEMP, 이력 246).
+_IDEM_PROTOCOL = "2"
+#: 순서 오류 사유 ``MIMQE_OUT_OF_ORDER_SEQUENCE (expected n, got m)`` 에서 n 을 뽑는다.
+_OOO_EXPECTED = re.compile(r"expected (\d+), got (\d+)")
+
+
+class _Pending:
+    """누적 버퍼의 레코드 1건. ``seq`` 는 봉투를 만들 때 매긴다(-1 = 아직 없음)."""
+
+    __slots__ = ("frame", "future", "record", "partition", "seq")
+
+    def __init__(self, frame: bytes, future: ILPublishFuture,
+                 record: ILProducerRecord, partition: int) -> None:
+        self.frame = frame
+        self.future = future
+        self.record = record
+        self.partition = partition
+        self.seq = -1
+
+
 class ILTopicProducer:
     """토픽 발행자. ``ILQmgr.create_producer()`` 로 얻는다.
 
@@ -814,9 +845,15 @@ class ILTopicProducer:
         self._closed = False
         self._connected = False
         self._pid = -1
-        #: 멱등 seq - **토픽별**로 0 부터 센다(자바 seqByTopic 과 같다). 엔진은 (pid, 토픽)마다
-        #: seq 가 이어지는지 본다.
-        self._seq_by_topic: dict[str, int] = {}
+        #: 멱등 seq - **(토픽, 파티션)별**로 0 부터 센다. 엔진 appender 가 파티션마다 연속을 본다(IDEMP).
+        #: 봉투를 만들 때 매기고, 적재 안 됨이 확정된 건(건별 NACK)의 번호는 돌려받아 다시 매긴다.
+        self._seq_next: dict[tuple[str, int], int] = {}
+        #: (토픽, 파티션)에서 받아들여진(적재 또는 중복 응답) 가장 큰 seq. 재번호의 하한이다.
+        self._seq_acked: dict[tuple[str, int], int] = {}
+        #: 토픽별 파티션 수(TOPIC_METADATA). 파티션 수는 토픽을 다시 만들 때만 바뀐다.
+        self._partitions: dict[str, int] = {}
+        #: 키 없는 레코드의 균일 스티키 - 토픽별 [지금 파티션, 그 파티션에 붙인 바이트].
+        self._sticky: dict[str, list[int]] = {}
 
         self._candidates: list[str] = []
         for s in str(host).split(","):
@@ -835,7 +872,7 @@ class ILTopicProducer:
         self._connect_any()
 
         # accumulator - linger/batchSize 로 모았다가 봉투로 내보낸다.
-        self._pending: list[tuple[bytes, ILPublishFuture, ILProducerRecord]] = []
+        self._pending: list[_Pending] = []
         self._pending_bytes = 0
 
     # ── 접속 / 페일오버 ──────────────────────────────────────────────────
@@ -876,9 +913,18 @@ class ILTopicProducer:
         if self.config.is_idempotence_enabled() and self._pid < 0:
             # 멱등 발행: PID 는 최초 1회만 발급하고 재접속에도 재사용한다
             # (엔진이 레코드 헤더의 Pid/Seq 로 dedup 상태를 복구한다).
-            res = self._request(ILC.MIMQ_INIT_PRODUCER_ID)
-            if res is not None and res.getArg1():
-                self._pid = int(res.getArg1())
+            # arg1 = 이 클라의 멱등 프로토콜 판. 엔진은 응답 arg2 로 자기 판을 준다. "2" 가 아니면
+            # seq 범위(토픽 / 파티션)가 달라, 파티션 seq 가 dup-ACK 로 조용히 버려질 수 있다.
+            # 그래서 폴백 없이 생성을 실패시킨다.
+            res = self._request(ILC.MIMQ_INIT_PRODUCER_ID, _IDEM_PROTOCOL)
+            if res is None or res.getCode() != ILC.MIMQ_SUCCESSFUL_TOPIC_OPERATION:
+                raise ILOperationException(
+                    (res.getArg2() if res is not None else "")
+                    or "MIMQE_INVALID_MSG_FORMAT (init producer id)")
+            if (res.getArg2() or "").strip() != _IDEM_PROTOCOL:
+                raise ILOperationException(
+                    "MIMQE_NOT_SUPPORTED (partition-scoped idempotence requires newer engine)")
+            self._pid = int(res.getArg1())
         self._fetch_cluster_info()
         self.host = host
         self.port = port
@@ -921,18 +967,101 @@ class ILTopicProducer:
             return res.getReportMsg()
         return None
 
+    # ── 메타데이터 / 파티션 결정 ────────────────────────────────────────────
+    def _partition_count(self, topic: str, refresh: bool = False) -> int:
+        """토픽의 파티션 수. 처음 한 번 TOPIC_METADATA 로 묻고 캐시한다.
+
+        flush 창의 ``MIMQE_TOPIC_FLUSHED`` 는 ``retryBackoffMs`` 간격으로 ``maxBlockMs`` 까지
+        다시 묻는다(flush 는 파티션 수를 바꾸지 않는다). 연결 실패는 발행과 같은 방식으로
+        재접속한다(``retries`` 횟수, ``maxBlockMs`` 시한).
+
+        Raises:
+            ILOperationException: 토픽이 없거나 서버가 거절했을 때.
+        """
+        if not refresh:
+            n = self._partitions.get(topic)
+            if n is not None:
+                return n
+        deadline = time.time() + self.config.get_max_block_ms() / 1000.0
+        backoff = max(self.config.get_retry_backoff_ms() / 1000.0, 0.01)
+        attempt = 0
+        while True:
+            try:
+                rep = self._request(ILC.MIMQ_TOPIC_METADATA, topic)
+            except ILOperationException:
+                raise
+            except Exception:
+                self._connected = False
+                remain = deadline - time.time()
+                if attempt >= self.config.get_retries() or self._closed or remain <= 0:
+                    raise
+                attempt += 1
+                time.sleep(min(backoff, remain))
+                try:
+                    self._connect_any()
+                except Exception:
+                    pass                    # 다음 회차에서 다시 시도(시한이 막는다)
+                continue
+            if rep is None:
+                raise ILOperationException("MIMQE_INVALID_MSG_FORMAT (topic metadata : not a report)")
+            if rep.getCode() == ILC.MIMQ_SUCCESSFUL_TOPIC_OPERATION:
+                n = int(rep.getArg1() or "0")
+                if n < 1:
+                    raise ILOperationException(
+                        "MIMQE_INVALID_MSG_FORMAT (topic metadata : %d partitions)" % n)
+                self._partitions[topic] = n
+                return n
+            reason = rep.getArg2() or "topic metadata failed (code=%d)" % rep.getCode()
+            if "MIMQE_TOPIC_FLUSHED" in reason and time.time() + backoff < deadline:
+                time.sleep(backoff)
+                continue
+            raise ILOperationException(reason)
+
+    def _choose_partition(self, record: ILProducerRecord) -> int:
+        """파티션을 정한다: 명시 파티션 > 키 해시(murmur2, UTF-8) > 키 없음 균일 스티키.
+
+        엔진은 파티션을 고르지 않는다(IDEMP) - 명시 파티션이 없는 레코드는 거절한다.
+        관리 API 단건 발행도 같은 :func:`~ilink.partitioner.partition_for_key` 를 쓴다.
+        """
+        cached = record.topic in self._partitions
+        n = self._partition_count(record.topic)
+        if record.partition >= 0:
+            if record.partition >= n and cached:
+                n = self._partition_count(record.topic, refresh=True)   # 다시 만들어져 늘었을 수 있다
+            if record.partition >= n:
+                raise ILOperationException(
+                    "MIMQE_INVALID_ARGUMENT (Partition : %d, Available : 0~%d)"
+                    % (record.partition, n - 1))
+            return record.partition
+        if record.key:
+            return partition_for_key(record.key, n)
+        st = self._sticky.get(record.topic)
+        if st is None or st[0] >= n:
+            st = [random.randrange(n), 0]
+            self._sticky[record.topic] = st
+        return st[0]
+
+    def _sticky_advance(self, topic: str, nbytes: int) -> None:
+        """키 없는 레코드를 붙인 만큼 센다. ``batchSize`` 를 채우면 다음 파티션으로 넘긴다(Kafka 3.3+)."""
+        st = self._sticky[topic]
+        st[1] += nbytes
+        if st[1] >= self.config.get_batch_size():
+            st[0] = (st[0] + 1) % self._partitions.get(topic, 1)
+            st[1] = 0
+
     # ── 프레임 조립 ──────────────────────────────────────────────────────
-    def _serialize(self, record: ILProducerRecord, corr_id: str, seq: int) -> bytes:
-        """PUBLISH(2020) 프레임 1개. 조립/직렬화는 :class:`ILTopicFrameMsg` 가 한다."""
+    def _serialize(self, record: ILProducerRecord, partition: int, corr_id: str) -> bytes:
+        """PUBLISH(2020) 프레임 1개. 조립/직렬화는 :class:`ILTopicFrameMsg` 가 한다.
+
+        pid/seq 칸은 비워 둔다 - 멱등이면 봉투를 만들 때 :meth:`ILTopicFrameMsg.patchPidSeq` 로 채운다.
+        """
         frame = ILTopicFrameMsg.createPublish(
             record.topic, record.key, corr_id,
             encode_property(record.properties), record.value,
         )
         if self.config.get_acks() == 0:
             frame.setAckMode("0")
-        frame.setPartition(record.partition)
-        if self._pid >= 0:
-            frame.setPidSeq(self._pid, seq)
+        frame.setPartition(partition)
         return frame.to_byte_array()
 
     @staticmethod
@@ -957,6 +1086,8 @@ class ILTopicProducer:
         Raises:
             ILOperationException: producer 가 이미 닫혔거나, 직렬화된 프레임이
                 ``maxRequestSize`` 를 넘거나, 레코드 하나가 ``bufferMemory`` 보다 클 때.
+                토픽의 파티션 수를 알 수 없거나(없는 토픽, 조회 실패) 명시 파티션이 범위
+                밖일 때도 - ``acks=0`` 이어도 조용히 버리지 않는다.
             ILException: 연결 실패가 ``retries`` / ``deliveryTimeoutMs`` 안에
                 복구되지 않았을 때.
 
@@ -974,14 +1105,13 @@ class ILTopicProducer:
             raise ILOperationException("MIMQE_NOT_SUPPORTED (producer is closed)")
         future = ILPublishFuture(self.config.get_delivery_timeout_ms())
         with self._lock:
-            # v0.6.8 멱등 seq 는 (pid, 토픽)마다 0 부터 이어져야 한다 - 엔진 CheckProducerSeq 가
-            #   토픽마다 LastSeq + 1 을 요구한다. 전에는 producer 전체에 카운터가 하나라, 한
-            #   producer 로 토픽을 섞어 쓰면 두 번째 토픽부터 OUT_OF_ORDER 가 났다(2026-09-11 실측,
-            #   봉투당 1건에서도). 재전송은 레코드가 받은 seq 를 그대로 쓴다(프레임째 다시 보낸다).
-            seq = self._seq_by_topic.get(record.topic, 0)
-            if self._pid >= 0:
-                self._seq_by_topic[record.topic] = seq + 1
-            frame = self._serialize(record, _corr_id(), seq)
+            # IDEMP: 파티션은 producer 가 정한다(엔진은 명시 파티션이 없는 레코드를 거절한다).
+            #   토픽의 파티션 수는 처음 한 번 묻는다. 파티션을 정하지 못하면(없는 토픽, 조회 실패,
+            #   명시 파티션이 범위 밖) **예외를 던진다.** 실패한 future 로 돌려주면 acks=0 처럼 future 를
+            #   보지 않는 호출자에게는 조용한 유실이 된다(엔진 설계 v0.4.1 4.7).
+            #   멱등 seq 는 여기서가 아니라 봉투를 만들 때 매긴다(_send_batch_locked).
+            partition = self._choose_partition(record)
+            frame = self._serialize(record, partition, _corr_id())
 
             if len(frame) > self.config.get_max_request_size():
                 raise ILOperationException(
@@ -1000,8 +1130,10 @@ class ILTopicProducer:
                         % (self._pending_bytes + len(frame), self.config.get_buffer_memory())
                     )
 
-            self._pending.append((frame, future, record))
+            self._pending.append(_Pending(frame, future, record, partition))
             self._pending_bytes += len(frame)
+            if record.partition < 0 and not record.key:
+                self._sticky_advance(record.topic, len(frame))
             # linger 0 이면 즉시, 아니면 배치 한도에 닿을 때 내보낸다.
             if self.config.get_linger_ms() <= 0 or self._pending_bytes >= self.config.get_batch_size():
                 self._flush_locked()
@@ -1044,7 +1176,17 @@ class ILTopicProducer:
                 self._conn.send_bytes(payload)
                 if not expect_ack:
                     return None
-                return self._conn.recv(self.config.get_request_timeout_ms())
+                res = self._conn.recv(self.config.get_request_timeout_ms())
+                if res.getType() == ILC.MIMQ_REPORT_MESSAGE:
+                    reason = res.getReportMsg().getArg2() or ""
+                    if "MIMQE_FOLLOWER_NODE" in reason:
+                        # 팔로워에 붙어 있다. 봉투 거절은 헤더 단계라 한 건도 적재되지 않았다(엔진 보장,
+                        # 이력 248) - 리더 힌트를 앞세워 다시 붙고 같은 봉투를 다시 보낸다(연결 실패와 같은 예산).
+                        hint = _extract_leader_hint(ILOperationException(reason))
+                        if hint:
+                            self._promote(hint)
+                        raise ILSessionException(0, reason)
+                return res
             except ILOperationException:
                 raise                       # 서버 거절 - 재시도 대상이 아니다
             except Exception:
@@ -1075,36 +1217,63 @@ class ILTopicProducer:
         #   장애를 숨기지 않는다. 멱등 producer 는 재시도하지 않는다(_send_batch_locked 참고).
         deadline = time.time() + self.config.get_delivery_timeout_ms() / 1000.0
         attempt = 0
-        while True:
-            retry = self._send_batch_locked(batch)
+        cap = self.config.get_max_request_size()
+        queue = batch
+        while queue:
+            # v0.6.9: 봉투 하나의 레코드 프레임 합이 maxRequestSize 를 넘지 않게 나눠 보낸다 - Kafka
+            #   max.request.size 와 같은 뜻. 기본값(1MB)에서는 봉투가 약 4만 건(최소 프레임 26바이트)을
+            #   넘지 못해 엔진의 봉투 건수 상한(10만)에 닿지 않는다.
+            n, size = 0, 0
+            while n < len(queue) and (n == 0 or size + len(queue[n].frame) <= cap):
+                size += len(queue[n].frame)
+                n += 1
+            chunk, queue = queue[:n], queue[n:]
+            try:
+                retry = self._send_batch_locked(chunk)
+            except Exception as exc:
+                err = exc if isinstance(exc, ILOperationException) else ILException(exc)
+                for p in queue:             # 아직 안 보낸 봉투의 레코드도 같은 사유로 끝낸다
+                    p.future._fail(err)
+                raise
             if not retry:
-                return
+                continue
             attempt += 1
             backoff = self.config.get_retry_backoff_ms() / 1000.0
             if attempt > self.config.get_retries() or time.time() + backoff > deadline:
-                for (_, fut, _), err in retry:
-                    fut._fail(err)
-                return
+                for p, err in retry:
+                    p.future._fail(err)
+                continue
             time.sleep(backoff)
-            batch = [item for item, _ in retry]
+            # 되돌린 건은 원래 순서대로 남은 레코드 앞에 둔다 - 파티션 안 순서를 지킨다
+            queue = [p for p, _ in retry] + queue
 
     def _send_batch_locked(self, batch: list) -> list:
         """봉투 하나를 보내고 결과로 각 레코드를 완결한다.
 
         Args:
-            batch (list): ``(프레임, future, 레코드)`` 목록.
+            batch (list): :class:`_Pending` 목록(보낼 순서).
 
         Returns:
-            list: ``MIMQE_TOPIC_FLUSHED`` 로 실패해 **다시 보낼** ``((프레임, future, 레코드), 예외)``
-            목록. 나머지 레코드는 여기서 완결된다.
+            list: **다시 보낼** ``(_Pending, 예외)`` 목록. 비멱등의 ``MIMQE_TOPIC_FLUSHED`` 와
+            멱등의 순서 오류(재번호해 다시 보낸다)다. 나머지 레코드는 여기서 완결된다.
         """
         retry = []
         corr = _corr_id()
-        total = sum(len(f) for f, _, _ in batch)
+        total = sum(len(p.frame) for p in batch)
         ack_mode = "0" if self.config.get_acks() == 0 else "1"
         payload = bytearray(self._build_envelope(corr, ack_mode, len(batch), total))
-        for frame, _, _ in batch:
-            payload += frame
+        idem = self._pid >= 0
+        for p in batch:
+            start = len(payload)
+            payload += p.frame
+            if idem:
+                # IDEMP: seq 는 봉투를 만들 때 (토픽, 파티션)마다 매긴다. 연결이 끊겨 결과를 모르는
+                #   재전송은 _send_with_retry 가 같은 payload 를 그대로 보내므로 같은 seq 가 된다.
+                if p.seq < 0:
+                    tp = (p.record.topic, p.partition)
+                    p.seq = self._seq_next.get(tp, 0)
+                    self._seq_next[tp] = p.seq + 1
+                ILTopicFrameMsg.patchPidSeq(payload, start, self._pid, p.seq)
         payload = bytes(payload)
 
         try:
@@ -1112,44 +1281,78 @@ class ILTopicProducer:
 
             if res is None:
                 # acks=0 은 무응답이다. 좌표를 알 수 없으므로 -1 로 완결시킨다.
-                for _, fut, rec in batch:
-                    fut._complete(ILRecordMetadata(rec.topic, rec.partition, -1, 0))
+                for p in batch:
+                    p.future._complete(ILRecordMetadata(p.record.topic, p.partition, -1, 0))
                 return retry
 
             if res.getType() == ILC.MIMQ_REPORT_MESSAGE:
+                # 봉투 전체 거절 - 건별 결과가 없다. 적재 여부를 모르는 것으로 보고 seq 는 쓴 채로 둔다.
+                #   적재되지 않았다면 다음 봉투가 순서 오류(expected n)를 받아 거기서 다시 맞춘다.
                 err = ILOperationException(res.getReportMsg().getArg2())
-                for _, fut, _ in batch:
-                    fut._fail(err)
+                for p in batch:
+                    p.future._fail(err)
                 return retry
 
             frame = res.getTopicFrameMsg()
+            # 재번호 기준 - (토픽, 파티션) -> [가장 낮은 거절 seq, 순서 오류의 expected 또는 None]
+            rejected: dict[tuple[str, int], list] = {}
             # 배치 ACK 은 **건별 결과**를 돌려준다. 일부만 실패할 수 있다.
-            for i, item in enumerate(batch):
-                _, fut, rec = item
+            for i, p in enumerate(batch):
                 if i >= frame.batchCount:
-                    fut._fail(ILOperationException("MIMQE_INVALID_MSG_FORMAT (ack count mismatch)"))
+                    # 결과 모름 - seq 는 쓴 것으로 둔다(재번호하지 않는다).
+                    p.future._fail(ILOperationException("MIMQE_INVALID_MSG_FORMAT (ack count mismatch)"))
                     continue
                 code = frame.resultCodes[i]
+                tp = (p.record.topic, p.partition)
                 if code == ILC.MIMQ_SUCCESSFUL_TOPIC_PUBLISH:
-                    fut._complete(ILRecordMetadata(
-                        rec.topic, frame.resultPartitions[i],
+                    # 중복 응답(dup-ACK)도 성공 코드로 온다. 엔진 Recent 캐시 밖이면 offset 이 -1 이다.
+                    if idem and p.seq > self._seq_acked.get(tp, -1):
+                        self._seq_acked[tp] = p.seq
+                    p.future._complete(ILRecordMetadata(
+                        p.record.topic, frame.resultPartitions[i],
                         frame.resultOffsets[i], frame.resultTimestamps[i]))
                     continue
                 reason = frame.resultReasons[i] or "publish failed"
                 err = ILOperationException("%s (code=%d)" % (reason, code))
-                # TFLUSH-3: FLUSHED 건은 호출자에게 알리지 않고 다시 보낸다. 단 멱등이면 안 된다 -
-                #   flush 로 새로 만든 토픽은 처음 받은 seq 를 기준선으로 삼고 그 이하는 적재 없이
-                #   성공(dup-ACK)으로 답한다(엔진 TopicStorage::CheckProducerSeq). 뒤 레코드가 먼저
-                #   들어간 뒤 되돌린 건을 보내면 성공 응답에 레코드는 없는 조용한 유실이 된다.
-                if "MIMQE_TOPIC_FLUSHED" in reason and not self.config.is_idempotence_enabled():
-                    retry.append((item, err))
+                if "MIMQE_OBJECT_NOT_FOUND" in reason or "MIMQE_INVALID_ARGUMENT (Partition" in reason:
+                    self._partitions.pop(p.record.topic, None)   # 다시 만들어졌을 수 있다 - 다음 send 가 다시 묻는다
+                ooo = None
+                if idem:
+                    # 건별 NACK = 적재 안 됨(엔진 계약 4.3.1). 이 seq 는 쓰이지 않았으니 돌려받는다.
+                    if code == ILC.MIMQ_OUT_OF_ORDER_SEQUENCE or "OUT_OF_ORDER" in reason:
+                        m = _OOO_EXPECTED.search(reason)
+                        ooo = int(m.group(1)) if m else -1
+                    r = rejected.setdefault(tp, [p.seq, None])
+                    r[0] = min(r[0], p.seq)
+                    if ooo is not None and ooo >= 0:
+                        r[1] = ooo
+                    p.seq = -1
+                # 다시 보내는 것 두 가지.
+                #   ① 비멱등 FLUSHED(TFLUSH-3) - 호출자에게 알리지 않고 그 레코드만 다시 보낸다. 멱등은
+                #      올린다: flush 로 새로 만든 파티션은 처음 받은 seq 를 기준선으로 삼아, 되돌린 건이
+                #      뒤 레코드보다 늦게 들어가면 순서가 바뀐다(엔진 설계 4.8, 계약 유지).
+                #   ② 멱등 순서 오류 - 그 레코드는 적재되지 않았고, 엔진이 기다리는 번호(expected)를
+                #      알려 준다. 그 번호부터 다시 매겨 보낸다. 앞 레코드가 거절돼 생긴 구멍과, 결과를
+                #      모른 채 실패한 봉투가 실제로는 적재되지 않아 생긴 구멍을 둘 다 메운다.
+                if (("MIMQE_TOPIC_FLUSHED" in reason and not idem)
+                        or (ooo is not None and ooo >= 0)):
+                    retry.append((p, err))
                 else:
-                    fut._fail(err)
+                    p.future._fail(err)
+            # 재번호(엔진 설계 5.5). 다음 seq = max(기준, 받아들여진 가장 큰 seq + 1).
+            #   기준은 순서 오류가 있으면 그 expected(엔진의 last + 1), 없으면 가장 낮은 거절 seq 다.
+            #   받아들여진 seq 이하는 절대 다시 쓰지 않는다 - 상태 없는 파티션은 처음 본 seq 를
+            #   기준선으로 받으므로, 앞 건이 거절되고 뒤 건이 기준선이 된 뒤 번호를 되돌리면 그 번호는
+            #   중복 응답(적재 없음)으로 조용히 사라진다. 봉투는 한 번에 하나만 나가므로(동기) 이
+            #   파티션의 앞선 결과는 여기서 모두 알고 있다(재번호 규칙 i).
+            for tp, (low, expected) in rejected.items():
+                base = expected if expected is not None else low
+                self._seq_next[tp] = max(base, self._seq_acked.get(tp, -1) + 1)
             return retry
         except Exception as exc:
             err = exc if isinstance(exc, ILOperationException) else ILException(exc)
-            for _, fut, _ in batch:
-                fut._fail(err)
+            for p in batch:
+                p.future._fail(err)
             raise
 
     def close(self, timeout_ms: int = 5000) -> None:

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/jetstream_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.6.8
+Version: 0.6.9
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -54,6 +54,18 @@ Python으로 작성된 ILink 클라이언트 API입니다.
 ## 설치 방법
 pip install jetstream-api
 
+## 0.6.9 변경 - 파티션을 클라이언트가 정한다 (엔진 7.0.1.3401 이상 필요)
+
+엔진이 더는 파티션을 고르지 않습니다. 이 판부터 producer 와 관리 API 단건 발행이 파티션을 정해 보냅니다(Kafka 와 같은 방식).
+
+- **키가 있으면** Kafka 와 같은 murmur2 로 **UTF-8 키 바이트**를 해시해 정합니다. 같은 키는 파이썬·자바 어느 클라이언트든 같은 파티션으로 갑니다.
+- **키가 없으면** producer 는 한 파티션에 `batchSize` 바이트씩 붙였다가 다음 파티션으로 넘깁니다(Kafka 3.3+ 균일 스티키). 관리 API 단건 발행은 토픽별 라운드로빈입니다.
+- 토픽의 파티션 수는 처음 보낼 때 한 번 묻습니다. **알 수 없으면(없는 토픽 등) `send()` 가 예외를 던집니다.** `acks=0` 도 같습니다.
+- 멱등 발행(`enableIdempotence(True)`)은 (토픽, 파티션)마다 번호를 매깁니다. 한 레코드가 거절돼도(너무 큼 등) 뒤 레코드는 계속 적재되고, 여러 건을 한 봉투에 묶어 보냅니다.
+- `maxRequestSize`(기본 1MB)는 레코드 한 건과 **봉투 하나의 크기**를 함께 묶습니다.
+
+★ 그 이전 엔진에서는 발행이 모두 실패합니다(파티션 수를 물을 수 없다). 그런 엔진에는 0.6.8 을 쓰십시오.
+
 ## 0.2.0 신규 - pub/sub 토픽
 
 큐에 더해 **pub/sub 토픽**을 지원합니다. 발행된 메시지는 retention 정책이 지울 때까지 보존되어

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/jetstream_api.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ ilink/common.py
 ilink/connectivity.py
 ilink/exception.py
 ilink/msg.py
+ilink/partitioner.py
 ilink/pattern.py
 ilink/producer.py
 ilink/properties.py

{jetstream_api-0.6.8 → jetstream_api-0.6.9}/pyproject.toml

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