webtap-tool 0.11.0__py3-none-any.whl

webtap/rpc/machine.py

@@ -0,0 +1,84 @@
+"""Connection state machine using transitions library.
+
+PUBLIC API:
+  - ConnectionState: Enum of connection lifecycle states
+  - ConnectionMachine: Thread-safe state machine for connection management
+"""
+
+from enum import Enum
+from typing import Any
+
+from transitions.extensions import LockedMachine
+
+
+class ConnectionState(str, Enum):
+    """Connection lifecycle states.
+
+    Attributes:
+        DISCONNECTED: Not connected to any Chrome page
+        CONNECTING: Connection in progress
+        CONNECTED: Connected and ready for operations
+        INSPECTING: Element selection mode active
+        DISCONNECTING: Cleanup in progress
+    """
+
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    INSPECTING = "inspecting"
+    DISCONNECTING = "disconnecting"
+
+
+class ConnectionMachine(LockedMachine):  # type: ignore
+    """Thread-safe state machine for WebTap connection lifecycle.
+
+    States:
+        - disconnected: Not connected to any Chrome page
+        - connecting: Connection in progress
+        - connected: Connected and ready for operations
+        - inspecting: Element selection mode active
+        - disconnecting: Cleanup in progress
+
+    The machine uses LockedMachine for thread safety and queued transitions.
+    Epoch counter is incremented on successful connection.
+    """
+
+    def __init__(self):
+        """Initialize the connection state machine."""
+        _states = [s.value for s in ConnectionState]
+        _transitions: list[dict[str, Any]] = [
+            {"trigger": "start_connect", "source": ["disconnected", "connected", "inspecting"], "dest": "connecting"},
+            {
+                "trigger": "connect_success",
+                "source": "connecting",
+                "dest": "connected",
+                "after": "_increment_epoch",
+            },
+            {"trigger": "connect_failed", "source": "connecting", "dest": "disconnected"},
+            {"trigger": "start_inspect", "source": "connected", "dest": "inspecting"},
+            {"trigger": "stop_inspect", "source": "inspecting", "dest": "connected"},
+            {
+                "trigger": "start_disconnect",
+                "source": ["connected", "inspecting"],
+                "dest": "disconnecting",
+            },
+            {
+                "trigger": "disconnect_complete",
+                "source": ["disconnecting", "connecting"],
+                "dest": "disconnected",
+            },
+            {"trigger": "force_disconnect", "source": "*", "dest": "disconnected"},
+        ]
+
+        super().__init__(
+            states=_states,
+            transitions=_transitions,
+            initial="disconnected",
+            auto_transitions=False,
+            queued=True,
+        )
+        self.epoch = 0
+
+    def _increment_epoch(self):
+        """Increment epoch counter on successful connection."""
+        self.epoch += 1

webtap/services/README.md

@@ -0,0 +1,83 @@
+# WebTap Services Layer
+
+The services layer provides clean, reusable interfaces for querying and managing CDP events stored in DuckDB.
+
+## Architecture
+
+```
+commands/ → RPCClient → /rpc endpoint → RPCFramework → services/ → cdp/session → DuckDB
+                              ↓
+                     rpc/handlers.py (thin wrappers)
+```
+
+## Services
+
+### WebTapService (`main.py`)
+Main orchestrator that manages all domain-specific services and CDP connection.
+
+**Key Properties:**
+- `event_count` - Total CDP events stored
+
+**Key Methods:**
+- `connect_to_page()` - Connect and enable CDP domains
+- `disconnect()` - Clean disconnection
+- `get_status()` - Comprehensive status with metrics from all services
+
+### FetchService (`fetch.py`)
+Manages HTTP request/response interception.
+
+**Key Properties:**
+- `paused_count` - Number of paused requests
+
+**Key Methods:**
+- `get_paused_rowids()` - List of paused request rowids
+- `enable()` / `disable()` - Control interception
+- `continue_request()` / `fail_request()` - Process paused requests
+
+### NetworkService (`network.py`)
+Queries network events (requests/responses).
+
+**Key Properties:**
+- `request_count` - Total network requests
+
+**Key Methods:**
+- `get_recent_requests()` - Network events with filter support
+- `get_failed_requests()` - 4xx/5xx errors
+- `get_request_by_id()` - All events for a request
+
+### ConsoleService (`console.py`)
+Queries console messages and browser logs.
+
+**Key Properties:**
+- `message_count` - Total console messages
+- `error_count` - Console errors only
+
+**Key Methods:**
+- `get_recent_messages()` - Console events with level filter
+- `get_errors()` / `get_warnings()` - Filtered queries
+- `clear_browser_console()` - CDP command to clear console
+
+## Design Principles
+
+1. **Rowid-Native**: All queries return rowid as primary identifier
+2. **Direct Queries**: No caching, query DuckDB on-demand
+3. **Properties for Counts**: Common counts exposed as properties
+4. **Methods for Queries**: Complex queries as methods with parameters
+5. **Service Isolation**: Each service manages its domain independently
+
+## Usage
+
+Services are accessed through the WebTapState:
+
+```python
+# In commands (via RPC)
+@app.command()
+def network(state, limit: int = 50):
+    result = state.client.call("network", limit=limit)
+    return table_response(result["requests"], ...)
+
+# In RPC handlers (thin wrappers)
+def network(ctx: RPCContext, limit: int = 50) -> dict:
+    requests = ctx.service.network.get_requests(limit=limit)
+    return {"requests": requests}
+```

