lanscape 2.3.1__tar.gz → 2.4.0b1__tar.gz

{lanscape-2.3.1/lanscape.egg-info → lanscape-2.4.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lanscape
-Version: 2.3.1
+Version: 2.4.0b1
 Summary: A python based local network scanner
 Author-email: Michael Dennis <michael@dipduo.com>
 License-Expression: MIT
@@ -26,10 +26,12 @@ Requires-Dist: tabulate==0.9.0
 Requires-Dist: pydantic
 Requires-Dist: icmplib
 Requires-Dist: pwa-launcher>=1.1.0
+Requires-Dist: websockets<14.0,>=12.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: pytest-xdist>=3.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: openai>=1.0.0; extra == "dev"
 Requires-Dist: pylint>=3.0; extra == "dev"
 Requires-Dist: autopep8>=2.0; extra == "dev"

{lanscape-2.3.1 → lanscape-2.4.0b1}/lanscape/core/runtime_args.py

@@ -14,6 +14,8 @@ class RuntimeArgs:
     loglevel: str = 'INFO'
     flask_logging: bool = False
     persistent: bool = False
+    ws_server: bool = False
+    ws_port: int = 8766
 
 
 def parse_args() -> RuntimeArgs:
@@ -35,6 +37,10 @@ def parse_args() -> RuntimeArgs:
                         help='Don\'t exit after browser is closed')
     parser.add_argument('--debug', action='store_true',
                         help='Shorthand debug mode (equivalent to "--loglevel DEBUG --reloader")')
+    parser.add_argument('--ws-server', action='store_true',
+                        help='Start WebSocket server instead of Flask UI')
+    parser.add_argument('--ws-port', type=int, default=8766,
+                        help='Port for WebSocket server (default: 8766)')
 
     # Parse the arguments
     args = parser.parse_args()

{lanscape-2.3.1 → lanscape-2.4.0b1}/lanscape/ui/main.py

@@ -16,6 +16,7 @@ from lanscape.core.logger import configure_logging
 from lanscape.core.runtime_args import parse_args
 from lanscape.core.version_manager import get_installed_version, is_update_available
 from lanscape.ui.app import start_webserver_daemon, start_webserver
+from lanscape.ui.ws.server import run_server
 # do this so any logs generated on import are displayed
 args = parse_args()
 configure_logging(args.loglevel, args.logfile, args.flask_logging)
@@ -48,6 +49,11 @@ def _main():
     else:
         log.info('Flask reloaded app.')
 
+    # Check if WebSocket server mode is requested
+    if args.ws_server:
+        start_websocket_server()
+        return
+
     args.port = get_valid_port(args.port)
 
     try:
@@ -72,6 +78,22 @@ def try_check_update():
         log.warning('Unable to check for updates.')
 
 
