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

mock_vws/_query_validators/__init__.py

@@ -0,0 +1,128 @@
+"""Input validators to use in the mock query API."""
+
+from collections.abc import Iterable, Mapping
+
+from beartype import beartype
+
+from mock_vws.database import CloudDatabase
+
+from .accept_header_validators import validate_accept_header
+from .auth_validators import (
+    validate_auth_header_exists,
+    validate_auth_header_has_signature,
+    validate_auth_header_number_of_parts,
+    validate_authorization,
+    validate_client_key_exists,
+)
+from .content_length_validators import (
+    validate_content_length_header_is_int,
+    validate_content_length_header_not_too_large,
+    validate_content_length_header_not_too_small,
+)
+from .content_type_validators import validate_content_type_header
+from .date_validators import (
+    validate_date_format,
+    validate_date_header_given,
+    validate_date_in_range,
+)
+from .fields_validators import validate_extra_fields
+from .image_validators import (
+    validate_image_dimensions,
+    validate_image_field_given,
+    validate_image_file_size,
+    validate_image_format,
+    validate_image_is_image,
+)
+from .include_target_data_validators import validate_include_target_data
+from .num_results_validators import validate_max_num_results
+from .project_state_validators import validate_project_state
+
+
+@beartype
+def run_query_validators(
+    *,
+    request_path: str,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+    request_method: str,
+    databases: Iterable[CloudDatabase],
+) -> None:
+    """Run all validators.
+
+    Args:
+        request_path: The path of the request.
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+        request_method: The HTTP method of the request.
+        databases: All Vuforia databases.
+    """
+    validate_content_length_header_is_int(request_headers=request_headers)
+    validate_content_length_header_not_too_large(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_content_length_header_not_too_small(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_auth_header_exists(request_headers=request_headers)
+    validate_auth_header_number_of_parts(request_headers=request_headers)
+    validate_auth_header_has_signature(request_headers=request_headers)
+    validate_client_key_exists(
+        request_headers=request_headers,
+        databases=databases,
+    )
+    validate_authorization(
+        request_headers=request_headers,
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+        databases=databases,
+    )
+    validate_project_state(
+        request_headers=request_headers,
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+        databases=databases,
+    )
+    validate_accept_header(request_headers=request_headers)
+    validate_date_header_given(request_headers=request_headers)
+    validate_date_format(request_headers=request_headers)
+    validate_date_in_range(request_headers=request_headers)
+    validate_content_type_header(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_extra_fields(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_image_field_given(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_image_is_image(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_image_format(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_image_dimensions(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_image_file_size(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_max_num_results(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    validate_include_target_data(
+        request_headers=request_headers,
+        request_body=request_body,
+    )

mock_vws/_query_validators/accept_header_validators.py

@@ -0,0 +1,31 @@
+"""Validators for the ``Accept`` header."""
+
+import logging
+from collections.abc import Mapping
+
+from beartype import beartype
+
+from mock_vws._query_validators.exceptions import InvalidAcceptHeaderError
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_accept_header(request_headers: Mapping[str, str]) -> None:
+    """Validate the accept header.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        InvalidAcceptHeaderError: The Accept header is given and is not
+            'application/json' or '*/*'.
+    """
+    accept = request_headers.get("Accept")
+    if accept in {"application/json", "*/*", None}:
+        return
+
+    _LOGGER.warning(
+        msg="The Accept header is not 'application/json' or '*/*'.",
+    )
+    raise InvalidAcceptHeaderError

mock_vws/_query_validators/auth_validators.py

@@ -0,0 +1,143 @@
+"""Authorization validators to use in the mock query API."""
+
+import logging
+from collections.abc import Iterable, Mapping
+
+from beartype import beartype
+
+from mock_vws._database_matchers import get_database_matching_client_keys
+from mock_vws._query_validators.exceptions import (
+    AuthenticationFailureError,
+    AuthHeaderMissingError,
+    MalformedAuthHeaderError,
+)
+from mock_vws.database import CloudDatabase
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_auth_header_exists(*, request_headers: Mapping[str, str]) -> None:
+    """Validate that there is an authorization header given to the query
+    endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        AuthHeaderMissingError: There is no "Authorization" header.
+    """
+    if "Authorization" in request_headers:
+        return
+
+    _LOGGER.warning(msg="There is no authorization header.")
+    raise AuthHeaderMissingError
+
+
+@beartype
+def validate_auth_header_number_of_parts(
+    *,
+    request_headers: Mapping[str, str],
+) -> None:
+    """Validate the authorization header includes text either side of a
+    space.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        MalformedAuthHeaderError: The "Authorization" header is not as
+            expected.
+    """
+    header = request_headers["Authorization"]
+    parts = header.split(sep=" ")
+    expected_number_of_parts = 2
+    if len(parts) == expected_number_of_parts and parts[1]:
+        return
+
+    _LOGGER.warning(msg="The authorization header is malformed.")
+    raise MalformedAuthHeaderError
+
+
+@beartype
+def validate_client_key_exists(
+    *,
+    request_headers: Mapping[str, str],
+    databases: Iterable[CloudDatabase],
+) -> None:
+    """Validate the authorization header includes a client key for a
+    database.
+
+    Args:
+        request_headers: The headers sent with the request.
+        databases: All Vuforia databases.
+
+    Raises:
+        AuthenticationFailureError: The client key is unknown.
+    """
+    header = request_headers["Authorization"]
+    first_part, _ = header.split(sep=":")
+    _, access_key = first_part.split(sep=" ")
+    for database in databases:
+        if access_key == database.client_access_key:
+            return
+
+    _LOGGER.warning(msg="The client key is unknown.")
+    raise AuthenticationFailureError
+
+
+@beartype
+def validate_auth_header_has_signature(
+    request_headers: Mapping[str, str],
+) -> None:
+    """Validate the authorization header includes a signature.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        MalformedAuthHeaderError: The "Authorization" header has no signature.
+    """
+    header = request_headers["Authorization"]
+    if header.count(":") == 1 and header.split(sep=":")[1]:
+        return
+
+    _LOGGER.warning(msg="The authorization header has no signature.")
+    raise MalformedAuthHeaderError
+
+
+@beartype
+def validate_authorization(
+    *,
+    request_path: str,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+    request_method: str,
+    databases: Iterable[CloudDatabase],
+) -> None:
+    """Validate the authorization header given to the query endpoint.
+
+    Args:
+        request_path: The path of the request.
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+        request_method: The HTTP method of the request.
+        databases: All Vuforia databases.
+
+    Raises:
+        AuthenticationFailureError: The "Authorization" header is not as
+            expected.
+    """
+    try:
+        get_database_matching_client_keys(
+            request_headers=request_headers,
+            request_body=request_body,
+            request_method=request_method,
+            request_path=request_path,
+            databases=databases,
+        )
+    except ValueError as exc:
+        _LOGGER.warning(
+            msg="The authorization header does not match any databases.",
+        )
+        raise AuthenticationFailureError from exc

mock_vws/_query_validators/content_length_validators.py

@@ -0,0 +1,90 @@
+"""Content-Length header validators to use in the mock."""
+
+import logging
+from collections.abc import Mapping
+
+from beartype import beartype
+
+from mock_vws._query_validators.exceptions import (
+    AuthenticationFailureGoodFormattingError,
+    ContentLengthHeaderNotIntError,
+    ContentLengthHeaderTooLargeError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_content_length_header_is_int(
+    *,
+    request_headers: Mapping[str, str],
+) -> None:
+    """Validate the ``Content-Length`` header is an integer.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        ContentLengthHeaderNotIntError: ``Content-Length`` header is not an
+            integer.
+    """
+    given_content_length = request_headers["Content-Length"]
+
+    try:
+        int(given_content_length)
+    except ValueError as exc:
+        _LOGGER.warning(msg="The Content-Length header is not an integer.")
+        raise ContentLengthHeaderNotIntError from exc
+
+
+@beartype
+def validate_content_length_header_not_too_large(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the ``Content-Length`` header is not too large.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        ContentLengthHeaderTooLargeError: The given content length header says
+            that the content length is greater than the body length.
+    """
+    given_content_length = request_headers["Content-Length"]
+
+    body_length = len(request_body)
+    given_content_length_value = int(given_content_length)
+    # We skip coverage here as running a test to cover this is very slow.
+    if given_content_length_value > body_length:  # pragma: no cover
+        _LOGGER.warning(msg="The Content-Length header is too large.")
+        raise ContentLengthHeaderTooLargeError
+
+
+@beartype
+def validate_content_length_header_not_too_small(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the ``Content-Length`` header is not too small.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        AuthenticationFailureGoodFormattingError: The given content length
+            header says that the content length is smaller than the body
+            length.
+    """
+    given_content_length = request_headers["Content-Length"]
+
+    body_length = len(request_body)
+    given_content_length_value = int(given_content_length)
+
+    if given_content_length_value < body_length:
+        _LOGGER.warning(msg="The Content-Length header is too small.")
+        raise AuthenticationFailureGoodFormattingError

mock_vws/_query_validators/content_type_validators.py

@@ -0,0 +1,65 @@
+"""Validators for the ``Content-Type`` header."""
+
+import logging
+from collections.abc import Mapping
+from email.message import EmailMessage
+
+from beartype import beartype
+
+from mock_vws._query_validators.exceptions import (
+    ImageNotGivenError,
+    NoBoundaryFoundError,
+    NoContentTypeError,
+    UnsupportedMediaTypeError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_content_type_header(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the ``Content-Type`` header.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        UnsupportedMediaTypeError: The ``Content-Type`` header main part is not
+            'multipart/form-data'.
+        NoBoundaryFoundError: The ``Content-Type`` header does not contain a
+            boundary.
+        ImageNotGivenError: The boundary is not in the request body.
+        NoContentTypeError: The content type header is either empty or not
+            given.
+    """
+    request_headers_dict = dict(request_headers)
+    content_type_header = request_headers_dict.get("Content-Type", "")
+    if not content_type_header:
+        _LOGGER.warning(msg="The content type header is empty.")
+        raise NoContentTypeError
+
+    email_message = EmailMessage()
+    email_message["Content-Type"] = request_headers["Content-Type"]
+    if email_message.get_content_type() not in {"multipart/form-data", "*/*"}:
+        _LOGGER.warning(
+            msg=(
+                "The content type header main part is not multipart/form-data."
+            ),
+        )
+        raise UnsupportedMediaTypeError
+
+    boundary = email_message.get_boundary()
+    if boundary is None:
+        _LOGGER.warning(
+            msg="The content type header does not contain a boundary.",
+        )
+        raise NoBoundaryFoundError
+
+    if boundary.encode() not in request_body:
+        _LOGGER.warning(msg="The boundary is not in the request body.")
+        raise ImageNotGivenError

mock_vws/_query_validators/date_validators.py

@@ -0,0 +1,110 @@
+"""Validators of the date header to use in the mock query API."""
+
+import contextlib
+import datetime
+import logging
+from collections.abc import Mapping
+from zoneinfo import ZoneInfo
+
+from beartype import beartype
+
+from mock_vws._query_validators.exceptions import (
+    DateFormatNotValidError,
+    DateHeaderNotGivenError,
+    RequestTimeTooSkewedError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_date_header_given(*, request_headers: Mapping[str, str]) -> None:
+    """Validate the date header is given to the query endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        DateHeaderNotGivenError: The date is not given.
+    """
+    if "Date" in request_headers:
+        return
+
+    _LOGGER.warning(msg="The date header is not given.")
+    raise DateHeaderNotGivenError
+
+
+@beartype
+def _accepted_date_formats() -> set[str]:
+    """Return all known accepted date formats.
+
+    We expect that more formats than this will be accepted. These are
+    the accepted ones we know of at the time of writing.
+    """
+    known_accepted_formats = {
+        "%a, %b %d %H:%M:%S %Y",
+        "%a %b %d %H:%M:%S %Y",
+        "%a, %d %b %Y %H:%M:%S",
+        "%a %d %b %Y %H:%M:%S",
+    }
+
+    return known_accepted_formats.union(
+        {f"{date_format} GMT" for date_format in known_accepted_formats},
+    )
+
+
+@beartype
+def validate_date_format(*, request_headers: Mapping[str, str]) -> None:
+    """Validate the format of the date header given to the query endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        DateFormatNotValidError: The date is in the wrong format.
+    """
+    date_header = request_headers["Date"]
+
+    for date_format in _accepted_date_formats():
+        with contextlib.suppress(ValueError):
+            datetime.datetime.strptime(date_header, date_format).astimezone()
+            return
+
+    _LOGGER.warning(msg="The date header is in the wrong format.")
+    raise DateFormatNotValidError
+
+
+@beartype
+def validate_date_in_range(*, request_headers: Mapping[str, str]) -> None:
+    """Validate date in the date header given to the query endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        RequestTimeTooSkewedError: The date is out of range.
+    """
+    date_header = request_headers["Date"]
+    gmt = ZoneInfo(key="GMT")
+
+    dates: list[datetime.datetime] = []
+    for date_format in _accepted_date_formats():
+        with contextlib.suppress(ValueError):
+            date = datetime.datetime.strptime(
+                date_header,
+                date_format,
+            ).astimezone()
+            dates.append(date)
+
+    date = dates[0]
+    now = datetime.datetime.now(tz=gmt)
+    date_from_header = date.replace(tzinfo=gmt)
+    time_difference = now - date_from_header
+
+    maximum_time_difference = datetime.timedelta(minutes=65)
+
+    if abs(time_difference) < maximum_time_difference:
+        return
+
+    _LOGGER.warning(msg="The date header is out of range.")
+    raise RequestTimeTooSkewedError