jetstream-api 0.4.4__tar.gz → 0.5.0__tar.gz

{jetstream_api-0.4.4 → jetstream_api-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.4.4
+Version: 0.5.0
 Summary: Python client API for iLink M.O.M. (Message Oriented Middleware)
 Author: snowjeans
 License: Boost Software License - Version 1.0 - August 17th, 2003
@@ -146,13 +146,20 @@ qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
 ```
 
 접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아 캐싱하므로
-**주소는 하나만 주면 됩니다.** 목록은 첫 접속 시점의 장애까지 대비할 때 씁니다.
+**주소는 하나만 주면 됩니다.** 팔로워를 지목해도 거부에 실린 리더 힌트를 따라 자동으로
+리더에 붙으며, 이는 **단일 주소든 목록이든 마찬가지**입니다. 그때 알게 된 리더 주소는
+**후보 캐시에 들어가** 목록으로 받은 주소와 똑같이 쓰이고, `set_endpoint_cache_file()` 로
+경로를 지정해 뒀다면 파일에도 반영됩니다(이미 있으면 그대로 둡니다).
+
+목록은 **첫 접속 시점**의 장애까지 대비할 때 씁니다 — 하나만 준 그 주소가 죽어 있으면
+힌트를 줄 상대조차 없기 때문입니다.
 
 ### 0.4.4 변경 - 자동 재접속은 옵션이 아니라 기본 동작
 
 캐싱된 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한 put/get 을 페일오버
-재접속 후 **한 번 자동 재시도합니다.** `set_auto_reconnect()` 는 더 이상 필요 없으며,
-불러도 무시됩니다(기존 코드 호환용으로만 남겨 두었습니다).
+재접속 후 **한 번 자동 재시도합니다.** 켜고 끄는 설정은 없습니다
+(`set_auto_reconnect()` 는 제거했습니다 — 아무 일도 하지 않는 세터를 남겨 두면
+"껐는데 왜 재접속하냐"는 혼란만 생깁니다).
 
 | 상황 | 동작 |
 |---|---|
@@ -161,8 +168,117 @@ qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
 | endpoint 목록 없음 (비클러스터/구엔진) | 예외를 올립니다 - 갈 곳이 없습니다 |
 
 > 재시도는 **at-least-once** 입니다. 서버가 처리한 뒤 응답이 유실된 시점에 재시도하면
-> **중복 put 이 생길 수 있습니다.** 멱등하지 않은 처리라면 메시지 ID 로 중복을 걸러야
-> 합니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
+> **중복 put 이 생길 수 있습니다.** 재시도는 같은 msgId 로 나가므로 수신측에서 메시지 ID
+> 로 걸러낼 수 있습니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
+
+### 장애 전환(failover) 시 앱이 해야 할 일
+
+리더가 죽으면 새 리더가 뽑힐 때까지 **아무도 접속을 받지 않습니다.** 실측(2노드 클러스터,
+엔진 7.0.1.3341) **약 15~20초**가 걸립니다. 그 사이의 재접속 시도는 정상적으로 실패하므로,
+**한 번 실패했다고 끝내지 말고 재시도**해야 합니다.
+
+세션 종류에 따라 앱이 할 일이 갈립니다.
+
+| 세션 | 실패 시점에 미커밋 | 앱이 할 일 |
+|---|---|---|
+| auto-commit | 없음 | **아무것도 안 해도 됩니다.** 그 연산을 다시 부르기만 하면 라이브러리가 재접속·재시도합니다 |
+| transacted | 없음 | 위와 같습니다 |
+| transacted | 있음 | `reconnect()` 로 자리를 옮기고 **트랜잭션을 처음부터 다시** 수행해야 합니다 |
+
+`access_queue()` 는 **자동 재접속 대상이 아닙니다.** 끊긴 세션에서 부르면 그대로 실패하니,
+재접속에 성공한 **뒤에** 핸들을 다시 얻으십시오. 기존 핸들을 계속 쓰는 쪽은 스스로 복구됩니다.
+
+#### (1) 트랜잭션 재수행이 필요 없는 경우 — auto-commit
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")   # 재기동 대비(선택)
+q.connect("10.0.0.1", 5000, "collector", True)                    # auto-commit
+queue = q.access_queue("APP.EVENTS")                              # 핸들은 한 번만 얻는다
+
+def publish(payload):
+    """페일오버가 나도 이 함수는 그대로 둔다 - 라이브러리가 복구한다."""
+    for attempt in range(1, 11):
+        try:
+            return queue.put(payload)          # 실패하면 내부에서 재접속 + 1회 재시도
+        except ILOperationException:
+            raise                              # 서버가 거절 - 재시도해도 같다
+        except (ILException, ILSessionException):
+            if attempt == 10:
+                raise                          # 승격이 20초 넘게 안 끝났다
+            time.sleep(3)                      # 리더 승격을 기다렸다가 다시
+```
+
+앱 코드에 `reconnect()` 가 없다는 점이 요지입니다. 같은 큐 핸들로 `put` 을 다시 부르기만
+하면, 승격이 끝난 시점의 호출이 새 리더에 붙어 성공합니다(실측 20.6초에 복구).
+
+#### (2) 트랜잭션 재수행이 필요한 경우 — transacted
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+MAX_RETRY = 10
+
+def process_batch(records):
+    """한 번의 트랜잭션 = 전부 커밋되거나 전부 없던 일이 된다."""
+    q = ILQmgr()
+    q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+    q.connect("10.0.0.1", 5000, "billing-svc", False)      # transacted
+    try:
+        for attempt in range(1, MAX_RETRY + 1):
+            try:
+                queue = q.access_queue("APP.ORDERS")       # 재접속 뒤 핸들을 다시 얻는다
+                for rec in records:
+                    queue.put(rec)
+                q.commit()                                 # 여기까지 와야 확정된다
+                return
+            except ILOperationException:
+                q.rollback()                               # 서버 거절 - 재시도 무의미
+                raise
+            except (ILException, ILSessionException):
+                if attempt == MAX_RETRY:
+                    raise
+                try:
+                    q.reconnect()                          # 승격 전이면 여기서 또 실패한다
+                except Exception:
+                    time.sleep(3)                          # 기다렸다가 다음 회차에 다시
+                # 루프 처음으로 -> 배치 전체를 다시 넣는다
+    finally:
+        q.disconnect()
+```
+
+읽어야 할 포인트 셋입니다.
+
+1. **재시도 단위는 트랜잭션 전체**입니다. 실패 지점부터 이어붙이면 안 됩니다 — 앞서 넣은
+   것들도 커밋되지 않았으므로 함께 사라집니다(실측: 미커밋 1건 유실, 재수행 후 depth 2 정상).
+2. **`reconnect()` 자체가 실패할 수 있습니다.** 승격 전에 부르면 실패하는 게 정상이라,
+   루프 안에서 간격을 두고 다시 불러야 합니다(실측 2번째 시도, 16.5초에 성공).
+3. **`ILOperationException` 과 통신 예외를 갈라 잡습니다.** 전자는 서버가 판단해 거절한
+   것이라 재시도가 무의미하고, 후자만 재접속 대상입니다. 파이썬의 예외 클래스는 평면
+   구조라 `ILSessionException` 은 `ILException` 의 하위 타입이 **아닙니다** — 통신 장애를
+   잡으려면 **둘 다** 적어야 합니다(자바는 모두 `ILException` 으로 감싸므로 하나면 됩니다).
+
+#### 앱이 재기동되는 경우
+
+캐싱은 메모리에만 있으므로 프로세스가 죽으면 사라집니다. 설정에 남은 옛 리더 주소로 다시
+붙을 때 이렇게 갈립니다.
+
+| 옛 리더의 상태 | 결과 |
+|---|---|
+| 살아 있고 **팔로워로 강등** | 그 노드가 리더 힌트를 주므로 **자동으로 새 리더에 접속** |
+| **죽어 있음** | 갈 곳이 없어 실패 — `set_endpoint_cache_file()` 을 쓰거나 주소를 목록으로 주십시오 |
+
+```python
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+q.connect("10.0.0.1", 5000, "APP", True)   # 이 주소가 죽어 있어도 파일 후보로 붙는다
+```
 
 ## 0.4.0 신규 - 관리 연결 하나로 pub/sub
 

{jetstream_api-0.4.4 → jetstream_api-0.5.0}/README.md

@@ -100,13 +100,20 @@ qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
 ```
 
 접속에 성공하면 핸드셰이크 직후 나머지 노드 주소를 서버에서 받아 캐싱하므로
-**주소는 하나만 주면 됩니다.** 목록은 첫 접속 시점의 장애까지 대비할 때 씁니다.
+**주소는 하나만 주면 됩니다.** 팔로워를 지목해도 거부에 실린 리더 힌트를 따라 자동으로
+리더에 붙으며, 이는 **단일 주소든 목록이든 마찬가지**입니다. 그때 알게 된 리더 주소는
+**후보 캐시에 들어가** 목록으로 받은 주소와 똑같이 쓰이고, `set_endpoint_cache_file()` 로
+경로를 지정해 뒀다면 파일에도 반영됩니다(이미 있으면 그대로 둡니다).
+
+목록은 **첫 접속 시점**의 장애까지 대비할 때 씁니다 — 하나만 준 그 주소가 죽어 있으면
+힌트를 줄 상대조차 없기 때문입니다.
 
 ### 0.4.4 변경 - 자동 재접속은 옵션이 아니라 기본 동작
 
 캐싱된 endpoint 목록이 있으면(= 클러스터) 통신 장애로 실패한 put/get 을 페일오버
-재접속 후 **한 번 자동 재시도합니다.** `set_auto_reconnect()` 는 더 이상 필요 없으며,
-불러도 무시됩니다(기존 코드 호환용으로만 남겨 두었습니다).
+재접속 후 **한 번 자동 재시도합니다.** 켜고 끄는 설정은 없습니다
+(`set_auto_reconnect()` 는 제거했습니다 — 아무 일도 하지 않는 세터를 남겨 두면
+"껐는데 왜 재접속하냐"는 혼란만 생깁니다).
 
 | 상황 | 동작 |
 |---|---|
@@ -115,8 +122,117 @@ qmgr.connect("10.0.0.1:5000,10.0.0.2:5000", "APP", True)
 | endpoint 목록 없음 (비클러스터/구엔진) | 예외를 올립니다 - 갈 곳이 없습니다 |
 
 > 재시도는 **at-least-once** 입니다. 서버가 처리한 뒤 응답이 유실된 시점에 재시도하면
-> **중복 put 이 생길 수 있습니다.** 멱등하지 않은 처리라면 메시지 ID 로 중복을 걸러야
-> 합니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
+> **중복 put 이 생길 수 있습니다.** 재시도는 같은 msgId 로 나가므로 수신측에서 메시지 ID
+> 로 걸러낼 수 있습니다. 미커밋 트랜잭션이 없을 때만 재시도하므로 트랜잭션 유실은 없습니다.
+
+### 장애 전환(failover) 시 앱이 해야 할 일
+
+리더가 죽으면 새 리더가 뽑힐 때까지 **아무도 접속을 받지 않습니다.** 실측(2노드 클러스터,
+엔진 7.0.1.3341) **약 15~20초**가 걸립니다. 그 사이의 재접속 시도는 정상적으로 실패하므로,
+**한 번 실패했다고 끝내지 말고 재시도**해야 합니다.
+
+세션 종류에 따라 앱이 할 일이 갈립니다.
+
+| 세션 | 실패 시점에 미커밋 | 앱이 할 일 |
+|---|---|---|
+| auto-commit | 없음 | **아무것도 안 해도 됩니다.** 그 연산을 다시 부르기만 하면 라이브러리가 재접속·재시도합니다 |
+| transacted | 없음 | 위와 같습니다 |
+| transacted | 있음 | `reconnect()` 로 자리를 옮기고 **트랜잭션을 처음부터 다시** 수행해야 합니다 |
+
+`access_queue()` 는 **자동 재접속 대상이 아닙니다.** 끊긴 세션에서 부르면 그대로 실패하니,
+재접속에 성공한 **뒤에** 핸들을 다시 얻으십시오. 기존 핸들을 계속 쓰는 쪽은 스스로 복구됩니다.
+
+#### (1) 트랜잭션 재수행이 필요 없는 경우 — auto-commit
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")   # 재기동 대비(선택)
+q.connect("10.0.0.1", 5000, "collector", True)                    # auto-commit
+queue = q.access_queue("APP.EVENTS")                              # 핸들은 한 번만 얻는다
+
+def publish(payload):
+    """페일오버가 나도 이 함수는 그대로 둔다 - 라이브러리가 복구한다."""
+    for attempt in range(1, 11):
+        try:
+            return queue.put(payload)          # 실패하면 내부에서 재접속 + 1회 재시도
+        except ILOperationException:
+            raise                              # 서버가 거절 - 재시도해도 같다
+        except (ILException, ILSessionException):
+            if attempt == 10:
+                raise                          # 승격이 20초 넘게 안 끝났다
+            time.sleep(3)                      # 리더 승격을 기다렸다가 다시
+```
+
+앱 코드에 `reconnect()` 가 없다는 점이 요지입니다. 같은 큐 핸들로 `put` 을 다시 부르기만
+하면, 승격이 끝난 시점의 호출이 새 리더에 붙어 성공합니다(실측 20.6초에 복구).
+
+#### (2) 트랜잭션 재수행이 필요한 경우 — transacted
+
+```python
+import time
+from ilink.qmgr import ILQmgr
+from ilink.exception import ILException, ILSessionException, ILOperationException
+
+MAX_RETRY = 10
+
+def process_batch(records):
+    """한 번의 트랜잭션 = 전부 커밋되거나 전부 없던 일이 된다."""
+    q = ILQmgr()
+    q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+    q.connect("10.0.0.1", 5000, "billing-svc", False)      # transacted
+    try:
+        for attempt in range(1, MAX_RETRY + 1):
+            try:
+                queue = q.access_queue("APP.ORDERS")       # 재접속 뒤 핸들을 다시 얻는다
+                for rec in records:
+                    queue.put(rec)
+                q.commit()                                 # 여기까지 와야 확정된다
+                return
+            except ILOperationException:
+                q.rollback()                               # 서버 거절 - 재시도 무의미
+                raise
+            except (ILException, ILSessionException):
+                if attempt == MAX_RETRY:
+                    raise
+                try:
+                    q.reconnect()                          # 승격 전이면 여기서 또 실패한다
+                except Exception:
+                    time.sleep(3)                          # 기다렸다가 다음 회차에 다시
+                # 루프 처음으로 -> 배치 전체를 다시 넣는다
+    finally:
+        q.disconnect()
+```
+
+읽어야 할 포인트 셋입니다.
+
+1. **재시도 단위는 트랜잭션 전체**입니다. 실패 지점부터 이어붙이면 안 됩니다 — 앞서 넣은
+   것들도 커밋되지 않았으므로 함께 사라집니다(실측: 미커밋 1건 유실, 재수행 후 depth 2 정상).
+2. **`reconnect()` 자체가 실패할 수 있습니다.** 승격 전에 부르면 실패하는 게 정상이라,
+   루프 안에서 간격을 두고 다시 불러야 합니다(실측 2번째 시도, 16.5초에 성공).
+3. **`ILOperationException` 과 통신 예외를 갈라 잡습니다.** 전자는 서버가 판단해 거절한
+   것이라 재시도가 무의미하고, 후자만 재접속 대상입니다. 파이썬의 예외 클래스는 평면
+   구조라 `ILSessionException` 은 `ILException` 의 하위 타입이 **아닙니다** — 통신 장애를
+   잡으려면 **둘 다** 적어야 합니다(자바는 모두 `ILException` 으로 감싸므로 하나면 됩니다).
+
+#### 앱이 재기동되는 경우
+
+캐싱은 메모리에만 있으므로 프로세스가 죽으면 사라집니다. 설정에 남은 옛 리더 주소로 다시
+붙을 때 이렇게 갈립니다.
+
+| 옛 리더의 상태 | 결과 |
+|---|---|
+| 살아 있고 **팔로워로 강등** | 그 노드가 리더 힌트를 주므로 **자동으로 새 리더에 접속** |
+| **죽어 있음** | 갈 곳이 없어 실패 — `set_endpoint_cache_file()` 을 쓰거나 주소를 목록으로 주십시오 |
+
+```python
+q = ILQmgr()
+q.set_endpoint_cache_file("/var/run/myapp/ilink-endpoints.txt")
+q.connect("10.0.0.1", 5000, "APP", True)   # 이 주소가 죽어 있어도 파일 후보로 붙는다
+```
 
 ## 0.4.0 신규 - 관리 연결 하나로 pub/sub
 

{jetstream_api-0.4.4 → jetstream_api-0.5.0}/ilink/__init__.py

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.4.4"
+__version__ = "0.5.0"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser