crackerjack 0.33.0__py3-none-any.whl → 0.33.2__py3-none-any.whl

crackerjack/core/websocket_lifecycle.py

@@ -1,9 +1,3 @@
-"""WebSocket and network resource lifecycle management.
-
-Provides comprehensive cleanup patterns for WebSocket connections,
-HTTP clients, and network resources to prevent resource leaks.
-"""
-
 import asyncio
 import contextlib
 import logging
@@ -19,11 +13,9 @@ from .resource_manager import ManagedResource, ResourceManager
 
 
 class ManagedWebSocketConnection(ManagedResource):
-    """WebSocket connection with automatic cleanup on error scenarios."""
-
     def __init__(
         self,
-        websocket: t.Any,  # websockets protocols have import issues
+        websocket: t.Any,
         manager: ResourceManager | None = None,
     ) -> None:
         super().__init__(manager)
@@ -31,20 +23,17 @@ class ManagedWebSocketConnection(ManagedResource):
         self.logger = logging.getLogger(__name__)
 
     async def cleanup(self) -> None:
-        """Clean up WebSocket connection."""
         if not self._closed and not self.websocket.closed:
             self._closed = True
 
             try:
                 await asyncio.wait_for(self.websocket.close(), timeout=5.0)
             except (TimeoutError, websockets.ConnectionClosed):
-                # Expected when connection is already closed or times out
                 pass
             except Exception as e:
                 self.logger.warning(f"Error closing WebSocket connection: {e}")
 
     async def send_safe(self, message: str) -> bool:
-        """Send message safely, returning True if successful."""
         if self._closed or self.websocket.closed:
             return False
 
@@ -61,8 +50,6 @@ class ManagedWebSocketConnection(ManagedResource):
 
 
 class ManagedHTTPClient(ManagedResource):
-    """HTTP client session with automatic cleanup."""
-
     def __init__(
         self,
         session: aiohttp.ClientSession,
@@ -72,7 +59,6 @@ class ManagedHTTPClient(ManagedResource):
         self.session = session
 
     async def cleanup(self) -> None:
-        """Clean up HTTP client session."""
         if not self._closed and not self.session.closed:
             self._closed = True
 
@@ -83,8 +69,6 @@ class ManagedHTTPClient(ManagedResource):
 
 
 class ManagedWebSocketServer(ManagedResource):
-    """WebSocket server with comprehensive lifecycle management."""
-
     def __init__(
         self,
         port: int,
@@ -94,7 +78,7 @@ class ManagedWebSocketServer(ManagedResource):
         super().__init__(manager)
         self.port = port
         self.host = host
-        self.server: t.Any | None = None  # websockets server type has import issues
+        self.server: t.Any | None = None
         self.connections: set[ManagedWebSocketConnection] = set()
         self.logger = logging.getLogger(__name__)
         self._server_task: asyncio.Task[t.Any] | None = None
@@ -103,13 +87,11 @@ class ManagedWebSocketServer(ManagedResource):
         self,
         handler: t.Callable[[t.Any], t.Awaitable[None]],
     ) -> None:
-        """Start the WebSocket server."""
         if self.server:
             return
 
-        # Wrap handler to manage connections
         async def managed_handler(
-            websocket: t.Any,  # websocket protocol type
+            websocket: t.Any,
         ) -> None:
             managed_conn = ManagedWebSocketConnection(websocket, self.manager)
             self.connections.add(managed_conn)
@@ -124,26 +106,24 @@ class ManagedWebSocketServer(ManagedResource):
             managed_handler,
             self.host,
             self.port,
-            # Configure timeouts and limits
             ping_interval=20,
             ping_timeout=10,
             close_timeout=10,
-            max_size=2**20,  # 1MB
+            max_size=2**20,
             max_queue=32,
         )
 
-        self.logger.info(f"WebSocket server started on {self.host}:{self.port}")
+        self.logger.info(f"WebSocket server started on {self.host}: {self.port}")
 
     async def cleanup(self) -> None:
-        """Clean up WebSocket server and all connections."""
         if self._closed:
             return
         self._closed = True
 
-        # Close all active connections
         if self.connections:
             close_tasks = [
-                asyncio.create_task(conn.cleanup()) for conn in list(self.connections)
+                asyncio.create_task(conn.cleanup())
+                for conn in list[t.Any](self.connections)
             ]
 
             if close_tasks:
@@ -151,7 +131,6 @@ class ManagedWebSocketServer(ManagedResource):
 
         self.connections.clear()
 
-        # Close server
         if self.server:
             try:
                 self.server.close()
