fix: keep error responses well-formed under hostile error attributes

Guard failure_category and status_code pickup against raising descriptors
and non-int values, serialize non-string HTTPException details, and repair
the inverted single-parameter validation in check_precheck_func.

Author: Nick Franck

test/api/test_api.py

@@ -642,3 +642,88 @@ def _enum_category_precheck() -> None:
     assert body["status_code"] == 403
     assert body["failure_category"] is None
     assert "credential rejected" in body["status_code_text"]
+
+
+def test_invoke_reports_failure_category_from_raised_error():
+    class _CategorizedError(Exception):
+        status_code = 403
+        failure_category = "AUTH_PERMISSION_DENIED"
+
+    def _raising_func() -> None:
+        raise _CategorizedError("credential rejected")
+
+    client = TestClient(wrap_in_fastapi(func=_raising_func, plugin_id="mock_plugin"))
+
+    body = client.post("/invoke").json()
+    assert body["status_code"] == 403
+    assert body["failure_category"] == "AUTH_PERMISSION_DENIED"
+
+
+def test_invoke_sanitizes_raising_error_attributes():
+    class _HostileError(Exception):
+        @property
+        def status_code(self) -> int:
+            raise RuntimeError("status_code exploded")
+
+        @property
+        def failure_category(self) -> str:
+            raise RuntimeError("failure_category exploded")
+
+    def _raising_func() -> None:
+        raise _HostileError("original message")
+
+    client = TestClient(wrap_in_fastapi(func=_raising_func, plugin_id="mock_plugin"))
+
+    resp = client.post("/invoke")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["status_code"] == 500
+    assert body["failure_category"] is None
+    assert "original message" in body["status_code_text"]
+
+
+def test_invoke_ignores_non_integer_status_code():
+    class _BadStatusError(Exception):
+        status_code = "not-a-code"
+
+    def _raising_func() -> None:
+        raise _BadStatusError("boom")
+
+    client = TestClient(wrap_in_fastapi(func=_raising_func, plugin_id="mock_plugin"))
+
+    body = client.post("/invoke").json()
+    assert body["status_code"] == 500
+
+
+def test_invoke_serializes_non_string_http_exception_detail():
+    from fastapi import HTTPException
+
+    def _raising_func() -> None:
+        raise HTTPException(status_code=422, detail=["field a", "field b"])
+
+    client = TestClient(wrap_in_fastapi(func=_raising_func, plugin_id="mock_plugin"))
+
+    body = client.post("/invoke").json()
+    assert body["status_code"] == 422
+    assert body["status_code_text"] == '["field a", "field b"]'
+
+
+def test_precheck_func_may_take_a_usage_list_parameter():
+    def _usage_precheck(usage: list) -> None:
+        return None
+
+    client = TestClient(
+        wrap_in_fastapi(func=_no_params, plugin_id="mock_plugin", precheck_func=_usage_precheck)
+    )
+
+    assert client.get("/precheck").json()["status_code"] == 200
+
+
+def test_precheck_func_with_non_list_usage_parameter_is_rejected():
+    from unstructured_platform_plugins.etl_uvicorn.api_generator import EtlApiException
+
+    def _bad_precheck(usage: int) -> None:
+        return None
+
+    with pytest.raises(EtlApiException):
+        wrap_in_fastapi(func=_no_params, plugin_id="mock_plugin", precheck_func=_bad_precheck)

unstructured_platform_plugins/etl_uvicorn/api_generator.py

@@ -4,7 +4,7 @@
 import json
 import logging
 from functools import partial
-from typing import Any, Callable, Optional, Union
+from typing import Any, Callable, Optional, Union, get_origin
 
 from fastapi import FastAPI, HTTPException, status
 from fastapi.responses import StreamingResponse
@@ -65,13 +65,33 @@ def log_func_and_body(func: Callable, body: Optional[str] = None) -> None:
 def failure_category_of(error: BaseException) -> Optional[str]:
     """Return the error's failure_category only when it is a plain string.
 
-    Any other value would fail response-model validation inside an exception
-    handler, replacing the sanitized error body with a raw 500.
+    Runs while an exception handler is building the sanitized response, so a
+    non-string value — or an attribute access that itself raises — is treated
+    as absent rather than allowed to replace that response with a raw 500.
     """
-    category = getattr(error, "failure_category", None)
+    try:
+        category = getattr(error, "failure_category", None)
+    except Exception:
+        return None
     return category if isinstance(category, str) else None
 
 
+def status_code_of(error: BaseException) -> int:
+    """Return the error's status_code only when it is a usable integer.
+
+    Same contract as failure_category_of: runs inside exception handlers, so
+    anything other than a plain int falls back to 500 instead of failing
+    response-model validation.
+    """
+    try:
+        status_code = getattr(error, "status_code", None)
+    except Exception:
+        return status.HTTP_500_INTERNAL_SERVER_ERROR
+    if isinstance(status_code, int) and not isinstance(status_code, bool):
+        return status_code
+    return status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
 async def invoke_func(func: Callable, kwargs: Optional[dict[str, Any]] = None) -> Any:
     kwargs = kwargs or {}
     if inspect.iscoroutinefunction(func):
@@ -82,11 +102,14 @@ async def invoke_func(func: Callable, kwargs: Optional[dict[str, Any]] = None) -
 
 def check_precheck_func(precheck_func: Callable):
     sig = inspect.signature(precheck_func)
-    inputs = sig.parameters.values()
+    inputs = list(sig.parameters.values())
     outputs = sig.return_annotation
     if len(inputs) == 1:
         i = inputs[0]
-        if i.name != "usage" or i.annotation is list:
+        annotation_is_list = (
+            i.annotation is sig.empty or i.annotation is list or get_origin(i.annotation) is list
+        )
+        if i.name != "usage" or not annotation_is_list:
             raise ValueError("the only input available for precheck is usage which must be a list")
     if outputs not in [None, sig.empty]:
         raise ValueError(f"no output should exist for precheck function, found: {outputs}")
@@ -208,8 +231,7 @@ async def _stream_response():
                                 filedata_meta=filedata_meta_model.model_validate(
                                     filedata_meta.model_dump()
                                 ),
-                                status_code=getattr(e, "status_code", None)
-                                or status.HTTP_500_INTERNAL_SERVER_ERROR,
+                                status_code=status_code_of(e),
                                 status_code_text=f"[{e.__class__.__name__}] {e}",
                                 failure_category=failure_category_of(e),
                             ).model_dump_json()
@@ -236,9 +258,9 @@ async def _stream_response():
                 message_channels=message_channels,
                 filedata_meta=filedata_meta_model.model_validate(filedata_meta.model_dump()),
                 status_code=exc.status_code,
-                status_code_text=json.dumps(exc.detail)
-                if isinstance(exc.detail, dict)
-                else exc.detail,
+                status_code_text=exc.detail
+                if isinstance(exc.detail, str)
+                else json.dumps(exc.detail, default=str),
                 failure_category=failure_category_of(exc),
                 file_data=request_dict.get("file_data", None),
             )
@@ -262,8 +284,7 @@ async def _stream_response():
                 usage=usage,
                 message_channels=message_channels,
                 filedata_meta=filedata_meta_model.model_validate(filedata_meta.model_dump()),
-                status_code=getattr(invoke_error, "status_code", None)
-                or status.HTTP_500_INTERNAL_SERVER_ERROR,
+                status_code=status_code_of(invoke_error),
                 status_code_text=f"[{invoke_error.__class__.__name__}] {invoke_error}",
                 failure_category=failure_category_of(invoke_error),
                 file_data=request_dict.get("file_data", None),