lanscape 1.3.8a1__py3-none-any.whl → 2.4.0a2__py3-none-any.whl

lanscape/ui/ws/handlers/scan.py

@@ -0,0 +1,352 @@
+"""
+WebSocket handler for network scanning operations.
+
+Provides handlers for:
+- Starting scans (threaded and synchronous)
+- Getting scan results (full and delta)
+- Getting scan summary/status
+- Terminating scans
+- Subscribing to real-time scan updates
+"""
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable, Optional
+
+from lanscape.core.subnet_scan import ScanManager, ScanConfig
+from lanscape.ui.ws.handlers.base import BaseHandler
+from lanscape.ui.ws.delta import ScanDeltaTracker
+
+
+class ScanHandler(BaseHandler):
+    """
+    Handler for scan-related WebSocket actions.
+
+    Supports actions:
+    - scan.start: Start a new scan (non-blocking)
+    - scan.start_sync: Start a scan and wait for completion
+    - scan.get: Get full scan results
+    - scan.get_delta: Get only changed results since last request
+    - scan.summary: Get scan summary/progress
+    - scan.terminate: Stop a running scan
+    - scan.subscribe: Subscribe to real-time scan updates
+    - scan.unsubscribe: Unsubscribe from scan updates
+    """
+
+    def __init__(self, scan_manager: Optional[ScanManager] = None):
+        """
+        Initialize the scan handler.
+
+        Args:
+            scan_manager: Optional ScanManager instance. If not provided,
+                         uses the singleton instance.
+        """
+        super().__init__()
+        self._scan_manager = scan_manager or ScanManager()
+        self._delta_trackers: dict[str, ScanDeltaTracker] = {}
+        self._subscriptions: dict[str, set] = {}  # scan_id -> set of client_ids
+        self.log = logging.getLogger('ScanHandler')
+
+        # Register handlers
+        self.register('start', self._handle_start)
+        self.register('start_sync', self._handle_start_sync)
+        self.register('get', self._handle_get)
+        self.register('get_delta', self._handle_get_delta)
+        self.register('summary', self._handle_summary)
+        self.register('terminate', self._handle_terminate)
+        self.register('subscribe', self._handle_subscribe)
+        self.register('unsubscribe', self._handle_unsubscribe)
+        self.register('list', self._handle_list)
+
+    @property
+    def prefix(self) -> str:
+        """Return the action prefix for this handler."""
+        return 'scan'
+
+    def _handle_start(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Start a new network scan.
+
+        Params:
+            subnet: Target subnet to scan
+            port_list: Name of the port list to use
+            ... (other ScanConfig parameters)
+
+        Returns:
+            Dict with scan_id and status
+        """
+        config = ScanConfig.from_dict(params)
+        scan = self._scan_manager.new_scan(config)
+        self.log.info(f"Started scan {scan.uid} for {config.subnet}")
+
+        return {
+            'scan_id': scan.uid,
+            'status': 'running'
+        }
+
+    async def _handle_start_sync(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Start a scan and wait for completion.
+
+        Params:
+            Same as _handle_start
+
+        Returns:
+            Dict with scan_id and status='complete'
+        """
+        config = ScanConfig.from_dict(params)
+        scan = self._scan_manager.new_scan(config)
+        self.log.info(f"Started sync scan {scan.uid} for {config.subnet}")
+
+        # Wait for completion in a non-blocking way
+        while scan.running:
+            await asyncio.sleep(0.5)
+
+        return {
+            'scan_id': scan.uid,
+            'status': 'complete'
+        }
+
+    def _handle_get(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Get full scan results.
+
+        Params:
+            scan_id: The scan ID to retrieve
+
+        Returns:
+            Full scan results as dict
+        """
+        scan_id = self._get_param(params, 'scan_id', required=True)
+        scan = self._scan_manager.get_scan(scan_id)
+
+        if scan is None:
+            raise ValueError(f"Scan not found: {scan_id}")
+
+        return json.loads(scan.results.export(str))
+
+    def _handle_get_delta(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Get only changed scan results since last request.
+
+        Params:
+            scan_id: The scan ID to retrieve
+            client_id: Client identifier for tracking deltas
+
+        Returns:
+            Delta update containing only changed devices and metadata
+        """
+        scan_id = self._get_param(params, 'scan_id', required=True)
+        client_id = self._get_param(params, 'client_id', default='default')
+
+        scan = self._scan_manager.get_scan(scan_id)
+        if scan is None:
+            raise ValueError(f"Scan not found: {scan_id}")
+
+        # Get or create delta tracker for this client
+        tracker_key = f"{scan_id}_{client_id}"
+        if tracker_key not in self._delta_trackers:
+            self._delta_trackers[tracker_key] = ScanDeltaTracker()
+
+        tracker = self._delta_trackers[tracker_key]
+        full_results = json.loads(scan.results.export(str))
+        delta = tracker.get_scan_delta(full_results)
+
+        # Add scan status info
+        delta['scan_id'] = scan_id
+        delta['running'] = scan.running
+
+        # Add calculated progress from backend (more accurate than simple host count)
+        if delta.get('metadata') is None:
+            delta['metadata'] = {}
+        delta['metadata']['percent_complete'] = scan.calc_percent_complete()
+
+        return delta
+
+    def _handle_summary(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Get scan summary/progress.
+
+        Params:
+            scan_id: The scan ID to get summary for
+
+        Returns:
+            Dict with running status, percent complete, stage, runtime, and device counts
+        """
+        scan_id = self._get_param(params, 'scan_id', required=True)
+        scan = self._scan_manager.get_scan(scan_id)
+
+        if scan is None:
+            raise ValueError(f"Scan not found: {scan_id}")
+
+        return {
+            'scan_id': scan_id,
+            'running': scan.running,
+            'percent_complete': scan.calc_percent_complete(),
+            'stage': scan.results.stage,
+            'runtime': scan.results.get_runtime(),
+            'devices': {
+                'scanned': scan.results.devices_scanned,
+                'alive': len(scan.results.devices),
+                'total': scan.results.devices_total
+            }
+        }
+
+    def _handle_terminate(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Terminate a running scan.
+
+        Params:
+            scan_id: The scan ID to terminate
+
+        Returns:
+            Dict with success status
+        """
+        scan_id = self._get_param(params, 'scan_id', required=True)
+        scan = self._scan_manager.get_scan(scan_id)
+
+        if scan is None:
+            raise ValueError(f"Scan not found: {scan_id}")
+
+        scan.terminate()
+        self.log.info(f"Terminated scan {scan_id}")
+
+        return {'success': True, 'scan_id': scan_id}
+
+    def _handle_subscribe(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Subscribe to real-time scan updates.
+
+        Params:
+            scan_id: The scan ID to subscribe to
+            client_id: Client identifier for the subscription
+
+        Returns:
+            Dict with subscription confirmation
+        """
+        scan_id = self._get_param(params, 'scan_id', required=True)
+        client_id = self._get_param(params, 'client_id', required=True)
+
+        scan = self._scan_manager.get_scan(scan_id)
+        if scan is None:
+            raise ValueError(f"Scan not found: {scan_id}")
+
+        if scan_id not in self._subscriptions:
+            self._subscriptions[scan_id] = set()
+        self._subscriptions[scan_id].add(client_id)
+
+        self.log.debug(f"Client {client_id} subscribed to scan {scan_id}")
+
+        return {
+            'subscribed': True,
+            'scan_id': scan_id,
+            'client_id': client_id
+        }
+
+    def _handle_unsubscribe(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Unsubscribe from scan updates.
+
+        Params:
+            scan_id: The scan ID to unsubscribe from
+            client_id: Client identifier for the subscription
+
+        Returns:
+            Dict with unsubscription confirmation
+        """
+        scan_id = self._get_param(params, 'scan_id', required=True)
+        client_id = self._get_param(params, 'client_id', required=True)
+
+        if scan_id in self._subscriptions:
+            self._subscriptions[scan_id].discard(client_id)
+
+        # Clean up delta tracker
+        tracker_key = f"{scan_id}_{client_id}"
+        self._delta_trackers.pop(tracker_key, None)
+
+        self.log.debug(f"Client {client_id} unsubscribed from scan {scan_id}")
+
+        return {
+            'unsubscribed': True,
+            'scan_id': scan_id,
+            'client_id': client_id
+        }
+
+    def _handle_list(
+        self,
+        params: dict[str, Any],  # pylint: disable=unused-argument
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> list:
+        """
+        List all scans.
+
+        Returns:
+            List of scan summaries
+        """
+        scans = []
+        for scan in self._scan_manager.scans:
+            scans.append({
+                'scan_id': scan.uid,
+                'subnet': scan.subnet_str,
+                'running': scan.running,
+                'stage': scan.results.stage,
+                'devices_found': len(scan.results.devices)
+            })
+        return scans
+
+    def get_subscriptions(self, scan_id: str) -> set:
+        """
+        Get all client IDs subscribed to a scan.
+
+        Args:
+            scan_id: The scan ID
+
+        Returns:
+            Set of client IDs
+        """
+        return self._subscriptions.get(scan_id, set())
+
+    def cleanup_client(self, client_id: str) -> None:
+        """
+        Clean up all subscriptions for a client.
+
+        Args:
+            client_id: The client ID to clean up
+        """
+        for scan_id in list(self._subscriptions.keys()):
+            self._subscriptions[scan_id].discard(client_id)
+            tracker_key = f"{scan_id}_{client_id}"
+            self._delta_trackers.pop(tracker_key, None)

lanscape/ui/ws/handlers/tools.py

@@ -0,0 +1,145 @@
+"""
+WebSocket handler for utility tools.
+
+Provides handlers for:
+- Subnet validation and listing
+- Default configuration retrieval
+"""
+
+import traceback
+from typing import Any, Callable, Optional
+
+from lanscape.core.net_tools import get_all_network_subnets, is_arp_supported
+from lanscape.core.ip_parser import parse_ip_input
+from lanscape.core.errors import SubnetTooLargeError
+from lanscape.core.scan_config import DEFAULT_CONFIGS
+from lanscape.ui.ws.handlers.base import BaseHandler
+
+
+class ToolsHandler(BaseHandler):
+    """
+    Handler for utility tool WebSocket actions.
+
+    Supports actions:
+    - tools.subnet_test: Validate a subnet string
+    - tools.subnet_list: List all network subnets on the system
+    - tools.config_defaults: Get default scan configurations
+    - tools.arp_supported: Check if ARP is supported on this system
+    """
+
+    def __init__(self):
+        """Initialize the tools handler."""
+        super().__init__()
+
+        # Register handlers
+        self.register('subnet_test', self._handle_subnet_test)
+        self.register('subnet_list', self._handle_subnet_list)
+        self.register('config_defaults', self._handle_config_defaults)
+        self.register('arp_supported', self._handle_arp_supported)
+
+    @property
+    def prefix(self) -> str:
+        """Return the action prefix for this handler."""
+        return 'tools'
+
+    def _handle_subnet_test(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Validate a subnet string.
+
+        Params:
+            subnet: The subnet string to validate
+
+        Returns:
+            Dict with 'valid', 'msg', and 'count' fields
+        """
+        subnet = self._get_param(params, 'subnet')
+
+        if not subnet:
+            return {'valid': False, 'msg': 'Subnet cannot be blank', 'count': -1}
+
+        try:
+            ips = parse_ip_input(subnet)
+            length = len(ips)
+            return {
+                'valid': True,
+                'msg': f"{length} IP{'s' if length > 1 else ''}",
+                'count': length
+            }
+        except SubnetTooLargeError:
+            return {
+                'valid': False,
+                'msg': 'subnet too large',
+                'error': traceback.format_exc(),
+                'count': -1
+            }
+        except Exception:
+            return {
+                'valid': False,
+                'msg': 'invalid subnet',
+                'error': traceback.format_exc(),
+                'count': -1
+            }
+
+    def _handle_subnet_list(
+        self,
+        params: dict[str, Any],  # pylint: disable=unused-argument
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> list | dict:
+        """
+        List all network subnets on the system.
+
+        Returns:
+            List of subnet information or error dict
+        """
+        try:
+            return get_all_network_subnets()
+        except Exception:
+            return {'error': traceback.format_exc()}
+
+    def _handle_config_defaults(
+        self,
+        params: dict[str, Any],  # pylint: disable=unused-argument
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Get default scan configurations.
+
+        Adjusts presets that rely on ARP_LOOKUP when ARP is not supported.
+
+        Returns:
+            Dict of preset name -> ScanConfig dict
+        """
+        arp_supported = is_arp_supported()
+
+        configs = {}
+        for key, config in DEFAULT_CONFIGS.items():
+            config_dict = config.to_dict()
+
+            if not arp_supported:
+                lookup_types = list(config_dict.get('lookup_type') or [])
+                if 'ARP_LOOKUP' in lookup_types:
+                    lookup_types = [lt for lt in lookup_types if lt != 'ARP_LOOKUP']
+                    if 'POKE_THEN_ARP' not in lookup_types:
+                        lookup_types.append('POKE_THEN_ARP')
+                    config_dict['lookup_type'] = lookup_types
+
+            configs[key] = config_dict
+
+        return configs
+
+    def _handle_arp_supported(
+        self,
+        params: dict[str, Any],  # pylint: disable=unused-argument
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Check if ARP is supported on this system.
+
+        Returns:
+            Dict with 'supported' boolean
+        """
+        return {'supported': is_arp_supported()}

lanscape/ui/ws/protocol.py

@@ -0,0 +1,86 @@
+"""
+WebSocket protocol definitions for LANscape.
+
+Defines the message format and types used for communication between
+WebSocket clients and the LANscape server.
+"""
+
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class MessageType(str, Enum):
+    """Types of WebSocket messages."""
+    # Requests
+    REQUEST = "request"
+    # Responses
+    RESPONSE = "response"
+    ERROR = "error"
+    # Push notifications (server-initiated)
+    EVENT = "event"
+
+
+class WSMessage(BaseModel):
+    """Base WebSocket message structure."""
+    type: MessageType
+    id: Optional[str] = None  # Message ID for request/response correlation
+
+
+class WSRequest(WSMessage):
+    """
+    WebSocket request message from client.
+
+    Attributes:
+        action: The action to perform (e.g., 'scan.start', 'port.list')
+        params: Optional parameters for the action
+    """
+    type: MessageType = Field(default=MessageType.REQUEST)
+    action: str
+    params: Optional[dict[str, Any]] = None
+
+
+class WSResponse(WSMessage):
+    """
+    WebSocket response message from server.
+
+    Attributes:
+        action: The action this is responding to
+        data: The response data
+        success: Whether the action was successful
+    """
+    type: MessageType = Field(default=MessageType.RESPONSE)
+    action: str
+    data: Any = None
+    success: bool = True
+
+
+class WSError(WSMessage):
+    """
+    WebSocket error message from server.
+
+    Attributes:
+        action: The action that caused the error
+        error: Error message
+        traceback: Optional full traceback for debugging
+    """
+    type: MessageType = Field(default=MessageType.ERROR)
+    action: Optional[str] = None
+    error: str
+    traceback: Optional[str] = None
+
+
+class WSEvent(WSMessage):
+    """
+    WebSocket event message from server (push notification).
+
+    Used for real-time updates like scan progress and results.
+
+    Attributes:
+        event: The event name (e.g., 'scan.progress', 'scan.device_found')
+        data: Event data
+    """
+    type: MessageType = Field(default=MessageType.EVENT)
+    event: str
+    data: Any = None