crackerjack 0.32.0__py3-none-any.whl → 0.33.1__py3-none-any.whl

crackerjack/executors/hook_lock_manager.py

@@ -1,16 +1,3 @@
-"""Global hook lock management to prevent concurrent execution of specific hooks.
-
-This module provides a lock manager that ensures certain hooks
-(like complexipy) run sequentially rather than concurrently to prevent
-resource contention and hanging processes.
-
-This implements the HookLockManagerProtocol for dependency injection compatibility.
-
-Phase 2 implementation provides enhanced file-based global lock coordination
-across multiple crackerjack sessions with atomic operations, heartbeat monitoring,
-and comprehensive stale lock cleanup.
-"""
-
 import asyncio
 import json
 import logging
@@ -18,19 +5,13 @@ import os
 import time
 import typing as t
 from collections import defaultdict
-from contextlib import asynccontextmanager, suppress
+from contextlib import AbstractAsyncContextManager, asynccontextmanager, suppress
 from pathlib import Path
 
 from ..config.global_lock_config import GlobalLockConfig
 
 
 class HookLockManager:
-    """Manager for hook-specific locks to prevent concurrent execution.
-
-    Implements HookLockManagerProtocol for dependency injection compatibility.
-    Provides async locking with timeout protection and comprehensive monitoring.
-    """
-
     _instance: t.Optional["HookLockManager"] = None
     _initialized: bool = False
 
@@ -44,37 +25,30 @@ class HookLockManager:
             return
 
         self._hooks_requiring_locks = {
-            "complexipy",  # Prevent multiple complexipy processes
-            # Add other hooks that should run sequentially
+            "complexipy",
         }
 
-        # Per-hook locks for sequential execution
         self._hook_locks: dict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
 
-        # Global lock configuration and state
         self._global_config = GlobalLockConfig()
         self._global_lock_enabled = self._global_config.enabled
         self._active_global_locks: set[str] = set()
         self._heartbeat_tasks: dict[str, asyncio.Task[None]] = {}
 
-        # Lock usage tracking for monitoring
         self._lock_usage: dict[str, list[float]] = defaultdict(list)
         self._lock_wait_times: dict[str, list[float]] = defaultdict(list)
         self._lock_execution_times: dict[str, list[float]] = defaultdict(list)
-        self._max_history = 50  # Keep last 50 lock acquisitions
+        self._max_history = 50
 
-        # Global lock statistics tracking
         self._global_lock_attempts: dict[str, int] = defaultdict(int)
         self._global_lock_successes: dict[str, int] = defaultdict(int)
         self._global_lock_failures: dict[str, int] = defaultdict(int)
         self._stale_locks_cleaned: dict[str, int] = defaultdict(int)
         self._heartbeat_failures: dict[str, int] = defaultdict(int)
 
-        # Timeout protection
-        self._default_lock_timeout = 300.0  # 5 minutes default timeout
+        self._default_lock_timeout = 300.0
         self._lock_timeouts: dict[str, float] = {}
 
-        # Error tracking
         self._lock_failures: dict[str, int] = defaultdict(int)
         self._timeout_failures: dict[str, int] = defaultdict(int)
 
@@ -82,41 +56,22 @@ class HookLockManager:
         self._initialized = True
 
     def requires_lock(self, hook_name: str) -> bool:
-        """Check if a hook requires sequential execution."""
         return hook_name in self._hooks_requiring_locks
 
     @asynccontextmanager
-    async def acquire_hook_lock(self, hook_name: str) -> t.AsyncIterator[None]:
-        """Unified lock acquisition handling both hook-specific and global locks.
-
-        Args:
-            hook_name: Name of the hook to lock
-
-        Yields:
-            None when lock is acquired (or hook doesn't require lock)
-
-        Raises:
-            asyncio.TimeoutError: If lock acquisition times out
-
-        Example:
-            async with lock_manager.acquire_hook_lock("complexipy"):
-                # Only one complexipy process will run at a time
-                result = await execute_hook(hook)
-        """
+    async def acquire_hook_lock(
+        self, hook_name: str
+    ) -> AbstractAsyncContextManager[None]:
         if not self.requires_lock(hook_name):
-            # Hook doesn't require locking, proceed immediately
             yield
             return
 
         if not self._global_lock_enabled:
-            # Use existing hook-specific locking only (legacy behavior)
             async with self._acquire_existing_hook_lock(hook_name):
                 yield
             return
 
-        # Global locking: coordinate across all crackerjack sessions
         async with self._acquire_global_coordination_lock(hook_name):
-            # Then acquire hook-specific lock within global coordination
             async with self._acquire_existing_hook_lock(hook_name):
                 yield
 
@@ -124,7 +79,6 @@ class HookLockManager:
     async def _acquire_existing_hook_lock(
         self, hook_name: str
     ) -> t.AsyncIterator[None]:
-        """Acquire hook-specific asyncio lock (original behavior)."""
         lock = self._hook_locks[hook_name]
         timeout = self._lock_timeouts.get(hook_name, self._default_lock_timeout)
         start_time = time.time()
@@ -134,17 +88,15 @@ class HookLockManager:
         )
 
         try:
-            # Use asyncio.wait_for to implement timeout for lock acquisition
             await asyncio.wait_for(lock.acquire(), timeout=timeout)
 
             try:
                 acquisition_time = time.time() - start_time
                 self.logger.info(
                     f"Hook-specific lock acquired for {hook_name} after"
-                    f" {acquisition_time:.2f}s"
+                    f" {acquisition_time: .2f}s"
                 )
 
-                # Track lock usage for monitoring
                 self._track_lock_usage(hook_name, acquisition_time)
 
                 execution_start = time.time()
@@ -157,11 +109,10 @@ class HookLockManager:
                     self._track_lock_execution(hook_name, execution_time, total_time)
                     self.logger.debug(
                         f"Hook-specific lock released for {hook_name} after"
-                        f" {total_time:.2f}s total"
+                        f" {total_time: .2f}s total"
                     )
 
             finally:
-                # Always release the lock, even if an exception occurred
                 lock.release()
 
         except TimeoutError:
@@ -169,7 +120,7 @@ class HookLockManager:
             wait_time = time.time() - start_time
             self.logger.error(
                 f"Hook-specific lock acquisition timeout for {hook_name} after"
-                f" {wait_time:.2f}s "
+                f" {wait_time: .2f}s "
                 f"(timeout: {timeout}s, total failures: "
                 f"{self._timeout_failures[hook_name]})"
             )
@@ -187,7 +138,6 @@ class HookLockManager:
     async def _acquire_global_coordination_lock(
         self, hook_name: str
     ) -> t.AsyncIterator[None]:
-        """Acquire global file-based coordination lock across crackerjack sessions."""
         lock_path = self._global_config.get_lock_path(hook_name)
         start_time = time.time()
 
@@ -196,28 +146,24 @@ class HookLockManager:
             f"Attempting global lock acquisition for {hook_name}: {lock_path}"
         )
 
-        # Clean up stale locks first
         await self._cleanup_stale_lock_if_needed(hook_name)
 
         try:
-            # Atomic lock acquisition with retry logic
             await self._acquire_global_lock_file(hook_name, lock_path)
             self._global_lock_successes[hook_name] += 1
             self._active_global_locks.add(hook_name)
 
-            # Start heartbeat to keep lock alive
             heartbeat_task = asyncio.create_task(self._maintain_heartbeat(hook_name))
             self._heartbeat_tasks[hook_name] = heartbeat_task
 
             acquisition_time = time.time() - start_time
             self.logger.info(
-                f"Global lock acquired for {hook_name} after {acquisition_time:.2f}s"
+                f"Global lock acquired for {hook_name} after {acquisition_time: .2f}s"
             )
 
             try:
                 yield
             finally:
-                # Cleanup: cancel heartbeat and remove lock file
                 await self._cleanup_global_lock(hook_name, heartbeat_task)
 
         except Exception as e:
@@ -226,14 +172,12 @@ class HookLockManager:
             raise
 
     def _track_lock_usage(self, hook_name: str, acquisition_time: float) -> None:
-        """Track lock acquisition times for monitoring."""
         usage_list = self._lock_usage[hook_name]
         wait_list = self._lock_wait_times[hook_name]
 
         usage_list.append(acquisition_time)
         wait_list.append(acquisition_time)
 
