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

mock_vws/_respx_mock_server/__init__.py

@@ -0,0 +1 @@
+"""A fake implementation of Vuforia Web Services for use with respx."""

mock_vws/_respx_mock_server/decorators.py

@@ -0,0 +1,186 @@
+"""Helpers for mocking Vuforia with httpx via respx."""
+
+import re
+from collections.abc import Callable, Mapping
+from typing import Protocol
+from urllib.parse import urlparse
+
+import httpx
+import respx
+
+from mock_vws._mock_common import RequestData, Route
+
+_ResponseType = tuple[int, Mapping[str, str], str | bytes]
+
+
+class _APIHandler(Protocol):
+    """An API handler with mock routes."""
+
+    routes: set[Route]
+
+
+def _to_request_data(
+    request: httpx.Request,
+    *,
+    base_path: str,
+) -> RequestData:
+    """Convert an httpx.Request to a RequestData.
+
+    Args:
+        request: The httpx request to convert.
+        base_path: The base path prefix to strip from the request path.
+
+    Returns:
+        A RequestData with method, path, headers, and body set.
+    """
+    path = request.url.raw_path.decode(encoding="ascii")
+    if base_path and path.startswith(base_path):
+        path = path[len(base_path) :]
+    return RequestData(
+        method=request.method,
+        path=path,
+        headers={k.title(): v for k, v in request.headers.items()},
+        body=request.content,
+    )
+
+
+def _block_unmatched(request: httpx.Request) -> httpx.Response:
+    """Raise ConnectError for unmatched requests when real_http=False.
+
+    Args:
+        request: The unmatched httpx request.
+
+    Raises:
+        Exception: A connection error is always raised to block
+            unmatched requests.
+    """
+    raise httpx.ConnectError(
+        message="Connection refused by mock",
+        request=request,
+    )
+
+
+def _make_respx_callback(
+    *,
+    handler: Callable[[RequestData], _ResponseType],
+    base_path: str,
+    delay_seconds: float,
+    sleep_fn: Callable[[float], None],
+) -> Callable[[httpx.Request], httpx.Response]:
+    """Create a respx-compatible callback from a handler.
+
+    Args:
+        handler: A handler that takes a RequestData and returns a
+            response tuple.
+        base_path: The base path prefix to strip from the request path.
+        delay_seconds: The number of seconds to delay the response by.
+        sleep_fn: The function to use for sleeping during delays.
+
+    Returns:
+        A callback that takes an httpx.Request and returns an
+        httpx.Response.
+    """
+
+    def callback(request: httpx.Request) -> httpx.Response:
+        """Handle an httpx request by converting it and calling the
+        handler.
+
+        Args:
+            request: The httpx request to handle.
+
+        Returns:
+            An httpx.Response built from the handler's return value.
+
+        Raises:
+            Exception: A timeout error is raised when the response
+                delay exceeds the read timeout.
+        """
+        request_data = _to_request_data(
+            request=request,
+            base_path=base_path,
+        )
+        timeout_info: dict[str, float | None] = request.extensions.get(
+            "timeout", {}
+        )
+        read_timeout = timeout_info.get("read")
+        if read_timeout is not None and delay_seconds > read_timeout:
+            sleep_fn(read_timeout)
+            raise httpx.ReadTimeout(
+                message="Response delay exceeded read timeout",
+                request=request,
+            )
+        status_code, headers, body = handler(request_data)
+        sleep_fn(delay_seconds)
+        if isinstance(body, str):
+            body = body.encode()
+        return httpx.Response(
+            status_code=status_code,
+            headers=headers,
+            content=body,
+        )
+
+    return callback
+
+
+def start_respx_router(
+    *,
+    mock_vws_api: _APIHandler,
+    mock_vwq_api: _APIHandler,
+    base_vws_url: str,
+    base_vwq_url: str,
+    response_delay_seconds: float,
+    sleep_fn: Callable[[float], None],
+    real_http: bool,
+) -> respx.MockRouter:
+    """Configure and start a respx router with Vuforia routes.
+
+    Args:
+        mock_vws_api: The VWS API handler.
+        mock_vwq_api: The VWQ API handler.
+        base_vws_url: The base URL for the VWS API.
+        base_vwq_url: The base URL for the VWQ API.
+        response_delay_seconds: The number of seconds to delay responses.
+        sleep_fn: The function to use for sleeping during delays.
+        real_http: Whether to pass through unmatched requests.
+
+    Returns:
+        A started respx router.
+    """
+    router = respx.MockRouter(
+        assert_all_called=False,
+        assert_all_mocked=False,
+    )
+
+    for api, base_url in (
+        (mock_vws_api, base_vws_url),
+        (mock_vwq_api, base_vwq_url),
+    ):
+        base_path = urlparse(url=base_url).path.rstrip("/")
+        for route in api.routes:
+            url_pattern = base_url.rstrip("/") + route.path_pattern + "$"
+            compiled_url_pattern = re.compile(pattern=url_pattern)
+
+            for http_method in route.http_methods:
+                original_callback = getattr(  # pylint: disable=bad-builtin
+                    api,
+                    route.route_name,
+                )
+                router.route(
+                    method=http_method,
+                    url=compiled_url_pattern,
+                ).mock(
+                    side_effect=_make_respx_callback(
+                        handler=original_callback,
+                        base_path=base_path,
+                        delay_seconds=response_delay_seconds,
+                        sleep_fn=sleep_fn,
+                    ),
+                )
+
+    if real_http:
+        router.route().pass_through()
+    else:
+        router.route().mock(side_effect=_block_unmatched)
+
+    router.start()
+    return router

