jetstream-api 0.20.1__tar.gz → 0.20.2__tar.gz

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.20.1
+Version: 0.20.2
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -60,6 +60,35 @@ lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치
 ## 설치 방법
 pip install jetstream-api
 
+## 0.20.2 변경 - 관제 명령 관리 API · 강제 선출 · 리더십 표 · 격리본 (자바 v2.16.2 와 같음, 짝 엔진 7.0.1.3512 이상 - 리더십 표 · 격리본 · 키 단위 강제 선출은 7.0.1.3552 이상)
+
+- **리더십 표 · 격리본**(엔진 7.0.1.3552 이상, 그 전 엔진은 `MIMQE_INVALID_REQ_CODE`):
+  - `ILAdminService.getClusterLeadTable(cluster)`(VIEW CLUSTER LEADERS, 3423): 원문. `getClusterLeadTableParsed` 는
+    `ILClusterLeadTable`(노드 · 파티션 · 묶음 행, 강제 선출 기록, 오프라인 행)로 풀어 준다. 모르는 줄은 건너뛰고, 판(`ILLT1`)이 다르면 거절.
+  - `ILAdminQmgr.getQuarantineList()` / `scanQuarantine(dir, queue, since)`(VIEW QUARANTINE, 3425 / 3426): 원문.
+  - `reinjectQuarantine(dir, queue, since)`(REINJECT, 3427): `ILQuarantineReinjectResult`(건수 · 리더 · 멈춘 사유). ☠ OLD 까지
+    넣으면 중복 가능, 넣은 건은 큐 맨 뒤에 붙는다.
+
+- **ilsc 관제 명령을 관리 API 로**(엔진이 이미 받는 요청에 클라 메서드만 없던 것):
+  - `ILAdminService.shutdownService(clusterWide=False)`(SHUTDOWN, 3002): 응답 없이 끊기면 False(엔진이 내려가며 닫음), 시간 초과는 예외.
+  - `patchService(fileName, data)`(PATCH, 3335): 성공하면 서비스가 다시 기동하고 연결이 닫힌다.
+  - `diagnoseClusterDefinition(clusterName)`(DIAG CLUSTER 의 정의 대조, 3395): 텍스트 그대로.
+  - `ILAdminQmgr.getLoadMonitoringInfo(level)`(VIEW LOAD, 3204), `reloadQueue`(RELOAD QUEUE, 3315),
+    `setChannelStartMode(channel, autoStart)`(가동 중 STARTMODE, 3035), `removeMessagesFifo(queue, count)`(앞에서부터 지우기, 3345).
+  - `ILClusterProperty.placement` / `autoRebalance`(PLACEMENT · AUTOREBALANCE): `None` 은 보낼 때 "그대로 둔다",
+    `"DEFAULT"` 는 미설정으로 되돌린다.
+
+- **내부 테스트 자동화 전용** `ILAdminService.checkForceElectLeader` / `forceElectLeader`(+ snake 별칭): 엔진 7.0.1.3551 의 운영자
+  강제 선출(`ELECT CLUSTER(C) LEADER(..) FORCE`, 요청 3422)을 관리 API 로 부른다. 확인(위험만 봄)과 실행(☠ 유실 감수)을 나눴고,
+  키(`"<토픽>/<파티션>"` / `"Q:<묶음>/0"`, 도우미 `forceElectPartitionKey` / `forceElectGroupKey`)로 하나만 강제할 수도 있다 -
+  키 단위는 엔진 7.0.1.3552 이상(그 전 엔진은 키를 버리고 노드 단위로 실행하므로 옛 엔진임이 확실하면 보내기 전에 막는다).
+  결과는 `ILClusterForceElectResult`(target · state · risk). 클라는 다시 보내지 않는다(실행의 결과 모름은 확인부터).
+  지금은 내부 시험 자동화에서만 쓴다 - 운영자의 강제 선출은 ilsc 로 한다.
+
+- `removeNode` 문서: `MIMQE_CLUSTER_NOT_COMMITTED (not committed - retry)` 는 실패가 아니라 **결과 모름**입니다(컨트롤러가 8초 안에
+  확정을 못 봄, 늦게 확정될 수 있음). 클라는 스스로 다시 보내지 않습니다. 다시 불러도 안전하고, 그때 `MIMQE_OBJECT_NOT_FOUND` 면
+  먼저 것이 확정돼 이미 빠진 것입니다. 클라 동작은 바뀌지 않습니다.
+
 ## 0.20.1 변경 - 큐 묶음 이동 중 재시도 (자바 v2.16.1 과 같음, 짝 엔진 7.0.1.3512 이상 - 묶음 이동은 7.0.1.3550 이상의 묶음 모드)
 
 - 큐 묶음 이동(엔진 7.0.1.3550 3-b3, `ALTER QUEUE … LEADERGROUP` 등)이 진행 중이면 엔진이 그 큐의 요청을

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/README.md

@@ -10,6 +10,35 @@ lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치
 ## 설치 방법
 pip install jetstream-api
 
