132 lines
5.2 KiB
Python
132 lines
5.2 KiB
Python
# [DEF:storage_routes:Module]
|
|
#
|
|
# @SEMANTICS: storage, files, upload, download, backup, repository
|
|
# @PURPOSE: API endpoints for file storage management (backups and repositories).
|
|
# @LAYER: API
|
|
# @RELATION: DEPENDS_ON -> backend.src.models.storage
|
|
#
|
|
# @INVARIANT: All paths must be validated against path traversal.
|
|
|
|
# [SECTION: IMPORTS]
|
|
from fastapi import APIRouter, Depends, UploadFile, File, Form, HTTPException
|
|
from fastapi.responses import FileResponse
|
|
from typing import List, Optional
|
|
from ...models.storage import StoredFile, FileCategory
|
|
from ...dependencies import get_plugin_loader
|
|
from ...plugins.storage.plugin import StoragePlugin
|
|
from ...core.logger import belief_scope
|
|
# [/SECTION]
|
|
|
|
router = APIRouter(tags=["storage"])
|
|
|
|
# [DEF:list_files:Function]
|
|
# @PURPOSE: List all files and directories in the storage system.
|
|
#
|
|
# @PRE: None.
|
|
# @POST: Returns a list of StoredFile objects.
|
|
#
|
|
# @PARAM: category (Optional[FileCategory]) - Filter by category.
|
|
# @PARAM: path (Optional[str]) - Subpath within the category.
|
|
# @RETURN: List[StoredFile] - List of files/directories.
|
|
#
|
|
# @RELATION: CALLS -> StoragePlugin.list_files
|
|
@router.get("/files", response_model=List[StoredFile])
|
|
async def list_files(
|
|
category: Optional[FileCategory] = None,
|
|
path: Optional[str] = None,
|
|
plugin_loader=Depends(get_plugin_loader)
|
|
):
|
|
with belief_scope("list_files"):
|
|
storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
|
|
if not storage_plugin:
|
|
raise HTTPException(status_code=500, detail="Storage plugin not loaded")
|
|
return storage_plugin.list_files(category, path)
|
|
# [/DEF:list_files:Function]
|
|
|
|
# [DEF:upload_file:Function]
|
|
# @PURPOSE: Upload a file to the storage system.
|
|
#
|
|
# @PRE: category must be a valid FileCategory.
|
|
# @PRE: file must be a valid UploadFile.
|
|
# @POST: Returns the StoredFile object of the uploaded file.
|
|
#
|
|
# @PARAM: category (FileCategory) - Target category.
|
|
# @PARAM: path (Optional[str]) - Target subpath.
|
|
# @PARAM: file (UploadFile) - The file content.
|
|
# @RETURN: StoredFile - Metadata of the uploaded file.
|
|
#
|
|
# @SIDE_EFFECT: Writes file to the filesystem.
|
|
#
|
|
# @RELATION: CALLS -> StoragePlugin.save_file
|
|
@router.post("/upload", response_model=StoredFile, status_code=201)
|
|
async def upload_file(
|
|
category: FileCategory = Form(...),
|
|
path: Optional[str] = Form(None),
|
|
file: UploadFile = File(...),
|
|
plugin_loader=Depends(get_plugin_loader)
|
|
):
|
|
with belief_scope("upload_file"):
|
|
storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
|
|
if not storage_plugin:
|
|
raise HTTPException(status_code=500, detail="Storage plugin not loaded")
|
|
try:
|
|
return await storage_plugin.save_file(file, category, path)
|
|
except ValueError as e:
|
|
raise HTTPException(status_code=400, detail=str(e))
|
|
# [/DEF:upload_file:Function]
|
|
|
|
# [DEF:delete_file:Function]
|
|
# @PURPOSE: Delete a specific file or directory.
|
|
#
|
|
# @PRE: category must be a valid FileCategory.
|
|
# @POST: Item is removed from storage.
|
|
#
|
|
# @PARAM: category (FileCategory) - File category.
|
|
# @PARAM: path (str) - Relative path of the item.
|
|
# @RETURN: None
|
|
#
|
|
# @SIDE_EFFECT: Deletes item from the filesystem.
|
|
#
|
|
# @RELATION: CALLS -> StoragePlugin.delete_file
|
|
@router.delete("/files/{category}/{path:path}", status_code=204)
|
|
async def delete_file(category: FileCategory, path: str, plugin_loader=Depends(get_plugin_loader)):
|
|
with belief_scope("delete_file"):
|
|
storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
|
|
if not storage_plugin:
|
|
raise HTTPException(status_code=500, detail="Storage plugin not loaded")
|
|
try:
|
|
storage_plugin.delete_file(category, path)
|
|
except FileNotFoundError:
|
|
raise HTTPException(status_code=404, detail="File not found")
|
|
except ValueError as e:
|
|
raise HTTPException(status_code=400, detail=str(e))
|
|
# [/DEF:delete_file:Function]
|
|
|
|
# [DEF:download_file:Function]
|
|
# @PURPOSE: Retrieve a file for download.
|
|
#
|
|
# @PRE: category must be a valid FileCategory.
|
|
# @POST: Returns a FileResponse.
|
|
#
|
|
# @PARAM: category (FileCategory) - File category.
|
|
# @PARAM: path (str) - Relative path of the file.
|
|
# @RETURN: FileResponse - The file content.
|
|
#
|
|
# @RELATION: CALLS -> StoragePlugin.get_file_path
|
|
@router.get("/download/{category}/{path:path}")
|
|
async def download_file(category: FileCategory, path: str, plugin_loader=Depends(get_plugin_loader)):
|
|
with belief_scope("download_file"):
|
|
storage_plugin: StoragePlugin = plugin_loader.get_plugin("storage-manager")
|
|
if not storage_plugin:
|
|
raise HTTPException(status_code=500, detail="Storage plugin not loaded")
|
|
try:
|
|
abs_path = storage_plugin.get_file_path(category, path)
|
|
filename = Path(path).name
|
|
return FileResponse(path=abs_path, filename=filename)
|
|
except FileNotFoundError:
|
|
raise HTTPException(status_code=404, detail="File not found")
|
|
except ValueError as e:
|
|
raise HTTPException(status_code=400, detail=str(e))
|
|
# [/DEF:download_file:Function]
|
|
|
|
# [/DEF:storage_routes:Module] |