svc-infra 0.1.595__py3-none-any.whl → 0.1.706__py3-none-any.whl

svc_infra/storage/base.py

@@ -0,0 +1,239 @@
+"""
+Base storage abstractions and exceptions.
+
+Defines the StorageBackend protocol that all storage implementations must follow.
+"""
+
+from typing import Optional, Protocol
+
+
+class StorageError(Exception):
+    """Base exception for all storage operations."""
+
+    pass
+
+
+class FileNotFoundError(StorageError):
+    """Raised when a requested file does not exist."""
+
+    pass
+
+
+class PermissionDeniedError(StorageError):
+    """Raised when lacking permissions for an operation."""
+
+    pass
+
+
+class QuotaExceededError(StorageError):
+    """Raised when storage quota is exceeded."""
+
+    pass
+
+
+class InvalidKeyError(StorageError):
+    """Raised when a key format is invalid."""
+
+    pass
+
+
+class StorageBackend(Protocol):
+    """
+    Abstract storage backend interface.
+
+    All storage backends must implement this protocol to be compatible
+    with the storage system.
+
+    Example:
+        >>> from svc_infra.storage import StorageBackend
+        >>>
+        >>> class MyBackend:
+        ...     async def put(self, key, data, content_type, metadata=None):
+        ...         # Custom implementation
+        ...         return "https://example.com/files/key"
+        >>>
+        >>> # MyBackend is now a valid StorageBackend
+    """
+
+    async def put(
+        self,
+        key: str,
+        data: bytes,
+        content_type: str,
+        metadata: Optional[dict] = None,
+    ) -> str:
+        """
+        Store file content and return its URL.
+
+        Args:
+            key: Storage key (path) for the file
+            data: File content as bytes
+            content_type: MIME type (e.g., "image/jpeg", "application/pdf")
+            metadata: Optional metadata dict (user_id, tenant_id, etc.)
+
+        Returns:
+            Public or signed URL to access the file
+
+        Raises:
+            InvalidKeyError: If key format is invalid
+            PermissionDeniedError: If lacking write permissions
+            QuotaExceededError: If storage quota exceeded
+            StorageError: For other storage errors
+
+        Example:
+            >>> url = await storage.put(
+            ...     key="avatars/user_123/profile.jpg",
+            ...     data=image_bytes,
+            ...     content_type="image/jpeg",
+            ...     metadata={"user_id": "user_123"}
+            ... )
+        """
+        ...
+
+    async def get(self, key: str) -> bytes:
+        """
+        Retrieve file content.
+
+        Args:
+            key: Storage key (path) for the file
+
+        Returns:
+            File content as bytes
+
+        Raises:
+            FileNotFoundError: If file does not exist
+            PermissionDeniedError: If lacking read permissions
+            StorageError: For other storage errors
+
+        Example:
+            >>> data = await storage.get("avatars/user_123/profile.jpg")
+        """
+        ...
+
+    async def delete(self, key: str) -> bool:
+        """
+        Delete a file.
+
+        Args:
+            key: Storage key (path) for the file
+
+        Returns:
+            True if file was deleted, False if file did not exist
+
+        Raises:
+            PermissionDeniedError: If lacking delete permissions
+            StorageError: For other storage errors
+
+        Example:
+            >>> deleted = await storage.delete("avatars/user_123/profile.jpg")
+        """
+        ...
+
+    async def exists(self, key: str) -> bool:
+        """
+        Check if a file exists.
+
+        Args:
+            key: Storage key (path) for the file
+
+        Returns:
+            True if file exists, False otherwise
+
+        Example:
+            >>> if await storage.exists("avatars/user_123/profile.jpg"):
+            ...     print("File exists")
+        """
+        ...
+
+    async def get_url(
+        self,
+        key: str,
+        expires_in: int = 3600,
+        download: bool = False,
+    ) -> str:
+        """
+        Generate a signed or public URL for file access.
+
+        Args:
+            key: Storage key (path) for the file
+            expires_in: URL expiration time in seconds (default: 1 hour)
+            download: If True, force download instead of inline display
+
+        Returns:
+            Signed or public URL
+
+        Raises:
+            FileNotFoundError: If file does not exist
+            StorageError: For other storage errors
+
+        Example:
+            >>> # Get 1-hour signed URL for viewing
+            >>> url = await storage.get_url("documents/invoice.pdf")
+            >>>
+            >>> # Get 5-minute download URL
+            >>> url = await storage.get_url(
+            ...     "documents/invoice.pdf",
+            ...     expires_in=300,
+            ...     download=True
+            ... )
+        """
+        ...
+
+    async def list_keys(
+        self,
+        prefix: str = "",
+        limit: int = 100,
+    ) -> list[str]:
+        """
+        List stored file keys with optional prefix filter.
+
+        Args:
+            prefix: Key prefix to filter by (e.g., "avatars/")
+            limit: Maximum number of keys to return (default: 100)
+
+        Returns:
+            List of matching keys
+
+        Example:
+            >>> # List all avatars for a user
+            >>> keys = await storage.list_keys(prefix="avatars/user_123/")
+            >>>
+            >>> # List all files
+            >>> keys = await storage.list_keys()
+        """
+        ...
+
+    async def get_metadata(self, key: str) -> dict:
+        """
+        Get file metadata.
+
+        Args:
+            key: Storage key (path) for the file
+
+        Returns:
+            Metadata dict containing:
+                - size: File size in bytes
+                - content_type: MIME type
+                - created_at: Creation timestamp (ISO 8601)
+                - Custom metadata from put() call
+
+        Raises:
+            FileNotFoundError: If file does not exist
+            StorageError: For other storage errors
+
+        Example:
+            >>> meta = await storage.get_metadata("avatars/user_123/profile.jpg")
+            >>> print(f"Size: {meta['size']} bytes")
+            >>> print(f"Type: {meta['content_type']}")
+        """
+        ...
+
+
+__all__ = [
+    "StorageBackend",
+    "StorageError",
+    "FileNotFoundError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "InvalidKeyError",
+]

