Improve response parser value-read diagnostics

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

hyperbrowser/client/managers/response_utils.py

@@ -6,6 +6,8 @@
 T = TypeVar("T")
 _MAX_OPERATION_NAME_DISPLAY_LENGTH = 120
 _TRUNCATED_OPERATION_NAME_SUFFIX = "... (truncated)"
+_MAX_KEY_DISPLAY_LENGTH = 120
+_TRUNCATED_KEY_DISPLAY_SUFFIX = "... (truncated)"
 
 
 def _normalize_operation_name_for_error(operation_name: str) -> str:
@@ -25,6 +27,21 @@ def _normalize_operation_name_for_error(operation_name: str) -> str:
     return f"{normalized_name[:available_length]}{_TRUNCATED_OPERATION_NAME_SUFFIX}"
 
 
+def _normalize_response_key_for_error(key: str) -> str:
+    normalized_key = "".join(
+        "?" if ord(character) < 32 or ord(character) == 127 else character
+        for character in key
+    ).strip()
+    if not normalized_key:
+        return "<blank key>"
+    if len(normalized_key) <= _MAX_KEY_DISPLAY_LENGTH:
+        return normalized_key
+    available_length = _MAX_KEY_DISPLAY_LENGTH - len(_TRUNCATED_KEY_DISPLAY_SUFFIX)
+    if available_length <= 0:
+        return _TRUNCATED_KEY_DISPLAY_SUFFIX
+    return f"{normalized_key[:available_length]}{_TRUNCATED_KEY_DISPLAY_SUFFIX}"
+
+
 def parse_response_model(
     response_data: Any,
     *,
@@ -39,20 +56,33 @@ def parse_response_model(
             f"Expected {normalized_operation_name} response to be an object"
         )
     try:
-        response_payload = dict(response_data)
+        response_keys = list(response_data.keys())
     except HyperbrowserError:
         raise
     except Exception as exc:
         raise HyperbrowserError(
             f"Failed to read {normalized_operation_name} response data",
             original_error=exc,
         ) from exc
-    for key in response_payload.keys():
+    for key in response_keys:
         if isinstance(key, str):
             continue
         raise HyperbrowserError(
             f"Expected {normalized_operation_name} response object keys to be strings"
         )
+    response_payload: dict[str, object] = {}
+    for key in response_keys:
+        try:
+            response_payload[key] = response_data[key]
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            key_display = _normalize_response_key_for_error(key)
+            raise HyperbrowserError(
+                f"Failed to read {normalized_operation_name} response value for key "
+                f"'{key_display}'",
+                original_error=exc,
+            ) from exc
     try:
         return model(**response_payload)
     except HyperbrowserError:

tests/test_response_utils.py

@@ -133,6 +133,22 @@ def __getitem__(self, key: str) -> object:
         return self._payload[key]
 
 
+class _BrokenValueLookupMapping(Mapping[str, object]):
+    def __init__(self, *, key: str, error: Exception):
+        self._key = key
+        self._error = error
+
+    def __iter__(self):
+        yield self._key
+
+    def __len__(self) -> int:
+        return 1
+
+    def __getitem__(self, key: str) -> object:
+        _ = key
+        raise self._error
+
+
 def test_parse_response_model_parses_mapping_payloads():
     response_model = parse_response_model(
         {"success": True},
@@ -221,6 +237,54 @@ def test_parse_response_model_wraps_mapping_read_failures():
     assert exc_info.value.original_error is not None
 
 
+def test_parse_response_model_wraps_mapping_value_read_failures():
+    with pytest.raises(
+        HyperbrowserError,
+        match="Failed to read basic operation response value for key 'success'",
+    ) as exc_info:
+        parse_response_model(
+            _BrokenValueLookupMapping(
+                key="success",
+                error=RuntimeError("cannot read value"),
+            ),
+            model=BasicResponse,
+            operation_name="basic operation",
+        )
+
+    assert exc_info.value.original_error is not None
+
+
+def test_parse_response_model_sanitizes_key_display_in_value_read_failures():
+    with pytest.raises(
+        HyperbrowserError,
+        match="Failed to read basic operation response value for key 'bad\\?key'",
+    ) as exc_info:
+        parse_response_model(
+            _BrokenValueLookupMapping(
+                key="bad\tkey",
+                error=RuntimeError("cannot read value"),
+            ),
+            model=BasicResponse,
+            operation_name="basic operation",
+        )
+
+    assert exc_info.value.original_error is not None
+
+
+def test_parse_response_model_preserves_hyperbrowser_value_read_failures():
+    with pytest.raises(HyperbrowserError, match="custom read failure") as exc_info:
+        parse_response_model(
+            _BrokenValueLookupMapping(
+                key="success",
+                error=HyperbrowserError("custom read failure"),
+            ),
+            model=BasicResponse,
+            operation_name="basic operation",
+        )
+
+    assert exc_info.value.original_error is None
+
+
 def test_sync_team_manager_rejects_invalid_response_shape():
     class _SyncTransport:
         def get(self, url, params=None, follow_redirects=False):