jetstream-api 0.4.3__tar.gz → 0.4.5__tar.gz

{jetstream_api-0.4.3 → jetstream_api-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.4.3
+Version: 0.4.5
 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,141 @@ 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)
+```
+
+접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아 캐싱하므로
+**주소는 하나만 주면 됩니다.** 목록은 첫 접속 시점의 장애까지 대비할 때 씁니다.
+
+### 0.4.4 변경 - 자동 재접속은 옵션이 아니라 기본 동작
+
+캐싱된 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한 put/get 을 페일오버
+재접속 후 **한 번 자동 재시도합니다.** `set_auto_reconnect()` 는 더 이상 필요 없으며,
+불러도 무시됩니다(기존 코드 호환용으로만 남겨 두었습니다).
+
+| 상황 | 동작 |
+|---|---|
+| 미커밋 트랜잭션 **있음** | 예외를 올립니다. 앱이 `reconnect()` 후 트랜잭션을 처음부터 다시 수행 |
+| 미커밋 트랜잭션 **없음** (auto-commit 포함) | 내부에서 재접속 후 1회 재시도 |
+| endpoint 목록 없음 (비클러스터/구엔진) | 예외를 올립니다 - 갈 곳이 없습니다 |
+
+> 재시도는 **at-least-once** 입니다. 서버가 처리한 뒤 응답이 유실된 시점에 재시도하면
+> **중복 put 이 생길 수 있습니다.** 재시도는 같은 msgId 로 나가므로 수신측에서 메시지 ID
+> 로 걸러낼 수 있습니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
+
+### 장애 전환(failover) 시 앱이 해야 할 일
+
+리더가 죽으면 새 리더가 뽑힐 때까지 **아무도 접속을 받지 않습니다.** 실측(2노드 클러스터,
+엔진 7.0.1.3341) **약 15~20초**가 걸립니다. 그 사이의 재접속 시도는 정상적으로 실패하므로,
+**한 번 실패했다고 끝내지 말고 재시도**해야 합니다.
+
+세션 종류에 따라 앱이 할 일이 갈립니다.
+
+| 세션 | 실패 시점에 미커밋 | 앱이 할 일 |
+|---|---|---|
+| auto-commit | 없음 | **아무것도 안 해도 됩니다.** 그 연산을 다시 부르기만 하면 라이브러리가 재접속·재시도합니다 |
+| transacted | 없음 | 위와 같습니다 |
+| transacted | 있음 | `reconnect()` 로 자리를 옮기고 **트랜잭션을 처음부터 다시** 수행해야 합니다 |
+
+`access_queue()` 는 **자동 재접속 대상이 아닙니다.** 끊긴 세션에서 부르면 그대로 실패하니,
+재접속에 성공한 **뒤에** 핸들을 다시 얻으십시오. 기존 핸들을 계속 쓰는 쪽은 스스로 복구됩니다.
+
+#### (1) 트랜잭션 재수행이 필요 없는 경우 — auto-commit
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")   # 재기동 대비(선택)
+q.connect("10.0.0.1", 5000, "collector", True)                    # auto-commit
+queue = q.access_queue("APP.EVENTS")                              # 핸들은 한 번만 얻는다
+
+def publish(payload):
+    """페일오버가 나도 이 함수는 그대로 둔다 - 라이브러리가 복구한다."""
+    for attempt in range(1, 11):
+        try:
+            return queue.put(payload)          # 실패하면 내부에서 재접속 + 1회 재시도
+        except ILOperationException:
+            raise                              # 서버가 거절 - 재시도해도 같다
+        except (ILException, ILSessionException):
+            if attempt == 10:
+                raise                          # 승격이 20초 넘게 안 끝났다
+            time.sleep(3)                      # 리더 승격을 기다렸다가 다시
+```
+
+앱 코드에 `reconnect()` 가 없다는 점이 요지입니다. 같은 큐 핸들로 `put` 을 다시 부르기만
+하면, 승격이 끝난 시점의 호출이 새 리더에 붙어 성공합니다(실측 20.6초에 복구).
+
+#### (2) 트랜잭션 재수행이 필요한 경우 — transacted
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+MAX_RETRY = 10
+
+def process_batch(records):
+    """한 번의 트랜잭션 = 전부 커밋되거나 전부 없던 일이 된다."""
+    q = ILQmgr()
+    q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+    q.connect("10.0.0.1", 5000, "billing-svc", False)      # transacted
+    try:
+        for attempt in range(1, MAX_RETRY + 1):
+            try:
+                queue = q.access_queue("APP.ORDERS")       # 재접속 뒤 핸들을 다시 얻는다
+                for rec in records:
+                    queue.put(rec)
+                q.commit()                                 # 여기까지 와야 확정된다
+                return
+            except ILOperationException:
+                q.rollback()                               # 서버 거절 - 재시도 무의미
+                raise
+            except (ILException, ILSessionException):
+                if attempt == MAX_RETRY:
+                    raise
+                try:
+                    q.reconnect()                          # 승격 전이면 여기서 또 실패한다
+                except Exception:
+                    time.sleep(3)                          # 기다렸다가 다음 회차에 다시
+                # 루프 처음으로 -> 배치 전체를 다시 넣는다
+    finally:
+        q.disconnect()
 ```
 
-> `set_auto_reconnect`는 **transacted 세션에서는 동작하지 않습니다.** 미커밋 트랜잭션이
-> 재접속으로 유실되므로, 예외를 받고 앱이 트랜잭션을 처음부터 재수행해야 합니다
-> (`reconnect()` 직접 호출은 가능합니다). auto-commit 세션도 응답 유실 시점의 재시도로
-> **중복 put이 발생할 수 있습니다.**
+읽어야 할 포인트 셋입니다.
+
+1. **재시도 단위는 트랜잭션 전체**입니다. 실패 지점부터 이어붙이면 안 됩니다 — 앞서 넣은
+   것들도 커밋되지 않았으므로 함께 사라집니다(실측: 미커밋 1건 유실, 재수행 후 depth 2 정상).
+2. **`reconnect()` 자체가 실패할 수 있습니다.** 승격 전에 부르면 실패하는 게 정상이라,
+   루프 안에서 간격을 두고 다시 불러야 합니다(실측 2번째 시도, 16.5초에 성공).
+3. **`ILOperationException` 과 통신 예외를 갈라 잡습니다.** 전자는 서버가 판단해 거절한
+   것이라 재시도가 무의미하고, 후자만 재접속 대상입니다. 파이썬의 예외 클래스는 평면
+   구조라 `ILSessionException` 은 `ILException` 의 하위 타입이 **아닙니다** — 통신 장애를
+   잡으려면 **둘 다** 적어야 합니다(자바는 모두 `ILException` 으로 감싸므로 하나면 됩니다).
+
+#### 앱이 재기동되는 경우
+
+캐싱은 메모리에만 있으므로 프로세스가 죽으면 사라집니다. 설정에 남은 옛 리더 주소로 다시
+붙을 때 이렇게 갈립니다.
+
+| 옛 리더의 상태 | 결과 |
+|---|---|
+| 살아 있고 **팔로워로 강등** | 그 노드가 리더 힌트를 주므로 **자동으로 새 리더에 접속** |
+| **죽어 있음** | 갈 곳이 없어 실패 — `set_endpoint_cache_file()` 을 쓰거나 주소를 목록으로 주십시오 |
+
+```python
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+q.connect("10.0.0.1", 5000, "APP", True)   # 이 주소가 죽어 있어도 파일 후보로 붙는다
+```
 
 ## 0.4.0 신규 - 관리 연결 하나로 pub/sub
 

{jetstream_api-0.4.3 → jetstream_api-0.4.5}/README.md

@@ -91,15 +91,141 @@ 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)
+```
+
+접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아 캐싱하므로
+**주소는 하나만 주면 됩니다.** 목록은 첫 접속 시점의 장애까지 대비할 때 씁니다.
+
+### 0.4.4 변경 - 자동 재접속은 옵션이 아니라 기본 동작
+
+캐싱된 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한 put/get 을 페일오버
+재접속 후 **한 번 자동 재시도합니다.** `set_auto_reconnect()` 는 더 이상 필요 없으며,
+불러도 무시됩니다(기존 코드 호환용으로만 남겨 두었습니다).
+
+| 상황 | 동작 |
+|---|---|
+| 미커밋 트랜잭션 **있음** | 예외를 올립니다. 앱이 `reconnect()` 후 트랜잭션을 처음부터 다시 수행 |
+| 미커밋 트랜잭션 **없음** (auto-commit 포함) | 내부에서 재접속 후 1회 재시도 |
+| endpoint 목록 없음 (비클러스터/구엔진) | 예외를 올립니다 - 갈 곳이 없습니다 |
+
+> 재시도는 **at-least-once** 입니다. 서버가 처리한 뒤 응답이 유실된 시점에 재시도하면
+> **중복 put 이 생길 수 있습니다.** 재시도는 같은 msgId 로 나가므로 수신측에서 메시지 ID
+> 로 걸러낼 수 있습니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
+
+### 장애 전환(failover) 시 앱이 해야 할 일
+
+리더가 죽으면 새 리더가 뽑힐 때까지 **아무도 접속을 받지 않습니다.** 실측(2노드 클러스터,
+엔진 7.0.1.3341) **약 15~20초**가 걸립니다. 그 사이의 재접속 시도는 정상적으로 실패하므로,
+**한 번 실패했다고 끝내지 말고 재시도**해야 합니다.
+
+세션 종류에 따라 앱이 할 일이 갈립니다.
+
+| 세션 | 실패 시점에 미커밋 | 앱이 할 일 |
+|---|---|---|
+| auto-commit | 없음 | **아무것도 안 해도 됩니다.** 그 연산을 다시 부르기만 하면 라이브러리가 재접속·재시도합니다 |
+| transacted | 없음 | 위와 같습니다 |
+| transacted | 있음 | `reconnect()` 로 자리를 옮기고 **트랜잭션을 처음부터 다시** 수행해야 합니다 |
+
+`access_queue()` 는 **자동 재접속 대상이 아닙니다.** 끊긴 세션에서 부르면 그대로 실패하니,
+재접속에 성공한 **뒤에** 핸들을 다시 얻으십시오. 기존 핸들을 계속 쓰는 쪽은 스스로 복구됩니다.
+
+#### (1) 트랜잭션 재수행이 필요 없는 경우 — auto-commit
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")   # 재기동 대비(선택)
+q.connect("10.0.0.1", 5000, "collector", True)                    # auto-commit
+queue = q.access_queue("APP.EVENTS")                              # 핸들은 한 번만 얻는다
+
+def publish(payload):
+    """페일오버가 나도 이 함수는 그대로 둔다 - 라이브러리가 복구한다."""
+    for attempt in range(1, 11):
+        try:
+            return queue.put(payload)          # 실패하면 내부에서 재접속 + 1회 재시도
+        except ILOperationException:
+            raise                              # 서버가 거절 - 재시도해도 같다
+        except (ILException, ILSessionException):
+            if attempt == 10:
+                raise                          # 승격이 20초 넘게 안 끝났다
+            time.sleep(3)                      # 리더 승격을 기다렸다가 다시
+```
+
+앱 코드에 `reconnect()` 가 없다는 점이 요지입니다. 같은 큐 핸들로 `put` 을 다시 부르기만
+하면, 승격이 끝난 시점의 호출이 새 리더에 붙어 성공합니다(실측 20.6초에 복구).
+
+#### (2) 트랜잭션 재수행이 필요한 경우 — transacted
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+MAX_RETRY = 10
+
+def process_batch(records):
+    """한 번의 트랜잭션 = 전부 커밋되거나 전부 없던 일이 된다."""
+    q = ILQmgr()
+    q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+    q.connect("10.0.0.1", 5000, "billing-svc", False)      # transacted
+    try:
+        for attempt in range(1, MAX_RETRY + 1):
+            try:
+                queue = q.access_queue("APP.ORDERS")       # 재접속 뒤 핸들을 다시 얻는다
+                for rec in records:
+                    queue.put(rec)
+                q.commit()                                 # 여기까지 와야 확정된다
+                return
+            except ILOperationException:
+                q.rollback()                               # 서버 거절 - 재시도 무의미
+                raise
+            except (ILException, ILSessionException):
+                if attempt == MAX_RETRY:
+                    raise
+                try:
+                    q.reconnect()                          # 승격 전이면 여기서 또 실패한다
+                except Exception:
+                    time.sleep(3)                          # 기다렸다가 다음 회차에 다시
+                # 루프 처음으로 -> 배치 전체를 다시 넣는다
+    finally:
+        q.disconnect()
 ```
 
