fix: close remaining error-contract gaps in the invoke handlers

Clamp status_code_of to the HTTP status range (0 regressed to being served
verbatim instead of falling back to 500), read status_code through the
guarded accessor in the UnstructuredIngestError log line, and resolve
string/postponed annotations before validating precheck signatures.

Author: Nick Franck

test/api/test_api.py

@@ -719,3 +719,46 @@ def _bad_precheck(usage: int) -> None:
 
     with pytest.raises(EtlApiException):
         wrap_in_fastapi(func=_no_params, plugin_id="mock_plugin", precheck_func=_bad_precheck)
+
+
+def test_invoke_clamps_out_of_range_status_code():
+    class _ZeroStatusError(Exception):
+        status_code = 0
+
+    def _raising_func() -> None:
+        raise _ZeroStatusError("boom")
+
+    client = TestClient(wrap_in_fastapi(func=_raising_func, plugin_id="mock_plugin"))
+
+    assert client.post("/invoke").json()["status_code"] == 500
+
+
+def test_invoke_survives_ingest_error_with_raising_status_code():
+    from unstructured_ingest.error import UnstructuredIngestError
+
+    class _HostileIngestError(UnstructuredIngestError):
+        @property
+        def status_code(self) -> int:
+            raise RuntimeError("status_code exploded")
+
+    def _raising_func() -> None:
+        raise _HostileIngestError("boom")
+
+    client = TestClient(wrap_in_fastapi(func=_raising_func, plugin_id="mock_plugin"))
+
+    resp = client.post("/invoke")
+    assert resp.status_code == 200
+    assert resp.json()["status_code"] == 500
+
+
+def test_precheck_func_accepts_string_annotations():
+    def _string_annotated_precheck(usage: "list") -> "None":
+        return None
+
+    client = TestClient(
+        wrap_in_fastapi(
+            func=_no_params, plugin_id="mock_plugin", precheck_func=_string_annotated_precheck
+        )
+    )
+
+    assert client.get("/precheck").json()["status_code"] == 200

unstructured_platform_plugins/etl_uvicorn/api_generator.py

@@ -82,9 +82,13 @@ def failure_category_of(error: BaseException) -> Optional[str]:
 
 
 def status_code_of(error: BaseException) -> int:
-    """Return the error's status_code only when it is a usable integer, else 500."""
+    """Return the error's status_code only when it is an int in the HTTP range, else 500."""
     status_code = _error_attr(error, "status_code")
-    if isinstance(status_code, int) and not isinstance(status_code, bool):
+    if (
+        isinstance(status_code, int)
+        and not isinstance(status_code, bool)
+        and 100 <= status_code <= 599
+    ):
         return status_code
     return status.HTTP_500_INTERNAL_SERVER_ERROR
 
@@ -98,7 +102,11 @@ async def invoke_func(func: Callable, kwargs: Optional[dict[str, Any]] = None) -
 
 
 def check_precheck_func(precheck_func: Callable):
-    sig = inspect.signature(precheck_func)
+    try:
+        # eval_str resolves postponed/string annotations ('list', 'None')
+        sig = inspect.signature(precheck_func, eval_str=True)
+    except (NameError, TypeError):
+        sig = inspect.signature(precheck_func)
     inputs = list(sig.parameters.values())
     outputs = sig.return_annotation
     if len(inputs) == 1:
@@ -265,7 +273,8 @@ async def _stream_response():
             )
         except UnstructuredIngestError as exc:
             logger.error(
-                f"UnstructuredIngestError: {str(exc)} (status_code={exc.status_code})",
+                f"UnstructuredIngestError: {exc} "
+                f"(status_code={_error_attr(exc, 'status_code')})",
                 exc_info=True,
             )
             return InvokeResponse(
@@ -322,9 +331,7 @@ async def run_job_with_body(request: BaseModel) -> ResponseType:
 
         @fastapi_app.post("/invoke", response_model=InvokeResponse)
         async def run_job(request: Optional[input_schema_model] = None) -> ResponseType:
-            return await run_job_with_body(
-                request if request is not None else input_schema_model()
-            )
+            return await run_job_with_body(request if request is not None else input_schema_model())
 
     elif input_schema_model.model_fields: