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

{jetstream_api-0.4.1/jetstream_api.egg-info → jetstream_api-0.4.3}/PKG-INFO

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

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.3"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser
@@ -26,6 +26,7 @@ from .properties import (
     ILChannelSecurity,
     ILChannelBalanceMode,
     ILClusterNode,
+    ILClusterControlResult,
     ILClusterProperty,
     ILQmgrProperty,
     ILSessionProperty,
@@ -75,6 +76,7 @@ __all__ = [
     "ILChannelSecurity",
     "ILChannelBalanceMode",
     "ILClusterNode",
+    "ILClusterControlResult",
     "ILClusterProperty",
     "ILQmgrProperty",
     "ILSessionProperty",

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

@@ -22,6 +22,7 @@ from .properties import (
     ILChannelStatus,
     ILChannelType,
     ILChannelDirection,
+    ILClusterControlResult,
     ILClusterNode,
     ILClusterProperty,
     ILQmgrMinorProperty,
@@ -704,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:
@@ -721,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`` 에 머물고
@@ -867,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")
@@ -895,7 +946,11 @@ class ILAdminService:
             port (int): **큐 관리자 리스너 포트**(ilcc 포트가 아니다).
 
         Raises:
-            ILOperationException: 조회나 반영이 거절됐을 때.
+            ILOperationException: 조회나 반영이 거절됐을 때. **같은 ``host:port``
+                노드가 이미 있으면 거절된다** - 한 큐 관리자를 두 노드로 등록하는
+                셈이기 때문이다(``MIMQE_ALREADY_EXIST`` 로 이 라이브러리가 먼저 막고,
+                블롭을 직접 만들어 보내도 서버가 ``MIMQE_INVALID_ARGUMENT`` 로
+                거절한다 - **엔진 rev 3323+**).
             ILException: 통신 실패.
 
         Warning:
@@ -946,26 +1001,165 @@ class ILAdminService:
         self.setClusterProperty(vo)
         return True
 
-    def startCluster(self, clusterName: str) -> None:
-        """ilcc 프로세스를 기동한다. 이미 떠 있으면 실패한다."""
+    def _clusterNodesArg(self, withNodes: bool) -> str:
+        """START/STOP CLUSTER 의 arg3 를 만든다.
+
+        Args:
+            withNodes (bool): 엮인 큐 관리자까지 제어할지.
+
+        Returns:
+            str: 기본이면 ``""``, 조정자만 다루면 ``"N"``.
+
+        Raises:
+            ILOperationException: ``withNodes=False`` 인데 엔진이 **rev 3315 미만**일 때.
+
+        Note:
+            구엔진은 이 인자를 **조용히 무시하고 큐 관리자까지 내린다.** 침묵하는
+            옵션은 "안 내린다"고 믿게 만들어 옵션이 없는 것보다 나쁘므로, 보내기 전에
+            막는다. 판정을 ``0 < revision`` 으로 한정한 이유는 버전 문자열을 파싱하지
+            못했을 때 정상 엔진에서 기능이 조용히 사라지지 않게 하기 위해서다.
+        """
+        if withNodes:
+            return ""
+        if 0 < self.revision < ILC.CLUSTER_NO_NODES_MIN_REVISION:
+            raise ILOperationException(
+                "MIMQE_NOT_SUPPORTED (withNodes=False requires engine rev "
+                f"{ILC.CLUSTER_NO_NODES_MIN_REVISION}+, current: {self.revision})"
+            )
+        return ILC.MIMQ_CLUSTER_NO_NODES
+
+    def startCluster(self, clusterName: str,
+                     withNodes: bool = True) -> "ILClusterControlResult":
+        """클러스터를 기동한다 - 기본은 **ilcc 와 엮인 큐 관리자를 함께** 올린다.
+
+        Args:
+            clusterName (str): 기동할 클러스터 이름.
+            withNodes (bool): 엮인 큐 관리자까지 함께 기동할지. 기본 True.
+                ``False`` 면 조정자(ilcc)만 올리고 데이터 평면은 건드리지 않는다.
+                **엔진 rev 3315 이상**에서만 쓸 수 있다.
+
+        Returns:
+            ILClusterControlResult: 제어된 노드 수와 **빠진 노드 목록**.
+                ``getSkipped()`` 이 0 이 아니면 일부 노드가 처리되지 않은 것이다.
+                엔진 rev 3317 미만은 집계를 싣지 않으므로 ``known`` 이 False 로 온다.
+
+        Raises:
+            ILOperationException: 이미 떠 있을 때(``MIMQE_CLUSTER_NOT_STOPPED``),
+                그런 클러스터가 없을 때, ``withNodes=False`` 인데 엔진이 rev 3315
+                미만일 때(``MIMQE_NOT_SUPPORTED``).
+            ILException: 통신 실패.
+
+        Warning:
+            **기본값은 조정자만 올리는 게 아니다.** 노드 목록에 있는 큐 관리자 중
+            **이 서비스 소관인 것**을 함께 기동한다(엔진 rev 3309+). 다른 서비스
+            소관 노드는 전파받은 그쪽 서비스가 올린다. "클러스터를 켠다 = 데이터
+            평면까지 켠다"는 뜻이라 그렇다.
+
+        .. warning:: 성공 반환이 "전부 떴다"는 뜻이 아니다
+
+            노드 제어는 **최선 노력**이라 일부가 빠져도 이 호출은 성공을 돌려준다.
+            빠진 노드는 반환값 :class:`ILClusterControlResult` 로 알려 주므로
+            **반드시 확인하라**(엔진 rev 3317+). 빠지는 경우는 이렇다.
+
+            - 개별 노드 제어가 실패했다(그 서비스가 로그를 남기고 다음 노드로 넘어간다).
+            - 다른 서비스 소관 노드인데 **전파가 닿지 못했다.** 그쪽 노드는 그대로 남는다.
+
+            큐 관리자 이름이 빈 노드도 제어 대상에서 빠지는데, 엔진 **rev 3319 부터
+            그런 노드는 애초에 저장이 거부**되므로 새로 만든 클러스터에서는 생기지
+            않는다. rev 3319 이전에 등록된 레거시 노드가 남아 있다면
+            :meth:`removeClusterNode` 후 :meth:`addClusterNode` 로 이름을 채워야 한다.
+
+            ::
+
+                r = svc.startCluster("CC1")
+                if r.getSkipped():
+                    print("제어 대상에서 빠진 노드:", r.getSkippedNodes())
+                print("제어한 노드 %d개" % r.getControlled())
+
+        Note:
+            요청만 보내고 돌아온다. 상태는 :meth:`getClusterProperty` 로 확인하라.
+
+        Example::
+
+            svc.startCluster("CC1")                     # 큐 관리자까지 함께
+            svc.startCluster("CC1", withNodes=False)    # 조정자(ilcc)만
+
+            for _ in range(30):
+                if svc.getClusterProperty("CC1").get_status_string() == "RUNNING":
+                    break
+                time.sleep(0.5)
+        """
         try:
             self._checkClusterSupported()
-            self.service.request(
+            res = self.service.request(
                 ILC.MIMQ_START_CLUSTER,
-                ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION,
                 clusterName,
+                "",
+                self._clusterNodesArg(withNodes),
             )
+            if res is None or res.getCode() != ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION:
+                raise ILOperationException(
+                    res.getArg1() if res is not None else "no response")
+            return ILClusterControlResult(res.getArg1(), res.getArg2(), res.getArg3())
         except _PASSTHROUGH_EXCEPTIONS:
             raise
         except Exception as exc:
             raise ILException(exc) from exc
 
-    def stopCluster(self, clusterName: str) -> None:
-        """ilcc 프로세스를 정지한다.
+    def stopCluster(self, clusterName: str,
+                    withNodes: bool = True) -> "ILClusterControlResult":
+        """클러스터를 정지한다 - 기본은 **ilcc 와 엮인 큐 관리자를 함께** 내린다.
+
+        Args:
+            clusterName (str): 정지할 클러스터 이름.
+            withNodes (bool): 엮인 큐 관리자까지 함께 정지할지. 기본 True.
+                ``False`` 면 조정자(ilcc)만 내리고 **데이터 평면은 살려 둔다.**
+                **엔진 rev 3315 이상**에서만 쓸 수 있다.
+
+        Returns:
+            ILClusterControlResult: 제어된 노드 수와 **빠진 노드 목록**.
+                ``getSkipped()`` 이 0 이 아니면 일부 노드가 처리되지 않은 것이다.
+                엔진 rev 3317 미만은 집계를 싣지 않으므로 ``known`` 이 False 로 온다.
+
+        Raises:
+            ILOperationException: ``withNodes=False`` 인데 엔진이 rev 3315 미만일 때
+                (``MIMQE_NOT_SUPPORTED``).
+            ILException: 통신 실패.
 
         미기동 상태에서 호출해도 성공이다(큐관리자 STOP 관례와 같다).
         정지 후에는 서비스 자동 기동 대상에서도 빠진다 - startCluster 로 되살린다.
 
+        .. warning:: 기본값은 큐 관리자까지 내린다
+
+            노드 목록에 있는 큐 관리자 중 **이 서비스 소관인 것**을 함께 정지시킨다
+            (엔진 rev 3309+). 그 위에서 돌던 응용의 연결이 함께 끊어진다.
+            조정자만 내리고 데이터 평면을 살려 두려면 ``withNodes=False`` 를 쓴다.
+
+            **구엔진(rev 3315 미만)은 이 옵션을 조용히 무시하고 큐 관리자까지
+            내린다.** 그래서 이 라이브러리가 보내기 전에 막는다 - 안 내려갈 것이라
+            믿고 부르는 것이 가장 위험하기 때문이다.
+
+        .. warning:: 성공 반환이 "전부 내려갔다"는 뜻이 아니다
+
+            노드 제어는 **최선 노력**이라 일부가 빠져도 이 호출은 성공을 돌려준다.
+            빠진 노드는 반환값 :class:`ILClusterControlResult` 로 알려 주므로
+            **반드시 확인하라**(엔진 rev 3317+). 빠지는 경우는 이렇다.
+
+            - 개별 노드 제어가 실패했다(그 서비스가 로그를 남기고 다음 노드로 넘어간다).
+            - 다른 서비스 소관 노드인데 **전파가 닿지 못했다.** 그쪽 노드는 그대로 남는다.
+
+            큐 관리자 이름이 빈 노드도 제어 대상에서 빠지는데, 엔진 **rev 3319 부터
+            그런 노드는 애초에 저장이 거부**되므로 새로 만든 클러스터에서는 생기지
+            않는다. rev 3319 이전에 등록된 레거시 노드가 남아 있다면
+            :meth:`removeClusterNode` 후 :meth:`addClusterNode` 로 이름을 채워야 한다.
+
+            ::
+
+                r = svc.stopCluster("CC1")
+                if r.getSkipped():
+                    print("제어 대상에서 빠진 노드:", r.getSkippedNodes())
+                print("제어한 노드 %d개" % r.getControlled())
+
         .. warning:: 정지 완료를 기다리지 않는다
 
             요청만 보내고 바로 돌아온다. **곧바로** :meth:`removeCluster` 를 부르면
@@ -973,14 +1167,31 @@ class ILAdminService:
             :meth:`getClusterProperty` 의 상태가 ``STOPPED`` 가 될 때까지 확인하고
             진행하라 - 큐관리자와 달리 ``stopClusterWithStatus`` 같은 대기형 메서드가
             없다.
+
+        Example::
+
+            # 조정자만 내린다 - 큐 관리자는 계속 서비스한다 (ilcc 패치 등)
+            svc.stopCluster("CC1", withNodes=False)
+            svc.startCluster("CC1", withNodes=False)
+
+            # 클러스터를 통째로 내린다 (기본)
+            svc.stopCluster("CC1")
+            while svc.getClusterProperty("CC1").get_status_string() != "STOPPED":
+                time.sleep(0.5)
+            svc.removeCluster("CC1")
         """
         try:
             self._checkClusterSupported()
-            self.service.request(
+            res = self.service.request(
                 ILC.MIMQ_STOP_CLUSTER,
-                ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION,
                 clusterName,
+                "",
+                self._clusterNodesArg(withNodes),
             )
+            if res is None or res.getCode() != ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION:
+                raise ILOperationException(
+                    res.getArg1() if res is not None else "no response")
+            return ILClusterControlResult(res.getArg1(), res.getArg2(), res.getArg3())
         except _PASSTHROUGH_EXCEPTIONS:
             raise
         except Exception as exc: