Prevent duplicate default headers on case-insensitive overrides

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

Author: cursoragent

hyperbrowser/header_utils.py

@@ -41,6 +41,33 @@ def normalize_headers(
     return normalized_headers
 
 
+def merge_headers(
+    base_headers: Mapping[str, str],
+    override_headers: Optional[Mapping[str, str]],
+    *,
+    mapping_error_message: str,
+    pair_error_message: Optional[str] = None,
+) -> Dict[str, str]:
+    merged_headers = dict(base_headers)
+    normalized_overrides = normalize_headers(
+        override_headers,
+        mapping_error_message=mapping_error_message,
+        pair_error_message=pair_error_message,
+    )
+    if not normalized_overrides:
+        return merged_headers
+
+    existing_canonical_to_key = {key.lower(): key for key in merged_headers}
+    for override_key, override_value in normalized_overrides.items():
+        canonical_override_key = override_key.lower()
+        existing_key = existing_canonical_to_key.get(canonical_override_key)
+        if existing_key is not None:
+            del merged_headers[existing_key]
+        merged_headers[override_key] = override_value
+        existing_canonical_to_key[canonical_override_key] = override_key
+    return merged_headers
+
+
 def parse_headers_env_json(raw_headers: Optional[str]) -> Optional[Dict[str, str]]:
     if raw_headers is None:
         return None

hyperbrowser/transport/async_transport.py

@@ -3,7 +3,7 @@
 from typing import Mapping, Optional
 
 from hyperbrowser.exceptions import HyperbrowserError
-from hyperbrowser.header_utils import normalize_headers
+from hyperbrowser.header_utils import merge_headers
 from hyperbrowser.version import __version__
 from .base import APIResponse, AsyncTransportStrategy
 from .error_utils import extract_error_message, extract_request_error_context
@@ -18,16 +18,14 @@ def __init__(self, api_key: str, headers: Optional[Mapping[str, str]] = None):
         normalized_api_key = api_key.strip()
         if not normalized_api_key:
             raise HyperbrowserError("api_key must not be empty")
-        merged_headers = {
-            "x-api-key": normalized_api_key,
-            "User-Agent": f"hyperbrowser-python-sdk/{__version__}",
-        }
-        normalized_headers = normalize_headers(
+        merged_headers = merge_headers(
+            {
+                "x-api-key": normalized_api_key,
+                "User-Agent": f"hyperbrowser-python-sdk/{__version__}",
+            },
             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,7 +3,7 @@
 from typing import Mapping, Optional
 
 from hyperbrowser.exceptions import HyperbrowserError
-from hyperbrowser.header_utils import normalize_headers
+from hyperbrowser.header_utils import merge_headers
 from hyperbrowser.version import __version__
 from .base import APIResponse, SyncTransportStrategy
 from .error_utils import extract_error_message, extract_request_error_context
@@ -18,16 +18,14 @@ def __init__(self, api_key: str, headers: Optional[Mapping[str, str]] = None):
         normalized_api_key = api_key.strip()
         if not normalized_api_key:
             raise HyperbrowserError("api_key must not be empty")
-        merged_headers = {
-            "x-api-key": normalized_api_key,
-            "User-Agent": f"hyperbrowser-python-sdk/{__version__}",
-        }
-        normalized_headers = normalize_headers(
+        merged_headers = merge_headers(
+            {
+                "x-api-key": normalized_api_key,
+                "User-Agent": f"hyperbrowser-python-sdk/{__version__}",
+            },
             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)
 
     def _handle_response(self, response: httpx.Response) -> APIResponse:

tests/test_header_utils.py

@@ -1,7 +1,11 @@
 import pytest
 
 from hyperbrowser.exceptions import HyperbrowserError
-from hyperbrowser.header_utils import normalize_headers, parse_headers_env_json
+from hyperbrowser.header_utils import (
+    merge_headers,
+    normalize_headers,
+    parse_headers_env_json,
+)
 
 
 def test_normalize_headers_trims_header_names():
@@ -67,3 +71,16 @@ def test_parse_headers_env_json_rejects_non_mapping_payload():
         match="HYPERBROWSER_HEADERS must be a JSON object of string pairs",
     ):
         parse_headers_env_json('["bad"]')
+
+
+def test_merge_headers_replaces_existing_headers_case_insensitively():
+    merged = merge_headers(
+        {"User-Agent": "default-sdk", "x-api-key": "test-key"},
+        {"user-agent": "custom-sdk", "X-API-KEY": "override-key"},
+        mapping_error_message="headers must be a mapping of string pairs",
+    )
+
+    assert merged["user-agent"] == "custom-sdk"
+    assert merged["X-API-KEY"] == "override-key"
+    assert "User-Agent" not in merged
+    assert "x-api-key" not in merged

tests/test_transport_headers.py

@@ -30,3 +30,50 @@ async def run() -> None:
             await transport.close()
 
     asyncio.run(run())
+
+
+def test_sync_transport_case_insensitive_header_overrides_replace_defaults():
+    transport = SyncTransport(
+        api_key="test-key",
+        headers={"user-agent": "custom-agent", "X-API-KEY": "override-key"},
+    )
+    try:
+        user_agent_values = [
+            value
+            for key, value in transport.client.headers.multi_items()
+            if key.lower() == "user-agent"
+        ]
+        api_key_values = [
+            value
+            for key, value in transport.client.headers.multi_items()
+            if key.lower() == "x-api-key"
+        ]
+        assert user_agent_values == ["custom-agent"]
+        assert api_key_values == ["override-key"]
+    finally:
+        transport.close()
+
+
+def test_async_transport_case_insensitive_header_overrides_replace_defaults():
+    async def run() -> None:
+        transport = AsyncTransport(
+            api_key="test-key",
+            headers={"user-agent": "custom-agent", "X-API-KEY": "override-key"},
+        )
+        try:
+            user_agent_values = [
+                value
+                for key, value in transport.client.headers.multi_items()
+                if key.lower() == "user-agent"
+            ]
+            api_key_values = [
+                value
+                for key, value in transport.client.headers.multi_items()
+                if key.lower() == "x-api-key"
+            ]
+            assert user_agent_values == ["custom-agent"]
+            assert api_key_values == ["override-key"]
+        finally:
+            await transport.close()
+
+    asyncio.run(run())