+## 0.20.2 변경 - 관제 명령 관리 API · 강제 선출 · 리더십 표 · 격리본 (자바 v2.16.2 와 같음, 짝 엔진 7.0.1.3512 이상 - 리더십 표 · 격리본 · 키 단위 강제 선출은 7.0.1.3552 이상)
+
+- **리더십 표 · 격리본**(엔진 7.0.1.3552 이상, 그 전 엔진은 `MIMQE_INVALID_REQ_CODE`):
+  - `ILAdminService.getClusterLeadTable(cluster)`(VIEW CLUSTER LEADERS, 3423): 원문. `getClusterLeadTableParsed` 는
+    `ILClusterLeadTable`(노드 · 파티션 · 묶음 행, 강제 선출 기록, 오프라인 행)로 풀어 준다. 모르는 줄은 건너뛰고, 판(`ILLT1`)이 다르면 거절.
+  - `ILAdminQmgr.getQuarantineList()` / `scanQuarantine(dir, queue, since)`(VIEW QUARANTINE, 3425 / 3426): 원문.
+  - `reinjectQuarantine(dir, queue, since)`(REINJECT, 3427): `ILQuarantineReinjectResult`(건수 · 리더 · 멈춘 사유). ☠ OLD 까지
+    넣으면 중복 가능, 넣은 건은 큐 맨 뒤에 붙는다.
+
+- **ilsc 관제 명령을 관리 API 로**(엔진이 이미 받는 요청에 클라 메서드만 없던 것):
+  - `ILAdminService.shutdownService(clusterWide=False)`(SHUTDOWN, 3002): 응답 없이 끊기면 False(엔진이 내려가며 닫음), 시간 초과는 예외.
+  - `patchService(fileName, data)`(PATCH, 3335): 성공하면 서비스가 다시 기동하고 연결이 닫힌다.
+  - `diagnoseClusterDefinition(clusterName)`(DIAG CLUSTER 의 정의 대조, 3395): 텍스트 그대로.
+  - `ILAdminQmgr.getLoadMonitoringInfo(level)`(VIEW LOAD, 3204), `reloadQueue`(RELOAD QUEUE, 3315),
+    `setChannelStartMode(channel, autoStart)`(가동 중 STARTMODE, 3035), `removeMessagesFifo(queue, count)`(앞에서부터 지우기, 3345).
+  - `ILClusterProperty.placement` / `autoRebalance`(PLACEMENT · AUTOREBALANCE): `None` 은 보낼 때 "그대로 둔다",
+    `"DEFAULT"` 는 미설정으로 되돌린다.
+
+- **내부 테스트 자동화 전용** `ILAdminService.checkForceElectLeader` / `forceElectLeader`(+ snake 별칭): 엔진 7.0.1.3551 의 운영자
+  강제 선출(`ELECT CLUSTER(C) LEADER(..) FORCE`, 요청 3422)을 관리 API 로 부른다. 확인(위험만 봄)과 실행(☠ 유실 감수)을 나눴고,
+  키(`"<토픽>/<파티션>"` / `"Q:<묶음>/0"`, 도우미 `forceElectPartitionKey` / `forceElectGroupKey`)로 하나만 강제할 수도 있다 -
+  키 단위는 엔진 7.0.1.3552 이상(그 전 엔진은 키를 버리고 노드 단위로 실행하므로 옛 엔진임이 확실하면 보내기 전에 막는다).
+  결과는 `ILClusterForceElectResult`(target · state · risk). 클라는 다시 보내지 않는다(실행의 결과 모름은 확인부터).
+  지금은 내부 시험 자동화에서만 쓴다 - 운영자의 강제 선출은 ilsc 로 한다.
+
+- `removeNode` 문서: `MIMQE_CLUSTER_NOT_COMMITTED (not committed - retry)` 는 실패가 아니라 **결과 모름**입니다(컨트롤러가 8초 안에
+  확정을 못 봄, 늦게 확정될 수 있음). 클라는 스스로 다시 보내지 않습니다. 다시 불러도 안전하고, 그때 `MIMQE_OBJECT_NOT_FOUND` 면
+  먼저 것이 확정돼 이미 빠진 것입니다. 클라 동작은 바뀌지 않습니다.
+
 ## 0.20.1 변경 - 큐 묶음 이동 중 재시도 (자바 v2.16.1 과 같음, 짝 엔진 7.0.1.3512 이상 - 묶음 이동은 7.0.1.3550 이상의 묶음 모드)
 
 - 큐 묶음 이동(엔진 7.0.1.3550 3-b3, `ALTER QUEUE … LEADERGROUP` 등)이 진행 중이면 엔진이 그 큐의 요청을

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/ilink/__init__.py

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.20.1"
+__version__ = "0.20.2"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser
@@ -29,6 +29,11 @@ from .properties import (
     ILClusterNode,
     ILClusterControlResult,
     ILClusterDissolveResult,
+    ILClusterForceElectResult,
+    ILClusterLeadTable,
+    ILClusterLeadEntry,
+    ILClusterForcedKey,
+    ILQuarantineReinjectResult,
     ILClusterJoinResult,
     ILClusterNodeAddResult,
     ILFollowerStatus,
@@ -90,6 +95,11 @@ __all__ = [
     "ILClusterNode",
     "ILClusterControlResult",
     "ILClusterDissolveResult",
+    "ILClusterForceElectResult",
+    "ILClusterLeadTable",
+    "ILClusterLeadEntry",
+    "ILClusterForcedKey",
+    "ILQuarantineReinjectResult",
     "ILClusterJoinResult",
     "ILClusterNodeAddResult",
     "ILFollowerStatus",

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/ilink/admin.py

@@ -27,6 +27,9 @@ from .properties import (
     ILChannelDirection,
     ILClusterControlResult,
     ILClusterDissolveResult,
+    ILClusterForceElectResult,
+    ILClusterLeadTable,
+    ILQuarantineReinjectResult,
     ILClusterJoinResult,
     ILClusterNodeAddResult,
     ILReplicationStatus,
@@ -1241,6 +1244,261 @@ class ILAdminService:
         except Exception as exc:
             raise ILException(exc) from exc
 
+    def checkForceElectLeader(self, clusterName: str, node, key: str | None = None) -> "ILClusterForceElectResult":
+        """강제 선출을 **확인만** 한다 - 받아들여질지, 받아들여지면 무엇을 잃는지 본다(0.20.2, 엔진 7.0.1.3551).
+
+        ☠ **내부 테스트 자동화 전용.** 지금은 내부 시험 자동화(장애 재현 · 회귀)에서만 쓴다. 운영 절차나 응용에서 부르지
+        않는다 - 운영자의 강제 선출은 ilsc 의 ``ELECT CLUSTER(C) LEADER(..) FORCE`` 로 한다(위험을 보이고 y/n 을 묻는다).
+
+        :meth:`forceElectLeader` 앞에 부르는 단계다(ilsc 의 ``ELECT CLUSTER(C) LEADER(..) FORCE`` 가 위험을 보이고
+        y/n 을 묻는 것과 같다). 아무것도 바꾸지 않는다.
+
+        Args:
+            clusterName (str): 클러스터 이름.
+            node (int | str): 리더로 세울 노드 - 번호(int 또는 숫자 문자열) 또는 큐 관리자 이름. 같은 이름이 여러
+                노드에 있으면(HA 에서는 정상) 번호로 다시 달라고 거절된다.
+            key (str | None): 그 하나만 강제할 키 - **엔진 7.0.1.3552 이상**. 토픽 파티션은 ``"<토픽>/<파티션>"``, 큐 묶음은
+                ``"Q:<묶음>/0"``(:meth:`forceElectPartitionKey` / :meth:`forceElectGroupKey` 로 만든다). ``None`` 이면 노드
+                단위(브로커 리더, 엔진 7.0.1.3551 이상). ☠ 그 전 엔진은 키를 버리고 **노드 단위로 실행**하므로, 옛 엔진임이
+                확실하면 보내기 전에 ``MIMQE_NOT_SUPPORTED`` 로 막는다.
+
+        Returns:
+            ILClusterForceElectResult: 대상 번호 · 지금 현황 · 유실 위험.
+
+        Raises:
+            ILOperationException: 엔진이 거절할 때 - 강제할 까닭이 없거나 할 수 없다(사유 문자열로 가른다).
+                리더가 서빙 중이면 ``MIMQE_CLUSTER_LEADER_SERVING (node N leads - nothing to force)``(스위치백이
+                유실 없는 길이다), 안전 후보가 있으면 ``MIMQE_CLUSTER_SAFE_CANDIDATE (node N is elected without loss)``
+                (컨트롤러가 곧 유실 없이 뽑는다), 대상이 살아 있지 않으면
+                ``MIMQE_INVALID_TARGET (node N is not alive - start it first)``, 대상이 없으면
+                ``MIMQE_OBJECT_NOT_FOUND (...)``(키 단위면 키가 리더십 표에 없음), 키 형식이 틀렸거나 같은 이름의 노드가
+                여럿이면 ``MIMQE_INVALID_ARGUMENT (...)``, 키 단위인데 파티션 · 묶음이 배치된 표가 아니면
+                ``MIMQE_INVALID_OPERATION (...)``(노드 단위를 쓴다), 컨트롤러 임기가 적용되기 전이면
+                ``MIMQE_CLUSTER_NOT_READY (...)``, 컨트롤러 리더가 없으면 ``MIMQE_CLUSTER_NO_LEADER (...)``, 해산 중이면
+                ``MIMQE_CLUSTER_DISSOLVED (...)``, 3422 를 모르는 엔진이면 ``MIMQE_INVALID_REQ_CODE (...)``. 키를 줬는데
+                옛 엔진이면 ``MIMQE_NOT_SUPPORTED (...)``. 클라이언트는 이 거절들을 다시 보내지 않는다.
+            ILException: 통신 실패.
+        """
+        return self._force_elect(clusterName, node, key, False)
+
+    def forceElectLeader(self, clusterName: str, node, key: str | None = None) -> "ILClusterForceElectResult":
+        """☠ **유실을 감수하고** 리더를 강제로 세운다(0.20.2, 엔진 7.0.1.3551). 비상 탈출구다.
+
+        ☠ **내부 테스트 자동화 전용.** 지금은 내부 시험 자동화(장애 재현 · 회귀)에서만 쓴다. 운영 절차나 응용에서 부르지
+        않는다 - 운영자의 강제 선출은 ilsc 의 ``ELECT CLUSTER(C) LEADER(..) FORCE`` 로 한다(위험을 보이고 y/n 을 묻는다).
+
+        안전한 후보가 진짜 없을 때(혼자 커밋하던 리더가 돌아오지 않는 등)만 쓴다. 엔진은 자동으로는 절대 하지
+        않는다. **반드시 먼저** :meth:`checkForceElectLeader` 로 위험(``risk``)을 보고 사람이 판단한 뒤 부른다.
+
+        Args:
+            clusterName (str): 클러스터 이름.
+            node (int | str): 리더로 세울 노드 - 번호 또는 큐 관리자 이름(:meth:`checkForceElectLeader` 와 같다).
+            key (str | None): 그 하나만 강제할 키(``"<토픽>/<파티션>"`` / ``"Q:<묶음>/0"``) - **엔진 7.0.1.3552 이상**.
+                ``None`` 이면 노드 단위. 키 단위 실행은 그 키가 오프라인(리더 없음)일 때만 받는다.
+
+        Returns:
+            ILClusterForceElectResult: 대상 번호 · 배정 결과(``state``) · 유실 위험. ``state`` 가
+            ``commit pending`` 이면 배정은 냈으나 확정을 아직 못 본 것이다 - 리더십 현황을 다시 확인한다.
+
+        Raises:
+            ILOperationException: 엔진이 거절할 때(:meth:`checkForceElectLeader` 와 같은 사유). 실행 순간 상황이
+                바뀌었으면(리더가 돌아왔다 · 안전 후보가 생겼다) 실행도 거절된다. ☠ ``MIMQE_CLUSTER_NOT_COMMITTED`` 나
+                ``state`` 의 ``commit pending`` 은 **결과 모름**이다 - 다시 실행하면 강제 선출이 두 번 될 수 있으니,
+                :meth:`checkForceElectLeader` 로 상태부터 본다.
+            ILException: 통신 실패.
+
+        Note:
+            ☠ **위험에 적힌 노드들만 가진 커밋은 사라진다.** 돌아온 옛 리더는 새 리더 밑으로 다시 붙으며 갈라진
+            몫을 잃는다(갈라진 기록은 잘려 나간다). 키 단위면 엔진이 갈라진 데이터를 ``<홈>/QUARANTINE/`` 아래로 격리한 뒤
+            새 리더 사본으로 맞춘다. 클라이언트는 이 요청을 **스스로 다시 보내지 않는다.**
+
+        Example::
+
+            chk = svc.checkForceElectLeader("C1", 2)
+            print(chk.getState(), "잃을 수 있는 노드:", chk.getRisk())
+            if input("강제로 세울까요? (y/n) ") == "y":
+                print(svc.forceElectLeader("C1", 2))
+        """
+        return self._force_elect(clusterName, node, key, True)
+
+    def _force_elect(self, clusterName: str, node, key: str | None, execute: bool) -> "ILClusterForceElectResult":
+        if isinstance(node, bool) or not isinstance(node, (int, str)):
+            raise ILOperationException("MIMQE_INVALID_ARGUMENT (node must be a NodeId or a qmgr name)")
+        target = str(node).strip()
+        if not target:
+            raise ILOperationException("MIMQE_INVALID_ARGUMENT (node must be a NodeId or a qmgr name)")
+        if key is not None and not str(key).strip():
+            raise ILOperationException("MIMQE_INVALID_ARGUMENT (key)")
+        mode = ILC.MIMQ_FORCE_ELECT_EXEC if execute else ILC.MIMQ_FORCE_ELECT_CHECK
+        try:
+            self._checkClusterSupported()
+            # ☠ 옛 엔진은 키(확장)를 버리고 노드 단위로 실행한다 - 확실히 옛 엔진일 때만 막는다(리비전을 모르면 보낸다)
+            if key is not None and 0 < self.revision < ILC.FORCE_ELECT_KEY_MIN_REVISION:
+                raise ILOperationException(
+                    "MIMQE_NOT_SUPPORTED (force elect by key requires engine rev %d+, current: %d - node-level would run)"
+                    % (ILC.FORCE_ELECT_KEY_MIN_REVISION, self.revision))
+            if key is None:
+                res = self.service.request(ILC.MIMQ_CLUSTER_FORCE_ELECT, clusterName, target, mode)
+            else:
+                res = self.service.request(ILC.MIMQ_CLUSTER_FORCE_ELECT, str(key).encode("utf-8"),
+                                           clusterName, target, mode)
+            if res is None or res.getCode() != ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION:
+                raise ILOperationException(
+                    (res.getArg2() or res.getArg1()) if res is not None else "no response")
+            return ILClusterForceElectResult(res.getArg1(), res.getArg2(), res.getArg3())
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def shutdownService(self, clusterWide: bool = False) -> bool:
+        """접속한 **서비스(ilsvc)를 내린다** - ilsc 의 ``SHUTDOWN`` (0.20.2).
+
+        Args:
+            clusterWide (bool): True 면 **클러스터 전체 정지**를 알린다(``MIMQ_SHUTDOWN_SCOPE_CLUSTER``) - 컨트롤러가
+                리더 반납을 기다리지 않는다. 기본 False 는 이 서비스만 내린다(종전 동작).
+
+        Returns:
+            bool: 엔진의 성공 응답을 받았으면 True. **응답 없이 연결이 끊겼으면 False** 다 - 엔진이 정지하며
+            SO_LINGER(1, 0) 로 소켓을 닫아 응답이 오지 않을 수 있다(엔진 C++ 관리 도구도 이 경우를 성공으로 본다).
+            False 는 "정지 요청은 갔으나 확인 못 함" 이니, 확실히 하려면 다시 접속해 보거나 프로세스를 확인한다.
+
+        Raises:
+            ILOperationException: 엔진이 거절했을 때.
+            ILSessionException: 응답도 끊김도 없이 시간이 다했을 때(``MIMQE_WAIT_TIMEOUT`` / ``MIMQE_SESSION_TIMEOUT`` -
+                판정 불가라 성공으로 치지 않는다).
+            ILException: 그 밖의 통신 실패.
+
+        Note:
+            어느 쪽이든 끝나면 이 관리 연결은 **닫힌다**(:meth:`isConnected` 가 False). 큐 관리자들도 함께 내려간다.
+        """
+        scope = ILC.MIMQ_SHUTDOWN_SCOPE_CLUSTER if clusterWide else ""
+        try:
+            self.service.request(ILC.MIMQ_EXIT_ALL_REQUEST, ILC.MIMQ_SUCCESSFUL_SET_EXIT_FLAG, scope, "", "")
+            return True
+        except ILSessionException as exc:
+            if getattr(exc, "reason_code", None) in (ILRC.MIMQE_WAIT_TIMEOUT, ILRC.MIMQE_SESSION_TIMEOUT):
+                raise                       # 시간이 다했다 - 끊김이 아니라 판정 불가다
+            return False                    # 응답 없이 끊김 - 엔진이 내려가며 닫았다
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+        finally:
+            try:
+                self.service.shutdown()
+            except Exception:
+                pass
+
+    def patchService(self, fileName: str, data: bytes) -> None:
+        """서비스에 **패치 파일을 보내 적용한다** - ilsc 의 ``PATCH FILEPATH(..)`` (0.20.2).
+
+        Args:
+            fileName (str): 패치 파일 이름(경로 없이, ilsc 가 보내는 것과 같다). UTF-8 127바이트 이하.
+            data (bytes): 파일 내용 그대로.
+
+        Raises:
+            UnsupportedOperationException: 이름이 비었거나 127바이트를 넘을 때(보내기 전에 막는다).
+            ILOperationException: 엔진이 거절했을 때, 또는 요청이 프레임 상한(기본 128MiB)을 넘을 때.
+            ILException: 통신 실패.
+
+        Note:
+            성공하면 서비스가 파일을 갈아 끼우며 **다시 기동한다** - 이 관리 연결은 닫힌다. 잠시 뒤 다시 접속한다.
+            응답 대기는 관리 연결의 세션 타임아웃(기본 600초)이다.
+        """
+        name = (fileName or "").encode("utf-8")
+        if not name or len(name) > ILC.MIMQ_PATCH_FILE_NAME_LENGTH - 1:
+            raise UnsupportedOperationException(
+                "[%s] is an unacceptable value. (acceptable length: 1 to %d bytes)"
+                % (fileName, ILC.MIMQ_PATCH_FILE_NAME_LENGTH - 1))
+        body = name + bytes(ILC.MIMQ_PATCH_FILE_NAME_LENGTH - len(name)) + bytes(data or b"")
+        try:
+            self.service.apply(ILC.MIMQ_UPDATE_REQUEST, body, ILC.MIMQ_SUCCESSFUL_UPDATE_REQUEST)
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+        try:
+            self.service.shutdown()
+        except Exception:
+            pass
+
+    def diagnoseClusterDefinition(self, clusterName: str) -> str:
+        """클러스터 **정의 진단** - 이 서비스의 정의 사본과 컨트롤러 정족수가 적용한 것을 대조한다(0.20.2).
+
+        ilsc ``DIAG CLUSTER(C)`` 의 앞부분이다(뒷부분은 큐 관리자마다의 :meth:`ILAdminQmgr.getClusterRuntime`).
+        0.18.1 에서 지운 판사 모델의 ``getClusterDefDiag`` (객체 반환)와는 다른 메서드다 - 엔진 3395 의 본문이 컨트롤러
+        정족수 모델의 텍스트가 되어 이름을 새로 붙였다.
+
+        Args:
+            clusterName (str): 클러스터 이름.
+
+        Returns:
+            str: 엔진이 준 텍스트 그대로. 줄 머리가 ``NOTE`` · ``STATE`` · ``HERE`` · ``DEF`` 다
+            (예: ``DEF replicas .. minsync .. ctrlhb .. ctrlelect .. coords .. secret ..``). **형식은 계약이 아니다** -
+            사람이 읽거나 그대로 기록한다.
+
+        Raises:
+            ILOperationException: 엔진이 거절했을 때(사유는 엔진 문구 그대로).
+            ILException: 통신 실패.
+        """
+        try:
+            self._checkClusterSupported()
+            res_msg = self.service.inquire(
+                ILMsgUtil.create_request_msg(ILC.MIMQ_GET_CLUSTER_DEFDIAG, clusterName, "", ""), False)
+            if res_msg.getType() == ILC.MIMQ_REPORT_MESSAGE:
+                raise ILOperationException(res_msg.getReportMsg().getArg2())
+            return res_msg.getDataMsg().getData().decode("utf-8", "replace")
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def getClusterLeadTable(self, clusterName: str) -> str:
+        """클러스터 **리더십 표** 원문 - 노드 · 토픽 파티션 · 큐 묶음 리더와 강제 선출 기록(0.20.2, 엔진 7.0.1.3552).
+
+        ilsc ``VIEW CLUSTER(C) LEADERS`` 와 같다. 풀어 쓰려면 :meth:`getClusterLeadTableParsed` 나
+        ``ILClusterLeadTable(text)`` 를 쓴다.
+
+        Args:
+            clusterName (str): 클러스터 이름.
+
+        Returns:
+            str: 엔진이 준 텍스트 그대로(첫 줄 ``ILLT1|<C|U>|<컨트롤러 리더>``, 칸 구분 ``|``, 빈 값 ``-``).
+
+        Raises:
+            ILOperationException: 엔진이 거절했을 때 - 컨트롤러에 닿지 않으면 ``MIMQE_CLUSTER_UNREACHABLE (...)``, 아직 기록이
+                없으면 ``MIMQE_CLUSTER_NO_LEADER (...)``, 7.0.1.3552 전 엔진이면 ``MIMQE_INVALID_REQ_CODE (...)``.
+            ILException: 통신 실패.
+        """
+        try:
+            self._checkClusterSupported()
+            res_msg = self.service.inquire(
+                ILMsgUtil.create_request_msg(ILC.MIMQ_CLUSTER_LEAD_TABLE, clusterName, "", ""), False)
+            if res_msg.getType() == ILC.MIMQ_REPORT_MESSAGE:
+                raise ILOperationException(res_msg.getReportMsg().getArg2())
+            return res_msg.getDataMsg().getData().decode("utf-8", "replace")
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def getClusterLeadTableParsed(self, clusterName: str) -> "ILClusterLeadTable":
+        """:meth:`getClusterLeadTable` 을 :class:`ILClusterLeadTable` 로 풀어 돌려준다(0.20.2).
+
+        Args:
+            clusterName (str): 클러스터 이름.
+
+        Returns:
+            ILClusterLeadTable: 풀린 표(원문은 ``raw``).
+
+        Raises:
+            ILOperationException: :meth:`getClusterLeadTable` 과 같다.
+            ILDeserializeException: 표의 판이 이 클라와 다를 때.
+            ILException: 통신 실패.
+        """
+        return ILClusterLeadTable(self.getClusterLeadTable(clusterName))
+
     def addNode(self, clusterName: str, node: ILClusterNode) -> "ILClusterNodeAddResult":
         """클러스터에 **노드 하나**(컨트롤러 전용 노드 또는 브로커)를 더한다. 투표권은 주지 않는다.
 
@@ -1316,8 +1574,19 @@ class ILAdminService:
                 엔진이 거절할 때 - 아직 투표권이 있으면 ``... (node N still votes - revoke with COORDS)``,
                 마지막 브로커일 때 ``... (the last broker cannot be removed)``, 그 브로커가 지금 리더일 때
                 ``MIMQE_INVALID_OPERATION (node N leads - stop it first, then DELNODE)``.
+                컨트롤러 정족수가 확정해 주지 못할 때 ``MIMQE_CLUSTER_NOT_COMMITTED (not committed - retry)`` - 아래 Note.
             ILException: 통신 실패.
 
+        Note:
+            ☠ ``MIMQE_CLUSTER_NOT_COMMITTED (not committed - retry)`` 는 **실패가 아니라 결과 모름**이다. 컨트롤러 리더가
+            변경을 올리고 8초 안에 확정을 못 봤다는 뜻이고, 제안은 거둬지지 않아 **늦게 확정될 수 있다**. 얼마나 이어질지는
+            원인에 달렸다 - 컨트롤러 리더가 바뀌는 중이면 보통 몇 초, 투표자 컨트롤러가 죽어 있으면 돌아올 때까지 계속 난다.
+            클라이언트는 스스로 다시 보내지 않는다. 다시 부르면 안전하다(매번 정의를 새로 읽어 그 판으로 보낸다): 먼저 것이
+            그사이 확정됐으면 ``MIMQE_OBJECT_NOT_FOUND (node N in cluster C)`` 가 나는데 이것은 **이미 빠졌다는 뜻**(성공)이고,
+            다시 보낸 뒤에 먼저 것이 확정되면 ``MIMQE_CLUSTER_DEF_MOVED`` 로 갈려 두 번 적용되지 않는다.
+            :meth:`getClusterProperty` 로 노드 목록을 보고 판단해도 된다. ``(earlier change still pending - retry)`` 는 이번
+            것을 올리지 않은 것이라 그대로 다시 부르면 된다.
+
         Note:
             ★ **투표자를 빼려면 두 번 부른다** - 먼저 :meth:`setCoords` 로 투표권을 거두고, 그다음 이것으로 뺀다.
 
@@ -1649,6 +1918,55 @@ class ILAdminService:
         """:meth:`joinCluster` 의 snake 별칭."""
         return self.joinCluster(cluster_name, controller_addr, auto_start, seats)
 
+    @staticmethod
+    def forceElectPartitionKey(topic: str, partition: int) -> str:
+        """토픽 파티션 하나의 강제 선출 키를 만든다(``"<토픽>/<파티션>"``). **내부 테스트 자동화 전용.**
+
+        Args:
+            topic (str): 토픽 이름.
+            partition (int): 파티션 번호.
+
+        Returns:
+            str: 키.
+        """
+        return "%s/%d" % (topic, int(partition))
+
+    @staticmethod
+    def forceElectGroupKey(group: str) -> str:
+        """큐 묶음(LEADERGROUP) 하나의 강제 선출 키를 만든다(``"Q:<묶음>/0"`` - 묶음은 파티션 하나뿐인 토픽처럼 다룬다).
+        **내부 테스트 자동화 전용.**
+
+        Args:
+            group (str): 묶음 이름.
+
+        Returns:
+            str: 키.
+        """
+        return "Q:%s/0" % group
+
+    force_elect_partition_key = forceElectPartitionKey
+    force_elect_group_key = forceElectGroupKey
+
+    def get_cluster_lead_table(self, cluster_name: str) -> str:
+        """:meth:`getClusterLeadTable` 의 snake 별칭."""
+        return self.getClusterLeadTable(cluster_name)
+
+    def get_cluster_lead_table_parsed(self, cluster_name: str) -> "ILClusterLeadTable":
+        """:meth:`getClusterLeadTableParsed` 의 snake 별칭."""
+        return self.getClusterLeadTableParsed(cluster_name)
+
+    def diagnose_cluster_definition(self, cluster_name: str) -> str:
+        """:meth:`diagnoseClusterDefinition` 의 snake 별칭."""
+        return self.diagnoseClusterDefinition(cluster_name)
+
+    def check_force_elect_leader(self, cluster_name: str, node, key: str | None = None) -> "ILClusterForceElectResult":
+        """:meth:`checkForceElectLeader` 의 snake 별칭."""
+        return self.checkForceElectLeader(cluster_name, node, key)
+
+    def force_elect_leader(self, cluster_name: str, node, key: str | None = None) -> "ILClusterForceElectResult":
+        """:meth:`forceElectLeader` 의 snake 별칭."""
+        return self.forceElectLeader(cluster_name, node, key)
+
     def dissolve_cluster(self, cluster_name: str) -> "ILClusterDissolveResult":
         """:meth:`dissolveCluster` 의 snake 별칭."""
         return self.dissolveCluster(cluster_name)
@@ -3894,6 +4212,182 @@ class ILAdminQmgr:
         except Exception as exc:
             raise ILException(exc) from exc
 
+    def _quarantineText(self, code: int, *args: str) -> str:
+        res_msg = self.service.inquire(
+            ILMsgUtil.create_request_msg_with_qmgr(self.qmgrName, code, None, *args), False)
+        if res_msg.getType() == ILC.MIMQ_REPORT_MESSAGE:
+            raise ILOperationException(res_msg.getReportMsg().getArg2())
+        return res_msg.getDataMsg().getData().decode("utf-8", "replace")
+
+    @staticmethod
+    def _quarantineSince(since) -> str:
+        if since is None:
+            return ""
+        if isinstance(since, bool):
+            raise UnsupportedOperationException("[%s] is an unacceptable value. (since)" % (since,))
+        return str(since)
+
+    def getQuarantineList(self) -> str:
+        """이 큐 관리자의 **격리본 목록** - ilsc ``VIEW QUARANTINE`` (0.20.2, 엔진 7.0.1.3552).
+
+        격리본은 강제 선출 뒤 돌아온 옛 리더가 새 리더 사본으로 맞추기 전에 갈라진 데이터를 ``<홈>/QUARANTINE/`` 아래로 옮겨 둔
+        것이다. 큐 관리자가 떠 있어야 하고, 팔로워 노드에서도 된다.
+
+        Returns:
+            str: 엔진이 준 텍스트 그대로. 첫 줄 ``QL1|<격리 루트>``, 그다음
+            ``D|<디렉터리>|<NODE|GROUP|TOPIC|?>|<파일 수>|<바이트>|<기준 시각 또는 ->|<FORK.txt 첫 줄 또는 ->`` 와
+            ``Q|<디렉터리>|<큐>|<세그먼트 수>|<재주입 건수>`` 줄.
+
+        Raises:
+            ILOperationException: 엔진이 거절했을 때(7.0.1.3552 전 엔진은 ``MIMQE_INVALID_REQ_CODE``).
+            ILException: 통신 실패.
+        """
+        try:
+            return self._quarantineText(ILC.MIMQ_QUARANTINE_LIST, "", "", "")
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def scanQuarantine(self, directory: str, queueName: str | None = None, since=None) -> str:
+        """격리본을 **검사만** 한다 - 재주입하면 무엇이 들어갈지 본다. 부수효과 없음(0.20.2, 엔진 7.0.1.3552).
+
+        Args:
+            directory (str): 격리 디렉터리 이름(한 단계 - ``/`` ``\\`` ``:`` 금지).
+            queueName (str | None): 큐. ``None`` 이면 그 디렉터리의 모든 큐 요약.
+            since (str | int | None): 기준. ``None`` 이면 디렉터리 기준 시각, ``"ALL"`` 이면 전부,
+                ``"yyyymmddhhmmss"`` 문자열이나 epoch 밀리초 숫자.
+
+        Returns:
+            str: 엔진이 준 텍스트 그대로. 첫 줄 ``QS1|<디렉터리>|<큐 또는 *>|<기준>``, 큐마다
+            ``S|<큐>|<전체>|<LIVE>|<CANDIDATE>|<OLD>|<DONE>``, 큐를 줬으면 재주입 대상 앞 500건
+            ``M|C|<IndexId>|<PUT 시각>|<바이트>|<MsgId>``. LIVE = 지금 큐에 있음, CANDIDATE = 재주입 대상, OLD = 기준 전(소비됐을
+            가능성), DONE = 이미 재주입.
+
+        Raises:
+            ILOperationException: 엔진이 거절했을 때(디렉터리 · 큐가 없으면 ``MIMQE_OBJECT_NOT_FOUND`` 등).
+            ILException: 통신 실패.
+        """
+        try:
+            return self._quarantineText(ILC.MIMQ_QUARANTINE_SCAN, directory or "", queueName or "",
+                                        self._quarantineSince(since))
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def reinjectQuarantine(self, directory: str, queueName: str, since=None) -> "ILQuarantineReinjectResult":
+        """격리본의 재주입 대상(CANDIDATE)을 **그 큐의 지금 리더에 다시 넣는다** - ilsc ``REINJECT`` (0.20.2, 엔진 7.0.1.3552).
+
+        원래 MsgId · CorrelId 로 PUT 하고 100건마다 커밋한다. 넣은 것은 기록되어 다시 넣지 않는다. **먼저**
+        :meth:`scanQuarantine` 으로 무엇이 들어갈지 본다.
+
+        Args:
+            directory (str): 격리 디렉터리 이름.
+            queueName (str): 큐(필수).
+            since (str | int | None): 기준(:meth:`scanQuarantine` 과 같다).
+
+        Returns:
+            ILQuarantineReinjectResult: 넣은 건수 · 넣은 리더 · 메모. 메모가 ``stopped: ...`` 면 중간에 멈춘 것이다 - 넣은 만큼은
+            커밋됐고 다시 부르면 나머지만 넣는다.
+
+        Raises:
+            UnsupportedOperationException: 큐를 주지 않았을 때(보내기 전에 막는다).
+            ILOperationException: 엔진이 거절했을 때 - ``MIMQE_OBJECT_NOT_FOUND``, 토픽 격리본이면
+                ``MIMQE_UNSUPPORTED_OPERATION``, 리더가 없으면 ``MIMQE_CLUSTER_NO_LEADER``, 리더 접속 실패 사유.
+            ILException: 통신 실패.
+
+        Warning:
+            ☠ **중복이 생길 수 있다** - ``since="ALL"`` 로 OLD(이미 소비됐을 수 있는 것)까지 넣으면 같은 메시지가 두 번 처리될 수
+            있다. 넣은 메시지는 **큐 맨 뒤에** 붙는다(원래 순서 자리로 가지 않는다). 건수에 비례해 오래 걸릴 수 있으니 관리 연결의
+            세션 타임아웃을 넉넉히 둔다(ilsc 는 120초).
+        """
+        if not queueName:
+            raise UnsupportedOperationException("queueName is required for reinject")
+        try:
+            res = self.service.request(self.qmgrName, ILC.MIMQ_QUARANTINE_REINJECT, directory or "", queueName,
+                                       self._quarantineSince(since))
+            if res is None or res.getCode() != ILC.MIMQ_SUCCESSFUL_CLUSTER_OPERATION:
+                raise ILOperationException(res.getArg2() if res is not None else "no response")
+            return ILQuarantineReinjectResult(res.getArg1(), res.getArg2(), res.getArg3())
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def removeMessagesFifo(self, queueName: str, count: int) -> None:
+        """큐 **앞에서부터** ``count`` 건을 지운다(0.20.2). :meth:`flushQueue` 와 달리 일부만 지운다.
+
+        Args:
+            queueName (str): 큐 이름.
+            count (int): 지울 건수(1 이상). 큐에 그보다 적으면 있는 만큼 지운다.
+
+        Raises:
+            UnsupportedOperationException: ``count`` 가 1 보다 작을 때(보내기 전에 막는다).
+            ILOperationException: 그런 큐가 없거나 엔진이 거절했을 때. 클러스터 큐 묶음 모드에서는 그 큐 묶음의
+                리더가 아닌 큐 관리자로 보내면 ``MIMQE_FOLLOWER_NODE (...)`` 로 거절된다.
+            ILException: 통신 실패.
+
+        Warning:
+            **되돌릴 수 없다.** 다른 세션이 받으려던 메시지일 수 있다. 지운 건은 클러스터에서 팔로워에도 복제된다.
+        """
+        if isinstance(count, bool) or not isinstance(count, int) or count < 1:
+            raise UnsupportedOperationException("[%s] is an unacceptable value. (acceptable: 1 or greater)" % (count,))
+        try:
+            self.service.request(self.qmgrName, ILC.MIMQ_REMOVE_MSG_FIFO, ILC.MIMQ_SUCCESSFUL_REMOVE_MSG,
+                                 queueName, str(count))
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def reloadQueue(self, queueName: str) -> None:
+        """큐를 **디스크에서 다시 읽어 올린다** - ilsc 의 ``RELOAD QUEUE(q)`` (0.20.2).
+
+        Args:
+            queueName (str): 큐 이름.
+
+        Raises:
+            ILOperationException: 그런 큐가 없거나 엔진이 거절했을 때. 클러스터 큐 묶음 모드에서는 그 큐 묶음의
+                리더가 아닌 큐 관리자로 보내면 ``MIMQE_FOLLOWER_NODE (...)`` 로 거절된다.
+            ILException: 통신 실패.
+        """
+        try:
+            self.service.request(self.qmgrName, ILC.MIMQ_RELOAD_QUEUE, ILC.MIMQ_SUCCESSFUL_QUEUE_RELOAD, queueName)
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
+    def getLoadMonitoringInfo(self, level: int = 1) -> str:
+        """큐 관리자 **부하 정보** - ilsc 의 ``VIEW LOAD [LEVEL(n)]`` (0.20.2).
+
+        Args:
+            level (int): 자세한 정도 1 · 2 · 3. 기본 1.
+
+        Returns:
+            str: 엔진이 준 텍스트 그대로. **형식은 계약이 아니다** - 사람이 읽거나 그대로 기록한다.
+
+        Raises:
+            UnsupportedOperationException: ``level`` 이 1 · 2 · 3 이 아닐 때(보내기 전에 막는다).
+            ILOperationException: 엔진이 거절했을 때.
+            ILException: 통신 실패.
+        """
+        if isinstance(level, bool) or level not in (1, 2, 3):
+            raise UnsupportedOperationException("[%s] is an unacceptable value. (acceptable: 1, 2, 3)" % (level,))
+        try:
+            res_msg = self.service.inquire(
+                ILMsgUtil.create_request_msg_with_qmgr(
+                    self.qmgrName, ILC.MIMQ_GET_LOAD_MONITORING_INFO, None, str(level), "", ""),
+                False)
+            if res_msg.getType() == ILC.MIMQ_REPORT_MESSAGE:
+                raise ILOperationException(res_msg.getReportMsg().getArg2())
+            return res_msg.getDataMsg().getData().decode("utf-8", "replace")
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
     def _queueBlob(self, prop: ILQueueProperty) -> bytes:
         """큐 속성을 **붙어 있는 엔진이 이해하는 레이아웃**으로 직렬화한다.
 
@@ -5271,6 +5765,29 @@ class ILAdminQmgr:
                 pass
         return False
 
+    def setChannelStartMode(self, channelName: str, autoStart: bool) -> None:
+        """채널의 **자동 기동 여부**를 바꾼다 - 채널이 **가동 중이어도** 된다(ilsc ``ALTER CHANNEL STARTMODE``, 0.20.2).
+
+        :meth:`setChannelProperty` 는 채널이 멈춰 있을 때만 바꿀 수 있는 항목이 있다. 이 메서드는 기동 방식 하나만
+        가동 중에 바꾼다.
+
+        Args:
+            channelName (str): 채널 이름.
+            autoStart (bool): True 면 큐 관리자가 뜰 때 같이 기동한다.
+
+        Raises:
+            ILOperationException: 그런 채널이 없거나 엔진이 거절했을 때.
+            ILException: 통신 실패.
+        """
+        try:
+            self.service.request(self.qmgrName, ILC.MIMQ_SET_CHANNEL_EXECUTION_MODE,
+                                 ILC.MIMQ_SUCCESSFUL_SET_EXECUTION_MODE, channelName,
+                                 "true" if autoStart else "false")
+        except _PASSTHROUGH_EXCEPTIONS:
+            raise
+        except Exception as exc:
+            raise ILException(exc) from exc
+
     def setChannelTrace(self, channelName: str, enabled: bool) -> None:
         """특정 채널의 트레이스를 켜거나 끈다.
 

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/ilink/common.py

@@ -429,6 +429,28 @@ class ILC:
     #: 이미 있는 클러스터에 이 서비스를 참여시킨다(엔진 r3487). arg1 이름, arg2 ``host:ctrlPort``,
     #: arg3 STARTMODE(빈 값 = AUTO). 성공 arg1 = 노드 번호, arg2 = 로컬 컨트롤러 포트(0 = 없음).
     MIMQ_JOIN_CLUSTER = 3406
+    #: 운영자 강제 선출(엔진 7.0.1.3551 FORCELEAD-1 / FORCEKEY-1). arg1 클러스터, arg2 대상(NodeId 또는 큐 관리자 이름),
+    #: arg3 :attr:`MIMQ_FORCE_ELECT_CHECK` / :attr:`MIMQ_FORCE_ELECT_EXEC`, 확장 = 키(없으면 노드 단위).
+    #: 성공 4272 arg1 = 대상 NodeId, arg2 = 상태(EXEC 면 배정 결과), arg3 = 유실 위험. 거절 4273.
+    MIMQ_CLUSTER_FORCE_ELECT = 3422
+    #: SHUTDOWN(3002) arg1 - **클러스터 전체 정지**(엔진 CLSREL-1). 빈 값이면 이 서비스만 내린다(종전).
+    MIMQ_SHUTDOWN_SCOPE_CLUSTER = "C"
+    #: 리더십 표 조회(엔진 7.0.1.3552 LEADVIEW-1). ilsvc 요청, arg1 클러스터. 성공 LONG_REPORT 텍스트(첫 줄 ``ILLT1|...``).
+    MIMQ_CLUSTER_LEAD_TABLE = 3423
+    #: 격리본 목록(엔진 7.0.1.3552 QUARTOOL-1). 큐 관리자 중계. 성공 LONG_REPORT 텍스트(첫 줄 ``QL1|...``).
+    MIMQ_QUARANTINE_LIST = 3425
+    #: 격리본 검사(재주입의 확인, 부수효과 없음). arg1 디렉터리, arg2 큐, arg3 SINCE. 성공 LONG_REPORT(첫 줄 ``QS1|...``).
+    MIMQ_QUARANTINE_SCAN = 3426
+    #: 격리본 재주입. arg 는 검사와 같다(큐 필수). 성공 4272 arg1 넣은 건수, arg2 넣은 리더, arg3 멈춘 사유.
+    MIMQ_QUARANTINE_REINJECT = 3427
+    #: PATCH(3335) 본문 앞 파일 이름 칸 폭(ILINKBYTE128). 이름은 이 폭 - 1 바이트까지(널 종단).
+    MIMQ_PATCH_FILE_NAME_LENGTH = 128
+    #: 3422 arg3 - 확인만(거절 사유 또는 상태 · 위험).
+    MIMQ_FORCE_ELECT_CHECK = "CHECK"
+    #: 3422 arg3 - 실행(유실 감수).
+    MIMQ_FORCE_ELECT_EXEC = "EXEC"
+    #: 키 단위 강제 선출(3422 확장 칸)을 받는 엔진 리비전(FORCEKEY-1). 그 전 엔진은 확장을 버리고 **노드 단위로 실행**한다.
+    FORCE_ELECT_KEY_MIN_REVISION = 3552
     #: REMOVE CLUSTER 의 arg2. 이 값이면 **클러스터 전체 해산**이다(엔진 r3487). 빈 값이면 이 서비스
     #: 사본만 지운다. ☠ 옛 엔진은 arg2 를 무시해 사본만 지운다 - 성공 arg1 이 빈 값이면 그것이다.
     MIMQ_CLUSTER_DISSOLVE_ALL = "ALL"

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/ilink/properties.py

@@ -5305,6 +5305,267 @@ class ILClusterDissolveResult(_AutoAccessor):
         return s
 
 
+class ILClusterForceElectResult(_AutoAccessor):
+    """:meth:`ILAdminService.checkForceElectLeader` / :meth:`ILAdminService.forceElectLeader` 의 결과(0.20.2). **내부 테스트 자동화 전용.**
+
+    Attributes:
+        target (int): 대상 노드 번호(큐 관리자 이름으로 불렀어도 엔진이 푼 번호).
+        state (str): 확인이면 지금 리더십 현황, 실행이면 배정 결과(``assigned epoch N - committed`` 또는
+            ``... - commit pending (check VIEW CLUSTER)``). 사람이 읽는 문구이고 **형식은 계약이 아니다.**
+        risk (str): 유실 위험 - 대상 말고 확정 리더 · 확정 ISR · 보유자 노드. **그 노드들만 가진 커밋이 사라진다.**
+            사람이 읽는 문구이고 형식은 계약이 아니다.
+    """
+
+    def __init__(self, arg1: str = "", arg2: str = "", arg3: str = "") -> None:
+        """응답 arg 세 개를 담는다. **응용이 직접 만들 일은 없다.**
+
+        Args:
+            arg1 (str): 대상 노드 번호.
+            arg2 (str): 상태.
+            arg3 (str): 유실 위험.
+        """
+        try:
+            self.target = int(str(arg1 or "").strip() or 0)
+        except ValueError:
+            self.target = 0
+        self.state = str(arg2 or "")
+        self.risk = str(arg3 or "")
+
+    def __str__(self) -> str:
+        """사람이 읽는 한 줄 요약을 돌려준다.
+
+        Returns:
+            str: 대상 · 상태 · 위험. 형식은 고정이 아니므로 파싱하지 말 것.
+        """
+        return "force elect node %d: %s [risk: %s]" % (self.target, self.state, self.risk)
+
+
+def _lt_int(v: str, default: int = 0) -> int:
+    v = (v or "").strip()
+    if v in ("", "-"):
+        return default
+    try:
+        return int(v)
+    except ValueError:
+        return default
+
+
+def _lt_ids(v: str) -> list:
+    v = (v or "").strip()
+    if v in ("", "-"):
+        return []
+    out = []
+    for x in v.split(","):
+        x = x.strip()
+        if x.lstrip("-").isdigit():
+            out.append(int(x))
+    return out
+
+
+class ILClusterLeadEntry(_AutoAccessor):
+    """리더십 표의 **토픽 파티션 하나 또는 큐 묶음 하나**(0.20.2). :class:`ILClusterLeadTable` 의 항목이다.
+
+    Attributes:
+        key (str): 토픽 파티션은 ``"<토픽>/<파티션>"``, 큐 묶음은 묶음 이름.
+        leader (int): 리더 노드 번호. **0 이면 오프라인**(앞 ISR 이 모두 죽음 - 키 단위 강제 선출 대상).
+        epoch (int): 리더 epoch.
+        isr (list[int]): 확정 ISR 노드 번호.
+        replicas (list[int]): 복제본 노드 번호.
+    """
+
+    def __init__(self, key: str = "", leader: int = 0, epoch: int = 0,
+                 isr: list | None = None, replicas: list | None = None) -> None:
+        """값을 담는다. **응용이 직접 만들 일은 없다.**
+
+        Args:
+            key (str): 키.
+            leader (int): 리더.
+            epoch (int): epoch.
+            isr (list | None): ISR.
+            replicas (list | None): 복제본.
+        """
+        self.key = key
+        self.leader = leader
+        self.epoch = epoch
+        self.isr = list(isr or [])
+        self.replicas = list(replicas or [])
+
+    def is_offline(self) -> bool:
+        """리더가 없는가(리더 0).
+
+        Returns:
+            bool: 오프라인이면 True.
+        """
+        return self.leader == 0
+
+    isOffline = is_offline
+
+    def __str__(self) -> str:
+        """사람이 읽는 한 줄을 돌려준다.
+
+        Returns:
+            str: 형식은 고정이 아니므로 파싱하지 말 것.
+        """
+        return "%s leader %d e%d isr%s replicas%s" % (self.key, self.leader, self.epoch, self.isr, self.replicas)
+
+
+class ILClusterForcedKey(_AutoAccessor):
+    """리더십 표의 **강제 선출 기록 하나**(키 단위, 0.20.2).
+
+    Attributes:
+        key (str): 강제 선출한 키(``"<토픽>/<파티션>"`` 또는 ``"Q:<묶음>/0"``).
+        epoch (int): 강제 선출로 배정한 epoch.
+        risk (list[int]): 그때 잃을 수 있던 노드 번호.
+    """
+
+    def __init__(self, key: str = "", epoch: int = 0, risk: list | None = None) -> None:
+        """값을 담는다. **응용이 직접 만들 일은 없다.**
+
+        Args:
+            key (str): 키.
+            epoch (int): epoch.
+            risk (list | None): 위험 노드.
+        """
+        self.key = key
+        self.epoch = epoch
+        self.risk = list(risk or [])
+
+
+class ILClusterLeadTable(_AutoAccessor):
+    """:meth:`ILAdminService.getClusterLeadTable` 원문을 푼 **리더십 표**(0.20.2, 엔진 7.0.1.3552 LEADVIEW-1).
+
+    Attributes:
+        committed (bool): 컨트롤러 정족수가 확정한 표면 True(``C``). False(``U``)면 리더가 없어 한 컨트롤러가 적용한 판이라
+            **낡았을 수 있다.**
+        controllerLeader (int): 컨트롤러 리더 노드 번호(없으면 0).
+        nodeLeader (int): 노드 단위(브로커) 리더. 0 이면 없음.
+        nodeEpoch (int): 노드 리더 epoch.
+        nodeIsr (list[int]): 노드 단위 확정 ISR.
+        nodeHolders (list[int]): 보유자.
+        nodeForcedEpoch (int): 노드 단위 강제 선출 epoch(없으면 0).
+        nodeRisk (list[int]): 그 강제 선출의 위험 노드.
+        partitionSeq (int | None): 파티션 절 순번. 파티션 절이 없으면 None.
+        placed (bool): 파티션 · 묶음이 배치된 표인가(키 단위 강제 선출을 받는 표).
+        partitions (list[ILClusterLeadEntry]): 토픽 파티션 행.
+        groups (list[ILClusterLeadEntry]): 큐 묶음 행.
+        forced (list[ILClusterForcedKey]): 키 단위 강제 선출 기록.
+        raw (str): 엔진이 준 원문.
+
+    Note:
+        모르는 머리글 줄은 건너뛴다(엔진 뒤 판이 줄 종류를 늘릴 수 있다). 첫 줄이 ``ILLT1|`` 이 아니면 거절한다 -
+        판이 다른 표를 조용히 잘못 읽지 않도록.
+    """
+
+    def __init__(self, text: str) -> None:
+        """원문을 푼다.
+
+        Args:
+            text (str): :meth:`ILAdminService.getClusterLeadTable` 원문.
+
+        Raises:
+            ILDeserializeException: 첫 줄이 ``ILLT1|`` 이 아닐 때.
+        """
+        self.raw = text or ""
+        lines = [ln.rstrip("\r") for ln in self.raw.split("\n") if ln.strip()]
+        if not lines or not lines[0].startswith("ILLT1|"):
+            raise ILDeserializeException(
+                "unsupported lead table : first line %r - expected 'ILLT1|...' (upgrade the client)"
+                % (lines[0][:20] if lines else ""))
+        head = lines[0].split("|")
+        self.committed = len(head) > 1 and head[1] == "C"
+        self.controllerLeader = _lt_int(head[2]) if len(head) > 2 else 0
+        self.nodeLeader = 0
+        self.nodeEpoch = 0
+        self.nodeIsr: list = []
+        self.nodeHolders: list = []
+        self.nodeForcedEpoch = 0
+        self.nodeRisk: list = []
+        self.partitionSeq = None
+        self.placed = False
+        self.partitions: list = []
+        self.groups: list = []
+        self.forced: list = []
+        for ln in lines[1:]:
+            f = ln.split("|")
+            kind = f[0]
+            f = f + [""] * 7
+            if kind == "N":
+                self.nodeLeader = _lt_int(f[1])
+                self.nodeEpoch = _lt_int(f[2])
+                self.nodeIsr = _lt_ids(f[3])
+                self.nodeHolders = _lt_ids(f[4])
+                self.nodeForcedEpoch = _lt_int(f[5])
+                self.nodeRisk = _lt_ids(f[6])
+            elif kind == "PT":
+                self.partitionSeq = _lt_int(f[1])
+                self.placed = f[2].strip() == "1"
+            elif kind in ("P", "G"):
+                e = ILClusterLeadEntry(f[1], _lt_int(f[2]), _lt_int(f[3]), _lt_ids(f[4]), _lt_ids(f[5]))
+                (self.partitions if kind == "P" else self.groups).append(e)
+            elif kind == "K":
+                self.forced.append(ILClusterForcedKey(f[1], _lt_int(f[2]), _lt_ids(f[3])))
+            # 모르는 줄은 건너뛴다
+
+    def get_offline(self) -> list:
+        """리더가 없는(오프라인) 파티션 · 묶음 행.
+
+        Returns:
+            list[ILClusterLeadEntry]: 키 단위 강제 선출 대상.
+        """
+        return [e for e in self.partitions + self.groups if e.leader == 0]
+
+    getOffline = get_offline
+
+    def __str__(self) -> str:
+        """원문을 돌려준다.
+
+        Returns:
+            str: 엔진이 준 원문.
+        """
+        return self.raw
+
+
+class ILQuarantineReinjectResult(_AutoAccessor):
+    """:meth:`ILAdminQmgr.reinjectQuarantine` 의 결과(0.20.2).
+
+    Attributes:
+        count (int): 넣은 건수.
+        leader (str): 넣은 리더(``"node <id> <host:port>"``).
+        note (str): ``""`` 이면 다 넣었다. ``"stopped: <사유>"`` 면 중간에 멈췄다(넣은 만큼은 커밋됐다 - 다시 부르면 나머지만
+            넣는다). ``"nothing to reinject"`` 면 넣을 것이 없었다.
+    """
+
+    def __init__(self, arg1: str = "", arg2: str = "", arg3: str = "") -> None:
+        """응답 arg 세 개를 담는다. **응용이 직접 만들 일은 없다.**
+
+        Args:
+            arg1 (str): 넣은 건수.
+            arg2 (str): 넣은 리더.
+            arg3 (str): 메모.
+        """
+        self.count = _lt_int(arg1)
+        self.leader = str(arg2 or "")
+        self.note = str(arg3 or "")
+
+    def is_stopped(self) -> bool:
+        """중간에 멈췄는가.
+
+        Returns:
+            bool: ``note`` 가 ``"stopped:"`` 로 시작하면 True.
+        """
+        return self.note.startswith("stopped:")
+
+    isStopped = is_stopped
+
+    def __str__(self) -> str:
+        """사람이 읽는 한 줄 요약을 돌려준다.
+
+        Returns:
+            str: 형식은 고정이 아니므로 파싱하지 말 것.
+        """
+        return "reinjected %d to %s%s" % (self.count, self.leader, (" [" + self.note + "]") if self.note else "")
+
+
 class ILClusterControlResult(_AutoAccessor):
     """:meth:`ILAdminService.startCluster` / :meth:`ILAdminService.stopCluster` 의 결과.
 
@@ -5379,7 +5640,10 @@ _CLUSTER_FIXED_FIELDS = (
     # actingCoordinator 는 **폐기 예정**이다(0.18.1): r3481~r3483 은 controllerLeader 의 사본이었고,
     # r3484 부터는 엔진이 채우지 않는다. 이 12바이트 중 앞 6바이트(583..588)는 **영구 결번** -
     # 다른 값에 다시 쓰이지 않는다(옛 클라가 새 값을 이 이름으로 조용히 잘못 읽지 않도록).
-    ("actingCoordinator", 6), ("localCtrlPort", 6), (None, 173),
+    ("actingCoordinator", 6), ("localCtrlPort", 6),
+    # 엔진 PLACEMENT-1: 예약 앞 20바이트에 **정의 칸 둘**. 판 표시는 V2 그대로 - 옛 블롭에는 0x00 이라
+    # 미설정으로 읽힌다. 빈칸으로 보내면 엔진이 저장값을 유지하고, "DEFAULT" 를 보내면 미설정으로 되돌린다.
+    ("placement", 12), ("autoRebalance", 8), (None, 153),
 )
 
 _CLUSTER_OFF, _CLUSTER_LEN = _field_offsets(_CLUSTER_FIXED_FIELDS)
@@ -5390,7 +5654,7 @@ _CLUSTER_OFF, _CLUSTER_LEN = _field_offsets(_CLUSTER_FIXED_FIELDS)
 _CLUSTER_WRITTEN = ("layoutVersion", "name", "startMode",
                     "controllerHeartbeatIntervalMs", "controllerElectionTimeoutMs",
                     "heartbeatIntervalMs", "heartbeatMissCount", "electionDelayMs",
-                    "replicas", "minSync")
+                    "replicas", "minSync", "placement", "autoRebalance")
 
 # 표에서 계산한 길이와 공개 상수가 어긋나면 **여기서 터진다.** 한쪽만 고치는 일을 막는다 -
 # 상수를 써서 오프셋을 잡는 코드가 밖에 있어서 조용히 어긋나면 잘못된 자리를 파게 된다.
@@ -5821,6 +6085,12 @@ class ILClusterProperty(_AutoAccessor):
             친다 - 노드를 더하면 RF 도 따라 는다. 숫자를 명시하면 그 진술이 고정되어
             노드 수가 달라질 때 거절된다. ★ **ALTER 에서 ``None``(빈칸)은 "그대로 둔다"** 이고, 명시해 둔 값을
             **지우려면 0 을 보낸다** - 미설정으로 되돌아가 다시 노드 수를 따른다(``minSync`` 와 같은 규칙).
+        placement (str | None): 파티션 배치(문법의 ``PLACEMENT``) - ``"OFF"`` · ``"ROUNDROBIN"`` · ``"LOAD"``(0.20.2).
+            ``None`` 은 미설정(엔진이 ``OFF`` 로 친다)이고, **보낼 때는 "말하지 않았다"** 라 엔진이 저장값을 유지한다.
+            미설정으로 되돌리려면 ``"DEFAULT"`` 를 보낸다. 켜면(``ROUNDROBIN`` · ``LOAD``) ``replicas`` 가 파티션마다의 복제본
+            수가 된다. 값 검사는 엔진이 한다(``MIMQE_INVALID_PROPERTY (PLACEMENT must be OFF | ROUNDROBIN | LOAD)``).
+        autoRebalance (str | None): 배치를 켠 정의에서 브로커가 바뀔 때 저절로 다시 배치할지(``AUTOREBALANCE``) -
+            ``"ON"`` · ``"OFF"``(0.20.2). ``None`` 은 미설정(엔진이 ``ON`` 으로 친다), 보낼 때 규칙은 ``placement`` 와 같다.
         minSync (int | None): 쓰기를 받는 최소 확정 ISR 수. ``None`` 이면 엔진이 1 로 친다 -
             혼자 남은 리더도 계속 쓴다(가용성을 택하고 내구성을 내린다).
             **2 이상을 명시하면 Kafka 의 ``min.insync.replicas`` 처럼 동작한다** -
@@ -5942,6 +6212,8 @@ class ILClusterProperty(_AutoAccessor):
         self.controllerElectionTimeoutMs = None
         self.replicas = None
         self.minSync = None
+        self.placement = None
+        self.autoRebalance = None
         self.clusterId = ""
         self.status = ILC.MIMQ_STOPPED
         self.statusReason = ""
@@ -5996,6 +6268,8 @@ class ILClusterProperty(_AutoAccessor):
         self.electionDelayMs = ba_pick_int(ba, o["electionDelayMs"][0], o["electionDelayMs"][1])
         self.replicas = ba_pick_int_opt(ba, o["replicas"][0], o["replicas"][1])
         self.minSync = ba_pick_int_opt(ba, o["minSync"][0], o["minSync"][1])
+        self.placement = ba_pick_string(ba, o["placement"][0], o["placement"][1]).strip() or None
+        self.autoRebalance = ba_pick_string(ba, o["autoRebalance"][0], o["autoRebalance"][1]).strip() or None
         self.secretFile = ba_pick_string(ba, o["secretFile"][0], o["secretFile"][1])
         self.controllerLeader = ba_pick_int_opt(ba, o["controllerLeader"][0],
                                                 o["controllerLeader"][1])
@@ -6214,6 +6488,10 @@ class ILClusterProperty(_AutoAccessor):
             _v = getattr(self, _name)
             if _v is not None:              # 0 은 "0" 으로, None 은 빈칸으로
                 ba_merge(_v, ba, o[_name][0], o[_name][1])
+        for _name in ("placement", "autoRebalance"):
+            _v = getattr(self, _name)
+            if _v:                          # None / "" 은 빈칸 = 엔진이 저장값 유지
+                ba_merge(str(_v), ba, o[_name][0], o[_name][1])
         offset = _CLUSTER_LEN
         ba_merge(len(self.nodes), ba, offset, ILC.MIMQ_LIST_SIZE_LENGTH)
         offset += ILC.MIMQ_LIST_SIZE_LENGTH

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/jetstream_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.20.1
+Version: 0.20.2
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -60,6 +60,35 @@ lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치
 ## 설치 방법
 pip install jetstream-api
 
+## 0.20.2 변경 - 관제 명령 관리 API · 강제 선출 · 리더십 표 · 격리본 (자바 v2.16.2 와 같음, 짝 엔진 7.0.1.3512 이상 - 리더십 표 · 격리본 · 키 단위 강제 선출은 7.0.1.3552 이상)
+
+- **리더십 표 · 격리본**(엔진 7.0.1.3552 이상, 그 전 엔진은 `MIMQE_INVALID_REQ_CODE`):
+  - `ILAdminService.getClusterLeadTable(cluster)`(VIEW CLUSTER LEADERS, 3423): 원문. `getClusterLeadTableParsed` 는
+    `ILClusterLeadTable`(노드 · 파티션 · 묶음 행, 강제 선출 기록, 오프라인 행)로 풀어 준다. 모르는 줄은 건너뛰고, 판(`ILLT1`)이 다르면 거절.
+  - `ILAdminQmgr.getQuarantineList()` / `scanQuarantine(dir, queue, since)`(VIEW QUARANTINE, 3425 / 3426): 원문.
+  - `reinjectQuarantine(dir, queue, since)`(REINJECT, 3427): `ILQuarantineReinjectResult`(건수 · 리더 · 멈춘 사유). ☠ OLD 까지
+    넣으면 중복 가능, 넣은 건은 큐 맨 뒤에 붙는다.
+
+- **ilsc 관제 명령을 관리 API 로**(엔진이 이미 받는 요청에 클라 메서드만 없던 것):
+  - `ILAdminService.shutdownService(clusterWide=False)`(SHUTDOWN, 3002): 응답 없이 끊기면 False(엔진이 내려가며 닫음), 시간 초과는 예외.
+  - `patchService(fileName, data)`(PATCH, 3335): 성공하면 서비스가 다시 기동하고 연결이 닫힌다.
+  - `diagnoseClusterDefinition(clusterName)`(DIAG CLUSTER 의 정의 대조, 3395): 텍스트 그대로.
+  - `ILAdminQmgr.getLoadMonitoringInfo(level)`(VIEW LOAD, 3204), `reloadQueue`(RELOAD QUEUE, 3315),
+    `setChannelStartMode(channel, autoStart)`(가동 중 STARTMODE, 3035), `removeMessagesFifo(queue, count)`(앞에서부터 지우기, 3345).
+  - `ILClusterProperty.placement` / `autoRebalance`(PLACEMENT · AUTOREBALANCE): `None` 은 보낼 때 "그대로 둔다",
+    `"DEFAULT"` 는 미설정으로 되돌린다.
+
+- **내부 테스트 자동화 전용** `ILAdminService.checkForceElectLeader` / `forceElectLeader`(+ snake 별칭): 엔진 7.0.1.3551 의 운영자
+  강제 선출(`ELECT CLUSTER(C) LEADER(..) FORCE`, 요청 3422)을 관리 API 로 부른다. 확인(위험만 봄)과 실행(☠ 유실 감수)을 나눴고,
+  키(`"<토픽>/<파티션>"` / `"Q:<묶음>/0"`, 도우미 `forceElectPartitionKey` / `forceElectGroupKey`)로 하나만 강제할 수도 있다 -
+  키 단위는 엔진 7.0.1.3552 이상(그 전 엔진은 키를 버리고 노드 단위로 실행하므로 옛 엔진임이 확실하면 보내기 전에 막는다).
+  결과는 `ILClusterForceElectResult`(target · state · risk). 클라는 다시 보내지 않는다(실행의 결과 모름은 확인부터).
+  지금은 내부 시험 자동화에서만 쓴다 - 운영자의 강제 선출은 ilsc 로 한다.
+
+- `removeNode` 문서: `MIMQE_CLUSTER_NOT_COMMITTED (not committed - retry)` 는 실패가 아니라 **결과 모름**입니다(컨트롤러가 8초 안에
+  확정을 못 봄, 늦게 확정될 수 있음). 클라는 스스로 다시 보내지 않습니다. 다시 불러도 안전하고, 그때 `MIMQE_OBJECT_NOT_FOUND` 면
+  먼저 것이 확정돼 이미 빠진 것입니다. 클라 동작은 바뀌지 않습니다.
+
 ## 0.20.1 변경 - 큐 묶음 이동 중 재시도 (자바 v2.16.1 과 같음, 짝 엔진 7.0.1.3512 이상 - 묶음 이동은 7.0.1.3550 이상의 묶음 모드)
 
 - 큐 묶음 이동(엔진 7.0.1.3550 3-b3, `ALTER QUEUE … LEADERGROUP` 등)이 진행 중이면 엔진이 그 큐의 요청을

{jetstream_api-0.20.1 → jetstream_api-0.20.2}/pyproject.toml

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