mock_vws/_services_validators/__init__.py

@@ -0,0 +1,186 @@
+"""Input validators to use in the mock."""
+
+from collections.abc import Iterable, Mapping
+
+from beartype import beartype
+
+from mock_vws._database_matchers import AnyDatabase
+
+from .active_flag_validators import validate_active_flag
+from .auth_validators import (
+    validate_access_key_exists,
+    validate_auth_header_exists,
+    validate_auth_header_has_signature,
+    validate_authorization,
+)
+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_given
+from .date_validators import (
+    validate_date_format,
+    validate_date_header_given,
+    validate_date_in_range,
+)
+from .image_validators import (
+    validate_image_color_space,
+    validate_image_data_type,
+    validate_image_encoding,
+    validate_image_format,
+    validate_image_integrity,
+    validate_image_is_image,
+    validate_image_size,
+)
+from .json_validators import validate_body_given, validate_json
+from .key_validators import validate_keys
+from .metadata_validators import (
+    validate_metadata_encoding,
+    validate_metadata_size,
+    validate_metadata_type,
+)
+from .name_validators import (
+    validate_name_characters_in_range,
+    validate_name_does_not_exist_existing_target,
+    validate_name_does_not_exist_new_target,
+    validate_name_length,
+    validate_name_type,
+)
+from .project_state_validators import validate_project_state
+from .request_quota_validators import validate_request_quota
+from .target_quota_validators import validate_target_quota
+from .target_validators import validate_target_id_exists
+from .width_validators import validate_width
+
+
+@beartype
+def run_services_validators(
+    *,
+    request_path: str,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+    request_method: str,
+    databases: Iterable[AnyDatabase],
+) -> 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_auth_header_exists(request_headers=request_headers)
+    validate_auth_header_has_signature(request_headers=request_headers)
+    validate_access_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_request_quota(
+        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_target_quota(
+        request_headers=request_headers,
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+        databases=databases,
+    )
+    validate_target_id_exists(
+        request_headers=request_headers,
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+        databases=databases,
+    )
+
+    validate_body_given(
+        request_body=request_body,
+        request_method=request_method,
+    )
+
+    validate_date_header_given(request_headers=request_headers)
+    validate_date_format(request_headers=request_headers)
+    validate_date_in_range(request_headers=request_headers)
+
+    validate_json(request_body=request_body, request_path=request_path)
+
+    validate_keys(
+        request_body=request_body,
+        request_path=request_path,
+        request_method=request_method,
+    )
+    validate_metadata_type(request_body=request_body)
+    validate_metadata_encoding(request_body=request_body)
+    validate_metadata_size(request_body=request_body)
+    validate_active_flag(request_body=request_body)
+
+    validate_image_data_type(request_body=request_body)
+    validate_image_encoding(request_body=request_body)
+    validate_image_is_image(request_body=request_body)
+    validate_image_format(request_body=request_body)
+    validate_image_color_space(request_body=request_body)
+    validate_image_size(request_body=request_body)
+    validate_image_integrity(request_body=request_body)
+
+    validate_name_type(request_body=request_body)
+    validate_name_length(request_body=request_body)
+    validate_name_characters_in_range(
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+    )
+    validate_name_does_not_exist_new_target(
+        request_headers=request_headers,
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+        databases=databases,
+    )
+    validate_name_does_not_exist_existing_target(
+        request_headers=request_headers,
+        request_body=request_body,
+        request_method=request_method,
+        request_path=request_path,
+        databases=databases,
+    )
+
+    validate_width(request_body=request_body)
+    validate_content_type_header_given(
+        request_headers=request_headers,
+        request_method=request_method,
+    )
+
+    validate_content_length_header_is_int(
+        request_headers=request_headers,
+        request_body=request_body,
+    )
+    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,
+    )

