[GPCAPIM-395]: Refactor PDS client to use session-based GET requests

- Introduced a new session_get_impl function to handle GET requests with session support
- Updated PdsClient to use the new session_get_impl for making requests
- Modified tests to replace calls to the deprecated _make_get_request with _make_session_get_request
- Added SessionGetStub to the PdsFhirApiStub for handling session-based GET requests

Author: DWolfsNHS

gateway-api/src/gateway_api/pds/client.py

@@ -37,13 +37,34 @@
 _pds_url = os.getenv("PDS_URL", "stub")
 STUB_PDS = _pds_url.strip().lower() == "stub"
 
-if not STUB_PDS:
-    from requests import get
-else:
+if STUB_PDS:
     from stubs.pds.stub import PdsFhirApiStub
 
-    pds = PdsFhirApiStub()
-    get = pds.get  # type: ignore
+    pds_stub = PdsFhirApiStub()
+
+
+def session_get_impl(
+    session: requests.Session,
+    url: str,
+    headers: dict[str, str],
+    timeout: int,
+) -> requests.Response:
+    if STUB_PDS:
+        return pds_stub.session_get(
+            session=session,
+            url=url,
+            headers=headers,
+            params={},
+            timeout=timeout,
+        )
+
+    return session.get(
+        url=url,
+        headers=headers,
+        params={},
+        timeout=timeout,
+    )
+
 
 _logger = logging.getLogger(__name__)
 
@@ -131,18 +152,13 @@ def search_patient_by_nhs_number(
         }
         _logger.info(log_details)
 
-        # This normally calls requests.get, but if PDS_URL is set it uses the stub.
-        # response = get(
-        #     url,
-        #     headers=headers,
-        #     params={},
-        #     timeout=timeout or self.timeout,
-        # )
+        # This uses an auth-wrapped session. The underlying GET implementation
+        # is selected at import time based on PDS_URL.
         set_correlation_id(
             full_id=correlation_id or "no-correlation-id",
             short_id=correlation_id or "no-correlation-id",
         )
-        response = _make_get_request(
+        response = _make_session_get_request(
             url,
             headers=headers,
             timeout=timeout or self.timeout,
@@ -171,16 +187,11 @@ def search_patient_by_nhs_number(
 
 # TODO [GPCAPIM-359]: consider moving this to a nested method
 @environment.apim_authenticator().auth
-def _make_get_request(
+def _make_session_get_request(
     session: requests.Session,
     url: str,
     headers: dict[str, str],
     timeout: int,
 ) -> Any:
-    response = session.get(
-        url=url,
-        headers=headers,
-        params={},
-        timeout=timeout,
-    )
+    response = session_get_impl(session, url, headers, timeout)
     return response

gateway-api/src/gateway_api/pds/test_client.py

@@ -22,7 +22,8 @@ def test_search_patient_by_nhs_number_happy_path(
         status_code=200, headers={}, _json=happy_path_pds_response_body
     )
     mocker.patch(
-        "gateway_api.pds.client._make_get_request", return_value=happy_path_response
+        "gateway_api.pds.client._make_session_get_request",
+        return_value=happy_path_response,
     )
 
     client = PdsClient(base_url="https://test.com")
@@ -43,7 +44,8 @@ def test_search_patient_by_nhs_number_has_no_gp_returns_gp_ods_code_none(
         status_code=200, headers={}, _json=gp_less_response_body
     )
     mocker.patch(
-        "gateway_api.pds.client._make_get_request", return_value=gp_less_response
+        "gateway_api.pds.client._make_session_get_request",
+        return_value=gp_less_response,
     )
 
     client = PdsClient(base_url="https://test.com")
@@ -62,7 +64,8 @@ def test_search_patient_by_nhs_number_sends_expected_headers(
         status_code=200, headers={}, _json=happy_path_pds_response_body
     )
     mocked_get = mocker.patch(
-        "gateway_api.pds.client._make_get_request", return_value=happy_path_response
+        "gateway_api.pds.client._make_session_get_request",
+        return_value=happy_path_response,
     )
 
     request_id = str(uuid4())
@@ -93,7 +96,8 @@ def test_search_patient_by_nhs_number_generates_request_id(
         status_code=200, headers={}, _json=happy_path_pds_response_body
     )
     mocked_get = mocker.patch(
-        "gateway_api.pds.client._make_get_request", return_value=happy_path_response
+        "gateway_api.pds.client._make_session_get_request",
+        return_value=happy_path_response,
     )
 
     client = PdsClient(base_url="https://test.com")
@@ -116,7 +120,8 @@ def test_search_patient_by_nhs_number_not_found_raises_error(
         reason="Not Found",
     )
     mocker.patch(
-        "gateway_api.pds.client._make_get_request", return_value=not_found_response
+        "gateway_api.pds.client._make_session_get_request",
+        return_value=not_found_response,
     )
     pds = PdsClient(base_url="https://test.com")
 
@@ -138,7 +143,9 @@ def test_search_patient_by_nhs_number_missing_nhs_number_raises_error(
         headers={},
         _json=response_body_missing_nhs_number,
     )
-    mocker.patch("gateway_api.pds.client._make_get_request", return_value=response)
+    mocker.patch(
+        "gateway_api.pds.client._make_session_get_request", return_value=response
+    )
 
     client = PdsClient(base_url="https://test.com")
 
@@ -157,7 +164,8 @@ def test_search_patient_respects_url(
         status_code=200, headers={}, _json=happy_path_pds_response_body
     )
     mocked_get = mocker.patch(
-        "gateway_api.pds.client._make_get_request", return_value=happy_path_response
+        "gateway_api.pds.client._make_session_get_request",
+        return_value=happy_path_response,
     )
 
     client = PdsClient(base_url="https://a.different.url/base")

gateway-api/src/gateway_api/test_controller.py

@@ -366,7 +366,7 @@ def test_controller_respects_pds_url(
     Test that the controller uses the PDS URL provided in the constructor.
     """
     mocked_get_pds = mocker.patch(
-        "gateway_api.pds.client._make_get_request",
+        "gateway_api.pds.client._make_session_get_request",
         return_value=FakeResponse(
             status_code=200, headers={}, _json=happy_path_pds_response_body
         ),

gateway-api/stubs/stubs/base_stub.py

@@ -145,3 +145,18 @@ def post_session(self) -> Session:
         """
         Last Session stub.session_post was called with. None if not called yet.
         """
+
+
+class SessionGetStub(Protocol):
+    @abstractmethod
+    def session_get(
+        self,
+        session: Session,
+        url: str,
+        headers: dict[str, str],
+        params: dict[str, Any],
+        timeout: int,
+    ) -> Response:
+        """
+        Handle HTTP GET requests for the stub, using a provided Session.
+        """

gateway-api/stubs/stubs/pds/stub.py

@@ -9,13 +9,14 @@
 from datetime import UTC, datetime
 from typing import Any
 
+import requests
 from requests import Response
 
-from stubs.base_stub import StubBase
+from stubs.base_stub import SessionGetStub, StubBase
 from stubs.data.patients import Patients
 
 
-class PdsFhirApiStub(StubBase):
+class PdsFhirApiStub(StubBase, SessionGetStub):
     """
     Minimal in-memory stub for the PDS FHIR API, implementing only ``GET /Patient/{id}``
 
@@ -174,6 +175,7 @@ def get_patient(
             status_code=200, json_data=patient, additional_headers=headers_out
         )
 
+    # TODO [GPCAPIM-395]: remove depricated, and updated tests
     def get(
         self,
         url: str,
@@ -210,6 +212,25 @@ def post(
         """
         raise NotImplementedError("POST requests are not supported by PdsFhirApiStub")
 
+    def session_get(
+        self,
+        session: requests.Session,  # noqa: ARG002 - maintain signature for stub
+        url: str,
+        headers: dict[str, str],
+        params: dict[str, Any],  # noqa: ARG002 - maintain signature for stub
+        timeout: int,  # noqa: ARG002 - maintain signature for stub
+    ) -> Response:
+        nhs_number = url.split("/")[-1]
+
+        request_id = headers.get("X-Request-ID") if headers else None
+        correlation_id = headers.get("X-Correlation-ID") if headers else None
+
+        return self.get_patient(
+            nhs_number=nhs_number,
+            request_id=request_id,
+            correlation_id=correlation_id,
+        )
+
     # ---------------------------
     # Internal helpers
     # ---------------------------