feat: Provide HTTP headers via Fault event

Author: keelerm84

ld_eventsource/actions.py

@@ -1,6 +1,8 @@
 import json
 from typing import Any, Dict, Optional
 
+from ld_eventsource.errors import ExceptionWithHeaders
+
 
 class Action:
     """
@@ -144,6 +146,9 @@ class Fault(Action):
     connection attempt has failed or an existing connection has been closed. The SSEClient
     will attempt to reconnect if you either call :meth:`.SSEClient.start()`
     or simply continue reading events after this point.
+
+    When the error includes HTTP response headers (such as for :class:`.HTTPStatusError`
+    or :class:`.HTTPContentTypeError`), they are accessible via the :attr:`headers` property.
     """
 
     def __init__(self, error: Optional[Exception]):
@@ -157,3 +162,18 @@ def error(self) -> Optional[Exception]:
         in an orderly way after sending an EOF chunk as defined by chunked transfer encoding.
         """
         return self.__error
+
+    @property
+    def headers(self) -> Optional[Dict[str, Any]]:
+        """
+        The HTTP response headers from the failed connection, if available.
+
+        This property returns headers when the error is an exception that includes them,
+        such as :class:`.HTTPStatusError` or :class:`.HTTPContentTypeError`. For other
+        error types or when the stream ended normally, this returns ``None``.
+
+        :return: the response headers, or ``None`` if not available
+        """
+        if isinstance(self.__error, ExceptionWithHeaders):
+            return self.__error.headers
+        return None

ld_eventsource/errors.py

@@ -1,28 +1,62 @@
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ExceptionWithHeaders(Protocol):
+    """
+    Protocol for exceptions that include HTTP response headers.
+
+    This allows type-safe access to headers from error responses without
+    using hasattr checks.
+    """
+
+    @property
+    def headers(self) -> Optional[Dict[str, Any]]:
+        """The HTTP response headers associated with this exception."""
+        raise NotImplementedError
+
+
 class HTTPStatusError(Exception):
     """
     This exception indicates that the client was able to connect to the server, but that
     the HTTP response had an error status.
+
+    When available, the response headers are accessible via the :attr:`headers` property.
     """
 
-    def __init__(self, status: int):
+    def __init__(self, status: int, headers: Optional[Dict[str, Any]] = None):
         super().__init__("HTTP error %d" % status)
         self._status = status
+        self._headers = headers
 
     @property
     def status(self) -> int:
         return self._status
 
+    @property
+    def headers(self) -> Optional[Dict[str, Any]]:
+        """The HTTP response headers, if available."""
+        return self._headers
+
 
 class HTTPContentTypeError(Exception):
     """
     This exception indicates that the HTTP response did not have the expected content
     type of `"text/event-stream"`.
