semantics
This commit is contained in:
@@ -1,13 +1,12 @@
|
||||
# [DEF:StoragePlugin:Module]
|
||||
# #region StoragePlugin [TYPE Module] [SEMANTICS storage, files, filesystem, plugin]
|
||||
# @BRIEF Provides core filesystem operations for managing backups and repositories.
|
||||
# @LAYER App
|
||||
# @INVARIANT All file operations must be restricted to the configured storage root.
|
||||
# @RELATION IMPLEMENTS -> [PluginBase]
|
||||
# @RELATION DEPENDS_ON -> [backend.src.models.storage]
|
||||
# @RELATION USES -> [TaskContext]
|
||||
#
|
||||
# @SEMANTICS: storage, files, filesystem, plugin
|
||||
# @PURPOSE: Provides core filesystem operations for managing backups and repositories.
|
||||
# @LAYER: App
|
||||
# @RELATION: IMPLEMENTS -> PluginBase
|
||||
# @RELATION: DEPENDS_ON -> backend.src.models.storage
|
||||
# @RELATION: USES -> TaskContext
|
||||
#
|
||||
# @INVARIANT: All file operations must be restricted to the configured storage root.
|
||||
|
||||
# [SECTION: IMPORTS]
|
||||
import os
|
||||
@@ -27,80 +26,80 @@ from ...dependencies import get_config_manager
|
||||
from ...core.task_manager.context import TaskContext
|
||||
# [/SECTION]
|
||||
|
||||
# [DEF:StoragePlugin:Class]
|
||||
# @PURPOSE: Implementation of the storage management plugin.
|
||||
# #region StoragePlugin [TYPE Class]
|
||||
# @BRIEF Implementation of the storage management plugin.
|
||||
class StoragePlugin(PluginBase):
|
||||
"""
|
||||
Plugin for managing local file storage for backups and repositories.
|
||||
"""
|
||||
|
||||
# [DEF:__init__:Function]
|
||||
# @PURPOSE: Initializes the StoragePlugin and ensures required directories exist.
|
||||
# @PRE: Configuration manager must be accessible.
|
||||
# @POST: Storage root and category directories are created on disk.
|
||||
# #region __init__ [TYPE Function]
|
||||
# @BRIEF Initializes the StoragePlugin and ensures required directories exist.
|
||||
# @PRE Configuration manager must be accessible.
|
||||
# @POST Storage root and category directories are created on disk.
|
||||
def __init__(self):
|
||||
with belief_scope("StoragePlugin:init"):
|
||||
self.ensure_directories()
|
||||
# [/DEF:__init__:Function]
|
||||
# #endregion __init__
|
||||
|
||||
@property
|
||||
# [DEF:id:Function]
|
||||
# @PURPOSE: Returns the unique identifier for the storage plugin.
|
||||
# @PRE: None.
|
||||
# @POST: Returns the plugin ID string.
|
||||
# @RETURN: str - "storage-manager"
|
||||
# #region id [TYPE Function]
|
||||
# @BRIEF Returns the unique identifier for the storage plugin.
|
||||
# @PRE None.
|
||||
# @POST Returns the plugin ID string.
|
||||
# @RETURN str - "storage-manager"
|
||||
def id(self) -> str:
|
||||
with belief_scope("StoragePlugin:id"):
|
||||
return "storage-manager"
|
||||
# [/DEF:id:Function]
|
||||
# #endregion id
|
||||
|
||||
@property
|
||||
# [DEF:name:Function]
|
||||
# @PURPOSE: Returns the human-readable name of the storage plugin.
|
||||
# @PRE: None.
|
||||
# @POST: Returns the plugin name string.
|
||||
# @RETURN: str - "Storage Manager"
|
||||
# #region name [TYPE Function]
|
||||
# @BRIEF Returns the human-readable name of the storage plugin.
|
||||
# @PRE None.
|
||||
# @POST Returns the plugin name string.
|
||||
# @RETURN str - "Storage Manager"
|
||||
def name(self) -> str:
|
||||
with belief_scope("StoragePlugin:name"):
|
||||
return "Storage Manager"
|
||||
# [/DEF:name:Function]
|
||||
# #endregion name
|
||||
|
||||
@property
|
||||
# [DEF:description:Function]
|
||||
# @PURPOSE: Returns a description of the storage plugin.
|
||||
# @PRE: None.
|
||||
# @POST: Returns the plugin description string.
|
||||
# @RETURN: str - Plugin description.
|
||||
# #region description [TYPE Function]
|
||||
# @BRIEF Returns a description of the storage plugin.
|
||||
# @PRE None.
|
||||
# @POST Returns the plugin description string.
|
||||
# @RETURN str - Plugin description.
|
||||
def description(self) -> str:
|
||||
with belief_scope("StoragePlugin:description"):
|
||||
return "Manages local file storage for backups and repositories."
|
||||
# [/DEF:description:Function]
|
||||
# #endregion description
|
||||
|
||||
@property
|
||||
# [DEF:version:Function]
|
||||
# @PURPOSE: Returns the version of the storage plugin.
|
||||
# @PRE: None.
|
||||
# @POST: Returns the version string.
|
||||
# @RETURN: str - "1.0.0"
|
||||
# #region version [TYPE Function]
|
||||
# @BRIEF Returns the version of the storage plugin.
|
||||
# @PRE None.
|
||||
# @POST Returns the version string.
|
||||
# @RETURN str - "1.0.0"
|
||||
def version(self) -> str:
|
||||
with belief_scope("StoragePlugin:version"):
|
||||
return "1.0.0"
|
||||
# [/DEF:version:Function]
|
||||
# #endregion version
|
||||
|
||||
@property
|
||||
# [DEF:ui_route:Function]
|
||||
# @PURPOSE: Returns the frontend route for the storage plugin.
|
||||
# @RETURN: str - "/tools/storage"
|
||||
# #region ui_route [TYPE Function]
|
||||
# @BRIEF Returns the frontend route for the storage plugin.
|
||||
# @RETURN str - "/tools/storage"
|
||||
def ui_route(self) -> str:
|
||||
with belief_scope("StoragePlugin:ui_route"):
|
||||
return "/tools/storage"
|
||||
# [/DEF:ui_route:Function]
|
||||
# #endregion ui_route
|
||||
|
||||
# [DEF:get_schema:Function]
|
||||
# @PURPOSE: Returns the JSON schema for storage plugin parameters.
|
||||
# @PRE: None.
|
||||
# @POST: Returns a dictionary representing the JSON schema.
|
||||
# @RETURN: Dict[str, Any] - JSON schema.
|
||||
# #region get_schema [TYPE Function]
|
||||
# @BRIEF Returns the JSON schema for storage plugin parameters.
|
||||
# @PRE None.
|
||||
# @POST Returns a dictionary representing the JSON schema.
|
||||
# @RETURN Dict[str, Any] - JSON schema.
|
||||
def get_schema(self) -> Dict[str, Any]:
|
||||
with belief_scope("StoragePlugin:get_schema"):
|
||||
return {
|
||||
@@ -114,10 +113,10 @@ class StoragePlugin(PluginBase):
|
||||
},
|
||||
"required": ["category"]
|
||||
}
|
||||
# [/DEF:get_schema:Function]
|
||||
# #endregion get_schema
|
||||
|
||||
# [DEF:execute:Function]
|
||||
# @PURPOSE: Executes storage-related tasks with TaskContext support.
|
||||
# #region execute [TYPE Function]
|
||||
# @BRIEF Executes storage-related tasks with TaskContext support.
|
||||
# @PARAM: params (Dict[str, Any]) - Storage parameters.
|
||||
# @PARAM: context (Optional[TaskContext]) - Task context for logging with source attribution.
|
||||
# @PRE: params must match the plugin schema.
|
||||
@@ -125,12 +124,12 @@ class StoragePlugin(PluginBase):
|
||||
async def execute(self, params: Dict[str, Any], context: Optional[TaskContext] = None):
|
||||
with belief_scope("StoragePlugin:execute"):
|
||||
log.reason(f"Executing with params: {params}")
|
||||
# [/DEF:execute:Function]
|
||||
# #endregion execute
|
||||
|
||||
# [DEF:get_storage_root:Function]
|
||||
# @PURPOSE: Resolves the absolute path to the storage root.
|
||||
# @PRE: Settings must define a storage root path.
|
||||
# @POST: Returns a Path object representing the storage root.
|
||||
# #region get_storage_root [TYPE Function]
|
||||
# @BRIEF Resolves the absolute path to the storage root.
|
||||
# @PRE Settings must define a storage root path.
|
||||
# @POST Returns a Path object representing the storage root.
|
||||
def get_storage_root(self) -> Path:
|
||||
with belief_scope("StoragePlugin:get_storage_root"):
|
||||
config_manager = get_config_manager()
|
||||
@@ -147,10 +146,10 @@ class StoragePlugin(PluginBase):
|
||||
project_root = Path(__file__).parents[3]
|
||||
root = (project_root / root).resolve()
|
||||
return root
|
||||
# [/DEF:get_storage_root:Function]
|
||||
# #endregion get_storage_root
|
||||
|
||||
# [DEF:resolve_path:Function]
|
||||
# @PURPOSE: Resolves a dynamic path pattern using provided variables.
|
||||
# #region resolve_path [TYPE Function]
|
||||
# @BRIEF Resolves a dynamic path pattern using provided variables.
|
||||
# @PARAM: pattern (str) - The path pattern to resolve.
|
||||
# @PARAM: variables (Dict[str, str]) - Variables to substitute in the pattern.
|
||||
# @PRE: pattern must be a valid format string.
|
||||
@@ -171,13 +170,13 @@ class StoragePlugin(PluginBase):
|
||||
log.explore("Missing variable for path resolution", error=str(e))
|
||||
# Fallback to literal pattern if formatting fails partially (or handle as needed)
|
||||
return pattern.replace("{", "").replace("}", "")
|
||||
# [/DEF:resolve_path:Function]
|
||||
# #endregion resolve_path
|
||||
|
||||
# [DEF:ensure_directories:Function]
|
||||
# @PURPOSE: Creates the storage root and category subdirectories if they don't exist.
|
||||
# @PRE: Storage root must be resolvable.
|
||||
# @POST: Directories are created on the filesystem.
|
||||
# @SIDE_EFFECT: Creates directories on the filesystem.
|
||||
# #region ensure_directories [TYPE Function]
|
||||
# @BRIEF Creates the storage root and category subdirectories if they don't exist.
|
||||
# @PRE Storage root must be resolvable.
|
||||
# @POST Directories are created on the filesystem.
|
||||
# @SIDE_EFFECT Creates directories on the filesystem.
|
||||
def ensure_directories(self):
|
||||
with belief_scope("StoragePlugin:ensure_directories"):
|
||||
root = self.get_storage_root()
|
||||
@@ -186,12 +185,12 @@ class StoragePlugin(PluginBase):
|
||||
path = root / category.value
|
||||
path.mkdir(parents=True, exist_ok=True)
|
||||
log.reason(f"Ensured directory: {path}")
|
||||
# [/DEF:ensure_directories:Function]
|
||||
# #endregion ensure_directories
|
||||
|
||||
# [DEF:validate_path:Function]
|
||||
# @PURPOSE: Prevents path traversal attacks by ensuring the path is within the storage root.
|
||||
# @PRE: path must be a Path object.
|
||||
# @POST: Returns the resolved absolute path if valid, otherwise raises ValueError.
|
||||
# #region validate_path [TYPE Function]
|
||||
# @BRIEF Prevents path traversal attacks by ensuring the path is within the storage root.
|
||||
# @PRE path must be a Path object.
|
||||
# @POST Returns the resolved absolute path if valid, otherwise raises ValueError.
|
||||
def validate_path(self, path: Path) -> Path:
|
||||
with belief_scope("StoragePlugin:validate_path"):
|
||||
root = self.get_storage_root().resolve()
|
||||
@@ -202,10 +201,10 @@ class StoragePlugin(PluginBase):
|
||||
log.explore(f"Path traversal detected: {resolved} is not under {root}", error="Path outside storage root")
|
||||
raise ValueError("Access denied: Path is outside of storage root.")
|
||||
return resolved
|
||||
# [/DEF:validate_path:Function]
|
||||
# #endregion validate_path
|
||||
|
||||
# [DEF:list_files:Function]
|
||||
# @PURPOSE: Lists all files and directories in a specific category and subpath.
|
||||
# #region list_files [TYPE Function]
|
||||
# @BRIEF Lists all files and directories in a specific category and subpath.
|
||||
# @PARAM: category (Optional[FileCategory]) - The category to list.
|
||||
# @PARAM: subpath (Optional[str]) - Nested path within the category.
|
||||
# @PARAM: recursive (bool) - Whether to scan nested subdirectories recursively.
|
||||
@@ -300,10 +299,10 @@ class StoragePlugin(PluginBase):
|
||||
|
||||
# Sort: directories first, then by name
|
||||
return sorted(files, key=lambda x: (x.mime_type != "directory", x.name))
|
||||
# [/DEF:list_files:Function]
|
||||
# #endregion list_files
|
||||
|
||||
# [DEF:save_file:Function]
|
||||
# @PURPOSE: Saves an uploaded file to the specified category and optional subpath.
|
||||
# #region save_file [TYPE Function]
|
||||
# @BRIEF Saves an uploaded file to the specified category and optional subpath.
|
||||
# @PARAM: file (UploadFile) - The uploaded file.
|
||||
# @PARAM: category (FileCategory) - The target category.
|
||||
# @PARAM: subpath (Optional[str]) - The target subpath.
|
||||
@@ -334,10 +333,10 @@ class StoragePlugin(PluginBase):
|
||||
category=category,
|
||||
mime_type=file.content_type
|
||||
)
|
||||
# [/DEF:save_file:Function]
|
||||
# #endregion save_file
|
||||
|
||||
# [DEF:delete_file:Function]
|
||||
# @PURPOSE: Deletes a file or directory from the specified category and path.
|
||||
# #region delete_file [TYPE Function]
|
||||
# @BRIEF Deletes a file or directory from the specified category and path.
|
||||
# @PARAM: category (FileCategory) - The category.
|
||||
# @PARAM: path (str) - The relative path of the file or directory.
|
||||
# @PRE: path must belong to the specified category and exist on disk.
|
||||
@@ -360,10 +359,10 @@ class StoragePlugin(PluginBase):
|
||||
log.reflect(f"Deleted: {full_path}")
|
||||
else:
|
||||
raise FileNotFoundError(f"Item {path} not found")
|
||||
# [/DEF:delete_file:Function]
|
||||
# #endregion delete_file
|
||||
|
||||
# [DEF:get_file_path:Function]
|
||||
# @PURPOSE: Returns the absolute path of a file for download.
|
||||
# #region get_file_path [TYPE Function]
|
||||
# @BRIEF Returns the absolute path of a file for download.
|
||||
# @PARAM: category (FileCategory) - The category.
|
||||
# @PARAM: path (str) - The relative path of the file.
|
||||
# @PRE: path must belong to the specified category and be a file.
|
||||
@@ -381,7 +380,7 @@ class StoragePlugin(PluginBase):
|
||||
raise FileNotFoundError(f"File {path} not found")
|
||||
|
||||
return file_path
|
||||
# [/DEF:get_file_path:Function]
|
||||
# #endregion get_file_path
|
||||
|
||||
# [/DEF:StoragePlugin:Class]
|
||||
# [/DEF:StoragePlugin:Module]
|
||||
# #endregion StoragePlugin
|
||||
# #endregion StoragePlugin
|
||||
|
||||
Reference in New Issue
Block a user