webtap-tool 0.11.0__py3-none-any.whl

webtap/filters.py

@@ -0,0 +1,219 @@
+"""Network request filter management for WebTap."""
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class FilterGroup:
+    """A named filter group with hide configuration."""
+
+    hide: dict  # {"types": [...], "urls": [...]}
+
+
+class FilterManager:
+    """Manages filter groups with file persistence and memory toggle state.
+
+    Groups define what to hide (types, URL patterns). Enabled state is in-memory
+    only - all groups start disabled on load. Group definitions persist to file.
+    """
+
+    def __init__(self, filter_path: Path | str | None = None):
+        """Initialize filter manager.
+
+        Args:
+            filter_path: Path to filters.json. Defaults to .webtap/filters.json.
+        """
+        if filter_path is None:
+            self.filter_path = Path.cwd() / ".webtap" / "filters.json"
+        else:
+            self.filter_path = Path(filter_path)
+        self.groups: dict[str, FilterGroup] = {}
+        self.enabled: set[str] = set()
+
+    def load(self) -> bool:
+        """Load group definitions from file. All disabled by default.
+
+        Returns:
+            True if loaded successfully, False otherwise.
+        """
+        if self.filter_path.exists():
+            try:
+                with open(self.filter_path) as f:
+                    data = json.load(f)
+                self.groups = {
+                    name: FilterGroup(hide=cfg.get("hide", {"types": [], "urls": []}))
+                    for name, cfg in data.get("groups", {}).items()
+                }
+                self.enabled = set()  # All disabled on load
+                logger.info(f"Loaded {len(self.groups)} filter groups from {self.filter_path}")
+                return True
+            except Exception as e:
+                logger.error(f"Failed to load filters: {e}")
+                self.groups = {}
+                return False
+        else:
+            logger.debug(f"No filters found at {self.filter_path}")
+            self.groups = {}
+            return False
+
+    def save(self) -> bool:
+        """Save group definitions to file (not enabled state).
+
+        Returns:
+            True if saved successfully, False on error.
+        """
+        try:
+            self.filter_path.parent.mkdir(parents=True, exist_ok=True)
+            data = {"groups": {name: {"hide": group.hide} for name, group in self.groups.items()}}
+            with open(self.filter_path, "w") as f:
+                json.dump(data, f, indent=2)
+            logger.info(f"Saved filters to {self.filter_path}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to save filters: {e}")
+            return False
+
+    def add(self, name: str, hide: dict) -> None:
+        """Add a group definition and persist to file.
+
+        Args:
+            name: Group name.
+            hide: Filter config {"types": [...], "urls": [...]}.
+        """
+        # Ensure hide has required keys
+        normalized_hide = {
+            "types": hide.get("types", []),
+            "urls": hide.get("urls", []),
+        }
+        self.groups[name] = FilterGroup(hide=normalized_hide)
+        self.save()
+
+    def remove(self, name: str) -> bool:
+        """Remove a group and persist to file.
+
+        Args:
+            name: Group name to remove.
+
+        Returns:
+            True if removed, False if not found.
+        """
+        if name in self.groups:
+            del self.groups[name]
+            self.enabled.discard(name)
+            self.save()
+            return True
+        return False
+
+    def enable(self, name: str) -> bool:
+        """Enable a group (in-memory only).
+
+        Args:
+            name: Group name to enable.
+
+        Returns:
+            True if group exists and was enabled, False otherwise.
+        """
+        if name in self.groups:
+            self.enabled.add(name)
+            return True
+        return False
+
+    def disable(self, name: str) -> bool:
+        """Disable a group (in-memory only).
+
+        Args:
+            name: Group name to disable.
+
+        Returns:
+            True if group exists and was disabled, False otherwise.
+        """
+        if name in self.groups:
+            self.enabled.discard(name)
+            return True
+        return False
+
+    def get_active_filters(self) -> dict:
+        """Get consolidated filters from enabled groups (deduplicated).
+
+        Returns:
+            Dict with "types" and "urls" lists from all enabled groups.
+        """
+        hide_types: set[str] = set()
+        hide_urls: set[str] = set()
+        for name in self.enabled:
+            if name in self.groups:
+                hide_types.update(self.groups[name].hide.get("types", []))
+                hide_urls.update(self.groups[name].hide.get("urls", []))
+        return {"types": list(hide_types), "urls": list(hide_urls)}
+
+    def get_status(self) -> dict:
+        """Get all groups with enabled status.
+
+        Returns:
+            Dict mapping group names to their config and enabled status.
+        """
+        return {
+            name: {
+                "enabled": name in self.enabled,
+                "hide": group.hide,
+            }
+            for name, group in self.groups.items()
+        }
+
+    def build_filter_sql(
+        self,
+        status: int | None = None,
+        method: str | None = None,
+        type_filter: str | None = None,
+        url: str | None = None,
+        apply_groups: bool = True,
+    ) -> str:
+        """Build SQL WHERE conditions for har_summary filtering.
+
+        Args:
+            status: Filter by HTTP status code.
+            method: Filter by HTTP method.
+            type_filter: Filter by resource type.
+            url: Filter by URL pattern (supports * wildcard).
+            apply_groups: Apply enabled filter groups.
+
+        Returns:
+            SQL WHERE clause conditions (without WHERE keyword).
+        """
+        conditions = []
+
+        # Inline filters
+        if status is not None:
+            conditions.append(f"status = {status}")
+        if method:
+            conditions.append(f"UPPER(method) = '{method.upper()}'")
+        if type_filter:
+            conditions.append(f"LOWER(type) = '{type_filter.lower()}'")
+        if url:
+            sql_pattern = url.replace("'", "''").replace("*", "%")
+            conditions.append(f"url LIKE '{sql_pattern}'")
+
+        # Apply enabled filter groups
+        if apply_groups:
+            active = self.get_active_filters()
+
+            # Hide matching types
+            if active["types"]:
+                escaped_types = [t.replace("'", "''") for t in active["types"]]
+                type_list = ", ".join(f"'{t}'" for t in escaped_types)
+                conditions.append(f"type NOT IN ({type_list})")
+
+            # Hide matching URLs
+            for pattern in active["urls"]:
+                sql_pattern = pattern.replace("'", "''").replace("*", "%")
+                conditions.append(f"url NOT LIKE '{sql_pattern}'")
+
+        return " AND ".join(conditions) if conditions else ""
+
+
+__all__ = ["FilterManager"]

