Centralize header parsing and normalization utilities

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

Author: cursoragent

hyperbrowser/config.py

@@ -1,10 +1,10 @@
 from dataclasses import dataclass
-import json
 from urllib.parse import urlparse
 from typing import Dict, Mapping, Optional
 import os
 
 from .exceptions import HyperbrowserError
+from .header_utils import normalize_headers, parse_headers_env_json
 
 
 @dataclass
@@ -36,25 +36,10 @@ def __post_init__(self) -> None:
             raise HyperbrowserError(
                 "base_url must start with 'https://' or 'http://' and include a host"
             )
-        if self.headers is not None:
-            normalized_headers: Dict[str, str] = {}
-            for key, value in self.headers.items():
-                if not isinstance(key, str) or not isinstance(value, str):
-                    raise HyperbrowserError("headers must be a mapping of string pairs")
-                normalized_key = key.strip()
-                if not normalized_key:
-                    raise HyperbrowserError("header names must not be empty")
-                if (
-                    "\n" in normalized_key
-                    or "\r" in normalized_key
-                    or "\n" in value
-                    or "\r" in value
-                ):
-                    raise HyperbrowserError(
-                        "headers must not contain newline characters"
-                    )
-                normalized_headers[normalized_key] = value
-            self.headers = normalized_headers
+        self.headers = normalize_headers(
+            self.headers,
+            mapping_error_message="headers must be a mapping of string pairs",
+        )
 
     @classmethod
     def from_env(cls) -> "ClientConfig":
@@ -72,23 +57,4 @@ def from_env(cls) -> "ClientConfig":
 
     @staticmethod
     def parse_headers_from_env(raw_headers: Optional[str]) -> Optional[Dict[str, str]]:
-        if raw_headers is None or not raw_headers.strip():
-            return None
-        try:
-            parsed_headers = json.loads(raw_headers)
-        except json.JSONDecodeError as exc:
-            raise HyperbrowserError(
-                "HYPERBROWSER_HEADERS must be valid JSON object"
-            ) from exc
-        if not isinstance(parsed_headers, dict):
-            raise HyperbrowserError(
-                "HYPERBROWSER_HEADERS must be a JSON object of string pairs"
-            )
-        if any(
-            not isinstance(key, str) or not isinstance(value, str)
-            for key, value in parsed_headers.items()
-        ):
-            raise HyperbrowserError(
-                "HYPERBROWSER_HEADERS must be a JSON object of string pairs"
-            )
-        return parsed_headers
+        return parse_headers_env_json(raw_headers)

hyperbrowser/header_utils.py

@@ -0,0 +1,50 @@
+import json
+from typing import Dict, Mapping, Optional
+
+from .exceptions import HyperbrowserError
+
+
+def normalize_headers(
+    headers: Optional[Mapping[str, str]],
+    *,
+    mapping_error_message: str,
+    pair_error_message: Optional[str] = None,
+) -> Optional[Dict[str, str]]:
+    if headers is None:
+        return None
+    if not isinstance(headers, Mapping):
+        raise HyperbrowserError(mapping_error_message)
+
+    effective_pair_error_message = pair_error_message or mapping_error_message
+    normalized_headers: Dict[str, str] = {}
+    for key, value in headers.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            raise HyperbrowserError(effective_pair_error_message)
+        normalized_key = key.strip()
+        if not normalized_key:
+            raise HyperbrowserError("header names must not be empty")
+        if (
+            "\n" in normalized_key
+            or "\r" in normalized_key
+            or "\n" in value
+            or "\r" in value
+        ):
+            raise HyperbrowserError("headers must not contain newline characters")
+        normalized_headers[normalized_key] = value
+    return normalized_headers
+
+
+def parse_headers_env_json(raw_headers: Optional[str]) -> Optional[Dict[str, str]]:
+    if raw_headers is None or not raw_headers.strip():
+        return None
+    try:
+        parsed_headers = json.loads(raw_headers)
+    except json.JSONDecodeError as exc:
+        raise HyperbrowserError(
+            "HYPERBROWSER_HEADERS must be valid JSON object"
+        ) from exc
+    return normalize_headers(
+        parsed_headers,  # type: ignore[arg-type]
+        mapping_error_message="HYPERBROWSER_HEADERS must be a JSON object of string pairs",
+        pair_error_message="HYPERBROWSER_HEADERS must be a JSON object of string pairs",
+    )

