Create VuMarkTarget type for semantically correct VuMark fixture (#2968)

* Create VuMarkTarget type for semantically correct VuMark fixture

Previously, _vumark_database used ImageTarget for VuMark targets, which was
semantically incorrect since VuMark targets don't have image data. Now
VuMarkTarget is a proper type that reflects the differences: no image_value,
no processing_time_seconds, always SUCCESS status, and hardcoded tracking_rating.

Changes:
- Add VuMarkTarget and VuMarkTargetDict to target.py
- Add vumark_targets field to CloudDatabase (separate from image targets)
- Update not_deleted_targets to include both types for validator lookups
- Keep active_targets, inactive_targets, etc. as image-only for clarity
- Add POST /databases/{name}/vumark_targets Flask endpoint
- Update _vumark_database fixture to use VuMarkTarget
- Update _enable_use_docker_in_memory to use new endpoint
- Document VuMarkTarget in API reference

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* Fix type issues with get_target returning image targets only

The validator uses not_deleted_targets (which returns union type) so it can
find both image and VuMark targets. But get_target() is only called for image
targets in the Flask and requests mock servers, so return ImageTarget only.

* Fix mypy type hint for not_deleted_targets union

* Separate VuMark database from CloudDatabase and minimize VuMarkTarget

Introduce VuMarkDatabase and VuMarkDatabaseDict as distinct types from
CloudDatabase, since VuMark databases don't have client keys, state, or
quota fields. Minimize VuMarkTarget/VuMarkTargetDict to only the fields
actually used (target_id, name, delete_date). Update all validators,
Flask endpoints, and request mock servers to handle the AnyDatabase
union type.

Split target manager endpoints by database type: /databases for cloud,
/vumark_databases for VuMark. Add typed lookup helpers instead of
isinstance guards in endpoint functions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix Sphinx docs reference to renamed endpoint

The create_database endpoint was renamed to create_cloud_database
but the docs/source/docker.rst autoflask directive was not updated.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Split TargetManager.databases into typed cloud_databases and vumark_databases

This eliminates 22 isinstance checks by storing each database type
separately and narrowing all downstream signatures to the specific type
they need (CloudDatabase for VWS/VWQ APIs and validators).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Revert unnecessary changes to cloud-specific functions

Restore cloud functions to match main exactly - only VuMark additions remain.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Revert cosmetic changes to existing code

Remove unnecessary docstring tweaks, comment rewraps, and refactors
to CloudDatabase that are unrelated to VuMark support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix VuMark auth by widening validators to accept both database types

VuMark database credentials were not found during VWS authentication
because validators only searched cloud databases. Widen all service
validator signatures to accept AnyDatabase (CloudDatabase | VuMarkDatabase),
pass both database types from the Flask and requests-mock servers, and
add VuMarkDatabase to the Sphinx API docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address bugbot review: scope validate_request to cloud-only databases

- Skip validate_request for VuMark endpoint; it does its own validation
  with both database types (fixes 500 when VuMark creds hit cloud endpoints)
- Fix misleading error message in add_cloud_database ("cloud database" → "database")
- Deduplicate AnyDatabase alias: import from _database_matchers in target_manager

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update tests to match new database conflict error message

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix coverage: remove dead VuMark branches, add duplicate key tests

- Remove delete_date field from VuMarkTarget (VuMark targets can't be deleted)
- Simplify VuMarkDatabase.not_deleted_targets (no filtering needed)
- Remove NOT_FOUND branch from delete_vumark_database (internal API)
- Add test_duplicate_vumark_keys to both Flask and requests-mock test suites

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix VuMark duplicate keys test isolation in Flask tests

Use distinct keys ("v1", "v2", "v3") for VuMark database tests to avoid
conflicts with the TARGET_MANAGER singleton state from cloud database tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: adamtheturtle

docs/source/mock-api-reference.rst

@@ -20,12 +20,19 @@ API Reference
    :undoc-members:
    :exclude-members: to_dict, get_target, from_dict, not_deleted_targets, active_targets, inactive_targets, failed_targets, processing_targets
 
+.. autoclass:: mock_vws.database.VuMarkDatabase
+   :members:
+   :undoc-members:
+   :exclude-members: to_dict, from_dict, not_deleted_targets
+
 .. autoenum:: mock_vws.states.States
    :members:
    :undoc-members:
 
 .. autoclass:: mock_vws.target.ImageTarget
 
+.. autoclass:: mock_vws.target.VuMarkTarget
+
 Image matchers
 --------------
 

src/mock_vws/_database_matchers.py

@@ -5,7 +5,9 @@
 from beartype import beartype
 from vws_auth_tools import authorization_header
 
-from mock_vws.database import CloudDatabase
+from mock_vws.database import CloudDatabase, VuMarkDatabase
+
+AnyDatabase = CloudDatabase | VuMarkDatabase
 
 
 @beartype
@@ -58,14 +60,14 @@ def get_database_matching_client_keys(
 
 
 @beartype
-def get_database_matching_server_keys(
+def get_database_matching_server_keys[DatabaseT: AnyDatabase](
     *,
     request_headers: Mapping[str, str],
     request_body: bytes | None,
     request_method: str,
     request_path: str,
-    databases: Iterable[CloudDatabase],
-) -> CloudDatabase:
+    databases: Iterable[DatabaseT],
+) -> DatabaseT:
     """Return the first of the given databases which is being accessed by
     the
     given server request.

src/mock_vws/_flask_server/target_manager.py

@@ -12,9 +12,9 @@
 from flask import Flask, Response, request
 from pydantic_settings import BaseSettings
 
-from mock_vws.database import CloudDatabase
+from mock_vws.database import CloudDatabase, VuMarkDatabase
 from mock_vws.states import States
-from mock_vws.target import ImageTarget
+from mock_vws.target import ImageTarget, VuMarkTarget
 from mock_vws.target_manager import TargetManager
 from mock_vws.target_raters import (
     BrisqueTargetTrackingRater,
@@ -80,6 +80,25 @@ def delete_cloud_database(database_name: str) -> Response:
     return Response(response="", status=HTTPStatus.OK)
 
 
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases/<string:database_name>",
+    methods=[HTTPMethod.DELETE],
+)
+@beartype
+def delete_vumark_database(database_name: str) -> Response:
+    """Delete a VuMark database.
+
+    :status 200: The VuMark database has been deleted.
+    """
+    (matching_database,) = {
+        database
+        for database in TARGET_MANAGER.vumark_databases
+        if database_name == database.database_name
+    }
+    TARGET_MANAGER.remove_vumark_database(vumark_database=matching_database)
+    return Response(response="", status=HTTPStatus.OK)
+
+
 @TARGET_MANAGER_FLASK_APP.route(
     rule="/cloud_databases", methods=[HTTPMethod.GET]
 )
@@ -95,6 +114,22 @@ def get_cloud_databases() -> Response:
     )
 
 
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases",
+    methods=[HTTPMethod.GET],
+)
+@beartype
+def get_vumark_databases() -> Response:
+    """Return a list of all VuMark databases."""
+    databases = [
+        database.to_dict() for database in TARGET_MANAGER.vumark_databases
+    ]
+    return Response(
+        response=json.dumps(obj=databases),
+        status=HTTPStatus.OK,
+    )
+
+
 @TARGET_MANAGER_FLASK_APP.route(
     rule="/cloud_databases", methods=[HTTPMethod.POST]
 )
@@ -194,6 +229,47 @@ def create_cloud_database() -> Response:
     )
 
 
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases",
+    methods=[HTTPMethod.POST],
+)
+@beartype
+def create_vumark_database() -> Response:
+    """Create a new VuMark database.
+
+    :status 201: The database has been successfully created.
+    """
+    request_json = json.loads(s=request.data)
+    random_vumark_database = VuMarkDatabase()
+    database = VuMarkDatabase(
+        server_access_key=request_json.get(
+            "server_access_key",
+            random_vumark_database.server_access_key,
+        ),
+        server_secret_key=request_json.get(
+            "server_secret_key",
+            random_vumark_database.server_secret_key,
+        ),
+        database_name=request_json.get(
+            "database_name",
+            random_vumark_database.database_name,
+        ),
+    )
+
+    try:
+        TARGET_MANAGER.add_vumark_database(vumark_database=database)
+    except ValueError as exc:
+        return Response(
+            response=str(object=exc),
+            status=HTTPStatus.CONFLICT,
+        )
+
+    return Response(
+        response=json.dumps(obj=database.to_dict()),
+        status=HTTPStatus.CREATED,
+    )
+
+
 @TARGET_MANAGER_FLASK_APP.route(
     rule="/cloud_databases/<string:database_name>/targets",
     methods=[HTTPMethod.POST],
@@ -230,6 +306,28 @@ def create_target(database_name: str) -> Response:
     )
 
 
+@TARGET_MANAGER_FLASK_APP.route(
+    rule="/vumark_databases/<string:database_name>/vumark_targets",
+    methods=[HTTPMethod.POST],
+)
+@beartype
+def create_vumark_target(database_name: str) -> Response:
+    """Create a new VuMark target in a given database."""
+    (database,) = (
+        database
+        for database in TARGET_MANAGER.vumark_databases
+        if database.database_name == database_name
+    )
+    request_json = json.loads(s=request.data)
+    target = VuMarkTarget.from_dict(target_dict=request_json)
+    database.vumark_targets.add(target)
+
+    return Response(
+        response=json.dumps(obj=target.to_dict()),
+        status=HTTPStatus.CREATED,
+    )
+
+
 @TARGET_MANAGER_FLASK_APP.route(
     rule="/cloud_databases/<string:database_name>/targets/<string:target_id>",
     methods={HTTPMethod.DELETE},

src/mock_vws/_flask_server/vws.py

@@ -36,7 +36,7 @@
     TargetStatusProcessingError,
     ValidatorError,
 )
-from mock_vws.database import CloudDatabase
+from mock_vws.database import CloudDatabase, VuMarkDatabase
 from mock_vws.image_matchers import (
     ExactMatcher,
     ImageMatcher,
@@ -100,6 +100,21 @@ def get_all_cloud_databases() -> set[CloudDatabase]:
     }
 
 
+@beartype
+def get_all_vumark_databases() -> set[VuMarkDatabase]:
+    """Get all VuMark database objects from the task manager back-end."""
+    settings = VWSSettings.model_validate(obj={})
+    timeout_seconds = 30
+    response = requests.get(
+        url=f"{settings.target_manager_base_url}/vumark_databases",
+        timeout=timeout_seconds,
+    )
+    return {
+        VuMarkDatabase.from_dict(database_dict=database_dict)
+        for database_dict in response.json()
+    }
+
+
 @VWS_FLASK_APP.before_request
 def set_terminate_wsgi_input() -> None:
     """We set ``wsgi.input_terminated`` to ``True`` when going through
@@ -129,14 +144,19 @@ def set_terminate_wsgi_input() -> None:
 @VWS_FLASK_APP.before_request
 @beartype
 def validate_request() -> None:
-    """Run validators on the request."""
-    databases = get_all_cloud_databases()
+    """Run validators on the request.
+
+    The VuMark endpoint does its own validation because it needs to
+    authenticate against both cloud and VuMark databases.
+    """
+    if request.endpoint == "generate_vumark_instance":
+        return
     run_services_validators(
         request_headers=dict(request.headers),
         request_body=request.data,
         request_method=request.method,
         request_path=request.path,
-        databases=databases,
+        databases=get_all_cloud_databases(),
     )
 
 
@@ -357,6 +377,20 @@ def generate_vumark_instance(target_id: str) -> Response:
     Fake implementation of
     https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#generate-instance
     """
+    cloud_databases = get_all_cloud_databases()
+    vumark_databases = get_all_vumark_databases()
+    all_databases: list[CloudDatabase | VuMarkDatabase] = [
+        *cloud_databases,
+        *vumark_databases,
+    ]
+    run_services_validators(
+        request_headers=dict(request.headers),
+        request_body=request.data,
+        request_method=request.method,
+        request_path=request.path,
+        databases=all_databases,
+    )
+
     # ``target_id`` is validated by request validators.
     del target_id
 

src/mock_vws/_requests_mock_server/decorators.py

@@ -12,7 +12,7 @@
 from requests import PreparedRequest
 from responses import RequestsMock
 
-from mock_vws.database import CloudDatabase
+from mock_vws.database import CloudDatabase, VuMarkDatabase
 from mock_vws.image_matchers import (
     ImageMatcher,
     StructuralSimilarityMatcher,
@@ -140,6 +140,20 @@ def add_cloud_database(self, cloud_database: CloudDatabase) -> None:
             cloud_database=cloud_database,
         )
 
+    def add_vumark_database(self, vumark_database: VuMarkDatabase) -> None:
+        """Add a VuMark database.
+
+        Args:
+            vumark_database: The VuMark database to add.
+
+        Raises:
+            ValueError: One of the given database keys matches a key for
+                an existing database.
+        """
+        self._target_manager.add_vumark_database(
+            vumark_database=vumark_database,
+        )
+
     @staticmethod
     def _wrap_callback(
         callback: _Callback,

src/mock_vws/_requests_mock_server/mock_web_services_api.py

@@ -12,7 +12,7 @@
 import uuid
 from collections.abc import Callable, Iterable, Mapping
 from http import HTTPMethod, HTTPStatus
-from typing import Any, ParamSpec, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Any, ParamSpec, Protocol, runtime_checkable
 from zoneinfo import ZoneInfo
 
 from beartype import BeartypeConf, beartype
@@ -41,6 +41,9 @@
 from mock_vws.target_manager import TargetManager
 from mock_vws.target_raters import TargetTrackingRater
 
+if TYPE_CHECKING:
+    from mock_vws.database import CloudDatabase, VuMarkDatabase
+
 _TARGET_ID_PATTERN = "[A-Za-z0-9]+"
 
 
@@ -309,12 +312,16 @@ def generate_vumark_instance(
             "application/pdf": VUMARK_PDF,
         }
         try:
+            all_databases: list[CloudDatabase | VuMarkDatabase] = [
+                *self._target_manager.cloud_databases,
+                *self._target_manager.vumark_databases,
+            ]
             run_services_validators(
                 request_headers=request.headers,
                 request_body=_body_bytes(request=request),
                 request_method=request.method or "",
                 request_path=request.path_url,
-                databases=self._target_manager.cloud_databases,
+                databases=all_databases,
             )
 
             accept = dict(request.headers).get("Accept", "")

src/mock_vws/_services_validators/__init__.py

@@ -2,7 +2,7 @@
 
 from collections.abc import Iterable, Mapping
 
-from mock_vws.database import CloudDatabase
+from mock_vws._database_matchers import AnyDatabase
 
 from .active_flag_validators import validate_active_flag
 from .auth_validators import (
@@ -55,7 +55,7 @@ def run_services_validators(
     request_headers: Mapping[str, str],
     request_body: bytes,
     request_method: str,
-    databases: Iterable[CloudDatabase],
+    databases: Iterable[AnyDatabase],
 ) -> None:
     """Run all validators.
 

src/mock_vws/_services_validators/auth_validators.py

@@ -6,12 +6,14 @@
 
 from beartype import beartype
 
-from mock_vws._database_matchers import get_database_matching_server_keys
+from mock_vws._database_matchers import (
+    AnyDatabase,
+    get_database_matching_server_keys,
+)
 from mock_vws._services_validators.exceptions import (
     AuthenticationFailureError,
     FailError,
 )
-from mock_vws.database import CloudDatabase
 
 _LOGGER = logging.getLogger(name=__name__)
 
@@ -36,7 +38,7 @@ def validate_auth_header_exists(*, request_headers: Mapping[str, str]) -> None:
 def validate_access_key_exists(
     *,
     request_headers: Mapping[str, str],
-    databases: Iterable[CloudDatabase],
+    databases: Iterable[AnyDatabase],
 ) -> None:
     """Validate the authorization header includes an access key for a
     database.
@@ -92,7 +94,7 @@ def validate_authorization(
     request_headers: Mapping[str, str],
     request_body: bytes,
     request_method: str,
-    databases: Iterable[CloudDatabase],
+    databases: Iterable[AnyDatabase],
 ) -> None:
     """Validate the authorization header given to a VWS endpoint.