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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.20.0
+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,53 @@ 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` 등)이 진행 중이면 엔진이 그 큐의 요청을
+  `MIMQE_QUEUE_MOVING (<큐> -> group <새 묶음>)` 으로 거절합니다(요청 입구에서 작업 전 - 적용 안 됨 확정). 자동 확인 세션은 이것을
+  앱에 올리지 않고 100ms → 1초로 쉬며 리더를 다시 묻고 세션 타임아웃까지 다시 보냅니다(이동은 보통 1초 안팎). 끝내 이동이 안 끝나면
+  그 사유로 실패합니다. 트랜잭션 세션은 지금처럼 올립니다(커밋이면 엔진이 롤백 - 트랜잭션을 처음부터). 0.20.0 은 이 사유를 그대로
+  올렸습니다.
+
+- 큐 속성 `leaderGroup` 문서: 큐가 하나도 없는 새 묶음으로 옮기면 첫 시도가
+  `MIMQE_QUEUE_MOVE_REFUSED (group <묶음> has no leader yet - retry)` 로 거절될 수 있습니다(엔진 7.0.1.3550 이상, 속성은 바뀌지
+  않음 - 함께 실린 다른 속성 변경도 적용되지 않는 요청 전체 거절). 관리 요청은 클라가 다시 보내지 않으니 몇 초 뒤 같은 객체로
+  `setQueueProperty` 를 다시 부릅니다. 클라 동작은 바뀌지 않습니다.
+
+- 큐 자동 확인 세션의 `get` / `gets`: "at-most-once" 라고만 적었던 것을 "**한 번만 온다고 보장하지 않는다**" 로 고쳤습니다.
+  받는 도중 수신 시간이 다하면 다시 오지 않는 것(유실)은 그대로이고, 클러스터에서는 리더 장애 순간에 받은 메시지가 새 리더에서
+  **한 번 더** 올 수 있습니다(at-least-once - 엔진 큐 묶음 리더 판 7.0.1.3550 의 규칙, 2026-10-03 결정). 중복을 견뎌야 하면 메시지
+  ID 로 거르거나 트랜잭션 세션으로 받습니다. 클라 동작은 바뀌지 않습니다.
+
 ## 0.20.0 변경 - 큐 묶음 리더 라우팅, 큐 속성 leaderGroup (자바 v2.16.0 과 같음, 짝 엔진 7.0.1.3512 이상)
 
 > 큐 묶음(LEADERGROUP) 라우팅은 엔진 **7.0.1.3540** 이상에서 묶음 모드가 켜졌을 때만 동작합니다(묶음 모드는 엔진 3-b3 에서 켜집니다).

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

@@ -10,6 +10,53 @@ 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` 등)이 진행 중이면 엔진이 그 큐의 요청을
+  `MIMQE_QUEUE_MOVING (<큐> -> group <새 묶음>)` 으로 거절합니다(요청 입구에서 작업 전 - 적용 안 됨 확정). 자동 확인 세션은 이것을
+  앱에 올리지 않고 100ms → 1초로 쉬며 리더를 다시 묻고 세션 타임아웃까지 다시 보냅니다(이동은 보통 1초 안팎). 끝내 이동이 안 끝나면
+  그 사유로 실패합니다. 트랜잭션 세션은 지금처럼 올립니다(커밋이면 엔진이 롤백 - 트랜잭션을 처음부터). 0.20.0 은 이 사유를 그대로
+  올렸습니다.
+
+- 큐 속성 `leaderGroup` 문서: 큐가 하나도 없는 새 묶음으로 옮기면 첫 시도가
+  `MIMQE_QUEUE_MOVE_REFUSED (group <묶음> has no leader yet - retry)` 로 거절될 수 있습니다(엔진 7.0.1.3550 이상, 속성은 바뀌지
+  않음 - 함께 실린 다른 속성 변경도 적용되지 않는 요청 전체 거절). 관리 요청은 클라가 다시 보내지 않으니 몇 초 뒤 같은 객체로
+  `setQueueProperty` 를 다시 부릅니다. 클라 동작은 바뀌지 않습니다.
+
+- 큐 자동 확인 세션의 `get` / `gets`: "at-most-once" 라고만 적었던 것을 "**한 번만 온다고 보장하지 않는다**" 로 고쳤습니다.
+  받는 도중 수신 시간이 다하면 다시 오지 않는 것(유실)은 그대로이고, 클러스터에서는 리더 장애 순간에 받은 메시지가 새 리더에서
+  **한 번 더** 올 수 있습니다(at-least-once - 엔진 큐 묶음 리더 판 7.0.1.3550 의 규칙, 2026-10-03 결정). 중복을 견뎌야 하면 메시지
+  ID 로 거르거나 트랜잭션 세션으로 받습니다. 클라 동작은 바뀌지 않습니다.
+
 ## 0.20.0 변경 - 큐 묶음 리더 라우팅, 큐 속성 leaderGroup (자바 v2.16.0 과 같음, 짝 엔진 7.0.1.3512 이상)
 
 > 큐 묶음(LEADERGROUP) 라우팅은 엔진 **7.0.1.3540** 이상에서 묶음 모드가 켜졌을 때만 동작합니다(묶음 모드는 엔진 3-b3 에서 켜집니다).

{jetstream_api-0.20.0 → 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.0"
+__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.0 → jetstream_api-0.20.2}/ilink/_qleader.py

@@ -108,6 +108,34 @@ def follower_hint(reason: str):
     return (tok, nid)
 
 
+def is_moving(reason: str) -> bool:
+    """큐 묶음 이동 중 거절인가(0.20.1, 엔진 3-b3).
+
+    ``MIMQE_QUEUE_MOVING (<큐> -> group <새 묶음>)`` / ``(... (node leader))`` / ``(retry shortly)``. 엔진은 요청 입구에서 작업 전에
+    거절하므로 **그 요청은 적용되지 않았다**(엔진 확인). 리더 힌트는 없다 - 이동이 끝난 뒤 3397 "Q" 로 다시 묻는다. 이동은 보통
+    1초 안팎, 최악이면 수십 초다.
+
+    Args:
+        reason (str): 엔진 사유(arg2).
+
+    Returns:
+        bool: 이동 중 거절이면 True.
+    """
+    return bool(reason) and reason.startswith("MIMQE_QUEUE_MOVING (")
+
+
+def route_rejected(reason: str) -> bool:
+    """라우팅 거절(적용 안 됨 확정)인가 - 요청 단위 팔로워 거절 또는 묶음 이동 중.
+
+    Args:
+        reason (str): 엔진 사유(arg2).
+
+    Returns:
+        bool: 둘 중 하나면 True.
+    """
+    return follower_hint(reason) is not None or is_moving(reason)
+
+
 def cross_error(have: str, want: str) -> ILOperationException:
     """한 트랜잭션에 다른 묶음 큐를 섞으려 할 때의 오류(엔진 사유와 같은 머리).
 
@@ -315,6 +343,26 @@ class QueueRouter:
         self.lookup([name])
         return True
 
+    def forget_queue(self, name: str) -> None:
+        """그 큐의 묶음 소속만 버린다 - 묶음 이동으로 소속이 바뀔 때. 다음 요청이 다시 묻는다.
+
+        Args:
+            name (str): 큐 이름.
+        """
+        with self.lock:
+            self.q_group.pop(name, None)
+
+    def on_moving(self, name: str, pause: float) -> None:
+        """묶음 이동 중 거절을 받았다 - 소속을 버리고 ``pause`` 초 쉰 뒤 다시 묻는다(0.20.1).
+
+        Args:
+            name (str): 큐 이름.
+            pause (float): 쉴 시간(초).
+        """
+        self.forget_queue(name)
+        time.sleep(pause)
+        self.lookup([name])
+
     def forget_group(self, grp: str | None) -> None:
         """그 묶음의 리더와 그 묶음 큐들의 소속을 버린다 - 다음 요청이 다시 묻는다.