jetstream-api 0.17.0__tar.gz → 0.18.0__tar.gz

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.17.0
+Version: 0.18.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

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/ilink/__init__.py

@@ -1,104 +1,104 @@
-"""iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
-
-__version__ = "0.17.0"
-
-# --- Admin / Service ---
-from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser
-
-# --- Queue Manager & Queue ---
-from .qmgr import ILQmgr, ILQueue
-
-# --- Message ---
-from .msg import ILMsg, ILMsgUtil
-
-# --- Constants & Enums ---
-from .common import ILC, ILCC, ILRC, MatchOption
-
-# --- Properties ---
-from .properties import (
-    DestItem,
-    PartitionItem,
-    SegmentItem,
-    ILQueueProperty,
-    ILChannelProperty,
-    ILChannelType,
-    ILChannelStatus,
-    ILChannelDirection,
-    ILChannelSecurity,
-    ILChannelBalanceMode,
-    ILClusterNode,
-    ILClusterControlResult,
-    ILClusterProperty,
-    ILQmgrProperty,
-    ILSessionProperty,
-    ILServiceProperty,
-    ILSpokeProperty,
-    ILAccessRuleProperty,
-    ILSecureFileProperty,
-    ILQueueRealTimeInfo,
-    ILQueueFlow,
-    ILQmgrDiag,
-    ILClusterDefDiag,
-    ILClusterPeerDef,
-)
-
-# --- Exceptions ---
-from .exception import (
-    ILException,
-    ILNoMsgException,
-    ILTimeoutException,
-    ILOperationException,
-    ILSessionException,
-    ILMsgTypeException,
-)
-
-__all__ = [
-    # Admin
-    "ILAdminService",
-    "ILAdminQmgr",
-    "ILLogBrowser",
-    "ILQueueBrowser",
-    # QMgr / Queue
-    "ILQmgr",
-    "ILQueue",
-    # Message
-    "ILMsg",
-    "ILMsgUtil",
-    # Constants
-    "ILC",
-    "ILCC",
-    "ILRC",
-    "MatchOption",
-    # Properties
-    "DestItem",
-    "PartitionItem",
-    "SegmentItem",
-    "ILQueueProperty",
-    "ILChannelProperty",
-    "ILChannelType",
-    "ILChannelStatus",
-    "ILChannelDirection",
-    "ILChannelSecurity",
-    "ILChannelBalanceMode",
-    "ILClusterNode",
-    "ILClusterControlResult",
-    "ILClusterProperty",
-    "ILQmgrProperty",
-    "ILSessionProperty",
-    "ILServiceProperty",
-    "ILSpokeProperty",
-    "ILAccessRuleProperty",
-    "ILSecureFileProperty",
-    "ILQueueRealTimeInfo",
-    "ILQueueFlow",
-    "ILQmgrDiag",
-    "ILClusterDefDiag",
-    "ILClusterPeerDef",
-    # Exceptions
-    "ILException",
-    "ILNoMsgException",
-    "ILTimeoutException",
-    "ILOperationException",
-    "ILSessionException",
-    "ILMsgTypeException",
-]
+"""iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
+
+__version__ = "0.18.0"
+
+# --- Admin / Service ---
+from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser
+
+# --- Queue Manager & Queue ---
+from .qmgr import ILQmgr, ILQueue
+
+# --- Message ---
+from .msg import ILMsg, ILMsgUtil
+
+# --- Constants & Enums ---
+from .common import ILC, ILCC, ILRC, MatchOption
+
+# --- Properties ---
+from .properties import (
+    DestItem,
+    PartitionItem,
+    SegmentItem,
+    ILQueueProperty,
+    ILChannelProperty,
+    ILChannelType,
+    ILChannelStatus,
+    ILChannelDirection,
+    ILChannelSecurity,
+    ILChannelBalanceMode,
+    ILClusterNode,
+    ILClusterControlResult,
+    ILClusterProperty,
+    ILQmgrProperty,
+    ILSessionProperty,
+    ILServiceProperty,
+    ILSpokeProperty,
+    ILAccessRuleProperty,
+    ILSecureFileProperty,
+    ILQueueRealTimeInfo,
+    ILQueueFlow,
+    ILQmgrDiag,
+    ILClusterDefDiag,
+    ILClusterPeerDef,
+)
+
+# --- Exceptions ---
+from .exception import (
+    ILException,
+    ILNoMsgException,
+    ILTimeoutException,
+    ILOperationException,
+    ILSessionException,
+    ILMsgTypeException,
+)
+
+__all__ = [
+    # Admin
+    "ILAdminService",
+    "ILAdminQmgr",
+    "ILLogBrowser",
+    "ILQueueBrowser",
+    # QMgr / Queue
+    "ILQmgr",
+    "ILQueue",
+    # Message
+    "ILMsg",
+    "ILMsgUtil",
+    # Constants
+    "ILC",
+    "ILCC",
+    "ILRC",
+    "MatchOption",
+    # Properties
+    "DestItem",
+    "PartitionItem",
+    "SegmentItem",
+    "ILQueueProperty",
+    "ILChannelProperty",
+    "ILChannelType",
+    "ILChannelStatus",
+    "ILChannelDirection",
+    "ILChannelSecurity",
+    "ILChannelBalanceMode",
+    "ILClusterNode",
+    "ILClusterControlResult",
+    "ILClusterProperty",
+    "ILQmgrProperty",
+    "ILSessionProperty",
+    "ILServiceProperty",
+    "ILSpokeProperty",
+    "ILAccessRuleProperty",
+    "ILSecureFileProperty",
+    "ILQueueRealTimeInfo",
+    "ILQueueFlow",
+    "ILQmgrDiag",
+    "ILClusterDefDiag",
+    "ILClusterPeerDef",
+    # Exceptions
+    "ILException",
+    "ILNoMsgException",
+    "ILTimeoutException",
+    "ILOperationException",
+    "ILSessionException",
+    "ILMsgTypeException",
+]

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/ilink/admin.py

@@ -119,7 +119,7 @@ class ILAdminService:
             args (list[str]): 명령행 인자. ``["--version"]`` 이면 버전을 찍는다.
         """
         if len(args) != 1:
-            print("available argrments.")
+            print("available arguments.")
             print("    --version : displays the library version.")
         ILC.print_version(args[0] if args else "")
 
@@ -170,9 +170,11 @@ class ILAdminService:
             self.service.connect(host, port)
             if not clientName:
                 clientName = caller_module_name()   # 0.11.0: inspect.stack()[-1] 과 같은 값(프레임 순회 - 소스 줄을 읽지 않는다)
-            conn_res_msg = self.service.request(
-                ILC.MIMQ_NEW_CONNECTION, "0", clientName, "USR"
-            )
+            # 0.18.0: 능력 선언을 **확장**에 싣는다. ☠ arg1 은 자동커밋 플래그 자리다.
+            _caps = ILC.client_caps_extension()
+            _cargs = ((ILC.MIMQ_NEW_CONNECTION,) + ((_caps,) if _caps else ())
+                      + ("0", clientName, "USR"))
+            conn_res_msg = self.service.request(*_cargs)
             if conn_res_msg is None:
                 raise ILOperationException("MIMQE_INTERNAL_ERROR")
             if conn_res_msg.getCode() != ILC.MIMQ_SUCCESSFUL_CONNECTION:
@@ -1035,6 +1037,7 @@ class ILAdminService:
             if not isinstance(cluster, ILClusterProperty):
                 raise ILOperationException(
                     "MIMQE_INVALID_ARGUMENT (createCluster takes an ILClusterProperty)")
+            cluster._validate_addresses()   # 왕복 전에 막는다 - 사유가 빠르다
             self.service.apply_for_report(
                 ILC.MIMQ_CREATE_CLUSTER,
                 cluster.get_serialized(),
@@ -1178,6 +1181,11 @@ class ILAdminService:
         Note:
             **노드 목록은 바꿀 수 없다** - 다르면 거절된다(조용히 무시되지 않는다).
 
+        Note:
+            ★ **컨트롤러는 서비스마다 하나다.** 컨트롤러를 셋 두려면 관리 서비스가
+            셋 있어야 한다 - 한 서비스에 몰면 나머지는 **닿지 않는 피어**가 되어
+            과반을 못 채우고 ☠ **거절이 아니라 끝나지 않는다.**
+
         Example::
 
             p = judge_svc.getClusterProperty("C1")
@@ -1186,6 +1194,7 @@ class ILAdminService:
         """
         try:
             self._checkClusterSupported()
+            cluster._validate_addresses()
             self.service.apply_for_report(
                 ILC.MIMQ_SET_CLUSTER_PROPERTY,
                 cluster.get_serialized(),
@@ -2865,7 +2874,7 @@ class ILAdminQmgr:
             args (list[str]): 명령행 인자. ``["--version"]`` 이면 버전을 찍는다.
         """
         if len(args) != 1:
-            print("available argrments.")
+            print("available arguments.")
             print("    --version : displays the library version.")
         ILC.print_version(args[0] if args else "")
 
@@ -5666,12 +5675,12 @@ class ILAdminQmgr:
                 전부다). 그래서 **클라이언트가 막는다** - 안 막으면 ``"JSON"``
                 이나 오타를 보낸 쪽이 **요청한 것과 다른 모양을 조용히 받는다.**
 
-        Raises:
-            ValueError: ``format`` 이 ``"TEXT"`` / ``"LINE"`` 이 아닐 때.
-
         Returns:
             리포트 문자열. 클러스터 미구성이면 본문에 ``STANDALONE (not clustered)``.
 
+        Raises:
+            ValueError: ``format`` 이 ``"TEXT"`` / ``"LINE"`` 이 아닐 때.
+
         Example::
 
             aq = svc.accessAdminQmgr("NODE_A")
@@ -6134,8 +6143,8 @@ class ILAdminQmgr:
 
         Args:
             topicName (str): 토픽 이름. 엔진 **rev 3393 이상**은 ``A-Z a-z 0-9 . _ -``
-                만 1~47바이트로 받고 ``.`` / ``..`` 는 거절한다(Kafka 토픽 이름 규칙과
-                같다). 그 이전 엔진은 47바이트 상한만 검사한다. 엔진은 **생성할 때만**
+                만 1~47바이트로 받고 ``.`` / ``..`` 는 거절한다.
+                그 이전 엔진은 47바이트 상한만 검사한다. 엔진은 **생성할 때만**
                 검사하므로 이미 있는 토픽은 이름과 상관없이 계속 쓸 수 있다.
             options (str): ``key=value`` 를 ``;`` 로 이은 문자열. 기본 ``""`` 는
                 엔진 기본값이다. 예 ``"partitions=3"``, ``"retentionms=86400000"``.

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/ilink/common.py

@@ -895,6 +895,17 @@ class ILC:
     MIMQ_CLIENT_NAME_ILSC = "ILSC"
     MIMQ_CLIENT_NAME_ILSVC = "ILSVC"
     MIMQ_CLIENT_NAME_ILWC = "ILWC"
+
+    #: 접속 확장에 싣는 **능력 선언**의 접두(0.18.0, 엔진 CAPDECL-2 짝).
+    #: ☠ ``arg1`` 에 실으면 안 된다 - 엔진이 그 자리를 **자동커밋 플래그**로 읽는다
+    #: (``atoi("0.18.0") == 0`` 이라 모든 세션이 조용히 트랜잭션 모드가 된다).
+    MIMQ_CLIENT_CAPS_PREFIX = "CAP="
+    #: 능력 선언의 최대 길이(접두 포함). 넘으면 **자르지 않고 통째로 버린다** -
+    #: 자르면 ``clsblob=2`` 가 ``clsblob=`` 가 되어 **읽히는데 뜻이 다른** 값이 된다.
+    MIMQ_CLIENT_CAPS_MAX = 63
+    #: 이 클라가 읽고 쓰는 클러스터 블롭 판. :data:`ilink.properties.CLUSTER_LAYOUT_MARK`
+    #: 와 능력 선언이 **모두 이 값에서 나온다** - 판 번호를 두 곳에 적지 않는다.
+    MIMQ_CLUSTER_BLOB_VERSION = 2
     MIMQ_SESSION_STATUS_DEAD = 0
     MIMQ_SESSION_STATUS_IDLE = 1
     MIMQ_SESSION_STATUS_RECEIVING = 2
@@ -1027,6 +1038,35 @@ class ILC:
                 return False
         return True
 
+    @staticmethod
+    def client_caps_extension():
+        """접속 메시지에 실을 **능력 선언** 확장을 만든다(0.18.0).
+
+        Returns:
+            bytes | None: ``b"CAP=clsblob=2,ver=0.18.0"`` 꼴. 길이가
+            :data:`MIMQ_CLIENT_CAPS_MAX` 를 넘으면 **None**(안 싣는다).
+
+        Note:
+            ★ 엔진은 이 값을 **기록만** 한다 - 아무것도 거부하지 않는다. 이득은
+            **다음 판 변경 때부터**다: 그때 엔진이 "못 읽는 클라" 에게 사유 있는
+            오류를 줄 수 있다. 지금 배포된 판(0.17.0 이하)은 구할 수 없다.
+
+            ☠ **admin / qmgr 유형에만 싣는다.** ``CHL`` / ``REL`` 은 확장을 자기
+            용도로 쓰고 옛 엔진이 그 크기로 분기한다.
+
+            판정은 ``clsblob`` 으로 한다. ``ver`` 은 사람이 로그에서 읽는 값이고
+            **판정에 쓰지 않는다** - 판 문자열로 능력을 유도하면 엔진이 표를 들고
+            있어야 하고 그 표는 반드시 낡는다.
+        """
+        import ilink                        # 판 문자열은 한 곳에만 있다
+        text = "%sclsblob=%d,ver=%s" % (ILC.MIMQ_CLIENT_CAPS_PREFIX,
+                                        ILC.MIMQ_CLUSTER_BLOB_VERSION,
+                                        getattr(ilink, "__version__", "?"))
+        raw = bytes(c for c in text.encode("utf-8", "replace") if 0x20 <= c <= 0x7E)
+        if len(raw) > ILC.MIMQ_CLIENT_CAPS_MAX:
+            return None                     # 자르지 않는다 - 뜻이 달라진다
+        return raw
+
     @staticmethod
     def get_api_version_info() -> str:
         """이 라이브러리의 버전 정보 문자열.

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/ilink/connectivity.py

@@ -42,7 +42,14 @@ def _ba_pick_int(ba: bytes, offset: int, length: int) -> int:
 
 
 def clamp_max_frame_length(n: int) -> int:
-    """프레임 길이 상한 설정값을 엔진 설정 범위(1,048,576 ~ 999,999,999)로 맞춘다."""
+    """프레임 길이 상한 설정값을 엔진 설정 범위(1,048,576 ~ 999,999,999)로 맞춘다.
+
+    Args:
+        n (int): 맞출 값(**바이트**).
+
+    Returns:
+        int: 범위 안으로 보정한 값(**바이트**).
+    """
     return min(max(ILC.MIMQ_MIN_MAX_FRAME_LENGTH, int(n)), ILC.MIMQ_MAX_FRAME_LENGTH)
 
 

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/ilink/partitioner.py

@@ -1,78 +1,85 @@
-"""토픽 파티셔너 - 키로 파티션 번호를 정한다(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
+"""토픽 파티셔너 - 키로 파티션 번호를 정한다(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 이상으로 만든다.
+
+    Args:
+        value (int): 부호 있는 32비트 값.
+
+    Returns:
+        int: 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.17.0 → jetstream_api-0.18.0}/ilink/producer.py

@@ -303,7 +303,7 @@ class ILProducerConfig:
 
     def maxRequestSize(self, n: int) -> "ILProducerConfig":
         """**봉투 하나의 본문 크기 상한**이자 레코드 크기 상한(바이트).
-        (기본 1048576 = 1MB, Kafka ``max.request.size`` 와 같은 뜻)
+        (기본 1048576 = 1MB)
 
         Args:
             n (int): 프레임 크기 상한(**바이트**). **1024 미만은 1024 로, 999,999,974 초과는
@@ -417,7 +417,7 @@ class ILProducerConfig:
         """lz4 압축 레벨을 정한다. (기본 ``9`` = 빠른 압축기)
 
         Args:
-            level (int): ``1`` ~ ``17``. Kafka ``compression.lz4.level`` 과 뜻이 같다 - ``9`` (기본)는 빠른 압축기이고,
+            level (int): ``1`` ~ ``17``. ``9`` (기본)는 빠른 압축기이고,
                 ``9`` 가 아닌 값은 그 레벨의 LZ4HC(훨씬 느리고 조금 더 준다)다. 레벨 12 이상은 결과가 같다.
 
         Returns:
@@ -689,8 +689,8 @@ class ILProducerConfig:
         # 0.7.0: 엔진은 (pid, 파티션)마다 최근 배치 5개로 중복을 가린다 - 그보다 많이 겹쳐 보내면 재전송이 중복으로 가려지지 않는다
         if self._idempotenceSet and self._enableIdempotence and self._maxInFlight > 5:
             raise ValueError(
-                "enableIdempotence requires maxInFlight <= 5 (the engine remembers the last 5 batches"
-                " per partition; Kafka has the same limit)"
+                "enableIdempotence requires maxInFlight <= 5"
+                " (the engine remembers the last 5 batches per partition)"
             )
         # 0.8.0: 직접 대입(cfg.compressionType = "gzip")은 빌더의 검사를 거치지 않는다 - 여기서 다시 본다
         self._compressionType = _codec.check_type(self._compressionType)
@@ -1492,7 +1492,9 @@ class ILTopicProducer:
         conn.max_frame_length = self.config.get_max_frame_length()
         conn.connect(host, port, self.config.get_request_timeout_ms())
         try:
-            rep = self._request(conn, ILC.MIMQ_NEW_CONNECTION, "1", self.clientName, "USR")
+            # 0.18.0: 능력 선언. ☠ arg1("1")은 자동커밋 플래그라 그대로 둔다.
+            rep = self._request(conn, ILC.MIMQ_NEW_CONNECTION, "1", self.clientName, "USR",
+                                ext=ILC.client_caps_extension())
             if rep is None or rep.getCode() != ILC.MIMQ_SUCCESSFUL_CONNECTION:
                 raise ILOperationException((rep.getArg2() if rep is not None else "")
                                            or "MIMQE_INVALID_MSG_FORMAT (connection)")
@@ -1534,9 +1536,10 @@ class ILTopicProducer:
         self._connected = True
         self._reconnect_attempts = 0
 
-    def _request(self, conn: TCPConnector, code: int, *args: str):
+    def _request(self, conn: TCPConnector, code: int, *args: str, ext: bytes = None):
         with _io_lock_of(conn):         # 0.7.3: 부트스트랩 전용 연결이지만 요청-응답 짝 규칙은 같게
-            conn.send(ILMsgUtil.create_request_msg(code, *args))
+            conn.send(ILMsgUtil.create_request_msg_with_ext(code, ext, *args)
+                      if ext is not None else ILMsgUtil.create_request_msg(code, *args))
             res = conn.recv(self.config.get_request_timeout_ms())
         if res.getType() == ILC.MIMQ_REPORT_MESSAGE:
             return res.getReportMsg()

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/ilink/properties.py

@@ -200,6 +200,17 @@ class _AutoAccessor:
             field = name[2].lower() + name[3:]
             if hasattr(self, field):
                 return lambda: bool(getattr(self, field))
+        # 0.18.0: 개명 안내를 **게터 호출에도** 붙인다. 전에는 대입 경로에만 있어서
+        # `p.getClusterType()` 이 맨 AttributeError 로 떨어졌다 - 정작 시험과 예제가
+        # 부딪히는 것은 게터 쪽이다.
+        for _pfx, _cut in (("get", 3), ("set", 3), ("is", 2)):
+            if name.startswith(_pfx) and len(name) > _cut:
+                moved = type(self)._RENAMED.get(name[_cut].lower() + name[_cut + 1:])
+                if moved is not None:
+                    raise AttributeError(
+                        f"{self.__class__.__name__} has no attribute {name}"
+                        f" - {moved[1]} 에서 {moved[0]} 로 바뀌었다"
+                    )
         raise AttributeError(f"{self.__class__.__name__} has no attribute {name}")
 
     _SPEC: dict = {}
@@ -3267,8 +3278,7 @@ class ILQmgrProperty(_AutoAccessor):
             스펙: 기본 10485760 · 범위 1~1073741824000 · 단위 byte · 변경 가능/재기동 불필요.
         subExpiryMinutes (int): 구독 만료(분). 기본 10080(7일).
             스펙: 기본 10080 · 범위 0~2147483647 (0=비활성) · 단위 분 · 변경 가능/재기동 불필요.
-        memberExpiryMinutes (int): 컨슈머 그룹 멤버 유휴 만료(분). 기본 5
-            (Kafka ``max.poll.interval.ms`` 기본값에 대응).
+        memberExpiryMinutes (int): 컨슈머 그룹 멤버 유휴 만료(분). 기본 5.
             구독 옵션 ``expiryMs`` 가 이 값을 덮는다.
             스펙: 기본 5 · 범위 1~9999 · 단위 분 · 변경 가능/재기동 불필요.
         deadSessionKeepDuration (int): 끊긴 세션 정보 보관(초). 기본 600.
@@ -5292,11 +5302,11 @@ class ILSpokeProperty(_AutoAccessor):
 #: 왼쪽 정렬 십진수로 썼고 ``MIMQ_RUNNING`` 이 **2** 라, 판 표시를 ``"2"`` 로 두면
 #: 옛 블롭이 **"판 2 와 정확히 일치" 로 읽힌다**(거절도 아니고 "낮은 판" 도 아니다).
 #: 글자로 시작하면 옛 블롭이 만들 수 없는 값이 되어 두 방향이 모두 막힌다.
-CLUSTER_LAYOUT_MARK = "V2"
+CLUSTER_LAYOUT_MARK = "V%d" % ILC.MIMQ_CLUSTER_BLOB_VERSION
 
 #: :data:`CLUSTER_LAYOUT_MARK` 의 숫자 부분. 비교는 이쪽으로 한다 - 문자열 비교는
 #: ``"V10" < "V2"`` 로 갈린다.
-_CLUSTER_LAYOUT_NUMBER = 2
+_CLUSTER_LAYOUT_NUMBER = ILC.MIMQ_CLUSTER_BLOB_VERSION
 
 #: :class:`ILClusterNode` 와이어 레이아웃 ``(속성 이름, 폭)``. **오프셋은 순서에서 계산한다** -
 #: 폭이 조정돼도 이 표 한 줄만 고치면 파싱·직렬화·보존이 같이 따라간다.
@@ -5380,6 +5390,13 @@ class ILClusterNode(_AutoAccessor):
         ctrlPort (int): 그 노드의 **컨트롤러 포트**. 문법에서 주소 뒤 ``/9000`` 자리다.
             스펙: 범위 1025~65535 · 변경 불가.
         coordinator (bool | None): 이 노드가 **컨트롤러 멤버**인가(문법의 ``COORDS``).
+            엔진 rev 3463 이상이면 보낸 값이 **정의에 보존된다**(되읽으면 온다).
+            ☠ 다만 **동작에 쓰이는 것은 컨트롤러 정족수가 켜진 뒤**다 - 그전에는
+            저장만 되고 아무 일도 일어나지 않는다.
+            ☠ 문법의 ``COORDS(1)`` 은 *"1번이 컨트롤러고 **나머지는 아니다**"* 라는
+            완결된 진술이다. 블롭으로 같은 말을 하려면 나머지 노드를 **명시적으로
+            ``False``** 로 둬야 한다 - 빈칸으로 두면 *"모른다"* 가 되어 뜻이 다르다.
+            컨트롤러 노드에는 **``ctrl_port`` 가 반드시** 있어야 한다.
             ★ **``None`` 은 "모름"** 이고 ``False``("아니다")와 **다르다**. 서버가 안
             채웠거나 이 판이 모르는 값일 때 ``None`` 이다. 참/거짓으로 판정하지 말고
             ``is None`` 으로 먼저 가른다.
@@ -5660,7 +5677,11 @@ _CLUSTER_FIXED_FIELDS = (
     ("replicas", 5), ("minSync", 5),
     ("secretFile", 256),
     ("controllerLeader", 6), ("defTerm", 10), ("defVersion", 10),
-    ("signature", 20), ("statusReason", 96), (None, 185),
+    ("signature", 20), ("statusReason", 96),
+    # 엔진 r3473 이 예약 앞 12바이트에 이름을 줬다. **판 번호는 안 올랐다**(V2 그대로) -
+    # 이 클라는 모르는 자리를 원본째 되보내므로 이름이 붙기 전에도 아무 문제가 없었다.
+    # ☠ 둘 다 **관측 전용**이다: 엔진이 나갈 때만 채우고 들어올 때는 지운다.
+    ("actingCoordinator", 6), ("localCtrlPort", 6), (None, 173),
 )
 
 _CLUSTER_OFF, _CLUSTER_LEN = _field_offsets(_CLUSTER_FIXED_FIELDS)
@@ -5765,6 +5786,11 @@ class ILClusterProperty(_AutoAccessor):
         defVersion (int | None): **읽기 전용.** 이 정의의 **판 번호**.
             ★ ``defTerm`` 과 **쌍**이다. **0 은 정상값**이고 없음은 오직 ``None`` 이다.
         signature (str): **읽기 전용.** 엔진이 정의에 붙이는 표식.
+        actingCoordinator (int | None): **읽기 전용.** 승격을 집행하는 조정자의
+            노드 번호. 모르면 ``None`` - **0 은 노드 번호가 아니다.**
+        localCtrlPort (int | None): **읽기 전용.** 이 응답을 준 **서비스가 실제로
+            듣고 있는** ilcc 포트. 정의에 적힌 값이 아니라 **관측값**이다.
+            ★ 둘 다 엔진이 **나갈 때만** 채운다 - 실어 보내도 무시된다.
         nodes (list[ILClusterNode]): 클러스터를 이루는 노드 전부.
 
     Note:
@@ -5806,11 +5832,15 @@ class ILClusterProperty(_AutoAccessor):
         "defTerm": "엔진이 채우는 값이다",
         "defVersion": "엔진이 채우는 값이다",
         "signature": "엔진이 채우는 값이다",
+        "actingCoordinator": "관측값이다 - 엔진이 나갈 때만 채운다",
+        "localCtrlPort": "관측값이다 - 답한 서비스가 실제로 듣는 포트다",
     }
 
     _RENAMED = {
         "clusterType": ("노드마다의 역할(ILClusterNode.is_broker / coordinator)", "0.17.0"),
         "ilccPort": ("노드마다의 ILClusterNode.ctrlPort", "0.17.0"),
+        "judge": ("노드마다의 ILClusterNode.is_coordinator", "0.17.0"),
+        "coordinator": ("노드마다의 ILClusterNode.is_coordinator", "0.17.0"),
         "authorityHolder": ("controllerLeader (노드 번호다)", "0.17.0"),
     }
 
