Handle CLI request errors and backend whisper timeout

Reviewed-on: #2

backend/src/server.py

@@ -17,6 +17,7 @@ CONTENT_TYPES = {
 }
 
 app = FastAPI(title="whisper-remote-backend")
+WHISPER_PROCESS_TIMEOUT_SECONDS = 300
 
 
 def validate_output_format(output_format: str) -> str:
@@ -112,12 +113,21 @@ async def transcribe(
                 check=False,
                 capture_output=True,
                 text=True,
+                timeout=WHISPER_PROCESS_TIMEOUT_SECONDS,
             )
         except FileNotFoundError as exc:
             raise HTTPException(
                 status_code=500,
                 detail="The 'whisper' CLI was not found on PATH on the backend host.",
             ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise HTTPException(
+                status_code=504,
+                detail=(
+                    "Whisper CLI timed out after "
+                    f"{WHISPER_PROCESS_TIMEOUT_SECONDS}s and was terminated."
+                ),
+            ) from exc
 
         if completed.returncode != 0:
             detail = completed.stderr.strip() or completed.stdout.strip() or "Whisper CLI failed."

backend/tests/test_server.py

@@ -64,3 +64,22 @@ def test_transcriptions_maps_subprocess_failure(monkeypatch) -> None:
 
     assert response.status_code == 502
     assert response.json()["detail"] == "bad whisper day"
+
+
+def test_transcriptions_maps_subprocess_timeout(monkeypatch) -> None:
+    def fake_run(command: list[str], check: bool, capture_output: bool, text: bool, timeout: int):
+        raise server.subprocess.TimeoutExpired(cmd=command, timeout=timeout)
+
+    monkeypatch.setattr(server.subprocess, "run", fake_run)
+
+    response = client.post(
+        "/transcriptions",
+        data={"model": "base", "output_format": "txt"},
+        files={"file": ("clip.wav", b"audio", "audio/wav")},
+    )
+
+    assert response.status_code == 504
+    assert (
+        response.json()["detail"]
+        == f"Whisper CLI timed out after {server.WHISPER_PROCESS_TIMEOUT_SECONDS}s and was terminated."
+    )

cli/src/main.py

@@ -59,6 +59,19 @@ def save_response(response: httpx.Response, destination: Path) -> None:
     destination.write_bytes(response.content)
 
 
+def format_http_error(response: httpx.Response, endpoint: str) -> str:
+    body = response.text.strip() or "<empty response body>"
+    return f"HTTP {response.status_code} from {endpoint}: {body}"
+
+
+def format_request_error(exc: httpx.RequestError, endpoint: str) -> str:
+    if isinstance(exc, httpx.TimeoutException):
+        return f"Request to {endpoint} timed out."
+
+    reason = str(exc).strip() or exc.__class__.__name__
+    return f"Request to {endpoint} failed: {reason}"
+
+
 def main() -> int:
     parser = build_parser()
     args = parser.parse_args()
@@ -70,21 +83,24 @@ def main() -> int:
     server = resolve_server(args)
     endpoint = f"{server}/transcriptions"
 
-    with input_file.open("rb") as handle, httpx.Client(timeout=300.0) as client:
+    try:
-        response = client.post(
+        with input_file.open("rb") as handle, httpx.Client(timeout=300.0) as client:
-            endpoint,
+            response = client.post(
-            data={
+                endpoint,
-                "model": args.model,
+                data={
-                "language": args.language or "",
+                    "model": args.model,
-                "output_format": args.output_format,
+                    "language": args.language or "",
-            },
+                    "output_format": args.output_format,
-            files={"file": (input_file.name, handle, "application/octet-stream")},
+                },
-        )
+                files={"file": (input_file.name, handle, "application/octet-stream")},
+            )
+    except httpx.RequestError as exc:
+        parser.exit(1, f"{format_request_error(exc, endpoint)}\n")
 
     try:
         response.raise_for_status()
     except httpx.HTTPStatusError as exc:
-        message = exc.response.text.strip() or str(exc)
+        message = format_http_error(exc.response, endpoint)
         parser.exit(1, f"{message}\n")
 
     if args.to_file:

cli/tests/test_main.py

@@ -8,6 +8,7 @@ import pytest
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 
 import main
+import httpx
 
 
 def test_resolve_server_from_env(monkeypatch) -> None:
@@ -29,3 +30,34 @@ def test_infer_output_path_for_directory(tmp_path: Path) -> None:
 def test_infer_output_path_for_explicit_file(tmp_path: Path) -> None:
     destination = main.infer_output_path(tmp_path / "custom-name.txt", Path("clip.wav"), "txt")
     assert destination == tmp_path / "custom-name.txt"
+
+
+def test_format_http_error_with_body() -> None:
+    request = httpx.Request("POST", "http://localhost:8000/transcriptions")
+    response = httpx.Response(500, text="Internal Server Error", request=request)
+    message = main.format_http_error(response, "http://localhost:8000/transcriptions")
+    assert message == "HTTP 500 from http://localhost:8000/transcriptions: Internal Server Error"
+
+
+def test_format_http_error_with_empty_body() -> None:
+    request = httpx.Request("POST", "http://localhost:8000/transcriptions")
+    response = httpx.Response(500, text="", request=request)
+    message = main.format_http_error(response, "http://localhost:8000/transcriptions")
+    assert message == "HTTP 500 from http://localhost:8000/transcriptions: <empty response body>"
+
+
+def test_format_request_error_timeout() -> None:
+    request = httpx.Request("POST", "http://localhost:8000/transcriptions")
+    exc = httpx.ReadTimeout("read timed out", request=request)
+    message = main.format_request_error(exc, "http://localhost:8000/transcriptions")
+    assert message == "Request to http://localhost:8000/transcriptions timed out."
+
+
+def test_format_request_error_network_failure() -> None:
+    request = httpx.Request("POST", "http://localhost:8000/transcriptions")
+    exc = httpx.ConnectError("connection refused", request=request)
+    message = main.format_request_error(exc, "http://localhost:8000/transcriptions")
+    assert (
+        message
+        == "Request to http://localhost:8000/transcriptions failed: connection refused"
+    )