Wrap base URL decode failures with context

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

Author: cursoragent

hyperbrowser/config.py

@@ -38,16 +38,37 @@ def __post_init__(self) -> None:
     def _decode_url_component_with_limit(value: str, *, component_label: str) -> str:
         decoded_value = value
         for _ in range(10):
-            next_decoded_value = unquote(decoded_value)
+            next_decoded_value = ClientConfig._safe_unquote(
+                decoded_value,
+                component_label=component_label,
+            )
             if next_decoded_value == decoded_value:
                 return decoded_value
             decoded_value = next_decoded_value
-        if unquote(decoded_value) == decoded_value:
+        if (
+            ClientConfig._safe_unquote(
+                decoded_value,
+                component_label=component_label,
+            )
+            == decoded_value
+        ):
             return decoded_value
         raise HyperbrowserError(
             f"{component_label} contains excessively nested URL encoding"
         )
 
+    @staticmethod
+    def _safe_unquote(value: str, *, component_label: str) -> str:
+        try:
+            return unquote(value)
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            raise HyperbrowserError(
+                f"Failed to decode {component_label}",
+                original_error=exc,
+            ) from exc
+
     @staticmethod
     def normalize_base_url(base_url: str) -> str:
         if not isinstance(base_url, str):
@@ -136,7 +157,10 @@ def normalize_base_url(base_url: str) -> str:
                 raise HyperbrowserError(
                     "base_url host must not contain encoded delimiter characters"
                 )
-            next_decoded_base_netloc = unquote(decoded_base_netloc)
+            next_decoded_base_netloc = ClientConfig._safe_unquote(
+                decoded_base_netloc,
+                component_label="base_url host",
+            )
             if next_decoded_base_netloc == decoded_base_netloc:
                 break
             decoded_base_netloc = next_decoded_base_netloc
@@ -145,7 +169,13 @@ def normalize_base_url(base_url: str) -> str:
                 raise HyperbrowserError(
                     "base_url host must not contain encoded delimiter characters"
                 )
-            if unquote(decoded_base_netloc) != decoded_base_netloc:
+            if (
+                ClientConfig._safe_unquote(
+                    decoded_base_netloc,
+                    component_label="base_url host",
+                )
+                != decoded_base_netloc
+            ):
                 raise HyperbrowserError(
                     "base_url host contains excessively nested URL encoding"
                 )

tests/test_config.py

@@ -459,6 +459,50 @@ def _raise_hyperbrowser_error(_value: str):
     assert exc_info.value.original_error is None
 
 
+def test_client_config_normalize_base_url_wraps_path_decode_runtime_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    def _raise_runtime_error(_value: str) -> str:
+        raise RuntimeError("path decode exploded")
+
+    monkeypatch.setattr(config_module, "unquote", _raise_runtime_error)
+
+    with pytest.raises(HyperbrowserError, match="Failed to decode base_url path") as exc_info:
+        ClientConfig.normalize_base_url("https://example.local/api")
+
+    assert exc_info.value.original_error is not None
+
+
+def test_client_config_normalize_base_url_wraps_host_decode_runtime_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    def _conditional_unquote(value: str) -> str:
+        if value == "example.local":
+            raise RuntimeError("host decode exploded")
+        return value
+
+    monkeypatch.setattr(config_module, "unquote", _conditional_unquote)
+
+    with pytest.raises(HyperbrowserError, match="Failed to decode base_url host") as exc_info:
+        ClientConfig.normalize_base_url("https://example.local/api")
+
+    assert exc_info.value.original_error is not None
+
+
+def test_client_config_normalize_base_url_preserves_hyperbrowser_decode_errors(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    def _raise_hyperbrowser_error(_value: str) -> str:
+        raise HyperbrowserError("custom decode failure")
+
+    monkeypatch.setattr(config_module, "unquote", _raise_hyperbrowser_error)
+
+    with pytest.raises(HyperbrowserError, match="custom decode failure") as exc_info:
+        ClientConfig.normalize_base_url("https://example.local/api")
+
+    assert exc_info.value.original_error is None
+
+
 def test_client_config_normalize_base_url_preserves_invalid_port_original_error():
     with pytest.raises(
         HyperbrowserError, match="base_url must contain a valid port number"