jetstream-api 0.21.12__tar.gz → 0.22.0__tar.gz

{jetstream_api-0.21.12 → jetstream_api-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jetstream-api
-Version: 0.21.12
+Version: 0.22.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
@@ -60,6 +60,25 @@ lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치
 ## 설치 방법
 pip install jetstream-api
 
+## 0.22.0 변경 - 7 신규 오브젝트(쿼터 · 디스크 가드 · 토픽 · 클러스터) 관리를 Property v2(JSON)로 (자바 v2.18.0 와 같음, 짝 엔진 7.0.1.3601 이상)
+
+- **와이어**: 쿼터 · 디스크 가드 · 토픽 · 클러스터의 생성 · 조회 · 목록 · 변경 · 삭제가 새 요청 코드 3600~3604(본문 = UTF-8 JSON)로 간다.
+  ★ 이 네 오브젝트는 **엔진 7.0.1.3601 이상에서만** 된다(엔진이 옛 코드를 지웠다). 6.x 엔진에는 원래 없는 기능이라 보내지 않고
+  ``MIMQE_NOT_SUPPORTED (... requires ILink 7)`` 로 거절한다. 큐 · 채널 · 큐 관리자 · 세션 등 6.x 오브젝트와 데이터 경로는 바뀌지 않았다.
+- **바꾼 값만 보낸다(patch)**: ``setQuotaProperty`` · ``setDiskGuardProperty`` · ``setClusterProperty`` 는 **세터(또는 필드 대입)로 바꾼
+  칸만** 보낸다. 조회한 객체를 그대로 넘기면 아무것도 보내지 않는다. 쿼터 클라 항목 · 클러스터 노드 목록은 바뀌면 통째로 간다.
+  클러스터는 읽은 정의 판(defTerm, defVersion)을 낙관적 잠금으로 자동으로 싣는다.
+- **새 함수 - 결과를 돌려준다**: ``setQuotaPropertyWithResult`` · ``setDiskGuardPropertyWithResult`` · ``setClusterPropertyWithResult`` ·
+  ``createTopicWithResult`` · ``setTopicPropertyWithResult`` · ``removeTopicWithResult`` -> :class:`ILPropertyResult`(적용된 키와 반영 시점 ·
+  무시된 키와 까닭 · 바꿔 받은 값 · 조작별 결과). 무시된 키가 있으면 기존 함수도 WARNING 로그(``ilink.propv2``)를 남긴다.
+- **동작 변화**: 토픽 옵션 문자열의 모르는 키는 거절되지 않고 **무시 + 경고**가 된다(모르는 키 무시 규칙). 범위 밖 토픽 값(SEGMENTBYTES 등)은
+  엔진이 고쳐 받지 않고 **거절**한다. 없는 토픽 조회는 ``MIMQE_OBJECT_NOT_FOUND``. 토픽 목록(``getTopicList`` · ``list_topics``)은 예전과 같은
+  ``name|earliest|next|epoch|partitions`` 줄로 돌려준다.
+- **없앤 것(옛 와이어 코덱)**: ``ILQuotaProperty(text)`` · ``to_text``, ``ILDiskGuardProperty(csv)`` · ``to_csv``. 클러스터의 옛 블롭 코덱은
+  아직 남아 있으나 쓰지 않는다(다음 정리 대상).
+- 문서: 트랜잭션 커밋이 ``MIMQE_FOLLOWER_NODE`` 로 실패하면 적용 안 됨 - 처음부터 다시(엔진 r3598). 클러스터 노드 번호는 1~62.
+  엔진 판 표기 ``v7.1.x`` 를 엔진 리비전(rNNNN)으로.
+
 ## 0.21.12 변경 - 긴 실패 사유를 자르지 않는다 (자바 v2.17.12 와 같음, 짝 엔진 7.0.1.3597 이상)
 
 - **실패 사유 전문**: 응답의 사유 칸은 69바이트라 긴 사유가 잘렸다. 엔진 7.0.1.3597 부터는 그보다 긴 사유의 전문(최대 8192 바이트,
@@ -972,7 +991,7 @@ svc.createCluster(c)
 큐에 더해 **pub/sub 토픽**을 지원합니다. 발행된 메시지는 retention 정책이 지울 때까지 보존되어
 모든 구독자에게 각자의 커서로 전달됩니다(팬아웃). 큐와 달리 소비해도 사라지지 않습니다.
 
-> 엔진 v7.1.1 rev 3265 이상이 필요합니다.
+> 엔진 r3265 이상이 필요합니다.
 
 ### 구독
 

{jetstream_api-0.21.12 → jetstream_api-0.22.0}/README.md

@@ -10,6 +10,25 @@ lz4 배치 압축을 쓰려면 `pip install "jetstream-api[lz4]"`, zstd 배치
 ## 설치 방법
 pip install jetstream-api
 
+## 0.22.0 변경 - 7 신규 오브젝트(쿼터 · 디스크 가드 · 토픽 · 클러스터) 관리를 Property v2(JSON)로 (자바 v2.18.0 와 같음, 짝 엔진 7.0.1.3601 이상)
+
+- **와이어**: 쿼터 · 디스크 가드 · 토픽 · 클러스터의 생성 · 조회 · 목록 · 변경 · 삭제가 새 요청 코드 3600~3604(본문 = UTF-8 JSON)로 간다.
+  ★ 이 네 오브젝트는 **엔진 7.0.1.3601 이상에서만** 된다(엔진이 옛 코드를 지웠다). 6.x 엔진에는 원래 없는 기능이라 보내지 않고
+  ``MIMQE_NOT_SUPPORTED (... requires ILink 7)`` 로 거절한다. 큐 · 채널 · 큐 관리자 · 세션 등 6.x 오브젝트와 데이터 경로는 바뀌지 않았다.
+- **바꾼 값만 보낸다(patch)**: ``setQuotaProperty`` · ``setDiskGuardProperty`` · ``setClusterProperty`` 는 **세터(또는 필드 대입)로 바꾼
+  칸만** 보낸다. 조회한 객체를 그대로 넘기면 아무것도 보내지 않는다. 쿼터 클라 항목 · 클러스터 노드 목록은 바뀌면 통째로 간다.
+  클러스터는 읽은 정의 판(defTerm, defVersion)을 낙관적 잠금으로 자동으로 싣는다.
+- **새 함수 - 결과를 돌려준다**: ``setQuotaPropertyWithResult`` · ``setDiskGuardPropertyWithResult`` · ``setClusterPropertyWithResult`` ·
+  ``createTopicWithResult`` · ``setTopicPropertyWithResult`` · ``removeTopicWithResult`` -> :class:`ILPropertyResult`(적용된 키와 반영 시점 ·
+  무시된 키와 까닭 · 바꿔 받은 값 · 조작별 결과). 무시된 키가 있으면 기존 함수도 WARNING 로그(``ilink.propv2``)를 남긴다.
+- **동작 변화**: 토픽 옵션 문자열의 모르는 키는 거절되지 않고 **무시 + 경고**가 된다(모르는 키 무시 규칙). 범위 밖 토픽 값(SEGMENTBYTES 등)은
+  엔진이 고쳐 받지 않고 **거절**한다. 없는 토픽 조회는 ``MIMQE_OBJECT_NOT_FOUND``. 토픽 목록(``getTopicList`` · ``list_topics``)은 예전과 같은
+  ``name|earliest|next|epoch|partitions`` 줄로 돌려준다.
+- **없앤 것(옛 와이어 코덱)**: ``ILQuotaProperty(text)`` · ``to_text``, ``ILDiskGuardProperty(csv)`` · ``to_csv``. 클러스터의 옛 블롭 코덱은
+  아직 남아 있으나 쓰지 않는다(다음 정리 대상).
+- 문서: 트랜잭션 커밋이 ``MIMQE_FOLLOWER_NODE`` 로 실패하면 적용 안 됨 - 처음부터 다시(엔진 r3598). 클러스터 노드 번호는 1~62.
+  엔진 판 표기 ``v7.1.x`` 를 엔진 리비전(rNNNN)으로.
+
 ## 0.21.12 변경 - 긴 실패 사유를 자르지 않는다 (자바 v2.17.12 와 같음, 짝 엔진 7.0.1.3597 이상)
 
 - **실패 사유 전문**: 응답의 사유 칸은 69바이트라 긴 사유가 잘렸다. 엔진 7.0.1.3597 부터는 그보다 긴 사유의 전문(최대 8192 바이트,
@@ -922,7 +941,7 @@ svc.createCluster(c)
 큐에 더해 **pub/sub 토픽**을 지원합니다. 발행된 메시지는 retention 정책이 지울 때까지 보존되어
 모든 구독자에게 각자의 커서로 전달됩니다(팬아웃). 큐와 달리 소비해도 사라지지 않습니다.
 
-> 엔진 v7.1.1 rev 3265 이상이 필요합니다.
+> 엔진 r3265 이상이 필요합니다.
 
 ### 구독
 

{jetstream_api-0.21.12 → jetstream_api-0.22.0}/ilink/__init__.py

@@ -1,6 +1,6 @@
 """iLink - Python client API for iLink M.O.M. (Message Oriented Middleware)."""
 
-__version__ = "0.21.12"
+__version__ = "0.22.0"
 
 # --- Admin / Service ---
 from .admin import ILAdminService, ILAdminQmgr, ILLogBrowser, ILQueueBrowser
@@ -58,6 +58,7 @@ from .properties import (
     ILQuotaMeter,
     ILQuotaFollower,
     ILQuotaRefusedPeer,
+    ILPropertyResult,
     ILThrottleStats,
 )
 
@@ -131,6 +132,7 @@ __all__ = [
     "ILQuotaMeter",
     "ILQuotaFollower",
     "ILQuotaRefusedPeer",
+    "ILPropertyResult",
     "ILThrottleStats",
     # Exceptions
     "ILException",

jetstream_api-0.22.0/ilink/_propv2.py

@@ -0,0 +1,440 @@
+"""Property v2 속성 와이어 - JSON 본문 규칙(모듈 내부용, 엔진 PROPV2-1).
+
+본문은 UTF-8 JSON 객체 하나다(BOM 없음). 오브젝트 속성은 최상위에 평평하게 싣고, ``_`` 로 시작하는 키는 메타다
+(``_TYPE`` · ``_KEYS`` · ``_ITEMS`` · ``_APPLIED`` · ``_IGNORED`` · ``_NORMALIZED`` · ``_RESULT`` · ``_EXPECT``).
+정본은 엔진 ``DESIGN_PROPERTY_V2.md`` §3 이고, 세 언어가 같은 시험 벡터(``propv2_test/json_rule_vectors.txt``)로 맞춘다.
+
+파서는 엄격하다 - 깨진 UTF-8 · 중복 키(중첩 포함) · 깊이 8 초과 · null · 섞인 배열 · 문자열 안 NUL · 뒤 쓰레기 ·
+비표준 확장(주석 · 끝 쉼표 · NaN · 작은따옴표 · 앞자리 0)은 거절한다. 키는 ``[A-Z0-9_]`` 1~63자, 첫 글자 ``[A-Z_]``.
+
+값 종류(:func:`take`): ``INT`` = 정수 number(int32), ``LONG`` = 10진 문자열(int64, ``-?[0-9]+``), ``DOUBLE`` = number,
+``BOOL`` = true/false, ``STR`` = string.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+
+MAX_KEY_LEN = 63
+MAX_DEPTH = 8           # 최상위 객체 = 0, 안쪽 객체 / 배열 한 겹마다 +1
+
+_INT_MIN, _INT_MAX = -(1 << 31), (1 << 31) - 1
+_LONG_MIN, _LONG_MAX = -(1 << 63), (1 << 63) - 1
+_LONG_RE = re.compile(r"-?[0-9]+\Z")
+_KEY_RE = re.compile(r"[A-Z_][A-Z0-9_]*\Z")
+_WS = " \t\r\n"
+
+
+class PropV2Error(ValueError):
+    """본문 규칙 위반."""
+
+
+def _no_constant(name: str):
+    raise PropV2Error("JSON: %s is not allowed" % name)
+
+
+def _pairs(pairs):
+    # 중복 키를 그 자리에서 잡는다(경로는 아래 검사가 붙인다) - 순서는 보존한다
+    d = {}
+    for k, v in pairs:
+        if k in d:
+            raise PropV2Error("duplicate key %s" % k)
+        d[k] = v
+    return d
+
+
+def is_valid_key(k: str) -> bool:
+    """키 문자 규칙(1~63자, ``[A-Z0-9_]``, 첫 글자 ``[A-Z_]``)에 맞는가.
+
+    Returns:
+        bool: 맞으면 True.
+    """
+    return bool(k) and len(k) <= MAX_KEY_LEN and _KEY_RE.match(k) is not None
+
+
+def _kind(v) -> str:
+    if isinstance(v, bool):
+        return "b"
+    if isinstance(v, (int, float)):
+        return "n"
+    if isinstance(v, str):
+        return "s"
+    if isinstance(v, dict):
+        return "o"
+    if isinstance(v, list):
+        return "a"
+    return "?"
+
+
+def _check(v, path: str, depth: int) -> None:
+    if depth > MAX_DEPTH:
+        raise PropV2Error("nesting deeper than 8")
+    if v is None:
+        raise PropV2Error("%s must not be null" % (path or "value"))
+    if isinstance(v, float) and (v != v or v in (float("inf"), float("-inf"))):
+        raise PropV2Error("JSON: number out of range")
+    if isinstance(v, str):
+        if "\x00" in v:
+            raise PropV2Error("%s contains NUL" % path)
+        try:
+            v.encode("utf-8")
+        except UnicodeEncodeError:
+            raise PropV2Error("JSON: lone surrogate in %s" % path) from None
+    elif isinstance(v, dict):
+        for k, x in v.items():
+            if not is_valid_key(k):
+                raise PropV2Error("bad key '%s'" % k)
+            _check(x, k if not path else path + "." + k, depth + 1)
+    elif isinstance(v, list):
+        kinds = set()
+        for i, x in enumerate(v):
+            if x is None:
+                raise PropV2Error("%s[%d] must not be null" % (path, i))
+            kinds.add(_kind(x))
+            _check(x, "%s[%d]" % (path, i), depth + 1)
+        if len(kinds) > 1:
+            raise PropV2Error("%s mixes element types" % path)
+
+
+def parse(data: bytes | bytearray | memoryview) -> dict:
+    """본문 바이트를 객체(dict, 키 순서 보존)로 푼다.
+
+    Returns:
+        dict: 최상위 객체.
+
+    Raises:
+        PropV2Error: 규칙 위반(부분 결과 없음).
+    """
+    b = bytes(data)
+    try:
+        text = b.decode("utf-8")
+    except UnicodeDecodeError:
+        raise PropV2Error("JSON: invalid UTF-8") from None
+    if not text.strip(_WS):
+        raise PropV2Error("JSON: empty body")
+    try:
+        obj = json.loads(text, object_pairs_hook=_pairs, parse_constant=_no_constant)
+    except PropV2Error as e:
+        if str(e).startswith("duplicate key"):
+            raise PropV2Error(_dup_path(text) or str(e)) from None
+        raise
+    except RecursionError:
+        raise PropV2Error("nesting deeper than 8") from None
+    except ValueError as e:
+        raise PropV2Error("JSON: %s" % e) from None
+    if not isinstance(obj, dict):
+        raise PropV2Error("must be an object")
+    _check(obj, "", 0)
+    return obj
+
+
+def _dup_path(text: str) -> str:
+    # 중복 키의 경로(O.X · L[1].X)를 사유에 싣는다 - 다시 풀며 경로를 따라간다(실패 경로에서만 돈다)
+    found = []
+
+    def walk(pairs_list, path):
+        seen = set()
+        for k, v in pairs_list:
+            p = k if not path else path + "." + k
+            if k in seen:
+                found.append(p)
+                return
+            seen.add(k)
+
+    def hook(pairs):
+        return ("__pairs__", pairs)
+
+    try:
+        raw = json.loads(text, object_pairs_hook=hook, parse_constant=_no_constant)
+    except Exception:
+        return ""
+
+    def visit(node, path):
+        if found:
+            return
+        if isinstance(node, tuple) and node and node[0] == "__pairs__":
+            walk(node[1], path)
+            for k, v in node[1]:
+                visit(v, k if not path else path + "." + k)
+        elif isinstance(node, list):
+            for i, x in enumerate(node):
+                visit(x, "%s[%d]" % (path, i))
+
+    visit(raw, "")
+    return "duplicate key " + found[0] if found else ""
+
+
+def take(obj: dict, key: str, kind: str):
+    """객체에서 키 하나를 그 종류로 꺼낸다.
+
+    Args:
+        obj (dict): :func:`parse` 결과(또는 그 안쪽 객체).
+        key (str): 키.
+        kind (str): 값 종류. ``"INT"`` · ``"LONG"`` · ``"DOUBLE"`` · ``"BOOL"`` · ``"STR"`` 중 하나.
+
+    Returns:
+        int | float | bool | str | None: 값. 키가 없으면 None.
+
+    Raises:
+        PropV2Error: 값이 그 종류가 아닐 때(``<KEY> must be LONG (decimal string)`` 등).
+    """
+    if key not in obj:
+        return None
+    v = obj[key]
+    if kind == "INT":
+        if type(v) is int and _INT_MIN <= v <= _INT_MAX:
+            return v
+    elif kind == "LONG":
+        if type(v) is str and _LONG_RE.match(v):
+            n = int(v)
+            if _LONG_MIN <= n <= _LONG_MAX:
+                return n
+        raise PropV2Error("%s must be LONG (decimal string)" % key)
+    elif kind == "DOUBLE":
+        if type(v) in (int, float):
+            return float(v)
+    elif kind == "BOOL":
+        if type(v) is bool:
+            return v
+    elif kind == "STR":
+        if type(v) is str:
+            return v
+    else:
+        raise ValueError("unknown kind %r" % kind)
+    raise PropV2Error("%s must be %s" % (key, kind))
+
+
+def long_str(n: int) -> str:
+    """LONG 값을 와이어 표기(10진 문자열)로.
+
+    Returns:
+        str: 10진 문자열.
+    """
+    return "%d" % int(n)
+
+
+def dumps(obj: dict) -> bytes:
+    """객체를 본문 바이트(UTF-8, 공백 없는 JSON)로. 보내기 전에 규칙을 같은 검사로 확인한다.
+
+    Returns:
+        bytes: 본문 바이트.
+
+    Raises:
+        PropV2Error: 규칙 위반(키 · null · 섞인 배열 · 깊이 등).
+    """
+    if not isinstance(obj, dict):
+        raise PropV2Error("must be an object")
+    _check(obj, "", 0)
+    return json.dumps(obj, ensure_ascii=False, separators=(",", ":"), allow_nan=False).encode("utf-8")
+
+
+# ── 요청(엔진 설계 §5-1) ───────────────────────────────────────────────────────
+
+PROP_CREATE = 3600
+PROP_ALTER = 3601       # 코드 자체가 patch 다(본문에 표지 없음)
+PROP_GET = 3602
+PROP_LIST = 3603
+PROP_DELETE = 3604
+PROP_FAILED = 4601      # 실패 REPORT(arg2 = 사유). 성공은 LONG_REPORT(본문 JSON) - 4600 은 예약만
+
+_LOG = logging.getLogger("ilink.propv2")
+
+
+def require_v2(version: str | None, what: str) -> None:
+    """상대가 Property v2 를 말하지 않으면 보내지 않고 거절한다(7 신규 오브젝트는 옛 와이어가 없다).
+
+    Args:
+        version (str | None): 접속 응답의 버전 문자열.
+        what (str): 사유에 실을 대상(``"quota"`` 등).
+
+    Raises:
+        ILOperationException: ``MIMQE_NOT_SUPPORTED (<what> requires ILink 7, current: <버전>)``.
+    """
+    if not peer_speaks_v2(version):
+        from .exception import ILOperationException
+        raise ILOperationException("MIMQE_NOT_SUPPORTED (%s requires ILink 7, current: %s)" % (what, version or "?"))
+
+
+def request(helper, qmgr_name: str, code: int, obj: dict) -> dict:
+    """요청 하나를 보내고 응답 본문을 푼다. ``_IGNORED`` 가 있으면 WARNING 로그를 남긴다.
+
+    Args:
+        helper: 연결(``ILRequestHelper``).
+        qmgr_name (str): 대상 큐 관리자 이름. ``""`` 이면 서비스(ilsvc)가 직접 처리한다(쿼터 · 디스크 가드).
+        code (int): ``PROP_CREATE`` · ``PROP_ALTER`` · ``PROP_GET`` · ``PROP_LIST`` · ``PROP_DELETE`` 중 하나.
+        obj (dict): 본문(``_TYPE`` 포함).
+
+    Returns:
+        dict: 응답 본문. 빈 결과면 ``{}``.
+
+    Raises:
+        ILOperationException: 엔진이 거절했을 때(4601 의 사유 그대로). 토픽 FLUSH 와 겹친 거절은 조용히 몇 번 다시 보낸다.
+        PropV2Error: 응답 본문이 규칙에 맞지 않을 때.
+    """
+    from .common import ILC
+    from .connectivity import _FLUSH_RETRY_MAX, _flush_backoff, _is_topic_flushed
+    from .exception import ILOperationException
+    from .msg import ILMsgUtil
+    body = dumps(obj)
+    for attempt in range(_FLUSH_RETRY_MAX + 1):
+        msg = (ILMsgUtil.create_long_request_msg(code, body) if not qmgr_name
+               else ILMsgUtil.create_long_request_msg_with_qmgr(qmgr_name, code, body))
+        res = helper._call(msg, helper.sessionTimeoutMS)
+        if res.getType() == ILC.MIMQ_REPORT_MESSAGE:
+            exc = ILOperationException(res.getReportMsg().getArg2())
+            if attempt >= _FLUSH_RETRY_MAX or not _is_topic_flushed(exc):
+                raise exc
+            _flush_backoff(attempt)
+            continue
+        data = res.getDataMsg().getData()
+        out = parse(data) if data and bytes(data).strip(b" \t\r\n") else {}
+        ign = out.get("_IGNORED")
+        if ign:
+            _LOG.warning("property v2 %s %s: engine ignored %s", obj.get("_TYPE", "?"), code,
+                         ", ".join("%s(%s)" % (e.get("KEY", "?"), e.get("WHY", "?")) for e in ign if isinstance(e, dict)))
+        return out
+    raise AssertionError("unreachable")
+
+
+# ── 토픽(엔진 설계 §13-3) ─────────────────────────────────────────────────────
+
+#: 토픽 설정 키의 종류. 옵션 문자열(``"k=v;..."``)을 본문으로 바꿀 때 쓴다 - 표에 없는 키는 STR 로 실어 보내고
+#: 엔진이 모르면 ``_IGNORED unknown`` 으로 돌려준다(U4).
+TOPIC_KINDS = {
+    "PARTITIONS": "INT", "INDEXINTERVAL": "INT",
+    "SEGMENTBYTES": "LONG", "SEGMENTROLLMS": "LONG", "RETENTIONMS": "LONG", "RETENTIONBYTES": "LONG",
+    "APPENDRUNBYTES": "LONG", "TOMBSTONERETENTIONMS": "LONG",
+    "MINCLEANABLERATIO": "DOUBLE", "SAFERETENTION": "BOOL", "CLEANUPPOLICY": "STR",
+}
+#: 읽기 전용 칸의 종류(GET / LIST 응답)
+TOPIC_RO_KINDS = {
+    "EPOCH": "LONG", "EARLIEST": "LONG", "NEXT": "LONG", "TOTALBYTES": "LONG", "PUBLISHED": "LONG",
+    "DELIVERED": "LONG", "CURSORJUMPS": "LONG", "EXPIREDSUBS": "LONG", "SEGMENTCOUNT": "INT", "SUBSCRIPTIONS": "INT",
+}
+
+
+def topic_options(options: str) -> dict:
+    """옛 옵션 문자열(``"partitions=3;retentionms=86400000"``)을 본문 키로 바꾼다.
+
+    키는 대소문자를 가리지 않고 대문자로 바꾼다(옛 엔진 ApplyOptions 와 같다). 값은 :data:`TOPIC_KINDS` 의 종류로
+    바꾸고, 표에 없는 키는 문자열로 싣는다.
+
+    Args:
+        options (str): ``key=value`` 를 ``;`` 로 이은 문자열. 빈 칸은 건너뛴다.
+
+    Returns:
+        dict: 본문 키 -> 값.
+
+    Raises:
+        PropV2Error: ``=`` 가 없는 칸, 키 문자 규칙 위반, 값이 그 키의 종류로 읽히지 않을 때.
+    """
+    out: dict = {}
+    for tok in str(options or "").split(";"):
+        tok = tok.strip()
+        if not tok:
+            continue
+        eq = tok.find("=")
+        if eq < 0:
+            raise PropV2Error("topic option without '=' : %s" % tok)
+        key = tok[:eq].strip().upper()
+        val = tok[eq + 1:].strip()
+        if not is_valid_key(key) or key.startswith("_"):
+            raise PropV2Error("bad topic option key '%s'" % tok[:eq].strip())
+        kind = TOPIC_KINDS.get(key, "STR")
+        try:
+            if kind == "INT":
+                n = int(val, 10)
+                if not _INT_MIN <= n <= _INT_MAX:
+                    raise ValueError(val)
+                out[key] = n
+            elif kind == "LONG":
+                if not _LONG_RE.match(val) or not _LONG_MIN <= int(val) <= _LONG_MAX:
+                    raise ValueError(val)
+                out[key] = long_str(int(val))
+            elif kind == "DOUBLE":
+                d = float(val)
+                if d != d or d in (float("inf"), float("-inf")):
+                    raise ValueError(val)
+                out[key] = d
+            elif kind == "BOOL":
+                if val.lower() not in ("true", "false"):
+                    raise ValueError(val)
+                out[key] = val.lower() == "true"
+            else:
+                out[key] = val.upper() if key == "CLEANUPPOLICY" else val
+        except ValueError:
+            raise PropV2Error("%s must be %s : %s" % (key, kind, val)) from None
+    return out
+
+
+def topic_list_text(obj: dict) -> str:
+    """LIST 응답을 옛 목록 줄(``name|earliest|next|epoch|partitions`` + ``\\n``)로 다시 만든다.
+
+    Args:
+        obj (dict): LIST 응답 본문(``_ITEMS``).
+
+    Returns:
+        str: 토픽당 한 줄(엔진 옛 GetTopicDisplayList 와 같은 모양). 토픽이 없으면 빈 문자열.
+    """
+    out = []
+    for e in obj.get("_ITEMS", []) or []:
+        if not isinstance(e, dict):
+            raise PropV2Error("_ITEMS must be ARRAY of OBJ")
+        out.append("%s|%d|%d|%d|%d\n" % (take(e, "NAME", "STR") or "", take(e, "EARLIEST", "LONG") or 0,
+                                          take(e, "NEXT", "LONG") or 0, take(e, "EPOCH", "LONG") or 0,
+                                          take(e, "PARTITIONS", "INT") or 0))
+    return "".join(out)
+
+
+def topic_names(obj: dict) -> list:
+    """LIST 응답에서 이름만 모은다.
+
+    Returns:
+        list[str]: 토픽 이름들(응답 순서).
+    """
+    return [take(e, "NAME", "STR") or "" for e in obj.get("_ITEMS", []) or [] if isinstance(e, dict)]
+
+
+def topic_detail_text(obj: dict) -> str:
+    """GET 응답을 사람이 읽는 평문으로 만든다(형식은 고정하지 않는다).
+
+    Returns:
+        str: ``KEY : 값`` 줄들과 파티션마다 ``PART n ...`` 줄.
+    """
+    lines = []
+    for k, v in obj.items():
+        if k.startswith("_") or k == "PARTS":
+            continue
+        lines.append("%s : %s" % (k, ("true" if v else "false") if isinstance(v, bool) else v))
+    for p in obj.get("PARTS", []) or []:
+        if isinstance(p, dict):
+            lines.append("PART %s : earliest=%s next=%s bytes=%s leader=%s epoch=%s isr=%s" % (
+                p.get("PARTITION", "?"), p.get("EARLIEST", "?"), p.get("NEXT", "?"), p.get("BYTES", "?"),
+                p.get("LEADER", "?"), p.get("EPOCH", "?"), p.get("ISR", "")))
+    return "".join(x + "\n" for x in lines)
+
+
+def peer_speaks_v2(version: str | None) -> bool:
+    """상대(접속 응답 arg2 의 버전 문자열)가 Property v2 를 말하는가.
+
+    앞뒤 공백 · 탭을 뺀 뒤 첫 '.'(없으면 끝)까지가 비지 않은 숫자열(6자리 이하)이고 그 값이 7 이상이면 참.
+    revision · 브랜드는 보지 않는다. 비었거나 못 읽으면 거짓(기존 방식). split 을 쓰지 않는다 - ".7.0.1" 은 거짓이다.
+
+    Returns:
+        bool: Property v2 를 말하면 True.
+    """
+    if not version:
+        return False
+    s = version.lstrip(" \t")
+    if not s:
+        return False
+    i = s.find(".")
+    major = (s if i < 0 else s[:i]).rstrip(" \t")
+    if not major or len(major) > 6:
+        return False
+    for c in major:
+        if not ("0" <= c <= "9"):
+            return False
+    return int(major) >= 7