@@ -5826,15 +5856,15 @@ class ILClusterProperty(_AutoAccessor):
             ba (bytes | bytearray | None): 서버가 보낸 바이트(키워드로도 줄 수 있다).
                 주면 나머지 인자는 무시된다.
 
+        Raises:
+            ILDeserializeException: 바이트 길이가 규격보다 짧거나, **판 표시가 없거나
+                (레거시) 이 클라보다 높을 때.**
+
         Note:
             ★ **둘째 자리부터는 키워드로만 받는다.** 예전 둘째 자리는 ``ilcc_port`` 였다.
             그대로 위치 인자를 받으면 ``ILClusterProperty("C1", 27091)`` 이 **예외 없이**
             ``is_auto_start = 27091`` 로 들어가 조용히 다른 뜻이 된다 - **자리 재사용은 제거보다
             나쁘다.** 키워드 전용으로 막아 ``TypeError`` 로 터지게 한다.
-
-        Raises:
-            ILDeserializeException: 바이트 길이가 규격보다 짧거나, **판 표시가 없거나
-                (레거시) 이 클라보다 높을 때.**
         """
         if isinstance(name, (bytes, bytearray)):
             ba, name = name, ""
@@ -5855,6 +5885,8 @@ class ILClusterProperty(_AutoAccessor):
         self.defTerm = None
         self.defVersion = None
         self.signature = ""
+        self.actingCoordinator = None
+        self.localCtrlPort = None
         #: (내부) 서버가 준 고정부 원본. **읽기만 하는 자리와 읽지도 쓰지도 않는 구간을
         #: 되돌려 보내기 위해** 들고 있다(:meth:`get_serialized` 참조).
         self._rawBytes = b""
@@ -5905,6 +5937,10 @@ class ILClusterProperty(_AutoAccessor):
         self.defTerm = ba_pick_int_opt(ba, o["defTerm"][0], o["defTerm"][1])
         self.defVersion = ba_pick_int_opt(ba, o["defVersion"][0], o["defVersion"][1])
         self.signature = ba_pick_string(ba, o["signature"][0], o["signature"][1])
+        self.actingCoordinator = ba_pick_int_opt(ba, o["actingCoordinator"][0],
+                                                o["actingCoordinator"][1])
+        self.localCtrlPort = ba_pick_int_opt(ba, o["localCtrlPort"][0],
+                                            o["localCtrlPort"][1])
         _sr_off, _sr_len = o["statusReason"]
         self.statusReason = bytes(ba[_sr_off:_sr_off + _sr_len]).split(b"\x00")[0].decode(
             "utf-8", "replace")
@@ -5924,6 +5960,11 @@ class ILClusterProperty(_AutoAccessor):
         Returns:
             list[ILClusterNode]: ``coordinator`` 가 **True 인 노드만**. ``None``(모름)은
             넣지 않는다 - 모르는 것을 정족수에 세면 정족수가 틀린다.
+
+        Note:
+            ☠ **빈 목록은 두 뜻이다** - *"컨트롤러가 없다"* 와 *"아직 모른다"*. 목록
+            하나로는 삼상태를 못 싣는다. 가르려면 노드별
+            :meth:`ILClusterNode.is_coordinator` 를 ``is None`` 으로 본다.
         """
         return [n for n in self.nodes if n.coordinator is True]
 
@@ -5943,6 +5984,53 @@ class ILClusterProperty(_AutoAccessor):
 
     getBrokerNodes = get_broker_nodes
 
+    def _validate_addresses(self) -> None:
+        """노드 주소가 서로 겹치는지 **모든 짝**을 본다.
+
+        Raises:
+            ILOperationException: 브로커 둘이 같은 ``(host, port)`` 를 들거나,
+                노드 둘이 같은 ``(host, ctrlPort)`` 를 들 때
+                (``MIMQE_INVALID_ARGUMENT``).
+
+        Note:
+            ★ **ctrl 포트 검사는 역할을 안 본다.** ctrl 포트는 *"컨트롤러의 투표
+            포트"* 가 아니라 **그 서비스의 ilcc 포트**다 - 컨트롤러가 아닌 서비스도
+            ilcc 를 돌린다(브로커에 붙어 하트비트와 승격을 한다). 컨트롤러끼리만
+            보면 **역할 경계에 사각이 생긴다**(브로커 노드와 컨트롤러 전용 노드가
+            같은 포트를 들어도 안 걸린다).
+
+        Note:
+            ☠ **한 호스트에 컨트롤러 전용 노드가 둘인 것은 여기서 막지 않는다.**
+            주소가 다르면 정의는 정당하고(한 호스트에 서비스 둘이 각각 컨트롤러를
+            들 수 있다), 엔진이 *"둘 중 내가 누구인지 못 가린다"* 는 것뿐이다. 그
+            판정은 **요청을 받는 서비스가 누구인가**에 달렸는데 클라는 그것을
+            모른다 - 걸면 **정당한 정의를 거절**하게 된다.
+
+            같은 이유로 **컨트롤러 수 {1, 3, 5} 도 여기서 안 본다.** 그것은 엔진
+            정책이라 넓어질 수 있고, 그날 이 클라가 이유 없이 거절하는 쪽이 된다.
+            ⇒ 클라가 걸어도 되는 것은 **정의 자체로 판정되는 모순**뿐이다.
+        """
+        seen: dict = {}
+        for n in self.nodes:                       # 브로커끼리 데이터 주소
+            if not n.is_broker():
+                continue
+            key = (n.host, n.port)
+            if key in seen:
+                raise ILOperationException(
+                    "MIMQE_INVALID_ARGUMENT (nodes %d and %d share qmgr port %d)"
+                    % (seen[key], n.nodeId, n.port))
+            seen[key] = n.nodeId
+        seen = {}
+        for n in self.nodes:                       # ★ 역할 무관 - ctrl 포트가 있으면 본다
+            if not n.ctrlPort:
+                continue
+            key = (n.host, n.ctrlPort)
+            if key in seen:
+                raise ILOperationException(
+                    "MIMQE_INVALID_ARGUMENT (nodes %d and %d share ctrl port %d)"
+                    % (seen[key], n.nodeId, n.ctrlPort))
+            seen[key] = n.nodeId
+
     def get_node(self, node_id: int):
         """번호로 노드를 찾는다.
 

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/ilink/qmgr.py

@@ -199,7 +199,7 @@ class ILQmgr:
                 그 외에는 사용법을 안내한다.
         """
         if len(args) != 1:
