feat: improve the file browser with pagination.

Author: arabcoders

API.md

@@ -1576,6 +1576,13 @@ Binary image data with the appropriate `Content-Type`.
 **Path Parameter**:
 - `path` = Relative path within the download directory (URL-encoded).
 
+**Query Parameters**:
+- `page` (optional): Page number (1-indexed). Default: `1`.
+- `per_page` (optional): Items per page. Default: `config.default_pagination`, Max: `1000`.
+- `sort_by` (optional): Sort field. Options: `name`, `size`, `date`, `type`. Default: `name`.
+- `sort_order` (optional): Sort direction. Options: `asc`, `desc`. Default: `asc`.
+- `search` (optional): Filter by filename (case-insensitive).
+
 **Response**:
 ```json
 {
@@ -1587,12 +1594,12 @@ Binary image data with the appropriate `Content-Type`.
       "name": "filename.mp4",
       "path": "/filename.mp4",
       "size": 123456789,
-      "mimetype": "mime/type",
+      "mime": "mime/type",
       "mtime": "2023-01-01T12:00:00Z",
       "ctime": "2023-01-01T12:00:00Z",
       "is_dir": true|false,
       "is_file": true|false,
-      ...
+      "is_symlink": true|false
     },
     {
       "type": "dir",
@@ -1601,11 +1608,36 @@ Binary image data with the appropriate `Content-Type`.
       "path": "/Season 2025",
       ...
     }
-  ]
+  ],
+  "pagination": {
+    "page": 1,
+    "per_page": 50,
+    "total": 123,
+    "total_pages": 3,
+    "has_next": true,
+    "has_prev": false
+  }
 }
 ```
+
+**Examples**:
+```bash
+# Get first page of root directory
+GET /api/file/browser/
+
+# Get second page of videos folder, sorted by size descending
+GET /api/file/browser/videos?page=2&sort_by=size&sort_order=desc
+
+# Search for mp4 files
+GET /api/file/browser/videos?search=mp4
+
+# Sort by date, newest first
+GET /api/file/browser/videos?sort_by=date&sort_order=desc
+```
+
 - Returns `403 Forbidden` if file browser is disabled.
 - Returns `404 Not Found` if the path doesn't exist.
+- Returns `400 Bad Request` if the path is not a directory.
 
 ---
 

app/library/Utils.py

@@ -814,16 +814,29 @@ def get(
     return data
 
 
-def get_files(base_path: Path | str, dir: str | None = None):
+def get_files(
+    base_path: Path | str,
+    dir: str | None = None,
+    page: int = 1,
+    per_page: int = 0,
+    sort_by: str = "name",
+    sort_order: str = "asc",
+    search: str | None = None,
+) -> tuple[list, int]:
     """
-    Get directory contents.
+    Get directory contents with optional pagination, sorting, and search.
 
     Args:
         base_path (Path|str): Base download path.
         dir (str): Directory to check.
+        page (int): Page number (1-indexed). Ignored if per_page is 0.
+        per_page (int): Items per page. If 0, returns all items.
+        sort_by (str): Sort field: name, size, date, type.
+        sort_order (str): Sort direction: asc, desc.
+        search (str|None): Filter by filename (case-insensitive).
 
     Returns:
-        list: List of files and directories.
+        tuple[list, int]: List of file/directory dicts and total count (before pagination).
 
     Raises:
         OSError: If the directory is invalid or not a directory.
@@ -909,7 +922,26 @@ def get_files(base_path: Path | str, dir: str | None = None):
             }
         )
 
-    return contents
+    total: int = len(contents)
+
+    if search:
+        search_lower: str = search.lower()
+        contents = [c for c in contents if search_lower in c["name"].lower()]
+
+    if sort_by == "name":
+        contents.sort(key=lambda x: x["name"].lower(), reverse=(sort_order.lower() == "desc"))
+    elif sort_by == "size":
+        contents.sort(key=lambda x: x["size"], reverse=(sort_order.lower() == "desc"))
+    elif sort_by == "date":
+        contents.sort(key=lambda x: x["mtime"], reverse=(sort_order.lower() == "desc"))
+    elif sort_by == "type":
+        contents.sort(key=lambda x: x["content_type"], reverse=(sort_order.lower() == "desc"))
+
+    if per_page > 0:
+        offset: int = (page - 1) * per_page
+        contents = contents[offset : offset + per_page]
+
+    return contents, total
 
 
 def clean_item(item: dict, keys: list | tuple) -> tuple[dict, bool]:

app/routes/api/browser.py

@@ -7,6 +7,7 @@
 from aiohttp import web
 from aiohttp.web import Request, Response
 
+from app.features.core.utils import build_pagination, normalize_pagination
 from app.features.streaming.library.ffprobe import ffprobe
 from app.library.cache import Cache
 from app.library.config import Config
@@ -134,16 +135,15 @@ async def file_browser(request: Request, config: Config, encoder: Encoder) -> Re
     req_path: str = request.match_info.get("path")
     req_path: str = "/" if not req_path else unquote_plus(req_path)
 
-    # Normalize requested path to always be inside download root.
     raw_req: str = (req_path or "").strip()
     root_dir: Path = Path(config.download_path).resolve()
     if raw_req in ("", "/"):
         test: Path = root_dir
-        rel_for_listing = "/"
+        rel_for_listing: str = "/"
     else:
         # Strip leading slash so joinpath doesn't ignore the base path.
         test = root_dir.joinpath(raw_req.lstrip("/")).resolve(strict=False)
-        rel_for_listing = raw_req.lstrip("/")
+        rel_for_listing: str = raw_req.lstrip("/")
 
     try:
         test.relative_to(root_dir)
@@ -163,10 +163,34 @@ async def file_browser(request: Request, config: Config, encoder: Encoder) -> Re
         )
 
     try:
+        page, per_page = normalize_pagination(request)
+        sort_by: str = request.query.get("sort_by", "name")
+        sort_order: str = request.query.get("sort_order", "asc")
+        search: str | None = request.query.get("search")
+
+        if sort_by not in ("name", "size", "date", "type"):
+            sort_by = "name"
+
+        if sort_order not in ("asc", "desc"):
+            sort_order = "asc"
+
+        contents, total = get_files(
+            base_path=root_dir,
+            dir=rel_for_listing,
+            page=page,
+            per_page=per_page,
+            sort_by=sort_by,
+            sort_order=sort_order,
+            search=search,
+        )
+
+        total_pages: int = (total + per_page - 1) // per_page if total > 0 else 1
+
         return web.json_response(
             data={
                 "path": rel_for_listing,
-                "contents": get_files(base_path=root_dir, dir=rel_for_listing),
+                "contents": contents,
+                "pagination": build_pagination(total, page, per_page, total_pages),
             },
             status=web.HTTPOk.status_code,
             dumps=encoder.encode,

app/tests/test_utils.py

@@ -1488,13 +1488,13 @@ def teardown_method(self):
 
     def test_get_files_root(self):
         """Test getting files from root directory."""
-        result = get_files(self.base_path)
+        result, total = get_files(self.base_path)
         assert isinstance(result, list)
         assert len(result) > 0
 
     def test_get_files_subdir(self):
         """Test getting files from subdirectory."""
-        result = get_files(self.base_path, "subdir")
+        result, total = get_files(self.base_path, "subdir")
         assert isinstance(result, list)