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

{jetstream_api-0.4.2/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.2
+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.2 → 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.2"
+__version__ = "0.4.3"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser

{jetstream_api-0.4.2 → jetstream_api-0.4.3}/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:

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

@@ -3603,17 +3603,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 +3719,10 @@ class ILClusterControlResult(_AutoAccessor):
         아무것도 싣지 않으므로 셋 다 0 / 빈 목록으로 온다 - **"빠진 노드가 없다"는
         뜻이 아니라 "알 수 없다"는 뜻**이다. :attr:`known` 으로 구분한다.
 
-        ``withNodes=False`` 로 불렀다면 애초에 노드를 제어하지 않으므로 이 값들은
-        의미가 없다.
+        ``withNodes=False`` 로 불렀다면 노드를 제어하지 않으므로 **셋 다 0 / 빈 목록**
+        으로 온다(엔진 rev 3322+). "빠져서 0" 이 아니라 "안 하기로 해서 0" 인데,
+        부른 쪽은 자기가 준 옵션을 아니까 구분된다. **rev 3317~3321 은 제어하지
+        않았는데도 전체 노드 수**를 실었다.
 
     Example::
 
@@ -3839,6 +3848,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 +3975,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 +4001,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.3/jetstream_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.4.2
+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.2 → jetstream_api-0.4.3}/pyproject.toml

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