fairagro-middleware-api-client 11.1.1.dev34__tar.gz → 12.0.1.dev35__tar.gz

{fairagro_middleware_api_client-11.1.1.dev34 → fairagro_middleware_api_client-12.0.1.dev35}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fairagro-middleware-api-client
-Version: 11.1.1.dev34
+Version: 12.0.1.dev35
 Summary: The FAIRagro advanced middleware API client
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.28.1

{fairagro_middleware_api_client-11.1.1.dev34 → fairagro_middleware_api_client-12.0.1.dev35}/pyproject.toml

@@ -36,9 +36,6 @@ markers = [
 [tool.hatch.build.targets.wheel]
 packages = ["src/middleware"]
 
-[tool.ruff]
-extend = "../../pyproject.toml"
-
 [tool.hatch.version]
 source = "vcs"
 raw-options = { root = "../..", fallback_version = "0.0.0", tag_regex = "^(?:v|.*-(?:chart|docker)-v)(?P<version>\\d+\\.\\d+\\.\\d+)(?:$|[-+].*)" }

{fairagro_middleware_api_client-11.1.1.dev34 → fairagro_middleware_api_client-12.0.1.dev35}/src/middleware/api_client/api_client.py

@@ -5,7 +5,8 @@ import json
 import logging
 import ssl
 import threading
-from collections.abc import AsyncGenerator, AsyncIterator
+import uuid
+from collections.abc import AsyncGenerator, AsyncIterator, Mapping
 from contextlib import asynccontextmanager
 from datetime import UTC, datetime
 from http import HTTPStatus
@@ -69,12 +70,21 @@ class ApiClient:
     _global_in_flight_requests: int = 0
     _global_state_lock = threading.Lock()
 
+    @classmethod
+    def _has_idempotency_key(cls, headers: Mapping[str, str] | None) -> bool:
+        """Return True when headers contain a non-empty Idempotency-Key."""
+        if not headers:
+            return False
+        for key, value in headers.items():
+            if key.lower() == "idempotency-key":
+                return bool(str(value).strip())
+        return False
+
     @classmethod
     def _is_idempotent_arc_post_path(cls, path: str) -> bool:
         """Return whether *path* is a server-idempotent ARC POST endpoint.
 
         Covers ``POST /v3/arcs`` and ``POST /v3/harvests/{harvest_id}/arcs``.
-        Other POSTs (create/complete harvest) are not safe to retry.
         """
         normalized = path.lstrip("/")
         if normalized == "v3/arcs":
@@ -86,11 +96,29 @@ class ApiClient:
         )
 
     @classmethod
-    def _is_retryable_method(cls, method: str, path: str) -> bool:
+    def _is_idempotent_post_path(cls, path: str, headers: Mapping[str, str] | None = None) -> bool:
+        """Return whether a POST path is safe to retry with an identical request.
+
+        Covers idempotent ARC POSTs and ``POST /v3/harvests`` only when a
+        non-empty ``Idempotency-Key`` header is present. Harvest completion
+        remains non-retryable.
+        """
+        normalized = path.lstrip("/")
+        if normalized == "v3/harvests":
+            return cls._has_idempotency_key(headers)
+        return cls._is_idempotent_arc_post_path(path)
+
+    @classmethod
+    def _is_retryable_method(
+        cls,
+        method: str,
+        path: str,
+        headers: Mapping[str, str] | None = None,
+    ) -> bool:
         """Return whether failures for this method/path may be retried."""
         if method in cls._IDEMPOTENT_METHODS:
             return True
-        return method == "POST" and cls._is_idempotent_arc_post_path(path)
+        return method == "POST" and cls._is_idempotent_post_path(path, headers)
 
     @classmethod
     def _configure_global_request_limiter(cls, max_concurrency: int) -> None:
@@ -132,15 +160,27 @@ class ApiClient:
             limiter.release()
 
     @classmethod
-    def _should_retry_http_status(cls, method: str, path: str, status_code: int) -> bool:
+    def _should_retry_http_status(
+        cls,
+        method: str,
+        path: str,
+        status_code: int,
+        headers: Mapping[str, str] | None = None,
+    ) -> bool:
         """Return whether a response status is retryable for a method/path."""
         transient = {httpx.codes.BAD_GATEWAY, httpx.codes.SERVICE_UNAVAILABLE, httpx.codes.GATEWAY_TIMEOUT}
-        return cls._is_retryable_method(method, path) and status_code in transient
+        return cls._is_retryable_method(method, path, headers) and status_code in transient
 
     @classmethod
-    def _should_retry_request_error(cls, method: str, path: str, error: httpx.RequestError) -> bool:
+    def _should_retry_request_error(
+        cls,
+        method: str,
+        path: str,
+        error: httpx.RequestError,
+        headers: Mapping[str, str] | None = None,
+    ) -> bool:
         """Return whether a request error is retryable for a method/path."""
-        if not cls._is_retryable_method(method, path):
+        if not cls._is_retryable_method(method, path, headers):
             return False
         return not isinstance(error, httpx.TimeoutException)
 