webtap/services/__init__.py

@@ -0,0 +1,15 @@
+"""WebTap service layer for managing CDP state and operations.
+
+The service layer provides a clean interface between REPL commands/API endpoints
+and the underlying CDP session. Services encapsulate domain-specific queries and
+operations, making them reusable across different interfaces.
+
+PUBLIC API:
+  - WebTapService: Main service orchestrating all domain services
+  - SetupService: Service for installing WebTap components
+"""
+
+from webtap.services.main import WebTapService
+from webtap.services.setup import SetupService
+
+__all__ = ["WebTapService", "SetupService"]

webtap/services/console.py

@@ -0,0 +1,124 @@
+"""Console monitoring service for browser messages."""
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from webtap.cdp import CDPSession
+
+logger = logging.getLogger(__name__)
+
+
+class ConsoleService:
+    """Console event queries and monitoring.
+
+    Provides access to browser console messages captured via CDP.
+    Supports filtering by level (error, warning, log, info) and
+    querying message counts.
+
+    Attributes:
+        cdp: CDP session for querying events
+    """
+
+    def __init__(self):
+        """Initialize console service."""
+        self.cdp: CDPSession | None = None
+
+    @property
+    def message_count(self) -> int:
+        """Count of all console messages."""
+        if not self.cdp:
+            return 0
+        result = self.cdp.query(
+            "SELECT COUNT(*) FROM events WHERE method IN ('Runtime.consoleAPICalled', 'Log.entryAdded')"
+        )
+        return result[0][0] if result else 0
+
+    @property
+    def error_count(self) -> int:
+        """Count of console errors."""
+        if not self.cdp:
+            return 0
+        result = self.cdp.query("""
+            SELECT COUNT(*) FROM events
+            WHERE method IN ('Runtime.consoleAPICalled', 'Log.entryAdded')
+            AND (
+                json_extract_string(event, '$.params.type') = 'error'
+                OR json_extract_string(event, '$.params.entry.level') = 'error'
+            )
+        """)
+        return result[0][0] if result else 0
+
+    def get_recent_messages(self, limit: int = 50, level: str | None = None) -> list[tuple]:
+        """Get recent console messages with common fields extracted.
+
+        Args:
+            limit: Maximum results
+            level: Optional filter by level (error, warning, log, info)
+        """
+        if not self.cdp:
+            return []
+
+        sql = """
+        SELECT 
+            rowid,
+            COALESCE(
+                json_extract_string(event, '$.params.type'),
+                json_extract_string(event, '$.params.entry.level')
+            ) as Level,
+            COALESCE(
+                json_extract_string(event, '$.params.source'),
+                json_extract_string(event, '$.params.entry.source'),
+                'console'
+            ) as Source,
+            COALESCE(
+                json_extract_string(event, '$.params.args[0].value'),
+                json_extract_string(event, '$.params.entry.text')
+            ) as Message,
+            COALESCE(
+                json_extract_string(event, '$.params.timestamp'),
+                json_extract_string(event, '$.params.entry.timestamp')
+            ) as Time
+        FROM events
+        WHERE method IN ('Runtime.consoleAPICalled', 'Log.entryAdded')
+        """
+
+        if level:
+            sql += f"""
+            AND (
+                json_extract_string(event, '$.params.type') = '{level.lower()}'
+                OR json_extract_string(event, '$.params.entry.level') = '{level.lower()}'
+            )
+            """
+
+        sql += f" ORDER BY rowid DESC LIMIT {limit}"
+
+        return self.cdp.query(sql)
+
+    def get_errors(self, limit: int = 20) -> list[tuple]:
+        """Get console errors only.
+
+        Args:
+            limit: Maximum results
+        """
+        return self.get_recent_messages(limit=limit, level="error")
+
+    def get_warnings(self, limit: int = 20) -> list[tuple]:
+        """Get console warnings only.
+
+        Args:
+            limit: Maximum results
+        """
+        return self.get_recent_messages(limit=limit, level="warning")
+
+    def clear_browser_console(self) -> bool:
+        """Clear console in the browser (CDP command)."""
+        if not self.cdp:
+            return False
+
+        try:
+            self.cdp.execute("Runtime.discardConsoleEntries")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to clear browser console: {e}")
+            return False