machinaos 0.0.1

package/server/services/android/client.py

@@ -0,0 +1,608 @@
+"""
+Android Services Relay WebSocket Client
+
+Handles WebSocket connection to relay server and communication with paired Android device.
+
+Connection flow:
+1. Connect to wss://<relay-server>/ws?client_type=web&api_key=<your-api-key>
+2. Receive connection.established with session_token and qr_data
+3. Display QR code for Android to scan
+4. Receive pairing.connected when Android pairs
+5. Exchange messages via relay.send / relay.message
+"""
+import asyncio
+import json
+import uuid
+import aiohttp
+from typing import Optional, Dict, Any, Set, Callable
+from datetime import datetime
+import structlog
+
+from .protocol import RPCRequest, RPCResponse, RPCEvent, RPCRequestTracker, parse_message, is_response
+from .broadcaster import (
+    broadcast_android_status,
+    broadcast_connected,
+    broadcast_device_disconnected,
+    broadcast_relay_disconnected,
+    broadcast_qr_code
+)
+
+logger = structlog.get_logger()
+
+
+class RelayWebSocketClient:
+    """WebSocket client for Android Services Relay using JSON-RPC 2.0 protocol"""
+
+    def __init__(self, base_url: str, api_key: str):
+        """
+        Initialize relay client.
+
+        Args:
+            base_url: Base WebSocket URL (e.g., 'wss://your-relay-server.com/ws')
+            api_key: API key for authentication
+        """
+        self.base_url = base_url
+        self.api_key = api_key
+        self.url = f"{base_url}?client_type=web&api_key={api_key}"
+
+        # WebSocket connection
+        self.ws: Optional[aiohttp.ClientWebSocketResponse] = None
+        self.session: Optional[aiohttp.ClientSession] = None
+        self.connected = False
+
+        # JSON-RPC request tracking
+        self._rpc_tracker = RPCRequestTracker()
+
+        # Pairing state
+        self.session_token: Optional[str] = None
+        self.qr_data: Optional[str] = None
+        self.paired = False
+        self.paired_device_id: Optional[str] = None
+        self.paired_device_name: Optional[str] = None
+
+        # Background tasks
+        self._receive_task: Optional[asyncio.Task] = None
+        self._keepalive_task: Optional[asyncio.Task] = None
+        self._running = False
+
+        # Service response queues (requestId -> queue)
+        self._service_queues: Dict[str, asyncio.Queue] = {}
+
+        # Event callbacks
+        self.on_pairing_connected: Optional[Callable] = None
+        self.on_pairing_disconnected: Optional[Callable] = None
+        self.on_relay_message: Optional[Callable] = None
+
+    # =========================================================================
+    # Connection Management
+    # =========================================================================
+
+    async def connect(self) -> tuple[bool, str]:
+        """Connect to relay WebSocket server.
+
+        Returns:
+            Tuple of (success: bool, error_message: str)
+        """
+        try:
+            logger.info("[Relay] Connecting...", url=self.url)
+            timeout = aiohttp.ClientTimeout(total=None, connect=10, sock_read=300)
+            self.session = aiohttp.ClientSession(timeout=timeout)
+
+            self.ws = await self.session.ws_connect(
+                self.url,
+                heartbeat=30,
+                autoping=True,
+                ssl=True  # Explicit SSL for wss://
+            )
+            self.connected = True
+            self._running = True
+
+            logger.info("[Relay] WebSocket connected, waiting for server message...", url=self.base_url)
+
+            # Wait for connection.established event
+            msg = await asyncio.wait_for(self.ws.receive(), timeout=10.0)
+
+            if msg.type == aiohttp.WSMsgType.TEXT:
+                data = json.loads(msg.data)
+                method = data.get("method")
+                logger.info("[Relay] Received initial message", method=method)
+
+                # Handle both "welcome" and "connection.established" methods
+                if method in ("welcome", "connection.established"):
+                    params = data.get("params", {})
+                    self.session_token = params.get("session_token")
+                    self.qr_data = params.get("qr_data")
+
+                    logger.info("[Relay] Connection established",
+                               session_token=self.session_token,
+                               has_qr=bool(self.qr_data))
+
+                    # Broadcast QR data to frontend
+                    if self.qr_data:
+                        await broadcast_qr_code(self.qr_data)
+
+                    # Start background tasks
+                    self._receive_task = asyncio.create_task(self._receive_loop())
+                    self._keepalive_task = asyncio.create_task(self._keepalive_loop())
+
+                    return True, ""
+                elif data.get("error"):
+                    error_msg = data.get("error", {}).get("message", "Unknown server error")
+                    logger.error("[Relay] Server error", error=error_msg)
+                    return False, f"Server error: {error_msg}"
+                else:
+                    logger.error("[Relay] Unexpected initial message", data=data)
+                    return False, f"Unexpected response: {method or 'unknown'}"
+
+            elif msg.type == aiohttp.WSMsgType.CLOSE:
+                close_code = msg.data
+                close_reason = msg.extra or "Unknown"
+                logger.error("[Relay] Connection closed by server", code=close_code, reason=close_reason)
+                return False, f"Connection closed: {close_reason} (code {close_code})"
+
+            elif msg.type == aiohttp.WSMsgType.ERROR:
+                logger.error("[Relay] WebSocket error on receive")
+                return False, "WebSocket error during handshake"
+
+            return False, "No response from server"
+
+        except asyncio.TimeoutError:
+            logger.error("[Relay] Connection timeout")
+            return False, "Connection timeout - server not responding"
+        except aiohttp.ClientConnectorError as e:
+            logger.error("[Relay] Connection failed", error=str(e))
+            return False, f"Cannot connect to server: {str(e)}"
+        except aiohttp.WSServerHandshakeError as e:
+            logger.error("[Relay] WebSocket handshake failed", error=str(e))
+            return False, f"WebSocket handshake failed: {str(e)}"
+        except Exception as e:
+            logger.error("[Relay] Connection error", error=str(e), exc_info=True)
+            return False, f"Connection error: {str(e)}"
+
+    async def disconnect(self, clear_stored_session: bool = True):
+        """Close connection and cleanup.
+
+        Args:
+            clear_stored_session: If True, clear stored pairing session from database.
+                                  Set to False when disconnecting due to connection drop
+                                  (will try to auto-reconnect later).
+        """
+        logger.info("[Relay] Disconnecting...", clear_stored_session=clear_stored_session)
+        self._running = False
+
+        # Cancel background tasks
+        for task in [self._keepalive_task, self._receive_task]:
+            if task and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+
+        # Close WebSocket
+        if self.ws and not self.ws.closed:
+            await self.ws.close()
+
+        if self.session and not self.session.closed:
+            await self.session.close()
+
+        # Reset state
+        self.connected = False
+        self.paired = False
+        self.paired_device_id = None
+        self.paired_device_name = None
+        self.session_token = None
+        self.qr_data = None
+
+        # Cancel pending RPC requests
+        self._rpc_tracker.cancel_all()
+
+        # Clear stored session if explicitly disconnecting
+        if clear_stored_session:
+            await self._clear_stored_session()
+
+        # Broadcast relay disconnection (fully disconnected from relay server)
+        await broadcast_relay_disconnected()
+
+        logger.info("[Relay] Disconnected")
+
+    async def _clear_stored_session(self):
+        """Clear stored pairing session from database."""
+        try:
+            from core.container import container
+            database = container.database()
+
+            await database.clear_android_relay_session()
+            logger.info("[Relay] Cleared stored pairing session")
+        except Exception as e:
+            logger.warning("[Relay] Failed to clear stored session", error=str(e))
+
+    def is_connected(self) -> bool:
+        """Check if connected to relay server."""
+        return self.connected and self._running and self.ws is not None and not self.ws.closed
+
+    def is_paired(self) -> bool:
+        """Check if paired with Android device."""
+        return self.paired and self.paired_device_id is not None
+
+    # =========================================================================
+    # Background Tasks
+    # =========================================================================
+
+    async def _receive_loop(self):
+        """Background task to receive messages."""
+        logger.info("[Relay] Receive loop started")
+        unexpected_disconnect = False
+        try:
+            while self._running and self.ws and not self.ws.closed:
+                try:
+                    msg = await self.ws.receive()
+
+                    if msg.type == aiohttp.WSMsgType.TEXT:
+                        data = json.loads(msg.data)
+                        await self._handle_message(data)
+
+                    elif msg.type == aiohttp.WSMsgType.CLOSED:
+                        logger.warning("[Relay] Connection closed by server")
+                        self._running = False
+                        unexpected_disconnect = True
+                        break
+
+                    elif msg.type == aiohttp.WSMsgType.ERROR:
+                        logger.error("[Relay] WebSocket error")
+                        self._running = False
+                        unexpected_disconnect = True
+                        break
+
+                except Exception as e:
+                    logger.error("[Relay] Receive error", error=str(e))
+                    await asyncio.sleep(1)
+
+        except asyncio.CancelledError:
+            pass
+        finally:
+            self._running = False
+            self.connected = False
+            logger.info("[Relay] Receive loop stopped")
+
+            # Broadcast relay disconnection if connection dropped unexpectedly
+            if unexpected_disconnect:
+                try:
+                    await broadcast_relay_disconnected()
+                except Exception as e:
+                    logger.warning("[Relay] Failed to broadcast disconnection", error=str(e))
+
+    async def _keepalive_loop(self):
+        """Background keepalive task."""
+        try:
+            while self._running and self.ws and not self.ws.closed:
+                await asyncio.sleep(25)
+                if self._running and self.ws and not self.ws.closed:
+                    try:
+                        await self.ws.send_json({
+                            "jsonrpc": "2.0",
+                            "method": "ping",
+                            "params": {}
+                        })
+                    except Exception as e:
+                        logger.error("[Relay] Keepalive error", error=str(e))
+                        self._running = False
+                        break
+        except asyncio.CancelledError:
+            pass
+
+    # =========================================================================
+    # Message Handling
+    # =========================================================================
+
+    async def _handle_message(self, data: dict):
+        """Handle incoming JSON-RPC message."""
+        # Log ALL incoming messages for debugging
+        method = data.get("method", "")
+        logger.info("[Relay] Received message", method=method, has_result="result" in data, has_error="error" in data)
+
+        # Check if response to pending request
+        if is_response(data):
+            response = RPCResponse.from_dict(data)
+            logger.debug("[Relay] Processing as RPC response", id=response.id)
+            if self._rpc_tracker.resolve(response):
+                return
+
+        # Handle server events
+        params = data.get("params", {})
+
+        if method == "pairing.connected":
+            await self._handle_pairing_connected(params)
+
+        elif method == "pairing.restored":
+            # Handle auto-reconnect of previously paired device
+            await self._handle_pairing_restored(params)
+
+        elif method == "pairing.disconnected":
+            await self._handle_pairing_disconnected(params)
+
+        elif method == "relay.message":
+            await self._handle_relay_message(params)
+
+        elif method == "connection.established":
+            # Reconnect scenario
+            self.session_token = params.get("session_token")
+            self.qr_data = params.get("qr_data")
+            if self.qr_data:
+                await broadcast_qr_code(self.qr_data)
+
+    async def _handle_pairing_connected(self, params: dict):
+        """Handle pairing.connected event."""
+        self.paired = True
+        self.paired_device_id = params.get("device_id")
+        self.paired_device_name = params.get("device_name")
+
+        logger.info("[Relay] Android paired",
+                   device_id=self.paired_device_id,
+                   device_name=self.paired_device_name)
+
+        await broadcast_connected(self.paired_device_id, self.paired_device_name)
+
+        # Persist pairing data for auto-reconnect on server restart
+        await self._save_pairing_session()
+
+        if self.on_pairing_connected:
+            await self.on_pairing_connected(params)
+
+    async def _handle_pairing_restored(self, params: dict):
+        """Handle pairing.restored event - auto-reconnect of previously paired device."""
+        self.paired = True
+        self.paired_device_id = params.get("device_id")
+        self.paired_device_name = params.get("device_name")
+
+        logger.info("[Relay] Android pairing restored (auto-reconnect)",
+                   device_id=self.paired_device_id,
+                   device_name=self.paired_device_name)
+
+        await broadcast_connected(self.paired_device_id, self.paired_device_name)
+
+        # Update saved session with latest info
+        await self._save_pairing_session()
+
+        if self.on_pairing_connected:
+            await self.on_pairing_connected(params)
+
+    async def _save_pairing_session(self):
+        """Save pairing session to database for auto-reconnect."""
+        try:
+            from core.container import container
+            database = container.database()
+
+            await database.save_android_relay_session(
+                relay_url=self.base_url,
+                api_key=self.api_key,
+                device_id=self.paired_device_id,
+                device_name=self.paired_device_name,
+                session_token=self.session_token
+            )
+            logger.info("[Relay] Pairing session saved for auto-reconnect")
+        except Exception as e:
+            logger.warning("[Relay] Failed to save pairing session", error=str(e))
+
+    async def _handle_pairing_disconnected(self, params: dict):
+        """Handle pairing.disconnected event.
+
+        The Android device has disconnected, but the relay connection may still be active.
+        This allows the user to re-scan the QR code without reconnecting to the relay.
+        """
+        reason = params.get("reason", "unknown")
+        logger.info("[Relay] Android device disconnected", reason=reason)
+
+        self.paired = False
+        self.paired_device_id = None
+        self.paired_device_name = None
+
+        # Broadcast device disconnection - relay is still connected, pass QR data for re-pairing
+        await broadcast_device_disconnected(
+            relay_connected=self.is_connected(),
+            qr_data=self.qr_data,
+            session_token=self.session_token
+        )
+
+        if self.on_pairing_disconnected:
+            await self.on_pairing_disconnected(params)
+
+    async def _handle_relay_message(self, params: dict):
+        """Handle relay.message event from Android.
+
+        Schema: relay.message params = {"data": {...}}
+        The data contains the actual message from Android.
+        """
+        # Schema: params = {"data": {...}}
+        data = params.get("data", {})
+
+        logger.info("[Relay] relay.message received",
+                   data_keys=list(data.keys()) if isinstance(data, dict) else "not_dict",
+                   data=data)
+
+        # Route to service response queue if matching request_id
+        # Android app uses "request_id" (underscore), not "requestId" (camelCase)
+        request_id = data.get("request_id")
+        logger.info("[Relay] Checking request_id", request_id=request_id, waiting_for=list(self._service_queues.keys()))
+
+        if request_id and request_id in self._service_queues:
+            logger.info("[Relay] Routing to service queue", request_id=request_id)
+            await self._service_queues[request_id].put(data)
+        elif self.on_relay_message:
+            logger.info("[Relay] Passing to on_relay_message callback")
+            await self.on_relay_message(data)
+        else:
+            logger.warning("[Relay] Unhandled relay message", request_id=request_id, data=data)
+
+    # =========================================================================
+    # RPC Methods
+    # =========================================================================
+
+    async def call(self, method: str, params: Dict[str, Any] = None, timeout: float = 30) -> Any:
+        """
+        Make JSON-RPC 2.0 call and wait for response.
+
+        Args:
+            method: RPC method name
+            params: Method parameters
+            timeout: Response timeout in seconds
+
+        Returns:
+            Result from the RPC call
+        """
+        if not self.is_connected():
+            raise Exception("Not connected to relay server")
+
+        request, future = self._rpc_tracker.create_request(method, params)
+
+        try:
+            req_dict = request.to_dict()
+            logger.debug("[Relay] Sending RPC request", method=method, id=request.id)
+            await self.ws.send_json(req_dict)
+            result = await asyncio.wait_for(future, timeout)
+            logger.debug("[Relay] RPC response received", method=method, id=request.id)
+            return result
+        except asyncio.TimeoutError:
+            self._rpc_tracker.cancel(request.id)
+            raise Exception(f"RPC call '{method}' timed out after {timeout}s")
+
+    async def get_pairing_status(self) -> Dict[str, Any]:
+        """Get current pairing status."""
+        return await self.call("pairing.status")
+
+    async def disconnect_pairing(self) -> Dict[str, Any]:
+        """End pairing session."""
+        result = await self.call("pairing.disconnect")
+        self.paired = False
+        self.paired_device_id = None
+        self.paired_device_name = None
+        return result
+
+    async def relay_send(self, data: Dict[str, Any], timeout: float = 30) -> Dict[str, Any]:
+        """
+        Send message to paired Android device via relay.
+
+        Schema: relay.send params = {"data": {...}}
+
+        Args:
+            data: Message data to send to Android device
+            timeout: Response timeout
+        """
+        if not self.paired:
+            raise Exception("Not paired with Android device")
+
+        logger.info("[Relay] Sending relay.send RPC", data=data)
+
+        # Schema: {"jsonrpc": "2.0", "method": "relay.send", "params": {"data": {...}}, "id": 1}
+        result = await self.call("relay.send", {"data": data}, timeout=timeout)
+        logger.info("[Relay] relay.send RPC response", result=result)
+        return result
+
+    # =========================================================================
+    # Service Requests
+    # =========================================================================
+
+    async def send_service_request(
+        self,
+        service_id: str,
+        action: str,
+        parameters: Dict[str, Any] = None,
+        target_id: Optional[str] = None,  # Ignored, kept for compatibility
+        timeout: float = 30.0
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Send service request to paired Android device.
+
+        Args:
+            service_id: Android service ID (e.g., 'battery', 'wifi_automation')
+            action: Service action (e.g., 'status', 'enable')
+            parameters: Action parameters
+            target_id: Ignored (kept for API compatibility)
+            timeout: Response timeout in seconds
+
+        Returns:
+            Response data or None if timeout/error
+        """
+        if not self.paired:
+            logger.error("[Relay] Cannot send - not paired")
+            return None
+
+        request_id = str(uuid.uuid4())
+        response_queue: asyncio.Queue = asyncio.Queue()
+        self._service_queues[request_id] = response_queue
+
+        try:
+            # Send via relay - schema: relay.send params = {"data": {...}}
+            # Field names must match Android app expectations:
+            # - service (not serviceId)
+            # - action
+            # - request_id (not requestId)
+            # - params (not parameters)
+            await self.relay_send({
+                "service": service_id,
+                "action": action,
+                "request_id": request_id,
+                "params": parameters or {}
+            }, timeout=5.0)
+
+            logger.info("[Relay] Sent service request",
+                       request_id=request_id,
+                       service_id=service_id,
+                       action=action)
+
+            # Wait for response
+            logger.info("[Relay] Waiting for response", request_id=request_id, timeout=timeout)
+            response = await asyncio.wait_for(response_queue.get(), timeout=timeout)
+            logger.info("[Relay] Service response received", request_id=request_id, response_keys=list(response.keys()) if isinstance(response, dict) else "not_dict")
+            return response
+
+        except asyncio.TimeoutError:
+            logger.warning("[Relay] Service response timeout", request_id=request_id, timeout=timeout, pending_queues=list(self._service_queues.keys()))
+            return None
+        except Exception as e:
+            logger.error("[Relay] Service request error", error=str(e))
+            return None
+        finally:
+            self._service_queues.pop(request_id, None)
+
+    async def wait_for_pairing(self, timeout: float = 60.0) -> bool:
+        """
+        Wait for Android device to pair.
+
+        Args:
+            timeout: Maximum time to wait in seconds
+
+        Returns:
+            True if paired successfully, False if timeout
+        """
+        if self.paired:
+            return True
+
+        logger.info("[Relay] Waiting for pairing...", timeout=timeout)
+
+        start = asyncio.get_event_loop().time()
+        while asyncio.get_event_loop().time() - start < timeout:
+            if self.paired:
+                return True
+            await asyncio.sleep(0.5)
+
+        logger.warning("[Relay] Pairing timeout")
+        return False
+
+    # =========================================================================
+    # Legacy Compatibility
+    # =========================================================================
+
+    def get_android_device_id(self) -> Optional[str]:
+        """Get paired Android device ID."""
+        return self.paired_device_id
+
+    def has_real_android_devices(self) -> bool:
+        """Check if paired with Android device."""
+        return self.paired
+
+    def get_connected_devices(self) -> Set[str]:
+        """Get set of connected Android device IDs."""
+        if self.paired_device_id:
+            return {self.paired_device_id}
+        return set()

package/server/services/android/manager.py

@@ -0,0 +1,78 @@
+"""
+Android Relay Client Manager
+
+Global instance management for persistent WebSocket connection.
+Provides singleton pattern for reusing connection across API requests.
+"""
+from typing import Optional
+import structlog
+
+from .client import RelayWebSocketClient
+
+logger = structlog.get_logger()
+
+# Global client instance
+_relay_client: Optional[RelayWebSocketClient] = None
+
+
+async def get_relay_client(base_url: str, api_key: str) -> tuple[Optional[RelayWebSocketClient], str]:
+    """
+    Get or create persistent relay client instance.
+
+    Args:
+        base_url: WebSocket URL (e.g., 'wss://your-relay-server.com/ws')
+        api_key: API key for authentication
+
+    Returns:
+        Tuple of (client or None, error_message)
+    """
+    global _relay_client
+
+    # Reuse existing connection if valid
+    if _relay_client and _relay_client.is_connected():
+        logger.info("[Manager] Reusing existing connection")
+        return _relay_client, ""
+
+    # Close stale connection
+    if _relay_client:
+        await _relay_client.disconnect()
+
+    # Create new connection
+    logger.info("[Manager] Creating new connection", url=base_url)
+    _relay_client = RelayWebSocketClient(base_url, api_key)
+    connected, error = await _relay_client.connect()
+
+    if connected:
+        logger.info("[Manager] Connection established")
+        return _relay_client, ""
+    else:
+        _relay_client = None
+        logger.error("[Manager] Failed to connect", error=error)
+        return None, error
+
+
+async def close_relay_client(clear_stored_session: bool = True):
+    """Close global relay client.
+
+    Args:
+        clear_stored_session: If True, clear stored pairing session from database.
+                              This prevents auto-reconnect on next client connect.
+    """
+    global _relay_client
+    if _relay_client:
+        logger.info("[Manager] Closing connection", clear_stored_session=clear_stored_session)
+        await _relay_client.disconnect(clear_stored_session=clear_stored_session)
+        _relay_client = None
+
+
+def get_current_relay_client() -> Optional[RelayWebSocketClient]:
+    """
+    Get current relay client if connected.
+
+    Returns:
+        Connected client or None
+    """
+    global _relay_client
+    if _relay_client and _relay_client.is_connected():
+        return _relay_client
+    return None