motorcortex-python 0.25.4__tar.gz → 1.0.0__tar.gz

motorcortex_python-1.0.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.1
+Name: motorcortex-python
+Version: 1.0.0
+Summary: Python bindings for Motorcortex Engine
+Home-page: https://www.motorcortex.io
+Author: Alexey Zakharov
+Author-email: alexey.zakharov@vectioneer.com
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pynng<2,>=0.9.0
+Requires-Dist: protobuf>=3.20
+
+# motorcortex-python
+
+[![pipeline status](https://git.vectioneer.com/pub/motorcortex-python/badges/master/pipeline.svg)](https://git.vectioneer.com/pub/motorcortex-python/-/commits/master)
+[![coverage report](https://git.vectioneer.com/pub/motorcortex-python/badges/master/coverage.svg?job=coverage)](https://git.vectioneer.com/pub/motorcortex-python/-/commits/master)
+[![PyPI version](https://img.shields.io/pypi/v/motorcortex-python.svg)](https://pypi.org/project/motorcortex-python/)
+[![Python versions](https://img.shields.io/pypi/pyversions/motorcortex-python.svg)](https://pypi.org/project/motorcortex-python/)
+[![License: MIT](https://img.shields.io/pypi/l/motorcortex-python.svg)](LICENSE)
+
+Python bindings for the [Motorcortex](https://www.motorcortex.io) real-time control engine. Connect to a Motorcortex server, read and write parameters, and stream live telemetry over a single TLS-secured websocket.
+
+## Installation
+
+```bash
+pip install motorcortex-python
+```
+
+Requires Python ≥ 3.10. Runtime dependencies (`pynng`, `protobuf`) are installed automatically.
+
+## Quick start
+
+Recommended — `Session` context manager (close is automatic, even on exceptions):
+
+```python
+import motorcortex
+
+with motorcortex.Session(
+    "wss://192.168.2.100",
+    certificate="mcx.cert.crt",
+    login="admin", password="admin",
+    timeout_ms=1000,
+) as s:
+    # Read a single parameter
+    reply = s.req.getParameter("root/Control/dummyDouble").get()
+    print(reply.value)
+
+    # Write a parameter
+    s.req.setParameter("root/Control/dummyDouble", 3.14).get()
+
+    # Subscribe to a streamed update (every 10th cycle)
+    subscription = s.sub.subscribe(
+        ["root/Control/dummyDouble"], "myGroup", frq_divider=10,
+    )
+    subscription.get()
+    subscription.notify(lambda result: print(result[0].value))
+```
+
+Explicit-objects form — the original API, still supported:
+
+```python
+types = motorcortex.MessageTypes()
+tree = motorcortex.ParameterTree()
+
+req, sub = motorcortex.connect(
+    "wss://192.168.2.100", types, tree,
+    certificate="mcx.cert.crt",
+    login="admin", password="admin",
+)
+try:
+    reply = req.getParameter("root/Control/dummyDouble").get()
+    print(reply.value)
+finally:
+    sub.close()
+    req.close()
+```
+
+The URL grammar accepts IPv4, hostnames, and IPv6 literals both with and without explicit ports — e.g. `wss://host`, `wss://host:5568:5567`, `wss://[::1]`, `wss://[fe80::1]:5568:5567`.
+
+## Documentation
+
+- **[API reference — `docs/_index.md`](docs/_index.md)** — flat, method-by-method reference for every public class and function. Regenerated from the docstrings via `pydoc-markdown`.
+- **[`ARCHITECTURE.md`](ARCHITECTURE.md)** — internals tour: module layout, connection lifecycle, subscribe frame format, parameter-tree cache, threading model, error contract, type conventions.
+- **[`examples/README.md`](examples/README.md)** — runnable scripts (`quickstart.py`, `error_handling.py`) that demonstrate the canonical usage patterns.
+- **[`CHANGELOG.md`](CHANGELOG.md)** — version history.
+
+## Repository layout
+
+```
+motorcortex/            Python package
+test/
+  unit/                 Offline unit tests (no server)
+  integration/          Live tests against the vendored test_server
+  server/               Vendored C++ test_server (CMake project)
+docs/                   pydoc-markdown + stub generation scripts
+benchmark/              Throughput scripts (not part of the test suite)
+sandbox/                Ad-hoc repro scripts
+```
+
+## Testing
+
+Unit tests run offline and require only the package itself:
+
+```bash
+pip install -e .
+pip install "coverage[toml]>=7.4"
+python -m unittest discover -s test/unit -t .
+```
+
+Integration tests spawn the vendored `test_server`. Build it once, then run the suite:
+
+```bash
+cmake -S test/server -B test/server/build -DCMAKE_BUILD_TYPE=Release
+cmake --build test/server/build
+
+python -m unittest discover -s test/integration -t .
+```
+
+Coverage (line + branch). `pyproject.toml` sets `parallel = true`, so each
+`coverage run` writes a per-process data shard; use `coverage combine` to
+merge them before `coverage report`:
+
+```bash
+coverage erase
+coverage run -m unittest discover -s test/unit -t .
+coverage run -m unittest discover -s test/integration -t .
+coverage combine
+coverage report
+```
+
+See [`test/README.md`](test/README.md) for the full testing walkthrough.
+
+## Regenerating the API reference
+
+[`docs/_index.md`](docs/_index.md) is committed and should be refreshed
+before each release so the rendered reference matches the code at
+the tag. The regen is two commands — `pydoc-markdown` first, then
+`format_api.sh` to wrap `>>>` examples as fenced Python blocks and
+prepend the front matter:
+
+```bash
+pip install pydoc-markdown
+cd docs
+pydoc-markdown pydoc-markdown.yml > _index.md
+./format_api.sh
+```
+
+The hook-based one-shot version was dropped — it races with the
+shell redirect and silently loses output. See `docs/readme.md` and
+the comment in `docs/pydoc-markdown.yml` for the full rationale.
+
+## Release process
+
+See [`PIPHOWTO.md`](PIPHOWTO.md) for PyPI release steps and [`CHANGELOG.md`](CHANGELOG.md) for version history.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

motorcortex_python-1.0.0/README.md

@@ -0,0 +1,146 @@
+# motorcortex-python
+
+[![pipeline status](https://git.vectioneer.com/pub/motorcortex-python/badges/master/pipeline.svg)](https://git.vectioneer.com/pub/motorcortex-python/-/commits/master)
+[![coverage report](https://git.vectioneer.com/pub/motorcortex-python/badges/master/coverage.svg?job=coverage)](https://git.vectioneer.com/pub/motorcortex-python/-/commits/master)
+[![PyPI version](https://img.shields.io/pypi/v/motorcortex-python.svg)](https://pypi.org/project/motorcortex-python/)
+[![Python versions](https://img.shields.io/pypi/pyversions/motorcortex-python.svg)](https://pypi.org/project/motorcortex-python/)
+[![License: MIT](https://img.shields.io/pypi/l/motorcortex-python.svg)](LICENSE)
+
+Python bindings for the [Motorcortex](https://www.motorcortex.io) real-time control engine. Connect to a Motorcortex server, read and write parameters, and stream live telemetry over a single TLS-secured websocket.
+
+## Installation
+
+```bash
+pip install motorcortex-python
+```
+
+Requires Python ≥ 3.10. Runtime dependencies (`pynng`, `protobuf`) are installed automatically.
+
+## Quick start
+
+Recommended — `Session` context manager (close is automatic, even on exceptions):
+
+```python
+import motorcortex
+
+with motorcortex.Session(
+    "wss://192.168.2.100",
+    certificate="mcx.cert.crt",
+    login="admin", password="admin",
+    timeout_ms=1000,
+) as s:
+    # Read a single parameter
+    reply = s.req.getParameter("root/Control/dummyDouble").get()
+    print(reply.value)
+
+    # Write a parameter
+    s.req.setParameter("root/Control/dummyDouble", 3.14).get()
+
+    # Subscribe to a streamed update (every 10th cycle)
+    subscription = s.sub.subscribe(
+        ["root/Control/dummyDouble"], "myGroup", frq_divider=10,
+    )
+    subscription.get()
+    subscription.notify(lambda result: print(result[0].value))
+```
+
+Explicit-objects form — the original API, still supported:
+
+```python
+types = motorcortex.MessageTypes()
+tree = motorcortex.ParameterTree()
+
+req, sub = motorcortex.connect(
+    "wss://192.168.2.100", types, tree,
+    certificate="mcx.cert.crt",
+    login="admin", password="admin",
+)
+try:
+    reply = req.getParameter("root/Control/dummyDouble").get()
+    print(reply.value)
+finally:
+    sub.close()
+    req.close()
+```
+
+The URL grammar accepts IPv4, hostnames, and IPv6 literals both with and without explicit ports — e.g. `wss://host`, `wss://host:5568:5567`, `wss://[::1]`, `wss://[fe80::1]:5568:5567`.
+
+## Documentation
+
+- **[API reference — `docs/_index.md`](docs/_index.md)** — flat, method-by-method reference for every public class and function. Regenerated from the docstrings via `pydoc-markdown`.
+- **[`ARCHITECTURE.md`](ARCHITECTURE.md)** — internals tour: module layout, connection lifecycle, subscribe frame format, parameter-tree cache, threading model, error contract, type conventions.
+- **[`examples/README.md`](examples/README.md)** — runnable scripts (`quickstart.py`, `error_handling.py`) that demonstrate the canonical usage patterns.
+- **[`CHANGELOG.md`](CHANGELOG.md)** — version history.
+
+## Repository layout
+
+```
+motorcortex/            Python package
+test/
+  unit/                 Offline unit tests (no server)
+  integration/          Live tests against the vendored test_server
+  server/               Vendored C++ test_server (CMake project)
+docs/                   pydoc-markdown + stub generation scripts
+benchmark/              Throughput scripts (not part of the test suite)
+sandbox/                Ad-hoc repro scripts
+```
+
+## Testing
+
+Unit tests run offline and require only the package itself:
+
+```bash
+pip install -e .
+pip install "coverage[toml]>=7.4"
+python -m unittest discover -s test/unit -t .
+```
+
+Integration tests spawn the vendored `test_server`. Build it once, then run the suite:
+
+```bash
+cmake -S test/server -B test/server/build -DCMAKE_BUILD_TYPE=Release
+cmake --build test/server/build
+
+python -m unittest discover -s test/integration -t .
+```
+
+Coverage (line + branch). `pyproject.toml` sets `parallel = true`, so each
+`coverage run` writes a per-process data shard; use `coverage combine` to
+merge them before `coverage report`:
+
+```bash
+coverage erase
+coverage run -m unittest discover -s test/unit -t .
+coverage run -m unittest discover -s test/integration -t .
+coverage combine
+coverage report
+```
+
+See [`test/README.md`](test/README.md) for the full testing walkthrough.
+
+## Regenerating the API reference
+
+[`docs/_index.md`](docs/_index.md) is committed and should be refreshed
+before each release so the rendered reference matches the code at
+the tag. The regen is two commands — `pydoc-markdown` first, then
+`format_api.sh` to wrap `>>>` examples as fenced Python blocks and
+prepend the front matter:
+
+```bash
+pip install pydoc-markdown
+cd docs
+pydoc-markdown pydoc-markdown.yml > _index.md
+./format_api.sh
+```
+
+The hook-based one-shot version was dropped — it races with the
+shell redirect and silently loses output. See `docs/readme.md` and
+the comment in `docs/pydoc-markdown.yml` for the full rationale.
+
+## Release process
+
+See [`PIPHOWTO.md`](PIPHOWTO.md) for PyPI release steps and [`CHANGELOG.md`](CHANGELOG.md) for version history.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

{motorcortex_python-0.25.4 → motorcortex_python-1.0.0}/motorcortex/__init__.py

@@ -2,7 +2,7 @@
 
 #
 #   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
-#   All rights reserved. Copyright (c) 2016 - 2025 VECTIONEER.
+#   All rights reserved. Copyright (c) 2016 - 2026 VECTIONEER.
 #
 
 """
@@ -14,6 +14,9 @@ Provides high-level APIs for communication, login, and data exchange using proto
 See documentation for usage examples.
 """
 
+from enum import IntEnum as _IntEnum
+from typing import Any
+
 from motorcortex.version import __version__
 from motorcortex.parameter_tree import ParameterTree
 from motorcortex.message_types import MessageTypes
@@ -21,11 +24,105 @@ from motorcortex.request import Request, ConnectionState
 from motorcortex.reply import Reply
 from motorcortex.subscribe import Subscribe
 from motorcortex.subscription import Subscription
-from motorcortex.timespec import Timespec, compare_timespec, timespec_to_sec, timespec_to_msec, timespec_to_usec, \
-    timespec_to_nsec
-from motorcortex.setup_logger import logger
-from motorcortex.state_callback_handler import StateCallbackHandler
+from motorcortex.timespec import (
+    Timespec,
+    compare_timespec,
+    timespec_to_sec,
+    timespec_to_msec,
+    timespec_to_usec,
+    timespec_to_nsec,
+)
 from motorcortex.init_threads import init_nng_threads
+from motorcortex.session import Session
+from motorcortex.exceptions import (
+    McxError,
+    McxConnectionError,
+    McxLoginError,
+    McxTimeout,
+)
+from motorcortex.motorcortex_pb2 import StatusCode as _PbStatusCode
+from motorcortex.setup_logger import logger  # not re-exported — ``__all__`` gates package surface
+
+# Build an ``IntEnum`` facade over the protobuf ``StatusCode`` enum so
+# callers can write ``motorcortex.StatusCode.OK`` without reaching into
+# the generated protobuf module. Subclassing ``int`` means comparisons
+# like ``reply.status == StatusCode.OK`` work against the raw ints that
+# come back on the wire.
+StatusCode = _IntEnum(
+    "StatusCode",
+    {v.name: v.number for v in _PbStatusCode.DESCRIPTOR.values},
+)
+StatusCode.__doc__ = (
+    "Motorcortex response status codes. Members mirror the ``StatusCode`` "
+    "enum in the wire protocol. Use ``motorcortex.StatusCode.OK`` (or the "
+    "flat re-exports such as ``motorcortex.OK``) to compare against "
+    "``reply.status``."
+)
+
+# Flat re-exports for the conventional ``motorcortex.OK`` idiom. Values
+# are members of :class:`StatusCode` and therefore also ``int``.
+OK = StatusCode.OK
+READ_ONLY_MODE = StatusCode.READ_ONLY_MODE
+FAILED = StatusCode.FAILED
+FAILED_TO_DECODE = StatusCode.FAILED_TO_DECODE
+SUB_LIST_IS_FULL = StatusCode.SUB_LIST_IS_FULL
+WRONG_PARAMETER_PATH = StatusCode.WRONG_PARAMETER_PATH
+FAILED_TO_SET_REQUESTED_FRQ = StatusCode.FAILED_TO_SET_REQUESTED_FRQ
+FAILED_TO_OPEN_FILE = StatusCode.FAILED_TO_OPEN_FILE
+GROUP_LIST_IS_FULL = StatusCode.GROUP_LIST_IS_FULL
+WRONG_PASSWORD = StatusCode.WRONG_PASSWORD
+USER_NOT_LOGGED_IN = StatusCode.USER_NOT_LOGGED_IN
+PERMISSION_DENIED = StatusCode.PERMISSION_DENIED
+
+# ``__all__`` is the 1.0 public API surface. Anything not listed here —
+# including module-level helpers defined below (``parseUrl``,
+# ``makeUrl``, ``statusToStr``) and submodule imports like
+# ``motorcortex.setup_logger`` — is implicitly private and may change
+# between minor releases. For logging, do
+# ``logging.getLogger("mcx")`` instead of reaching into the package.
+__all__ = [
+    "__version__",
+    # Entry points
+    "connect",
+    "Session",
+    # Connection / protocol classes
+    "Request",
+    "Subscribe",
+    "Subscription",
+    "Reply",
+    "ConnectionState",
+    # Protobuf / parameters
+    "MessageTypes",
+    "ParameterTree",
+    # Time
+    "Timespec",
+    "compare_timespec",
+    "timespec_to_sec",
+    "timespec_to_msec",
+    "timespec_to_usec",
+    "timespec_to_nsec",
+    # Exceptions
+    "McxError",
+    "McxConnectionError",
+    "McxLoginError",
+    "McxTimeout",
+    # Status codes
+    "StatusCode",
+    "OK",
+    "READ_ONLY_MODE",
+    "FAILED",
+    "FAILED_TO_DECODE",
+    "SUB_LIST_IS_FULL",
+    "WRONG_PARAMETER_PATH",
+    "FAILED_TO_SET_REQUESTED_FRQ",
+    "FAILED_TO_OPEN_FILE",
+    "GROUP_LIST_IS_FULL",
+    "WRONG_PASSWORD",
+    "USER_NOT_LOGGED_IN",
+    "PERMISSION_DENIED",
+    # Tuning
+    "init_nng_threads",
+]
 
 init_nng_threads()
 
@@ -46,9 +143,20 @@ def parseUrl(url: str) -> tuple[str, str, int | None, int | None]:
 
     If the URL does not contain ports, default endpoints '/mcx_req' and '/mcx_sub' are appended.
     """
+    # IPv6 host literals embed colons (``wss://[::1]``), so the rfind-based
+    # port scan has to start *after* the closing bracket of the host
+    # literal — otherwise it walks into the address bytes and either
+    # mis-parses the ports or (in the no-ports case) tries to int() an
+    # empty slice. For IPv4 / hostname URLs there is no bracket, so
+    # ``port_start`` stays at 0 and behavior matches the pre-fix code.
+    host_end = url.rfind(']')
+    port_start = host_end + 1 if host_end != -1 else 0
+
     end = url.rfind(':')
-    start = url.rfind(':', 0, end)
-    if end == -1 or start == -1:
+    if end < port_start:
+        return url + '/mcx_req', url + '/mcx_sub', None, None
+    start = url.rfind(':', port_start, end)
+    if start == -1:
         return url + '/mcx_req', url + '/mcx_sub', None, None
     req_port = int(url[start + 1:end])
     sub_port = int(url[end + 1:])
@@ -75,10 +183,10 @@ def makeUrl(address: str, port: int | None) -> str:
 
 def connect(
         url: str,
-        motorcortex_types: object,
+        motorcortex_types: "MessageTypes",
         param_tree: "ParameterTree",
         reconnect: bool = True,
-        **kwargs
+        **kwargs: Any,
 ) -> tuple["Request", "Subscribe"]:
     """
     Establishes connections to Motorcortex request and subscribe endpoints, performs login, and loads the parameter tree.
@@ -152,26 +260,52 @@ def connect(
     req_address, sub_address, req_port, sub_port = parseUrl(url)
     # Open request connection
     req = Request(motorcortex_types, param_tree, kwargs.get("req_number_of_threads", 2))
-    kwargs_copy = kwargs.copy()
-    kwargs_copy.update(state_update=None)
-    if not req.connect(makeUrl(req_address, req_port), **kwargs_copy).get():
-        raise RuntimeError("Failed to establish request connection: {}:{}".format(req_address, req_port))
-    # Open subscribe connection
-    sub = Subscribe(req, motorcortex_types, kwargs.get("sub_number_of_threads", 2))
-    if not sub.connect(makeUrl(sub_address, sub_port), **kwargs).get():
-        raise RuntimeError("Failed to establish subscribe connection: {}:{}".format(sub_address, sub_port))
-    # Login
-    login_reply = req.login(kwargs['login'], kwargs['password'])
-    login_reply_msg = login_reply.get()
-
-    motorcortex_msg = motorcortex_types.motorcortex()
-    if not login_reply_msg.status == motorcortex_msg.OK:
-        raise RuntimeError("Login failed, status: {}".format(login_reply_msg.status))
-
-    # Requesting a parameter tree
-    param_tree_reply = req.getParameterTree()
-    tree = param_tree_reply.get()
-    param_tree.load(tree)
+    sub = None
+    # Wrap every post-construction failure point so half-opened sockets
+    # get closed; otherwise the Subscribe receive thread stays blocked in
+    # recv() forever and pins the Python interpreter on exit (an atexit
+    # ``_python_exit`` handler then joins the worker indefinitely).
+    try:
+        kwargs_copy = kwargs.copy()
+        kwargs_copy.update(state_update=None)
+        if not req.connect(makeUrl(req_address, req_port), **kwargs_copy).get():
+            raise McxConnectionError(
+                "Failed to establish request connection: {}:{}".format(req_address, req_port)
+            )
+        # Open subscribe connection
+        sub = Subscribe(req, motorcortex_types, kwargs.get("sub_number_of_threads", 2))
+        if not sub.connect(makeUrl(sub_address, sub_port), **kwargs).get():
+            raise McxConnectionError(
+                "Failed to establish subscribe connection: {}:{}".format(sub_address, sub_port)
+            )
+        # Login. With ``Login: disable`` servers the credentials can legitimately
+        # be omitted — default to empty strings so the helper does not raise
+        # ``KeyError`` on valid callers.
+        login_reply = req.login(kwargs.get('login', ''), kwargs.get('password', ''))
+        login_reply_msg = login_reply.get()
+
+        motorcortex_msg = motorcortex_types.motorcortex()
+        if not login_reply_msg.status == motorcortex_msg.OK:
+            raise McxLoginError(
+                "Login failed, status: {}".format(login_reply_msg.status),
+                status=login_reply_msg.status,
+            )
+
+        # Requesting a parameter tree
+        param_tree_reply = req.getParameterTree()
+        tree = param_tree_reply.get()
+        param_tree.load(tree)
+    except Exception:
+        if sub is not None:
+            try:
+                sub.close()
+            except Exception:
+                pass
+        try:
+            req.close()
+        except Exception:
+            pass
+        raise
 
     # Start session token refresh
     req._startTokenRefresh(token_interval_sec)
@@ -181,7 +315,7 @@ def connect(
     return req, sub
 
 
-def statusToStr(motorcortex_msg: object, code: int) -> str:
+def statusToStr(motorcortex_msg: Any, code: int) -> str:
     """Converts status codes to a readable message.
 
         Args:

motorcortex_python-1.0.0/motorcortex/_connection_state.py

@@ -0,0 +1,58 @@
+#
+#   Developer: Alexey Zakharov (alexey.zakharov@vectioneer.com)
+#   All rights reserved. Copyright (c) 2026 VECTIONEER.
+#
+
+"""Connection-state enum + pure state-transition helpers.
+
+``ConnectionState`` was historically defined in ``motorcortex.request`` and
+is still re-exported from there (and from ``motorcortex``) for backward
+compatibility. It lives here so pure helpers can depend on it without
+dragging the whole ``request`` module — which would cause a circular
+import.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ConnectionState(Enum):
+    """Enumeration of connection states.
+
+        - CONNECTING:           Connection is being established.
+        - CONNECTION_OK:        Connection is successfully established.
+        - CONNECTION_LOST:      Connection was lost.
+        - CONNECTION_FAILED:    Connection attempt failed.
+        - DISCONNECTING:        Connection is being closed.
+        - DISCONNECTED:         Connection is closed.
+    """
+    CONNECTING = 0
+    CONNECTION_OK = 1
+    CONNECTION_LOST = 2
+    CONNECTION_FAILED = 3
+    DISCONNECTING = 4
+    DISCONNECTED = 5
+
+
+def next_state_after_pipe_remove(current: ConnectionState) -> ConnectionState:
+    """Map the current state to the one we enter when the remote pipe goes away.
+
+    nng fires its post-remove callback when a peer socket is torn down, but
+    the callback itself can't tell *why*: we might have called
+    ``close()`` (clean shutdown) or the remote might have died (lost /
+    failed). The only disambiguator is the state we were already in.
+
+    Transitions:
+        DISCONNECTING    → DISCONNECTED        (clean close we initiated)
+        CONNECTING       → CONNECTION_FAILED   (never finished handshake)
+        CONNECTION_OK    → CONNECTION_LOST     (remote went away mid-session)
+        anything else    → unchanged           (idempotent / re-entry safe)
+    """
+    if current == ConnectionState.DISCONNECTING:
+        return ConnectionState.DISCONNECTED
+    if current == ConnectionState.CONNECTING:
+        return ConnectionState.CONNECTION_FAILED
+    if current == ConnectionState.CONNECTION_OK:
+        return ConnectionState.CONNECTION_LOST
+    return current