Refactor serialization and AUScanner for improved error handling and constants usage

- Replaced magic numbers and strings with constants for APP_VERSION and CACHE_VERSION in serialization logic.
- Enhanced error handling by introducing custom exceptions (CacheCorruptedError, CacheVersionError, CacheWriteError) for better clarity and debugging.
- Updated AUScanner to use PLATFORM_MACOS and PLUGIN_TYPE_AU constants, improving code readability and maintainability.
- Improved logging for error scenarios to provide more informative feedback during plugin operations.

Author: twardoch

src/pedalboard_pluginary/retry.py

@@ -0,0 +1,96 @@
+"""
+Retry logic for handling transient failures.
+"""
+
+import functools
+import logging
+import time
+from typing import Any, Callable, Optional, Tuple, Type, TypeVar, Union
+
+from .constants import MAX_SCAN_RETRIES, SCAN_RETRY_DELAY
+
+logger = logging.getLogger(__name__)
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def with_retry(
+    exceptions: Union[Type[Exception], Tuple[Type[Exception], ...]],
+    max_attempts: int = MAX_SCAN_RETRIES,
+    delay: float = SCAN_RETRY_DELAY,
+    backoff_factor: float = 2.0,
+    max_delay: float = 60.0,
+) -> Callable[[F], F]:
+    """Decorator that retries a function on specified exceptions.
+    
+    Args:
+        exceptions: Exception or tuple of exceptions to catch and retry on.
+        max_attempts: Maximum number of attempts (including the first).
+        delay: Initial delay between retries in seconds.
+        backoff_factor: Factor to multiply delay by after each failure.
+        max_delay: Maximum delay between retries in seconds.
+        
+    Returns:
+        Decorated function that will retry on failure.
+    """
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            current_delay = delay
+            last_exception: Optional[Exception] = None
+            
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt == max_attempts - 1:
+                        # Last attempt, re-raise
+                        logger.warning(
+                            f"{func.__name__} failed after {max_attempts} attempts: {e}"
+                        )
+                        raise
+                    
+                    logger.info(
+                        f"{func.__name__} failed (attempt {attempt + 1}/{max_attempts}): {e}. "
+                        f"Retrying in {current_delay:.1f}s..."
+                    )
+                    time.sleep(current_delay)
+                    
+                    # Exponential backoff with max delay
+                    current_delay = min(current_delay * backoff_factor, max_delay)
+            
+            # This should never be reached, but just in case
+            if last_exception:
+                raise last_exception
+            else:
+                raise RuntimeError(f"{func.__name__} failed with unknown error")
+        
+        return wrapper  # type: ignore[return-value]
+    
+    return decorator
+
+
+def with_timeout(timeout: float) -> Callable[[F], F]:
+    """Decorator that adds a timeout to a function.
+    
+    Note: This is a placeholder for future implementation.
+    Proper timeout handling requires different approaches for
+    synchronous vs asynchronous functions.
+    
+    Args:
+        timeout: Timeout in seconds.
+        
+    Returns:
+        Decorated function.
+    """
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # TODO: Implement proper timeout handling
+            # For now, just pass through
+            return func(*args, **kwargs)
+        
+        return wrapper  # type: ignore[return-value]
+    
+    return decorator

src/pedalboard_pluginary/scanners/au_scanner.py

@@ -29,19 +29,19 @@ def __init__(
     ):
         """Initialize the AU scanner with optional ignore paths and specific paths."""
         super().__init__(ignore_paths, specific_paths)
-        self._is_macos = platform.system() == "Darwin"
+        self._is_macos = platform.system() == PLATFORM_MACOS
         if not self._is_macos:
             logger.info("AU scanning is only available on macOS.")
 
     @property
     def plugin_type(self) -> str:
         """Return the plugin type this scanner handles."""
-        return "aufx"
+        return PLUGIN_TYPE_AU
 
     @property
     def supported_extensions(self) -> List[str]:
         """Return list of file extensions this scanner supports."""
-        return [".component"]
+        return [AU_EXTENSION]
 
     def _get_au_plugin_locations(self) -> List[Path]:
         """Get standard AU plugin locations on macOS."""
@@ -184,6 +184,9 @@ def scan_plugin(self, path: Path) -> Optional[PluginInfo]:
             logger.info(f"Successfully scanned AU plugin: {display_name}")
             return plugin_info
 
+        except PluginLoadError:
+            # Re-raise our custom exceptions
+            raise
         except Exception as e:
             logger.error(f"Failed to scan AU plugin {path} with pedalboard: {e}")
             # Fall back to basic info extraction from auval

src/pedalboard_pluginary/serialization.py

@@ -8,6 +8,8 @@
 from pathlib import Path
 from typing import Any, Dict, Optional
 
+from .constants import APP_VERSION, CACHE_VERSION
+from .exceptions import CacheCorruptedError, CacheVersionError, CacheWriteError
 from .models import PluginInfo, PluginParameter
 from .types import (
     CacheData,
@@ -21,9 +23,6 @@
 
 logger = logging.getLogger(__name__)
 
-# Version for cache format
-CACHE_VERSION = "2.0.0"
-
 
 class PluginSerializer:
     """Handles serialization and deserialization of plugin data."""
@@ -142,7 +141,7 @@ def create_cache_metadata(cls, plugin_count: int) -> CacheMetadata:
             "created_at": now,
             "updated_at": now,
             "plugin_count": plugin_count,
-            "scanner_version": "0.1.0",  # TODO: Get from package version
+            "scanner_version": APP_VERSION,
         }
 
     @classmethod
@@ -177,7 +176,7 @@ def save_plugins(cls, plugins: Dict[str, PluginInfo], path: Path) -> None:
             logger.info(f"Saved {len(plugins_dict)} plugins to {path}")
         except Exception as e:
             logger.error(f"Failed to save plugins to {path}: {e}")
-            raise
+            raise CacheWriteError(str(path), str(e))
 
     @classmethod
     def load_plugins(cls, path: Path) -> Dict[str, PluginInfo]:
@@ -198,10 +197,10 @@ def load_plugins(cls, path: Path) -> Dict[str, PluginInfo]:
                 data = json.load(f)
         except json.JSONDecodeError as e:
             logger.error(f"Invalid JSON in cache file {path}: {e}")
-            return {}
+            raise CacheCorruptedError(str(path), f"JSON decode error: {e}")
         except Exception as e:
             logger.error(f"Failed to read cache file {path}: {e}")
-            return {}
+            raise CacheCorruptedError(str(path), str(e))
 
         # Handle both old format (direct plugin dict) and new format (with metadata)
         if isinstance(data, dict) and "metadata" in data and "plugins" in data:
@@ -211,7 +210,7 @@ def load_plugins(cls, path: Path) -> Dict[str, PluginInfo]:
 
             if cache_version != CACHE_VERSION:
                 logger.warning(f"Cache version mismatch: expected {CACHE_VERSION}, got {cache_version}")
-                # TODO: Implement cache migration if needed
+                raise CacheVersionError(CACHE_VERSION, cache_version, str(path))
 
             plugins_data = data.get("plugins", {})
         else: