swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/filesystem/exceptions.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import builtins
+
+from swiftpy.http.exceptions import HttpException, PayloadTooLargeError
+
+
+class FilesystemException(Exception):
+    """Base exception for all filesystem and storage operations."""
+
+
+class DiskNotFoundError(FilesystemException, KeyError):
+    """Raised when an unconfigured disk is requested."""
+
+
+class FileNotFoundError(FilesystemException, builtins.FileNotFoundError):
+    """Raised when a requested file does not exist on storage."""
+
+
+class FileAlreadyExistsError(FilesystemException, FileExistsError):
+    """Raised when a file already exists and overwrite is false."""
+
+
+class PathTraversalError(FilesystemException, PermissionError):
+    """Raised when a path traversal attempt is detected."""
+
+
+class ReadOnlyFileSystemError(FilesystemException, PermissionError):
+    """Raised when a write or delete operation is attempted on a read-only disk."""
+
+
+class StorageQuotaExceededError(FilesystemException):
+    """Raised when storage disk quota or size threshold is exceeded."""
+
+
+class InvalidSignatureError(FilesystemException):
+    """Raised when a signed temporary URL has an invalid signature or is expired."""
+
+
+class DriverNotSupportedError(FilesystemException):
+    """Raised when a driver name is unknown or an operation is unsupported."""
+
+
+class FileUploadError(FilesystemException):
+    """Base exception for HTTP upload operations."""
+
+
+class FileValidationError(FileUploadError, HttpException):
+    """Raised when file upload validation fails. Defaults to HTTP 422."""
+
+    def __init__(
+        self,
+        errors: dict[str, list[str]],
+        message: str = "The uploaded file was invalid.",
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.errors = errors
+        super().__init__(message=message, status_code=422, headers=headers)
+
+
+class FileTooLargeError(FileUploadError, PayloadTooLargeError):
+    """Raised when an uploaded file or total request exceeds configured size limits."""
+
+    def __init__(self, message: str = "Uploaded file payload is too large") -> None:
+        super().__init__(message=message)
+
+
+class InvalidMimeTypeError(FileValidationError):
+    """Raised when an uploaded file's MIME type does not match allowed types."""
+
+    def __init__(
+        self,
+        errors_or_message: str | dict[str, list[str]] = "Invalid file MIME type.",
+        message: str | None = None,
+        headers: dict[str, str] | None = None,
+        field_name: str = "file",
+    ) -> None:
+        errors, resolved_msg = _normalize_validation_args(
+            errors_or_message,
+            message=message,
+            default_message="Invalid file MIME type.",
+            field_name=field_name,
+        )
+        super().__init__(errors=errors, message=resolved_msg, headers=headers)
+
+
+class InvalidFileExtensionError(FileValidationError):
+    """Raised when an uploaded file's extension is disallowed."""
+
+    def __init__(
+        self,
+        errors_or_message: str | dict[str, list[str]] = "Invalid file extension.",
+        message: str | None = None,
+        headers: dict[str, str] | None = None,
+        field_name: str = "file",
+    ) -> None:
+        errors, resolved_msg = _normalize_validation_args(
+            errors_or_message,
+            message=message,
+            default_message="Invalid file extension.",
+            field_name=field_name,
+        )
+        super().__init__(errors=errors, message=resolved_msg, headers=headers)
+
+
+def _normalize_validation_args(
+    errors_or_message: str | dict[str, list[str]],
+    *,
+    message: str | None,
+    default_message: str,
+    field_name: str,
+) -> tuple[dict[str, list[str]], str]:
+    if isinstance(errors_or_message, str):
+        resolved_msg = message or errors_or_message
+        return {field_name: [resolved_msg]}, resolved_msg
+    first_msg = next(
+        (msgs[0] for msgs in errors_or_message.values() if msgs),
+        default_message,
+    )
+    return errors_or_message, message or first_msg
+
+
+class MalformedMultipartError(FileUploadError, HttpException):
+    """Raised when multipart form body is corrupted or improperly formatted."""
+
+    def __init__(self, message: str = "Malformed multipart request payload") -> None:
+        super().__init__(message=message, status_code=400)

swiftpy/filesystem/manager.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from swiftpy.core.config import Config
+from swiftpy.core.container import get_container
+from swiftpy.filesystem.disk import StorageDisk
+from swiftpy.filesystem.drivers.base import StorageDriver
+from swiftpy.filesystem.drivers.local import LocalStorageDriver
+from swiftpy.filesystem.drivers.s3 import S3StorageDriver
+from swiftpy.filesystem.exceptions import DiskNotFoundError, DriverNotSupportedError
+
+
+class FilesystemManager:
+    """
+    Registry and factory for configured StorageDisk instances.
+    Integrates with SwiftPY's configuration repository and DI container.
+    """
+
+    _instance: FilesystemManager | None = None
+
+    def __init__(self, config: Config | None = None) -> None:
+        if config is None:
+            try:
+                container = get_container()
+                if container.has(Config):
+                    self.config = container.resolve(Config)
+                else:
+                    self.config = Config.get_instance()
+            except RuntimeError:
+                self.config = Config.get_instance()
+        else:
+            self.config = config
+
+        self._disks: dict[str, StorageDisk] = {}
+        self._custom_creators: dict[str, Callable[[dict[str, Any]], StorageDriver]] = {}
+
+    @classmethod
+    def get_instance(cls) -> FilesystemManager:
+        try:
+            container = get_container()
+            if container.has(cls):
+                return container.resolve(cls)
+        except RuntimeError:
+            pass
+
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @property
+    def default_disk_name(self) -> str:
+        return str(self.config.get("filesystems.default", "local"))
+
+    def extend(
+        self,
+        driver_name: str,
+        factory: Callable[[dict[str, Any]], StorageDriver],
+    ) -> None:
+        """Register a custom storage driver factory."""
+        self._custom_creators[driver_name] = factory
+
+    def disk(self, name: str | None = None) -> StorageDisk:
+        """Resolve a storage disk instance by name, or return the default disk."""
+        disk_name = name or self.default_disk_name
+
+        if disk_name in self._disks:
+            return self._disks[disk_name]
+
+        disk_instance = self._resolve_disk(disk_name)
+        self._disks[disk_name] = disk_instance
+        return disk_instance
+
+    def build(self, disk_config: dict[str, Any], name: str = "on_demand") -> StorageDisk:
+        """Build an unmanaged on-demand storage disk from a configuration dict."""
+        driver = self._create_driver(disk_config)
+        read_only = bool(disk_config.get("read_only", False))
+        prefix = str(disk_config.get("prefix", ""))
+        return StorageDisk(name=name, driver=driver, read_only=read_only, prefix=prefix)
+
+    def _resolve_disk(self, name: str) -> StorageDisk:
+        disks = self.config.get("filesystems.disks", {})
+        if not isinstance(disks, dict) or name not in disks:
+            raise DiskNotFoundError(f"Storage disk '{name}' is not configured.")
+
+        disk_config = disks[name]
+        if not isinstance(disk_config, dict):
+            raise DiskNotFoundError(f"Configuration for disk '{name}' must be a dictionary.")
+
+        driver = self._create_driver(disk_config)
+        read_only = bool(disk_config.get("read_only", False))
+        prefix = str(disk_config.get("prefix", ""))
+
+        return StorageDisk(name=name, driver=driver, read_only=read_only, prefix=prefix)
+
+    def _create_driver(self, disk_config: dict[str, Any]) -> StorageDriver:
+        driver_type = str(disk_config.get("driver", "local")).lower()
+
+        if driver_type in self._custom_creators:
+            return self._custom_creators[driver_type](disk_config)
+
+        if driver_type == "local":
+            root = str(disk_config.get("root", "storage/app/private"))
+            url_prefix = str(disk_config.get("url", "/storage"))
+            visibility = str(disk_config.get("visibility", "private"))
+            raw_signing_key = self.config.get("filesystems.signing_key")
+            if raw_signing_key is None or (
+                isinstance(raw_signing_key, str)
+                and (not raw_signing_key.strip() or raw_signing_key.strip().lower() == "none")
+            ):
+                raw_signing_key = self.config.get("app.key")
+            signing_key = (
+                str(raw_signing_key)
+                if isinstance(raw_signing_key, str)
+                and raw_signing_key.strip()
+                and raw_signing_key.strip().lower() != "none"
+                else None
+            )
+            permissions = disk_config.get("permissions")
+            return LocalStorageDriver(
+                root=root,
+                url_prefix=url_prefix,
+                default_visibility=visibility,
+                signing_key=signing_key,
+                permissions=permissions if isinstance(permissions, dict) else None,
+            )
+
+        if driver_type == "s3":
+            return S3StorageDriver.from_config(disk_config)
+
+        raise DriverNotSupportedError(f"Unsupported storage driver: '{driver_type}'")
+
+    async def close(self) -> None:
+        """Close and clean up all instantiated storage drivers."""
+        for disk_instance in self._disks.values():
+            await disk_instance.driver.close()
+        self._disks.clear()

swiftpy/filesystem/metadata.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from swiftpy.filesystem.visibility import Visibility
+
+
+@dataclass(slots=True, frozen=True)
+class FileMetadata:
+    """Unified metadata representation for a stored file."""
+
+    path: str
+    size: int
+    mime_type: str
+    last_modified: datetime
+    visibility: Visibility | str = Visibility.PRIVATE
+    etag: str | None = None
+    checksum: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+

swiftpy/filesystem/paths.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from pathlib import Path
+from urllib.parse import unquote
+
+from swiftpy.filesystem.exceptions import PathTraversalError
+
+
+class PathNormalizer:
+    """Security-focused path normalization and collision-resistant name generation."""
+
+    _SUSPICIOUS_ENCODED = re.compile(r"%2e|%2f|%5c", re.IGNORECASE)
+    _SAFE_EXT = re.compile(r"^[a-zA-Z0-9]+$")
+    _WINDOWS_DRIVE = re.compile(r"^[a-zA-Z]:(?:[/\\]|$)", re.IGNORECASE)
+
+    @classmethod
+    def normalize(cls, path: str) -> str:
+        """
+        Normalize a relative storage path.
+        Strips leading/trailing slashes, normalizes separators to '/',
+        and rejects path traversal attempts.
+        """
+        if "\x00" in path:
+            raise PathTraversalError("Null byte detected in storage path.")
+
+        # Reject Windows drive letters (e.g., C:\, C:/, D:)
+        if cls._WINDOWS_DRIVE.match(path):
+            raise PathTraversalError(f"Windows drive letter detected in storage path: '{path}'.")
+
+        # Check for URL-encoded and double-encoded traversal indicators
+        decoded = unquote(path)
+        double_decoded = unquote(decoded)
+        if "\x00" in decoded or "\x00" in double_decoded:
+            raise PathTraversalError("Null byte detected in storage path.")
+
+        if ".." in decoded or ".." in double_decoded:
+            raise PathTraversalError(f"Encoded path traversal sequence detected in '{path}'.")
+
+        if (cls._SUSPICIOUS_ENCODED.search(path) or cls._SUSPICIOUS_ENCODED.search(decoded)) and (
+            "/" in decoded or "\\" in decoded or "/" in double_decoded or "\\" in double_decoded
+        ):
+            raise PathTraversalError("Encoded path traversal characters detected.")
+
+        clean = path.replace("\\", "/")
+        parts = [p for p in clean.split("/") if p and p != "."]
+
+        for part in parts:
+            if part == "..":
+                raise PathTraversalError(f"Path traversal sequence '..' detected in '{path}'.")
+            if re.match(r"^[a-zA-Z]:$", part, re.IGNORECASE):
+                raise PathTraversalError(f"Windows drive letter detected in storage path: '{path}'.")
+
+        return "/".join(parts)
+
+    @classmethod
+    def resolve_safe_path(cls, root: str | Path, path: str) -> Path:
+        """
+        Resolve a relative path against a storage root and strictly ensure
+        it does not escape the root via symlinks or relative references.
+        """
+        clean_rel = cls.normalize(path)
+        root_path = Path(root).resolve()
+        target = (root_path / clean_rel).resolve()
+
+        if target != root_path and not target.is_relative_to(root_path):
+            raise PathTraversalError(
+                f"Storage path '{path}' escapes configured root '{root}'."
+            )
+        return target
+
+    @classmethod
+    def generate_name(
+        cls,
+        original_filename: str | None = None,
+        prefix: str = "",
+        extension: str | None = None,
+    ) -> str:
+        """
+        Generate a cryptographically random, collision-resistant storage filename.
+        Preserves or overrides a sanitized extension.
+        """
+        random_hex = uuid.uuid4().hex
+        ext = extension
+
+        if ext is None and original_filename:
+            sanitized = original_filename.replace("\x00", "")
+            _, raw_ext = os.path.splitext(sanitized)
+            candidate = raw_ext.lstrip(".").lower()
+            if cls._SAFE_EXT.match(candidate):
+                ext = candidate
+
+        filename = f"{prefix}{random_hex}"
+        if ext:
+            filename = f"{filename}.{ext}"
+        return filename
+

swiftpy/filesystem/service_provider.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from swiftpy.core.providers.base import ServiceProvider
+from swiftpy.filesystem.manager import FilesystemManager
+
+
+class FilesystemServiceProvider(ServiceProvider):
+    """
+    Registers the FilesystemManager singleton into the application DI container.
+    """
+
+    def register(self) -> None:
+        self.container.singleton(FilesystemManager)
+
+    def boot(self) -> None:
+        pass
+

swiftpy/filesystem/uploads/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from swiftpy.filesystem.uploads.handlers import FormData, MultipartParser
+from swiftpy.filesystem.uploads.uploaded_file import UploadedFile
+from swiftpy.filesystem.uploads.validators import FileValidator
+
+__all__ = [
+    "FileValidator",
+    "FormData",
+    "MultipartParser",
+    "UploadedFile",
+]
+