Handle CLI request errors and backend whisper timeout

Reviewed-on: #2

AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md
+
+This repository contains two Python packages:
+
+- `backend/`: a FastAPI wrapper around the upstream `whisper` CLI
+- `cli/`: a local `whisper-remote` command that forwards transcription jobs to the backend
+
+## Working rules
+
+- Keep changes focused and scoped to the request.
+- Prefer small, verifiable edits over broad refactors.
+- When behavior changes, update tests or add coverage in the same change.
+- If a change touches the request/response contract, verify both `backend/` and `cli/` paths.
+
+## Local commands
+
+Backend:
+
+```bash
+cd backend
+python -m pip install -e .[dev]
+python -m pytest
+python -m build
+uvicorn server:app --app-dir src --host 0.0.0.0 --port 8000
+```
+
+CLI:
+
+```bash
+cd cli
+python -m pip install -e .[dev]
+python -m pytest
+python -m build
+```
+
+## Delivery policy
+
+- All new pushes must go through a pull request.
+- Do not push directly to `main`.
+- Open a PR, wait for CI to pass, and merge through the review flow.
+- If a change is ready, create a branch commit and hand it off via PR instead of bypassing review.
+
+## Notes for future agents
+
+- The repo uses Gitea Actions for CI in `.gitea/workflows/ci.yml`.
+- The backend package requires the upstream `whisper` CLI to already be available on `PATH` for runtime use.
+- On Windows, PowerShell examples are preferred when documenting local setup.

README.md

@@ -9,8 +9,17 @@ Two separate Python packages live here:
 
 The repo also includes a Gitea Actions workflow at `.gitea/workflows/ci.yml` that tests and builds both packages on pushes to `main` and pull requests.
 
-## Backend setup
+## Docker backend (no image build)
 
+Run the backend directly from an official Python image without creating a Dockerfile:
+
+```bash
+docker compose up backend
+```
+
+This uses `python:3.14-slim`, installs `ffmpeg` and `openai-whisper` at container startup, mounts this repo into the container, and serves the API on `http://localhost:8000`.
+
+## Backend setup
 ```bash
 cd backend
 pip install -e .
@@ -50,3 +59,4 @@ whisper-remote ./audio.mp3 --model base --language en --output-format txt
 - backend-side cleanup of uploaded and generated files after each request
 
 By default the CLI prints the returned transcript to stdout. Use `--to-file` to save it locally.
+

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"
+    )

docker-compose.yml

@@ -0,0 +1,22 @@
+services:
+  backend:
+    image: python:3.14-slim
+    working_dir: /app/backend
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./:/app
+      - whisper_cache:/root/.cache
+    environment:
+      - PYTHONUNBUFFERED=1
+    command: >-
+      sh -lc "
+      apt-get update
+      && apt-get install -y --no-install-recommends ffmpeg
+      && rm -rf /var/lib/apt/lists/*
+      && pip install --no-cache-dir -e . openai-whisper
+      && uvicorn server:app --app-dir src --host 0.0.0.0 --port 8000
+      "
+
+volumes:
+  whisper_cache: