jetstream-api 0.3.0__tar.gz → 0.4.0__tar.gz

{jetstream_api-0.3.0/jetstream_api.egg-info → jetstream_api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.3.0
+Version: 0.4.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
@@ -147,6 +147,53 @@ qmgr.reconnect()                  # 새 리더를 찾아 재접속
 > (`reconnect()` 직접 호출은 가능합니다). auto-commit 세션도 응답 유실 시점의 재시도로
 > **중복 put이 발생할 수 있습니다.**
 
+## 0.4.0 신규 - 관리 연결 하나로 pub/sub
+
+`ILAdminService`(관리 포트, 보통 9998) 연결만으로 토픽 발행·구독이 가능합니다.
+큐 관리자 리스너 포트에 따로 붙지 않아도 되므로, **방화벽이 관리 포트만 열린 환경**에서
+쓸 수 있습니다.
+
+> 엔진 v7.0.1 rev 3295 이상이 필요합니다.
+
+```python
+from ilink.admin import ILAdminService
+from ilink.exception import ILNoMsgException
+from ilink.topic import ILSubscribeOptions, ILTopic
+
+svc = ILAdminService()
+svc.connect("127.0.0.1", 9998, "admin-app")
+aq = svc.accessAdminQmgr("QM1")
+
+# 발행 - (offset, timestamp, partition)
+off, ts, part = aq.publish("ORDER.EVENT", b"payload", key="order-1")
+
+# 구독
+topic = aq.accessTopic("ORDER.EVENT")
+sub = topic.subscribe("audit", ILSubscribeOptions()
+                      .startMode(ILTopic.START_EARLIEST)
+                      .commitMode(ILTopic.COMMIT_MANUAL))
+try:
+    while True:
+        try:
+            msg = sub.read(3000)
+        except ILNoMsgException:
+            break
+        print(msg.get_offset(), msg.get_key(), msg.get_data_string())
+        sub.commit(msg)
+finally:
+    sub.close()
+```
+
+패턴(와일드카드) 구독도 같은 연결로 됩니다.
+
+```python
+ps = aq.accessPattern("ORDER.*").subscribe("audit")
+```
+
+> **제약**: 관리 연결에는 배치가 없어 **레코드 한 건에 한 번 왕복**합니다. 멱등 발행도
+> 지원되지 않습니다(acks=1 고정). 대량 처리나 중복 제거가 필요하면 리스너 포트에
+> `ILQmgr` 로 붙어 `ILTopicProducer` 를 쓰세요.
+
 ## 0.3.0 신규 - 허브-스포크 연결 전환 헬퍼
 
 허브에 접속해 스포크를 찾고 연결을 전환하는 세 단계를 한 번에 처리하는
@@ -218,7 +265,7 @@ sub = topic.assign("app1", [0, 2], ILTopic.START_EARLIEST)   # 수동 파티션
 
 ## 개발자 가이드 문서
 
-**공개 API 756개 전부에 한국어 docstring이 붙어 있습니다.** 편집기에서 함수 위에
+**공개 API 779개 전부에 한국어 docstring이 붙어 있습니다.** 편집기에서 함수 위에
 마우스를 올리거나 `help()`로 파라미터 타입·기본값·허용값·예외를 바로 확인할 수 있습니다.
 
 ```python

{jetstream_api-0.3.0 → jetstream_api-0.4.0}/README.md

@@ -101,6 +101,53 @@ qmgr.reconnect()                  # 새 리더를 찾아 재접속
 > (`reconnect()` 직접 호출은 가능합니다). auto-commit 세션도 응답 유실 시점의 재시도로
 > **중복 put이 발생할 수 있습니다.**
 
+## 0.4.0 신규 - 관리 연결 하나로 pub/sub
+
+`ILAdminService`(관리 포트, 보통 9998) 연결만으로 토픽 발행·구독이 가능합니다.
+큐 관리자 리스너 포트에 따로 붙지 않아도 되므로, **방화벽이 관리 포트만 열린 환경**에서
+쓸 수 있습니다.
+
+> 엔진 v7.0.1 rev 3295 이상이 필요합니다.
+
+```python
+from ilink.admin import ILAdminService
+from ilink.exception import ILNoMsgException
+from ilink.topic import ILSubscribeOptions, ILTopic
+
+svc = ILAdminService()
+svc.connect("127.0.0.1", 9998, "admin-app")
+aq = svc.accessAdminQmgr("QM1")
+
+# 발행 - (offset, timestamp, partition)
+off, ts, part = aq.publish("ORDER.EVENT", b"payload", key="order-1")
+
+# 구독
+topic = aq.accessTopic("ORDER.EVENT")
+sub = topic.subscribe("audit", ILSubscribeOptions()
+                      .startMode(ILTopic.START_EARLIEST)
+                      .commitMode(ILTopic.COMMIT_MANUAL))
+try:
+    while True:
+        try:
+            msg = sub.read(3000)
+        except ILNoMsgException:
+            break
+        print(msg.get_offset(), msg.get_key(), msg.get_data_string())
+        sub.commit(msg)
+finally:
+    sub.close()
+```
+
+패턴(와일드카드) 구독도 같은 연결로 됩니다.
+
+```python
+ps = aq.accessPattern("ORDER.*").subscribe("audit")
+```
+
+> **제약**: 관리 연결에는 배치가 없어 **레코드 한 건에 한 번 왕복**합니다. 멱등 발행도
+> 지원되지 않습니다(acks=1 고정). 대량 처리나 중복 제거가 필요하면 리스너 포트에
+> `ILQmgr` 로 붙어 `ILTopicProducer` 를 쓰세요.
+
 ## 0.3.0 신규 - 허브-스포크 연결 전환 헬퍼
 
 허브에 접속해 스포크를 찾고 연결을 전환하는 세 단계를 한 번에 처리하는
@@ -172,7 +219,7 @@ sub = topic.assign("app1", [0, 2], ILTopic.START_EARLIEST)   # 수동 파티션
 
 ## 개발자 가이드 문서
 
-**공개 API 756개 전부에 한국어 docstring이 붙어 있습니다.** 편집기에서 함수 위에
+**공개 API 779개 전부에 한국어 docstring이 붙어 있습니다.** 편집기에서 함수 위에
 마우스를 올리거나 `help()`로 파라미터 타입·기본값·허용값·예외를 바로 확인할 수 있습니다.
 
 ```python

{jetstream_api-0.3.0 → jetstream_api-0.4.0}/ilink/__init__.py

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

{jetstream_api-0.3.0 → jetstream_api-0.4.0}/ilink/admin.py

@@ -1154,7 +1154,7 @@ class ILAdminService:
 
         Warning:
             **세션 회수는 비동기다.** 클라이언트가 :meth:`disconnect` 로 정상 종료해도
-            그 세션이 목록에서 곧바로 사라지지 않는다 - 실측(10.10.1.95 허브) 약 **1초**
+            그 세션이 목록에서 곧바로 사라지지 않는다 - 실측(127.0.0.1 허브) 약 **1초**
             동안 ``getStatus()`` 가 여전히 ``1``, ``getDestroyedTime()`` 이 ``-1`` 인
             채로 남아 있다가 사라진다. 끊긴 것을 확인하려면 **한 번 조회로 단정하지 말고
             잠시 기다렸다 다시 조회하라.**
@@ -1459,13 +1459,13 @@ class ILAdminService:
             조회하거나 지울 수 없다는 뜻이다.
 
         Note:
-            실측(10.10.1.95 허브, 스포크 2대): 전환 자체는 **20~45ms**, 전환 뒤 요청의
+            실측(127.0.0.1 허브, 스포크 2대): 전환 자체는 **20~45ms**, 전환 뒤 요청의
             릴레이 오버헤드는 **측정되지 않는 수준**이다(``getQmgrList`` 중앙값 릴레이
             18.3ms vs 허브 직결 18.4ms). ``timeoutSec`` 은 0 이나 1 을 줘도 성공했다.
 
         Example::
 
-            svc.connect("10.10.1.95", 9998, "ADMIN")
+            svc.connect("127.0.0.1", 9998, "ADMIN")
             for sp in svc.getSpokeList():
                 if sp.getName() == "S48":
                     svc.spokeSwitchTo(sp.getKey(), 10)
@@ -1509,8 +1509,7 @@ class ILAdminService:
 
         Raises:
             ILOperationException: 그런 이름의 스포크가 없거나 전환이 거절됐을 때.
-                없는 이름이면 ``MIMQE_OBJECT_NOT_FOUND (spoke: 이름)`` 이다 -
-                Java 와 사유 코드를 맞추려고 엔진 관례의 접두사를 쓴다.
+                없는 이름이면 ``MIMQE_OBJECT_NOT_FOUND (spoke: 이름)`` 이다.
             ILSessionException: 허브에 접속하지 못했을 때.
             ILException: 그 밖의 통신 실패.
 
@@ -1525,7 +1524,7 @@ class ILAdminService:
         Example::
 
             for name in ("S48", "S85"):
-                svc = ILAdminService.connectToSpoke("10.10.1.95", 9998, "ADMIN", name)
+                svc = ILAdminService.connectToSpoke("127.0.0.1", 9998, "ADMIN", name)
                 try:
                     print(name, [q.getName() for q in svc.getQmgrList()])
                 finally:
@@ -2116,12 +2115,9 @@ class ILAdminQmgr:
             **트레이스를 켜면 로그가 급격히 늘어난다** - 장애 분석 때만 쓰라.
             특정 세션만 보려면 :meth:`setSessionTrace` 가 부담이 적다.
 
-        .. warning:: Java 와 의도적으로 다르다
-
-            Java 는 성공 코드 자리에 ``MIMQ_NOT_SUCCESSFUL_*`` 을 넘겨 **판정이
-            뒤집혀 있다** - 성공하면 빈 사유로 예외가 나고, 실패하면 조용히 통과한다.
-            파이썬은 ``MIMQ_SUCCESSFUL_*`` 로 바로잡았다(실서버 확인: 성공 4208 /
-            실패 4209). **Java 쪽도 고쳐야 한다.**
+        Note:
+            성공 판정은 ``MIMQ_SUCCESSFUL_*`` 응답으로 한다(실서버 확인: 성공 4208 /
+            실패 4209).
         """
         try:
             self.service.request(
@@ -2249,12 +2245,9 @@ class ILAdminQmgr:
         Note:
             큐 관리자 전체(:meth:`setSystemTrace`)보다 로그 부담이 훨씬 적다.
 
-        .. warning:: Java 와 의도적으로 다르다
-
-            Java 는 성공 코드 자리에 ``MIMQ_NOT_SUCCESSFUL_*`` 을 넘겨 **판정이
-            뒤집혀 있다** - 성공하면 빈 사유로 예외가 나고, 실패하면 조용히 통과한다.
-            파이썬은 ``MIMQ_SUCCESSFUL_*`` 로 바로잡았다(실서버 확인: 성공 4208 /
-            실패 4209). **Java 쪽도 고쳐야 한다.**
+        Note:
+            성공 판정은 ``MIMQ_SUCCESSFUL_*`` 응답으로 한다(실서버 확인: 성공 4208 /
+            실패 4209).
         """
         try:
             self.service.request(
@@ -2940,12 +2933,9 @@ class ILAdminQmgr:
                 p.setTraceEnabled(True)
                 qmgr.setQueueProperty(p)
 
-        .. warning:: Java 와 의도적으로 다르다
-
-            Java 는 성공 코드 자리에 ``MIMQ_NOT_SUCCESSFUL_*`` 을 넘겨 **판정이
-            뒤집혀 있다** - 성공하면 빈 사유로 예외가 나고, 실패하면 조용히 통과한다.
-            파이썬은 ``MIMQ_SUCCESSFUL_*`` 로 바로잡았다(실서버 확인: 성공 4208 /
-            실패 4209). **Java 쪽도 고쳐야 한다.**
+        Note:
+            성공 판정은 ``MIMQ_SUCCESSFUL_*`` 응답으로 한다(실서버 확인: 성공 4208 /
+            실패 4209).
         """
         try:
             self.service.request(
@@ -3803,12 +3793,9 @@ class ILAdminQmgr:
         Note:
             채널이 붙지 않거나 자꾸 끊길 때 원인을 보는 데 쓴다.
 
-        .. warning:: Java 와 의도적으로 다르다
-
-            Java 는 성공 코드 자리에 ``MIMQ_NOT_SUCCESSFUL_*`` 을 넘겨 **판정이
-            뒤집혀 있다** - 성공하면 빈 사유로 예외가 나고, 실패하면 조용히 통과한다.
-            파이썬은 ``MIMQ_SUCCESSFUL_*`` 로 바로잡았다(실서버 확인: 성공 4208 /
-            실패 4209). **Java 쪽도 고쳐야 한다.**
+        Note:
+            성공 판정은 ``MIMQ_SUCCESSFUL_*`` 응답으로 한다(실서버 확인: 성공 4208 /
+            실패 4209).
         """
         try:
             self.service.request(
@@ -3836,12 +3823,9 @@ class ILAdminQmgr:
             ILOperationException: 그런 채널이 없거나 서버가 거절했을 때.
             ILException: 통신 실패.
 
-        .. warning:: Java 와 의도적으로 다르다
-
-            Java 는 성공 코드 자리에 ``MIMQ_NOT_SUCCESSFUL_*`` 을 넘겨 **판정이
-            뒤집혀 있다** - 성공하면 빈 사유로 예외가 나고, 실패하면 조용히 통과한다.
-            파이썬은 ``MIMQ_SUCCESSFUL_*`` 로 바로잡았다(실서버 확인: 성공 4208 /
-            실패 4209). **Java 쪽도 고쳐야 한다.**
+        Note:
+            성공 판정은 ``MIMQ_SUCCESSFUL_*`` 응답으로 한다(실서버 확인: 성공 4208 /
+            실패 4209).
         """
         try:
             self.service.request(
@@ -4261,9 +4245,7 @@ class ILAdminQmgr:
             **토픽을 보려면 반드시 ``objectType`` 을 지정하라.**
 
         Note:
-            자바 API 는 ``createObjectLogBrowser(objectType, objectName)`` 순서지만,
-            여기서는 기존 호출부(``createObjectLogBrowser("TEST.LQ")``)를 깨지 않으려고
-            **이름을 먼저** 받는다.
+            인자 순서는 **이름이 먼저**다 - ``createObjectLogBrowser("TEST.LQ")``.
 
         Example::
 
@@ -5057,6 +5039,151 @@ class ILAdminQmgr:
         except Exception as exc:
             raise ILException(exc) from exc
 
+    # ── 관리 연결 pub/sub (엔진 rev 3295+) ─────────────────────────────
+    def _relayTopic(self, code: int, ext, *args):
+        """토픽 요청을 큐 관리자로 릴레이한다(내부용).
+
+        관리 연결은 요청에 **대상 큐 관리자 이름**을 실어야 ilsvc 가 릴레이한다.
+        """
+        return self.service.inquire_data_or_report(self.qmgrName, code, ext, *args)
+
+    def get_qmgr_name(self) -> str:
+        """이 핸들이 다루는 큐 관리자 이름.
+
+        Returns:
+            str: 큐 관리자 이름.
+        """
+        return self.qmgrName
+
+    def list_topic_names(self) -> list[str]:
+        """토픽 이름만 뽑아 목록으로 돌려준다.
+
+        Returns:
+            list[str]: 토픽 이름 목록. 없으면 빈 목록.
+
+        Raises:
+            ILOperationException: 서버가 조회를 거절했을 때.
+            ILException: 통신 실패.
+
+        Note:
+            :meth:`getTopicList` 가 돌려주는 ``|`` 구분 원문에서 첫 필드만 모은 것이다.
+            오프셋이나 파티션 수까지 필요하면 :meth:`getTopicList` 를 쓰라.
+        """
+        raw = self.getTopicList() or ""
+        return [ln.split("|", 1)[0] for ln in raw.split("\n") if ln.strip()]
+
+    def accessTopic(self, topicName: str, existCheck: bool = True) -> "ILAdminTopic":
+        """**관리 연결로** 다룰 토픽 핸들을 얻는다.
+
+        큐 관리자 리스너 포트에 따로 붙지 않고 관리 포트 연결을 그대로 쓴다.
+        방화벽이 관리 포트만 열린 환경에서 발행/구독을 할 때 쓴다.
+
+        Args:
+            topicName (str): 토픽 이름.
+            existCheck (bool): True(기본)면 토픽이 있는지 먼저 확인한다.
+
+        Returns:
+            ILAdminTopic: 발행과 구독을 함께 하는 토픽 핸들.
+
+        Raises:
+            ILOperationException: ``existCheck=True`` 인데 토픽이 없을 때.
+            ILException: 통신 실패.
+
+        Warning:
+            관리 연결에는 **배치가 없다.** 레코드 한 건에 한 번 왕복하므로 대량
+            소비/발행에는 맞지 않는다. 처리량이 필요하면 리스너 포트에
+            :class:`~ilink.qmgr.ILQmgr` 로 붙으라.
+
+        Note:
+            엔진 **rev 3295 이상**이 필요하다.
+
+        Example::
+
+            aq = svc.accessAdminQmgr("QM1")
+            topic = aq.accessTopic("ORDER.EVENT")
+
+            off, ts, part = topic.publish(b"payload", key="k1")
+
+            sub = topic.subscribe("audit")
+            try:
+                msg = sub.read(3000)
+                print(msg.get_offset(), msg.get_data_string())
+                sub.commit(msg)
+            finally:
+                sub.close()
+        """
+        from .admintopic import ILAdminTopic
+        return ILAdminTopic(self, topicName, existCheck)
+
+    def accessPattern(self, pattern: str):
+        """**관리 연결로** 다룰 토픽 패턴 핸들을 얻는다.
+
+        Args:
+            pattern (str): 글롭 패턴(예 ``"ORDER.*"``). ``*`` 는 0자 이상으로
+                구분자 ``.`` 도 삼키고, ``?`` 는 1자다. 비우면 거부한다.
+
+        Returns:
+            ILTopicPattern: 패턴 핸들. **이 시점에는 서버와 통신하지 않는다.**
+
+        Raises:
+            ILOperationException: 패턴이 비었을 때.
+
+        Warning:
+            관리 연결에는 배치 read 가 없어, 패턴 구독도 하위 토픽을 **한 건씩**
+            훑는다. 매칭 토픽이 많으면 왕복 수가 그만큼 늘어난다.
+
+        Example::
+
+            pat = aq.accessPattern("ORDER.*")
+            print(pat.resolve())                  # 구독 전 오타 확인
+
+            ps = pat.subscribe("audit")
+            try:
+                for msg in ps.read_batch(10, 3000):
+                    print(msg.get_topic_name(), msg.get_offset())
+                ps.commit_sync()
+            finally:
+                ps.close()
+        """
+        from .pattern import ILTopicPattern
+        return ILTopicPattern(self, pattern)
+
+    def publish(self, topicName: str, value: bytes, key: str = "",
+                partition: int | None = None) -> tuple[int, int, int]:
+        """관리 연결로 레코드 **한 건**을 발행한다.
+
+        :meth:`accessTopic` 없이 바로 한 건 보낼 때 쓰는 지름길이다.
+
+        Args:
+            topicName (str): 대상 토픽 이름.
+            value (bytes): payload. 빈 값도 허용한다(컴팩션 tombstone).
+            key (str): 파티션 라우팅 키. **UTF-8 69바이트 이하.** 비우면 서버가 고른다.
+            partition (int | None): 파티션 직접 지정. None(기본)이면 서버가 정한다.
+
+        Returns:
+            tuple[int, int, int]: ``(offset, timestamp, partition)``.
+            timestamp 는 epoch 밀리초.
+
+        Raises:
+            ILOperationException: 토픽이 없거나 키가 69바이트를 넘거나 서버가 거절했을 때.
+            ILException: 통신 실패.
+
+        Warning:
+            **멱등 발행이 아니다.** 재시도하면 중복이 생길 수 있다.
+
+        Note:
+            엔진 **rev 3295 이상**이 필요하다.
+
+        Example::
+
+            off, ts, part = aq.publish("ORDER.EVENT", b"payload", key="k1")
+        """
+        return self.accessTopic(topicName, False).publish(value, key, partition)
+
+    access_topic = accessTopic
+    access_pattern = accessPattern
+    getQmgrName = get_qmgr_name
+
     # snake_case 별칭 (이 패키지 관례 - 두 표기를 모두 제공한다)
     def create_topic(self, topic_name: str, options: str = "") -> None:
         """:meth:`createTopic` 의 snake 별칭."""