helix.fhir.client.sdk 4.1.67__py3-none-any.whl → 4.2.18__py3-none-any.whl

helix_fhir_client_sdk/utilities/cache/request_cache.py

@@ -1,4 +1,3 @@
-import asyncio
 from collections.abc import AsyncGenerator
 from datetime import datetime
 from types import TracebackType
@@ -11,7 +10,7 @@ from helix_fhir_client_sdk.utilities.cache.request_cache_entry import RequestCac
 
 class RequestCache:
     """
-    This is a class that caches requests to the FHIR server using a weak value dictionary.
+    This is a class that caches requests to the FHIR server.
     It is used to avoid multiple requests to the FHIR server when doing a large number
     of requests for the same resource.
     """
@@ -20,7 +19,6 @@ class RequestCache:
         "cache_hits",
         "cache_misses",
         "_cache",
-        "_lock",
         "_clear_cache_at_the_end",
     ]
 
@@ -33,7 +31,6 @@ class RequestCache:
         self.cache_hits: int = 0
         self.cache_misses: int = 0
         self._cache: dict[str, RequestCacheEntry] = initial_dict or {}
-        self._lock: asyncio.Lock = asyncio.Lock()
         self._clear_cache_at_the_end: bool | None = clear_cache_at_the_end
 
     async def __aenter__(self) -> "RequestCache":
@@ -42,8 +39,7 @@ class RequestCache:
         It returns the RequestCache instance.
         """
         if self._clear_cache_at_the_end:
-            async with self._lock:
-                self._cache.clear()
+            self._cache.clear()
         return self
 
     async def __aexit__(
@@ -57,8 +53,7 @@ class RequestCache:
         It clears the cache.
         """
         if self._clear_cache_at_the_end:
-            async with self._lock:
-                self._cache.clear()
+            self._cache.clear()
 
         if exc_value is not None:
             raise exc_value.with_traceback(traceback)
@@ -75,15 +70,14 @@ class RequestCache:
         """
         key: str = f"{resource_type}/{resource_id}"
 
-        async with self._lock:
-            cached_entry = self._cache.get(key)
+        cached_entry = self._cache.get(key)
 
-            if cached_entry is not None:
-                self.cache_hits += 1
-                return cached_entry
+        if cached_entry is not None:
+            self.cache_hits += 1
+            return cached_entry
 
-            self.cache_misses += 1
-            return None
+        self.cache_misses += 1
+        return None
 
     async def add_async(
         self,
@@ -111,43 +105,40 @@ class RequestCache:
         """
         key: str = f"{resource_type}/{resource_id}"
 
-        async with self._lock:
-            # Create the cache entry
-            cache_entry = RequestCacheEntry(
-                id_=resource_id,
-                resource_type=resource_type,
-                status=status,
-                bundle_entry=bundle_entry,
-                last_modified=last_modified,
-                etag=etag,
-                from_input_cache=from_input_cache,
-                raw_hash=raw_hash,
-            )
-
-            # Add to the weak value dictionary
-            self._cache[key] = cache_entry
+        # Create the cache entry
+        cache_entry = RequestCacheEntry(
+            id_=resource_id,
+            resource_type=resource_type,
+            status=status,
+            bundle_entry=bundle_entry,
+            last_modified=last_modified,
+            etag=etag,
+            from_input_cache=from_input_cache,
+            raw_hash=raw_hash,
+        )
+
+        # Add to the dictionary
+        self._cache[key] = cache_entry
 
-            return True
+        return True
 
     async def remove_async(self, *, resource_key: str) -> bool:
         """
         This method remove the given data from the cache.
         :param resource_key: resource key contains both resourceType and resourceId. Eg: Patient/123
         """
-        async with self._lock:
-            if resource_key not in self._cache:
-                return False
+        if resource_key not in self._cache:
+            return False
 
-            del self._cache[resource_key]
+        del self._cache[resource_key]
 
-            return True
+        return True
 
     async def clear_async(self) -> None:
         """
         This method clears the cache.
         """
-        async with self._lock:
-            self._cache.clear()
+        self._cache.clear()
 
     async def get_entries_async(self) -> AsyncGenerator[RequestCacheEntry, None]:
         """
@@ -155,9 +146,8 @@ class RequestCache:
 
         :return: The keys in the cache.
         """