svc_infra/storage/easy.py

@@ -0,0 +1,185 @@
+"""
+Easy storage backend builder with auto-detection.
+
+Simplifies storage backend initialization with sensible defaults.
+"""
+
+import logging
+import os
+from typing import Optional
+
+from .backends import LocalBackend, MemoryBackend, S3Backend
+from .base import StorageBackend
+from .settings import StorageSettings
+
+logger = logging.getLogger(__name__)
+
+
+def easy_storage(
+    backend: Optional[str] = None,
+    **kwargs,
+) -> StorageBackend:
+    """
+    Create a storage backend with auto-detection or explicit selection.
+
+    This is the recommended way to initialize storage in most applications.
+    It handles environment-based configuration and provides sensible defaults.
+
+    Args:
+        backend: Explicit backend type ("local", "s3", "gcs", "cloudinary", "memory")
+                If None, auto-detects from environment variables
+        **kwargs: Backend-specific configuration overrides
+
+    Returns:
+        Initialized storage backend
+
+    Auto-Detection Order:
+        1. Explicit backend parameter
+        2. STORAGE_BACKEND environment variable
+        3. Railway volume (RAILWAY_VOLUME_MOUNT_PATH) → LocalBackend
+        4. S3 credentials (AWS_ACCESS_KEY_ID or STORAGE_S3_BUCKET) → S3Backend
+        5. GCS credentials (GOOGLE_APPLICATION_CREDENTIALS) → GCSBackend
+        6. Cloudinary credentials (CLOUDINARY_URL) → CloudinaryBackend
+        7. Default: MemoryBackend (with warning)
+
+    Examples:
+        >>> # Auto-detect backend from environment
+        >>> storage = easy_storage()
+        >>>
+        >>> # Explicit local backend
+        >>> storage = easy_storage(
+        ...     backend="local",
+        ...     base_path="/data/uploads"
+        ... )
+        >>>
+        >>> # Explicit S3 backend
+        >>> storage = easy_storage(
+        ...     backend="s3",
+        ...     bucket="my-uploads",
+        ...     region="us-west-2"
+        ... )
+        >>>
+        >>> # DigitalOcean Spaces
+        >>> storage = easy_storage(
+        ...     backend="s3",
+        ...     bucket="my-uploads",
+        ...     region="nyc3",
+        ...     endpoint="https://nyc3.digitaloceanspaces.com"
+        ... )
+
+    Environment Variables:
+        See StorageSettings for full list of environment variables.
+
+    Raises:
+        ValueError: If backend type is unsupported or configuration is invalid
+        ImportError: If required backend dependencies are not installed
+
+    Note:
+        For production deployments, it's recommended to set STORAGE_BACKEND
+        explicitly to avoid unexpected auto-detection behavior.
+    """
+    # Load settings
+    settings = StorageSettings()
+
+    # Determine backend type
+    backend_type = backend or settings.detect_backend()
+
+    logger.info(f"Initializing {backend_type} storage backend")
+
+    # Create backend instance
+    if backend_type == "memory":
+        # Memory backend
+        if backend_type == settings.detect_backend() and not backend:
+            logger.warning(
+                "Using MemoryBackend (in-memory storage). "
+                "Data will be lost on restart. "
+                "Set STORAGE_BACKEND environment variable for production."
+            )
+
+        max_size = kwargs.get("max_size", 100_000_000)
+        return MemoryBackend(max_size=max_size)
+
+    elif backend_type == "local":
+        # Local filesystem backend
+        base_path = kwargs.get("base_path") or settings.storage_base_path
+
+        # Check for Railway volume
+        railway_volume = os.getenv("RAILWAY_VOLUME_MOUNT_PATH")
+        if railway_volume and not kwargs.get("base_path"):
+            base_path = railway_volume
+            logger.info(f"Detected Railway volume at {base_path}")
+
+        base_url = kwargs.get("base_url") or settings.storage_base_url
+        signing_secret = kwargs.get("signing_secret") or settings.storage_signing_secret
+
+        return LocalBackend(
+            base_path=base_path,
+            base_url=base_url,
+            signing_secret=signing_secret,
+        )
+
+    elif backend_type == "s3":
+        # S3-compatible backend
+        bucket = kwargs.get("bucket") or settings.storage_s3_bucket
+        if not bucket:
+            raise ValueError(
+                "S3 bucket is required. "
+                "Set STORAGE_S3_BUCKET environment variable or pass bucket parameter."
+            )
+
+        region = kwargs.get("region") or settings.storage_s3_region
+        endpoint = kwargs.get("endpoint") or settings.storage_s3_endpoint
+
+        # Get credentials with fallback
+        access_key = kwargs.get("access_key")
+        secret_key = kwargs.get("secret_key")
+
+        if not access_key or not secret_key:
+            access_key_from_settings, secret_key_from_settings = (
+                settings.get_s3_credentials()
+            )
+            access_key = access_key or access_key_from_settings
+            secret_key = secret_key or secret_key_from_settings
+
+        # Log provider detection
+        if endpoint:
+            if "digitalocean" in endpoint:
+                logger.info("Detected DigitalOcean Spaces")
+            elif "wasabi" in endpoint:
+                logger.info("Detected Wasabi")
+            elif "backblaze" in endpoint:
+                logger.info("Detected Backblaze B2")
+            else:
+                logger.info(f"Using custom S3 endpoint: {endpoint}")
+        else:
+            logger.info("Using AWS S3")
+
+        return S3Backend(
+            bucket=bucket,
+            region=region,
+            endpoint=endpoint,
+            access_key=access_key,
+            secret_key=secret_key,
+        )
+
+    elif backend_type == "gcs":
+        # Google Cloud Storage backend
+        raise NotImplementedError(
+            "GCS backend not yet implemented. " "Use 'local' or 's3' backend for now."
+        )
+
+    elif backend_type == "cloudinary":
+        # Cloudinary backend
+        raise NotImplementedError(
+            "Cloudinary backend not yet implemented. "
+            "Use 'local' or 's3' backend for now."
+        )
+
+    else:
+        raise ValueError(
+            f"Unsupported storage backend: {backend_type}. "
+            f"Supported: local, s3, memory (gcs, cloudinary coming soon)"
+        )
+
+
+__all__ = ["easy_storage"]

