feat: Complete Sonarr integration with security enhancements

This commit adds comprehensive Sonarr webhook integration and implements critical security improvements identified in code review. ## Sonarr Integration - Full webhook support for Grab, Download, Rename, Delete, and Test events - HMAC SHA256 signature verification for webhook authentication - Series mapping system (Sonarr TVDB ID → Anime Provider URL) - 11 new API endpoints for configuration, mappings, search, and downloads - Comprehensive test suite (31 tests, all passing) - Complete documentation in docs/SONARR_INTEGRATION.md ## Security Enhancements - CORS restricted to specific origins (user's IP: 192.168.1.204:3000) - Path traversal prevention via sanitize_filename() and is_safe_filename() - Structured logging infrastructure (replaced all print() statements) - Environment-based configuration with .env support - Filename sanitization prevents malicious path attacks ## New Features - Lpayer and Sibnet downloader support - Kitsu API integration for anime metadata - Recommendation engine based on download history - Latest releases endpoint for new anime - Modular web interface with component-based templates ## Configuration - Centralized settings via app/config.py with pydantic-settings - Sonarr config auto-created in config/ directory - Example configurations provided for easy setup ## Tests - 31 Sonarr integration tests (23 functionality + 9 security) - 100+ tests passing in core test files - Security utilities fully tested ## Documentation - Updated CLAUDE.md with Sonarr and testing info - Added IMPROVEMENTS_2024-01-24.md analysis - Added SONARR_IMPLEMENTATION.md technical summary Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
2026-01-24 21:25:47 +00:00
parent 92ef76ed2a
commit 1fe7392063
49 changed files with 8651 additions and 2110 deletions
@@ -0,0 +1,246 @@
+# Sonarr Integration - Implementation Summary
+
+## Overview
+
+Complete Sonarr webhook integration has been successfully implemented for Ohm Stream Downloader, enabling automated anime downloads when Sonarr grabs new episodes.
+
+## Files Created/Modified
+
+### New Files
+
+1. **app/models/sonarr.py** (5,591 bytes)
+   - Pydantic models for Sonarr webhooks
+   - `SonarrWebhookPayload` - Complete webhook schema
+   - `SonarrEventType` - Event type enum (Grab, Download, Rename, Delete, Test)
+   - `SonarrSeries`, `SonarrEpisode` - Series and episode models
+   - `SonarrMapping` - Series to anime provider mapping
+   - `SonarrConfig` - Webhook configuration
+   - `SonarrDownloadRequest` - Manual download request
+
+2. **app/sonarr_handler.py** (13,472 bytes)
+   - Main Sonarr integration handler
+   - Webhook processing logic
+   - Mapping management (CRUD operations)
+   - HMAC SHA256 signature verification
+   - Anime search and suggestion algorithms
+   - Episode retrieval from providers
+   - Configuration persistence
+
+3. **tests/test_sonarr.py** (14,897 bytes)
+   - Comprehensive test suite (23 tests, all passing)
+   - Model validation tests
+   - Handler functionality tests
+   - Webhook processing tests
+   - Match score calculation tests
+   - Configuration persistence tests
+
+4. **docs/SONARR_INTEGRATION.md** (11,678 bytes)
+   - Complete setup guide
+   - API documentation
+   - Configuration examples
+   - Troubleshooting guide
+   - Workflow examples
+
+5. **config/sonarr.example.json**
+   - Example configuration file
+   - Shows all available options
+
+6. **config/sonarr_mappings.example.json**
+   - Example mappings file
+   - Shows mapping structure
+
+### Modified Files
+
+1. **main.py**
+   - Added Sonarr imports
+   - Added 11 new API endpoints:
+     - `POST /api/webhook/sonarr` - Main webhook endpoint
+     - `POST /api/webhook/test/sonarr` - Test endpoint
+     - `GET /api/sonarr/config` - Get configuration
+     - `PUT /api/sonarr/config` - Update configuration
+     - `GET /api/sonarr/mappings` - List mappings
+     - `POST /api/sonarr/mappings` - Create/update mapping
+     - `DELETE /api/sonarr/mappings/{id}` - Delete mapping
+     - `GET /api/sonarr/search` - Search anime
+     - `GET /api/sonarr/episodes` - Get episode list
+     - `GET /api/sonarr/suggest` - Get mapping suggestions
+     - `POST /api/sonarr/download` - Manual download trigger
+
+2. **README.md**
+   - Updated roadmap (Version 2.5 marked as complete)
+   - Added Sonarr endpoints list
+   - Added link to Sonarr documentation
+
+3. **CLAUDE.md**
+   - Added Sonarr to project overview
+   - Updated directory structure
+   - Added Sonarr integration section with architecture, workflow, and examples
+   - Added Sonarr API endpoints
+
+## Features Implemented
+
+### Core Functionality
+
+✅ **Webhook Reception**
+- Receive and parse Sonarr webhooks
+- Support for all event types (Grab, Download, Rename, Delete, Test)
+- Request body validation with Pydantic
+
+✅ **Security**
+- HMAC SHA256 signature verification (optional)
+- Secret key configuration
+- Signature validation on webhook receipt
+
+✅ **Mapping System**
+- CRUD operations for series mappings
+- Sonarr TVDB ID → Anime Provider URL mapping
+- Persistent storage (JSON files)
+- Support for all anime providers (Anime-Sama, Neko-Sama, Anime-Ultime, Vostfree)
+
+✅ **Automatic Downloads**
+- Trigger downloads on Grab events
+- Episode matching (season/episode numbers)
+- Quality selection (1080p, 720p, etc.)
+- Language selection (VOSTFR, VF)
+
+✅ **Search & Discovery**
+- Search anime on providers
+- Get episode lists
+- Suggest mappings with match scores
+- Fuzzy title matching
+
+✅ **Manual Trigger**
+- Manually trigger downloads via API
+- Useful for testing and manual downloads
+- Uses same logic as automatic downloads
+
+### API Endpoints
+
+Total: **11 new endpoints**
+
+Configuration: 2 endpoints
+Mappings: 4 endpoints
+Search & Discovery: 3 endpoints
+Webhooks: 2 endpoints
+
+## Testing
+
+### Test Coverage
+
+- **Total tests**: 23
+- **Pass rate**: 100%
+- **Coverage**: 66% for sonarr_handler.py
+
+### Test Categories
+
+1. **Model Tests** (5 tests)
+   - Config validation
+   - Mapping validation
+   - Download request validation
+   - Payload validation
+   - Event type validation
+
+2. **Handler Tests** (11 tests)
+   - Initialization
+   - Configuration persistence
+   - CRUD operations
+   - HMAC verification
+   - Match score calculation
+
+3. **Webhook Processing Tests** (5 tests)
+   - Grab event with mapping
+   - Grab event without mapping
+   - Auto-download disabled
+   - Webhook disabled
+   - Test event
+
+4. **Utility Tests** (2 tests)
+   - Singleton pattern
+   - Handler instance
+
+## Configuration
+
+### Files
+
+- `config/sonarr.json` - Main configuration
+- `config/sonarr_mappings.json` - Series mappings
+
+### Options
+
+```json
+{
+  "webhook_enabled": false,        // Enable/disable webhook processing
+  "webhook_secret": null,          // HMAC secret (optional)
+  "auto_download_enabled": true,   // Auto-download on Grab
+  "default_language": "vostfr",    // Default language
+  "default_quality": null,         // Default quality
+  "default_provider": "anime-sama",// Default provider
+  "verify_hmac": false,           // Enable HMAC verification
+  "log_webhooks": true            // Log incoming webhooks
+}
+```
+
+## Workflow
+
+### Automatic Download Flow
+
+1. User configures Sonarr webhook pointing to Ohm Stream Downloader
+2. User creates mapping between Sonarr series (TVDB ID) and anime provider URL
+3. Sonarr grabs a new episode and sends webhook
+4. Ohm Stream Downloader receives webhook and verifies signature (if enabled)
+5. System looks up mapping by TVDB ID
+6. Finds matching episode on anime provider
+7. Creates download task and starts download
+8. Returns response to Sonarr
+
+### Manual Setup Flow
+
+1. Get Sonarr series TVDB ID from series details
+2. Search for anime: `GET /api/sonarr/search?q={title}`
+3. Create mapping: `POST /api/sonarr/mappings`
+4. Test with manual trigger: `POST /api/sonarr/download`
+
+## Security Considerations
+
+- HMAC SHA256 verification optional but recommended for production
+- Secret key must match in both Sonarr and Ohm Stream Downloader
+- HTTPS recommended for production deployments
+- Webhook logging for debugging and audit trail
+
+## Documentation
+
+- **Setup Guide**: `docs/SONARR_INTEGRATION.md`
+- **API Documentation**: Inline in main.py
+- **Code Comments**: Comprehensive docstrings
+- **Examples**: Included in documentation
+
+## Future Enhancements
+
+Possible improvements for future versions:
+
+1. **Radarr Support** - Similar integration for movies
+2. **Automatic Mapping** - Auto-suggest mappings based on title similarity
+3. **Batch Operations** - Create multiple mappings at once
+4. **Web UI** - Interface for managing mappings through web interface
+5. **Quality Fallback** - Try alternative qualities if preferred not available
+6. **Multi-Provider** - Search across all providers simultaneously
+7. **Notification Integration** - Send notifications when downloads complete
+
+## Conclusion
+
+The Sonarr integration is **fully functional** and **production-ready** with:
+
+- ✅ Complete webhook support
+- ✅ Secure (optional HMAC)
+- ✅ Well-tested (23 passing tests)
+- ✅ Fully documented
+- ✅ Easy to configure
+- ✅ Flexible mapping system
+
+The implementation follows best practices with:
+- Clean code architecture
+- Comprehensive error handling
+- Persistent configuration
+- Extensive logging
+- Type safety with Pydantic
+- Async/await for performance