feat: download - fase 01

webui/backend/app/api/routes_files.py

@@ -61,6 +61,19 @@ async def info(
     return service.info(path=path)
 
 
+@router.get("/download")
+async def download(
+    path: str,
+    service: FileOpsService = Depends(get_file_ops_service),
+) -> StreamingResponse:
+    prepared = service.prepare_download(path=path)
+    return StreamingResponse(
+        prepared["content"],
+        headers=prepared["headers"],
+        media_type=prepared["content_type"],
+    )
+
+
 @router.get("/video")
 async def video(
     path: str,

webui/backend/app/services/file_ops_service.py

@@ -353,6 +353,32 @@ class FileOpsService:
             height=metadata["height"],
         )
 
+    def prepare_download(self, path: str) -> dict:
+        resolved_target = self._path_guard.resolve_existing_path(path)
+
+        if resolved_target.absolute.is_dir():
+            raise AppError(
+                code="type_conflict",
+                message="Source must be a file",
+                status_code=409,
+                details={"path": resolved_target.relative},
+            )
+        if not resolved_target.absolute.is_file():
+            raise AppError(
+                code="type_conflict",
+                message="Unsupported path type for download",
+                status_code=409,
+                details={"path": resolved_target.relative},
+            )
+
+        return {
+            "content": self._filesystem.stream_file(resolved_target.absolute),
+            "headers": {
+                "Content-Disposition": f'attachment; filename="{resolved_target.absolute.name}"',
+            },
+            "content_type": self._content_type_for(resolved_target.absolute) or "application/octet-stream",
+        }
+
     def save(self, path: str, content: str, expected_modified: str) -> SaveResponse:
         resolved_target = self._path_guard.resolve_existing_path(path)
 

webui/backend/tests/golden/test_api_download_golden.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+import httpx
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from backend.app.dependencies import get_file_ops_service
+from backend.app.fs.filesystem_adapter import FilesystemAdapter
+from backend.app.main import app
+from backend.app.security.path_guard import PathGuard
+from backend.app.services.file_ops_service import FileOpsService
+
+
+class DownloadApiGoldenTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp_dir.name) / "root"
+        self.root.mkdir(parents=True, exist_ok=True)
+        path_guard = PathGuard({"storage1": str(self.root), "storage2": str(self.root)})
+        service = FileOpsService(path_guard=path_guard, filesystem=FilesystemAdapter())
+
+        async def _override_file_ops_service() -> FileOpsService:
+            return service
+
+        app.dependency_overrides[get_file_ops_service] = _override_file_ops_service
+
+    def tearDown(self) -> None:
+        app.dependency_overrides.clear()
+        self.temp_dir.cleanup()
+
+    def _get(self, url: str) -> httpx.Response:
+        async def _run() -> httpx.Response:
+            transport = httpx.ASGITransport(app=app)
+            async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+                return await client.get(url)
+
+        return asyncio.run(_run())
+
+    def test_download_success_for_allowed_file(self) -> None:
+        src = self.root / "report.txt"
+        src.write_text("hello download", encoding="utf-8")
+
+        response = self._get("/api/files/download?path=storage1/report.txt")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.content, b"hello download")
+        self.assertIn('attachment; filename="report.txt"', response.headers.get("content-disposition", ""))
+        self.assertEqual(response.headers.get("content-type"), "text/plain; charset=utf-8")
+
+    def test_download_directory_type_conflict(self) -> None:
+        (self.root / "docs").mkdir()
+
+        response = self._get("/api/files/download?path=storage1/docs")
+
+        self.assertEqual(response.status_code, 409)
+        self.assertEqual(response.json()["error"]["code"], "type_conflict")
+
+    def test_download_path_not_found(self) -> None:
+        response = self._get("/api/files/download?path=storage1/missing.txt")
+
+        self.assertEqual(response.status_code, 404)
+        self.assertEqual(response.json()["error"]["code"], "path_not_found")
+
+    def test_download_invalid_root_alias(self) -> None:
+        response = self._get("/api/files/download?path=unknown/file.txt")
+
+        self.assertEqual(response.status_code, 403)
+        self.assertEqual(response.json()["error"]["code"], "invalid_root_alias")
+
+    def test_download_traversal_blocked(self) -> None:
+        response = self._get("/api/files/download?path=storage1/../etc/passwd")
+
+        self.assertEqual(response.status_code, 403)
+        self.assertEqual(response.json()["error"]["code"], "path_traversal_detected")
+
+
+if __name__ == "__main__":
+    unittest.main()

webui/backend/tests/golden/test_ui_smoke_golden.py

@@ -73,6 +73,7 @@ class UiSmokeGoldenTest(unittest.TestCase):
         self.assertIn('id="context-menu-target"', body)
         self.assertIn('id="context-menu-open-btn"', body)
         self.assertIn('id="context-menu-edit-btn"', body)
+        self.assertIn('id="context-menu-download-btn"', body)
         self.assertIn('id="context-menu-rename-btn"', body)
         self.assertIn('id="context-menu-copy-btn"', body)
         self.assertIn('id="context-menu-move-btn"', body)
@@ -214,9 +215,11 @@ class UiSmokeGoldenTest(unittest.TestCase):
         self.assertIn('function openContextMenu(pane, entry, event)', app_js)
         self.assertIn('function closeContextMenu()', app_js)
         self.assertIn('function isOpenableSelection(item)', app_js)
+        self.assertIn('async function downloadFileRequest(path)', app_js)
         self.assertIn('function applyContextMenuSelection()', app_js)
         self.assertIn('function startContextMenuOpen()', app_js)
         self.assertIn('function startContextMenuEdit()', app_js)
+        self.assertIn('function startContextMenuDownload()', app_js)
         self.assertIn('function startContextMenuRename()', app_js)
         self.assertIn('function startContextMenuCopy()', app_js)
         self.assertIn('function startContextMenuMove()', app_js)
@@ -236,6 +239,9 @@ class UiSmokeGoldenTest(unittest.TestCase):
         self.assertIn('const editableSingle = items.length === 1 && isEditableSelection(items[0]);', app_js)
         self.assertIn('elements.editButton.classList.toggle("hidden", isMulti || items.length !== 1 || items[0].kind !== "file");', app_js)
         self.assertIn('elements.editButton.disabled = !editableSingle;', app_js)
+        self.assertIn('const downloadableSingle = items.length === 1 && items[0].kind === "file";', app_js)
+        self.assertIn('elements.downloadButton.classList.toggle("hidden", !downloadableSingle);', app_js)
+        self.assertIn('elements.downloadButton.disabled = !downloadableSingle;', app_js)
         self.assertIn('elements.renameButton.classList.toggle("hidden", isMulti);', app_js)
         self.assertIn('elements.copyButton.classList.remove("hidden");', app_js)
         self.assertIn('elements.copyButton.disabled = items.length === 0;', app_js)
@@ -244,6 +250,8 @@ class UiSmokeGoldenTest(unittest.TestCase):
         self.assertIn('elements.propertiesButton.disabled = items.length === 0;', app_js)
         self.assertIn('openCurrentDirectory();', app_js)
         self.assertIn('openEditor();', app_js)
+        self.assertIn('downloadFileRequest(selected.path);', app_js)
+        self.assertIn('anchor.download = selected.name;', app_js)
         self.assertIn('openRenamePopup();', app_js)
         self.assertIn('startCopySelected();', app_js)
         self.assertIn('openF6Flow();', app_js)