refactor: consolidate hostile-error attribute guards and quiet the precheck path

Share one guarded attribute reader between failure_category_of and
status_code_of, apply status_code_of at the UnstructuredIngestError site it
missed, compute the function signature once per request, and emit the
missing-usage-parameter warning once at wrap time instead of on every
request. Reuse existing test scaffolding instead of duplicating it.

Author: Nick Franck

test/api/test_api.py

@@ -1,4 +1,3 @@
-import enum
 from pathlib import Path
 from typing import Any, Optional, Union
 
@@ -623,12 +622,12 @@ def test_precheck_success_has_no_failure_category():
 
 
 def test_precheck_ignores_non_string_failure_category():
-    class _EnumCategoryFailure(Exception):
+    class _NonStringCategoryFailure(Exception):
         status_code = 403
-        failure_category = enum.Enum("Category", ["AUTH_PERMISSION_DENIED"]).AUTH_PERMISSION_DENIED
+        failure_category = 403
 
     def _enum_category_precheck() -> None:
-        raise _EnumCategoryFailure("credential rejected")
+        raise _NonStringCategoryFailure("credential rejected")
 
     client = TestClient(
         wrap_in_fastapi(
@@ -645,14 +644,7 @@ def _enum_category_precheck() -> None:
 
 
 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"))
+    client = TestClient(wrap_in_fastapi(func=_failing_precheck, plugin_id="mock_plugin"))
 
     body = client.post("/invoke").json()
     assert body["status_code"] == 403

unstructured_platform_plugins/etl_uvicorn/api_generator.py

@@ -62,31 +62,28 @@ def log_func_and_body(func: Callable, body: Optional[str] = None) -> None:
         logger.log(level=logger.level, msg=msg)
 
 
-def failure_category_of(error: BaseException) -> Optional[str]:
-    """Return the error's failure_category only when it is a plain string.
+def _error_attr(error: BaseException, name: str) -> Any:
+    """Read an attribute off a raised error, treating a raising property as absent.
 
-    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.
+    Runs while an exception handler is building the sanitized response; an
+    attribute access that itself raises must not replace that response with a
+    raw 500.
     """
     try:
-        category = getattr(error, "failure_category", None)
+        return getattr(error, name, None)
     except Exception:
         return None
+
+
+def failure_category_of(error: BaseException) -> Optional[str]:
+    """Return the error's failure_category only when it is a plain string."""
+    category = _error_attr(error, "failure_category")
     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
+    """Return the error's status_code only when it is a usable integer, else 500."""
+    status_code = _error_attr(error, "status_code")
     if isinstance(status_code, int) and not isinstance(status_code, bool):
         return status_code
     return status.HTTP_500_INTERNAL_SERVER_ERROR
@@ -168,6 +165,9 @@ def _wrap_in_fastapi(
 
     logger.debug(f"set static id response to: {plugin_id}")
 
+    if "usage" not in inspect.signature(func).parameters:
+        logger.warning("usage data not an expected parameter, omitting")
+
     fastapi_app = FastAPI()
 
     response_type = get_output_sig(func)
@@ -195,13 +195,12 @@ async def wrap_fn(func: Callable, kwargs: Optional[dict[str, Any]] = None) -> Re
         filedata_meta = FileDataMeta()
         message_channels = MessageChannels()
         request_dict = kwargs if kwargs else {}
-        if "usage" in inspect.signature(func).parameters:
+        params = inspect.signature(func).parameters
+        if "usage" in params:
             request_dict["usage"] = usage
-        else:
-            logger.warning("usage data not an expected parameter, omitting")
-        if "message_channels" in inspect.signature(func).parameters:
+        if "message_channels" in params:
             request_dict["message_channels"] = message_channels
-        if "filedata_meta" in inspect.signature(func).parameters:
+        if "filedata_meta" in params:
             request_dict["filedata_meta"] = filedata_meta
         try:
             if inspect.isasyncgenfunction(func):
@@ -273,7 +272,7 @@ async def _stream_response():
                 usage=usage,
                 message_channels=message_channels,
                 filedata_meta=filedata_meta_model.model_validate(filedata_meta.model_dump()),
-                status_code=exc.status_code or status.HTTP_500_INTERNAL_SERVER_ERROR,
+                status_code=status_code_of(exc),
                 status_code_text=str(exc),
                 failure_category=failure_category_of(exc),
                 file_data=request_dict.get("file_data", None),