qBitrr2 5.4.5__py3-none-any.whl → 5.5.0__py3-none-any.whl

qBitrr/bundled_data.py

@@ -1,5 +1,5 @@
-version = "5.4.5"
-git_hash = "155d9043"
+version = "5.5.0"
+git_hash = "fa9061aa"
 license_text = (
     "Licence can be found on:\n\nhttps://github.com/Feramance/qBitrr/blob/master/LICENSE"
 )

qBitrr/config_version.py

@@ -0,0 +1,144 @@
+"""Configuration version management for qBitrr.
+
+This module manages config schema versioning and migrations.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from qBitrr.gen_config import MyConfig
+
+# Current expected config version - increment when schema changes require migration
+EXPECTED_CONFIG_VERSION = 3
+
+logger = logging.getLogger(__name__)
+
+
+def get_config_version(config: MyConfig) -> int:
+    """
+    Get the ConfigVersion from the config file.
+
+    Args:
+        config: MyConfig instance
+
+    Returns:
+        Config version as integer, defaults to 1 if not found
+    """
+    version = config.get("Settings.ConfigVersion", fallback=1)
+    try:
+        return int(version)
+    except (ValueError, TypeError):
+        logger.warning(f"Invalid ConfigVersion value: {version}, defaulting to 1")
+        return 1
+
+
+def set_config_version(config: MyConfig, version: int) -> None:
+    """
+    Set the ConfigVersion in the config file.
+
+    Args:
+        config: MyConfig instance
+        version: Version number to set
+    """
+    if "Settings" not in config.config:
+        from tomlkit import table
+
+        config.config["Settings"] = table()
+
+    config.config["Settings"]["ConfigVersion"] = version
+    logger.info(f"Set ConfigVersion to {version}")
+
+
+def validate_config_version(config: MyConfig) -> tuple[bool, str | None]:
+    """
+    Validate config version and determine if migration is needed.
+
+    Args:
+        config: MyConfig instance
+
+    Returns:
+        Tuple of (is_valid, error_message)
+        - (True, None): Config version matches expected
+        - (True, "migration_needed"): Config version is older, migration required
+        - (False, error_msg): Config version is newer, show error to user
+    """
+    current_version = get_config_version(config)
+
+    if current_version == EXPECTED_CONFIG_VERSION:
+        logger.debug(f"Config version matches expected: {EXPECTED_CONFIG_VERSION}")
+        return True, None
+
+    if current_version < EXPECTED_CONFIG_VERSION:
+        logger.info(
+            f"Config version {current_version} is older than expected {EXPECTED_CONFIG_VERSION}, "
+            "migration needed"
+        )
+        return True, "migration_needed"
+
+    # Config version is newer than expected
+    error_msg = (
+        f"Config version mismatch: found {current_version}, expected {EXPECTED_CONFIG_VERSION}. "
+        f"Your config may have been created with a newer version of qBitrr and may not work correctly. "
+        f"Please update qBitrr or restore a compatible config backup."
+    )
+    logger.error(error_msg)
+    return False, error_msg
+
+
+def backup_config(config_path: Path) -> Path | None:
+    """
+    Create a timestamped backup of the config file.
+
+    Args:
+        config_path: Path to config.toml
+
+    Returns:
+        Path to backup file, or None if backup failed
+    """
+    if not config_path.exists():
+        logger.warning(f"Config file not found for backup: {config_path}")
+        return None
+
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    backup_path = config_path.parent / f"{config_path.stem}.backup.{timestamp}{config_path.suffix}"
+
+    try:
+        import shutil
+
+        shutil.copy2(config_path, backup_path)
+        logger.info(f"Created config backup: {backup_path}")
+        return backup_path
+    except Exception as e:
+        logger.error(f"Failed to create config backup: {e}")
+        return None
+
+
+def restore_config_backup(backup_path: Path, config_path: Path) -> bool:
+    """
+    Restore config from a backup file.
+
+    Args:
+        backup_path: Path to backup file
+        config_path: Path to config.toml
+
+    Returns:
+        True if restore succeeded, False otherwise
+    """
+    if not backup_path.exists():
+        logger.error(f"Backup file not found: {backup_path}")
+        return False
+
+    try:
+        import shutil
+
+        shutil.copy2(backup_path, config_path)
+        logger.info(f"Restored config from backup: {backup_path}")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to restore config from backup: {e}")
+        return False

qBitrr/db_lock.py

@@ -77,3 +77,192 @@ def database_lock() -> Iterator[None]:
     """Provide a shared lock used to serialize SQLite access across processes."""
     with _DB_LOCK.context():
         yield
+
+
+def with_database_retry(
+    func,
+    *,
+    retries: int = 5,
+    backoff: float = 0.5,
+    max_backoff: float = 10.0,
+    jitter: float = 0.25,
+    logger=None,
+):
+    """
+    Execute database operation with retry logic for transient I/O errors.
+
+    Catches:
+    - sqlite3.OperationalError (disk I/O, database locked)
+    - sqlite3.DatabaseError (corruption that may resolve)
+
+    Does NOT retry:
+    - sqlite3.IntegrityError (data constraint violations)
+    - sqlite3.ProgrammingError (SQL syntax errors)
+
+    Args:
+        func: Callable to execute (should take no arguments)
+        retries: Maximum number of retry attempts (default: 5)
+        backoff: Initial backoff delay in seconds (default: 0.5)
+        max_backoff: Maximum backoff delay in seconds (default: 10.0)
+        jitter: Random jitter added to delay in seconds (default: 0.25)
+        logger: Logger instance for logging retry attempts
+
+    Returns:
+        Result of func() if successful
+
+    Raises:
+        sqlite3.OperationalError or sqlite3.DatabaseError if retries exhausted
+    """
+    import random
+    import sqlite3
+    import time
+
+    attempt = 0
+    while True:
+        try:
+            return func()
+        except (sqlite3.OperationalError, sqlite3.DatabaseError) as e:
+            error_msg = str(e).lower()
+
+            # Don't retry on non-transient errors
+            if "syntax" in error_msg or "constraint" in error_msg:
+                raise
+
+            attempt += 1
+            if attempt >= retries:
+                if logger:
+                    logger.error(
+                        "Database operation failed after %s attempts: %s",
+                        retries,
+                        e,
+                    )
+                raise
+
+            delay = min(max_backoff, backoff * (2 ** (attempt - 1)))
+            delay += random.random() * jitter
+
+            if logger:
+                logger.warning(
+                    "Database I/O error (attempt %s/%s): %s. Retrying in %.2fs",
+                    attempt,
+                    retries,
+                    e,
+                    delay,
+                )
+
+            time.sleep(delay)
+
+
+class ResilientSqliteDatabase:
+    """
+    Wrapper for Peewee SqliteDatabase that adds retry logic to connection attempts.
+
+    This solves the issue where disk I/O errors occur during database connection
+    (specifically when setting PRAGMAs), before query-level retry logic can help.
+    """
+
+    def __init__(self, database, max_retries=5, backoff=0.5):
+        """
+        Args:
+            database: Peewee SqliteDatabase instance to wrap
+            max_retries: Maximum connection retry attempts
+            backoff: Initial backoff delay in seconds
+        """
+        self._db = database
+        self._max_retries = max_retries
+        self._backoff = backoff
+
+    def __getattr__(self, name):
+        """Delegate all attribute access to the wrapped database."""
+        return getattr(self._db, name)
+
+    def connect(self, reuse_if_open=False):
+        """
+        Connect to database with retry logic for transient I/O errors.
+
+        Args:
+            reuse_if_open: If True, return without error if already connected
+
+        Returns:
+            Result from underlying database.connect()
+        """
+        import random
+        import sqlite3
+        import time
+
+        from peewee import DatabaseError, OperationalError
+
+        last_error = None
+        delay = self._backoff
+
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                return self._db.connect(reuse_if_open=reuse_if_open)
+            except (OperationalError, DatabaseError, sqlite3.OperationalError) as e:
+                error_msg = str(e).lower()
+
+                # Only retry on transient I/O errors
+                if "disk i/o error" in error_msg or "database is locked" in error_msg:
+                    last_error = e
+
+                    if attempt < self._max_retries:
+                        # Add jitter to prevent thundering herd
+                        jittered_delay = delay * (1 + random.uniform(-0.25, 0.25))
+                        time.sleep(jittered_delay)
+                        delay = min(delay * 2, 10.0)  # Exponential backoff, max 10s
+                    else:
+                        # Final attempt failed
+                        raise
+                else:
+                    # Non-transient error, fail immediately
+                    raise
+
+        # Should never reach here, but just in case
+        if last_error:
+            raise last_error
+
+
+def check_database_health(db_path: Path, logger=None) -> tuple[bool, str]:
+    """
+    Perform lightweight SQLite integrity check.
+
+    Args:
+        db_path: Path to SQLite database file
+        logger: Logger instance for logging health check results
+
+    Returns:
+        (is_healthy, error_message) - True if healthy, False with error message otherwise
+    """
+    import sqlite3
+
+    try:
+        # Use a short timeout to avoid blocking
+        conn = sqlite3.connect(str(db_path), timeout=5.0)
+        cursor = conn.cursor()
+
+        # Quick integrity check (fast, catches major corruption)
+        cursor.execute("PRAGMA quick_check")
+        result = cursor.fetchone()[0]
+
+        conn.close()
+
+        if result != "ok":
+            error_msg = f"PRAGMA quick_check failed: {result}"
+            if logger:
+                logger.error("Database health check failed: %s", error_msg)
+            return False, error_msg
+
+        if logger:
+            logger.debug("Database health check passed")
+        return True, "Database healthy"
+
+    except sqlite3.OperationalError as e:
+        error_msg = f"Cannot access database: {e}"
+        if logger:
+            logger.error("Database health check failed: %s", error_msg)
+        return False, error_msg
+    except Exception as e:
+        error_msg = f"Unexpected error during health check: {e}"
+        if logger:
+            logger.error("Database health check failed: %s", error_msg)
+        return False, error_msg

qBitrr/db_recovery.py

@@ -0,0 +1,202 @@
+"""SQLite database recovery utilities."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import sqlite3
+from pathlib import Path
+
+logger = logging.getLogger("qBitrr.DBRecovery")
+
+
+class DatabaseRecoveryError(Exception):
+    """Raised when database recovery fails."""
+
+
+def checkpoint_wal(db_path: Path, logger_override=None) -> bool:
+    """
+    Force checkpoint of WAL file to main database.
+
+    This operation flushes all Write-Ahead Log entries to the main database
+    file, which can resolve certain types of corruption and reduce the risk
+    of data loss.
+
+    Args:
+        db_path: Path to SQLite database file
+        logger_override: Optional logger instance to use instead of module logger
+
+    Returns:
+        True if successful, False otherwise
+    """
+    log = logger_override or logger
+
+    try:
+        log.info("Starting WAL checkpoint for database: %s", db_path)
+        conn = sqlite3.connect(str(db_path), timeout=10.0)
+        cursor = conn.cursor()
+
+        # Force WAL checkpoint with TRUNCATE mode
+        # This checkpoints all frames and truncates the WAL file
+        cursor.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        result = cursor.fetchone()
+
+        conn.close()
+
+        # Result is (busy, log_pages, checkpointed_pages)
+        # If busy=0, checkpoint was fully successful
+        if result and result[0] == 0:
+            log.info(
+                "WAL checkpoint successful: %s frames checkpointed, %s pages in log",
+                result[2],
+                result[1],
+            )
+            return True
+        else:
+            log.warning(
+                "WAL checkpoint partially successful: result=%s (database may be busy)",
+                result,
+            )
+            return True  # Still consider partial success as success
+
+    except sqlite3.OperationalError as e:
+        log.error("WAL checkpoint failed (OperationalError): %s", e)
+        return False
+    except Exception as e:
+        log.error("WAL checkpoint failed (unexpected error): %s", e)
+        return False
+
+
+def repair_database(db_path: Path, backup: bool = True, logger_override=None) -> bool:
+    """
+    Attempt to repair corrupted SQLite database via dump/restore.
+
+    This operation:
+    1. Creates a backup of the corrupted database
+    2. Dumps all recoverable data to a temporary database
+    3. Replaces the original with the repaired copy
+    4. Verifies integrity of the repaired database
+
+    WARNING: Some data may be lost if corruption is severe.
+
+    Args:
+        db_path: Path to SQLite database file
+        backup: Whether to create backup before repair (default: True)
+        logger_override: Optional logger instance to use instead of module logger
+
+    Returns:
+        True if repair successful, False otherwise
+
+    Raises:
+        DatabaseRecoveryError: If repair fails critically
+    """
+    log = logger_override or logger
+
+    backup_path = db_path.with_suffix(".db.backup")
+    temp_path = db_path.with_suffix(".db.temp")
+
+    try:
+        # Step 1: Backup original
+        if backup:
+            log.info("Creating backup: %s", backup_path)
+            shutil.copy2(db_path, backup_path)
+
+        # Step 2: Dump recoverable data
+        log.info("Dumping recoverable data from corrupted database...")
+        source_conn = sqlite3.connect(str(db_path))
+
+        temp_conn = sqlite3.connect(str(temp_path))
+
+        # Dump schema and data
+        skipped_rows = 0
+        for line in source_conn.iterdump():
+            try:
+                temp_conn.execute(line)
+            except sqlite3.Error as e:
+                # Log but continue - recover what we can
+                skipped_rows += 1
+                log.debug("Skipping corrupted row during dump: %s", e)
+
+        if skipped_rows > 0:
+            log.warning("Skipped %s corrupted rows during dump", skipped_rows)
+
+        temp_conn.commit()
+        temp_conn.close()
+        source_conn.close()
+
+        # Step 3: Replace original with repaired copy
+        log.info("Replacing database with repaired version...")
+        db_path.unlink()
+        shutil.move(str(temp_path), str(db_path))
+
+        # Step 4: Verify integrity
+        log.info("Verifying integrity of repaired database...")
+        verify_conn = sqlite3.connect(str(db_path))
+        cursor = verify_conn.cursor()
+        cursor.execute("PRAGMA integrity_check")
+        result = cursor.fetchone()[0]
+        verify_conn.close()
+
+        if result != "ok":
+            raise DatabaseRecoveryError(f"Repair verification failed: {result}")
+
+        log.info("Database repair successful!")
+        return True
+
+    except Exception as e:
+        log.error("Database repair failed: %s", e)
+
+        # Attempt to restore backup
+        if backup and backup_path.exists():
+            log.warning("Restoring from backup...")
+            try:
+                shutil.copy2(backup_path, db_path)
+                log.info("Backup restored successfully")
+            except Exception as restore_error:
+                log.error("Failed to restore backup: %s", restore_error)
+
+        # Cleanup temp files
+        if temp_path.exists():
+            try:
+                temp_path.unlink()
+            except Exception:
+                pass  # Best effort cleanup
+
+        raise DatabaseRecoveryError(f"Repair failed: {e}") from e
+
+
+def vacuum_database(db_path: Path, logger_override=None) -> bool:
+    """
+    Run VACUUM to reclaim space and optimize database.
+
+    VACUUM rebuilds the database file, repacking it into a minimal amount of
+    disk space. This can help resolve some types of corruption and improve
+    performance.
+
+    Note: VACUUM requires free disk space approximately 2x the database size.
+
+    Args:
+        db_path: Path to SQLite database file
+        logger_override: Optional logger instance to use instead of module logger
+
+    Returns:
+        True if successful, False otherwise
+    """
+    log = logger_override or logger
+
+    try:
+        log.info("Running VACUUM on database: %s", db_path)
+        conn = sqlite3.connect(str(db_path), timeout=30.0)
+
+        conn.execute("VACUUM")
+        conn.close()
+
+        log.info("VACUUM completed successfully")
+        return True
+
+    except sqlite3.OperationalError as e:
+        log.error("VACUUM failed (OperationalError): %s", e)
+        return False
+    except Exception as e:
+        log.error("VACUUM failed (unexpected error): %s", e)
+        return False