jetstream-api 0.4.2__tar.gz → 0.4.4__tar.gz

{jetstream_api-0.4.2/jetstream_api.egg-info → jetstream_api-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.4.2
+Version: 0.4.4
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -137,15 +137,32 @@ print(adm.getTopicList())
 클러스터 큐 관리자에 접속하면 후보 주소를 캐싱해 두었다가, 리더가 바뀌어도 따라갑니다.
 
 ```python
-qmgr.set_auto_reconnect(True)     # auto-commit 세션에서만 동작
-print(qmgr.get_cluster_addresses())
-qmgr.reconnect()                  # 새 리더를 찾아 재접속
+qmgr.connect("10.0.0.1", 5000, "APP", True)   # 주소 하나면 됩니다
+print(qmgr.get_cluster_addresses())           # ['10.0.0.1:5000', '10.0.0.2:5000']
+qmgr.reconnect()                              # 새 리더를 찾아 재접속
+
+# 첫 접속 시점의 장애까지 대비하려면 목록으로 (포트 인자 없음)
+qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
 ```
 
-> `set_auto_reconnect`는 **transacted 세션에서는 동작하지 않습니다.** 미커밋 트랜잭션이
-> 재접속으로 유실되므로, 예외를 받고 앱이 트랜잭션을 처음부터 재수행해야 합니다
-> (`reconnect()` 직접 호출은 가능합니다). auto-commit 세션도 응답 유실 시점의 재시도로
-> **중복 put이 발생할 수 있습니다.**
+접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아 캐싱하므로
+**주소는 하나만 주면 됩니다.** 목록은 첫 접속 시점의 장애까지 대비할 때 씁니다.
+
+### 0.4.4 변경 - 자동 재접속은 옵션이 아니라 기본 동작
+
+캐싱된 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한 put/get 을 페일오버
+재접속 후 **한 번 자동 재시도합니다.** `set_auto_reconnect()` 는 더 이상 필요 없으며,
+불러도 무시됩니다(기존 코드 호환용으로만 남겨 두었습니다).
+
+| 상황 | 동작 |
+|---|---|
+| 미커밋 트랜잭션 **있음** | 예외를 올립니다. 앱이 `reconnect()` 후 트랜잭션을 처음부터 다시 수행 |
+| 미커밋 트랜잭션 **없음** (auto-commit 포함) | 내부에서 재접속 후 1회 재시도 |
+| endpoint 목록 없음 (비클러스터/구엔진) | 예외를 올립니다 - 갈 곳이 없습니다 |
+
+> 재시도는 **at-least-once** 입니다. 서버가 처리한 뒤 응답이 유실된 시점에 재시도하면
+> **중복 put 이 생길 수 있습니다.** 멱등하지 않은 처리라면 메시지 ID 로 중복을 걸러야
+> 합니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
 
 ## 0.4.0 신규 - 관리 연결 하나로 pub/sub
 

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/README.md

@@ -91,15 +91,32 @@ print(adm.getTopicList())
 클러스터 큐 관리자에 접속하면 후보 주소를 캐싱해 두었다가, 리더가 바뀌어도 따라갑니다.
 
 ```python
-qmgr.set_auto_reconnect(True)     # auto-commit 세션에서만 동작
-print(qmgr.get_cluster_addresses())
-qmgr.reconnect()                  # 새 리더를 찾아 재접속
+qmgr.connect("10.0.0.1", 5000, "APP", True)   # 주소 하나면 됩니다
+print(qmgr.get_cluster_addresses())           # ['10.0.0.1:5000', '10.0.0.2:5000']
+qmgr.reconnect()                              # 새 리더를 찾아 재접속
+
+# 첫 접속 시점의 장애까지 대비하려면 목록으로 (포트 인자 없음)
+qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
 ```
 
-> `set_auto_reconnect`는 **transacted 세션에서는 동작하지 않습니다.** 미커밋 트랜잭션이
-> 재접속으로 유실되므로, 예외를 받고 앱이 트랜잭션을 처음부터 재수행해야 합니다
-> (`reconnect()` 직접 호출은 가능합니다). auto-commit 세션도 응답 유실 시점의 재시도로
-> **중복 put이 발생할 수 있습니다.**
+접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아 캐싱하므로
+**주소는 하나만 주면 됩니다.** 목록은 첫 접속 시점의 장애까지 대비할 때 씁니다.
+
+### 0.4.4 변경 - 자동 재접속은 옵션이 아니라 기본 동작
+
+캐싱된 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한 put/get 을 페일오버
+재접속 후 **한 번 자동 재시도합니다.** `set_auto_reconnect()` 는 더 이상 필요 없으며,
+불러도 무시됩니다(기존 코드 호환용으로만 남겨 두었습니다).
+
+| 상황 | 동작 |
+|---|---|
+| 미커밋 트랜잭션 **있음** | 예외를 올립니다. 앱이 `reconnect()` 후 트랜잭션을 처음부터 다시 수행 |
+| 미커밋 트랜잭션 **없음** (auto-commit 포함) | 내부에서 재접속 후 1회 재시도 |
+| endpoint 목록 없음 (비클러스터/구엔진) | 예외를 올립니다 - 갈 곳이 없습니다 |
+
+> 재시도는 **at-least-once** 입니다. 서버가 처리한 뒤 응답이 유실된 시점에 재시도하면
+> **중복 put 이 생길 수 있습니다.** 멱등하지 않은 처리라면 메시지 ID 로 중복을 걸러야
+> 합니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
 
 ## 0.4.0 신규 - 관리 연결 하나로 pub/sub
 

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/ilink/__init__.py

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

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/ilink/admin.py

@@ -705,9 +705,11 @@ class ILAdminService:
 
         Raises:
             ILOperationException: 세 서비스 주소나 세 ilcc 포트 중 하나라도 비었을 때
-                (``MIMQE_INVALID_ARGUMENT``), 같은 이름이 이미 있을 때, 이름에 금지
-                문자가 있을 때(``MIMQE_UNAVAILABLE_CLUSTER_NAME``), 포트가 1025~65535
-                밖일 때(``MIMQE_UNAVAILABLE_PORT_NUMBER``).
+                (``MIMQE_INVALID_ARGUMENT``), **세 서비스 주소 중 둘 이상이 같은
+                서비스를 가리킬 때**(``MIMQE_INVALID_ARGUMENT``, 엔진 rev 3322+),
+                같은 이름이 이미 있을 때, 이름에 금지 문자가 있을 때
+                (``MIMQE_UNAVAILABLE_CLUSTER_NAME``), 포트가 1025~65535 밖일 때
+                (``MIMQE_UNAVAILABLE_PORT_NUMBER``).
             ILException: 통신 실패.
 
         Note:
@@ -722,6 +724,26 @@ class ILAdminService:
             역할(코디네이터/심판)과 각 ilcc 포트는 **서비스가 배정한다.** 이 호출을
             받은 서비스가 세 곳에 정의를 퍼뜨리면서 대상별로 채워 넣는다.
 
+        .. warning:: 접속 정보가 겹치면 생성이 실패한다
+
+            ``priSvc`` / ``secSvc`` / ``witSvc`` 는 **서로 다른 관리 서비스**여야 한다.
+            둘 이상이 같은 서비스를 가리키면 서버가 ``MIMQE_INVALID_ARGUMENT`` 로
+            **생성을 거부한다**(엔진 rev 3322+).
+
+            **같은 IP 라도 관리 서비스 포트가 다르면 된다**(한 호스트에 여러 서비스를
+            띄우는 시험 구성이 그렇다). 비교는 ``"호스트:포트"`` 로 하며 포트를 생략하면
+            9998 로 본다 - 즉 ``"10.0.0.1"`` 과 ``"10.0.0.1:9998"`` 은 같은 주소이고,
+            ``"10.0.0.1:9988"`` 은 다른 주소다.
+
+            왜 막느냐면, 겹친 채로 만들어지면 그 서비스가 같은 이름의 오브젝트를 두
+            역할로 갖게 되고 전파가 "있으면 갱신"으로 처리해 **나중 것이 앞 것을
+            덮어쓰기** 때문이다. 조정자가 하나뿐인 구성 - 3-서비스를 강제해서 막으려던
+            바로 그 상태가 된다.
+
+            **rev 3322 미만 엔진은 검사하지 않는다.** 거부 없이 그 구성이 그대로
+            만들어지므로 부르는 쪽이 지켜야 한다. 이 라이브러리는 검사하지 않는다 -
+            판정을 두 곳에 두면 규칙이 어긋나기 때문이다.
+
         Warning:
             **닿지 않는 서비스가 있어도 이 호출은 성공한다.** 구성만 미리 해두는
             운영을 허용하기 때문이다. 대신 클러스터가 ``STARTING`` 에 머물고
@@ -868,6 +890,34 @@ class ILAdminService:
         노드 편집은 **읽고-고치고-쓴다**: getClusterProperty 로 받아
         add_node()/remove_node() 한 뒤 이 메서드로 되돌려준다.
 
+        Raises:
+            ILOperationException: 노드가 규칙을 어겼을 때(전부
+                ``MIMQE_INVALID_ARGUMENT``) - 큐 관리자 이름이 빈 노드가 있을 때
+                (**rev 3319+**), 같은 ``host:port`` 노드가 둘 이상일 때, 같은
+                ``nodeId`` 노드가 둘 이상일 때(**rev 3323+**).
+            ILException: 통신 실패.
+
+        .. warning:: 토폴로지는 여기서 바꾸지 마라
+
+            ``priSvc`` / ``secSvc`` / ``witSvc`` 와 세 포트는 **생성 시점에 정하는
+            값**이다. ilsc 의 ALTER 는 이 항목을 아예 받지 않는다. 그런데 이 메서드는
+            속성 전체를 통째로 보내므로 **바뀐 채로 저장된다**(실측).
+
+            문제는 **빠진 서비스에 오브젝트가 남는다**는 것이다. 전파는 새 토폴로지로만
+            가므로 옛 서비스는 통지를 못 받고, 그 자리에 **옛 토폴로지를 든 오브젝트가
+            그대로 남는다**(실측: SEC 을 옮긴 뒤 옛 SEC 서비스에 잔존). 조정자를
+            옮기려면 **클러스터를 지우고 다시 만들어라.**
+
+        Note:
+            **클러스터 구성 검사는 전부 이 경로에서 이뤄진다.** 노드 추가/삭제도
+            결국 여기로 오므로, 서버는 쓰기 입구인 여기 한 곳에서 막는다.
+            :meth:`addClusterNode` / :meth:`removeClusterNode` 도 같은 검사를 받는다.
+
+            중복 노드가 왜 막히는지는
+            :meth:`ILClusterProperty.add_node` 를 보라 - 요약하면 같은 큐 관리자를
+            두 노드로 등록하면 이중 제어가 되고, ``nodeId`` 가 겹치면 **노드가 서로
+            다른 id 를 받아 갈라진다.**
+
         Example::
 
             p = svc.getClusterProperty("CC1")
@@ -896,7 +946,11 @@ class ILAdminService:
             port (int): **큐 관리자 리스너 포트**(ilcc 포트가 아니다).
 
         Raises:
-            ILOperationException: 조회나 반영이 거절됐을 때.
+            ILOperationException: 조회나 반영이 거절됐을 때. **같은 ``host:port``
+                노드가 이미 있으면 거절된다** - 한 큐 관리자를 두 노드로 등록하는
+                셈이기 때문이다(``MIMQE_ALREADY_EXIST`` 로 이 라이브러리가 먼저 막고,
+                블롭을 직접 만들어 보내도 서버가 ``MIMQE_INVALID_ARGUMENT`` 로
+                거절한다 - **엔진 rev 3323+**).
             ILException: 통신 실패.
 
         Warning:
@@ -2935,12 +2989,20 @@ class ILAdminQmgr:
                 qmgr.startChannel("TO.QM2")
 
                 qmgr2.createQueue(ILQueueProperty("APP.ORDERS"))   # 받는 쪽
+
+        .. note:: 구엔진(6.3.3 미만) 호환
+
+            큐 속성은 엔진 6.3.3 에서 전송 레이아웃이 한 번 바뀐 **유일한**
+            속성이다(4096 -> 2200). 붙어 있는 엔진의 리비전을 보고 알아서 옛
+            레이아웃으로 보내므로 호출부는 달라질 게 없다. 다만 구엔진에는
+            만료(``expiry``)/영속성(``deliveryMode``)/파티션 설정이 아예 없어
+            **그 값들은 무시된다** - 설정해도 반영되지 않는다.
         """
         try:
             self.service.apply(
                 self.qmgrName,
                 ILC.MIMQ_CREATE_QUEUE_REQUEST,
-                prop.get_serialized(),
+                self._queueBlob(prop),
                 ILC.MIMQ_SUCCESSFUL_QUEUE_CREATION,
             )
         except _PASSTHROUGH_EXCEPTIONS:
@@ -3043,6 +3105,41 @@ class ILAdminQmgr:
         except Exception as exc:
             raise ILException(exc) from exc
 
+    def _queueBlob(self, prop: ILQueueProperty) -> bytes:
+        """큐 속성을 **붙어 있는 엔진이 이해하는 레이아웃**으로 직렬화한다.
+
+        Args:
+            prop (ILQueueProperty): 보낼 큐 속성.
+
+        Returns:
+            bytes: rev 3155 미만이면 구버전(4096), 그 외에는 현행(2200) 블롭.
+
+        Note:
+            판정을 ``0 < revision`` 으로 한정한 이유는 다른 버전 게이트와 같다.
+            버전 문자열을 파싱하지 못하면 revision 이 0 으로 남는데, 그때 구버전
+            취급을 하면 최신 엔진에 4096 을 보내 조용히 깨진다.
+        """
+        return prop.get_serialized(
+            legacy=0 < self.revision < ILC.QUEUE_LAYOUT_MIN_REVISION
+        )
+
+    def _requireQueueFlowSupport(self) -> None:
+        """유량 조회를 지원하지 않는 엔진이면 그 자리에서 실패시킨다.
+
+        Raises:
+            ILOperationException: 엔진이 6.3.4(rev 3299) 미만일 때.
+
+        Note:
+            유량 통계는 6.3.4 에서 들어왔다. 구엔진은 요청 코드 자체를 모르므로
+            응답이 없거나 엉뚱한 리포트가 온다. 무엇이 잘못됐는지 알 수 없는
+            타임아웃 대신 **왜 안 되는지 적힌 예외**로 끊는다.
+        """
+        if 0 < self.revision < ILC.QUEUE_FLOW_MIN_REVISION:
+            raise ILOperationException(
+                "MIMQE_NOT_SUPPORTED (queue flow statistics require engine 6.3.4, "
+                f"rev {ILC.QUEUE_FLOW_MIN_REVISION}+, current: {self.revision})"
+            )
+
     def getQueueProperty(self, queueName: str) -> ILQueueProperty:
         """큐 하나의 전체 속성을 조회한다(종류 무관).
 
@@ -3204,12 +3301,20 @@ class ILAdminQmgr:
             prop = qmgr.getQueueProperty("APP.ORDERS")
             prop.setMaxDepth(50000)
             qmgr.setQueueProperty(prop)
+
+        .. note:: 구엔진(6.3.3 미만) 호환
+
+            큐 속성은 엔진 6.3.3 에서 전송 레이아웃이 한 번 바뀐 **유일한**
+            속성이다(4096 -> 2200). 붙어 있는 엔진의 리비전을 보고 알아서 옛
+            레이아웃으로 보내므로 호출부는 달라질 게 없다. 다만 구엔진에는
+            만료(``expiry``)/영속성(``deliveryMode``)/파티션 설정이 아예 없어
+            **그 값들은 무시된다** - 설정해도 반영되지 않는다.
         """
         try:
             self.service.apply(
                 self.qmgrName,
                 ILC.MIMQ_SET_QUEUE_PROPERTY,
-                prop.get_serialized(),
+                self._queueBlob(prop),
                 ILC.MIMQ_SUCCESSFUL_SET_QUEUE_PROPERTY,
             )
         except _PASSTHROUGH_EXCEPTIONS:
@@ -3388,23 +3493,39 @@ class ILAdminQmgr:
             ``getIncomingDataSize()`` / ``getOutgoingDataSize()`` / ``getDepth()``).
 
         Raises:
-            ILOperationException: 그런 큐가 없을 때.
+            ILOperationException: 그런 큐가 없을 때. 또는 엔진이 6.3.4(rev 3299)
+                미만이라 유량 통계 자체를 지원하지 않을 때.
             ILException: 통신 실패.
 
         Note:
             **한 시점의 스냅샷**이다. 시간에 따른 추이를 보려면
             :meth:`getQueueFlowInfoArray` 를 쓴다.
 
-        .. warning:: 갓 만든 큐는 잠시 조회되지 않는다
+        .. note:: 값은 **1초 주기**로 채워진다
+
+            유량 스냅샷은 서버가 1초마다 적재한다. 그래서 갓 만든 큐도 **조회
+            자체는 즉시 되지만**(엔진 r3336+) 유입/유출 값은 첫 적재가 돌 때까지
+            0 이다 - 실측: put 직후 0초 시점 0, 1.2초 시점 5건/2695B (r3336).
+            즉시 깊이가 필요하면 :meth:`getQueueRealTimeInfo` 를 쓰라. 그쪽은
+            적재 주기와 무관하게 현재 값을 준다.
+
+            **엔진 r3336 미만에서는 갓 만든 큐가 최대 1초간 조회되지 않는다** -
+            첫 적재 전까지 ``MIMQE_OBJECT_NOT_FOUND`` 가 난다(r3335 실측
+            0.1~1.1초, 단건·배열 50회). put/get 을 해도 앞당겨지지 않는다.
+
+            .. versionchanged:: 0.1.6
+                이전 문서는 "유량 테이블은 주기적(약 1분) 갱신"이라고 적었으나
+                **사실이 아니다**. 실서버에서 관측된 35초 지연은 적재 주기가
+                아니라 **적재 스레드가 분 단위 통계 리포트에 붙들려 있던 것**으로,
+                엔진 r3331 통계 컴팩션으로 해소됐다.
 
-            유량 집계 테이블은 **주기적으로 갱신**된다. 큐를 만든 직후에는 아직
-            등록되지 않아 ``MIMQE_OBJECT_NOT_FOUND`` 가 나고, **약 1분 뒤부터**
-            정상 조회된다(실서버 확인: 생성 직후 실패 -> 35초 뒤 성공).
-            put/get 을 해도 앞당겨지지 않는다. **서버 동작이라 클라이언트에서
-            우회할 수 없다** - 방금 만든 큐의 현황은 :meth:`getQueueRealTimeInfo`
-            로 보라(이쪽은 즉시 조회된다).
+            .. versionchanged:: 0.4.4
+                엔진 r3336 이 큐 생성 시점에 유량 항목을 미리 등재하도록 바뀌어
+                **생성 직후 조회 실패가 사라졌다**(24/24 첫 시도 성공, 값은 0).
+                재시도 코드는 구엔진 대비로만 남기면 된다.
 
         """
+        self._requireQueueFlowSupport()
         try:
             report_msg = self.service.request(
                 self.qmgrName, ILC.MIMQ_GET_QUEUE_ACCESS_INFO, queueName
@@ -3441,23 +3562,39 @@ class ILAdminQmgr:
             실제 기록이 그보다 적으면 0 으로 채운 항목이 들어간다.
 
         Raises:
-            ILOperationException: 그런 큐가 없을 때.
+            ILOperationException: 그런 큐가 없을 때. 또는 엔진이 6.3.4(rev 3299)
+                미만이라 유량 통계 자체를 지원하지 않을 때.
             ILException: 통신 실패.
 
         Note:
             0 으로 채워진 항목과 실제로 유량이 0 이었던 구간은 값만으로 구분되지
             않는다. 적체 추세만 보는 용도로 쓰라.
 
-        .. warning:: 갓 만든 큐는 잠시 조회되지 않는다
+        .. note:: 값은 **1초 주기**로 채워진다
+
+            유량 스냅샷은 서버가 1초마다 적재한다. 그래서 갓 만든 큐도 **조회
+            자체는 즉시 되지만**(엔진 r3336+) 유입/유출 값은 첫 적재가 돌 때까지
+            0 이다 - 실측: put 직후 0초 시점 0, 1.2초 시점 5건/2695B (r3336).
+            즉시 깊이가 필요하면 :meth:`getQueueRealTimeInfo` 를 쓰라. 그쪽은
+            적재 주기와 무관하게 현재 값을 준다.
+
+            **엔진 r3336 미만에서는 갓 만든 큐가 최대 1초간 조회되지 않는다** -
+            첫 적재 전까지 ``MIMQE_OBJECT_NOT_FOUND`` 가 난다(r3335 실측
+            0.1~1.1초, 단건·배열 50회). put/get 을 해도 앞당겨지지 않는다.
 
-            유량 집계 테이블은 **주기적으로 갱신**된다. 큐를 만든 직후에는 아직
-            등록되지 않아 ``MIMQE_OBJECT_NOT_FOUND`` 가 나고, **약 1분 뒤부터**
-            정상 조회된다(실서버 확인: 생성 직후 실패 -> 35초 뒤 성공).
-            put/get 을 해도 앞당겨지지 않는다. **서버 동작이라 클라이언트에서
-            우회할 수 없다** - 방금 만든 큐의 현황은 :meth:`getQueueRealTimeInfo`
-            로 보라(이쪽은 즉시 조회된다).
+            .. versionchanged:: 0.1.6
+                이전 문서는 "유량 테이블은 주기적(약 1분) 갱신"이라고 적었으나
+                **사실이 아니다**. 실서버에서 관측된 35초 지연은 적재 주기가
+                아니라 **적재 스레드가 분 단위 통계 리포트에 붙들려 있던 것**으로,
+                엔진 r3331 통계 컴팩션으로 해소됐다.
+
+            .. versionchanged:: 0.4.4
+                엔진 r3336 이 큐 생성 시점에 유량 항목을 미리 등재하도록 바뀌어
+                **생성 직후 조회 실패가 사라졌다**(24/24 첫 시도 성공, 값은 0).
+                재시도 코드는 구엔진 대비로만 남기면 된다.
 
         """
+        self._requireQueueFlowSupport()
         try:
             res_msg = self.service.inquire(
                 self.qmgrName, ILC.MIMQ_GET_QUEUE_ACCESS_INFO_ARRAY, queueName
@@ -4831,6 +4968,15 @@ class ILAdminQmgr:
         Note:
             **누가 언제 마지막으로 이 큐를 건드렸는지** 알 수 있어 소비자가
             멈춘 상황을 진단할 때 유용하다.
+
+        .. note:: 구엔진(6.3.3 미만)에 붙었을 때
+
+            그 시절 엔진은 이 요청에 **큐 속성 블롭을 통째로** 답한다. 사용 현황
+            통계가 속성 안에 들어 있었기 때문이다. 클라이언트가 알아서 판별해
+            같은 필드를 채우므로 호출부는 달라질 게 없다. 다만
+            :attr:`~ilink.properties.ILQueueRealTimeInfo.partitions` 는 **빈
+            목록**이다 - 파티셔닝은 6.3.3 에서 들어온 기능이라 구엔진 큐에는
+            파티션이라는 개념 자체가 없다.
         """
         try:
             res_msg = self.service.inquire(
@@ -4838,7 +4984,12 @@ class ILAdminQmgr:
             )
             if res_msg.getType() == ILC.MIMQ_REPORT_MESSAGE:
                 raise ILOperationException(res_msg.getReportMsg().getArg2())
-            return ILQueueRealTimeInfo(res_msg.getDataMsg().getData())
+            data = res_msg.getDataMsg().getData() or b""
+            # 구엔진(rev 3155 미만)은 이 요청에 **큐 속성 블롭 4096** 을 그대로
+            # 답한다. 그 시절에는 사용 현황 통계가 속성 안에 들어 있었기 때문이다.
+            if len(data) >= ILC.MIMQ_VO_QUEUE_LEN_LEGACY:
+                return ILQueueRealTimeInfo.from_legacy_queue_blob(data)
+            return ILQueueRealTimeInfo(data)
         except _PASSTHROUGH_EXCEPTIONS:
             raise
         except Exception as exc:

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/ilink/common.py

@@ -719,6 +719,19 @@ class ILC:
     MIMQ_VO_SERVER_LEN = 428
     MIMQ_VO_QMGR_LEN = 666
     MIMQ_VO_QUEUE_LEN = 2200
+    #: 큐 속성 블롭의 **구버전(4096) 길이**. 엔진 6.3.3 미만이 쓰던 레이아웃이다.
+    #: 0~1772 와 2142~2162 는 현행과 같고, 그 사이 370 바이트만 다르다 -
+    #: 구버전은 사용 현황 통계, 현행은 만료/영속성/파티셔닝 설정이 들어간다.
+    MIMQ_VO_QUEUE_LEN_LEGACY = 4096
+    #: 큐 속성이 2200 레이아웃으로 바뀐 **첫 엔진 리비전**(6.3.3.3155).
+    #: 이 값보다 낮으면 4096 레이아웃으로 주고받아야 한다.
+    QUEUE_LAYOUT_MIN_REVISION = 3155
+    #: 구버전(4096) 블롭에서 공통 접두가 끝나고 레이아웃이 갈리는 지점.
+    #: 큐 **유량 통계** 조회가 들어온 첫 엔진 리비전(6.3.4.3299).
+    QUEUE_FLOW_MIN_REVISION = 3299
+    QUEUE_LEGACY_DIVERGE_OFFSET = 1772
+    #: 구버전(4096) 블롭에서 incomingDelayDepth 가 있는 위치. 현행과 같다.
+    QUEUE_LEGACY_TAIL_OFFSET = 2142
     MIMQ_VO_CHANNEL_LEN = 2048
     MIMQ_VO_DEST_ITEM_LEN = 1024
     MIMQ_VO_QUEUE_INFO_LEN = 512

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/ilink/msg.py

@@ -2524,7 +2524,14 @@ class ILMsgUtil:
         elif cls is ILQmgrProperty:
             serialized_length = ILC.MIMQ_VO_QMGR_LEN
         elif cls is ILQueueProperty:
+            # 큐 속성만 컨테이너 길이가 바뀐 적이 있다(엔진 6.3.3 에서 4096 -> 2200).
+            # 버전을 따지는 대신 **응답 길이에서 보폭을 역산**한다. 구엔진에 붙어도
+            # 목록이 그대로 읽히고, 새 엔진에서는 계산 결과가 2200 이라 무해하다.
             serialized_length = ILC.MIMQ_VO_QUEUE_LEN
+            if count > 0:
+                stride = (len(ba) - count_length) // count
+                if stride == ILC.MIMQ_VO_QUEUE_LEN_LEGACY:
+                    serialized_length = ILC.MIMQ_VO_QUEUE_LEN_LEGACY
         elif cls is ILChannelProperty:
             serialized_length = ILC.MIMQ_VO_CHANNEL_LEN
         elif cls is ILSpokeProperty:

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/ilink/properties.py

@@ -446,6 +446,7 @@ class ILXmitQueueMinorProperty(ILQueueMinorProperty):
             super().__init__(name, ILC.MIMQ_CHANNEL_TRANSMISSION_QUEUE)
 
 
+
 class ILQueueProperty(_AutoAccessor):
     """큐의 **전체 속성**. 큐 생성/조회/변경에 모두 쓰이는 값 객체.
 
@@ -515,6 +516,11 @@ class ILQueueProperty(_AutoAccessor):
         maxMemorySize (int): 메모리 상주 한도(바이트). 기본 10485760(10MB).
         sharedMemorySize (int): 공유 메모리 크기. 기본 0.
         numberOfPartition (int): 파티션 수. 기본 10.
+        legacyBlob (bool): 이 객체가 **구버전(4096) 블롭**에서 만들어졌는지.
+            엔진 rev 3155 미만이 보낸 응답이면 True 다. 그 경우 ``expiry`` /
+            ``expiredQueue`` / ``deliveryMode`` / ``maxMemorySize`` /
+            ``sharedMemorySize`` / ``numberOfPartition`` 은 **서버가 준 값이 아니라
+            기본값**이다 - 구엔진에는 그 설정이 없다.
     """
 
     def __init__(
@@ -552,6 +558,8 @@ class ILQueueProperty(_AutoAccessor):
         self.maxMemorySize = 10485760
         self.sharedMemorySize = 0
         self.numberOfPartition = 10
+        #: 구버전(4096) 블롭에서 만들어졌는지. 내부 판별용.
+        self.legacyBlob = False
 
         if isinstance(name, (bytes, bytearray)):
             self._from_bytes(bytes(name))
@@ -575,6 +583,9 @@ class ILQueueProperty(_AutoAccessor):
                     + str(len(ba))
                     + "]"
                 )
+            # 엔진 6.3.3 미만은 4096 레이아웃을 보낸다. 길이로 가른다 -
+            # 엔진의 QueueProperty::IsLegacyBlob(nDataSize) 와 같은 판정이다.
+            self.legacyBlob = len(ba) >= ILC.MIMQ_VO_QUEUE_LEN_LEGACY
             offset = 0
             self.name = ba_pick_string(ba, offset, 70)
             offset += 70
@@ -603,19 +614,27 @@ class ILQueueProperty(_AutoAccessor):
             offset += 10
             self.traceEnabled = ba_pick_string(ba, offset, 1).lower() == "t"
             offset += 2
-            self.expiry = ba_pick_long(ba, offset, 20)
-            offset += 20
-            self.expiredQueue = ba_pick_string(ba, offset, 70)
-            offset += 70
-            self.deliveryMode = ba_pick_int(ba, offset, 2)
-            offset += 2
-            self.maxMemorySize = ba_pick_long(ba, offset, 20)
-            offset += 20
-            self.sharedMemorySize = ba_pick_long(ba, offset, 20)
-            offset += 20
-            self.numberOfPartition = ba_pick_int(ba, offset, 10)
-            offset += 10
-            offset += 228
+            # ---- 여기(1772)부터 레이아웃이 갈린다 ----
+            if self.legacyBlob:
+                # 구버전 4096: 이 자리는 사용 현황 통계다. 통계는
+                # ILQueueRealTimeInfo 가 같은 블롭에서 따로 꺼내가므로 여기서는
+                # 건너뛴다. 신규 설정 항목은 애초에 없으니 기본값을 유지한다.
+                offset = ILC.QUEUE_LEGACY_TAIL_OFFSET
+            else:
+                self.expiry = ba_pick_long(ba, offset, 20)
+                offset += 20
+                self.expiredQueue = ba_pick_string(ba, offset, 70)
+                offset += 70
+                self.deliveryMode = ba_pick_int(ba, offset, 2)
+                offset += 2
+                self.maxMemorySize = ba_pick_long(ba, offset, 20)
+                offset += 20
+                self.sharedMemorySize = ba_pick_long(ba, offset, 20)
+                offset += 20
+                self.numberOfPartition = ba_pick_int(ba, offset, 10)
+                offset += 10
+                offset += 228
+            # ---- 공통 접미 (2142) ----
             self.incomingDelayDepth = ba_pick_int(ba, offset, 10)
             offset += 10
             self.incomingDelay = ba_pick_int(ba, offset, 10)
@@ -623,16 +642,27 @@ class ILQueueProperty(_AutoAccessor):
         except Exception as exc:
             raise ILException(exc) from exc
 
-    def get_serialized(self) -> bytes:
+    def get_serialized(self, legacy: bool = False) -> bytes:
         """이 객체를 서버 규격의 **고정폭 바이트**로 직렬화한다.
 
+        Args:
+            legacy (bool): True 면 **구버전(4096) 레이아웃**으로 만든다.
+                엔진 rev 3155 미만에 보낼 때 쓴다. 기본 False(현행 2200).
+
         Returns:
             bytes: 서버로 그대로 보낼 수 있는 바이트열.
 
         Note:
             라이브러리가 요청을 보낼 때 내부적으로 부른다. 응용이 직접 부를
-            일은 거의 없다.
+            일은 거의 없다 - 어느 레이아웃으로 보낼지는 접속한 엔진 리비전을
+            보고 :class:`ILAdminQmgr` 가 정한다.
+
+            구버전 레이아웃에는 ``expiry`` / ``expiredQueue`` / ``deliveryMode`` /
+            ``maxMemorySize`` / ``sharedMemorySize`` / ``numberOfPartition`` 자리가
+            **없다.** 그 값들은 실리지 않고 버려진다 - 구엔진이 모르는 설정이다.
         """
+        if legacy:
+            return self._get_serialized_legacy()
         ba = bytearray(ILC.MIMQ_VO_QUEUE_LEN)
         offset = 0
         ba_merge(self.name, ba, offset)
@@ -681,6 +711,18 @@ class ILQueueProperty(_AutoAccessor):
         offset += 10
         return bytes(ba)
 
+    def _get_serialized_legacy(self) -> bytes:
+        """구버전(4096) 레이아웃으로 직렬화한다. 엔진 rev 3155 미만 전송용."""
+        cur = self.get_serialized()          # 현행 2200
+        ba = bytearray(ILC.MIMQ_VO_QUEUE_LEN_LEGACY)
+        d = ILC.QUEUE_LEGACY_DIVERGE_OFFSET
+        t = ILC.QUEUE_LEGACY_TAIL_OFFSET
+        # 공통 접두(0~1772)와 공통 접미(2142~2162)만 옮긴다. 그 사이는 구버전에서
+        # 사용 현황 통계 자리라 설정값을 넣으면 통계로 오독된다 - 0 으로 남긴다.
+        ba[0:d] = cur[0:d]
+        ba[t:t + 20] = cur[t:t + 20]
+        return bytes(ba)
+
     def get_type_string(self) -> str:
         """종류 코드를 사람이 읽는 문자열로 바꾼다.
 
@@ -1739,16 +1781,30 @@ class ILSecureFileProperty(_AutoAccessor):
 class ILQueueRealTimeInfo(_AutoAccessor):
     """큐의 **실시간 상태.** :meth:`ILAdminQmgr.getQueueRealTimeInfo` 가 돌려준다.
 
-    "소비자가 멈춘 것 같다" 를 진단할 때 ``lastGetTime`` / ``lastGetClient`` 가
-    결정적인 단서가 된다.
+    "소비자가 멈춘 것 같다" 를 진단할 때 깊이와 미커밋 건수를 함께 보면 된다.
+
+    Note:
+        **마지막 put/get 4항목은 6.3.3 미만 엔진 전용이다** - ``lastPutTime`` /
+        ``lastGetTime`` / ``lastPutClient`` / ``lastGetClient`` 넷을 말한다.
+        6.3.3 에서 실시간 속성이 별도 조회로 분리되면서 엔진의 실시간 정보
+        구조체에서 이 4개가 빠졌다 - 전송 규격에 자리는 남아 있지만 서버가
+        채우지 않는다(직렬화에서 그 180바이트를 건너뛴다). 그래서 구엔진에
+        붙었을 때만 값이 온다.
+
+        6.3.3+ 에서 "누가 마지막으로 이 큐를 건드렸는지" 를 보려면 세션 쪽을
+        보라 - :meth:`ILAdminQmgr.getSessionList` 가 주는
+        :class:`ILSessionProperty` 의 ``lastAccessObject`` 가 그 정보를 세션
+        기준으로 담고 있다.
 
     Attributes:
         curDepth (int): 현재 깊이(메시지 수). 기본 0.
         openTime (int): 큐가 열린 시각(epoch 밀리초). 기본 0.
-        lastPutTime (int): 마지막 put 시각(epoch 밀리초). 없으면 0.
-        lastGetTime (int): 마지막 get 시각(epoch 밀리초). 없으면 0.
-        lastPutClient (str): 마지막으로 put 한 클라이언트 이름. 기본 ``""``.
-        lastGetClient (str): 마지막으로 get 한 클라이언트 이름. 기본 ``""``.
+        lastPutTime (int): 마지막 put 시각(epoch 밀리초). **엔진 6.3.3+ 는 항상 0**.
+        lastGetTime (int): 마지막 get 시각(epoch 밀리초). **엔진 6.3.3+ 는 항상 0**.
+        lastPutClient (str): 마지막으로 put 한 클라이언트 이름.
+            **엔진 6.3.3+ 는 항상** ``""``.
+        lastGetClient (str): 마지막으로 get 한 클라이언트 이름.
+            **엔진 6.3.3+ 는 항상** ``""``.
         numberOfClient (int): 이 큐를 열고 있는 클라이언트 수. 기본 0.
         numberOfChannel (int): 이 큐를 열고 있는 채널 수. 기본 0.
         uncommittedPut (int): 아직 커밋되지 않은 put 건수. 기본 0.
@@ -1889,6 +1945,43 @@ class ILQueueRealTimeInfo(_AutoAccessor):
             ret += "  " + str(partition)
         return ret
 
+    @classmethod
+    def from_legacy_queue_blob(cls, ba: bytes) -> "ILQueueRealTimeInfo":
+        """**구버전(4096) 큐 속성 블롭**에서 실시간 정보를 뽑아 만든다.
+
+        Args:
+            ba (bytes): 엔진 rev 3155 미만이 보낸 큐 속성 블롭(4096).
+
+        Returns:
+            ILQueueRealTimeInfo: 채워진 실시간 정보 객체.
+
+        Note:
+            구엔진은 실시간 정보 요청(``MIMQ_GET_QUEUE_LIVE_PROPERTY``)에 **큐 속성
+            블롭 그대로** 답한다. 사용 현황 통계가 그 블롭 안에 들어 있기 때문이다
+            (6.3.3 에서 별도 조회로 분리됐다). 그래서 같은 응답으로 속성 객체와
+            이 객체를 모두 채울 수 있다.
+
+            :attr:`partitions` 는 **빈 목록**이 된다. 파티셔닝은 6.3.3 에서 들어온
+            기능이라 구엔진 큐에는 파티션이라는 개념 자체가 없다 - 누락이 아니라
+            사실이다.
+        """
+        o = ILC.QUEUE_LEGACY_DIVERGE_OFFSET
+        info = cls()
+        info.curDepth = ba_pick_int(ba, 1740, 10)
+        info.openTime = ba_pick_long(ba, o, 20)
+        info.lastPutTime = ba_pick_long(ba, o + 20, 20)
+        info.lastGetTime = ba_pick_long(ba, o + 40, 20)
+        info.lastPutClient = ba_pick_string(ba, o + 60, 70)
+        info.lastGetClient = ba_pick_string(ba, o + 130, 70)
+        info.numberOfClient = ba_pick_int(ba, o + 200, 10)
+        info.numberOfChannel = ba_pick_int(ba, o + 210, 10)
+        # o+220 ~ o+300 : accumulated put/get/putSize/getSize (누적 총량).
+        #   현행 유량 조회(ILQueueFlow)는 **구간별** 값이라 의미가 달라 쓰지 않는다.
+        info.uncommittedPut = ba_pick_int(ba, o + 300, 10)
+        info.uncommittedGet = ba_pick_int(ba, o + 310, 10)
+        info.partitions = []
+        return info
+
 
 class ILQueueFlow(_AutoAccessor):
     """큐의 유입/유출량 스냅샷 하나.
@@ -3603,17 +3696,24 @@ class ILClusterNode(_AutoAccessor):
     최저값 = 초기 리더, 스위치백 우선순위). 사람이 타이핑하지는 않지만 **서버가
     채번해 주지도 않는다** - ilsc 가 그렇듯 **클라이언트가 max+1 로 매겨 보낸다**
     (0 은 비클러스터 예약값). ILClusterProperty.add_node() 가 대신 해 준다.
-    0 으로 보내면 서버는 그대로 저장하고, 같은 0 을 가진 노드끼리 충돌해
-    하나만 남는다(2026-08-13 실측).
+    **중복은 서버가 거부한다**(엔진 rev 3323+). 같은 nodeId 가 둘이면
+    ``MIMQE_INVALID_ARGUMENT (duplicate NodeId ...)``, 같은 host:port 가 둘이면
+    ``MIMQE_INVALID_ARGUMENT (duplicate node ...)`` 다. 0 을 여럿 보내는 것도
+    같은 이유로 막힌다 - 그 전 엔진은 그대로 저장했고, 그러면 노드가 서로 다른
+    id 를 받아 갈라졌다.
 
     운영자가 다루는 식별자는 qmgrName + host:port 다.
 
     Attributes:
-        nodeId (int): 노드 번호. 기본 0. **1 이상**이어야 한다(0 은 비클러스터
-            예약값). :meth:`ILClusterProperty.add_node` 가 max+1 로 채번한다.
+        nodeId (int): 노드 번호. 기본 0. **1 이상이고 클러스터 안에서 유일**해야
+            한다(0 은 비클러스터 예약값). :meth:`ILClusterProperty.add_node` 가
+            max+1 로 채번하므로 직접 매길 일은 없다. 중복이면 서버가 거부한다
+            (**엔진 rev 3323+**).
         host (str): 노드의 IP 또는 호스트명. 기본 ``""``.
         port (int): 노드 큐 관리자의 리스너 포트. 기본 0. 심판(witness) 노드일
-            때는 **상대 ilcc 포트**를 넣는다.
+            때는 **상대 ilcc 포트**를 넣는다. ``host:port`` 조합은 클러스터 안에서
+            **유일**해야 한다 - 같은 큐 관리자를 두 번 넣으면 서버가 거부한다
+            (**엔진 rev 3323+**).
         status (int): **읽기 전용** 노드 상태. 서버가 채운다. 기본 0.
         qmgrName (str): 노드 큐 관리자 이름. 기본 ``""``. **필수 값이다** -
             클러스터 기동/정지가 이 이름으로 노드를 찾으므로 비어 있으면 그 노드가
@@ -3712,8 +3812,10 @@ class ILClusterControlResult(_AutoAccessor):
         아무것도 싣지 않으므로 셋 다 0 / 빈 목록으로 온다 - **"빠진 노드가 없다"는
         뜻이 아니라 "알 수 없다"는 뜻**이다. :attr:`known` 으로 구분한다.
 
-        ``withNodes=False`` 로 불렀다면 애초에 노드를 제어하지 않으므로 이 값들은
-        의미가 없다.
+        ``withNodes=False`` 로 불렀다면 노드를 제어하지 않으므로 **셋 다 0 / 빈 목록**
+        으로 온다(엔진 rev 3322+). "빠져서 0" 이 아니라 "안 하기로 해서 0" 인데,
+        부른 쪽은 자기가 준 옵션을 아니까 구분된다. **rev 3317~3321 은 제어하지
+        않았는데도 전체 노드 수**를 실었다.
 
     Example::
 
@@ -3839,6 +3941,13 @@ class ILClusterProperty(_AutoAccessor):
             있어야 한다. 하나라도 비면 서버가 ``MIMQE_INVALID_ARGUMENT`` 로 거절한다.
             이미 만들어진 클러스터를 읽어오는 데는 제한이 없다.
 
+            **접속 정보가 겹치면 생성이 실패한다.** ``pri_svc`` / ``sec_svc`` /
+            ``wit_svc`` 중 둘 이상이 같은 관리 서비스를 가리키면 서버가
+            ``MIMQE_INVALID_ARGUMENT`` 로 거부한다(**엔진 rev 3322+**). 같은 IP 라도
+            관리 서비스 포트가 다르면 된다 - 비교는 ``"호스트:포트"`` 로 하며 포트
+            생략은 9998 로 본다. rev 3322 미만 엔진은 검사하지 않으므로, 겹친 구성이
+            거부 없이 만들어지고 조정자가 하나뿐인 상태가 된다.
+
         Example::
 
             p = ILClusterProperty(
@@ -3959,6 +4068,17 @@ class ILClusterProperty(_AutoAccessor):
         식별은 **주소(host:port)로 한다**. qmgrName 중복은 막지 않는다 -
         HA 는 양 노드 이름이 같은 구성이 오히려 정상이다.
 
+        **중복 등록은 서버가 거부한다**(엔진 rev 3323+). 막히는 것은 둘이다.
+
+        - 같은 ``host:port`` 를 두 번 - 한 큐 관리자를 두 노드로 등록하는 셈이다.
+          ilcc 가 같은 대상에 두 번 하트비트하고, 클러스터 기동/정지가 같은 것을
+          두 번 제어하며, 제어 수 집계도 부풀려진다.
+        - 같은 ``nodeId`` 를 두 번 - **이쪽이 더 나쁘다.** 멤버십 통지가 "너의 id"
+          를 내릴 때 어느 쪽인지 정할 수 없어 **노드가 서로 다른 id 를 받아
+          갈라진다.**
+
+        rev 3323 미만 엔진은 둘 다 그대로 저장했다.
+
         Args:
             qmgr_name (str): 노드 큐 관리자 이름. **필수다**(엔진 rev 3319+).
                 비우면 서버가 저장을 거부한다.
@@ -3974,11 +4094,19 @@ class ILClusterProperty(_AutoAccessor):
                 (이 API 의 오류 관례를 따른다 - 내장 예외를 쓰면 호출자가
                 ILException 계열만 잡다가 놓친다)
 
+
         Note:
             **큐 관리자 이름은 필수다.** 원래는 표시용 필드였는데 클러스터
             기동/정지가 이 이름으로 노드를 찾게 되면서 **제어 키로 승격**됐다.
             비어 있으면 그 노드는 제어 대상에서 빠지므로, 엔진 rev 3319 부터
             아예 저장을 거부한다. 여기서도 먼저 막는다.
+
+        Example::
+
+            p = svc.getClusterProperty("CC1")
+            p.add_node("QM1", "10.0.0.1", 21001)
+            p.add_node("QM2", "10.0.0.2", 21002)   # nodeId 는 1, 2 로 자동 채번
+            svc.setClusterProperty(p)
         """
         if not qmgr_name:
             raise ILOperationException(

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/ilink/qmgr.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import os
 import time
 import uuid
 from typing import List
@@ -66,7 +67,12 @@ class ILQmgr:
         # HA-3 클라이언트 페일오버: 접속 성공 시 캐싱한 클러스터 후보("host:port")
         self.clusterAddresses: list[str] | None = None
         self.clusterLeaderNodeId = -1
-        self.autoReconnect = False
+        # endpoint 목록을 남겨 둘 파일. **지정했을 때만** 읽고 쓴다(기본 없음).
+        self.endpointCacheFile: str | None = None
+        # 트랜잭션 세션에서 **커밋되지 않은 작업이 걸려 있는지**.
+        #   성공한 put/get 마다 켜고 commit/rollback/접속 시 끈다.
+        #   자동 재접속을 허용할지 판단하는 데 쓴다(걸린 게 없으면 잃을 것도 없다).
+        self.txnPending = False
 
     # --- context manager ---------------------------------------------------
     def __enter__(self) -> "ILQmgr":
@@ -226,12 +232,13 @@ class ILQmgr:
     def connect(
         self,
         host: str,
-        port: int,
-        client_name: str = "",
+        port: int | str | bool | None = None,
+        client_name: str | bool = "",
         auto_commit: bool = False,
         *,
         clientName: str | None = None,
         isAutoCommit: bool | None = None,
+        _allow_redirect: bool = True,
     ) -> None:
         """큐 관리자에 접속해 세션을 연다.
 
@@ -240,9 +247,13 @@ class ILQmgr:
         찾아갈 수 있게 한다.
 
         Args:
-            host (str): 큐 관리자의 IP 또는 호스트명.
+            host (str): 큐 관리자의 IP 또는 호스트명. **``"host:port"`` 또는 콤마로
+                이은 목록** (``"h1:p1,h2:p2"``)을 줄 수도 있다 - 그 경우 ``port`` 는
+                생략하고 뒤 인자가 한 칸씩 당겨진다
+                (``connect("h1:p1,h2:p2", "APP", True)``).
             port (int): 큐 관리자의 리스너 포트. **관리 서비스(ilsvc) 포트가 아니다** -
                 관리 포트(보통 9998)는 :class:`~ilink.admin.ILAdminService` 쪽이다.
+                주소 목록 형태로 줬으면 지정하지 않는다.
             client_name (str): 이 세션의 클라이언트 이름. 기본 ``""`` 이면 **호출한
                 모듈 이름을 자동으로** 쓴다. 큐 관리자 세션 목록에 그대로 보이므로
                 운영상 알아볼 수 있는 이름을 주는 편이 좋다.
@@ -260,13 +271,63 @@ class ILQmgr:
             세 번째 인자에 ``bool`` 을 주면 ``auto_commit``
             으로 해석한다 - ``connect(host, port, True)`` 가 동작한다.
 
+        .. note:: 클러스터에는 **주소 하나면 된다**
+
+            접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아
+            캐싱한다(:meth:`get_cluster_addresses` 로 확인). 이후 리더가 바뀌어도
+            :meth:`reconnect` 가 그 후보로 새 리더를 찾아간다.
+
+            **주소 목록은 최초 접속 부트스트랩용이다.** 캐싱은 접속에 성공한
+            뒤에 일어나므로, 하나만 준 그 주소가 첫 접속 시점에 죽어 있으면 갈
+            곳이 없다. 목록을 주면 순회하며 붙고, 팔로워가
+            ``MIMQE_FOLLOWER_NODE`` 로 거절하면 응답에 실린 리더 힌트를 맨 앞으로
+            올려 재시도한다(최대 2회전).
+
+            **단일 주소 형태는 리더 힌트를 따라가지 않는다** - 팔로워를 지목하면
+            그대로 예외가 난다. 그때는 :meth:`reconnect` 를 부르면 리더로 넘어간다.
+
         Example::
 
             qmgr = ILQmgr()
             qmgr.connect("192.168.0.10", 5000)                    # 트랜잭션 세션
             qmgr.connect("192.168.0.10", 5000, auto_commit=True)  # 자동 커밋
             qmgr.connect("192.168.0.10", 5000, client_name="billing-svc")
+
+            # 클러스터 - 주소 하나면 충분하다(나머지는 접속 후 캐싱된다)
+            qmgr.connect("10.0.0.1", 5000, "APP", True)
+            qmgr.getClusterAddresses()      # ['10.0.0.1:5000', '10.0.0.2:5000']
+
+            # 첫 접속 시점의 장애까지 대비하려면 목록으로 준다(포트 인자 없음)
+            qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
         """
+        # 주소 목록 형태 - 자바 connect(addressList, clientName, isAutoCommit) 대응.
+        #   "host:port" 하나든 콤마로 이은 여럿이든 같은 경로로 처리한다.
+        #   포트를 따로 받지 않으므로 뒤 인자가 한 칸씩 당겨진 형태다.
+        #   포트를 int 로 함께 준 호출은 기존 경로 그대로 둔다(오탐 방지).
+        if isinstance(host, str) and ("," in host or (":" in host and not isinstance(port, int))):
+            if isinstance(port, bool):
+                auto_commit = port
+            elif isinstance(port, str):
+                if isinstance(client_name, bool):
+                    auto_commit = client_name
+                client_name = port
+            elif port is not None:
+                raise ILSessionException(
+                    ILRC.MIMQE_INVALID_ADDRESS,
+                    "address list form takes no port argument : [%s:%s]" % (host, port),
+                )
+            if clientName is not None:
+                client_name = clientName
+            if isAutoCommit is not None:
+                auto_commit = isAutoCommit
+            candidates = [a.strip() for a in host.split(",") if a.strip()]
+            if not candidates:
+                raise ILSessionException(
+                    ILRC.MIMQE_INVALID_ADDRESS, "empty address list"
+                )
+            self._connect_any(candidates, client_name or "", bool(auto_commit))
+            return
+
         # Support legacy positional bool for client_name (Java-style overload)
         if isinstance(client_name, bool):
             auto_commit = client_name
@@ -302,6 +363,7 @@ class ILQmgr:
 
             self.sessionId = conn_res_msg.getArg1()
             self.isAutoCommitFlag = auto_commit
+            self.txnPending = False
             if self.sessionId == "":
                 self.disconnect()
                 raise ILSessionException(
@@ -352,9 +414,36 @@ class ILQmgr:
             # 막으면 정상 클러스터에서 페일오버 후보 캐싱이 조용히 사라진다.
             if not (0 < self.revision < 3265):
                 self._fetch_cluster_info()
-        except _PASSTHROUGH_EXCEPTIONS:
-            raise
+                self._save_endpoint_cache()
         except Exception as exc:
+            # 팔로워를 지목했으면 응답에 실린 리더 힌트로 **한 번** 옮겨 붙는다.
+            #   앱이 옛 리더 주소만 들고 재기동해도 승격된 리더를 찾아간다 -
+            #   주소를 하나만 줘도 되게 한다는 설계 의도가 여기까지다.
+            if _allow_redirect:
+                hint = self._extract_leader_hint(exc)
+                if hint:
+                    colon = hint.rfind(":")
+                    try:
+                        self.service.shutdown()
+                    except Exception:
+                        pass
+                    self.connect(
+                        hint[:colon],
+                        int(hint[colon + 1:]),
+                        client_name,
+                        auto_commit,
+                        _allow_redirect=False,
+                    )
+                    return
+                # 힌트를 줄 상대조차 없으면(노드가 죽어 있음) 파일에 남겨 둔
+                # 후보로 한 번 더 돈다. 경로를 지정했을 때만 동작한다.
+                cached = [a for a in self._load_endpoint_cache()
+                          if a != "%s:%s" % (host, port)]
+                if cached:
+                    self._connect_any(cached, client_name, auto_commit)
+                    return
+            if isinstance(exc, _PASSTHROUGH_EXCEPTIONS):
+                raise
             raise ILException(exc) from exc
 
     def disconnect(self) -> None:
@@ -428,6 +517,7 @@ class ILQmgr:
             committed = qmgr.commit()   # 두 건이 원자적으로 확정된다
         """
         try:
+            self.txnPending = False
             report_msg = self.service.request(ILC.MIMQ_COMMIT_TRANSACTION_REQUEST)
             if report_msg is None:
                 raise ILOperationException("MIMQE_INTERNAL_ERROR")
@@ -460,6 +550,7 @@ class ILQmgr:
         """
         try:
             self.set_last_access_time()
+            self.txnPending = False
             report_msg = self.service.request(ILC.MIMQ_ROLLBACK_REQUEST)
             if (
                 report_msg is not None
@@ -651,27 +742,110 @@ class ILQmgr:
         return list(self.clusterAddresses) if self.clusterAddresses else None
 
     def set_auto_reconnect(self, value: bool) -> None:
-        """연결이 끊겼을 때 자동으로 재접속할지 정한다. (기본 False)
+        """**더 이상 쓰이지 않는다 - 불러도 아무 일도 일어나지 않는다.**
 
         Args:
-            value (bool): True 면 통신 장애 시 라이브러리가 스스로 재접속을 시도한다.
+            value (bool): 무시된다.
 
-        Warning:
-            **트랜잭션 세션에서는 켜도 동작하지 않는다.** 재접속하면 미커밋
-            트랜잭션이 유실되므로, 예외를 그대로 올려 앱이 트랜잭션을 처음부터
-            다시 수행하게 한다(:meth:`reconnect` 직접 호출은 언제든 가능).
-            자동 커밋 세션이라도 **응답을 못 받은 시점에 재시도하면 중복 put 이
-            생길 수 있다** - 멱등하지 않은 처리라면 주의하라.
+        Note:
+            0.4.4 부터 자동 재접속은 **옵션이 아니라 기본 동작**이다. 접속 때
+            받아 둔 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한
+            put/get 을 페일오버 재접속 후 1회 자동 재시도한다. 다만 **미커밋
+            트랜잭션이 걸려 있으면** 재접속으로 그것이 유실되므로 예외를 그대로
+            올린다 - 앱이 트랜잭션을 처음부터 다시 수행해야 한다.
+
+            메서드 자체는 기존 코드가 깨지지 않도록 남겨 둔 것이다.
+
+            .. deprecated:: 0.4.4
+                자동 재접속은 항상 켜져 있다.
         """
-        self.autoReconnect = bool(value)
+        # no-op : 자동 재접속은 이제 조건부 기본 동작이다(endpoint 목록 + 미커밋 없음).
 
     def is_auto_reconnect(self) -> bool:
-        """자동 재접속이 켜져 있는지. 기본 False.
+        """**항상 True 다.** 0.4.4 부터 자동 재접속은 옵션이 아니다.
 
         Returns:
-            bool: 자동 재접속이 켜져 있는지. 기본 False.
+            bool: 항상 True.
+
+        Note:
+            .. deprecated:: 0.4.4
+                자동 재접속은 항상 켜져 있다.
         """
-        return self.autoReconnect
+        return True
+
+    def set_endpoint_cache_file(self, path: str | None) -> None:
+        """클러스터 endpoint 목록을 남겨 둘 **파일 경로**를 지정한다.
+
+        Args:
+            path (str | None): 파일 경로. None 이면 파일을 쓰지도 읽지도 않는다(기본).
+
+        Note:
+            **접속하기 전에 지정해야 한다.** 지정하면
+
+            * :meth:`connect` 가 설정 주소로 붙지 못했을 때 이 파일의 주소들을
+              **보조 후보**로 써서 한 번 더 시도한다.
+            * 접속에 성공해 서버에서 받은 목록이 달라졌으면 파일을 새로 쓴다.
+
+            설정 주소를 **항상 먼저** 쓴다 - 파일이 낡아 이미 빠진 노드를 담고
+            있어도 정상 경로가 그것 때문에 느려지지 않는다.
+
+            입출력 실패는 **전부 조용히 무시한다.** 캐시 때문에 접속이 깨지면
+            안 되기 때문이다(경로가 없거나 권한이 없어도 그냥 동작한다).
+
+            한 줄에 ``host:port`` 하나씩 적힌 평범한 텍스트라 사람이 열어
+            고쳐도 된다. ``#`` 으로 시작하는 줄은 주석이다.
+
+        Example::
+
+            q = ILQmgr()
+            q.set_endpoint_cache_file("/var/run/myapp/ilink-cluster.txt")
+            q.connect("10.0.0.1", 5000, "APP", True)
+        """
+        self.endpointCacheFile = path
+
+    def setEndpointCacheFile(self, path: str | None) -> None:
+        """:meth:`set_endpoint_cache_file` 의 camelCase 별칭.
+
+        Args:
+            path (str | None): 파일 경로.
+        """
+        self.set_endpoint_cache_file(path)
+
+    def _load_endpoint_cache(self) -> list[str]:
+        # 파일에서 보조 후보를 읽는다. 없거나 못 읽으면 빈 목록.
+        if not self.endpointCacheFile:
+            return []
+        try:
+            out = []
+            with open(self.endpointCacheFile, "r", encoding="utf-8") as fp:
+                for line in fp:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    if line.rfind(":") > 0 and line not in out:
+                        out.append(line)
+            return out
+        except Exception:
+            return []
+
+    def _save_endpoint_cache(self) -> None:
+        # 받은 목록이 파일과 다르면 원자적으로 바꿔 쓴다(임시 파일 + rename).
+        if not self.endpointCacheFile or not self.clusterAddresses:
+            return
+        try:
+            if self._load_endpoint_cache() == list(self.clusterAddresses):
+                return
+            tmp = "%s.%d.tmp" % (self.endpointCacheFile, os.getpid())
+            with open(tmp, "w", encoding="utf-8", newline="\n") as fp:
+                fp.write("# ilink cluster endpoints - 라이브러리가 자동으로 갱신한다\n")
+                for addr in self.clusterAddresses:
+                    fp.write(addr + "\n")
+            os.replace(tmp, self.endpointCacheFile)
+        except Exception:
+            try:
+                os.remove(tmp)
+            except Exception:
+                pass
 
     @staticmethod
     def _extract_leader_hint(exc: Exception) -> str | None:
@@ -714,7 +888,7 @@ class ILQmgr:
                 except Exception:
                     i += 1; continue
                 try:
-                    self.connect(host, port, client_name, auto_commit)
+                    self.connect(host, port, client_name, auto_commit, _allow_redirect=False)
                     return
                 except Exception as exc:
                     last_error = exc
@@ -757,9 +931,26 @@ class ILQmgr:
             candidates.insert(0, last)
         self._connect_any(candidates, self.clientName, self.isAutoCommitFlag)
 
+    @staticmethod
+    def _is_connection_error(exc: BaseException) -> bool:
+        # 자바 ILQueue.isConnectionError 대응 - 원인 사슬에 통신 계열이 있으면 참.
+        t: BaseException | None = exc
+        seen = 0
+        while t is not None and seen < 10:
+            if isinstance(t, (OSError, ILSessionException)):
+                return True
+            t = getattr(t, "__cause__", None)
+            seen += 1
+        return False
+
     def _try_auto_reconnect(self) -> bool:
-        # 통신 장애 시 내부 호출. **오토커밋 + 활성화** 일 때만 시도한다.
-        if not self.autoReconnect or not self.isAutoCommitFlag:
+        # 통신 장애 시 내부 호출. 옵션이 아니라 기본 동작이다.
+        #   접속 때 받아 둔 endpoint 목록이 없으면 갈 곳이 없다(비클러스터/구엔진).
+        #   미커밋 트랜잭션이 걸려 있으면 재접속으로 그것이 유실되므로 예외를 그대로
+        #   올린다 - 앱이 트랜잭션을 처음부터 다시 수행해야 한다.
+        if not self.clusterAddresses:
+            return False
+        if not self.isAutoCommitFlag and self.txnPending:
             return False
         try:
             self.reconnect()
@@ -1243,6 +1434,17 @@ class ILQueue:
         raise TypeError("unsupported message type")
 
     def _put_msg(self, msg: ILDataMsg) -> str:
+        try:
+            return self._put_msg_once(msg)
+        except Exception as exc:
+            # HA-3: 통신 장애 + 오토커밋 세션이면 페일오버 재접속 후 1회 재시도.
+            #   endpoint 목록이 있고 미커밋 트랜잭션이 없을 때만 재접속한다.
+            if ILQmgr._is_connection_error(exc) and self.qmgr._try_auto_reconnect():
+                self.conn = self.qmgr.get_conn()
+                return self._put_msg_once(msg)
+            raise
+
+    def _put_msg_once(self, msg: ILDataMsg) -> str:
         try:
             msg_id = msg.getHeader().getMsgId()
             if msg_id == "":
@@ -1260,6 +1462,11 @@ class ILQueue:
                 if report_msg.getReportMsg().getCode() != ILC.MIMQ_SUCCESSFUL_PUT:
                     raise ILOperationException(report_msg.getReportMsg().getArg2())
             self.qmgr.set_last_access_time()
+            # 트랜잭션 세션이면 이제 **커밋 안 된 작업이 걸려 있다.**
+            #   실패한 연산은 표시하지 않는다 - 세션이 끊기면 서버가 버리므로
+            #   재접속 후 다시 보내도 중복이 생기지 않는다.
+            if not self.qmgr.is_auto_commit():
+                self.qmgr.txnPending = True
             return msg_id
         except _PASSTHROUGH_EXCEPTIONS:
             raise
@@ -1333,6 +1540,11 @@ class ILQueue:
                 if report_msg.getReportMsg().getCode() != ILC.MIMQ_SUCCESSFUL_PUT:
                     raise ILOperationException(report_msg.getReportMsg().getArg2())
             self.qmgr.set_last_access_time()
+            # 트랜잭션 세션이면 이제 **커밋 안 된 작업이 걸려 있다.**
+            #   실패한 연산은 표시하지 않는다 - 세션이 끊기면 서버가 버리므로
+            #   재접속 후 다시 보내도 중복이 생기지 않는다.
+            if not self.qmgr.is_auto_commit():
+                self.qmgr.txnPending = True
             return msg_ids
         except _PASSTHROUGH_EXCEPTIONS:
             raise
@@ -1403,6 +1615,21 @@ class ILQueue:
             msg = q.get("abc-123", MatchOption.MATCH_MSG_ID)     # 메시지 ID 로
             msg = q.get("corr-456", MatchOption.MATCH_CORREL_ID) # 상관 ID 로
         """
+        try:
+            return self._get_once(matchId, option)
+        except ILNoMsgException:
+            raise
+        except Exception as exc:
+            # HA-3: 통신 장애 + 오토커밋 세션이면 페일오버 재접속 후 1회 재시도.
+            #   endpoint 목록이 있고 미커밋 트랜잭션이 없을 때만 재접속한다.
+            if ILQmgr._is_connection_error(exc) and self.qmgr._try_auto_reconnect():
+                self.conn = self.qmgr.get_conn()
+                return self._get_once(matchId, option)
+            raise
+
+    def _get_once(
+        self, matchId: str | None = None, option: MatchOption = MatchOption.NONE
+    ) -> ILDataMsg:
         try:
             ext = None
             if matchId:
@@ -1426,6 +1653,8 @@ class ILQueue:
                 self.qmgr.set_last_access_time()
                 msg = self.conn.recv(timeout)
                 if msg.getType() == ILC.MIMQ_DATA_MESSAGE:
+                    if not self.qmgr.is_auto_commit():
+                        self.qmgr.txnPending = True
                     return msg.getDataMsg()
 
                 if msg.getType() != ILC.MIMQ_REPORT_MESSAGE:
@@ -1500,6 +1729,8 @@ class ILQueue:
                         offset += length
                         temp_msg = ILMsg(ba)
                         data_msgs.append(temp_msg.getDataMsg())
+                    if data_msgs and not self.qmgr.is_auto_commit():
+                        self.qmgr.txnPending = True
                     return data_msgs
 
                 if msg.getType() != ILC.MIMQ_REPORT_MESSAGE:

{jetstream_api-0.4.2 → jetstream_api-0.4.4/jetstream_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.4.2
+Version: 0.4.4
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -137,15 +137,32 @@ print(adm.getTopicList())
 클러스터 큐 관리자에 접속하면 후보 주소를 캐싱해 두었다가, 리더가 바뀌어도 따라갑니다.
 
 ```python
-qmgr.set_auto_reconnect(True)     # auto-commit 세션에서만 동작
-print(qmgr.get_cluster_addresses())
-qmgr.reconnect()                  # 새 리더를 찾아 재접속
+qmgr.connect("10.0.0.1", 5000, "APP", True)   # 주소 하나면 됩니다
+print(qmgr.get_cluster_addresses())           # ['10.0.0.1:5000', '10.0.0.2:5000']
+qmgr.reconnect()                              # 새 리더를 찾아 재접속
+
+# 첫 접속 시점의 장애까지 대비하려면 목록으로 (포트 인자 없음)
+qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
 ```
 
-> `set_auto_reconnect`는 **transacted 세션에서는 동작하지 않습니다.** 미커밋 트랜잭션이
-> 재접속으로 유실되므로, 예외를 받고 앱이 트랜잭션을 처음부터 재수행해야 합니다
-> (`reconnect()` 직접 호출은 가능합니다). auto-commit 세션도 응답 유실 시점의 재시도로
-> **중복 put이 발생할 수 있습니다.**
+접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아 캐싱하므로
+**주소는 하나만 주면 됩니다.** 목록은 첫 접속 시점의 장애까지 대비할 때 씁니다.
+
+### 0.4.4 변경 - 자동 재접속은 옵션이 아니라 기본 동작
+
+캐싱된 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한 put/get 을 페일오버
+재접속 후 **한 번 자동 재시도합니다.** `set_auto_reconnect()` 는 더 이상 필요 없으며,
+불러도 무시됩니다(기존 코드 호환용으로만 남겨 두었습니다).
+
+| 상황 | 동작 |
+|---|---|
+| 미커밋 트랜잭션 **있음** | 예외를 올립니다. 앱이 `reconnect()` 후 트랜잭션을 처음부터 다시 수행 |
+| 미커밋 트랜잭션 **없음** (auto-commit 포함) | 내부에서 재접속 후 1회 재시도 |
+| endpoint 목록 없음 (비클러스터/구엔진) | 예외를 올립니다 - 갈 곳이 없습니다 |
+
+> 재시도는 **at-least-once** 입니다. 서버가 처리한 뒤 응답이 유실된 시점에 재시도하면
+> **중복 put 이 생길 수 있습니다.** 멱등하지 않은 처리라면 메시지 ID 로 중복을 걸러야
+> 합니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
 
 ## 0.4.0 신규 - 관리 연결 하나로 pub/sub
 

{jetstream_api-0.4.2 → jetstream_api-0.4.4}/pyproject.toml

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