webtap/rpc/__init__.py

@@ -0,0 +1,14 @@
+"""WebTap RPC Framework.
+
+PUBLIC API:
+  - RPCFramework: Core RPC request/response handler
+  - RPCError: Exception class for structured errors
+  - ErrorCode: Standard RPC error codes
+  - ConnectionState: Connection state machine states
+"""
+
+from webtap.rpc.errors import ErrorCode, RPCError
+from webtap.rpc.framework import RPCFramework
+from webtap.rpc.machine import ConnectionState
+
+__all__ = ["RPCFramework", "RPCError", "ErrorCode", "ConnectionState"]

webtap/rpc/errors.py

@@ -0,0 +1,49 @@
+"""RPC error definitions.
+
+PUBLIC API:
+  - ErrorCode: Standard JSON-RPC 2.0 error codes
+  - RPCError: Structured exception for RPC errors
+"""
+
+from typing import Any
+
+
+class ErrorCode:
+    """Standard JSON-RPC 2.0 error codes.
+
+    Attributes:
+        METHOD_NOT_FOUND: RPC method not found
+        INVALID_STATE: Operation invalid in current state
+        STALE_EPOCH: Request epoch does not match current epoch
+        INVALID_PARAMS: Invalid or missing parameters
+        INTERNAL_ERROR: Internal server error
+        NOT_CONNECTED: Not connected to a Chrome page
+    """
+
+    METHOD_NOT_FOUND = "METHOD_NOT_FOUND"
+    INVALID_STATE = "INVALID_STATE"
+    STALE_EPOCH = "STALE_EPOCH"
+    INVALID_PARAMS = "INVALID_PARAMS"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    NOT_CONNECTED = "NOT_CONNECTED"
+
+
+class RPCError(Exception):
+    """Structured RPC error with code, message, and optional data.
+
+    Args:
+        code: Error code from ErrorCode constants
+        message: Human-readable error message
+        data: Optional additional error details
+
+    Attributes:
+        code: Error code
+        message: Error message
+        data: Additional error details
+    """
+
+    def __init__(self, code: str, message: str, data: dict[str, Any] | None = None):
+        self.code = code
+        self.message = message
+        self.data = data or {}
+        super().__init__(message)