svc_infra/storage/settings.py

@@ -0,0 +1,195 @@
+"""
+Storage configuration and settings.
+
+Handles environment-based configuration and auto-detection of storage backends.
+"""
+
+import os
+from typing import Literal, Optional
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class StorageSettings(BaseSettings):
+    """
+    Storage system configuration.
+
+    Supports multiple backends with auto-detection from environment variables.
+
+    Environment Variables:
+        STORAGE_BACKEND: Explicit backend selection ("local", "s3", "gcs", "cloudinary", "memory")
+
+        Local Backend:
+            STORAGE_BASE_PATH: Base directory for file storage (default: /data/uploads)
+            STORAGE_BASE_URL: Base URL for file serving (default: http://localhost:8000/files)
+            STORAGE_SIGNING_SECRET: Secret key for URL signing (auto-generated if not set)
+
+        S3 Backend:
+            STORAGE_S3_BUCKET: S3 bucket name (required for S3)
+            STORAGE_S3_REGION: AWS region (default: us-east-1)
+            STORAGE_S3_ENDPOINT: Custom endpoint for S3-compatible services (optional)
+            STORAGE_S3_ACCESS_KEY: AWS access key (optional, uses AWS_ACCESS_KEY_ID if not set)
+            STORAGE_S3_SECRET_KEY: AWS secret key (optional, uses AWS_SECRET_ACCESS_KEY if not set)
+
+        GCS Backend:
+            STORAGE_GCS_BUCKET: GCS bucket name (required for GCS)
+            STORAGE_GCS_PROJECT: GCP project ID (optional)
+            STORAGE_GCS_CREDENTIALS_PATH: Path to service account JSON (optional)
+
+        Cloudinary Backend:
+            STORAGE_CLOUDINARY_CLOUD_NAME: Cloudinary cloud name (required)
+            STORAGE_CLOUDINARY_API_KEY: Cloudinary API key (required)
+            STORAGE_CLOUDINARY_API_SECRET: Cloudinary API secret (required)
+
+    Example:
+        >>> # Auto-detect backend from environment
+        >>> settings = StorageSettings()
+        >>> backend = settings.detect_backend()
+        >>>
+        >>> # Explicit backend selection
+        >>> settings = StorageSettings(storage_backend="s3")
+    """
+
+    # Backend selection
+    storage_backend: Optional[Literal["local", "s3", "gcs", "cloudinary", "memory"]] = (
+        Field(
+            default=None,
+            description="Storage backend type (auto-detected if not set)",
+        )
+    )
+
+    # Local backend settings
+    storage_base_path: str = Field(
+        default="/data/uploads",
+        description="Base directory for local file storage",
+    )
+    storage_base_url: str = Field(
+        default="http://localhost:8000/files",
+        description="Base URL for serving files",
+    )
+    storage_signing_secret: Optional[str] = Field(
+        default=None,
+        description="Secret key for URL signing (auto-generated if not set)",
+    )
+
+    # S3 backend settings
+    storage_s3_bucket: Optional[str] = Field(
+        default=None,
+        description="S3 bucket name",
+    )
+    storage_s3_region: str = Field(
+        default="us-east-1",
+        description="AWS region",
+    )
+    storage_s3_endpoint: Optional[str] = Field(
+        default=None,
+        description="Custom S3 endpoint (for DigitalOcean Spaces, Wasabi, etc.)",
+    )
+    storage_s3_access_key: Optional[str] = Field(
+        default=None,
+        description="S3 access key (falls back to AWS_ACCESS_KEY_ID)",
+    )
+    storage_s3_secret_key: Optional[str] = Field(
+        default=None,
+        description="S3 secret key (falls back to AWS_SECRET_ACCESS_KEY)",
+    )
+
+    # GCS backend settings
+    storage_gcs_bucket: Optional[str] = Field(
+        default=None,
+        description="Google Cloud Storage bucket name",
+    )
+    storage_gcs_project: Optional[str] = Field(
+        default=None,
+        description="GCP project ID",
+    )
+    storage_gcs_credentials_path: Optional[str] = Field(
+        default=None,
+        description="Path to GCP service account JSON",
+    )
+
+    # Cloudinary backend settings
+    storage_cloudinary_cloud_name: Optional[str] = Field(
+        default=None,
+        description="Cloudinary cloud name",
+    )
+    storage_cloudinary_api_key: Optional[str] = Field(
+        default=None,
+        description="Cloudinary API key",
+    )
+    storage_cloudinary_api_secret: Optional[str] = Field(
+        default=None,
+        description="Cloudinary API secret",
+    )
+
+    model_config = {
+        "env_file": ".env",
+        "case_sensitive": False,
+        "extra": "ignore",  # Ignore unknown environment variables
+    }
+
+    def detect_backend(self) -> str:
+        """
+        Auto-detect storage backend from environment.
+
+        Detection order:
+            1. Explicit STORAGE_BACKEND setting
+            2. Railway volume (RAILWAY_VOLUME_MOUNT_PATH) → local
+            3. S3 credentials (AWS_ACCESS_KEY_ID or STORAGE_S3_BUCKET) → s3
+            4. GCS credentials (GOOGLE_APPLICATION_CREDENTIALS or STORAGE_GCS_BUCKET) → gcs
+            5. Cloudinary credentials (CLOUDINARY_URL or STORAGE_CLOUDINARY_CLOUD_NAME) → cloudinary
+            6. Default → memory (with warning)
+
+        Returns:
+            Backend type string
+
+        Example:
+            >>> settings = StorageSettings()
+            >>> backend_type = settings.detect_backend()
+            >>> print(f"Using {backend_type} backend")
+        """
+        # Explicit setting takes precedence
+        if self.storage_backend:
+            return self.storage_backend
+
+        # Check for Railway volume
+        railway_volume = os.getenv("RAILWAY_VOLUME_MOUNT_PATH")
+        if railway_volume:
+            return "local"
+
+        # Check for S3
+        has_s3_key = os.getenv("AWS_ACCESS_KEY_ID") or self.storage_s3_access_key
+        if has_s3_key or self.storage_s3_bucket:
+            return "s3"
+
+        # Check for GCS
+        has_gcs_creds = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+        if has_gcs_creds or self.storage_gcs_bucket:
+            return "gcs"
+
+        # Check for Cloudinary
+        has_cloudinary = os.getenv("CLOUDINARY_URL")
+        if has_cloudinary or self.storage_cloudinary_cloud_name:
+            return "cloudinary"
+
+        # Default to memory (for development/testing)
+        return "memory"
+
+    def get_s3_credentials(self) -> tuple[Optional[str], Optional[str]]:
+        """
+        Get S3 credentials with fallback to AWS environment variables.
+
+        Returns:
+            Tuple of (access_key, secret_key)
+
+        Example:
+            >>> settings = StorageSettings()
+            >>> access_key, secret_key = settings.get_s3_credentials()
+        """
+        access_key = self.storage_s3_access_key or os.getenv("AWS_ACCESS_KEY_ID")
+        secret_key = self.storage_s3_secret_key or os.getenv("AWS_SECRET_ACCESS_KEY")
+        return access_key, secret_key
+
+
+__all__ = ["StorageSettings"]