@@ -152,12 +192,13 @@ class ApiClient:
         *,
         status_code: int | None = None,
         request_error: httpx.RequestError | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> bool:
         """Return whether an HTTP failure is retryable for a request method/path."""
         if status_code is not None:
-            return cls._should_retry_http_status(method, path, status_code)
+            return cls._should_retry_http_status(method, path, status_code, headers)
         if request_error is not None:
-            return cls._should_retry_request_error(method, path, request_error)
+            return cls._should_retry_request_error(method, path, request_error, headers)
         return False
 
     @classmethod
@@ -202,22 +243,11 @@ class ApiClient:
         cls,
         failure: httpx.HTTPStatusError | httpx.RequestError,
         *,
-        method: str,
-        path: str,
+        should_retry: bool,
         attempt: int,
         max_retries: int,
     ) -> bool:
         """Return True to retry; otherwise raise a normalized ApiClientError."""
-        status_code = failure.response.status_code if isinstance(failure, httpx.HTTPStatusError) else None
-        request_error = failure if isinstance(failure, httpx.RequestError) else None
-
-        should_retry = cls._should_retry_failure(
-            method,
-            path,
-            status_code=status_code,
-            request_error=request_error,
-        )
-
         if should_retry and attempt < max_retries:
             if isinstance(failure, httpx.HTTPStatusError):
                 logger.warning("Transient HTTP error %d from server, will retry", failure.response.status_code)
@@ -474,6 +504,8 @@ class ApiClient:
         client = self._get_client()
         path = path.lstrip("/")
         method = method.upper()
+        raw_headers = kwargs.get("headers")
+        headers = cast(Mapping[str, str], raw_headers) if isinstance(raw_headers, Mapping) else None
 
         for attempt in range(self._config.max_retries + 1):
             if attempt > 0:
@@ -489,7 +521,7 @@ class ApiClient:
                     resp = await client.request(method, path, **kwargs)
 
                 # Retry on transient server-side errors before raising
-                should_retry = self._should_retry_failure(method, path, status_code=resp.status_code)
+                should_retry = self._should_retry_failure(method, path, status_code=resp.status_code, headers=headers)
                 if should_retry and attempt < self._config.max_retries:
                     logger.warning("Transient HTTP error %d from server, will retry", resp.status_code)
                     continue
@@ -500,10 +532,18 @@ class ApiClient:
                 return self._parse_json_response(resp, method, path)
 
             except (httpx.HTTPStatusError, httpx.RequestError) as e:
+                status_code = e.response.status_code if isinstance(e, httpx.HTTPStatusError) else None
+                request_error = e if isinstance(e, httpx.RequestError) else None
+                should_retry = self._should_retry_failure(
+                    method,
+                    path,
+                    status_code=status_code,
+                    request_error=request_error,
+                    headers=headers,
+                )
                 if self._should_retry_or_raise_failure(
                     e,
-                    method=method,
-                    path=path,
+                    should_retry=should_retry,
                     attempt=attempt,
                     max_retries=self._config.max_retries,
                 ):
@@ -633,7 +673,8 @@ class ApiClient:
     ) -> HarvestResult:
         """Start a new harvest run.
 
-        Uses ``POST /v3/harvests``.
+        Uses ``POST /v3/harvests`` with a generated ``Idempotency-Key`` so the
+        request is safe to retry after transport failures.
 
         Args:
             rdi: RDI identifier.
@@ -643,7 +684,16 @@ class ApiClient:
             :class:`HarvestResult` with the newly created harvest.
         """
         request = CreateHarvestRequest(rdi=rdi, expected_datasets=expected_datasets)