hyperbrowser/transport/async_transport.py

@@ -3,6 +3,7 @@
 from typing import Mapping, Optional
 
 from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.header_utils import normalize_headers
 from hyperbrowser.version import __version__
 from .base import APIResponse, AsyncTransportStrategy
 from .error_utils import extract_error_message
@@ -16,24 +17,11 @@ def __init__(self, api_key: str, headers: Optional[Mapping[str, str]] = None):
             "x-api-key": api_key,
             "User-Agent": f"hyperbrowser-python-sdk/{__version__}",
         }
-        if headers:
-            normalized_headers = {}
-            for key, value in headers.items():
-                if not isinstance(key, str) or not isinstance(value, str):
-                    raise HyperbrowserError("headers must be a mapping of string pairs")
-                normalized_key = key.strip()
-                if not normalized_key:
-                    raise HyperbrowserError("header names must not be empty")
-                if (
-                    "\n" in normalized_key
-                    or "\r" in normalized_key
-                    or "\n" in value
-                    or "\r" in value
-                ):
-                    raise HyperbrowserError(
-                        "headers must not contain newline characters"
-                    )
-                normalized_headers[normalized_key] = value
+        normalized_headers = normalize_headers(
+            headers,
+            mapping_error_message="headers must be a mapping of string pairs",
+        )
+        if normalized_headers:
             merged_headers.update(normalized_headers)
         self.client = httpx.AsyncClient(headers=merged_headers)
         self._closed = False

hyperbrowser/transport/sync.py

@@ -3,6 +3,7 @@
 from typing import Mapping, Optional
 
 from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.header_utils import normalize_headers
 from hyperbrowser.version import __version__
 from .base import APIResponse, SyncTransportStrategy
 from .error_utils import extract_error_message
@@ -16,24 +17,11 @@ def __init__(self, api_key: str, headers: Optional[Mapping[str, str]] = None):
             "x-api-key": api_key,
             "User-Agent": f"hyperbrowser-python-sdk/{__version__}",
         }
-        if headers:
-            normalized_headers = {}
-            for key, value in headers.items():
-                if not isinstance(key, str) or not isinstance(value, str):
-                    raise HyperbrowserError("headers must be a mapping of string pairs")
-                normalized_key = key.strip()
-                if not normalized_key:
-                    raise HyperbrowserError("header names must not be empty")
-                if (
-                    "\n" in normalized_key
-                    or "\r" in normalized_key
-                    or "\n" in value
-                    or "\r" in value
-                ):
-                    raise HyperbrowserError(
-                        "headers must not contain newline characters"
-                    )
-                normalized_headers[normalized_key] = value
+        normalized_headers = normalize_headers(
+            headers,
+            mapping_error_message="headers must be a mapping of string pairs",
+        )
+        if normalized_headers:
             merged_headers.update(normalized_headers)
         self.client = httpx.Client(headers=merged_headers)
 

tests/test_header_utils.py

@@ -0,0 +1,40 @@
+import pytest
+
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.header_utils import normalize_headers, parse_headers_env_json
+
+
+def test_normalize_headers_trims_header_names():
+    headers = normalize_headers(
+        {"  X-Correlation-Id  ": "abc123"},
+        mapping_error_message="headers must be a mapping of string pairs",
+    )
+
+    assert headers == {"X-Correlation-Id": "abc123"}
+
+
+def test_normalize_headers_rejects_empty_header_name():
+    with pytest.raises(HyperbrowserError, match="header names must not be empty"):
+        normalize_headers(
+            {"   ": "value"},
+            mapping_error_message="headers must be a mapping of string pairs",
+        )
+
+
+def test_parse_headers_env_json_ignores_blank_values():
+    assert parse_headers_env_json("   ") is None
+
+
+def test_parse_headers_env_json_rejects_invalid_json():
+    with pytest.raises(
+        HyperbrowserError, match="HYPERBROWSER_HEADERS must be valid JSON object"
+    ):
+        parse_headers_env_json("{invalid")
+
+
+def test_parse_headers_env_json_rejects_non_mapping_payload():
+    with pytest.raises(
+        HyperbrowserError,
+        match="HYPERBROWSER_HEADERS must be a JSON object of string pairs",
+    ):
+        parse_headers_env_json('["bad"]')