feat: add headers configuration property (#233)

Author: ewanharris

README.md

@@ -204,7 +204,7 @@ async def main():
 
 #### Default Headers
 
-You can set default headers that will be sent with every request by accessing the API client and using the `set_default_header` method:
+You can configure default headers that will be sent with every request by passing them to the `ClientConfiguration`:
 
 ```python
 from openfga_sdk import ClientConfiguration, OpenFgaClient
@@ -215,13 +215,13 @@ async def main():
         api_url=FGA_API_URL,
         store_id=FGA_STORE_ID,
         authorization_model_id=FGA_MODEL_ID,
+        headers={
+            "X-Custom-Header": "default-value",
+            "X-Request-Source": "my-app",
+        },
     )
 
     async with OpenFgaClient(configuration) as fga_client:
-        # Set default headers that will be sent with every request
-        fga_client._api_client.set_default_header("X-Custom-Header", "default-value")
-        fga_client._api_client.set_default_header("X-Request-Source", "my-app")
-
         api_response = await fga_client.read_authorization_models()
         return api_response
 ```

openfga_sdk/client/client.py

@@ -168,6 +168,11 @@ def __init__(self, configuration: ClientConfiguration):
         self._api_client = ApiClient(configuration)
         self._api = OpenFgaApi(self._api_client)
 
+        # Set default headers from configuration
+        if configuration.headers:
+            for header_name, header_value in configuration.headers.items():
+                self._api_client.set_default_header(header_name, header_value)
+
     async def __aenter__(self):
         return self
 

openfga_sdk/client/configuration.py

@@ -53,6 +53,7 @@ def __init__(
             ]
             | None
         ) = None,
+        headers: dict[str, str] | None = None,
     ):
         super().__init__(
             api_scheme,
@@ -64,6 +65,7 @@ def __init__(
             api_url=api_url,
             timeout_millisec=timeout_millisec,
             telemetry=telemetry,
+            headers=headers,
         )
         self._authorization_model_id = authorization_model_id
 

openfga_sdk/configuration.py

@@ -202,6 +202,7 @@ def __init__(
             | None
         ) = None,
         timeout_millisec: int | None = None,
+        headers: dict[str, str] | None = None,
     ):
         """Constructor"""
         self._url = api_url
@@ -326,6 +327,10 @@ def __init__(
         """Telemetry configuration
         """
 
+        self._headers = headers or {}
+        """Default headers to be sent with every request
+        """
+
     def __deepcopy__(self, memo):
         cls = self.__class__
         result = cls.__new__(cls)
@@ -656,6 +661,17 @@ def is_valid(self):
                     f"timeout_millisec not within reasonable range (0,60000), {self._timeout_millisec}"
                 )
 
+        if self._headers is not None:
+            for key, value in self._headers.items():
+                if not isinstance(key, str):
+                    raise FgaValidationException(
+                        f"header keys must be strings, got {type(key).__name__} for key {key}"
+                    )
+                if not isinstance(value, str):
+                    raise FgaValidationException(
+                        f"header values must be strings, got {type(value).__name__} for key '{key}'"
+                    )
+
     @property
     def api_scheme(self):
         """Return connection is https or http."""
@@ -740,3 +756,31 @@ def timeout_millisec(self, value):
         Update timeout milliseconds
         """
         self._timeout_millisec = value
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """
+        Return default headers to be sent with every request.
+
+        Headers are key-value pairs that will be included in all API requests.
+        Common use cases include correlation IDs, API versioning, and tenant identification.
+        """
+        return self._headers
+
+    @headers.setter
+    def headers(self, value: dict[str, str] | None) -> None:
+        """
+        Update default headers to be sent with every request.
+
+        Args:
+            value: Dictionary of header names to values, or None to clear headers.
+                   Both keys and values must be strings.
+
+        Raises:
+            FgaValidationException: If value is not a dict or None.
+        """
+        if value is not None and not isinstance(value, dict):
+            raise FgaValidationException(
+                f"headers must be a dict or None, got {type(value).__name__}"
+            )
+        self._headers = value or {}

openfga_sdk/sync/client/client.py

@@ -169,6 +169,11 @@ def __init__(self, configuration: ClientConfiguration) -> None:
         self._api_client = ApiClient(configuration)
         self._api = OpenFgaApi(self._api_client)
 
+        # Set default headers from configuration
+        if configuration.headers:
+            for header_name, header_value in configuration.headers.items():
+                self._api_client.set_default_header(header_name, header_value)
+
     def __enter__(self):
         return self