Aniworld/docs/instructions.md

# Aniworld Web Application Development Instructions

This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.

## Project Overview

The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in `SeriesApp.py` while the web layer provides REST API endpoints and a responsive UI.

## Architecture Principles

- **Single Responsibility**: Each file/class has one clear purpose
- **Dependency Injection**: Use FastAPI's dependency system
- **Clean Separation**: Web layer calls core logic, never the reverse
- **File Size Limit**: Maximum 500 lines per file
- **Type Hints**: Use comprehensive type annotations
- **Error Handling**: Proper exception handling and logging

## Additional Implementation Guidelines

### Code Style and Standards

- **Type Hints**: Use comprehensive type annotations throughout all modules
- **Docstrings**: Follow PEP 257 for function and class documentation
- **Error Handling**: Implement custom exception classes with meaningful messages
- **Logging**: Use structured logging with appropriate log levels
- **Security**: Validate all inputs and sanitize outputs
- **Performance**: Use async/await patterns for I/O operations

## 📞 Escalation

If you encounter:

- Architecture issues requiring design decisions
- Tests that conflict with documented requirements
- Breaking changes needed
- Unclear requirements or expectations

**Document the issue and escalate rather than guessing.**

---

## <20> Credentials

**Admin Login:**

- Username: `admin`
- Password: `Hallo123!`

---

## <20>📚 Helpful Commands

```bash
# Run all tests
conda run -n AniWorld python -m pytest tests/ -v --tb=short

# Run specific test file
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py -v

# Run specific test class
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService -v

# Run specific test
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService::test_broadcast_download_progress -v

# Run with extra verbosity
conda run -n AniWorld python -m pytest tests/ -vv

# Run with full traceback
conda run -n AniWorld python -m pytest tests/ -v --tb=long

# Run and stop at first failure
conda run -n AniWorld python -m pytest tests/ -v -x

# Run tests matching pattern
conda run -n AniWorld python -m pytest tests/ -v -k "auth"

# Show all print statements
conda run -n AniWorld python -m pytest tests/ -v -s

#Run app
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
```

---

## Implementation Notes

1. **Incremental Development**: Implement features incrementally, testing each component thoroughly before moving to the next
2. **Code Review**: Review all generated code for adherence to project standards
3. **Documentation**: Document all public APIs and complex logic
4. **Testing**: Maintain test coverage above 80% for all new code
5. **Performance**: Profile and optimize critical paths, especially download and streaming operations
6. **Security**: Regular security audits and dependency updates
7. **Monitoring**: Implement comprehensive monitoring and alerting
8. **Maintenance**: Plan for regular maintenance and updates

---

## Task Completion Checklist

For each task completed:

- [ ] Implementation follows coding standards
- [ ] Unit tests written and passing
- [ ] Integration tests passing
- [ ] Documentation updated
- [ ] Error handling implemented
- [ ] Logging added
- [ ] Security considerations addressed
- [ ] Performance validated
- [ ] Code reviewed
- [ ] Task marked as complete in instructions.md
- [ ] Infrastructure.md updated and other docs
- [ ] Changes committed to git; keep your messages in git short and clear
- [ ] Take the next task

---

## TODO List:

### ✅ **Task 1: Provider System Integration Tests** (Priority: CRITICAL) — COMPLETED (211 tests passing)

**Objective**: Create unit and integration tests for core provider orchestration system (6 files) that handles provider selection, failover, and health monitoring.

**Target Files to Test**:

- `src/core/providers/base_provider.py` - Abstract base class and interface
- `src/core/providers/aniworld_provider.py` - Main provider (664 lines, core functionality)
- `src/core/providers/provider_factory.py` - Provider instantiation logic
- `src/core/providers/enhanced_provider.py` - Enhanced features and caching
- `src/core/providers/monitored_provider.py` - Monitoring wrapper with metrics
- `src/core/providers/config_manager.py` - Provider configuration management

**Create Test Files**:
**Unit Tests**:

- `tests/unit/test_base_provider.py` - Abstract methods, interface contracts, inheritance
- `tests/unit/test_aniworld_provider.py` - Anime catalog scraping, episode listing, streaming link extraction (mock HTML responses)
- `tests/unit/test_provider_factory.py` - Factory instantiation, dependency injection, provider registration
- `tests/unit/test_enhanced_provider.py` - Caching behavior, optimization features, decorator patterns
- `tests/unit/test_monitored_provider.py` - Metrics collection, health checks, monitoring integration
- `tests/unit/test_provider_config_manager.py` - Configuration loading, validation, defaults