webtap/rpc/framework.py

@@ -0,0 +1,223 @@
+"""RPC framework for JSON-RPC 2.0 request handling.
+
+PUBLIC API:
+  - RPCFramework: Core RPC request/response handler with method registration
+  - RPCContext: Context passed to RPC handlers
+  - HandlerMeta: Metadata for RPC handler registration
+"""
+
+import asyncio
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from webtap.rpc.errors import ErrorCode, RPCError
+
+if TYPE_CHECKING:
+    from webtap.rpc.machine import ConnectionMachine
+    from webtap.services.main import WebTapService
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RPCContext:
+    """Context passed to RPC handlers.
+
+    Attributes:
+        service: WebTapService instance for accessing CDP and domain services
+        machine: ConnectionMachine for state management
+        epoch: Current connection epoch
+        request_id: JSON-RPC request ID
+    """
+
+    service: "WebTapService"
+    machine: "ConnectionMachine"
+    epoch: int
+    request_id: str
+
+
+@dataclass
+class HandlerMeta:
+    """Metadata for RPC handler registration.
+
+    Attributes:
+        requires_state: List of valid connection states for this handler
+        broadcasts: Whether to trigger SSE broadcast after successful execution. Defaults to True.
+        requires_paused_request: Whether to lookup and inject paused request into kwargs. Defaults to False.
+    """
+
+    requires_state: list[str]
+    broadcasts: bool = True
+    requires_paused_request: bool = False
+
+
+class RPCFramework:
+    """JSON-RPC 2.0 framework with state machine integration.
+
+    Handles JSON-RPC 2.0 request routing, validation, and response formatting.
+    Integrates with ConnectionMachine for state management.
+    """
+
+    def __init__(self, service: "WebTapService"):
+        self.service = service
+        from webtap.rpc.machine import ConnectionMachine
+
+        self.machine = ConnectionMachine()
+        self.handlers: dict[str, tuple[Callable, HandlerMeta]] = {}
+
+    def method(
+        self,
+        name: str,
+        requires_state: list[str] | None = None,
+        broadcasts: bool = True,
+        requires_paused_request: bool = False,
+    ) -> Callable:
+        """Decorator to register RPC method handlers.
+
+        Args:
+            name: RPC method name (e.g., "connect", "browser.startInspect")
+            requires_state: List of valid states for this method. Defaults to None.
+            broadcasts: Whether to trigger SSE broadcast after successful execution. Defaults to True.
+            requires_paused_request: Auto-lookup paused request by 'id' param and inject as 'paused'. Defaults to False.
+
+        Returns:
+            Decorator function for handler registration.
+
+        Example:
+            @rpc.method("connect")
+            def connect(ctx: RPCContext, page_id: str = None) -> dict:
+                return {"connected": True}
+        """
+
+        def decorator(func: Callable) -> Callable:
+            meta = HandlerMeta(
+                requires_state=requires_state or [],
+                broadcasts=broadcasts,
+                requires_paused_request=requires_paused_request,
+            )
+            self.handlers[name] = (func, meta)
+            return func
+
+        return decorator
+
+    async def handle(self, request: dict) -> dict:
+        """Handle JSON-RPC 2.0 request.
+
+        Validates request format, routes to handler, manages state transitions.
+
+        Args:
+            request: JSON-RPC 2.0 request dict
+
+        Returns:
+            JSON-RPC 2.0 response dict (success or error)
+        """
+        request_id = request.get("id", "")
+
+        try:
+            # Validate JSON-RPC 2.0 format
+            if request.get("jsonrpc") != "2.0":
+                return self._error_response(request_id, ErrorCode.INVALID_PARAMS, "Invalid JSON-RPC version")
+
+            method = request.get("method")
+            if not method:
+                return self._error_response(request_id, ErrorCode.INVALID_PARAMS, "Missing method")
+
+            params = request.get("params", {})
+
+            # Find handler
+            if method not in self.handlers:
+                return self._error_response(request_id, ErrorCode.METHOD_NOT_FOUND, f"Unknown method: {method}")
+
+            handler, meta = self.handlers[method]
+
+            # Validate state requirements
+            current_state = self.machine.state
+            if meta.requires_state and current_state not in meta.requires_state:
+                return self._error_response(
+                    request_id,
+                    ErrorCode.INVALID_STATE,
+                    f"Method {method} requires state {meta.requires_state}, current: {current_state}",
+                    {"current_state": current_state, "required_states": meta.requires_state},
+                )
+
+            # Validate epoch (if provided)
+            request_epoch = request.get("epoch")
+            if request_epoch is not None and request_epoch != self.machine.epoch:
+                return self._error_response(
+                    request_id,
+                    ErrorCode.STALE_EPOCH,
+                    f"Request epoch {request_epoch} does not match current {self.machine.epoch}",
+                    {"request_epoch": request_epoch, "current_epoch": self.machine.epoch},
+                )
+
+            # Create context
+            ctx = RPCContext(
+                service=self.service, machine=self.machine, epoch=self.machine.epoch, request_id=request_id
+            )
+
+            # Auto-lookup paused request if required
+            if meta.requires_paused_request:
+                request_id_param = params.get("id")
+                if request_id_param is None:
+                    return self._error_response(request_id, ErrorCode.INVALID_PARAMS, "Missing 'id' parameter")
+
+                network_id = self.service.network.get_request_id(request_id_param)
+                if not network_id:
+                    return self._error_response(
+                        request_id, ErrorCode.INVALID_PARAMS, f"Request {request_id_param} not found"
+                    )
+
+                paused = self.service.fetch.get_paused_by_network_id(network_id)
+                if not paused:
+                    return self._error_response(
+                        request_id, ErrorCode.INVALID_PARAMS, f"Request {request_id_param} is not paused"
+                    )
+
+                params["paused"] = paused
+
+            # Execute handler in thread pool (service methods are sync)
+            try:
+                result = await asyncio.to_thread(handler, ctx, **params)
+
+                # Auto-broadcast for state-modifying handlers
+                if meta.broadcasts:
+                    self.service._trigger_broadcast()
+
+                return self._success_response(request_id, result)
+            except RPCError as e:
+                return self._error_response(request_id, e.code, e.message, e.data)
+            except TypeError as e:
+                # Parameter mismatch (missing/extra params)
+                return self._error_response(request_id, ErrorCode.INVALID_PARAMS, f"Invalid parameters: {e}")
+            except Exception as e:
+                logger.exception(f"RPC handler error: {method}")
+                return self._error_response(request_id, ErrorCode.INTERNAL_ERROR, str(e))
+
+        except Exception as e:
+            logger.exception("RPC request processing error")
+            return self._error_response(request_id, ErrorCode.INTERNAL_ERROR, str(e))
+
+    def _success_response(self, request_id: str, result: Any) -> dict:
+        """Build JSON-RPC 2.0 success response.
+
+        Args:
+            request_id: JSON-RPC request ID
+            result: Result data to return
+        """
+        return {"jsonrpc": "2.0", "id": request_id, "result": result, "epoch": self.machine.epoch}
+
+    def _error_response(self, request_id: str, code: str, message: str, data: dict | None = None) -> dict:
+        """Build JSON-RPC 2.0 error response.
+
+        Args:
+            request_id: JSON-RPC request ID
+            code: Error code
+            message: Error message
+            data: Optional error data
+        """
+        error: dict[str, Any] = {"code": code, "message": message}
+        if data:
+            error["data"] = data
+        return {"jsonrpc": "2.0", "id": request_id, "error": error, "epoch": self.machine.epoch}