imgdude 0.1.0__tar.gz

imgdude-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ImgDude Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imgdude-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE
+include README.md
+include requirements.txt
+include requirements-dev.txt
+include pyproject.toml
+graft imgdude
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .git*
+global-exclude .pytest_cache
+global-exclude .coverage
+global-exclude htmlcov
+global-exclude .DS_Store 

imgdude-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: imgdude
+Version: 0.1.0
+Summary: Fast image resizing proxy for Nginx with FastAPI
+Author-email: ASafarzadeh <includesafarof@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ASafarzadeh/imgdude
+Project-URL: Documentation, https://github.com/ASafarzadeh/imgdude#readme
+Project-URL: Bug Tracker, https://github.com/ASafarzadeh/imgdude/issues
+Project-URL: Source, https://github.com/ASafarzadeh/imgdude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pillow>=9.0.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: python-multipart>=0.0.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Dynamic: license-file
+
+# ImgDude
+
+[![PyPI version](https://badge.fury.io/py/imgdude.svg)](https://badge.fury.io/py/imgdude)
+[![Python Version](https://img.shields.io/pypi/pyversions/imgdude.svg)](https://pypi.org/project/imgdude/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A high-performance image resizing proxy for Nginx, built with FastAPI. ImgDude provides on-the-fly image resizing with efficient caching capabilities.
+
+## Features
+
+- Dynamic image resizing with aspect ratio preservation
+- Intelligent caching system for optimized performance
+- Seamless Nginx integration
+- Built on FastAPI with async I/O support
+- Simple URL-based resizing API
+- Comprehensive security measures
+- Performance optimizations for production use
+
+## Installation
+
+### PyPI
+
+```bash
+pip install imgdude
+```
+
+### Source
+
+```bash
+git clone https://github.com/ASafarzadeh/imgdude.git
+cd imgdude
+pip install -e .
+```
+
+## Usage
+
+### Basic Server
+
+```bash
+# Default configuration (127.0.0.1:12312)
+imgdude
+
+# Custom configuration
+imgdude --host 0.0.0.0 --port 8080 --media-root /path/to/images --cache-dir /path/to/cache
+```
+
+### Docker Deployment
+
+1. Build and run using Docker Compose:
+
+```bash
+# Update volume paths in docker-compose.yml
+docker-compose up -d
+```
+
+2. Or build and run manually:
+
+```bash
+# Build the image
+docker build -t imgdude .
+
+# Run the container
+docker run -d \
+  -p 12312:12312 \
+  -v /path/to/images:/app/media \
+  -v /path/to/cache:/app/cache \
+  imgdude
+```
+
+### Nginx Integration
+
+Add to your Nginx configuration:
+
+```nginx
+location /images/ {
+    proxy_pass http://127.0.0.1:12312/image/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_cache_valid 200 7d;
+    expires max;
+}
+```
+
+### Image Resizing
+
+Resize images by adding the width parameter:
+
+```
+http://yourdomain.com/images/path/to/image.jpg?w=300
+```
+
+## Configuration
+
+| Setting         | Environment Variable    | Default   | Description              |
+| --------------- | ----------------------- | --------- | ------------------------ |
+| Host            | -                       | 127.0.0.1 | Server host              |
+| Port            | -                       | 12312     | Server port              |
+| Media Root      | IMGDUDE_MEDIA_ROOT      | ./media   | Media directory          |
+| Cache Directory | IMGDUDE_CACHE_DIR       | ./cache   | Cache directory          |
+| Cache Max Age   | IMGDUDE_CACHE_MAX_AGE   | 604800    | Cache duration (seconds) |
+| Max Width       | IMGDUDE_MAX_WIDTH       | 2000      | Maximum image width      |
+| Trusted Hosts   | IMGDUDE_TRUSTED_HOSTS   | \*        | Allowed IP addresses     |
+| Image Workers   | IMGDUDE_IMAGE_WORKERS   | CPU-based | Image processing threads |
+| I/O Workers     | IMGDUDE_IO_WORKERS      | CPU-based | File I/O threads         |
+| Max Connections | IMGDUDE_MAX_CONNECTIONS | 100       | Concurrent connections   |
+| Workers         | IMGDUDE_WORKERS         | 1         | Uvicorn workers          |
+
+## API Reference
+
+- `GET /image/{path}` - Original image
+- `GET /image/{path}?w=WIDTH` - Resized image
+- `GET /cache/stats` - Cache statistics
+- `POST /cache/clean` - Clean expired cache
+- `GET /health` - Health check
+
+## Security
+
+- Trusted host verification
+- CORS protection
+- Path traversal prevention
+- File extension validation
+- Input parameter validation
+- Absolute path blocking
+
+## Performance
+
+- Smart resize skipping
+- Dedicated thread pools
+- Image optimization
+- Cache control headers
+- Size-based cache management
+- Performance monitoring
+
+## Development
+
+```bash
+# Setup
+git clone https://github.com/ASafarzadeh/imgdude.git
+cd imgdude
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+
+# Testing
+pytest
+pytest --cov=imgdude
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

imgdude-0.1.0/README.md

@@ -0,0 +1,151 @@
+# ImgDude
+
+[![PyPI version](https://badge.fury.io/py/imgdude.svg)](https://badge.fury.io/py/imgdude)
+[![Python Version](https://img.shields.io/pypi/pyversions/imgdude.svg)](https://pypi.org/project/imgdude/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A high-performance image resizing proxy for Nginx, built with FastAPI. ImgDude provides on-the-fly image resizing with efficient caching capabilities.
+
+## Features
+
+- Dynamic image resizing with aspect ratio preservation
+- Intelligent caching system for optimized performance
+- Seamless Nginx integration
+- Built on FastAPI with async I/O support
+- Simple URL-based resizing API
+- Comprehensive security measures
+- Performance optimizations for production use
+
+## Installation
+
+### PyPI
+
+```bash
+pip install imgdude
+```
+
+### Source
+
+```bash
+git clone https://github.com/ASafarzadeh/imgdude.git
+cd imgdude
+pip install -e .
+```
+
+## Usage
+
+### Basic Server
+
+```bash
+# Default configuration (127.0.0.1:12312)
+imgdude
+
+# Custom configuration
+imgdude --host 0.0.0.0 --port 8080 --media-root /path/to/images --cache-dir /path/to/cache
+```
+
+### Docker Deployment
+
+1. Build and run using Docker Compose:
+
+```bash
+# Update volume paths in docker-compose.yml
+docker-compose up -d
+```
+
+2. Or build and run manually:
+
+```bash
+# Build the image
+docker build -t imgdude .
+
+# Run the container
+docker run -d \
+  -p 12312:12312 \
+  -v /path/to/images:/app/media \
+  -v /path/to/cache:/app/cache \
+  imgdude
+```
+
+### Nginx Integration
+
+Add to your Nginx configuration:
+
+```nginx
+location /images/ {
+    proxy_pass http://127.0.0.1:12312/image/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_cache_valid 200 7d;
+    expires max;
+}
+```
+
+### Image Resizing
+
+Resize images by adding the width parameter:
+
+```
+http://yourdomain.com/images/path/to/image.jpg?w=300
+```
+
+## Configuration
+
+| Setting         | Environment Variable    | Default   | Description              |
+| --------------- | ----------------------- | --------- | ------------------------ |
+| Host            | -                       | 127.0.0.1 | Server host              |
+| Port            | -                       | 12312     | Server port              |
+| Media Root      | IMGDUDE_MEDIA_ROOT      | ./media   | Media directory          |
+| Cache Directory | IMGDUDE_CACHE_DIR       | ./cache   | Cache directory          |
+| Cache Max Age   | IMGDUDE_CACHE_MAX_AGE   | 604800    | Cache duration (seconds) |
+| Max Width       | IMGDUDE_MAX_WIDTH       | 2000      | Maximum image width      |
+| Trusted Hosts   | IMGDUDE_TRUSTED_HOSTS   | \*        | Allowed IP addresses     |
+| Image Workers   | IMGDUDE_IMAGE_WORKERS   | CPU-based | Image processing threads |
+| I/O Workers     | IMGDUDE_IO_WORKERS      | CPU-based | File I/O threads         |
+| Max Connections | IMGDUDE_MAX_CONNECTIONS | 100       | Concurrent connections   |
+| Workers         | IMGDUDE_WORKERS         | 1         | Uvicorn workers          |
+
+## API Reference
+
+- `GET /image/{path}` - Original image
+- `GET /image/{path}?w=WIDTH` - Resized image
+- `GET /cache/stats` - Cache statistics
+- `POST /cache/clean` - Clean expired cache
+- `GET /health` - Health check
+
+## Security
+
+- Trusted host verification
+- CORS protection
+- Path traversal prevention
+- File extension validation
+- Input parameter validation
+- Absolute path blocking
+
+## Performance
+
+- Smart resize skipping
+- Dedicated thread pools
+- Image optimization
+- Cache control headers
+- Size-based cache management
+- Performance monitoring
+
+## Development
+
+```bash
+# Setup
+git clone https://github.com/ASafarzadeh/imgdude.git
+cd imgdude
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+
+# Testing
+pytest
+pytest --cov=imgdude
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

imgdude-0.1.0/imgdude/__init__.py

@@ -0,0 +1,3 @@
+"""Image resizing proxy for Nginx with FastAPI."""
+
+from ._version import __version__ 

imgdude-0.1.0/imgdude/_version.py

@@ -0,0 +1,5 @@
+"""Version information for ImgDude."""
+
+__all__ = ["__version__", "version"]
+
+__version__ = version = '0.1.0'

imgdude-0.1.0/imgdude/cache.py

@@ -0,0 +1,302 @@
+"""Cache management for imgdude."""
+
+import os
+import time
+import asyncio
+import logging
+import shutil
+from pathlib import Path
+from typing import Dict, Any, Union, List, Set, Optional, OrderedDict
+from concurrent.futures import ThreadPoolExecutor
+from collections import OrderedDict
+
+logger = logging.getLogger("imgdude.cache")
+
+class CacheManager:
+    """Handles image cache operations and cleanup."""
+    def __init__(self, cache_dir: str, max_age_seconds: int = 604800, max_size_mb: int = 1024):
+        """Initialize the cache manager.
+        Args:
+            cache_dir: Directory to store cached images
+            max_age_seconds: Maximum age of cached files in seconds
+            max_size_mb: Maximum size of cache in MB
+        """
+        self.cache_dir = Path(cache_dir)
+        self.max_age_seconds = max_age_seconds
+        self.max_size_bytes = max_size_mb * 1024 * 1024
+        self.cache_dir.mkdir(exist_ok=True, parents=True)
+        self._thread_pool = ThreadPoolExecutor(
+            max_workers=2,
+            thread_name_prefix="cache_worker"
+        )
+        # Use an OrderedDict with a max size for recently accessed files
+        # This is more efficient than maintaining separate deque and set
+        self._recently_accessed: OrderedDict[str, None] = OrderedDict()
+        self._max_recently_accessed = 1000
+        self._cleanup_lock = asyncio.Lock()
+
+    def mark_accessed(self, file_path: str) -> None:
+        """Mark a file as recently accessed to help prioritize cache cleanup."""
+        # If the file is already in recently accessed, remove it to add it at the end
+        if file_path in self._recently_accessed:
+            del self._recently_accessed[file_path]
+        
+        # Add to the OrderedDict (most recently accessed is at the end)
+        self._recently_accessed[file_path] = None
+        
+        # Trim if exceeds max size
+        while len(self._recently_accessed) > self._max_recently_accessed:
+            self._recently_accessed.popitem(last=False)  # Remove oldest item (first)
+
+    async def clean_cache(self) -> Dict[str, Union[int, str, float]]:
+        """Remove expired or excess items from the cache. Returns cleanup statistics."""
+        async with self._cleanup_lock:
+            try:
+                logger.info("Starting cache cleanup")
+                start_time = time.time()
+                now = time.time()
+                count = 0
+                failed = 0
+                removed_size = 0
+                total_size = await self._get_cache_size()
+                
+                # Process files in batches to reduce memory usage
+                # First, handle expired files
+                expired_stats = await self._clean_expired_files(now, total_size)
+                count += expired_stats["removed"]
+                failed += expired_stats["failed"]
+                removed_size += expired_stats["removed_size"]
+                total_size = expired_stats["new_total_size"]
+                
+                # Then handle size-based cleanup if still needed
+                if total_size > self.max_size_bytes:
+                    size_cleanup_stats = await self._clean_by_size(total_size)
+                    count += size_cleanup_stats["removed"]
+                    failed += size_cleanup_stats["failed"]
+                    removed_size += size_cleanup_stats["removed_size"]
+                    total_size = size_cleanup_stats["new_total_size"]
+                
+                process_time = time.time() - start_time
+                logger.info(f"Cache cleanup complete: removed {count} files ({removed_size / (1024*1024):.2f} MB) in {process_time:.2f}s")
+                return {
+                    "removed_files": count,
+                    "failed_files": failed,
+                    "removed_size_bytes": removed_size,
+                    "removed_size_mb": round(removed_size / (1024 * 1024), 2),
+                    "total_size_mb": round(total_size / (1024 * 1024), 2),
+                    "max_size_mb": self.max_size_bytes // (1024 * 1024),
+                    "process_time_seconds": round(process_time, 2)
+                }
+            except Exception as e:
+                logger.error(f"Cache cleanup error: {str(e)}")
+                return {
+                    "error": str(e),
+                    "removed_files": 0,
+                    "failed_files": 0
+                }
+    
+    async def _clean_expired_files(self, now: float, total_size: int) -> Dict[str, Union[int, float]]:
+        """Clean expired files from the cache."""
+        count = 0
+        failed = 0
+        removed_size = 0
+        
+        # Process files but don't store them all in memory
+        for file_path in self.cache_dir.glob("*"):
+            if not file_path.is_file():
+                continue
+            
+            try:
+                mtime = os.path.getmtime(file_path)
+                file_age = now - mtime
+                
+                # Remove if expired
+                if file_age > self.max_age_seconds:
+                    file_size = file_path.stat().st_size
+                    path_str = str(file_path)
+                    is_recently_accessed = path_str in self._recently_accessed
+                    
+                    # Skip recently accessed files unless we're critically low on space
+                    if is_recently_accessed and total_size < (self.max_size_bytes * 0.9):
+                        continue
+                        
+                    # Remove file
+                    loop = asyncio.get_event_loop()
+                    await loop.run_in_executor(self._thread_pool, os.remove, file_path)
+                    count += 1
+                    removed_size += file_size
+                    total_size -= file_size
+                    
+                    # Remove from recently accessed if present
+                    if path_str in self._recently_accessed:
+                        del self._recently_accessed[path_str]
+            except OSError as e:
+                logger.error(f"Error accessing/removing file {file_path}: {str(e)}")
+                failed += 1
+        
+        return {
+            "removed": count,
+            "failed": failed,
+            "removed_size": removed_size,
+            "new_total_size": total_size
+        }
+    
+    async def _clean_by_size(self, total_size: int) -> Dict[str, Union[int, float]]:
+        """Clean files based on size limits, starting with the oldest."""
+        count = 0
+        failed = 0
+        removed_size = 0
+        
+        # Get files with their metadata
+        files_info = []
+        
+        for file_path in self.cache_dir.glob("*"):
+            if not file_path.is_file():
+                continue
+            
+            try:
+                path_str = str(file_path)
+                mtime = os.path.getmtime(file_path)
+                size = file_path.stat().st_size
+                is_recently_accessed = path_str in self._recently_accessed
+                
+                files_info.append({
+                    "path": file_path,
+                    "mtime": mtime,
+                    "size": size,
+                    "is_recently_accessed": is_recently_accessed
+                })
+            except OSError as e:
+                logger.error(f"Error accessing file {file_path}: {str(e)}")
+                failed += 1
+        
+        # Sort by recently accessed (preserve), then by age (oldest first)
+        files_info.sort(key=lambda x: (x["is_recently_accessed"], -x["mtime"]))
+        
+        # Remove files until we're under the size limit
+        for file_info in files_info:
+            if total_size <= self.max_size_bytes:
+                break
+                
+            file_path = file_info["path"]
+            file_size = file_info["size"]
+            path_str = str(file_path)
+            
+            # Skip recently accessed files unless we're critically low on space
+            if file_info["is_recently_accessed"] and total_size < (self.max_size_bytes * 0.9):
+                continue
+                
+            try:
+                # Remove file
+                loop = asyncio.get_event_loop()
+                await loop.run_in_executor(self._thread_pool, os.remove, file_path)
+                count += 1
+                removed_size += file_size
+                total_size -= file_size
+                
+                # Remove from recently accessed if present
+                if path_str in self._recently_accessed:
+                    del self._recently_accessed[path_str]
+            except OSError as e:
+                logger.error(f"Error removing cache file {file_path}: {str(e)}")
+                failed += 1
+        
+        return {
+            "removed": count,
+            "failed": failed, 
+            "removed_size": removed_size,
+            "new_total_size": total_size
+        }
+
+    async def start_periodic_cleanup(self, interval_seconds: int = 3600) -> None:
+        """Periodically clean the cache in the background."""
+        try:
+            while True:
+                await self.clean_cache()
+                await asyncio.sleep(interval_seconds)
+        except asyncio.CancelledError:
+            logger.info("Periodic cache cleanup task cancelled")
+            self._thread_pool.shutdown(wait=False)
+            raise
+        except Exception as e:
+            logger.error(f"Error in periodic cache cleanup: {str(e)}")
+            raise
+
+    async def _get_cache_size(self) -> int:
+        """Calculate the total size of the cache in bytes."""
+        try:
+            loop = asyncio.get_event_loop()
+            total_size = await loop.run_in_executor(
+                self._thread_pool, 
+                lambda: sum(f.stat().st_size for f in self.cache_dir.glob("*") if f.is_file())
+            )
+            return total_size
+        except Exception as e:
+            logger.error(f"Error calculating cache size: {str(e)}")
+            return 0
+
+    async def get_cache_stats(self) -> Dict[str, Union[int, float, str, List[str]]]:
+        """Return statistics about the cache, including file types and disk usage."""
+        try:
+            start_time = time.time()
+            total_files = 0
+            total_size = 0
+            oldest_file_age = 0
+            newest_file_age = float('inf')
+            now = time.time()
+            file_exts: Dict[str, int] = {}
+            for file_path in self.cache_dir.glob("*"):
+                if file_path.is_file():
+                    total_files += 1
+                    size = file_path.stat().st_size
+                    total_size += size
+                    ext = file_path.suffix.lower()
+                    file_exts[ext] = file_exts.get(ext, 0) + 1
+                    try:
+                        file_age = now - os.path.getmtime(file_path)
+                        oldest_file_age = max(oldest_file_age, file_age)
+                        newest_file_age = min(newest_file_age, file_age)
+                    except OSError:
+                        pass
+            disk_usage = self._get_disk_usage(self.cache_dir)
+            extensions = [f"{ext}: {count}" for ext, count in file_exts.items()]
+            process_time = time.time() - start_time
+            return {
+                "total_files": total_files,
+                "total_size_bytes": total_size,
+                "total_size_mb": round(total_size / (1024 * 1024), 2),
+                "cache_dir": str(self.cache_dir),
+                "max_age_seconds": self.max_age_seconds,
+                "max_size_mb": self.max_size_bytes // (1024 * 1024),
+                "oldest_file_age_hours": round(oldest_file_age / 3600, 1) if oldest_file_age > 0 else 0,
+                "newest_file_age_hours": round(newest_file_age / 3600, 1) if newest_file_age < float('inf') else 0,
+                "file_types": extensions,
+                "disk_usage": disk_usage,
+                "process_time_seconds": round(process_time, 3)
+            }
+        except Exception as e:
+            logger.error(f"Error getting cache stats: {str(e)}")
+            return {
+                "error": str(e),
+                "total_files": 0,
+                "total_size_bytes": 0
+            }
+
+    def _get_disk_usage(self, path: Path) -> Dict[str, Union[int, float]]:
+        """Get disk usage information for the given path."""
+        try:
+            usage = shutil.disk_usage(path)
+            return {
+                "total_bytes": usage.total,
+                "used_bytes": usage.used,
+                "free_bytes": usage.free,
+                "total_gb": round(usage.total / (1024**3), 2),
+                "used_gb": round(usage.used / (1024**3), 2),
+                "free_gb": round(usage.free / (1024**3), 2),
+                "percent_used": round((usage.used / usage.total) * 100, 1)
+            }
+        except Exception as e:
+            logger.error(f"Error getting disk usage: {str(e)}")
+            return {
+                "error": str(e)
+            }