@@ -163,13 +142,10 @@ class ManagedWebSocketServer(ManagedResource):
                 self.server = None
 
     def get_connection_count(self) -> int:
-        """Get the number of active connections."""
         return len([conn for conn in self.connections if not conn._closed])
 
 
 class ManagedSubprocess(ManagedResource):
-    """Subprocess with enhanced lifecycle management and resource cleanup."""
-
     def __init__(
         self,
         process: subprocess.Popen[bytes],
@@ -183,19 +159,16 @@ class ManagedSubprocess(ManagedResource):
         self._monitor_task: asyncio.Task[t.Any] | None = None
 
     async def start_monitoring(self) -> None:
-        """Start monitoring the process for unexpected termination."""
         if self._monitor_task:
             return
 
         self._monitor_task = asyncio.create_task(self._monitor_process())
 
     async def _monitor_process(self) -> None:
-        """Monitor process health and log unexpected terminations."""
         try:
             while self.process.poll() is None:
                 await asyncio.sleep(5.0)
 
-            # Process has terminated
             return_code = self.process.returncode
             if return_code != 0:
                 self.logger.warning(
@@ -207,12 +180,10 @@ class ManagedSubprocess(ManagedResource):
             self.logger.warning(f"Error monitoring process: {e}")
 
     async def cleanup(self) -> None:
-        """Clean up subprocess with graceful termination."""
         if self._closed:
             return
         self._closed = True
 
-        # Cancel monitoring
         if self._monitor_task and not self._monitor_task.done():
             self._monitor_task.cancel()
             try:
@@ -220,10 +191,8 @@ class ManagedSubprocess(ManagedResource):
             except asyncio.CancelledError:
                 pass
 
-        # Clean up process
         if self.process.poll() is None:
             try:
-                # Try graceful termination first
                 self.process.terminate()
 
                 try:
@@ -232,7 +201,6 @@ class ManagedSubprocess(ManagedResource):
                         f"Process {self.process.pid} terminated gracefully"
                     )
                 except subprocess.TimeoutExpired:
-                    # Force kill if graceful termination fails
                     self.process.kill()
                     try:
                         self.process.wait(timeout=2.0)
@@ -243,7 +211,6 @@ class ManagedSubprocess(ManagedResource):
                         )
 
             except ProcessLookupError:
-                # Process already terminated
                 pass
             except Exception as e:
                 self.logger.warning(
@@ -251,13 +218,10 @@ class ManagedSubprocess(ManagedResource):
                 )
 
     def is_running(self) -> bool:
-        """Check if the process is still running."""
         return not self._closed and self.process.poll() is None
 
 
 class NetworkResourceManager:
-    """Manager for network-related resources with health monitoring."""
-
     def __init__(self) -> None:
         self.resource_manager = ResourceManager()
         self.logger = logging.getLogger(__name__)
@@ -267,7 +231,6 @@ class NetworkResourceManager:
         port: int,
         host: str = "127.0.0.1",
     ) -> ManagedWebSocketServer:
-        """Create a managed WebSocket server."""
         server = ManagedWebSocketServer(port, host, self.resource_manager)
         return server
 
@@ -276,7 +239,6 @@ class NetworkResourceManager:
         timeout: aiohttp.ClientTimeout | None = None,
         **kwargs: t.Any,
     ) -> ManagedHTTPClient:
-        """Create a managed HTTP client session."""
         timeout = timeout or aiohttp.ClientTimeout(total=30.0)
         session = aiohttp.ClientSession(timeout=timeout, **kwargs)
         return ManagedHTTPClient(session, self.resource_manager)
@@ -286,16 +248,14 @@ class NetworkResourceManager:
         process: subprocess.Popen[bytes],
         timeout: float = 30.0,
     ) -> ManagedSubprocess:
-        """Create a managed subprocess."""
         return ManagedSubprocess(process, timeout, self.resource_manager)
 
     async def check_port_available(self, port: int, host: str = "127.0.0.1") -> bool:
-        """Check if a port is available for binding."""
         try:
             with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
                 sock.settimeout(1.0)
                 result = sock.connect_ex((host, port))
-                return result != 0  # Port is available if connection fails
+                return result != 0
         except Exception:
             return False
 
@@ -306,7 +266,6 @@ class NetworkResourceManager:
         timeout: float = 30.0,
         poll_interval: float = 0.5,
     ) -> bool:
-        """Wait for a port to become available (service to start)."""
         start_time = time.time()
 
         while time.time() - start_time < timeout:
@@ -314,7 +273,7 @@ class NetworkResourceManager:
                 with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
                     sock.settimeout(1.0)
                     result = sock.connect_ex((host, port))
