[GPCAPIM-255] Controller module

gateway-api/pyproject.toml

@@ -12,6 +12,7 @@ requires-python = ">3.13,<4.0.0"
 clinical-data-common = { git = "https://github.com/NHSDigital/clinical-data-common.git", tag = "v0.1.0" }
 flask = "^3.1.2"
 types-flask = "^1.1.6"
+requests = "^2.32.5"
 
 [tool.poetry]
 packages = [{include = "gateway_api", from = "src"},
@@ -51,7 +52,6 @@ dev = [
     "pytest-html (>=4.1.1,<5.0.0)",
     "pact-python>=2.0.0",
     "python-dotenv>=1.0.0",
-    "requests>=2.31.0",
     "schemathesis>=4.4.1",
     "types-requests (>=2.32.4.20250913,<3.0.0.0)",
     "types-pyyaml (>=6.0.12.20250915,<7.0.0.0)",

gateway-api/src/gateway_api/app.py

@@ -4,9 +4,10 @@
 from flask import Flask, request
 from flask.wrappers import Response
 
+from gateway_api.controller import Controller
 from gateway_api.get_structured_record import (
-    GetStructuredRecordHandler,
     GetStructuredRecordRequest,
+    RequestValidationError,
 )
 
 app = Flask(__name__)
@@ -37,9 +38,28 @@ def get_app_port() -> int:
 def get_structured_record() -> Response:
     try:
         get_structured_record_request = GetStructuredRecordRequest(request)
-        GetStructuredRecordHandler.handle(get_structured_record_request)
+    except RequestValidationError as e:
+        response = Response(
+            response=str(e),
+            status=400,
+            content_type="text/plain",
+        )
+        return response
+    except Exception:
+        response = Response(
+            response="Internal Server Error",
+            status=500,
+            content_type="text/plain",
+        )
+        return response
+
+    try:
+        controller = Controller()
+        flask_response = controller.run(request=get_structured_record_request)
+        get_structured_record_request.set_response_from_flaskresponse(flask_response)
     except Exception as e:
         get_structured_record_request.set_negative_response(str(e))
+
     return get_structured_record_request.build_response()
 
 

gateway-api/src/gateway_api/common/common.py

@@ -0,0 +1,63 @@
+"""
+Shared lightweight types and helpers used across the gateway API.
+"""
+
+import re
+from dataclasses import dataclass
+
+# This project uses JSON request/response bodies as strings in the controller layer.
+# The alias is used to make intent clearer in function signatures.
+type json_str = str
+
+
+@dataclass
+class FlaskResponse:
+    """
+    Lightweight response container returned by controller entry points.
+
+    This mirrors the minimal set of fields used by the surrounding web framework.
+
+    :param status_code: HTTP status code for the response (e.g., 200, 400, 404).
+    :param data: Response body as text, if any.
+    :param headers: Response headers, if any.
+    """
+
+    status_code: int
+    data: str | None = None
+    headers: dict[str, str] | None = None
+
+
+def validate_nhs_number(value: str | int) -> bool:
+    """
+    Validate an NHS number using the NHS modulus-11 check digit algorithm.
+
+    The input may be a string or integer. Any non-digit separators in string
+    inputs (spaces, hyphens, etc.) are ignored.
+
+    :param value: NHS number as a string or integer. Non-digit characters
+        are ignored when a string is provided.
+    :returns: ``True`` if the number is a valid NHS number, otherwise ``False``.
+    """
+    str_value = str(value)  # Just in case they passed an integer
+    digits = re.sub(r"[\s-]", "", str_value or "")
+
+    if len(digits) != 10:
+        return False
+    if not digits.isdigit():
+        return False
+
+    first_nine = [int(ch) for ch in digits[:9]]
+    provided_check_digit = int(digits[9])
+
+    weights = list(range(10, 1, -1))
+    total = sum(d * w for d, w in zip(first_nine, weights, strict=True))
+
+    remainder = total % 11
+    check = 11 - remainder
+
+    if check == 11:
+        check = 0
+    if check == 10:
+        return False  # invalid NHS number
+
+    return check == provided_check_digit

gateway-api/src/gateway_api/common/test_common.py

@@ -0,0 +1,55 @@
+"""
+Unit tests for :mod:`gateway_api.common.common`.
+"""
+
+import pytest
+
+from gateway_api.common import common
+
+
+@pytest.mark.parametrize(
+    ("nhs_number", "expected"),
+    [
+        ("9434765919", True),  # Just a number
+        ("943 476 5919", True),  # Spaces are permitted
+        ("987-654-3210", True),  # Hyphens are permitted
+        (9434765919, True),  # Integer input is permitted
+        ("", False),  # Empty string is invalid
+        ("943476591", False),  # 9 digits
+        ("94347659190", False),  # 11 digits
+        ("9434765918", False),  # wrong check digit
+        ("NOT_A_NUMBER", False),  # non-numeric
+        ("943SOME_LETTERS4765919", False),  # non-numeric in a valid NHS number
+    ],
+)
+def test_validate_nhs_number(nhs_number: str | int, expected: bool) -> None:
+    """
+    Validate that separators (spaces, hyphens) are ignored and valid numbers pass.
+    """
+    assert common.validate_nhs_number(nhs_number) is expected
+
+
+@pytest.mark.parametrize(
+    ("nhs_number", "expected"),
+    [
+        # All zeros => weighted sum 0 => remainder 0 => check 11 => mapped to 0 => valid
+        ("0000000000", True),
+        # First 9 digits produce remainder 1 => check 10 => invalid
+        ("0000000060", False),
+    ],
+)
+def test_validate_nhs_number_check_edge_cases_10_and_11(
+    nhs_number: str | int, expected: bool
+) -> None:
+    """
+    validate_nhs_number should behave correctly when the computed ``check`` value
+    is 10 or 11.
+
+    - If ``check`` computes to 11, it should be treated as 0, so a number with check
+        digit 0 should validate successfully.
+    - If ``check`` computes to 10, the number is invalid and validation should return
+        False.
+    """
+    # All zeros => weighted sum 0 => remainder 0 => check 11 => mapped to 0 => valid
+    # with check digit 0
+    assert common.validate_nhs_number(nhs_number) is expected