jetstream-api 0.18.1__tar.gz → 0.19.3__tar.gz

{jetstream_api-0.18.1/jetstream_api.egg-info → jetstream_api-0.19.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.18.1
+Version: 0.19.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
@@ -60,6 +60,74 @@ lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치
 ## 설치 방법
 pip install jetstream-api
 
+## 0.19.3 변경 - 코디네이터 이동을 기다려 넘긴다, 문서 (자바 v2.15.3 과 같음, 짝 엔진 7.0.1.3512 이상)
+
+- `addNode` / `removeNode`: 파티션 배치(PLACEMENT)를 켠 정의에서는 `replicas` 가 파티션당 복제본 수라 노드를 더해도
+  늘리지 않고, 빼도 줄이지 않습니다(뺀 뒤 브로커 수보다 크면 그 수로 내립니다). 배치가 꺼진 정의는 전과 같이 ±1 입니다.
+- `setClusterProperty`: `replicas` 가 브로커 노드 수보다 크면 `MIMQE_INVALID_PROPERTY (REPLICAS <r> exceeds <n> data nodes)`.
+- `replicas` 에 0 을 넣어 보내면 명시한 값을 지워 미설정으로 되돌립니다(`minSync` 와 같은 규칙, 빈칸 = 그대로 둠).
+- 소비 v2: 그룹 코디네이터가 `NOT_COORDINATOR`(4175) / `LOADING`(4176) 으로 답하면 쉬었다가(100ms 부터 두 배, 1초까지)
+  10초 안에서 코디네이터를 다시 찾습니다. 끝내 안 되면 `MIMQE_NOT_AVAILABLE (group coordinator for <그룹>)` 입니다.
+  0.19.2 는 쉬지 않고 20번 뒤 4175 사유(`MIMQE_NOT_COORDINATOR (this node follows)`)를 그대로 올려, 페일오버 순간
+  코디네이터 조회가 몇 초 옛 리더를 가리키는 동안 `subscribe` 가 실패할 수 있었습니다. 커밋 조회가 끝내 안 되면 시작 위치로
+  가지 않고 거절합니다.
+
+## 0.19.2 변경 - 소비 v2(그룹 코디네이터 · 클라가 읽는 자리를 든다), 발행 다중 연결 (자바 v2.15.2 와 같음, 짝 엔진 7.0.1.3512)
+
+> 0.19.0 · 0.19.1 은 시험 저장소(test.pypi)에만 올렸고 배포하지 않았습니다 - 그 뒤 찾은 결함을 고쳐 이 판으로 냅니다:
+> `getSubscriptionList` 가 커밋 없이 배정만 받은 그룹을 빠뜨림, 클러스터 스위치백 뒤 발행이 팔로워 거절을 받은 연결에 붙어
+> 복구되지 않음(0.18.1 은 곧 복구), 페일오버 뒤 발행 연결이 옛 리더에 남음(0.19.1).
+
+> ☠ **짝 엔진은 0.18.x 이하 클라의 토픽 소비를 거절합니다** - REPORT 4157,
+> `MIMQE_UNSUPPORTED (consumer protocol v2 - upgrade client)`. 이 판과 그 엔진은 짝으로 올리십시오.
+> 옛 대응표: 저장소의 `MIGRATION-0.19.md`.
+
+- **토픽 소비가 그룹 모델로 바뀝니다.** 호출 이름과 인자는 그대로입니다(`subscribe` / `read` / `read_batch` / `commit` /
+  `commit_offset` / `seek_to_offset` / `seek_to_time` / `assign` / `close` / `unsubscribe`). 속이 바뀝니다:
+  - 구독 이름 = **그룹 이름**. 클라가 파티션별 다음 오프셋을 들고, 가입 · 하트비트 · 커밋은 그룹 코디네이터와, 읽기는 파티션
+    리더에서 합니다. 커밋 저장값은 **다음에 읽을 오프셋**입니다(`commit_offset(p, 50)` → 51).
+  - `COMMIT_AUTO` = **주기 커밋**(새 옵션 `autoCommitIntervalMs`, 기본 5초) + 재배정 직전 · `close` 때. 재전달 폭이 최대 한 주기로 넓어집니다.
+  - `COMMIT_IMMEDIATE` = 받은 배치를 건네기 전에 커밋(fetch 마다 왕복 하나). `durable(False)` = 임시 그룹(마지막 멤버가 닫을 때 그룹 삭제).
+  - `expiryMs` = read 사이 최대 시간(넘으면 클라가 스스로 그룹에서 빠지고 다음 read 에 다시 가입, 0 = 5분).
+  - `seek_*` 는 클라 위치만 바꿉니다(서버 왕복 없음, 시각은 LIST_OFFSETS). `unsubscribe` = 그룹 삭제(다른 멤버가 있으면
+    `MIMQE_GROUP_NOT_EMPTY (N active members)`).
+  - 재배정은 먼저 쥔 멤버가 다시 가입해야 넘어갑니다 - **두 번째 멤버가 배정을 받기까지 몇 초**(실측 약 6초) 걸립니다.
+  - 코디네이터 이동(4175) · 로딩(4176) · 파티션 리더 이동 · 범위 밖 오프셋은 클라가 감춥니다. 재배정 / 세대 불일치(4161 / 4178)는
+    **수동 커밋에서만 예외**로 드러납니다(`MIMQE_TOPIC_REBALANCED (...)`).
+- 구독(그룹) 이름 규칙은 엔진이 검사합니다: 빈 이름, 제어 문자, `| , : ;` 는 `MIMQE_INVALID_ARGUMENT (Group : byte 0x.. not allowed (|,:; ctrl))`
+  로 거절됩니다(한글 허용). 토픽을 지우거나 FLUSH 하면 그 토픽의 그룹 커밋도 지워집니다 - 같은 이름으로 다시 만든 토픽은 처음부터 읽습니다.
+- **관리 API 에 구독 그룹 관리가 생깁니다**: `getGroupList` · `describeGroup`(없는 그룹은 거절 없이 상태 `Dead`) · `seekGroup` ·
+  `seekGroupToTime` · `deleteGroup`(모두 **활성 멤버가 없을 때만** 옮기기 · 삭제), 정보 클래스 `ILGroupInfo` / `ILGroupMember` /
+  `ILGroupOffset` / `ILGroupDescription`. 그룹 요청은 큐 관리자 **데이터 포트**로 잠깐 연결해 보냅니다.
+- ☠ **`getSubscriptionList(topic)` 의 줄 형식이 바뀌었습니다**: `group|state|partition|commit|lag|members=N`(그룹 x 파티션).
+  그 토픽에 커밋이 있거나 그 토픽 파티션을 배정받은 멤버가 있는 그룹이 나오고(배정만 받고 커밋이 없으면 commit / lag 이 -1),
+  그런 그룹이 없으면 빈 문자열입니다. 파싱하던 코드는 고치거나 `describeGroup` 을 쓰십시오.
+- ☠ **큐 관리자 속성 `memberExpiryMinutes`(분)가 `subGroupTimeoutSec`(초, 기본 30, 1~300)으로 바뀌었습니다**(엔진
+  `SUBGROUPTIMEOUT`, 옛 `MEMBEREXPIRY` 는 없어짐). 같은 칸이고 **단위가 분에서 초로** 바뀌었습니다 - 옛 클라로 분 값(예: 5)을
+  넣으면 5초가 됩니다. 변경은 곧바로 반영되고, 이미 가입한 멤버는 다음 재가입부터 새 값을 씁니다.
+- 패턴 구독: `SYSTEM.` 으로 시작하는 내부 토픽(예: 그룹 커밋을 적는 `SYSTEM.GROUPS`)은 **패턴이 `SYSTEM.` 으로 시작할 때만**
+  잡습니다 - `*` 는 더 이상 잡지 않습니다.
+- 발행: 엔진이 파티션 리더 표를 주면 **리더 노드마다 연결을 하나씩 더 열어** 각 파티션 배치를 그 리더로 보냅니다(공개 API
+  무변경). 멱등에서 한 번도 받아들여지지 않은 파티션은 배치 하나만 응답을 기다립니다(첫 번호 틈 방지). 팔로워 거절
+  (`MIMQE_FOLLOWER_NODE`)을 받은 연결은 엔진이 그 뒤로도 거절하므로, 그 연결의 응답 대기가 끝나면 닫고 다시 엽니다 - 거절된
+  배치는 같은 번호로 새 리더(또는 다시 연 연결)에 나갑니다. 다시 붙을 때는 파티션 리더가 가장 많은 노드(페일오버 뒤 새 리더)로
+  붙고, 리더 표에 없는 연결은 한가해지면 닫습니다 - 페일오버 뒤 옛 리더에 연결이 남지 않습니다.
+
+### 0.18.2 로 예정했던 문서 정리(배포되지 않아 이 판에 함께 들어갑니다)
+
+- `setClusterProperty` / `addNode` / `removeNode` / `setCoords` 등의 `MIMQE_CLUSTER_NOT_COMMITTED` 는 괄호 속 꼬리로 가르십시오.
+  - `(not committed - retry)`: **아직 확정 안 됨 - 늦게 확정될 수 있습니다**(적용 안 됨이 아닙니다).
+  - `(outcome unknown - check VIEW CLUSTER)`: 요청을 보낸 뒤 답을 잃어 **결과를 모릅니다**.
+  - 두 경우 모두 `getClusterProperty` 로 다시 읽어 확인하고, 필요하면 **읽은 판 그대로** 다시 보내면 안전합니다(먼저 것이
+    확정됐으면 `MIMQE_CLUSTER_DEF_MOVED` 로 갈립니다). 새로 읽어 고치는 편의 함수(`addNode` 등)를 다시 부르면, 먼저 것이
+    확정됐을 때 `(qmgr or address is node N's)` 처럼 거절될 수 있습니다 - 중복은 생기지 않습니다.
+  - `(earlier change still pending - retry)`: 앞 변경이 아직 확정 전이라 **이번 것은 올리지 않았습니다** - 그대로 다시 보내도
+    안전합니다.
+- `joinCluster` 는 `createCluster` 직후 기다리지 않고 불러도 됩니다. 컨트롤러에 닿지 않으면 엔진이
+  최대 약 15초 다시 물은 뒤 `MIMQE_CLUSTER_UNREACHABLE` 로 답합니다.
+- 정지한 큐 관리자에 보낸 조회(예: `getReplicationStatus`)는 `MIMQE_QMGR_NOT_RUNNING (<큐 관리자>)` 로 거절됩니다.
+- 문서에서 개발 중인 옛 7.x 엔진 판의 동작 설명("엔진 7.0.1.35xx 전에는 ...")을 걷어 냈습니다. 설명은 최신 엔진 기준입니다.
+
 ## 0.18.1 변경 - 클러스터 정지 중 발행 결과 처리, 판사 모델 잔재 제거 (자바 v2.14.1 과 같음)
 
 - ☠ **엔진 7.0.1.3484 이상의 클러스터에서 발행한다면 0.18.1 로 올리십시오.** 그 엔진은 클러스터가 멈춘 동안의 발행에