-        data = await self._post("v3/harvests", request)
+        idempotency_key = str(uuid.uuid4())
+        data = await self._request_with_retries(
+            "POST",
+            "v3/harvests",
+            content=request.model_dump_json(by_alias=True),
+            headers={
+                "content-type": "application/json",
+                "Idempotency-Key": idempotency_key,
+            },
+        )
         return self._parse_harvest_response(data)
 
     async def list_harvests(

{fairagro_middleware_api_client-11.1.1.dev34 → fairagro_middleware_api_client-12.0.1.dev35}/tests/unit/test_client.py

@@ -252,16 +252,72 @@ async def test_create_or_update_arc_retries_on_connect_error(client_config: Conf
 
 @pytest.mark.asyncio
 @respx.mock
-async def test_create_harvest_network_error_not_retried(client_config: Config) -> None:
-    """Non-ARC POSTs (create harvest) must not retry ConnectError."""
+async def test_create_harvest_sends_idempotency_key(client_config: Config) -> None:
+    """create_harvest always sends a non-empty Idempotency-Key header."""
+    route = respx.post(f"{client_config.api_url}v3/harvests").mock(
+        return_value=httpx.Response(http.HTTPStatus.OK, json=HARVEST_RESPONSE)
+    )
+    async with ApiClient(client_config) as client:
+        await client.create_harvest(rdi="test-rdi")
+
+    assert route.called
+    key = route.calls.last.request.headers.get("idempotency-key")
+    assert key
+    assert len(key) > 0
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_create_harvest_retries_on_connect_error(client_config: Config) -> None:
+    """Keyed harvest create retries ConnectError then succeeds."""
     client_config.retry_backoff_factor = 0.01
+    client_config.max_retries = 2
+    seen_keys: list[str] = []
+
+    def _handler(request: httpx.Request) -> httpx.Response:
+        seen_keys.append(request.headers["idempotency-key"])
+        if len(seen_keys) == 1:
+            raise httpx.ConnectError("Connection refused")
+        return httpx.Response(http.HTTPStatus.OK, json=HARVEST_RESPONSE)
+
+    route = respx.post(f"{client_config.api_url}v3/harvests").mock(side_effect=_handler)
+    async with ApiClient(client_config) as client:
+        result = await client.create_harvest(rdi="test-rdi")
+
+    assert result.harvest_id == HARVEST_RESPONSE["harvest_id"]
+    assert route.call_count == 2  # noqa: PLR2004
+    assert len(seen_keys) == 2  # noqa: PLR2004
+    assert seen_keys[0] == seen_keys[1]
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_unkeyed_harvest_create_post_not_retried(client_config: Config) -> None:
+    """POST /v3/harvests without Idempotency-Key must not be retried."""
+    from middleware.shared.api_models.v3.models import CreateHarvestRequest
+
+    client_config.retry_backoff_factor = 0.01
+    client_config.max_retries = 2
     route = respx.post(f"{client_config.api_url}v3/harvests").mock(side_effect=httpx.ConnectError("Connection refused"))
     async with ApiClient(client_config) as client:
         with pytest.raises(ApiClientError, match="Request failed: Connection refused"):
-            await client.create_harvest(rdi="test-rdi")
+            await client._post("v3/harvests", CreateHarvestRequest(rdi="test-rdi"))  # noqa: SLF001
     assert route.call_count == 1
 
 
+@pytest.mark.asyncio
+@respx.mock
+async def test_create_harvest_exhausted_retries(client_config: Config) -> None:
+    """Keyed harvest create raises after retries are exhausted."""
+    client_config.retry_backoff_factor = 0.01
+    client_config.max_retries = 1
+    route = respx.post(f"{client_config.api_url}v3/harvests").mock(side_effect=httpx.ConnectError("Connection refused"))
+    async with ApiClient(client_config) as client:
+        with pytest.raises(ApiClientError, match="Request failed after 1 retries"):
+            await client.create_harvest(rdi="test-rdi")
+    assert route.call_count == 2  # noqa: PLR2004
+
+
 @pytest.mark.asyncio
 @respx.mock
 async def test_create_or_update_arc_invalid_response(client_config: Config) -> None:
@@ -384,9 +440,10 @@ def test_format_request_error_falls_back_when_message_empty() -> None:
 @respx.mock
 async def test_empty_connect_error_message_is_not_blank(client_config: Config) -> None:
     """ApiClientError for empty ConnectError still carries a useful message."""
+    client_config.max_retries = 0
     respx.post(f"{client_config.api_url}v3/harvests").mock(side_effect=httpx.ConnectError(""))
     async with ApiClient(client_config) as client:
-        with pytest.raises(ApiClientError, match="Request failed: ConnectError") as exc_info:
+        with pytest.raises(ApiClientError, match="ConnectError") as exc_info:
             await client.create_harvest(rdi="test-rdi")
     assert str(exc_info.value).strip() != "Request failed:"
 
@@ -465,15 +522,20 @@ async def test_create_harvest_without_expected_datasets(client_config: Config) -
 
 @pytest.mark.asyncio
 @respx.mock
-async def test_create_harvest_503_not_retried(client_config: Config) -> None:
-    """POST create_harvest is not retried on transient server errors."""
+async def test_create_harvest_retries_on_503(client_config: Config) -> None:
+    """Keyed harvest create retries transient 503 responses."""
+    client_config.retry_backoff_factor = 0.01
+    client_config.max_retries = 2
     route = respx.post(f"{client_config.api_url}v3/harvests").mock(
-        return_value=httpx.Response(http.HTTPStatus.SERVICE_UNAVAILABLE, text="Busy")
+        side_effect=[
+            httpx.Response(http.HTTPStatus.SERVICE_UNAVAILABLE, text="Busy"),
+            httpx.Response(http.HTTPStatus.OK, json=HARVEST_RESPONSE),
+        ]
     )
     async with ApiClient(client_config) as client:
-        with pytest.raises(ApiClientError, match="HTTP error 503"):
-            await client.create_harvest(rdi="test-rdi")
-    assert route.call_count == 1
+        result = await client.create_harvest(rdi="test-rdi")
+    assert result.harvest_id == HARVEST_RESPONSE["harvest_id"]
+    assert route.call_count == 2  # noqa: PLR2004
 
 
 @pytest.mark.asyncio