-            print("available argrments.")
+            print("available arguments.")
             print("    --version : displays the library version.")
         ILC.print_version(args[0] if args else "")
 
@@ -461,9 +461,11 @@ class ILQmgr:
             conn_mode = ILC.MIMQ_SESSION_TRANSACTED
             if auto_commit:
                 conn_mode = ILC.MIMQ_AUTO_ACKNOWLEDGE
-            conn_res_msg = self.service.request(
-                ILC.MIMQ_NEW_CONNECTION, str(conn_mode), client_name, "USR"
-            )
+            # 0.18.0: 능력 선언. ☠ arg1(conn_mode)은 자동커밋 플래그라 건드리지 않는다.
+            _caps = ILC.client_caps_extension()
+            _cargs = ((ILC.MIMQ_NEW_CONNECTION,) + ((_caps,) if _caps else ())
+                      + (str(conn_mode), client_name, "USR"))
+            conn_res_msg = self.service.request(*_cargs)
             if conn_res_msg is None:
                 raise ILOperationException("MIMQE_INTERNAL_ERROR")
             if conn_res_msg.getCode() != ILC.MIMQ_SUCCESSFUL_CONNECTION:

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/jetstream_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.17.0
+Version: 0.18.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

{jetstream_api-0.17.0 → jetstream_api-0.18.0}/pyproject.toml

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