vws-python-mock 2026.8.4__py3-none-any.whl

mock_vws/_services_validators/image_validators.py

@@ -0,0 +1,220 @@
+"""Image validators to use in the mock."""
+
+import binascii
+import io
+import json
+import logging
+from http import HTTPStatus
+
+from beartype import beartype
+from PIL import Image
+
+from mock_vws._base64_decoding import decode_base64
+from mock_vws._services_validators.exceptions import (
+    BadImageError,
+    FailError,
+    ImageTooLargeError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_image_integrity(*, request_body: bytes) -> None:
+    """Validate the integrity of the image given to a VWS endpoint.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        BadImageError: The image is given and is not a valid image file.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    image = json.loads(s=request_text).get("image")
+    if image is None:
+        return
+
+    decoded = decode_base64(encoded_data=image)
+
+    image_file = io.BytesIO(initial_bytes=decoded)
+    with Image.open(fp=image_file) as pil_image:
+        try:
+            pil_image.verify()
+        except SyntaxError as exc:
+            _LOGGER.warning(msg="The image is not a valid image file.")
+            raise BadImageError from exc
+
+
+@beartype
+def validate_image_format(*, request_body: bytes) -> None:
+    """Validate the format of the image given to a VWS endpoint.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        BadImageError:  The image is given and is not either a PNG or a JPEG.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    image = json.loads(s=request_text).get("image")
+
+    if image is None:
+        return
+
+    decoded = decode_base64(encoded_data=image)
+    image_file = io.BytesIO(initial_bytes=decoded)
+    with Image.open(fp=image_file) as pil_image:
+        if pil_image.format in {"PNG", "JPEG"}:
+            return
+
+    _LOGGER.warning(msg="The image is not a PNG or JPEG.")
+    raise BadImageError
+
+
+@beartype
+def validate_image_color_space(*, request_body: bytes) -> None:
+    """Validate the color space of the image given to a VWS endpoint.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        BadImageError: The image is given and is not in either the RGB or
+            greyscale color space.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    image = json.loads(s=request_text).get("image")
+
+    if image is None:
+        return
+
+    decoded = decode_base64(encoded_data=image)
+    image_file = io.BytesIO(initial_bytes=decoded)
+    with Image.open(fp=image_file) as pil_image:
+        if pil_image.mode in {"L", "RGB"}:
+            return
+
+    _LOGGER.warning(
+        msg="The image is not in the RGB or greyscale color space.",
+    )
+    raise BadImageError
+
+
+@beartype
+def validate_image_size(*, request_body: bytes) -> None:
+    """Validate the file size of the image given to a VWS endpoint.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        ImageTooLargeError:  The image is given and is not under a certain file
+            size threshold.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    image = json.loads(s=request_text).get("image")
+
+    if image is None:
+        return
+
+    decoded = decode_base64(encoded_data=image)
+
+    max_allowed_size = 2_359_293
+    if len(decoded) <= max_allowed_size:
+        return
+
+    _LOGGER.warning(msg="The image is too large.")
+    raise ImageTooLargeError
+
+
+@beartype
+def validate_image_is_image(*, request_body: bytes) -> None:
+    """Validate that the given image data is actually an image file.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        BadImageError: Image data is given and it is not an image file.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    image = json.loads(s=request_text).get("image")
+
+    if image is None:
+        return
+
+    decoded = decode_base64(encoded_data=image)
+    image_file = io.BytesIO(initial_bytes=decoded)
+
+    try:
+        with Image.open(fp=image_file) as _:
+            pass
+    except OSError as exc:
+        raise BadImageError from exc
+
+
+@beartype
+def validate_image_encoding(*, request_body: bytes) -> None:
+    """Validate that the given image data can be base64 decoded.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        FailError: Image data is given and it cannot be base64 decoded.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    if "image" not in json.loads(s=request_text):
+        return
+
+    image = json.loads(s=request_text).get("image")
+
+    try:
+        decode_base64(encoded_data=image)
+    except binascii.Error as exc:
+        _LOGGER.warning('Image data cannot be base64 decoded: "%s"', exc)
+        raise FailError(status_code=HTTPStatus.UNPROCESSABLE_ENTITY) from exc
+
+
+@beartype
+def validate_image_data_type(*, request_body: bytes) -> None:
+    """Validate that the given image data is a string.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        FailError: Image data is given and it is not a string.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    if "image" not in json.loads(s=request_text):
+        return
+
+    image = json.loads(s=request_text).get("image")
+
+    if isinstance(image, str):
+        return
+
+    _LOGGER.warning('Image data is not a string: "%s"', image)
+    raise FailError(status_code=HTTPStatus.BAD_REQUEST)

mock_vws/_services_validators/json_validators.py

@@ -0,0 +1,69 @@
+"""Validators for given JSON."""
+
+import json
+import logging
+from http import HTTPMethod, HTTPStatus
+from json.decoder import JSONDecodeError
+
+from beartype import beartype
+
+from mock_vws._services_validators.exceptions import (
+    BadRequestError,
+    FailError,
+    UnnecessaryRequestBodyError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_body_given(*, request_body: bytes, request_method: str) -> None:
+    """Validate that no JSON is given for requests other than ``POST`` and
+    ``PUT`` requests.
+
+    Args:
+        request_body: The body of the request.
+        request_method: The HTTP method of the request.
+
+    Raises:
+        UnnecessaryRequestBodyError: A request body was given for an endpoint
+            which does not require one.
+        FailError: The request body includes invalid JSON.
+    """
+    if not request_body:
+        return
+
+    if request_method not in {HTTPMethod.POST, HTTPMethod.PUT}:
+        _LOGGER.warning(
+            msg=(
+                "A request body was given for an endpoint which does not "
+                "require one."
+            ),
+        )
+        raise UnnecessaryRequestBodyError
+
+
+@beartype
+def validate_json(*, request_body: bytes, request_path: str) -> None:
+    """Validate that any given body is valid JSON.
+
+    Args:
+        request_body: The body of the request.
+        request_path: The path of the request.
+
+    Raises:
+        BadRequestError: The request body includes invalid JSON for the
+            VuMark instance generation endpoint.
+        FailError: The request body includes invalid JSON for other
+            endpoints.
+    """
+    if not request_body:
+        return
+
+    try:
+        json.loads(s=request_body.decode())
+    except JSONDecodeError as exc:
+        _LOGGER.warning(msg="The request body is not valid JSON.")
+        if request_path.endswith("/instances"):
+            raise BadRequestError from exc
+        raise FailError(status_code=HTTPStatus.BAD_REQUEST) from exc

mock_vws/_services_validators/key_validators.py

@@ -0,0 +1,171 @@
+"""Validators for JSON keys."""
+
+import json
+import logging
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from http import HTTPMethod, HTTPStatus
+
+from beartype import beartype
+
+from .exceptions import FailError
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+@dataclass(frozen=True, kw_only=True)
+class _Route:
+    """A representation of a VWS route.
+
+    Args:
+        path_pattern: The end part of a URL pattern. E.g. `/targets` or
+            `/targets/.+`.
+        http_methods: HTTP methods that map to the route function.
+        mandatory_keys: Keys required by the endpoint.
+        optional_keys: Keys which are not required by the endpoint but which
+            are allowed.
+    """
+
+    path_pattern: str
+    http_methods: Iterable[HTTPMethod]
+    mandatory_keys: Iterable[str]
+    optional_keys: Iterable[str]
+
+
+@beartype
+def validate_keys(
+    *,
+    request_body: bytes,
+    request_path: str,
+    request_method: str,
+) -> None:
+    """Validate the request keys given to a VWS endpoint.
+
+    Args:
+        request_body: The body of the request.
+        request_path: The path of the request.
+        request_method: The HTTP method of the request.
+
+    Raises:
+        FailError: Any given keys are not allowed, or if any required keys are
+            missing.
+    """
+    target_id_pattern = "[A-Za-z0-9]+"
+    add_target = _Route(
+        path_pattern="/targets",
+        http_methods={HTTPMethod.POST},
+        mandatory_keys={"image", "width", "name"},
+        optional_keys={"active_flag", "application_metadata"},
+    )
+
+    delete_target = _Route(
+        path_pattern=f"/targets/{target_id_pattern}",
+        http_methods={HTTPMethod.DELETE},
+        mandatory_keys=set(),
+        optional_keys=set(),
+    )
+
+    database_summary = _Route(
+        path_pattern="/summary",
+        http_methods={HTTPMethod.GET},
+        mandatory_keys=set(),
+        optional_keys=set(),
+    )
+
+    target_list = _Route(
+        path_pattern="/targets",
+        http_methods={HTTPMethod.GET},
+        mandatory_keys=set(),
+        optional_keys=set(),
+    )
+
+    get_target = _Route(
+        path_pattern=f"/targets/{target_id_pattern}",
+        http_methods={HTTPMethod.GET},
+        mandatory_keys=set(),
+        optional_keys=set(),
+    )
+
+    target_summary = _Route(
+        path_pattern=f"/summary/{target_id_pattern}",
+        http_methods={HTTPMethod.GET},
+        mandatory_keys=set(),
+        optional_keys=set(),
+    )
+
+    get_duplicates = _Route(
+        path_pattern=f"/duplicates/{target_id_pattern}",
+        http_methods={HTTPMethod.GET},
+        mandatory_keys=set(),
+        optional_keys=set(),
+    )
+
+    update_target = _Route(
+        path_pattern=f"/targets/{target_id_pattern}",
+        http_methods={HTTPMethod.PUT},
+        mandatory_keys=set(),
+        optional_keys={
+            "active_flag",
+            "application_metadata",
+            "image",
+            "name",
+            "width",
+        },
+    )
+
+    generate_instance = _Route(
+        path_pattern=f"/targets/{target_id_pattern}/instances",
+        http_methods={HTTPMethod.POST},
+        mandatory_keys={"instance_id"},
+        optional_keys=set(),
+    )
+
+    target_summary = _Route(
+        path_pattern=f"/summary/{target_id_pattern}",
+        http_methods={HTTPMethod.GET},
+        mandatory_keys=set(),
+        optional_keys=set(),
+    )
+
+    routes = (
+        add_target,
+        delete_target,
+        database_summary,
+        target_list,
+        get_target,
+        get_duplicates,
+        update_target,
+        generate_instance,
+        target_summary,
+    )
+
+    (matching_route,) = (
+        route
+        for route in routes
+        if re.match(
+            pattern=re.compile(pattern=f"{route.path_pattern}$"),
+            string=request_path,
+        )
+        and request_method in set(route.http_methods)
+    )
+
+    mandatory_keys = matching_route.mandatory_keys
+    optional_keys = matching_route.optional_keys
+    allowed_keys = {*mandatory_keys, *optional_keys}
+
+    if not request_body and not allowed_keys:
+        return
+
+    request_text = request_body.decode()
+    request_json = json.loads(s=request_text)
+    given_keys = set(request_json.keys())
+    all_given_keys_allowed = given_keys.issubset(allowed_keys)
+    all_mandatory_keys_given = set(mandatory_keys).issubset(set(given_keys))
+
+    if all_given_keys_allowed and all_mandatory_keys_given:
+        return
+
+    _LOGGER.warning(msg="Invalid keys given to endpoint.")
+    raise FailError(status_code=HTTPStatus.BAD_REQUEST)

mock_vws/_services_validators/metadata_validators.py

@@ -0,0 +1,106 @@
+"""Validators for application metadata."""
+
+import binascii
+import json
+import logging
+from http import HTTPStatus
+
+from beartype import beartype
+
+from mock_vws._base64_decoding import decode_base64
+from mock_vws._services_validators.exceptions import (
+    FailError,
+    MetadataTooLargeError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_metadata_size(*, request_body: bytes) -> None:
+    """Validate that the given application metadata is a string or 1024 *
+    1024
+    bytes or fewer.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        MetadataTooLargeError: Application metadata is given and it is too
+            large.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    request_json = json.loads(s=request_text)
+    application_metadata = request_json.get("application_metadata")
+    if application_metadata is None:
+        return
+    decoded = decode_base64(encoded_data=application_metadata)
+
+    max_metadata_bytes = 1024 * 1024 - 1
+    if len(decoded) <= max_metadata_bytes:
+        return
+
+    _LOGGER.warning(msg="The application metadata is too large.")
+    raise MetadataTooLargeError
+
+
+@beartype
+def validate_metadata_encoding(*, request_body: bytes) -> None:
+    """Validate that the given application metadata can be base64 decoded.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        FailError: Application metadata is given and it cannot be base64
+            decoded.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    request_json = json.loads(s=request_text)
+    if "application_metadata" not in request_json:
+        return
+
+    application_metadata = request_json.get("application_metadata")
+
+    if application_metadata is None:
+        return
+
+    try:
+        decode_base64(encoded_data=application_metadata)
+    except binascii.Error as exc:
+        _LOGGER.warning(msg="The application metadata is not base64 encoded.")
+        raise FailError(status_code=HTTPStatus.UNPROCESSABLE_ENTITY) from exc
+
+
+@beartype
+def validate_metadata_type(*, request_body: bytes) -> None:
+    """Validate that the given application metadata is a string or NULL.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        FailError: Application metadata is given and it is not a string or
+            NULL.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    request_json = json.loads(s=request_text)
+    if "application_metadata" not in request_json:
+        return
+
+    application_metadata = request_json.get("application_metadata")
+
+    if application_metadata is None or isinstance(application_metadata, str):
+        return
+
+    _LOGGER.warning(msg="The application metadata is not a string or NULL.")
+    raise FailError(status_code=HTTPStatus.BAD_REQUEST)