-> `set_auto_reconnect`는 **transacted 세션에서는 동작하지 않습니다.** 미커밋 트랜잭션이
-> 재접속으로 유실되므로, 예외를 받고 앱이 트랜잭션을 처음부터 재수행해야 합니다
-> (`reconnect()` 직접 호출은 가능합니다). auto-commit 세션도 응답 유실 시점의 재시도로
-> **중복 put이 발생할 수 있습니다.**
+읽어야 할 포인트 셋입니다.
+
+1. **재시도 단위는 트랜잭션 전체**입니다. 실패 지점부터 이어붙이면 안 됩니다 — 앞서 넣은
+   것들도 커밋되지 않았으므로 함께 사라집니다(실측: 미커밋 1건 유실, 재수행 후 depth 2 정상).
+2. **`reconnect()` 자체가 실패할 수 있습니다.** 승격 전에 부르면 실패하는 게 정상이라,
+   루프 안에서 간격을 두고 다시 불러야 합니다(실측 2번째 시도, 16.5초에 성공).
+3. **`ILOperationException` 과 통신 예외를 갈라 잡습니다.** 전자는 서버가 판단해 거절한
+   것이라 재시도가 무의미하고, 후자만 재접속 대상입니다. 파이썬의 예외 클래스는 평면
+   구조라 `ILSessionException` 은 `ILException` 의 하위 타입이 **아닙니다** — 통신 장애를
+   잡으려면 **둘 다** 적어야 합니다(자바는 모두 `ILException` 으로 감싸므로 하나면 됩니다).
+
+#### 앱이 재기동되는 경우
+
+캐싱은 메모리에만 있으므로 프로세스가 죽으면 사라집니다. 설정에 남은 옛 리더 주소로 다시
+붙을 때 이렇게 갈립니다.
+
+| 옛 리더의 상태 | 결과 |
+|---|---|
+| 살아 있고 **팔로워로 강등** | 그 노드가 리더 힌트를 주므로 **자동으로 새 리더에 접속** |
+| **죽어 있음** | 갈 곳이 없어 실패 — `set_endpoint_cache_file()` 을 쓰거나 주소를 목록으로 주십시오 |
+
+```python
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+q.connect("10.0.0.1", 5000, "APP", True)   # 이 주소가 죽어 있어도 파일 후보로 붙는다
+```
 
 ## 0.4.0 신규 - 관리 연결 하나로 pub/sub
 

{jetstream_api-0.4.3 → jetstream_api-0.4.5}/ilink/__init__.py

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

{jetstream_api-0.4.3 → jetstream_api-0.4.5}/ilink/admin.py

@@ -2989,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:
@@ -3097,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:
         """큐 하나의 전체 속성을 조회한다(종류 무관).
 
@@ -3258,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:
@@ -3442,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` 를 쓰라. 그쪽은
+            적재 주기와 무관하게 현재 값을 준다.
 
-            유량 집계 테이블은 **주기적으로 갱신**된다. 큐를 만든 직후에는 아직
-            등록되지 않아 ``MIMQE_OBJECT_NOT_FOUND`` 가 나고, **약 1분 뒤부터**
-            정상 조회된다(실서버 확인: 생성 직후 실패 -> 35초 뒤 성공).
-            put/get 을 해도 앞당겨지지 않는다. **서버 동작이라 클라이언트에서
-            우회할 수 없다** - 방금 만든 큐의 현황은 :meth:`getQueueRealTimeInfo`
-            로 보라(이쪽은 즉시 조회된다).
+            **엔진 r3336 미만에서는 갓 만든 큐가 최대 1초간 조회되지 않는다** -
+            첫 적재 전까지 ``MIMQE_OBJECT_NOT_FOUND`` 가 난다(r3335 실측
+            0.1~1.1초, 단건·배열 50회). put/get 을 해도 앞당겨지지 않는다.
+
+            .. versionchanged:: 0.1.6
+                이전 문서는 "유량 테이블은 주기적(약 1분) 갱신"이라고 적었으나
+                **사실이 아니다**. 실서버에서 관측된 35초 지연은 적재 주기가
+                아니라 **적재 스레드가 분 단위 통계 리포트에 붙들려 있던 것**으로,
+                엔진 r3331 통계 컴팩션으로 해소됐다.
+
+            .. 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
@@ -3495,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` 를 쓰라. 그쪽은
+            적재 주기와 무관하게 현재 값을 준다.
 
-            유량 집계 테이블은 **주기적으로 갱신**된다. 큐를 만든 직후에는 아직
-            등록되지 않아 ``MIMQE_OBJECT_NOT_FOUND`` 가 나고, **약 1분 뒤부터**
-            정상 조회된다(실서버 확인: 생성 직후 실패 -> 35초 뒤 성공).
-            put/get 을 해도 앞당겨지지 않는다. **서버 동작이라 클라이언트에서
-            우회할 수 없다** - 방금 만든 큐의 현황은 :meth:`getQueueRealTimeInfo`
-            로 보라(이쪽은 즉시 조회된다).
+            **엔진 r3336 미만에서는 갓 만든 큐가 최대 1초간 조회되지 않는다** -
+            첫 적재 전까지 ``MIMQE_OBJECT_NOT_FOUND`` 가 난다(r3335 실측
+            0.1~1.1초, 단건·배열 50회). put/get 을 해도 앞당겨지지 않는다.
+
+            .. 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
@@ -4885,6 +4968,15 @@ class ILAdminQmgr:
         Note:
             **누가 언제 마지막으로 이 큐를 건드렸는지** 알 수 있어 소비자가
             멈춘 상황을 진단할 때 유용하다.
+
+        .. note:: 구엔진(6.3.3 미만)에 붙었을 때
+
+            그 시절 엔진은 이 요청에 **큐 속성 블롭을 통째로** 답한다. 사용 현황
+            통계가 속성 안에 들어 있었기 때문이다. 클라이언트가 알아서 판별해
+            같은 필드를 채우므로 호출부는 달라질 게 없다. 다만
+            :attr:`~ilink.properties.ILQueueRealTimeInfo.partitions` 는 **빈
+            목록**이다 - 파티셔닝은 6.3.3 에서 들어온 기능이라 구엔진 큐에는
+            파티션이라는 개념 자체가 없다.
         """
         try:
             res_msg = self.service.inquire(
@@ -4892,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.3 → jetstream_api-0.4.5}/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.3 → jetstream_api-0.4.5}/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: