refactor(web): one error-response path for api_v3 (#624)

* refactor(web): answer unhandled api_v3 errors from one blueprint handler Fifty-three api_v3 routes ended in a copy of the same catch-all: log the traceback, return {status, "An error occurred; see logs for details", details: describe_exception(e)} with a 500. They are replaced by one errorhandler on the api_v3 blueprint that returns exactly that body. It lives on the blueprint rather than falling through to app.py's global handler because the two answers differ: the global one adds error_code: UNKNOWN_ERROR, and api_client.js sends a body with an error_code to the error modal and one without to a plain toast. A blueprint handler also gives tests that mount api_v3 on a bare Flask app the same answer the real app gives. Only handlers that were byte-for-byte that shape were removed (matched on the AST, and each rewritten function re-parsed and compared). Handlers with their own message, extra keys, operation-history records or cleanup stay, as does execute_plugin_action's step-1 handler, which sits inside an `except subprocess.TimeoutExpired` arm that would otherwise turn a plugin's timeout into a 408. HTTPExceptions raised inside a route go back as themselves in the global handler's 4xx shape. Where a removed catch-all used to swallow one (only delete_plugin_asset's non-silent get_json() is reachable), a malformed request now gets its 415/400 instead of a 500. Most of the diff is re-indentation from unwrapping the try blocks; `git diff -w` shows the real change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): plugin action errors name the real failure, not UnboundLocalError execute_plugin_action bound a local `logger` in its JSON-parsing arm, which made `logger` local to the whole function. Every other `logger.error` in it then raised UnboundLocalError, so a failing OAuth step-1 script was reported as "UnboundLocalError: cannot access local variable 'logger'" -- from the step-1 handler, and before the previous commit from the route's outer catch-all too. Use the module logger. Found by comparing every api_v3 route's forced-failure response before and after the catch-all consolidation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): drop the error category and exception-name code guessing WebInterfaceError derived an ErrorCategory from every error code and put it in each structured error body as `error_category`. Nothing reads it: not the web UI (static/ and templates/), not the tests beyond the ones pinning the mapping itself, and not any plugin in ledmatrix-plugins. The enum, the inference table and the JSON key go. from_exception() could also guess an error code from the exception's class name ("Config" -> CONFIG_LOAD_FAILED, and so on). Every caller passes a code, so the guess never ran; error_code is now required. suggested_fixes stays: the error dialog in static/v3/js/utils/ error_handler.js lists them. The REST reference loses error_category and says what an unanticipated exception in an /api/v3 route answers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): one call for the from_exception error responses Nine plugin routes built a structured error by hand: from src.web_interface.errors import WebInterfaceError error = WebInterfaceError.from_exception(e, ErrorCode.X) return error_response(error.error_code, error.message, details=error.details, context=error.context, status_code=500) That is now exception_error_response(e, ErrorCode.X) in api_helpers, so error_response() is the only structured-error entry point the routes use. The three operation-history routes never passed the context, and with_context=False keeps their bodies exactly as they were; a test compares the helper against the hand-written pair for both forms. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(changelog): one api_v3 error-response path Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-04 14:25:08 +00:00 · 2026-09-24 15:53:19 -04:00
parent ece416c4e5
commit 4e61d7248a
17 changed files with 2437 additions and 2418 deletions
@@ -15,7 +15,7 @@ every api_v3 endpoint actually calls.
 import pytest
 from flask import Flask

-from src.web_interface.api_helpers import success_response
+from src.web_interface.api_helpers import exception_error_response, success_response
 from src.web_interface.error_handler import (
    create_error_response,
    create_success_response,
@@ -64,6 +64,59 @@ class TestCreateErrorResponse:
        assert response.get_json()["suggested_fixes"] == ["Try again"]


+class TestExceptionErrorResponse:
+    """The one-call form of from_exception() + error_response().
+
+    Nine plugin routes spelled the pair out by hand; these pin that the helper
+    answers exactly what that spelling did, so folding them changed nothing a
+    client sees.
+    """
+
+    @staticmethod
+    def _by_hand(exc, code, with_context):
+        from src.web_interface.api_helpers import error_response
+        error = WebInterfaceError.from_exception(exc, code)
+        if with_context:
+            return error_response(error.error_code, error.message,
+                                  details=error.details, context=error.context,
+                                  status_code=500)
+        return error_response(error.error_code, error.message,
+                              details=error.details, status_code=500)
+
+    @pytest.mark.parametrize("with_context", [True, False])
+    @pytest.mark.parametrize("code", [ErrorCode.SYSTEM_ERROR,
+                                      ErrorCode.CONFIG_SAVE_FAILED,
+                                      ErrorCode.PLUGIN_UPDATE_FAILED])
+    def test_same_answer_as_the_hand_written_pair(self, app, code, with_context):
+        exc = ValueError("token=SECRET boom")
+        exc.context = {"config_path": "/etc/x.json"}
+        with app.test_request_context():
+            got, got_status = exception_error_response(
+                exc, code, with_context=with_context)
+            want, want_status = self._by_hand(exc, code, with_context)
+        assert got_status == want_status == 500
+        assert got.get_json() == want.get_json()
+
+    def test_shape(self, app):
+        with app.test_request_context():
+            response, status = exception_error_response(
+                RuntimeError("token=SECRET"), ErrorCode.SYSTEM_ERROR)
+        assert status == 500
+        assert response.get_json() == {
+            "status": "error",
+            "error_code": "SYSTEM_ERROR",
+            "message": "A system error occurred",
+            "context": {"exception_type": "RuntimeError"},
+            "suggested_fixes": ["Review error details and try again"],
+        }
+
+    def test_without_context(self, app):
+        with app.test_request_context():
+            response, _ = exception_error_response(
+                RuntimeError("x"), ErrorCode.SYSTEM_ERROR, with_context=False)
+        assert "context" not in response.get_json()
+
+
 class TestCreateSuccessResponse:
    def test_bare_success(self):
        assert create_success_response() == {"status": "success"}