Surface WebSocket errors on UtilResponse (closes #29) (#31)

* feat(device_utils): surface WebSocket errors on UtilResponse (closes #29)

UtilResponse gains ws_error / ws_close_code so a consumer can distinguish a
clean WebSocket completion from an errored, abnormally-closed, or
never-started one (previously the error was only logged and discarded):
- on_error records the first transport error (was a discard-only lambda);
- _on_close records the close code and flags a non-1000 abnormal close;
- start_with_trigger records ws_error when the WS factory returns None or
  raises during setup.

Additive and backward-compatible: ws_error stays None on a clean completion
or a trigger-only command. Adds unit tests for each path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(changelog): note ws_error/ws_close_code on UtilResponse (#29)

* chore(release): bump version to 0.63.1

* refactor(device_utils): address Copilot review on ws_error capture

- Guard the WS-factory-None ws_error assignment (first-write-wins, matching
  _on_error / _on_close).
- Neutralize the except-path ws_error message ('trigger/WebSocket setup
  error') since that except also wraps trigger_fn(), not only WS setup.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tmunzer-AIDE

CHANGELOG.md

@@ -1,4 +1,24 @@
 # CHANGELOG
+## Version 0.63.1 (June 2026)
+
+**Released**: June 14, 2026
+
+This patch release lets callers of the device-utility helpers detect WebSocket failures that were previously only logged.
+
+---
+
+### 1. BUG FIXES
+
+#### **Device Utilities: surface WebSocket errors on `UtilResponse`**
+`UtilResponse` now exposes `ws_error` and `ws_close_code` so callers can distinguish a clean WebSocket completion from an errored, abnormally-closed, or never-started one. Previously a WebSocket transport error was only logged and discarded, and a WS-backed command whose WebSocket failed to start was indistinguishable from a healthy trigger-only command.
+- `_on_error` records the first transport error (was a discard-only callback).
+- `_on_close` records the close status code and flags a non-1000 abnormal close.
+- `start_with_trigger` records `ws_error` when the WebSocket factory returns `None` or raises during setup.
+
+Additive and backward-compatible: `ws_error` stays `None` on a clean completion or a trigger-only command. (#29)
+
+---
+
 ## Version 0.63.0 (June 2026)
 
 **Released**: June 12, 2026

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mistapi"
-version = "0.63.0"
+version = "0.63.1"
 authors = [{ name = "Thomas Munzer", email = "tmunzer@juniper.net" }]
 description = "Python package to simplify the Mist System APIs usage"
 keywords = ["Mist", "Juniper", "API"]

src/mistapi/__version.py

@@ -1,2 +1,2 @@
-__version__ = "0.63.0"
+__version__ = "0.63.1"
 __author__ = "Thomas Munzer <tmunzer@juniper.net>"

src/mistapi/device_utils/__tools/__ws_wrapper.py

@@ -219,6 +219,13 @@ def __init__(
         self.ws_required: bool = False
         self.ws_data: list[str] = []
         self.ws_raw_events: list[str] = []
+        # Set when the WebSocket leg did NOT complete cleanly (transport error,
+        # abnormal close, or failure to start). Stays None on a clean completion or
+        # a trigger-only command, so `ws_error is not None` is a reliable
+        # "did not cleanly confirm" signal for consumers. ws_close_code records the
+        # WebSocket close status code when one was received.
+        self.ws_error: str | None = None
+        self.ws_close_code: int | None = None
         self._queue: queue.Queue[str | None] = queue.Queue()
         self._closed = threading.Event()
         self._await_timeout: float | None = None
@@ -349,8 +356,22 @@ def _on_open(self):
         # Start the max duration timer
         self._timeout_handler(Timer.MAX_DURATION, TimerAction.START)
 
+    def _on_error(self, error):
+        LOGGER.error("Error: %s", error)
+        # Record the first WebSocket transport error so a consumer can tell an
+        # errored stream from a clean one (otherwise the error is only logged).
+        if self.util_response.ws_error is None:
+            self.util_response.ws_error = str(error)
+
     def _on_close(self, code, msg):
         LOGGER.info("WebSocket closed: %s - %s", code, msg)
+        self.util_response.ws_close_code = code
+        # An abnormal close (anything other than a normal 1000 / no-status close)
+        # is recorded as an error so a clean completion is distinguishable.
+        if code is not None and code != 1000 and self.util_response.ws_error is None:
+            self.util_response.ws_error = (
+                f"WebSocket closed abnormally (code {code}): {msg}"
+            )
         self._stop_all_timers()
         self.util_response._queue.put(None)  # sentinel for receive()
         self.util_response._closed.set()  # signal completion
@@ -507,7 +528,7 @@ def start(self, ws) -> UtilResponse:
         """
         self.ws = ws
         ws.on_message(self._handle_message)
-        ws.on_error(lambda error: LOGGER.error("Error: %s", error))
+        ws.on_error(self._on_error)
         ws.on_close(self._on_close)
         ws.on_open(self._on_open)
 
@@ -564,6 +585,11 @@ def _run():
                         self.start(ws)
                         return  # start() / _on_close manages _closed
                     LOGGER.error("WS factory returned None")
+                    # The WebSocket leg was expected but never started; record it so
+                    # consumers don't mistake this for a clean trigger-only completion.
+                    # Guarded (first-write-wins) to match _on_error / _on_close.
+                    if self.util_response.ws_error is None:
+                        self.util_response.ws_error = "WebSocket factory returned None"
                 else:
                     LOGGER.error(
                         "Failed to trigger command: %s - %s",
@@ -572,6 +598,10 @@ def _run():
                     )
             except Exception as e:
                 LOGGER.error("Error during trigger: %s", e)
+                # This except also wraps trigger_fn(), so the message stays neutral
+                # rather than implying the failure was always in WebSocket setup.
+                if self.util_response.ws_error is None:
+                    self.util_response.ws_error = f"trigger/WebSocket setup error: {e}"
             # Mark done (failure or WS factory returned None)
             self.util_response._queue.put(None)
             self.util_response._closed.set()

tests/unit/test_ws_wrapper.py

@@ -183,3 +183,77 @@ def test_render_trims_trailing_spaces_and_empty_lines(self) -> None:
         rendered = s.render()
         assert rendered == "A"
         assert not rendered.endswith(" ")
+
+
+# ------------------------------------------------------------------
+# ws_error / ws_close_code (issue #29): let consumers distinguish a clean
+# WebSocket completion from an errored / abnormal / never-started one.
+# ------------------------------------------------------------------
+class TestUtilResponseWsErrorDefaults:
+    def test_defaults_are_none(self) -> None:
+        r = UtilResponse()
+        assert r.ws_error is None
+        assert r.ws_close_code is None
+
+
+class TestOnError:
+    def test_records_first_error(self) -> None:
+        w = _make_wrapper()
+        w._on_error(Exception("boom"))
+        assert w.util_response.ws_error == "boom"
+
+    def test_does_not_overwrite_existing(self) -> None:
+        w = _make_wrapper()
+        w._on_error(Exception("first"))
+        w._on_error(Exception("second"))
+        assert w.util_response.ws_error == "first"
+
+
+class TestOnClose:
+    def test_normal_close_is_clean(self) -> None:
+        w = _make_wrapper()
+        w._on_close(1000, "")
+        assert w.util_response.ws_close_code == 1000
+        assert w.util_response.ws_error is None
+
+    def test_abnormal_close_sets_error(self) -> None:
+        w = _make_wrapper()
+        w._on_close(1006, "abnormal closure")
+        assert w.util_response.ws_close_code == 1006
+        assert "1006" in (w.util_response.ws_error or "")
+
+    def test_no_status_close_is_not_flagged(self) -> None:
+        w = _make_wrapper()
+        w._on_close(None, "")
+        assert w.util_response.ws_close_code is None
+        assert w.util_response.ws_error is None
+
+
+class TestStartWithTriggerWsError:
+    """A WS-backed command whose WebSocket never starts must record ws_error so it
+    is not mistaken for a clean trigger-only completion."""
+
+    @staticmethod
+    def _trigger(status: int = 200, data=None):
+        return Mock(status_code=status, data=data if data is not None else {})
+
+    def test_ws_factory_returning_none_sets_ws_error(self) -> None:
+        w = _make_wrapper()
+        w.start_with_trigger(
+            trigger_fn=lambda: self._trigger(),
+            ws_factory_fn=lambda trigger: None,
+        )
+        w.util_response.wait(timeout=5)
+        assert w.util_response.done
+        assert w.util_response.ws_required is False  # WS never started
+        assert w.util_response.ws_error == "WebSocket factory returned None"
+
+    def test_ws_factory_raising_sets_ws_error(self) -> None:
+        def boom(trigger):
+            raise RuntimeError("factory kaboom")
+
+        w = _make_wrapper()
+        w.start_with_trigger(trigger_fn=lambda: self._trigger(), ws_factory_fn=boom)
+        w.util_response.wait(timeout=5)
+        assert w.util_response.done
+        assert "factory kaboom" in (w.util_response.ws_error or "")