Show live progress while pruning images (0.61.0)

docker image prune is a single blocking call that reports nothing until it
is done. With -a on a host with many images that meant minutes of a
spinner, and past the proxy timeout an error while the daemon carried on.

The prune now removes its candidates one by one and publishes how far it
is. The candidates are the ones Docker would pick: dangling only by
default, with -a every image no container (running or stopped) uses. The
UI starts the prune in the background (POST /api/images/prune?background=
true, 202) and polls GET /api/images/prune-status. A progress bar above
the image table shows x / y, the image being removed and any failures,
and a toast reports the outcome. It survives a reload and shows up in a
second tab.

- Multi-tag images lose their tags one by one instead of force=True, so a
  container created since the listing still makes the daemon refuse.
- One refused image does not stop the rest; up to ten errors are kept.
- Docker's own prune runs last to sweep up leftovers.
- Freed space is measured (image LayersSize before and after) rather than
  summed, which would count base layers shared with the images that stay.
- Without background=true the endpoint still waits and returns the old
  {ImagesDeleted, SpaceReclaimed} shape, so API-token scripts are
  unaffected. A second prune while one runs gets 409.
- The audit entry now counts deleted images, not Docker's untag entries.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

backend/routers/images.py

@@ -3,11 +3,11 @@ from __future__ import annotations
 
 import json
 
-from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
 from sqlmodel import Session
 
 from auth import get_current_user, require_admin
-from database import get_session
+from database import engine, get_session
 from models.image_scan import ImageScan, ScanDetail, ScanRequest, ScanSummary
 from models.user import User
 from services import audit_service, image_service, scan_service, update_service
@@ -37,19 +37,50 @@ async def check(_user: User = Depends(require_admin)) -> dict:
 @router.post("/prune")
 def prune(
     request: Request,
+    response: Response,
     all_unused: bool = Query(False, alias="all"),
-    session: Session = Depends(get_session),
+    background: bool = Query(False),
     user: User = Depends(require_admin),
 ) -> dict:
-    result = image_service.prune_images(all_unused)
-    audit_service.record(
-        session, user=user.username, action="image.prune", target="*",
-        detail=f"all={all_unused} reclaimed={result.get('SpaceReclaimed')}",
-        ip=_ip(request),
-    )
+    """Remove unused images (``all=true``: also unused tagged ones, ``-a``).
+
+    Waits for the result by default. ``background=true`` returns 202 with the
+    initial status at once and leaves the caller to poll /prune-status, which
+    is what the UI does: a large prune can outlast the proxy's read timeout.
+    """
+    username, ip = user.username, _ip(request)
+
+    def audit(result: dict) -> None:
+        # Docker lists every untagging too; only "Deleted" entries are images.
+        deleted = sum(1 for entry in result["ImagesDeleted"] if "Deleted" in entry)
+        # Its own session: in the background case the request's is long closed.
+        with Session(engine) as own:
+            audit_service.record(
+                own, user=username, action="image.prune", target="*",
+                detail=(
+                    f"all={all_unused} deleted={deleted} "
+                    f"reclaimed={result['SpaceReclaimed']}"
+                ),
+                ip=ip,
+            )
+
+    try:
+        if background:
+            response.status_code = 202
+            return image_service.start_prune(all_unused, on_done=audit)
+        result = image_service.prune_images(all_unused)
+    except image_service.PruneBusy as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    audit(result)
     return result
 
 
+@router.get("/prune-status")
+def prune_status(_admin: User = Depends(require_admin)) -> dict:
+    """Progress of a running (or the last) prune. Admin-only like the prune."""
+    return image_service.prune_status()
+
+
 # --------------------------------------------------------------------------- #
 # Vulnerability scanning
 # --------------------------------------------------------------------------- #