jetstream-api 0.6.6__tar.gz → 0.6.7__tar.gz

{jetstream_api-0.6.6 → jetstream_api-0.6.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.6.6
+Version: 0.6.7
 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.6.6 → jetstream_api-0.6.7}/ilink/__init__.py

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.6.6"
+__version__ = "0.6.7"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser
@@ -36,6 +36,7 @@ from .properties import (
     ILSecureFileProperty,
     ILQueueRealTimeInfo,
     ILQueueFlow,
+    ILQmgrDiag,
 )
 
 # --- Exceptions ---

{jetstream_api-0.6.6 → jetstream_api-0.6.7}/ilink/admin.py

@@ -7,6 +7,7 @@ import uuid
 from .common import ILC, ILRC, MatchOption
 from .connectivity import ILRequestHelper
 from .exception import (
+    UnsupportedOperationException,
     ILException,
     ILMsgTypeException,
     ILNoMsgException,
@@ -16,6 +17,7 @@ from .exception import (
 )
 from .msg import ILDataMsg, ILMsg, ILMsgUtil, ILReportMsg, JMSHeader
 from .properties import (
+    ILQmgrDiag,
     ILAccessRuleProperty,
     ILChannelMinorProperty,
     ILChannelProperty,
@@ -53,6 +55,9 @@ _ADMIN_QMGR_TOKEN = object()
 
 # Exception types that should propagate without re-wrapping
 _PASSTHROUGH_EXCEPTIONS = (
+    # 와이어 폭/길이 위반은 호출자가 고칠 수 있는 값 문제다 - 사유를
+    # 그대로 올려 준다. 감싸면 MIMQE_INTERNAL_ERROR 로만 보인다.
+    UnsupportedOperationException,
     ILException, ILOperationException, ILSessionException,
     ILMsgTypeException, ILNoMsgException, ILTimeoutException,
 )
@@ -458,6 +463,97 @@ class ILAdminService:
         except Exception as exc:
             raise ILException(exc) from exc
 
+    def _requireLastDiagSupport(self) -> None:
+        """진단 조회를 지원하지 않는 엔진이면 그 자리에서 실패시킨다.
+
+        Raises:
+            ILOperationException: 엔진이 rev 3380 미만일 때.
+
+        Note:
+            **구엔진에 보내면 예외가 아니라 정상 응답 모양으로 돌아온다.**
+            요청 코드를 모르는 엔진은 ``MIMQE_INVALID_REQ_CODE`` 를 arg2 에 담아
+            주므로, 게이트가 없으면 그 문자열을 "기동 실패 사유" 로 읽게 된다.
+            조용한 오독이라 여기서 막는다.
+        """
+        if 0 < self.revision < ILC.LAST_DIAG_MIN_REVISION:
+            raise ILOperationException(
+                "MIMQE_NOT_SUPPORTED (last diag requires engine rev "
+                f"{ILC.LAST_DIAG_MIN_REVISION}+, current: {self.revision})"
+            )
+
+    def getLastDiag(self, qmgrName: str) -> ILQmgrDiag:
+        """큐 관리자의 **마지막 진단**을 읽는다 - 기동 실패 사유와 대체된 속성.
+
+        ``startQmgrWithStatus`` 가 ``"ERROR"`` 만 돌려주고 **왜** 인지는 알려주지
+        않을 때 쓴다. 사유는 서버 로그에만 있었는데 이 조회로 응용이 받을 수 있다.
+
+        Args:
+            qmgrName (str): 조회할 큐 관리자 이름.
+
+        Returns:
+            ILQmgrDiag: 상태/사유/대체목록. ``state`` 는 ``"NONE"`` /
+            ``"STARTING"`` / ``"ERROR"`` 중 하나다.
+
+        Raises:
+            ILOperationException: 엔진이 rev 3380 미만이거나(지원 안 함),
+                **그 이름의 큐 관리자가 없을 때**(``MIMQE_OBJECT_NOT_FOUND``).
+            ILException: 통신 실패.
+
+        Warning:
+            **사유는 ``state`` 가 ``"ERROR"`` 일 때만 채워진다.** 비어 있다고
+            "실패한 적 없다" 로 읽으면 안 된다 - 엔진이 재시도할 때마다 사유를
+            지우기 때문에, 실패한 큐 관리자도 대부분의 시점에는
+            ``STARTING`` + 빈 사유로 보인다.
+
+            10.10.1.95 (7.0.1.3383) 실측 - 포트를 뺏어 기동을 막은 경우::
+
+                 0.0초  STARTING  (빈값)
+                11.1초  ERROR     MIMQE_PORT_BINDING_ERROR (26385): Address already in use
+                12.1초  STARTING  (빈값)
+                24.2초  ERROR     (같은 사유)
+                37.4초  ERROR     (같은 사유)
+
+            재시도 주기가 약 13초인데 ``ERROR`` 창은 1~2초다. 그래서 **한 번 물어
+            보고 판단하면 안 되고**, 사유가 필요하면 1초 간격으로 한 주기 이상
+            돌아야 한다. 아래 예제가 그 형태다.
+
+        Note:
+            **큐 관리자 전용이다.** 큐/채널/토픽/서비스/프록시/클러스터 이름으로
+            부르면 ``MIMQE_OBJECT_NOT_FOUND`` 다.
+
+            사유가 담기는 것은 **기동 실패**뿐이다. 속성 변경 거부처럼 즉시
+            예외로 돌아오는 실패는 여기 남지 않는다 - 그건 예외를 보면 된다.
+
+            서버가 큐 관리자 단위로 들고 있어서 **연결을 끊고 다시 붙어도 읽힌다.**
+            API 타임아웃으로 끊긴 뒤 재접속해 원인을 확인하는 용도로 쓸 수 있다.
+
+        Example::
+
+            import time
+
+            status = svc.startQmgrWithStatus("QMGR1", 30)
+            if status != "RUNNING":
+                # ERROR 창이 좁으므로 한 주기 동안 훑는다
+                reason = ""
+                for _ in range(15):
+                    d = svc.getLastDiag("QMGR1")
+                    if d.isError():
+                        reason = d.getReason()
+                        break
+                    time.sleep(1)
+                print("기동 실패:", reason or "(사유 미확정)")
+        """
+        self._requireLastDiagSupport()
+        try:
+            res = self.service.request(ILC.MIMQ_GET_LAST_DIAG, qmgrName)
+            if res.getCode() != ILC.MIMQ_SUCCESSFUL_GET_LAST_DIAG:
+                raise ILOperationException(res.getArg2() or "MIMQE_OBJECT_NOT_FOUND")
+            return ILQmgrDiag(res.getArg1(), res.getArg2(), res.getArg3())
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
     def _topic_logger_supported(self) -> bool:
         """접속한 엔진이 큐관리자 속성의 **토픽 로거 구간**을 이해하는지 알려준다.
 
@@ -568,8 +664,8 @@ class ILAdminService:
             )
         try:
             ba = bytearray(ILC.MIMQ_LONG_REQUEST_ARG_LENGTH + len(homePath))
-            ba_merge(qmgrName, ba, 0)
-            ba_merge(homePath, ba, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH)
+            ba_merge(qmgrName, ba, 0, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH)
+            ba_merge(homePath, ba, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH)
             self.service.apply(
                 ILC.MIMQ_SET_MANAGER_HOMEPATH,
                 bytes(ba),
@@ -606,27 +702,30 @@ class ILAdminService:
 
         Warning:
             **값 검증은 엔진이 한다.** 이 API 는 문자열 길이(와이어 폭) 외의 값
-            범위를 검사하지 않으므로, 범위 밖 값을 넣었을 때 무슨 일이 일어나는지는
-            **상대 엔진에 달려 있다.** 아래는 실측 결과다.
+            범위를 검사하지 않는다. 그래서 **범위 밖 숫자를 넘겼을 때 무슨 일이
+            일어나는지는 상대 엔진에 달려 있고, 결과가 셋으로 갈린다.** 셋 다
+            현재 운영 중인 엔진에서 실제로 나온다::
+
+                vo = ILQmgrProperty("QMGR01", 19999)
+                vo.setSendTimeout(999999)   # 범위 밖 (규격 1~864000)
+                svc.createQmgr(vo)
 
-            * **범위 검사층이 있는 엔진은 생성 시 범위 밖 값을 거부한다**
-              (``MIMQE_INVALID_PROPERTY``). 숫자 설정값이든 이름·포트 같은 신원
-              항목이든 마찬가지다 - 생성 경로는 저장값과 대조하지 않고 범위만 본다::
+                # 7.0.1.3367 -> ILOperationException
+                #     MIMQE_INVALID_PROPERTY (SOCKTIMEOUTSND must be 1~864000 sec)
+                # 7.0.1.3375 -> 성공. 저장값은 조용히 60 이 된다
+                # 6.3.1 / 6.3.4 -> 성공. 저장값은 999999 그대로다
 
-                  vo = ILQmgrProperty("QMGR01", 19999)
-                  vo.setSendTimeout(999999)   # 범위 밖 (1~864000)
-                  svc.createQmgr(vo)
-                  # 7.0.1.3367 -> ILOperationException
-                  #   MIMQE_INVALID_PROPERTY (SOCKTIMEOUTSND must be 1~864000 sec)
+            **그러므로 예외가 없다고 넘긴 값이 들어간 것이 아니다.** 어느 엔진이든
+            안전한 절차는 하나다 - 만든 뒤 :meth:`getQmgrProperty` 로 되읽어
+            값을 확인한다.
 
-            * **그 검사층이 없는 구엔진에서는 범위 밖 값이 그대로 저장된다.**
-              위와 같은 호출이 6.3.1 / 6.3.4 에서는 오류 없이 성공하고 저장값도
-              999999 가 된다. **조용히 잘못된 값으로 도는 쪽은 구엔진이므로**,
-              만든 뒤 :meth:`getQmgrProperty` 로 되읽어 확인한다.
+            이름·포트 같은 **신원 항목은 세 엔진 모두에서 거부된다**(규격 밖 포트는
+            어느 빌드에서도 만들어지지 않는다). 그래서 만든 뒤 봐야 할 것은 신원
+            항목이 아니라 **숫자 설정값** 쪽이다.
 
-            :meth:`setQmgrProperty` (변경)는 판정 기준이 다르다. 검사층이 있는
-            엔진은 **저장값과 대조**해서, 손대지 않은 왕복은 통과시키고 범위 밖
-            **새** 값만 거부한다 - 구엔진 설정 이관이 막히지 않게 하려는 것이다.
+            :meth:`setQmgrProperty` (변경)는 기준이 다르다. 검사층이 있는 엔진은
+            **저장값과 대조**해서 손대지 않은 왕복은 통과시키고 범위 밖 **새** 값은
+            거부한다 - 구엔진 설정 이관이 막히지 않게 하려는 것이다.
 
         Note:
             만든 뒤 :meth:`startQmgr` 로 기동해야 접속할 수 있다.
@@ -1322,12 +1421,21 @@ class ILAdminService:
 
         Args:
             qmgrName (str): 기동할 큐 관리자 이름.
-            timeout (int): 최대 대기 **초**. 기본 60.
+            timeout (int): 최대 대기 **초**. 1초 간격으로 상태를 확인하며 그
+                횟수가 이 값이다. **밀리초가 아니다** - 30000 을 넘기면 8시간
+                넘게 매달린다. 보통 10~60 이면 충분하다.
 
         Returns:
             str: 최종 상태 문자열. **전부 대문자**다 - ``"RUNNING"`` / ``"ERROR"``,
             시간이 다하면 그 시점의 상태(``"STARTING"`` 등).
-            **예외가 아니라 문자열로 결과를 알린다** - 값을 반드시 확인하라.
+
+            **실패는 두 가지 방식으로 온다 - 둘 다 대비한다.**
+
+            * 엔진이 기동 실패 사유를 제때 올리면 :class:`ILOperationException`
+              이 난다(사유가 메시지에 실린다).
+            * 사유가 제때 안 올라오면 예외 없이 ``"ERROR"`` 나 그 시점의 상태
+              문자열이 돌아온다. 그래서 **반환값을 반드시 확인해야 한다** -
+              예외가 없다고 기동에 성공한 것이 아니다.
 
         Raises:
             ILOperationException: 기동 요청 자체가 거절됐을 때.
@@ -1388,7 +1496,9 @@ class ILAdminService:
 
         Args:
             qmgrName (str): 정지할 큐 관리자 이름.
-            timeout (int): 최대 대기 **초**. 기본 60.
+            timeout (int): 최대 대기 **초**. 1초 간격으로 상태를 확인하며 그
+                횟수가 이 값이다. **밀리초가 아니다** - 30000 을 넘기면 8시간
+                넘게 매달린다. 보통 10~60 이면 충분하다.
 
         Returns:
             str: 최종 상태 문자열. **전부 대문자**다 - ``"STOPPED"`` / ``"ERROR"``,
@@ -1518,8 +1628,8 @@ class ILAdminService:
         """
         try:
             ba = bytearray(256)
-            ba_merge(keyFileName, ba, 0)
-            ba_merge(password, ba, 128)
+            ba_merge(keyFileName, ba, 0, 128)
+            ba_merge(password, ba, 128, 128)
             self.service.apply(
                 ILC.MIMQ_SET_KEY_PASSWORD,
                 bytes(ba),
@@ -2340,9 +2450,9 @@ class ILAdminService:
                 content = fileContent
             ba = bytearray(len(content) + ILC.ILINKBYTE256)
             offset = 0
-            ba_merge(fileName, ba, offset)
+            ba_merge(fileName, ba, offset, 128)
             offset += 128
-            ba_merge(password, ba, offset)
+            ba_merge(password, ba, offset, 128)
             offset += 128
             ba[offset : offset + len(content)] = content
             self.service.apply(
@@ -2777,8 +2887,8 @@ class ILAdminQmgr:
             )
         try:
             ba = bytearray(ILC.MIMQ_LONG_REQUEST_ARG_LENGTH + len(homePath))
-            ba_merge(self.qmgrName, ba, 0)
-            ba_merge(homePath, ba, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH)
+            ba_merge(self.qmgrName, ba, 0, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH)
+            ba_merge(homePath, ba, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH)
             self.service.apply(
                 ILC.MIMQ_SET_MANAGER_HOMEPATH,
                 bytes(ba),
@@ -5119,12 +5229,12 @@ class ILAdminQmgr:
             )
             buffer = bytearray(buflen)
             offset = 0
-            ba_merge(queueName, buffer, offset)
+            ba_merge(queueName, buffer, offset, ILC.MIMQ_LONG_REQUEST_ARG_LENGTH)
             offset += ILC.MIMQ_LONG_REQUEST_ARG_LENGTH
-            ba_merge(len(msg_ids), buffer, offset)
+            ba_merge(len(msg_ids), buffer, offset, ILC.SZ_LEN)
             offset += ILC.SZ_LEN
             for msg_id in msg_ids:
-                ba_merge(msg_id, buffer, offset)
+                ba_merge(msg_id, buffer, offset, ILC.ILINKBYTE48)
                 offset += ILC.ILINKBYTE48
             self.service.apply(
                 self.qmgrName,

{jetstream_api-0.6.6 → jetstream_api-0.6.7}/ilink/common.py

@@ -742,6 +742,18 @@ class ILC:
     #: 그 자리는 구엔진의 ``volumeMonitorForceReloadSize`` 다 - 값을 실어 보내면
     #: 구엔진 imqlsr 가 SIGFPE 로 죽는다(6.3.1.2813 실측).
     TOPIC_LOGGER_MIN_REVISION = 3283
+
+    #: ``getLastDiag`` 가 쓰는 진단 조회(3394)가 들어온 엔진 리비전.
+    #: 그 미만 엔진은 이 코드를 모르고 ``MIMQE_INVALID_REQ_CODE`` 를
+    #: **정상 응답 모양으로** 돌려주므로, 예외가 아니라 조용한 오독이 된다.
+    LAST_DIAG_MIN_REVISION = 3380
+
+    #: 큐 관리자 마지막 진단 조회 요청 코드.
+    MIMQ_GET_LAST_DIAG = 3394
+    #: 진단 조회 성공 응답 코드.
+    MIMQ_SUCCESSFUL_GET_LAST_DIAG = 4276
+    #: 진단 조회 실패 응답 코드(없는 큐 관리자 등).
+    MIMQ_NOT_SUCCESSFUL_GET_LAST_DIAG = 4277
     #: 구버전(4096) 블롭에서 공통 접두가 끝나고 레이아웃이 갈리는 지점.
     QUEUE_LEGACY_DIVERGE_OFFSET = 1772
     #: 구버전(4096) 블롭에서 incomingDelayDepth 가 있는 위치. 현행과 같다.