-        # Keep only recent history
         if len(usage_list) > self._max_history:
             usage_list.pop(0)
         if len(wait_list) > self._max_history:
@@ -242,35 +186,31 @@ class HookLockManager:
     def _track_lock_execution(
         self, hook_name: str, execution_time: float, total_time: float
     ) -> None:
-        """Track lock execution times for monitoring."""
         exec_list = self._lock_execution_times[hook_name]
         exec_list.append(execution_time)
 
-        # Keep only recent history
         if len(exec_list) > self._max_history:
             exec_list.pop(0)
 
         self.logger.debug(
-            f"Hook {hook_name} execution: {execution_time:.2f}s "
-            f"(total with lock: {total_time:.2f}s)"
+            f"Hook {hook_name} execution: {execution_time: .2f}s "
+            f"(total with lock: {total_time: .2f}s)"
         )
 
     async def _acquire_global_lock_file(self, hook_name: str, lock_path: Path) -> None:
-        """Atomic acquisition of global lock file with retry logic."""
         for attempt in range(self._global_config.max_retry_attempts):
             try:
                 await self._attempt_lock_acquisition(hook_name, lock_path)
                 return
             except FileExistsError:
                 if attempt < self._global_config.max_retry_attempts - 1:
-                    # Exponential backoff with jitter
                     delay = self._global_config.retry_delay_seconds * (2**attempt)
-                    jitter = delay * 0.1  # Add 10% jitter
+                    jitter = delay * 0.1
                     wait_time = delay + (jitter * (0.5 - os.urandom(1)[0] / 255))
 
                     self.logger.debug(
                         f"Global lock exists for {hook_name}, retrying in "
-                        f"{wait_time:.2f}s"
+                        f"{wait_time: .2f}s"
                     )
                     await asyncio.sleep(wait_time)
                 else:
@@ -280,7 +220,6 @@ class HookLockManager:
                     )
 
     async def _attempt_lock_acquisition(self, hook_name: str, lock_path: Path) -> None:
-        """Single atomic lock acquisition attempt using temp file + rename pattern."""
         temp_path = lock_path.with_suffix(".tmp")
 
         lock_data = {
@@ -290,39 +229,32 @@ class HookLockManager:
             "hook_name": hook_name,
             "acquired_at": time.time(),
             "last_heartbeat": time.time(),
-            "crackerjack_version": "0.30.3",  # Could be made configurable
+            "crackerjack_version": "0.30.3",
         }
 
         try:
-            # Use exclusive creation for atomic operation
             with temp_path.open("x", encoding="utf-8") as f:
                 json.dump(lock_data, f, indent=2)
 
-            # Set restrictive permissions (owner only)
             temp_path.chmod(0o600)
 
-            # Atomic rename - this is the critical section
             try:
                 temp_path.rename(lock_path)
                 self.logger.debug(f"Successfully created global lock file: {lock_path}")
             except FileExistsError:
-                # Another process won the race, clean up our temp file
                 with suppress(OSError):
                     temp_path.unlink()
                 raise
 
         except FileExistsError:
-            # Lock file already exists - convert to proper exception type
             raise FileExistsError(f"Global lock already exists for {hook_name}")
         except Exception as e:
-            # Clean up temp file on any error
             with suppress(OSError):
                 temp_path.unlink()
             self.logger.error(f"Failed to create global lock for {hook_name}: {e}")
             raise
 
     async def _maintain_heartbeat(self, hook_name: str) -> None:
-        """Maintain heartbeat updates to prevent stale lock detection."""
         lock_path = self._global_config.get_lock_path(hook_name)
         interval = self._global_config.session_heartbeat_interval
 
@@ -335,7 +267,6 @@ class HookLockManager:
                 if hook_name not in self._active_global_locks:
                     break
 
-                # Update heartbeat timestamp in lock file
                 await self._update_heartbeat_timestamp(hook_name, lock_path)
 
             except asyncio.CancelledError:
@@ -345,10 +276,9 @@ class HookLockManager:
                 self._heartbeat_failures[hook_name] += 1
                 self.logger.warning(f"Heartbeat update failed for {hook_name}: {e}")
 
-                # If too many heartbeat failures, consider the lock compromised
                 if self._heartbeat_failures[hook_name] > 3:
                     self.logger.error(
-                        f"Too many heartbeat failures for {hook_name},"
+                        f"Too many heartbeat failures for {hook_name}, "
                         f" stopping heartbeat"
                     )
                     break
@@ -356,7 +286,6 @@ class HookLockManager:
     async def _update_heartbeat_timestamp(
         self, hook_name: str, lock_path: Path
     ) -> None:
-        """Atomic update of heartbeat timestamp in existing lock file."""
         if not lock_path.exists():
             self.logger.warning(
                 f"Lock file disappeared for {hook_name}, stopping heartbeat"
@@ -367,11 +296,9 @@ class HookLockManager:
         temp_path = lock_path.with_suffix(".heartbeat_tmp")
 
         try:
-            # Read existing lock data
             with lock_path.open(encoding="utf-8") as f:
                 lock_data = json.load(f)
 
-            # Verify we still own this lock
             if lock_data.get("session_id") != self._global_config.session_id:
                 self.logger.warning(
                     f"Lock ownership changed for {hook_name}, stopping heartbeat"
@@ -379,10 +306,8 @@ class HookLockManager:
                 self._active_global_locks.discard(hook_name)
                 return
 
-            # Update heartbeat timestamp
             lock_data["last_heartbeat"] = time.time()
 
-            # Write updated data atomically
             with temp_path.open("w", encoding="utf-8") as f:
                 json.dump(lock_data, f, indent=2)
 
@@ -397,17 +322,13 @@ class HookLockManager:
     async def _cleanup_global_lock(
         self, hook_name: str, heartbeat_task: asyncio.Task[None] | None = None
     ) -> None:
-        """Clean up global lock resources and remove lock file."""
         self.logger.debug(f"Cleaning up global lock for {hook_name}")
 
-        # Stop tracking this lock
         self._active_global_locks.discard(hook_name)
 
-        # Cancel heartbeat task
         if heartbeat_task is None:
             heartbeat_task = self._heartbeat_tasks.pop(hook_name, None)
         else:
-            # Remove from task tracking
             self._heartbeat_tasks.pop(hook_name, None)
 
         if heartbeat_task:
@@ -415,11 +336,9 @@ class HookLockManager:
             with suppress(asyncio.CancelledError):
                 await heartbeat_task
 
-        # Remove lock file
         lock_path = self._global_config.get_lock_path(hook_name)
         with suppress(OSError):
             if lock_path.exists():
-                # Verify we still own the lock before deleting
                 try:
                     with lock_path.open(encoding="utf-8") as f:
                         lock_data = json.load(f)
@@ -438,14 +357,12 @@ class HookLockManager:
                     )
 
     async def _cleanup_stale_lock_if_needed(self, hook_name: str) -> None:
-        """Check for and remove stale lock if detected."""
         lock_path = self._global_config.get_lock_path(hook_name)
 
         if not lock_path.exists():
             return
 
         try:
-            # Check if lock is stale
             with lock_path.open(encoding="utf-8") as f:
                 lock_data = json.load(f)
 
@@ -456,12 +373,11 @@ class HookLockManager:
 
             if age_hours > self._global_config.stale_lock_hours:
                 self.logger.warning(
-                    f"Removing stale lock for {hook_name} (age: {age_hours:.2f}h)"
+                    f"Removing stale lock for {hook_name} (age: {age_hours: .2f}h)"
                 )
                 lock_path.unlink()
                 self._stale_locks_cleaned[hook_name] += 1
             else:
-                # Lock is not stale, someone else has it
                 owner = lock_data.get("session_id", "unknown")
                 self.logger.debug(
                     f"Active lock exists for {hook_name} owned by {owner}"
@@ -469,13 +385,12 @@ class HookLockManager:
 
         except Exception as e:
             self.logger.warning(f"Could not check lock staleness for {hook_name}: {e}")
-            # If we can't read the lock file, it might be corrupted - remove it
+
             with suppress(OSError):
                 lock_path.unlink()
                 self._stale_locks_cleaned[hook_name] += 1
 
     def get_lock_stats(self) -> dict[str, t.Any]:
-        """Get comprehensive statistics about lock usage for monitoring."""
         stats = {}
 
         for hook_name in self._hooks_requiring_locks:
@@ -518,7 +433,6 @@ class HookLockManager:
                     ),
                 }
 
-                # Wait time statistics
                 if wait_times:
                     base_stats.update(
                         {
@@ -536,7 +450,6 @@ class HookLockManager:
                         }
                     )
 
-                # Execution time statistics
                 if exec_times:
                     base_stats.update(
                         {
@@ -559,12 +472,10 @@ class HookLockManager:
         return stats
 
     def add_hook_to_lock_list(self, hook_name: str) -> None:
-        """Add a hook to the list requiring sequential execution."""
         self._hooks_requiring_locks.add(hook_name)
         self.logger.info(f"Added {hook_name} to hooks requiring locks")
 
     def remove_hook_from_lock_list(self, hook_name: str) -> None:
-        """Remove a hook from the list requiring sequential execution."""
         self._hooks_requiring_locks.discard(hook_name)
         if hook_name in self._hook_locks:
             del self._hook_locks[hook_name]
@@ -573,40 +484,18 @@ class HookLockManager:
         self.logger.info(f"Removed {hook_name} from hooks requiring locks")
 
     def is_hook_currently_locked(self, hook_name: str) -> bool:
-        """Check if a hook is currently locked."""
         if not self.requires_lock(hook_name):
             return False
         return self._hook_locks[hook_name].locked()
 
     def set_hook_timeout(self, hook_name: str, timeout: float) -> None:
-        """Set custom timeout for a specific hook.
-
-        Args:
-            hook_name: Name of the hook
-            timeout: Timeout in seconds
-        """
         self._lock_timeouts[hook_name] = timeout
         self.logger.info(f"Set custom timeout for {hook_name}: {timeout}s")
 
     def get_hook_timeout(self, hook_name: str) -> float:
-        """Get timeout for a specific hook.
-
-        Args:
-            hook_name: Name of the hook
-
-        Returns:
-            Timeout in seconds
-        """
         return self._lock_timeouts.get(hook_name, self._default_lock_timeout)
 
-    # New protocol methods for global lock functionality
-
     def enable_global_lock(self, enabled: bool = True) -> None:
-        """Enable or disable global lock functionality.
-
-        Args:
-            enabled: Whether to enable global locking
-        """
         self._global_lock_enabled = enabled
         self._global_config.enabled = enabled
         self.logger.info(
@@ -614,33 +503,12 @@ class HookLockManager:
         )
 
     def is_global_lock_enabled(self) -> bool:
-        """Check if global lock functionality is enabled.
-
-        Returns:
-            True if global locking is enabled
-        """
         return self._global_lock_enabled
 
     def get_global_lock_path(self, hook_name: str) -> Path:
-        """Get the filesystem path for a hook's global lock file.
-
-        Args:
-            hook_name: Name of the hook
-
-        Returns:
-            Path to the lock file for the hook
-        """
         return self._global_config.get_lock_path(hook_name)
 
     def cleanup_stale_locks(self, max_age_hours: float = 2.0) -> int:
-        """Clean up stale lock files older than max_age_hours.
-
-        Args:
-            max_age_hours: Maximum age in hours before a lock is considered stale
-
-        Returns:
-            Number of stale locks cleaned up
-        """
         locks_dir = self._global_config.lock_directory
         if not locks_dir.exists():
             return 0
@@ -665,9 +533,7 @@ class HookLockManager:
     def _process_lock_file(
         self, lock_file: Path, max_age_hours: float, current_time: float
     ) -> int:
-        """Process a single lock file and return number of files cleaned."""
         try:
-            # Check file age
             file_age_hours = (current_time - lock_file.stat().st_mtime) / 3600
 
             if file_age_hours > max_age_hours:
@@ -683,7 +549,6 @@ class HookLockManager:
     def _cleanup_stale_lock_file(
         self, lock_file: Path, max_age_hours: float, current_time: float
     ) -> int:
-        """Clean up a stale lock file and return 1 if successful."""
         try:
             with lock_file.open(encoding="utf-8") as f:
                 lock_data = json.load(f)
@@ -698,12 +563,11 @@ class HookLockManager:
                 hook_name = lock_file.stem
                 self._stale_locks_cleaned[hook_name] += 1
                 self.logger.info(
-                    f"Cleaned stale lock: {lock_file} (age: {heartbeat_age_hours:.2f}h)"
+                    f"Cleaned stale lock: {lock_file} (age: {heartbeat_age_hours: .2f}h)"
                 )
                 return 1
 
         except (json.JSONDecodeError, KeyError):
-            # Corrupted lock file, remove it
             lock_file.unlink()
             self.logger.warning(f"Cleaned corrupted lock file: {lock_file}")
             return 1
@@ -711,17 +575,12 @@ class HookLockManager:
         return 0
 
     def get_global_lock_stats(self) -> dict[str, t.Any]:
-        """Get comprehensive statistics about global lock usage.
-
-        Returns:
-            Dictionary containing global lock statistics and metrics
-        """
         stats: dict[str, t.Any] = {
             "global_lock_enabled": self._global_lock_enabled,
             "lock_directory": str(self._global_config.lock_directory),
             "session_id": self._global_config.session_id,
             "hostname": self._global_config.hostname,
-            "active_global_locks": list(self._active_global_locks),
+            "active_global_locks": list[t.Any](self._active_global_locks),
             "active_heartbeat_tasks": len(self._heartbeat_tasks),
             "configuration": {
                 "timeout_seconds": self._global_config.timeout_seconds,
@@ -734,11 +593,10 @@ class HookLockManager:
             "statistics": {},
         }
 
-        # Per-hook global lock statistics
         all_hooks = (
-            set(self._global_lock_attempts.keys())
-            | set(self._global_lock_successes.keys())
-            | set(self._global_lock_failures.keys())
+            set[t.Any](self._global_lock_attempts.keys())
+            | set[t.Any](self._global_lock_successes.keys())
+            | set[t.Any](self._global_lock_failures.keys())
         )
 
         for hook_name in all_hooks:
@@ -761,7 +619,6 @@ class HookLockManager:
                 "has_heartbeat_task": hook_name in self._heartbeat_tasks,
             }
 
-        # Overall statistics
         total_attempts = sum(self._global_lock_attempts.values())
         total_successes = sum(self._global_lock_successes.values())
         total_failures = sum(self._global_lock_failures.values())
@@ -782,32 +639,21 @@ class HookLockManager:
         return stats
 
     def configure_from_options(self, options: t.Any) -> None:
-        """Configure the lock manager from CLI options.
-
-        Args:
-            options: Options object containing CLI arguments
-        """
         self._global_config = GlobalLockConfig.from_options(options)
         self._global_lock_enabled = self._global_config.enabled
 
-        # Apply stale lock cleanup if requested
         if hasattr(options, "global_lock_cleanup") and options.global_lock_cleanup:
             self.cleanup_stale_locks()
 
         self.logger.info(
             f"Configured lock manager: global_locks={
                 'enabled' if self._global_lock_enabled else 'disabled'
-            },"
+            }, "
             f" timeout={self._global_config.timeout_seconds}s, "
             f"lock_dir={self._global_config.lock_directory}"
         )
 
     def reset_hook_stats(self, hook_name: str | None = None) -> None:
-        """Reset statistics for a specific hook or all hooks.
-
-        Args:
-            hook_name: Name of the hook to reset, or None for all hooks
-        """
         if hook_name:
             self._lock_usage[hook_name].clear()
             self._lock_wait_times[hook_name].clear()
@@ -824,9 +670,8 @@ class HookLockManager:
             self.logger.info("Reset statistics for all hooks")
 
     def get_comprehensive_status(self) -> dict[str, t.Any]:
-        """Get comprehensive status including configuration and health."""
         status = {
-            "hooks_requiring_locks": list(self._hooks_requiring_locks),
+            "hooks_requiring_locks": list[t.Any](self._hooks_requiring_locks),
             "default_timeout": self._default_lock_timeout,
             "custom_timeouts": self._lock_timeouts.copy(),
             "max_history": self._max_history,
@@ -840,7 +685,6 @@ class HookLockManager:
             "total_timeout_failures": sum(self._timeout_failures.values()),
         }
 
-        # Add global lock information if enabled
         if self._global_lock_enabled:
             status["global_lock_stats"] = self.get_global_lock_stats()
         else:
@@ -852,5 +696,4 @@ class HookLockManager:
         return status
 
 
-# Singleton instance
 hook_lock_manager = HookLockManager()