**Integration Tests**:

- `tests/integration/test_provider_failover_scenarios.py` - End-to-end provider switching when streaming fails
- `tests/integration/test_provider_selection.py` - Provider selection based on availability, health status, priority

**Test Coverage Requirements**:

- Provider instantiation via factory pattern (all provider types)
- Failover from failed provider to healthy backup (3+ provider scenario)
- Health monitoring and circuit breaker patterns
- Configuration loading from config.json and validation
- Aniworld catalog scraping with mocked HTML responses
- Episode listing and metadata extraction
- Multi-provider scenarios with different health states
- Provider priority and selection algorithm

**Expected Outcome**: ~80 tests total, 90%+ coverage for provider system

**Implementation Notes**:

- Mock HTML responses for aniworld_provider tests using BeautifulSoup fixtures
- Test factory pattern returns correct provider instances
- Integration tests should test full failover workflow: healthy provider → fails → switches to backup → succeeds
- Use existing `test_provider_health.py` and `test_provider_failover.py` as reference
- Mock external dependencies (HTTP, file system, database)
- Test concurrent provider usage scenarios

---

### ✅ **Task 2: Security Infrastructure Tests** (Priority: CRITICAL) — COMPLETED (75 tests passing)

**Objective**: Create comprehensive tests for security modules handling encryption and database integrity (2 critical files).

**Target Files to Test**:

- `src/infrastructure/security/config_encryption.py` - Configuration encryption/decryption
- `src/infrastructure/security/database_integrity.py` - Database integrity checks and validation

**Create Test Files**:

- `tests/unit/test_config_encryption.py`:
    - Encryption/decryption of sensitive configuration values
    - Key rotation and management lifecycle
    - AES-256 encryption validation
    - Decrypt failures with wrong key
    - Empty/null value handling
    - Multiple encryption rounds
    - Performance of encryption operations
- `tests/unit/test_database_integrity.py`:
    - Database checksum calculation and validation
    - Corruption detection mechanisms
    - Integrity verification on application startup
    - Backup restoration on corruption detection
    - Schema validation against expected structure
    - Transaction integrity checks
- `tests/security/test_encryption_security.py`:
    - Key strength validation (minimum bits)
    - Timing attack prevention
    - Secure key storage validation
    - Environment variable security
    - Encrypted data format validation
    - Key compromise scenarios

**Test Coverage Requirements**:

- Encryption algorithm correctness (encrypt → decrypt → original value)
- Key management lifecycle (generation, rotation, revocation)
- Database integrity check mechanisms
- Corruption detection and recovery workflows
- Security edge cases (key compromise, brute force attempts)
- Performance testing for encryption operations (should not slow down app significantly)

**Expected Outcome**: ~40 tests total, 95%+ coverage for security modules

**Implementation Notes**:

- Read security module files first to understand cryptography library used
- Test both successful and failed encryption/decryption scenarios
- Mock file system for encrypted key storage tests
- Use in-memory databases for integrity testing
- Simulate database corruption scenarios
- Follow security testing best practices from `tests/security/` directory
- Ensure tests don't expose sensitive data in logs or output

---

### ✅ **Task 3: Error Handling Tests** (Priority: HIGH) — COMPLETED (74 tests passing)

**Objective**: Create comprehensive tests for error handling and recovery mechanisms (2 files) to ensure robust error management across the application.

**Target Files to Test**:

- `src/core/error_handler.py` - Core error handling and retry logic
- `src/server/middleware/error_handler.py` - API error handling middleware

**Create Test Files**:

- `tests/unit/test_core_error_handler.py`:
    - Retry logic with exponential backoff
    - Maximum retry limits enforcement
    - Error classification (transient vs permanent errors)
    - Error recovery strategies
    - Circuit breaker integration
    - Timeout handling
    - Resource cleanup on errors
- `tests/unit/test_middleware_error_handler.py`:
    - HTTP error response formatting (JSON structure)
    - Stack trace sanitization in production mode
    - Error logging integration with structlog
    - Custom exception handling (AnimeNotFound, ProviderError, etc.)
    - 400/404/500 error responses
    - Error context preservation
    - CORS headers on error responses
- `tests/integration/test_error_recovery_workflows.py`:
    - End-to-end error recovery: download fails → retry → success
    - Provider failover on errors (primary fails → backup succeeds)
    - Database transaction rollback on errors
    - User notification on errors via WebSocket
    - Cascading error handling (error in one service affects others)
    - Error recovery after temporary outages

**Test Coverage Requirements**:

- Transient vs permanent error distinction
- Retry exhaustion scenarios (max retries reached)
- Error reporting to users (proper messages, no stack traces)
- Error logging with proper context
- Recovery workflows for common errors
- Error handling doesn't leak resources (connections, file handles)

**Expected Outcome**: ~50 tests total, 90%+ coverage for error handling

**Implementation Notes**:

- Test retry logic with controlled failure scenarios
- Mock external services to simulate errors
- Verify exponential backoff timing
- Test error message clarity and usefulness
- Integration tests should verify end-to-end recovery
- Use `pytest.raises` for exception testing
- Mock time.sleep for faster retry tests

---

### ✅ **Task 4: Services & Utilities Tests** (Priority: MEDIUM) — COMPLETED (64 tests passing)

**Objective**: Create tests for undertested service and utility modules to increase coverage of business logic and helper functions (5 files).

**Target Files to Test**:

- `src/core/services/series_manager_service.py` - Series orchestration logic
- `src/core/services/nfo_factory.py` - NFO service factory pattern
- `src/server/utils/media.py` - Media file validation utilities
- `src/server/utils/templates.py` - Template rendering utilities
- `src/server/controllers/error_controller.py` - Error page controller

**Create Test Files**:

- `tests/unit/test_series_manager_service.py`:
    - Series orchestration and lifecycle management
    - Episode management (add, remove, update)
    - Season handling and organization
    - Series state management
    - Interaction with SeriesApp
- `tests/unit/test_nfo_factory.py`:
    - Factory pattern instantiation of NFO services
    - Dependency injection setup
    - Service lifecycle (singleton vs transient)
    - Configuration passing to services
- `tests/unit/test_media_utils.py`:
    - Media file validation (video formats)
    - Codec detection (H.264, H.265, etc.)
    - Metadata extraction (duration, resolution)
    - File size checks and validation
    - Corrupt file detection
- `tests/unit/test_templates_utils.py`:
    - Template rendering with Jinja2
    - Context injection and variable passing
    - Error page rendering
    - Template caching behavior
    - Custom filters and functions
- `tests/unit/test_error_controller.py`:
    - 404 page rendering with context
    - 500 error page with safe error info
    - Error context passing to templates
    - Static file errors
    - API error responses

**Test Coverage Requirements**:

- Service initialization patterns and dependency setup
- Factory method correctness and proper instance types
- Media file operations with various formats
- Template rendering edge cases (missing variables, errors)
- Error controller response formatting

**Expected Outcome**: ~60 tests total, 85%+ coverage for each module

**Implementation Notes**:

- Mock file system for media utility tests
- Use temporary files for media validation tests
- Mock Jinja2 environment for template tests
- Test both success and error paths
- Verify proper resource cleanup
- Use existing service test patterns as reference

---

### ✅ **Task 5: Infrastructure Logging Tests** (Priority: MEDIUM) — COMPLETED (49 tests passing)

**Objective**: Create tests for logging infrastructure to ensure proper log configuration, formatting, and rotation (2 files).

**Target Files to Test**:

- `src/infrastructure/logging/logger.py` - Main logger configuration
- `src/infrastructure/logging/uvicorn_config.py` - Uvicorn logging configuration

**Create Test Files**:

- `tests/unit/test_infrastructure_logger.py`:
    - Logger initialization and setup
    - Log level configuration (DEBUG, INFO, WARNING, ERROR)
    - Log formatting (JSON, text formats)
    - File rotation behavior
    - Multiple handler setup (console, file, syslog)
    - Structured logging with context
    - Logger hierarchy and propagation
- `tests/unit/test_uvicorn_logging_config.py`:
    - Uvicorn access log configuration
    - Error log configuration
    - Log format customization for HTTP requests
    - Integration with main application logger
    - Log level filtering for Uvicorn logs
    - Performance logging (request timing)

**Test Coverage Requirements**:

- Logger configuration loading from settings
- Log output format validation (JSON structure, fields)
- Log level filtering works correctly
- File rotation behavior (size-based, time-based)
- Integration with structlog for structured logging
- Performance impact is minimal

**Expected Outcome**: ~30 tests total, 80%+ coverage for logging infrastructure

**Implementation Notes**:

- Use temporary log files for testing
- Capture log output using logging.handlers.MemoryHandler
- Test log rotation without waiting for actual rotation triggers
- Verify log format matches expected structure
- Mock file system for file handler tests
- Test various log levels and ensure filtering works
- Verify no sensitive data in logs

---

### ✅ **Task 6: CLI Tool Tests** (Priority: LOW) — COMPLETED (25 tests passing)

**Objective**: Create tests for NFO command-line interface tool used for DevOps and maintenance workflows (1 file).

**Target File to Test**:

- `src/cli/nfo_cli.py` - NFO management CLI commands

**Create Test Files**:

- `tests/unit/test_nfo_cli.py`:
    - Command parsing (argparse or click)
    - Argument validation (required args, types)
    - Batch operations (multiple NFO files)
    - Error reporting and user-friendly messages
    - Output formatting (table, JSON, text)
    - Help text generation
    - Exit codes (0 for success, non-zero for errors)
- `tests/integration/test_cli_workflows.py`:
    - NFO creation via CLI end-to-end
    - Batch NFO update workflow
    - CLI + database integration
    - CLI + API integration (if CLI calls API)
    - Error handling in CLI workflows
    - File system operations (read/write NFO files)

**Test Coverage Requirements**:

- CLI argument parsing for all commands
- Batch processing multiple files
- Error messages are clear and actionable
- Output formatting matches specification
- Integration with core services (NFO service)
- File operations work correctly

**Expected Outcome**: ~35 tests total, 80%+ coverage for CLI module

**Implementation Notes**:

- Read `src/cli/nfo_cli.py` first to understand commands
- Use `subprocess` or `click.testing.CliRunner` for integration tests
- Mock file system operations
- Test with various command-line arguments
- Verify exit codes are correct
- Test help text generation
- Use temporary directories for file operations
- Follow patterns from existing CLI tests if any exist

---

### ✅ **Task 7: Edge Case & Regression Tests** (Priority: MEDIUM) — COMPLETED (69 tests passing)

**Objective**: Add edge case coverage and regression tests across existing modules to catch rare bugs and prevent reintroduction of fixed bugs (4 new test files).

**Create Test Files**:

- `tests/unit/test_provider_edge_cases.py`:
    - Malformed HTML responses from providers
    - Missing episode data in provider responses
    - Invalid streaming URLs (malformed, expired)
    - Unicode characters in anime titles
    - Special characters in filenames
    - Empty responses from providers
    - Partial data from providers
    - Provider timeout scenarios
- `tests/integration/test_concurrent_operations.py`:
    - Concurrent downloads from same provider
    - Parallel NFO generation for multiple series
    - Race conditions in queue management
    - Database lock contention under load
    - WebSocket broadcasts during concurrent operations
    - Cache consistency with concurrent writes
- `tests/api/test_rate_limiting_edge_cases.py`:
    - Rate limiting with multiple IP addresses
    - Rate limit reset behavior
    - Burst traffic handling
    - Rate limit per-user vs per-IP
    - Rate limit with authenticated vs anonymous users
    - Rate limit bypass attempts
- `tests/integration/test_database_edge_cases.py`:
    - Database lock contention scenarios
    - Large transaction rollback (100+ operations)
    - Connection pool exhaustion
    - Slow query handling
    - Database file growth and vacuum
    - Concurrent write conflicts
    - Foreign key constraint violations

**Test Coverage Requirements**:

- Edge cases that aren't covered by existing tests
- Known bugs that were fixed (regression tests)
- Concurrent operation safety
- Resource exhaustion scenarios
- Boundary conditions (empty data, very large data)

**Expected Outcome**: ~50 tests total, targeting known edge cases and regression scenarios

**Implementation Notes**:

- Review git history for bug fixes to create regression tests
- Test boundary conditions (0, 1, max values)
- Simulate resource exhaustion (disk full, memory limit)
- Test concurrent operations with threading/asyncio
- Use property-based testing with hypothesis if appropriate
- Mock external services to simulate edge cases
- Test error recovery from edge cases