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.**

---

## 📚 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
-   [ ] Changes committed to git; keep your messages in git short and clear
-   [ ] Take the next task

---

### Prerequisites

1. Server is running: `conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload`
2. Password: `Hallo123!`
3. Login via browser at `http://127.0.0.1:8000/login`

### Notes

-   This is a simplification that removes complexity while maintaining core functionality
-   Improves user experience with explicit manual control
-   Easier to understand, test, and maintain
-   Good foundation for future enhancements if needed

---

---

## Task: Add Database Transaction Support

### Objective

Implement proper transaction handling across all database write operations using SQLAlchemy's transaction support. This ensures data consistency and prevents partial writes during compound operations.

### Background

Currently, the application uses SQLAlchemy sessions with auto-commit behavior through the `get_db_session()` generator. While individual operations are atomic, compound operations (multiple writes) can result in partial commits if an error occurs mid-operation.

### Requirements

1. **All database write operations must be wrapped in explicit transactions**
2. **Compound operations must be atomic** - either all writes succeed or all fail
3. **Nested operations should use savepoints** for partial rollback capability
4. **Existing functionality must not break** - backward compatible changes only
5. **All tests must pass after implementation**

---

## Task: Graceful Shutdown Implementation ✅ COMPLETED

### Objective

Implement proper graceful shutdown handling so that Ctrl+C (SIGINT) or SIGTERM triggers a clean shutdown sequence that terminates all concurrent processes and prevents database corruption.

### Background

The application runs multiple concurrent services (WebSocket connections, download service with ThreadPoolExecutor, database sessions) that need to be properly cleaned up during shutdown. Without graceful shutdown, active downloads may corrupt state, database writes may be incomplete, and WebSocket clients won't receive disconnect notifications.

### Implementation Summary

The following components were implemented:

#### 1. WebSocket Service Shutdown ([src/server/services/websocket_service.py](src/server/services/websocket_service.py))

-   Added `shutdown()` method to `ConnectionManager` that:
    -   Broadcasts `{"type": "server_shutdown"}` notification to all connected clients
    -   Gracefully closes each WebSocket connection with code 1001 (Going Away)
    -   Clears all connection tracking data structures
    -   Supports configurable timeout (default 5 seconds)
-   Added `shutdown()` method to `WebSocketService` that delegates to the manager

#### 2. Download Service Stop ([src/server/services/download_service.py](src/server/services/download_service.py))

-   Enhanced `stop()` method to:
    -   Persist active downloads back to "pending" status in database (allows resume on restart)
    -   Cancel active download tasks with proper timeout handling
    -   Shutdown ThreadPoolExecutor with `wait=True` and configurable timeout (default 10 seconds)
    -   Fall back to forced shutdown if timeout expires

#### 3. FastAPI Lifespan Shutdown ([src/server/fastapi_app.py](src/server/fastapi_app.py))

-   Expanded shutdown sequence in proper order:
    1. Broadcast shutdown notification via WebSocket
    2. Stop download service and persist state
    3. Clean up progress service (clear subscribers and active progress)
    4. Close database connections with WAL checkpoint
-   Added timeout protection (30 seconds total) with remaining time tracking
-   Each step has individual timeout to prevent hanging

#### 4. Uvicorn Graceful Shutdown ([run_server.py](run_server.py))

-   Added `timeout_graceful_shutdown=30` parameter to uvicorn.run()
-   Ensures uvicorn allows sufficient time for lifespan shutdown to complete
-   Updated docstring to document Ctrl+C behavior

#### 5. Stop Script ([stop_server.sh](stop_server.sh))

-   Replaced `kill -9` (SIGKILL) with `kill -TERM` (SIGTERM)
-   Added `wait_for_process()` function that waits up to 30 seconds for graceful shutdown
-   Only falls back to SIGKILL if graceful shutdown times out
-   Improved user feedback during shutdown process

#### 6. Database WAL Checkpoint ([src/server/database/connection.py](src/server/database/connection.py))

-   Enhanced `close_db()` to run `PRAGMA wal_checkpoint(TRUNCATE)` for SQLite
-   Ensures all pending WAL writes are flushed to main database file
-   Prevents database corruption during shutdown

### How Graceful Shutdown Works

1. **Ctrl+C or SIGTERM received** → uvicorn catches signal
2. **uvicorn triggers lifespan shutdown** → FastAPI's lifespan context manager exits
3. **WebSocket broadcast** → All connected clients receive shutdown notification
4. **Download service stops** → Active downloads persisted, executor shutdown
5. **Progress service cleanup** → Event subscribers cleared
6. **Database cleanup** → WAL checkpoint, connections disposed
7. **Process exits cleanly** → No data loss or corruption

### Testing

```bash
# Start server
conda run -n AniWorld python run_server.py

# Press Ctrl+C to trigger graceful shutdown
# Or use the stop script:
./stop_server.sh
```

### Verification

-   All existing tests pass (websocket, download service, database transactions)
-   WebSocket clients receive disconnect notification before connection closes
-   Active downloads are preserved and can resume on restart
-   SQLite WAL file is checkpointed before shutdown

---