refactor(api): route draft variable APIs through application services

api/controllers/common/__init__.py

@@ -0,0 +1 @@
+"""Shared HTTP adapter helpers."""

api/controllers/common/errors.py

@@ -1,14 +1,19 @@
+import logging
 from collections import OrderedDict
 from http import HTTPStatus
-from typing import cast
+from typing import NoReturn, cast
 
 from flask import current_app, got_request_exception
+from werkzeug.exceptions import HTTPException
 
 from core.logging.context import get_request_id
 from libs.exception import BaseHTTPException
 from libs.external_api import ExternalApi
+from services.annotation.errors import AnnotationResourceNotFoundError
 from services.credentials.refresh import CredentialRefreshUnavailableError
 from services.errors.base import NoPermissionError
+from services.errors.dataset import DatasetNotFoundError
+from services.errors.document import DocumentAccessDeniedError, DocumentNotFoundError, DocumentSourceNotFoundError
 
 
 class FilenameNotExistsError(BaseHTTPException):
@@ -167,6 +172,96 @@ class InvalidArgumentError(BaseHTTPException):
     code = 400
 
 
+class InvalidRequestError(BaseHTTPException):
+    error_code = "bad_request"
+    code = 400
+    description = "The browser (or proxy) sent a request that this server could not understand."
+
+
+class AccessDeniedError(BaseHTTPException):
+    error_code = "forbidden"
+    code = 403
+    description = (
+        "You don't have the permission to access the requested resource. "
+        "It is either read-protected or not readable by the server."
+    )
+
+
+class AuthenticationRequiredError(BaseHTTPException):
+    error_code = "unauthorized"
+    code = 401
+    description = "Authentication is required."
+
+
+class UnsupportedMediaTypeError(BaseHTTPException):
+    error_code = "unsupported_media_type"
+    code = 415
+    description = "The server does not support the media type transmitted in the request."
+
+
+class UnprocessableEntityError(BaseHTTPException):
+    error_code = "unprocessable_entity"
+    code = 422
+
+
+class TooManyRequestsError(BaseHTTPException):
+    error_code = "too_many_requests"
+    code = 429
+    description = "This user has exceeded an allotted request count. Try again later."
+
+
+class RequestBodyTooLargeError(BaseHTTPException):
+    error_code = "request_entity_too_large"
+    code = 413
+
+
+def raise_unexpected_error(error: Exception, *, message: str) -> NoReturn:
+    """Keep HTTP failures intact and sanitize unclassified failures at the transport boundary.
+
+    Framework request parsing and project HTTP errors may both reach a route's
+    error translator. Neither should be converted to a generic server error.
+    """
+    if isinstance(error, HTTPException):
+        raise error
+    logging.getLogger(__name__).exception(message)
+    raise InternalServerError() from error
+
+
+def register_resource_error_handlers(api: ExternalApi) -> None:
+    """Translate annotation and document failures at the HTTP boundary."""
+
+    def missing_resource(error: Exception) -> tuple[dict[str, str | int], int]:
+        got_request_exception.send(current_app, exception=error)
+        return {"code": "not_found", "message": str(error), "status": 404}, 404
+
+    def document_access_denied(error: DocumentAccessDeniedError) -> tuple[dict[str, str | int], int]:
+        got_request_exception.send(current_app, exception=error)
+        return {"code": "forbidden", "message": str(error), "status": 403}, 403
+
+    for error_type in (
+        AnnotationResourceNotFoundError,
+        DatasetNotFoundError,
+        DocumentNotFoundError,
+        DocumentSourceNotFoundError,
+    ):
+        api.errorhandler(error_type)(missing_resource)
+        cast(OrderedDict[type[Exception], object], api.error_handlers).move_to_end(error_type, last=False)
+    api.errorhandler(DocumentAccessDeniedError)(document_access_denied)
+    cast(OrderedDict[type[Exception], object], api.error_handlers).move_to_end(DocumentAccessDeniedError, last=False)
+    for error_type in (
+        AnnotationResourceNotFoundError,
+        DatasetNotFoundError,
+        DocumentNotFoundError,
+        DocumentSourceNotFoundError,
+    ):
+        api.document_error_handler(error_type, status=HTTPStatus.NOT_FOUND, code=NotFoundError.error_code)
+    api.document_error_handler(
+        DocumentAccessDeniedError,
+        status=HTTPStatus.FORBIDDEN,
+        code=ForbiddenError.error_code,
+    )
+
+
 def register_permission_error_handler(api: ExternalApi) -> None:
     """Preserve the default permission-error response for Console and Service API."""
 

api/controllers/console/__init__.py

@@ -15,6 +15,7 @@
     UnauthorizedError,
     register_credential_refresh_error_handler,
     register_permission_error_handler,
+    register_resource_error_handlers,
 )
 from controllers.console.error import NotInitValidateError, NotSetupError, UnauthorizedAndForceLogout
 from controllers.console.workspace.error import AccountNotInitializedError
@@ -26,6 +27,7 @@
     WorkflowRunArchiveInvalidMonthError,
     WorkflowRunArchiveNotFoundError,
 )
+from services.workflow.variable_contracts import DraftVariableChangedError
 
 bp = Blueprint("console", __name__, url_prefix="/console/api")
 register_app_access_error_metadata(bp, surface="console")
@@ -37,6 +39,7 @@
     description="Console management APIs for app configuration, monitoring, and administration",
 )
 register_permission_error_handler(api)
+register_resource_error_handlers(api)
 register_credential_refresh_error_handler(api)
 # Errors the Console client handles centrally (bootstrap redirects, forced logout, malformed
 # input); any operation may answer with them, so no operation lists them. The shared
@@ -117,6 +120,26 @@ def _handle_workflow_run_archive_download_not_ready_error(
 api.document_error_handler(WorkflowRunArchiveDownloadNotReadyError, status=HTTPStatus.CONFLICT, code="conflict")
 
 
+@api.errorhandler(DraftVariableChangedError)
+def _handle_draft_variable_changed_error(error: DraftVariableChangedError):
+    """Expose a concurrent variable edit consistently across Console use cases."""
+    got_request_exception.send(current_app, exception=error)
+    status = HTTPStatus.CONFLICT
+    return {
+        "code": "draft_variable_changed",
+        "message": "Variable changed; refresh and retry with the current value.",
+        "status": status.value,
+    }, status.value
+
+
+cast(OrderedDict[type[Exception], object], api.error_handlers).move_to_end(DraftVariableChangedError, last=False)
+api.document_error_handler(
+    DraftVariableChangedError,
+    status=HTTPStatus.CONFLICT,
+    code="draft_variable_changed",
+)
+
+
 console_ns = Namespace("console", description="Console management API operations", path="/")
 
 RESOURCE_MODULES = (