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

svc_infra/storage/easy.py

@@ -0,0 +1,181 @@
+"""
+Easy storage backend builder with auto-detection.
+
+Simplifies storage backend initialization with sensible defaults.
+"""
+
+import logging
+import os
+
+from .backends import LocalBackend, MemoryBackend, S3Backend
+from .base import StorageBackend
+from .settings import StorageSettings
+
+logger = logging.getLogger(__name__)
+
+
+def easy_storage(
+    backend: str | None = 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,193 @@
+"""
+Storage configuration and settings.
+
+Handles environment-based configuration and auto-detection of storage backends.
+"""
+
+import os
+from typing import Literal
+
+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: Literal["local", "s3", "gcs", "cloudinary", "memory"] | None = 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: str | None = Field(
+        default=None,
+        description="Secret key for URL signing (auto-generated if not set)",
+    )
+
+    # S3 backend settings
+    storage_s3_bucket: str | None = Field(
+        default=None,
+        description="S3 bucket name",
+    )
+    storage_s3_region: str = Field(
+        default="us-east-1",
+        description="AWS region",
+    )
+    storage_s3_endpoint: str | None = Field(
+        default=None,
+        description="Custom S3 endpoint (for DigitalOcean Spaces, Wasabi, etc.)",
+    )
+    storage_s3_access_key: str | None = Field(
+        default=None,
+        description="S3 access key (falls back to AWS_ACCESS_KEY_ID)",
+    )
+    storage_s3_secret_key: str | None = Field(
+        default=None,
+        description="S3 secret key (falls back to AWS_SECRET_ACCESS_KEY)",
+    )
+
+    # GCS backend settings
+    storage_gcs_bucket: str | None = Field(
+        default=None,
+        description="Google Cloud Storage bucket name",
+    )
+    storage_gcs_project: str | None = Field(
+        default=None,
+        description="GCP project ID",
+    )
+    storage_gcs_credentials_path: str | None = Field(
+        default=None,
+        description="Path to GCP service account JSON",
+    )
+
+    # Cloudinary backend settings
+    storage_cloudinary_cloud_name: str | None = Field(
+        default=None,
+        description="Cloudinary cloud name",
+    )
+    storage_cloudinary_api_key: str | None = Field(
+        default=None,
+        description="Cloudinary API key",
+    )
+    storage_cloudinary_api_secret: str | None = 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[str | None, str | None]:
+        """
+        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"]