mock_vws/_services_validators/active_flag_validators.py

@@ -0,0 +1,43 @@
+"""Validators for the active flag."""
+
+import json
+import logging
+from http import HTTPStatus
+
+from beartype import beartype
+
+from mock_vws._services_validators.exceptions import FailError
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_active_flag(*, request_body: bytes) -> None:
+    """Validate the active flag data given to the endpoint.
+
+    Args:
+        request_body: The body of the request.
+
+    Raises:
+        FailError: There is active flag data given to the endpoint which is not
+            either a Boolean or NULL.
+    """
+    if not request_body:
+        return
+
+    request_text = request_body.decode()
+    if "active_flag" not in json.loads(s=request_text):
+        return
+
+    active_flag = json.loads(s=request_text).get("active_flag")
+
+    if active_flag in {True, False, None}:
+        return
+
+    _LOGGER.warning(
+        msg=(
+            'The value of "active_flag" is not a Boolean or NULL. '
+            "This is not allowed."
+        ),
+    )
+    raise FailError(status_code=HTTPStatus.BAD_REQUEST)

mock_vws/_services_validators/auth_validators.py

@@ -0,0 +1,124 @@
+"""Authorization header validators to use in the mock."""
+
+import logging
+from collections.abc import Iterable, Mapping
+from http import HTTPStatus
+
+from beartype import beartype
+
+from mock_vws._database_matchers import (
+    AnyDatabase,
+    get_database_matching_server_keys,
+)
+from mock_vws._services_validators.exceptions import (
+    AuthenticationFailureError,
+    FailError,
+)
+
+_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 a VWS
+    endpoint.
+
+    Args:
+        request_headers: The headers sent with the request.
+
+    Raises:
+        AuthenticationFailureError: There is no "Authorization" header.
+    """
+    if "Authorization" not in request_headers:
+        _LOGGER.warning(msg="There is no authorization header.")
+        raise AuthenticationFailureError
+
+
+@beartype
+def validate_access_key_exists(
+    *,
+    request_headers: Mapping[str, str],
+    databases: Iterable[AnyDatabase],
+) -> None:
+    """Validate the authorization header includes an access key for a
+    database.
+
+    Args:
+        request_headers: The headers sent with the request.
+        databases: All Vuforia databases.
+
+    Raises:
+        FailError: The access key does not match a given database.
+    """
+    header = request_headers["Authorization"]
+    first_part, _ = header.split(sep=":")
+    _, access_key = first_part.split(sep=" ")
+    for database in databases:
+        if access_key == database.server_access_key:
+            return
+
+    _LOGGER.warning(
+        'The access key "%s" does not match a known database.',
+        access_key,
+    )
+    raise FailError(status_code=HTTPStatus.BAD_REQUEST)
+
+
+@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:
+        FailError: The "Authorization" header does not include a signature.
+    """
+    header = request_headers["Authorization"]
+    if header.count(":") == 1 and header.split(sep=":")[1]:
+        return
+
+    _LOGGER.warning(
+        msg="The authorization header does not include a signature.",
+    )
+    raise FailError(status_code=HTTPStatus.BAD_REQUEST)
+
+
+@beartype
+def validate_authorization(
+    *,
+    request_path: str,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+    request_method: str,
+    databases: Iterable[AnyDatabase],
+) -> None:
+    """Validate the authorization header given to a VWS 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: No database matches the given authorization
+            header.
+    """
+    try:
+        get_database_matching_server_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="No database matches the given authorization header.",
+        )
+        raise AuthenticationFailureError from exc

mock_vws/_services_validators/content_length_validators.py

@@ -0,0 +1,102 @@
+"""Content-Length header validators to use in the mock."""
+
+import logging
+from collections.abc import Mapping
+
+from beartype import beartype
+
+from mock_vws._services_validators.exceptions import (
+    AuthenticationFailureError,
+    ContentLengthHeaderNotIntError,
+    ContentLengthHeaderTooLargeError,
+)
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_content_length_header_is_int(
+    *,
+    request_headers: Mapping[str, str],
+    request_body: bytes,
+) -> None:
+    """Validate the ``Content-Length`` header is an integer.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_body: The body of the request.
+
+    Raises:
+        ContentLengthHeaderNotIntError: The content length header is not an
+            integer
+    """
+    body_length = len(request_body)
+    request_headers_dict = dict(request_headers)
+    given_content_length = request_headers_dict.get(
+        "Content-Length",
+        body_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.
+    """
+    body_length = len(request_body)
+    request_headers_dict = dict(request_headers)
+    given_content_length = request_headers_dict.get(
+        "Content-Length",
+        body_length,
+    )
+    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:
+        AuthenticationFailureError: The given content length header says that
+            the content length is smaller than the body length.
+    """
+    body_length = len(request_body)
+    request_headers_dict = dict(request_headers)
+    given_content_length = request_headers_dict.get(
+        "Content-Length",
+        body_length,
+    )
+    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 AuthenticationFailureError

mock_vws/_services_validators/content_type_validators.py

@@ -0,0 +1,42 @@
+"""Content-Type header validators to use in the mock."""
+
+import logging
+from collections.abc import Mapping
+from http import HTTPMethod
+
+from beartype import beartype
+
+from mock_vws._services_validators.exceptions import AuthenticationFailureError
+
+_LOGGER = logging.getLogger(name=__name__)
+
+
+@beartype
+def validate_content_type_header_given(
+    *,
+    request_headers: Mapping[str, str],
+    request_method: str,
+) -> None:
+    """Validate that there is a non-empty content type header given if
+    required.
+
+    Args:
+        request_headers: The headers sent with the request.
+        request_method: The HTTP method of the request.
+
+    Raises:
+        AuthenticationFailureError: No ``Content-Type`` header is given and the
+            request requires one.
+    """
+    request_headers_dict = dict(request_headers)
+    request_needs_content_type = bool(
+        request_method in {HTTPMethod.POST, HTTPMethod.PUT},
+    )
+    if (
+        request_headers_dict.get("Content-Type")
+        or not request_needs_content_type
+    ):
+        return
+
+    _LOGGER.warning(msg="No Content-Type header is given.")
+    raise AuthenticationFailureError