+
+    When available, the response headers are accessible via the :attr:`headers` property.
     """
 
-    def __init__(self, content_type: str):
+    def __init__(self, content_type: str, headers: Optional[Dict[str, Any]] = None):
         super().__init__("invalid content type \"%s\"" % content_type)
         self._content_type = content_type
+        self._headers = headers
 
     @property
     def content_type(self) -> str:
         return self._content_type
+
+    @property
+    def headers(self) -> Optional[Dict[str, Any]]:
+        """The HTTP response headers, if available."""
+        return self._headers

ld_eventsource/http.py

@@ -100,16 +100,19 @@ def connect(self, last_event_id: Optional[str]) -> Tuple[Iterator[bytes], Callab
             reason: Optional[Exception] = e.reason
             if reason is not None:
                 raise reason  # e.reason is the underlying I/O error
+
+        # Capture headers early so they're available for both error and success cases
+        response_headers = cast(Dict[str, Any], resp.headers)
+
         if resp.status >= 400 or resp.status == 204:
-            raise HTTPStatusError(resp.status)
+            raise HTTPStatusError(resp.status, response_headers)
         content_type = resp.headers.get('Content-Type', None)
         if content_type is None or not str(content_type).startswith(
             "text/event-stream"
         ):
-            raise HTTPContentTypeError(content_type or '')
+            raise HTTPContentTypeError(content_type or '', response_headers)
 
         stream = resp.stream(_CHUNK_SIZE)
-        response_headers = cast(Dict[str, Any], resp.headers)
 
         def close():
             try:

ld_eventsource/testing/test_headers.py

@@ -148,3 +148,68 @@ def test_connection_result_no_headers():
     """Test that ConnectionResult returns None when no headers provided"""
     result = ConnectionResult(stream=iter([b'data']), closer=None)
     assert result.headers is None
+
+
+def test_http_status_error_includes_headers():
+    """Test that HTTPStatusError can store and expose headers"""
+    headers = {'Retry-After': '120', 'X-RateLimit-Remaining': '0'}
+    error = HTTPStatusError(429, headers)
+    assert error.status == 429
+    assert error.headers == headers
+    assert error.headers.get('Retry-After') == '120'
+
+
+def test_http_content_type_error_includes_headers():
+    """Test that HTTPContentTypeError can store and expose headers"""
+    headers = {'Content-Type': 'text/plain', 'X-Custom': 'value'}
+    error = HTTPContentTypeError('text/plain', headers)
+    assert error.content_type == 'text/plain'
+    assert error.headers == headers
+    assert error.headers.get('X-Custom') == 'value'
+
+
+def test_fault_exposes_headers_from_http_status_error():
+    """Test that Fault.headers delegates to HTTPStatusError.headers"""
+    headers = {'Retry-After': '60'}
+    error = HTTPStatusError(503, headers)
+    fault = Fault(error)
+
+    assert fault.error == error
+    assert fault.headers == headers
+    assert fault.headers.get('Retry-After') == '60'
+
+
+def test_fault_exposes_headers_from_http_content_type_error():
+    """Test that Fault.headers delegates to HTTPContentTypeError.headers"""
+    headers = {'Content-Type': 'application/json'}
+    error = HTTPContentTypeError('application/json', headers)
+    fault = Fault(error)
+
+    assert fault.error == error
+    assert fault.headers == headers
+
+
+def test_fault_headers_none_for_non_http_errors():
+    """Test that Fault.headers returns None for errors without headers"""
+    error = RuntimeError("some error")
+    fault = Fault(error)
+
+    assert fault.error == error
+    assert fault.headers is None
+
+
+def test_fault_headers_none_when_no_error():
+    """Test that Fault.headers returns None when there's no error"""
+    fault = Fault(None)
+
+    assert fault.error is None
+    assert fault.headers is None
+
+
+def test_fault_headers_none_when_exception_has_no_headers():
+    """Test that Fault.headers returns None when exception doesn't provide headers"""
+    error = HTTPStatusError(500)  # No headers provided
+    fault = Fault(error)
+
+    assert fault.error == error
+    assert fault.headers is None

ld_eventsource/testing/test_http_connect_strategy.py

@@ -182,3 +182,60 @@ def test_http_response_headers_in_sse_client():
 
                 # Second item should be the event
                 assert isinstance(all_items[1], Event)
+
+
+def test_http_status_error_includes_headers():
+    """Test that HTTPStatusError captures response headers"""
+    with start_server() as server:
+        server.for_path('/', BasicResponse(429, None, {
+            'Retry-After': '120',
+            'X-RateLimit-Remaining': '0',
+            'X-RateLimit-Reset': '1234567890'
+        }))
+        try:
+            with ConnectStrategy.http(server.uri).create_client(logger()) as client:
+                client.connect(None)
+            raise Exception("expected exception, did not get one")
+        except HTTPStatusError as e:
+            assert e.status == 429
+            assert e.headers is not None
+            assert e.headers.get('Retry-After') == '120'
+            assert e.headers.get('X-RateLimit-Remaining') == '0'
+            assert e.headers.get('X-RateLimit-Reset') == '1234567890'
+
+
+def test_http_content_type_error_includes_headers():
+    """Test that HTTPContentTypeError captures response headers"""
+    with start_server() as server:
+        with ChunkedResponse({'Content-Type': 'application/json', 'X-Custom': 'value'}) as stream:
+            server.for_path('/', stream)
+            try:
+                with ConnectStrategy.http(server.uri).create_client(logger()) as client:
+                    client.connect(None)
+                raise Exception("expected exception, did not get one")
+            except HTTPContentTypeError as e:
+                assert e.content_type == "application/json"
+                assert e.headers is not None
+                assert e.headers.get('Content-Type') == 'application/json'
+                assert e.headers.get('X-Custom') == 'value'
+
+
+def test_fault_exposes_headers_from_http_error():
+    """Test that Fault.headers exposes headers from HTTP errors"""
+    with start_server() as server:
+        server.for_path('/', BasicResponse(503, None, {
+            'Retry-After': '60',
+            'X-Error-Code': 'SERVICE_UNAVAILABLE'
+        }))
+        with SSEClient(
+            connect=ConnectStrategy.http(server.uri),
+            error_strategy=ErrorStrategy.always_continue(),
+            retry_delay_strategy=no_delay()
+        ) as client:
+            # Read first item which should be a Fault with the error
+            fault = next(client.all)
+            assert isinstance(fault, Fault)
+            assert isinstance(fault.error, HTTPStatusError)
+            assert fault.headers is not None
+            assert fault.headers.get('Retry-After') == '60'
+            assert fault.headers.get('X-Error-Code') == 'SERVICE_UNAVAILABLE'