-        async with self._lock:
-            for entry in self._cache.values():
-                yield entry
+        for entry in self._cache.values():
+            yield entry
 
     async def get_keys_async(self) -> list[str]:
         """
@@ -165,8 +155,7 @@ class RequestCache:
 
         :return: The entries in the cache.
         """
-        async with self._lock:
-            return list(self._cache.keys())
+        return list(self._cache.keys())
 
     def __len__(self) -> int:
         """

helix_fhir_client_sdk/utilities/retryable_aiohttp_client.py

@@ -7,12 +7,15 @@ from typing import Any, cast
 import async_timeout
 from aiohttp import ClientError, ClientResponse, ClientResponseError, ClientSession
 from multidict import MultiMapping
+from opentelemetry import trace
 
 from helix_fhir_client_sdk.function_types import (
     RefreshTokenFunction,
     RefreshTokenResult,
     TraceRequestFunction,
 )
+from helix_fhir_client_sdk.open_telemetry.attribute_names import FhirClientSdkOpenTelemetryAttributeNames
+from helix_fhir_client_sdk.open_telemetry.span_names import FhirClientSdkOpenTelemetrySpanNames
 from helix_fhir_client_sdk.utilities.retryable_aiohttp_response import (
     RetryableAioHttpResponse,
 )
@@ -20,6 +23,8 @@ from helix_fhir_client_sdk.utilities.retryable_aiohttp_url_result import (
     RetryableAioHttpUrlResult,
 )
 
+TRACER = trace.get_tracer(__name__)
+
 
 class RetryableAioHttpClient:
     def __init__(
@@ -32,6 +37,7 @@ class RetryableAioHttpClient:
         refresh_token_func: RefreshTokenFunction | None,
         tracer_request_func: TraceRequestFunction | None,
         fn_get_session: Callable[[], ClientSession] | None = None,
+        caller_managed_session: bool = False,
         exclude_status_codes_from_retry: list[int] | None = None,
         use_data_streaming: bool | None,
         compress: bool | None = False,
@@ -42,8 +48,32 @@ class RetryableAioHttpClient:
         access_token_expiry_date: datetime | None,
     ) -> None:
         """
-        RetryableClient provides a way to make HTTP calls with automatic retry and automatic refreshing of access tokens
+        RetryableClient provides a way to make HTTP calls with automatic retry and automatic refreshing of access tokens.
+
+        Session Lifecycle Management:
+        - If caller_managed_session is False (default): The SDK manages the session lifecycle.
+          The session will be automatically closed when exiting the context manager.
+        - If caller_managed_session is True: The caller is responsible for managing the session lifecycle.
+          The SDK will NOT close the session - the caller must close it themselves.
 
