feat: add timeout parameter to Python API functions (#597)

#### Relevant issue or PR

n/a

#### Description of changes

In pathological cases, HTTP requests can hang forever (e.g. when a
container runs out of memory or just hangs indefinitely). This is hard
to detect and work around if it happens deep within a call stack. This
PR introduces a `timeout` parameter to `Tesseract.from_url` and
`Tesseract.from_image` so users can at least fail gracefully if requests
hang.

#### Testing done

CI

Author: dionhaefner

tesseract_core/sdk/tesseract.py

@@ -59,19 +59,28 @@ class Tesseract:
     _lastlog: str | None = None
     _client: HTTPClient | LocalClient | None = None
     _stream_logs: BoolOrCallable = False
+    _timeout: float | tuple[float, float] | None = None
 
-    def __init__(self, url: str, server_output_path: str | Path | None = None) -> None:
+    def __init__(
+        self,
+        url: str,
+        server_output_path: str | Path | None = None,
+        timeout: float | tuple[float, float] | None = None,
+    ) -> None:
         warnings.warn(
             "Direct instantiation of Tesseract is deprecated. "
             "Use Tesseract.from_url(), Tesseract.from_image(), or Tesseract.from_tesseract_api() instead.",
             UserWarning,
             stacklevel=2,
         )
-        self._client = HTTPClient(url, output_path=server_output_path)
+        self._client = HTTPClient(url, output_path=server_output_path, timeout=timeout)
 
     @classmethod
     def from_url(
-        cls, url: str, server_output_path: str | Path | None = None
+        cls,
+        url: str,
+        server_output_path: str | Path | None = None,
+        timeout: float | tuple[float, float] | None = None,
     ) -> Tesseract:
         """Create a Tesseract instance from a URL.
 
@@ -84,12 +93,17 @@ def from_url(
                 Must be a path accessible from the client machine (e.g., via a shared or
                 mounted filesystem), since the server writes .bin files there and the
                 client reads them from the same path.
+            timeout: Request timeout in seconds. Can be a float for both connect and
+                read timeouts, or a ``(connect, read)`` tuple for separate control.
+                ``None`` (the default) disables timeouts. See the `requests documentation
+                <https://requests.readthedocs.io/en/latest/user/advanced/#timeouts>`_
+                for details.
 
         Returns:
             A Tesseract instance.
         """
         obj = cls.__new__(cls)
-        obj._client = HTTPClient(url, output_path=server_output_path)
+        obj._client = HTTPClient(url, output_path=server_output_path, timeout=timeout)
         return obj
 
     @classmethod
@@ -113,6 +127,7 @@ def from_image(
         docker_args: list[str] | None = None,
         runtime_config: dict[str, Any] | None = None,
         stream_logs: BoolOrCallable = False,
+        timeout: float | tuple[float, float] | None = None,
     ) -> Tesseract:
         """Create a Tesseract instance from a Docker image.
 
@@ -151,6 +166,12 @@ def from_image(
                 `{"profiling": True}` enables profiling via TESSERACT_PROFILING=true.
             stream_logs: If True, stream logs to stdout while endpoints run.
                 If a callable, stream logs to that callable instead.
+            timeout: Request timeout in seconds for HTTP calls to the Tesseract.
+                Can be a float for both connect and read timeouts, or a
+                ``(connect, read)`` tuple for separate control. ``None`` (the default)
+                disables timeouts. See the `requests documentation
+                <https://requests.readthedocs.io/en/latest/user/advanced/#timeouts>`_
+                for details.
 
         Returns:
             A Tesseract instance.
@@ -171,6 +192,7 @@ def from_image(
             output_path = Path(tempfile.mkdtemp(prefix="tesseract_output_"))
 
         obj._stream_logs = stream_logs
+        obj._timeout = timeout
         obj._spawn_config = dict(
             image_name=image_name,
             volumes=volumes,
@@ -321,6 +343,7 @@ def serve(self) -> None:
         self._client = HTTPClient(
             f"http://{host_ip}:{container.host_port}",
             output_path=Path(output_path) if output_path else None,
+            timeout=self._timeout,
         )
 
         # Ensure that the Tesseract is torn down once the object is garbage collected,
@@ -666,9 +689,15 @@ def _decode_array(
 class HTTPClient:
     """HTTP Client for Tesseracts."""
 
-    def __init__(self, url: str, output_path: str | Path | None = None) -> None:
+    def __init__(
+        self,
+        url: str,
+        output_path: str | Path | None = None,
+        timeout: float | tuple[float, float] | None = None,
+    ) -> None:
         self._url = self._sanitize_url(url)
         self._output_path = output_path
+        self._timeout = timeout
         self._session = requests.Session()
         self._session.headers["Content-Type"] = "application/json"
 
@@ -709,15 +738,15 @@ def _request(
         data = orjson.dumps(encoded_payload)
         try:
             response = self._session.request(
-                method=method, url=url, data=data, params=params
+                method=method, url=url, data=data, params=params, timeout=self._timeout
             )
         except requests.ConnectionError:
             # Retry once on stale keep-alive connections. There is a race
             # between urllib3's is_connection_dropped check and the server
             # closing idle connections (uvicorn timeout_keep_alive) that
             # can cause ConnectionError on an otherwise healthy server.
             response = self._session.request(
-                method=method, url=url, data=data, params=params
+                method=method, url=url, data=data, params=params, timeout=self._timeout
             )
 
         if response.status_code == requests.codes.unprocessable_entity:

tests/endtoend_tests/test_tesseract_sdk.py

@@ -214,6 +214,8 @@ def test_signature_consistency():
         "output_format",
         # stream_logs is SDK-only for streaming logs to a callback
         "stream_logs",
+        # timeout is a client-side HTTP parameter, not relevant for serve
+        "timeout",
     ]
 
     from_image_sig = dict(inspect.signature(Tesseract.from_image).parameters)

tests/sdk_tests/test_tesseract.py

@@ -200,9 +200,70 @@ def test_HTTPClient_run_tesseract(mocker, run_id):
         url="http://somehost/apply",
         data=orjson.dumps({"inputs": {"a": 1}}),
         params=expected_params,
+        timeout=None,
     )
 
 
+def test_HTTPClient_timeout_passed_to_request(mocker):
+    """HTTPClient passes its timeout to every requests.Session.request call."""
+    mock_response = mocker.Mock()
+    mock_response.content = b'{"status": "ok"}'
+    mock_response.ok = True
+    mock_response.status_code = 200
+
+    mocked_request = mocker.patch(
+        "requests.Session.request",
+        return_value=mock_response,
+    )
+
+    client = HTTPClient("somehost", timeout=42)
+    client.run_tesseract("health")
+
+    mocked_request.assert_called_with(
+        method="GET",
+        url="http://somehost/health",
+        data=b"null",
+        params={},
+        timeout=42,
+    )
+
+
+def test_HTTPClient_default_timeout(mocker):
+    """HTTPClient has no timeout by default."""
+    mock_response = mocker.Mock()
+    mock_response.content = b'{"status": "ok"}'
+    mock_response.ok = True
+    mock_response.status_code = 200
+
+    mocked_request = mocker.patch(
+        "requests.Session.request",
+        return_value=mock_response,
+    )
+
+    client = HTTPClient("somehost")
+    client.run_tesseract("health")
+
+    assert mocked_request.call_args.kwargs["timeout"] is None
+
+
+def test_HTTPClient_timeout_tuple(mocker):
+    """HTTPClient accepts a (connect, read) timeout tuple."""
+    mock_response = mocker.Mock()
+    mock_response.content = b'{"status": "ok"}'
+    mock_response.ok = True
+    mock_response.status_code = 200
+
+    mocked_request = mocker.patch(
+        "requests.Session.request",
+        return_value=mock_response,
+    )
+
+    client = HTTPClient("somehost", timeout=(5, 300))
+    client.run_tesseract("health")
+
+    assert mocked_request.call_args.kwargs["timeout"] == (5, 300)
+
+
 def test_HTTPClient_run_tesseract_raises_validation_error(mocker):
     error_detail = {
         "detail": [
@@ -632,3 +693,33 @@ def _lie_once(self):
     finally:
         server.should_exit = True
         server_thread.join(timeout=5)
+
+
+def test_HTTPClient_timeout_fires(free_port):
+    """HTTPClient raises a timeout error when the server takes too long to respond."""
+    import http.server
+    import socketserver
+    import threading
+
+    shutdown = threading.Event()
+
+    class SlowHandler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):
+            shutdown.wait(timeout=10)
+
+        def log_message(self, *args):
+            pass  # suppress stderr noise
+
+    httpd = socketserver.TCPServer(("127.0.0.1", free_port), SlowHandler)
+    httpd.daemon_threads = True
+    server_thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+    server_thread.start()
+
+    try:
+        client = HTTPClient(f"http://127.0.0.1:{free_port}", timeout=0.5)
+        with pytest.raises(requests.exceptions.ReadTimeout):
+            client._request("health")
+    finally:
+        shutdown.set()
+        httpd.shutdown()
+        server_thread.join(timeout=5)