-                    if result == 0:  # Connection successful
+                    if result == 0:
                         return True
 
             await asyncio.sleep(poll_interval)
@@ -322,7 +281,6 @@ class NetworkResourceManager:
         return False
 
     async def cleanup_all(self) -> None:
-        """Clean up all managed network resources."""
         await self.resource_manager.cleanup_all()
 
     async def __aenter__(self) -> "NetworkResourceManager":
@@ -337,14 +295,12 @@ class NetworkResourceManager:
         await self.cleanup_all()
 
 
-# Context manager helpers for common network resource patterns
 @contextlib.asynccontextmanager
 async def with_websocket_server(
     port: int,
     handler: t.Callable[[t.Any], t.Awaitable[None]],
     host: str = "127.0.0.1",
-):
-    """Context manager for a WebSocket server with automatic cleanup."""
+) -> t.AsyncIterator[t.Any]:
     async with NetworkResourceManager() as manager:
         server = await manager.create_websocket_server(port, host)
         try:
@@ -355,8 +311,7 @@ async def with_websocket_server(
 
 
 @contextlib.asynccontextmanager
-async def with_http_client(**kwargs: t.Any):
-    """Context manager for an HTTP client with automatic cleanup."""
+async def with_http_client(**kwargs: t.Any) -> t.AsyncIterator[t.Any]:
     async with NetworkResourceManager() as manager:
         client = await manager.create_http_client(**kwargs)
         try:
@@ -370,10 +325,8 @@ async def with_managed_subprocess(
     command: list[str],
     timeout: float = 30.0,
     **popen_kwargs: t.Any,
-):
-    """Context manager for a subprocess with automatic cleanup."""
+) -> t.AsyncIterator[t.Any]:
     async with NetworkResourceManager() as manager:
-        # Ensure we get bytes output for consistent type handling
         process = subprocess.Popen[bytes](command, text=False, **popen_kwargs)
         managed_proc = manager.create_subprocess(process, timeout)
         try:
@@ -384,8 +337,6 @@ async def with_managed_subprocess(
 
 
 class WebSocketHealthMonitor:
-    """Health monitor for WebSocket connections and servers."""
-
     def __init__(self, check_interval: float = 30.0) -> None:
         self.check_interval = check_interval
         self.monitored_servers: list[ManagedWebSocketServer] = []
@@ -393,23 +344,19 @@ class WebSocketHealthMonitor:
         self._monitor_task: asyncio.Task[t.Any] | None = None
 
     def add_server(self, server: ManagedWebSocketServer) -> None:
-        """Add a server to health monitoring."""
         self.monitored_servers.append(server)
 
     def remove_server(self, server: ManagedWebSocketServer) -> None:
-        """Remove a server from health monitoring."""
         if server in self.monitored_servers:
             self.monitored_servers.remove(server)
 
     async def start_monitoring(self) -> None:
-        """Start health monitoring."""
         if self._monitor_task:
             return
 
         self._monitor_task = asyncio.create_task(self._monitor_loop())
 
     async def stop_monitoring(self) -> None:
-        """Stop health monitoring."""
         if self._monitor_task and not self._monitor_task.done():
             self._monitor_task.cancel()
             try:
@@ -418,7 +365,6 @@ class WebSocketHealthMonitor:
                 pass
 
     async def _monitor_loop(self) -> None:
-        """Main monitoring loop."""
         try:
             while True:
                 for server in self.monitored_servers.copy():
@@ -433,37 +379,26 @@ class WebSocketHealthMonitor:
             pass
 
     async def _check_server_health(self, server: ManagedWebSocketServer) -> None:
-        """Check health of a specific server."""
         if server._closed:
             self.remove_server(server)
             return
 
         connection_count = server.get_connection_count()
 
-        # Log health metrics
         self.logger.debug(
-            f"Server {server.host}:{server.port} - "
+            f"Server {server.host}: {server.port} - "
             f"Active connections: {connection_count}"
         )
 
-        # Could add more sophisticated health checks here:
-        # - Memory usage monitoring
-        # - Connection rate limiting
-        # - Error rate monitoring
-        # - Automatic restart on failure
-
 
-# Global network resource cleanup
 _global_network_managers: list[NetworkResourceManager] = []
 
 
 def register_network_manager(manager: NetworkResourceManager) -> None:
-    """Register a network resource manager for global cleanup."""
     _global_network_managers.append(manager)
 
 
 async def cleanup_all_network_resources() -> None:
-    """Clean up all globally registered network resource managers."""
     cleanup_tasks = [
         asyncio.create_task(manager.cleanup_all())
         for manager in _global_network_managers