+def start_websocket_server():
+    """Start the WebSocket server."""
+    args.ws_port = get_valid_port(args.ws_port)
+    log.info(f'Starting WebSocket server on port {args.ws_port}')
+    log.info(f'React UI should connect to ws://localhost:{args.ws_port}')
+    
+    try:
+        run_server(host='0.0.0.0', port=args.ws_port)
+    except KeyboardInterrupt:
+        log.info('WebSocket server stopped by user')
+    except Exception as e:
+        log.critical(f'WebSocket server failed: {e}')
+        log.debug(traceback.format_exc())
+        raise
+
+
 def open_browser(url: str, wait=2) -> Popen | None:
     """
     Open a browser window to the specified

lanscape-2.4.0b1/lanscape/ui/ws/__init__.py

@@ -0,0 +1,31 @@
+"""
+WebSocket interface for LANscape.
+
+Provides a standalone WebSocket server that exposes all LANscape functionality,
+allowing clients to initiate scans, manage port lists, and receive real-time
+scan results with delta updates.
+"""
+
+from lanscape.ui.ws.server import WebSocketServer, run_server
+from lanscape.ui.ws.protocol import (
+    WSMessage,
+    WSRequest,
+    WSResponse,
+    WSError,
+    WSEvent,
+    MessageType
+)
+from lanscape.ui.ws.delta import DeltaTracker, ScanDeltaTracker
+
+__all__ = [
+    'WebSocketServer',
+    'run_server',
+    'WSMessage',
+    'WSRequest',
+    'WSResponse',
+    'WSError',
+    'WSEvent',
+    'MessageType',
+    'DeltaTracker',
+    'ScanDeltaTracker'
+]

lanscape-2.4.0b1/lanscape/ui/ws/delta.py

@@ -0,0 +1,170 @@
+"""
+Delta tracking for efficient scan result updates.
+
+Uses content hashing to detect changes and only send updated data
+to clients, reducing bandwidth and improving performance.
+"""
+
+import json
+import hashlib
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+
+class DeltaState(BaseModel):
+    """
+    Represents the state of a tracked item.
+
+    Attributes:
+        hash: Content hash of the serialized data
+        data: The actual data being tracked
+    """
+    hash: str
+    data: Any
+
+
+class DeltaTracker:
+    """
+    Tracks changes to scan results and provides delta updates.
+
+    Uses MD5 hashing to detect changes in device data and scan state.
+    Clients receive only the changed portions of scan results.
+    """
+
+    def __init__(self):
+        """Initialize the delta tracker with empty state."""
+        self._states: dict[str, DeltaState] = {}
+
+    @staticmethod
+    def compute_hash(data: Any) -> str:
+        """
+        Compute MD5 hash of serialized data.
+
+        Args:
+            data: Any JSON-serializable data
+
+        Returns:
+            Hex string of the MD5 hash
+        """
+        serialized = json.dumps(data, sort_keys=True, default=str)
+        return hashlib.md5(serialized.encode()).hexdigest()
+
+    def update(self, key: str, data: Any) -> Optional[Any]:
+        """
+        Update tracked state and return data if changed.
+
+        Args:
+            key: Unique identifier for the tracked item
+            data: Current data for the item
+
+        Returns:
+            The data if it has changed, None otherwise
+        """
+        new_hash = self.compute_hash(data)
+        current_state = self._states.get(key)
+
+        if current_state is None or current_state.hash != new_hash:
+            self._states[key] = DeltaState(hash=new_hash, data=data)
+            return data
+        return None
+
+    def get_changes(self, items: dict[str, Any]) -> dict[str, Any]:
+        """
+        Get only changed items from a dictionary.
+
+        Args:
+            items: Dictionary of key -> data to check for changes
+
+        Returns:
+            Dictionary containing only the changed items
+        """
+        changes = {}
+        for key, data in items.items():
+            result = self.update(key, data)
+            if result is not None:
+                changes[key] = result
+        return changes
+
+    def reset(self, key: Optional[str] = None) -> None:
+        """
+        Reset tracked state.
+
+        Args:
+            key: Specific key to reset, or None to reset all
+        """
+        if key is not None:
+            self._states.pop(key, None)
+        else:
+            self._states.clear()
+
+    def has_key(self, key: str) -> bool:
+        """
+        Check if a key is being tracked.
+
+        Args:
+            key: The key to check
+
+        Returns:
+            True if the key is tracked, False otherwise
+        """
+        return key in self._states
+
+    def get_hash(self, key: str) -> Optional[str]:
+        """
+        Get the current hash for a tracked key.
+
+        Args:
+            key: The key to get the hash for
+
+        Returns:
+            The current hash, or None if not tracked
+        """
+        state = self._states.get(key)
+        return state.hash if state else None
+
+
+class ScanDeltaTracker(DeltaTracker):
+    """
+    Specialized delta tracker for scan results.
+
+    Tracks individual devices and overall scan metadata,
+    providing efficient delta updates for real-time scan monitoring.
+    """
+
+    def get_scan_delta(self, scan_results: dict) -> dict:
+        """
+        Get delta update for scan results.
+
+        Args:
+            scan_results: Full scan results dictionary
+
+        Returns:
+            Dictionary containing only changed fields:
+            - 'devices': List of changed device data
+            - 'metadata': Changed scan metadata (if any)
+            - 'has_changes': Boolean indicating if there are any changes
+        """
+        delta = {
+            'devices': [],
+            'metadata': None,
+            'has_changes': False
+        }
+
+        # Track metadata changes (everything except devices)
+        metadata = {k: v for k, v in scan_results.items() if k != 'devices'}
+        metadata_change = self.update('_metadata', metadata)
+        if metadata_change is not None:
+            delta['metadata'] = metadata_change
+            delta['has_changes'] = True
+
+        # Track individual device changes
+        devices = scan_results.get('devices', [])
+        for device in devices:
+            device_ip = device.get('ip', str(id(device)))
+            device_change = self.update(f'device_{device_ip}', device)
+            if device_change is not None:
+                delta['devices'].append(device_change)
+                delta['has_changes'] = True
+
+        return delta

lanscape-2.4.0b1/lanscape/ui/ws/handlers/__init__.py

@@ -0,0 +1,20 @@
+"""
+WebSocket handlers for LANscape.
+
+Provides handler classes for different functional areas:
+- ScanHandler: Network scanning operations
+- PortHandler: Port list management
+- ToolsHandler: Utility functions (subnet validation, etc.)
+"""
+
+from lanscape.ui.ws.handlers.base import BaseHandler
+from lanscape.ui.ws.handlers.scan import ScanHandler
+from lanscape.ui.ws.handlers.port import PortHandler
+from lanscape.ui.ws.handlers.tools import ToolsHandler
+
+__all__ = [
+    'BaseHandler',
+    'ScanHandler',
+    'PortHandler',
+    'ToolsHandler'
+]

lanscape-2.4.0b1/lanscape/ui/ws/handlers/base.py

@@ -0,0 +1,145 @@
+"""
+Base handler class for WebSocket handlers.
+
+Provides common functionality and interface for all handlers.
+"""
+
+import asyncio
+import logging
+import traceback
+from typing import Any, Callable, Optional
+
+from lanscape.ui.ws.protocol import WSRequest, WSResponse, WSError
+
+
+class BaseHandler:
+    """
+    Base class for WebSocket message handlers.
+
+    Provides registration of action handlers and dispatch logic.
+    Subclasses should register their handlers in __init__.
+    """
+
+    def __init__(self):
+        """Initialize the handler with an empty action registry."""
+        self._actions: dict[str, Callable] = {}
+        self.log = logging.getLogger(self.__class__.__name__)
+
+    @property
+    def prefix(self) -> str:
+        """
+        The action prefix for this handler.
+
+        Returns:
+            String prefix (e.g., 'scan', 'port', 'tools')
+        """
+        raise NotImplementedError("Subclasses must define a prefix")
+
+    def register(self, action: str, handler: Callable) -> None:
+        """
+        Register an action handler.
+
+        Args:
+            action: The action name (without prefix)
+            handler: The callable to handle the action
+        """
+        full_action = f"{self.prefix}.{action}"
+        self._actions[full_action] = handler
+        self.log.debug(f"Registered handler for action: {full_action}")
+
+    def can_handle(self, action: str) -> bool:
+        """
+        Check if this handler can process the given action.
+
+        Args:
+            action: The full action name
+
+        Returns:
+            True if this handler can process the action
+        """
+        return action in self._actions
+
+    def get_actions(self) -> list[str]:
+        """
+        Get all registered actions.
+
+        Returns:
+            List of action names this handler supports
+        """
+        return list(self._actions.keys())
+
+    async def handle(
+        self,
+        request: WSRequest,
+        send_event: Optional[Callable] = None
+    ) -> WSResponse | WSError:
+        """
+        Handle a WebSocket request.
+
+        Args:
+            request: The incoming request
+            send_event: Optional callback to send events to the client
+
+        Returns:
+            WSResponse on success, WSError on failure
+        """
+        action = request.action
+        handler = self._actions.get(action)
+
+        if handler is None:
+            return WSError(
+                id=request.id,
+                action=action,
+                error=f"Unknown action: {action}"
+            )
+
+        try:
+            params = request.params or {}
+            # Check if handler is async
+            if asyncio.iscoroutinefunction(handler):
+                result = await handler(params, send_event)
+            else:
+                result = handler(params, send_event)
+
+            return WSResponse(
+                id=request.id,
+                action=action,
+                data=result,
+                success=True
+            )
+        except Exception as e:
+            self.log.error(f"Error handling {action}: {e}")
+            self.log.debug(traceback.format_exc())
+            return WSError(
+                id=request.id,
+                action=action,
+                error=str(e),
+                traceback=traceback.format_exc()
+            )
+
+    def _get_param(
+        self,
+        params: dict[str, Any],
+        key: str,
+        required: bool = False,
+        default: Any = None
+    ) -> Any:
+        """
+        Get a parameter from the params dict with optional validation.
+
+        Args:
+            params: The parameters dictionary
+            key: The parameter key
+            required: Whether the parameter is required
+            default: Default value if not present
+
+        Returns:
+            The parameter value
+
+        Raises:
+            ValueError: If required parameter is missing
+        """
+        value = params.get(key, default)
+        if required and value is None:
+            raise ValueError(f"Missing required parameter: {key}")
+        return value

lanscape-2.4.0b1/lanscape/ui/ws/handlers/port.py

@@ -0,0 +1,184 @@
+"""
+WebSocket handler for port list management.
+
+Provides handlers for:
+- Listing port lists
+- Getting port list details
+- Creating, updating, deleting port lists
+"""
+
+from typing import Any, Callable, Optional
+
+from lanscape.core.port_manager import PortManager
+from lanscape.ui.ws.handlers.base import BaseHandler
+
+
+class PortHandler(BaseHandler):
+    """
+    Handler for port list management WebSocket actions.
+
+    Supports actions:
+    - port.list: Get all port list names
+    - port.list_summary: Get port lists with port counts
+    - port.get: Get a specific port list
+    - port.create: Create a new port list
+    - port.update: Update an existing port list
+    - port.delete: Delete a port list
+    """
+
+    def __init__(self, port_manager: Optional[PortManager] = None):
+        """
+        Initialize the port handler.
+
+        Args:
+            port_manager: Optional PortManager instance.
+        """
+        super().__init__()
+        self._port_manager = port_manager or PortManager()
+
+        # Register handlers
+        self.register('list', self._handle_list)
+        self.register('list_summary', self._handle_list_summary)
+        self.register('get', self._handle_get)
+        self.register('create', self._handle_create)
+        self.register('update', self._handle_update)
+        self.register('delete', self._handle_delete)
+
+    @property
+    def prefix(self) -> str:
+        """Return the action prefix for this handler."""
+        return 'port'
+
+    def _handle_list(
+        self,
+        params: dict[str, Any],  # pylint: disable=unused-argument
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> list:
+        """
+        Get all available port lists.
+
+        Returns:
+            List of port list names
+        """
+        return self._port_manager.get_port_lists()
+
+    def _handle_list_summary(
+        self,
+        params: dict[str, Any],  # pylint: disable=unused-argument
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> list:
+        """
+        Get port list names with their port counts.
+
+        Returns:
+            List of dicts with 'name' and 'count' keys
+        """
+        summaries = []
+        for name in self._port_manager.get_port_lists():
+            ports = self._port_manager.get_port_list(name) or {}
+            summaries.append({
+                'name': name,
+                'count': len(ports)
+            })
+        return summaries
+
+    def _handle_get(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Get a specific port list by name.
+
+        Params:
+            name: Name of the port list to retrieve
+
+        Returns:
+            Dict mapping port numbers to service names
+        """
+        name = self._get_param(params, 'name', required=True)
+        port_list = self._port_manager.get_port_list(name)
+
+        if port_list is None:
+            raise ValueError(f"Port list not found: {name}")
+
+        return port_list
+
+    def _handle_create(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Create a new port list.
+
+        Params:
+            name: Name for the new port list
+            ports: Dict mapping port numbers to service names
+
+        Returns:
+            Dict with success status
+        """
+        name = self._get_param(params, 'name', required=True)
+        ports = self._get_param(params, 'ports', required=True)
+
+        success = self._port_manager.create_port_list(name, ports)
+
+        if not success:
+            raise ValueError(
+                f"Failed to create port list '{name}'. "
+                "It may already exist or have invalid port data."
+            )
+
+        return {'success': True, 'name': name}
+
+    def _handle_update(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Update an existing port list.
+
+        Params:
+            name: Name of the port list to update
+            ports: New dict mapping port numbers to service names
+
+        Returns:
+            Dict with success status
+        """
+        name = self._get_param(params, 'name', required=True)
+        ports = self._get_param(params, 'ports', required=True)
+
+        success = self._port_manager.update_port_list(name, ports)
+
+        if not success:
+            raise ValueError(
+                f"Failed to update port list '{name}'. "
+                "It may not exist or have invalid port data."
+            )
+
+        return {'success': True, 'name': name}
+
+    def _handle_delete(
+        self,
+        params: dict[str, Any],
+        send_event: Optional[Callable] = None  # pylint: disable=unused-argument
+    ) -> dict:
+        """
+        Delete a port list.
+
+        Params:
+            name: Name of the port list to delete
+
+        Returns:
+            Dict with success status
+        """
+        name = self._get_param(params, 'name', required=True)
+
+        success = self._port_manager.delete_port_list(name)
+
+        if not success:
+            raise ValueError(f"Failed to delete port list '{name}'. It may not exist.")
+
+        return {'success': True, 'name': name}