+        :param retries: Number of retry attempts for failed requests
+        :param timeout_in_seconds: Timeout for HTTP requests
+        :param backoff_factor: Factor for exponential backoff between retries
+        :param retry_status_codes: HTTP status codes that trigger a retry
+        :param refresh_token_func: Function to refresh authentication tokens
+        :param tracer_request_func: Function to trace/log requests
+        :param fn_get_session: Optional callable that returns a ClientSession. If None, a basic
+                               ClientSession will be created internally.
+        :param caller_managed_session: If True, the caller is responsible for closing the session.
+                                       If False (default), the SDK will close the session on exit.
+        :param exclude_status_codes_from_retry: Status codes to exclude from retry logic
+        :param use_data_streaming: Whether to stream response data
+        :param compress: Whether to compress request data
+        :param send_data_as_chunked: Whether to use chunked transfer encoding
+        :param throw_exception_on_error: Whether to raise exceptions on HTTP errors
+        :param log_all_url_results: Whether to log all URL results
+        :param access_token: Access token for authentication
+        :param access_token_expiry_date: Expiry date of the access token
         """
         self.retries: int = retries
         self.timeout_in_seconds: float | None = timeout_in_seconds
@@ -53,6 +83,8 @@ class RetryableAioHttpClient:
         )
         self.refresh_token_func_async: RefreshTokenFunction | None = refresh_token_func
         self.trace_function_async: TraceRequestFunction | None = tracer_request_func
+        self._caller_managed_session: bool = caller_managed_session
+        # If no session factory provided, use a default one that creates a basic ClientSession
         self.fn_get_session: Callable[[], ClientSession] = (
             fn_get_session if fn_get_session is not None else lambda: ClientSession()
         )
@@ -76,7 +108,9 @@ class RetryableAioHttpClient:
         exc_val: BaseException | None,
         exc_tb: type[BaseException] | None | None,
     ) -> None:
-        if self.session is not None:
+        # Only close the session if SDK created it (fn_get_session was not provided)
+        # If the caller provided fn_get_session, they are responsible for closing the session
+        if not self._caller_managed_session and self.session is not None:
             await self.session.close()
 
     @staticmethod
@@ -110,7 +144,7 @@ class RetryableAioHttpClient:
             try:
                 if headers:
                     kwargs["headers"] = headers
-                # if there is no data then remove from kwargs so as not to confuse aiohttp
+                # if there is no data, then remove from kwargs so as not to confuse aiohttp
                 if "data" in kwargs and kwargs["data"] is None:
                     del kwargs["data"]
                 # compression and chunked can only be enabled if there is content sent
@@ -120,164 +154,101 @@ class RetryableAioHttpClient:
                     if self.compress:
                         kwargs["compress"] = self.compress
                 assert self.session is not None
-                async with async_timeout.timeout(self.timeout_in_seconds):
-                    start_time: float = time.time()
-                    response: ClientResponse = await self.session.request(
-                        method,
+                with TRACER.start_as_current_span(FhirClientSdkOpenTelemetrySpanNames.HTTP_GET) as span:
+                    span.set_attribute(
+                        FhirClientSdkOpenTelemetryAttributeNames.URL,
                         url,
-                        **kwargs,
                     )
-                    # Append the result to the list of results
-                    if self.log_all_url_results:
-                        results_by_url.append(
-                            RetryableAioHttpUrlResult(
+                    async with async_timeout.timeout(self.timeout_in_seconds):
+                        start_time: float = time.time()
+                        response: ClientResponse = await self.session.request(
+                            method,
+                            url,
+                            **kwargs,
+                        )
+                        # Append the result to the list of results
+                        if self.log_all_url_results:
+                            results_by_url.append(
+                                RetryableAioHttpUrlResult(
+                                    ok=response.ok,
+                                    url=url,
+                                    status_code=response.status,
+                                    retry_count=retry_attempts,
+                                    start_time=start_time,
+                                    end_time=time.time(),
+                                )
+                            )
+                        response_headers: dict[str, str] = {
+                            k: ",".join(response.headers.getall(k)) for k in response.headers.keys()
+                        }
+                        response_headers_multi_mapping: MultiMapping[str] = cast(MultiMapping[str], response.headers)
+
+                        if self.trace_function_async:
+                            request_headers: dict[str, str] = {
+                                k: ",".join(response.request_info.headers.getall(k))
+                                for k in response.request_info.headers.keys()
+                            }
+                            await self.trace_function_async(
                                 ok=response.ok,
                                 url=url,
                                 status_code=response.status,
+                                access_token=access_token,
+                                expiry_date=expiry_date,
                                 retry_count=retry_attempts,
                                 start_time=start_time,
                                 end_time=time.time(),
+                                request_headers=request_headers,
+                                response_headers=response_headers,
                             )
-                        )
-                    response_headers: dict[str, str] = {
-                        k: ",".join(response.headers.getall(k)) for k in response.headers.keys()
-                    }
-                    response_headers_multi_mapping: MultiMapping[str] = cast(MultiMapping[str], response.headers)
-
-                    if self.trace_function_async:
-                        request_headers: dict[str, str] = {
-                            k: ",".join(response.request_info.headers.getall(k))
-                            for k in response.request_info.headers.keys()
-                        }
-                        await self.trace_function_async(
-                            ok=response.ok,
-                            url=url,
-                            status_code=response.status,
-                            access_token=access_token,
-                            expiry_date=expiry_date,
-                            retry_count=retry_attempts,
-                            start_time=start_time,
-                            end_time=time.time(),
-                            request_headers=request_headers,
-                            response_headers=response_headers,
-                        )
 
-                    if response.ok:
-                        # If the response is successful, return the response
-                        return RetryableAioHttpResponse(
-                            ok=response.ok,
-                            status=response.status,
-                            response_headers=response_headers,
-                            response_text=(
-                                await self.get_safe_response_text_async(response=response)
-                                if not self.use_data_streaming
-                                else ""
-                            ),
-                            content=response.content,
-                            use_data_streaming=self.use_data_streaming,
-                            results_by_url=results_by_url,
-                            access_token=access_token,
-                            access_token_expiry_date=expiry_date,
-                            retry_count=retry_attempts,
-                        )
-                    elif (
-                        self.exclude_status_codes_from_retry and response.status in self.exclude_status_codes_from_retry
-                    ):
-                        return RetryableAioHttpResponse(
-                            ok=response.ok,
-                            status=response.status,
-                            response_headers=response_headers,
-                            response_text=await self.get_safe_response_text_async(response=response),
-                            content=response.content,
-                            use_data_streaming=self.use_data_streaming,
-                            results_by_url=results_by_url,
-                            access_token=access_token,
-                            access_token_expiry_date=expiry_date,
-                            retry_count=retry_attempts,
-                        )
-                    elif response.status == 400:
-                        return RetryableAioHttpResponse(
-                            ok=response.ok,
-                            status=response.status,
-                            response_headers=response_headers,
-                            response_text=await self.get_safe_response_text_async(response=response),
-                            content=response.content,
-                            use_data_streaming=self.use_data_streaming,
-                            results_by_url=results_by_url,
-                            access_token=access_token,
-                            access_token_expiry_date=expiry_date,
-                            retry_count=retry_attempts,
-                        )
-                    elif response.status in [403, 404]:
-                        return RetryableAioHttpResponse(
-                            ok=response.ok,
-                            status=response.status,
-                            response_headers=response_headers,
-                            response_text=await self.get_safe_response_text_async(response=response),
-                            content=response.content,
-                            use_data_streaming=self.use_data_streaming,
-                            results_by_url=results_by_url,
-                            access_token=access_token,
-                            access_token_expiry_date=expiry_date,
-                            retry_count=retry_attempts,
-                        )
-                    elif response.status == 429:
-                        await self._handle_429(response=response, full_url=url)
-                    elif self.retry_status_codes and response.status in self.retry_status_codes:
-                        raise ClientResponseError(
-                            status=response.status,
-                            message="Retryable status code received",
-                            headers=response_headers_multi_mapping,
-                            history=response.history,
-                            request_info=response.request_info,
-                        )
-                    elif response.status == 401 and self.refresh_token_func_async:
-                        # Call the token refresh function if status code is 401
-                        refresh_token_result: RefreshTokenResult = await self.refresh_token_func_async(
-                            current_token=access_token,
-                            expiry_date=expiry_date,
-                            url=url,
-                            status_code=response.status,
-                            retry_count=retry_attempts,
-                        )
-                        if refresh_token_result.abort_request or refresh_token_result.access_token is None:
+                        if response.ok:
+                            # If the response is successful, return the response
                             return RetryableAioHttpResponse(
-                                ok=False,
-                                status=401,
-                                response_headers={},
-                                response_text="Unauthorized",
-                                content=None,
+                                ok=response.ok,
+                                status=response.status,
+                                response_headers=response_headers,
+                                response_text=(
+                                    await self.get_safe_response_text_async(response=response)
+                                    if not self.use_data_streaming
+                                    else ""
+                                ),
+                                content=response.content,
                                 use_data_streaming=self.use_data_streaming,
                                 results_by_url=results_by_url,
                                 access_token=access_token,
                                 access_token_expiry_date=expiry_date,
                                 retry_count=retry_attempts,
                             )
-                        else:  # we got a valid token
-                            access_token = refresh_token_result.access_token
-                            expiry_date = refresh_token_result.expiry_date
-                            if not headers:
-                                headers = {}
-                            headers["Authorization"] = f"Bearer {access_token}"
-                            if retry_attempts >= self.retries:
-                                raise ClientResponseError(
-                                    status=response.status,
-                                    message="Unauthorized",
-                                    headers=response_headers_multi_mapping,
-                                    history=response.history,
-                                    request_info=response.request_info,
-                                )
-                            await asyncio.sleep(self.backoff_factor * (2 ** (retry_attempts - 1)))
-                    else:
-                        if self._throw_exception_on_error:
-                            raise ClientResponseError(
+                        elif (
+                            self.exclude_status_codes_from_retry
+                            and response.status in self.exclude_status_codes_from_retry
+                        ):
+                            return RetryableAioHttpResponse(
+                                ok=response.ok,
                                 status=response.status,
-                                message="Non-retryable status code received",
-                                headers=response_headers_multi_mapping,
-                                history=response.history,
-                                request_info=response.request_info,
+                                response_headers=response_headers,
+                                response_text=await self.get_safe_response_text_async(response=response),
+                                content=response.content,
+                                use_data_streaming=self.use_data_streaming,
+                                results_by_url=results_by_url,
+                                access_token=access_token,
+                                access_token_expiry_date=expiry_date,
+                                retry_count=retry_attempts,
                             )
-                        else:
+                        elif response.status == 400:
+                            return RetryableAioHttpResponse(
+                                ok=response.ok,
+                                status=response.status,
+                                response_headers=response_headers,
+                                response_text=await self.get_safe_response_text_async(response=response),
+                                content=response.content,
+                                use_data_streaming=self.use_data_streaming,
+                                results_by_url=results_by_url,
+                                access_token=access_token,
+                                access_token_expiry_date=expiry_date,
+                                retry_count=retry_attempts,
+                            )
+                        elif response.status in [403, 404]:
                             return RetryableAioHttpResponse(
                                 ok=response.ok,
                                 status=response.status,
@@ -290,6 +261,75 @@ class RetryableAioHttpClient:
                                 access_token_expiry_date=expiry_date,
                                 retry_count=retry_attempts,
                             )
+                        elif response.status == 429:
+                            await self._handle_429(response=response, full_url=url)
+                        elif response.status == 401 and self.refresh_token_func_async:
+                            # Call the token refresh function if status code is 401
+                            refresh_token_result: RefreshTokenResult = await self.refresh_token_func_async(
+                                current_token=access_token,
+                                expiry_date=expiry_date,
+                                url=url,
+                                status_code=response.status,
+                                retry_count=retry_attempts,
+                            )
+                            if refresh_token_result.abort_request or refresh_token_result.access_token is None:
+                                return RetryableAioHttpResponse(
+                                    ok=False,
+                                    status=401,
+                                    response_headers={},
+                                    response_text="Unauthorized",
+                                    content=None,
+                                    use_data_streaming=self.use_data_streaming,
+                                    results_by_url=results_by_url,
+                                    access_token=access_token,
+                                    access_token_expiry_date=expiry_date,
+                                    retry_count=retry_attempts,
+                                )
+                            else:  # we got a valid token
+                                access_token = refresh_token_result.access_token
+                                expiry_date = refresh_token_result.expiry_date
+                                if not headers:
+                                    headers = {}
+                                headers["Authorization"] = f"Bearer {access_token}"
+                                if retry_attempts >= self.retries:
+                                    raise ClientResponseError(
+                                        status=response.status,
+                                        message="Unauthorized",
+                                        headers=response_headers_multi_mapping,
+                                        history=response.history,
+                                        request_info=response.request_info,
+                                    )
+                                await asyncio.sleep(self.backoff_factor * (2 ** (retry_attempts - 1)))
+                        elif self.retry_status_codes and response.status in self.retry_status_codes:
+                            raise ClientResponseError(
+                                status=response.status,
+                                message="Retryable status code received",
+                                headers=response_headers_multi_mapping,
+                                history=response.history,
+                                request_info=response.request_info,
+                            )
+                        else:
+                            if self._throw_exception_on_error:
+                                raise ClientResponseError(
+                                    status=response.status,
+                                    message="Non-retryable status code received",
+                                    headers=response_headers_multi_mapping,
+                                    history=response.history,
+                                    request_info=response.request_info,
+                                )
+                            else:
+                                return RetryableAioHttpResponse(
+                                    ok=response.ok,
+                                    status=response.status,
+                                    response_headers=response_headers,
+                                    response_text=await self.get_safe_response_text_async(response=response),
+                                    content=response.content,
+                                    use_data_streaming=self.use_data_streaming,
+                                    results_by_url=results_by_url,
+                                    access_token=access_token,
+                                    access_token_expiry_date=expiry_date,
+                                    retry_count=retry_attempts,
+                                )
             except (TimeoutError, ClientError, ClientResponseError) as e:
                 if retry_attempts >= self.retries:
                     if self._throw_exception_on_error:
@@ -388,7 +428,7 @@ class RetryableAioHttpClient:
         if retry_after_text:
             # noinspection PyBroadException
             try:
-                if retry_after_text.isnumeric():  # it is number of seconds
+                if retry_after_text.isnumeric():  # it is a number of seconds
                     await asyncio.sleep(int(retry_after_text))
                 else:
                     wait_till: datetime = datetime.strptime(retry_after_text, "%a, %d %b %Y %H:%M:%S GMT")
@@ -402,7 +442,7 @@ class RetryableAioHttpClient:
                     if time_diff > 0:
                         await asyncio.sleep(time_diff)
             except Exception:
-                # if there was some exception parsing the Retry-After header, sleep for 60 seconds
+                # if there was some exception, parsing the Retry-After header, sleep for 60 seconds
                 await asyncio.sleep(60)
         else:
             await asyncio.sleep(60)

helix_fhir_client_sdk/utilities/retryable_aiohttp_response.py

@@ -3,6 +3,7 @@ from datetime import datetime
 from typing import Any, cast
 
 from aiohttp import StreamReader
+from multidict import CIMultiDict
 
 from helix_fhir_client_sdk.utilities.retryable_aiohttp_url_result import (
     RetryableAioHttpUrlResult,
@@ -53,7 +54,7 @@ class RetryableAioHttpResponse:
         self.status: int = status
         """ Status code of the response """
 
-        self.response_headers: dict[str, str] = response_headers
+        self.response_headers: CIMultiDict[str] = CIMultiDict(response_headers)
         """ Headers of the response """
 
         self._response_text: str = response_text

helix_fhir_client_sdk/utilities/url_checker.py

@@ -5,6 +5,52 @@ from furl import furl
 
 
 class UrlChecker:
+    @staticmethod
+    def preserve_port_from_base_url(*, base_url: str, next_url: str) -> str:
+        """
+        INC-285: Preserve the port from the base URL when the next URL has the same host
+        but is missing the port.
+
+        This fixes an issue where FHIR servers generate pagination URLs without the port,
+        causing requests to go to the default port (80 for HTTP, 443 for HTTPS) instead
+        of the correct port.
+
+        Example:
+            base_url: http://fhir-server:3000/4_0_0/Observation
+            next_url: http://fhir-server/4_0_0/Observation?_count=10&_getpagesoffset=10
+            result:   http://fhir-server:3000/4_0_0/Observation?_count=10&_getpagesoffset=10
+
+        Args:
+            base_url (str): The original base URL with the correct port
+            next_url (str): The URL returned by the FHIR server (may be missing port)
+
+        Returns:
+            str: The next URL with the port preserved from the base URL if applicable
+        """
+        base_parsed = urlparse(base_url)
+        next_parsed = urlparse(next_url)
+
+        # Only apply fix if:
+        # 1. Both URLs have the same scheme
+        # 2. Both URLs have the same hostname (ignoring port)
+        # 3. Base URL has an explicit port
+        # 4. The next URL does NOT have an explicit port
+        base_hostname = base_parsed.hostname
+        next_hostname = next_parsed.hostname
+
+        if (
+            base_parsed.scheme == next_parsed.scheme
+            and base_hostname == next_hostname
+            and base_parsed.port is not None
+            and next_parsed.port is None
+        ):
+            # Reconstruct the next URL with the port from base URL
+            next_furl = furl(next_url)
+            next_furl.port = base_parsed.port
+            return str(next_furl)
+
+        return next_url
+
     @staticmethod
     def is_absolute_url(*, url: str | furl) -> bool:
         """
@@ -57,16 +103,4 @@ class UrlChecker:
 
         absolute_url = absolute_url.join(relative)
 
-        # # Update path
-        # if relative.path:
-        #     absolute_url.path.segments += relative.path.segments
-        #
-        # # Update query parameters
-        # if relative.query:
-        #     absolute_url.query.set(relative.query.params)
-        #
-        # # Update fragment if present
-        # if relative.fragment:
-        #     absolute_url.fragment = relative.fragment
-        #
         return cast(str, absolute_url.url)