androidctl 0.1.0__py3-none-any.whl

androidctld/device/adapters.py

@@ -0,0 +1,220 @@
+"""Adapters from device boundary DTOs into runtime types."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from androidctld.device.errors import (
+    DeviceBootstrapError,
+    device_agent_unauthorized,
+    device_rpc_failed,
+)
+from androidctld.device.schema import (
+    ActionPerformResultPayload,
+    ActionResolvedTargetPayload,
+    DeviceCapabilitiesPayload,
+    DeviceEventPayload,
+    EventsPollResultPayload,
+    MetaPayload,
+    NodeHandlePayload,
+    ObservedAppPayload,
+    ResolvedCoordinatesTargetPayload,
+    ResolvedHandleTargetPayload,
+    ResolvedNoneTargetPayload,
+    RpcErrorPayload,
+    ScreenshotCaptureResultPayload,
+)
+from androidctld.device.types import (
+    ActionPerformResult,
+    ActionStatus,
+    DeviceCapabilities,
+    DeviceEvent,
+    EventsPollResult,
+    MetaInfo,
+    ObservedApp,
+    ResolvedCoordinatesTarget,
+    ResolvedHandleTarget,
+    ResolvedNoneTarget,
+    ResolvedTarget,
+    ScreenshotCaptureResult,
+)
+from androidctld.refs.models import NodeHandle
+from androidctld.schema.base import dump_api_model
+from androidctld.schema.core import SchemaDecodeError
+
+
+def adapt_meta_payload(
+    payload: MetaPayload,
+    *,
+    field_name: str = "result",
+) -> MetaInfo:
+    return MetaInfo(
+        service=payload.service,
+        version=payload.version,
+        capabilities=adapt_capabilities(
+            payload.capabilities,
+            field_name=f"{field_name}.capabilities",
+        ),
+    )
+
+
+def adapt_capabilities(
+    payload: DeviceCapabilitiesPayload,
+    *,
+    field_name: str = "result.capabilities",
+) -> DeviceCapabilities:
+    del field_name
+    return DeviceCapabilities(
+        supports_events_poll=payload.supports_events_poll,
+        supports_screenshot=payload.supports_screenshot,
+        action_kinds=list(payload.action_kinds),
+    )
+
+
+def adapt_rpc_error_payload(payload: RpcErrorPayload) -> DeviceBootstrapError:
+    details = {
+        "deviceCode": payload.code,
+        "retryable": payload.retryable,
+        "details": dict(payload.details),
+    }
+    if payload.code == "UNAUTHORIZED":
+        return device_agent_unauthorized(payload.message, details)
+    return device_rpc_failed(
+        payload.message,
+        details,
+        retryable=payload.retryable,
+    )
+
+
+def adapt_action_perform_result(
+    payload: ActionPerformResultPayload,
+    *,
+    field_name: str = "result",
+) -> ActionPerformResult:
+    resolved_target = None
+    if payload.resolved_target is not None:
+        resolved_target = adapt_resolved_target(
+            payload.resolved_target,
+            field_name=f"{field_name}.resolvedTarget",
+        )
+    observed = None
+    if payload.observed is not None:
+        observed = adapt_observed_app(
+            payload.observed,
+            field_name=f"{field_name}.observed",
+        )
+    return ActionPerformResult(
+        action_id=payload.action_id,
+        status=adapt_action_status(payload.status, field_name=f"{field_name}.status"),
+        duration_ms=payload.duration_ms,
+        resolved_target=resolved_target,
+        observed=observed,
+    )
+
+
+def build_node_handle_payload(handle: NodeHandle) -> NodeHandlePayload:
+    return NodeHandlePayload(snapshot_id=handle.snapshot_id, rid=handle.rid)
+
+
+def dump_node_handle(handle: NodeHandle) -> dict[str, Any]:
+    return dump_api_model(build_node_handle_payload(handle))
+
+
+def adapt_action_status(
+    status: str,
+    *,
+    field_name: str,
+) -> ActionStatus:
+    try:
+        return ActionStatus(status)
+    except ValueError as error:
+        raise SchemaDecodeError(
+            field_name,
+            "must be one of done|partial|timeout",
+        ) from error
+
+
+def adapt_observed_app(
+    payload: ObservedAppPayload,
+    *,
+    field_name: str = "result.observed",
+) -> ObservedApp:
+    del field_name
+    return ObservedApp(
+        package_name=payload.package_name,
+        activity_name=payload.activity_name,
+    )
+
+
+def adapt_resolved_target(
+    payload: ActionResolvedTargetPayload,
+    *,
+    field_name: str = "resolvedTarget",
+) -> ResolvedTarget:
+    if isinstance(payload, ResolvedHandleTargetPayload):
+        return ResolvedHandleTarget(
+            handle=adapt_node_handle(payload.handle, field_name=f"{field_name}.handle"),
+        )
+    if isinstance(payload, ResolvedCoordinatesTargetPayload):
+        return ResolvedCoordinatesTarget(x=payload.x, y=payload.y)
+    if isinstance(payload, ResolvedNoneTargetPayload):
+        return ResolvedNoneTarget()
+    raise SchemaDecodeError(
+        f"{field_name}.kind", "must be one of handle|coordinates|none"
+    )
+
+
+def adapt_node_handle(
+    payload: NodeHandlePayload,
+    *,
+    field_name: str = "handle",
+) -> NodeHandle:
+    del field_name
+    return NodeHandle(
+        snapshot_id=payload.snapshot_id,
+        rid=payload.rid,
+    )
+
+
+def adapt_events_poll_result(
+    payload: EventsPollResultPayload,
+    *,
+    field_name: str = "result",
+) -> EventsPollResult:
+    return EventsPollResult(
+        events=tuple(
+            adapt_device_event(event, field_name=f"{field_name}.events[{index}]")
+            for index, event in enumerate(payload.events)
+        ),
+        latest_seq=payload.latest_seq,
+        need_resync=payload.need_resync,
+        timed_out=payload.timed_out,
+    )
+
+
+def adapt_device_event(
+    payload: DeviceEventPayload,
+    *,
+    field_name: str = "result.events[0]",
+) -> DeviceEvent:
+    del field_name
+    return DeviceEvent(
+        seq=payload.seq,
+        type=payload.type,
+        timestamp=payload.timestamp,
+        data=dict(payload.data),
+    )
+
+
+def adapt_screenshot_capture_result(
+    payload: ScreenshotCaptureResultPayload,
+    *,
+    field_name: str = "result",
+) -> ScreenshotCaptureResult:
+    del field_name
+    return ScreenshotCaptureResult(
+        content_type=payload.content_type,
+        width_px=payload.width_px,
+        height_px=payload.height_px,
+        body_base64=payload.body_base64,
+    )

androidctld/device/bootstrap.py

@@ -0,0 +1,153 @@
+"""Bootstrap and readiness probing for the Android device agent."""
+
+from __future__ import annotations
+
+from androidctld import __version__ as ANDROIDCTLD_VERSION
+from androidctld.device.connectors import ConnectorHandle, DeviceConnectorFactory
+from androidctld.device.errors import (
+    DeviceBootstrapError,
+    accessibility_not_ready,
+    capability_mismatch,
+    version_mismatch,
+)
+from androidctld.device.rpc import DeviceRpcClient
+from androidctld.device.types import (
+    BootstrapResult,
+    ConnectionConfig,
+    MetaInfo,
+    RuntimeTransport,
+)
+from androidctld.errors import DaemonError
+from androidctld.protocol import DeviceRpcErrorCode
+
+MINIMUM_CONNECT_ACTION_KINDS = frozenset(
+    {
+        "tap",
+        "type",
+        "global",
+        "launchApp",
+    }
+)
+
+
+class DeviceBootstrapper:
+    def __init__(self, connector_factory: DeviceConnectorFactory | None = None) -> None:
+        self._connector_factory = connector_factory or DeviceConnectorFactory()
+
+    def bootstrap(self, config: ConnectionConfig) -> BootstrapResult:
+        handle = self.establish_transport(config)
+        try:
+            return self.bootstrap_runtime(handle, config)
+        except Exception:
+            handle.close()
+            raise
+
+    def bootstrap_rpc_only(self, config: ConnectionConfig) -> BootstrapResult:
+        handle = self.establish_transport(config)
+        try:
+            return self.bootstrap_runtime_rpc_only(handle, config)
+        except Exception:
+            handle.close()
+            raise
+
+    def establish_transport(self, config: ConnectionConfig) -> ConnectorHandle:
+        return self._connector_factory.connect(config)
+
+    def bootstrap_runtime(
+        self,
+        handle: ConnectorHandle,
+        config: ConnectionConfig,
+    ) -> BootstrapResult:
+        client = DeviceRpcClient(endpoint=handle.endpoint, token=config.token)
+        meta = self._fetch_release_compatible_meta(client)
+        self._validate_capabilities(meta)
+        self._probe_readiness(client)
+        return BootstrapResult(
+            connection=handle.connection,
+            transport=RuntimeTransport(
+                endpoint=handle.endpoint,
+                close=handle.close,
+            ),
+            meta=meta,
+        )
+
+    def bootstrap_runtime_rpc_only(
+        self,
+        handle: ConnectorHandle,
+        config: ConnectionConfig,
+    ) -> BootstrapResult:
+        client = DeviceRpcClient(endpoint=handle.endpoint, token=config.token)
+        meta = self._fetch_release_compatible_meta(client)
+        return BootstrapResult(
+            connection=handle.connection,
+            transport=RuntimeTransport(
+                endpoint=handle.endpoint,
+                close=handle.close,
+            ),
+            meta=meta,
+        )
+
+    def _fetch_release_compatible_meta(self, client: DeviceRpcClient) -> MetaInfo:
+        try:
+            meta = client.meta_get()
+        except DeviceBootstrapError as error:
+            if _is_legacy_rpc_version_schema_failure(error):
+                raise version_mismatch(
+                    "device agent meta.get payload is incompatible with this "
+                    "androidctld release; install matching androidctld and Android "
+                    "agent/APK versions",
+                    {"reason": "legacy_rpc_version_field"},
+                ) from error
+            raise
+        if meta.version != ANDROIDCTLD_VERSION:
+            raise version_mismatch(
+                "device agent release version mismatch: "
+                f"daemon={ANDROIDCTLD_VERSION} agent={meta.version}; "
+                "install matching androidctld and Android agent/APK versions",
+                {
+                    "expectedReleaseVersion": ANDROIDCTLD_VERSION,
+                    "actualReleaseVersion": meta.version,
+                },
+            )
+        return meta
+
+    def _validate_capabilities(self, meta: MetaInfo) -> None:
+        missing_capabilities: list[str] = []
+        if not meta.capabilities.supports_events_poll:
+            missing_capabilities.append("supportsEventsPoll")
+        missing_action_kinds = sorted(
+            MINIMUM_CONNECT_ACTION_KINDS.difference(meta.capabilities.action_kinds)
+        )
+        if not missing_capabilities and not missing_action_kinds:
+            return
+        raise capability_mismatch(
+            "device agent capability handshake failed",
+            {
+                "missingCapabilities": missing_capabilities,
+                "missingActionKinds": missing_action_kinds,
+            },
+        )
+
+    def _probe_readiness(self, client: DeviceRpcClient) -> None:
+        try:
+            client.snapshot_get()
+        except DaemonError as error:
+            device_code = error.details.get("deviceCode")
+            if device_code in (
+                DeviceRpcErrorCode.RUNTIME_NOT_READY.value,
+                DeviceRpcErrorCode.ACCESSIBILITY_DISABLED.value,
+            ):
+                raise accessibility_not_ready(
+                    "accessibility runtime is not ready",
+                    {"deviceCode": device_code},
+                ) from error
+            raise
+
+
+def _is_legacy_rpc_version_schema_failure(error: DeviceBootstrapError) -> bool:
+    return (
+        error.code == "DEVICE_RPC_FAILED"
+        and error.details.get("field") == "result"
+        and error.details.get("reason") == "invalid_payload"
+        and error.details.get("unknownFields") == ["rpcVersion"]
+    )

androidctld/device/connectors.py

@@ -0,0 +1,231 @@
+"""Transport connectors for reaching the Android device agent."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from androidctld.config import DEFAULT_HOST
+from androidctld.device.errors import device_agent_unavailable
+from androidctld.device.types import ConnectionConfig, ConnectionSpec, DeviceEndpoint
+from androidctld.protocol import ConnectionMode
+from androidctld.runtime_policy import ADB_COMMAND_TIMEOUT_SECONDS
+
+
+@dataclass
+class ConnectorHandle:
+    endpoint: DeviceEndpoint
+    close: Callable[[], None]
+    connection: ConnectionSpec
+
+
+class LanConnector:
+    def connect(self, config: ConnectionConfig) -> ConnectorHandle:
+        if not config.host:
+            raise device_agent_unavailable(
+                "LAN connection requires host", {"mode": config.mode.value}
+            )
+        return ConnectorHandle(
+            endpoint=DeviceEndpoint(host=config.host, port=config.port),
+            close=lambda: None,
+            connection=ConnectionSpec.from_config(config),
+        )
+
+
+class AdbConnector:
+    def __init__(
+        self,
+        runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+    ) -> None:
+        self._runner = runner
+
+    def connect(self, config: ConnectionConfig) -> ConnectorHandle:
+        serial = config.serial or self._select_serial()
+        local_port = self._forward(serial, config.port)
+        endpoint = DeviceEndpoint(host=DEFAULT_HOST, port=local_port)
+
+        def close() -> None:
+            self._remove_forward(serial, local_port)
+
+        return ConnectorHandle(
+            endpoint=endpoint,
+            close=close,
+            connection=ConnectionSpec(
+                mode=ConnectionMode.ADB,
+                serial=serial,
+                port=config.port,
+                host=None,
+            ),
+        )
+
+    def _select_serial(self) -> str:
+        completed = self._run_adb(
+            ["adb", "devices"],
+            operation="devices",
+        )
+        if completed.returncode != 0:
+            raise device_agent_unavailable(
+                "adb devices failed",
+                {
+                    "reason": "adb_devices_failed",
+                    "stderr": completed.stderr.strip(),
+                },
+            )
+        rows = _parse_adb_devices(completed.stdout)
+        eligible_serials = [row.serial for row in rows if row.state == "device"]
+        if len(eligible_serials) == 1:
+            return eligible_serials[0]
+        if not eligible_serials:
+            raise device_agent_unavailable(
+                "no eligible ADB devices found",
+                {
+                    "reason": "no_eligible_adb_device",
+                    "deviceStates": _state_counts(rows),
+                },
+            )
+        raise device_agent_unavailable(
+            "multiple eligible ADB devices found; pass explicit --serial",
+            {
+                "reason": "multiple_eligible_adb_devices",
+                "eligibleSerials": eligible_serials,
+                "hint": "pass explicit --serial",
+            },
+        )
+
+    def _forward(self, serial: str, remote_port: int) -> int:
+        command = [
+            "adb",
+            "-s",
+            serial,
+            "forward",
+            "tcp:0",
+            f"tcp:{remote_port}",
+        ]
+        completed = self._run_adb(
+            command,
+            operation="forward",
+            serial=serial,
+        )
+        if completed.returncode != 0:
+            raise device_agent_unavailable(
+                "adb forward failed",
+                {
+                    "serial": serial,
+                    "stderr": completed.stderr.strip(),
+                },
+            )
+        output = completed.stdout.strip()
+        if not re.match(r"^\d+$", output):
+            raise device_agent_unavailable(
+                "adb forward did not return a local port",
+                {
+                    "serial": serial,
+                    "stdout": output,
+                },
+            )
+        return int(output)
+
+    def _remove_forward(self, serial: str, local_port: int) -> None:
+        command = [
+            "adb",
+            "-s",
+            serial,
+            "forward",
+            "--remove",
+            f"tcp:{local_port}",
+        ]
+        self._run_adb(
+            command,
+            operation="forward_remove",
+            serial=serial,
+            suppress_timeout=True,
+        )
+
+    def _run_adb(
+        self,
+        command: list[str],
+        *,
+        operation: str,
+        serial: str | None = None,
+        suppress_timeout: bool = False,
+    ) -> subprocess.CompletedProcess[str]:
+        try:
+            return self._runner(
+                command,
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=ADB_COMMAND_TIMEOUT_SECONDS,
+            )
+        except subprocess.TimeoutExpired as exc:
+            if suppress_timeout:
+                stdout = exc.stdout if isinstance(exc.stdout, str) else ""
+                stderr = exc.stderr if isinstance(exc.stderr, str) else ""
+                return subprocess.CompletedProcess(
+                    exc.cmd,
+                    124,
+                    stdout=stdout,
+                    stderr=stderr,
+                )
+            details: dict[str, object] = {
+                "reason": "adb_command_timeout",
+                "operation": operation,
+                "timeoutSeconds": ADB_COMMAND_TIMEOUT_SECONDS,
+            }
+            if serial is not None:
+                details["serial"] = serial
+            raise device_agent_unavailable("ADB command timed out", details) from exc
+
+
+@dataclass(frozen=True)
+class _AdbDeviceRow:
+    serial: str
+    state: str
+
+
+def _parse_adb_devices(output: str) -> list[_AdbDeviceRow]:
+    rows: list[_AdbDeviceRow] = []
+    saw_header = False
+    for raw_line in output.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line == "List of devices attached":
+            saw_header = True
+            continue
+        if not saw_header:
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        serial, state = parts[0], parts[1]
+        rows.append(_AdbDeviceRow(serial=serial, state=state))
+    return rows
+
+
+def _state_counts(rows: list[_AdbDeviceRow]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for row in rows:
+        counts[row.state] = counts.get(row.state, 0) + 1
+    return counts
+
+
+class DeviceConnectorFactory:
+    def __init__(
+        self,
+        adb_connector: AdbConnector | None = None,
+        lan_connector: LanConnector | None = None,
+    ) -> None:
+        self._adb_connector = adb_connector or AdbConnector()
+        self._lan_connector = lan_connector or LanConnector()
+
+    def connect(self, config: ConnectionConfig) -> ConnectorHandle:
+        if config.mode is ConnectionMode.ADB:
+            return self._adb_connector.connect(config)
+        if config.mode is ConnectionMode.LAN:
+            return self._lan_connector.connect(config)
+        raise device_agent_unavailable(
+            "unsupported connection mode", {"mode": config.mode.value}
+        )

androidctld/device/errors.py

@@ -0,0 +1,100 @@
+"""Device bootstrap and RPC errors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from androidctld.errors import DaemonError, DaemonErrorCode
+
+
+class DeviceBootstrapError(DaemonError):
+    pass
+
+
+def device_agent_unavailable(
+    message: str, details: dict[str, Any] | None = None
+) -> DeviceBootstrapError:
+    return DeviceBootstrapError(
+        code=DaemonErrorCode.DEVICE_AGENT_UNAVAILABLE,
+        message=message,
+        retryable=True,
+        details=details or {},
+        http_status=200,
+    )
+
+
+def device_agent_unauthorized(
+    message: str,
+    details: dict[str, Any] | None = None,
+    *,
+    retryable: bool = False,
+) -> DeviceBootstrapError:
+    return DeviceBootstrapError(
+        code=DaemonErrorCode.DEVICE_AGENT_UNAUTHORIZED,
+        message=message,
+        retryable=retryable,
+        details=details or {},
+        http_status=200,
+    )
+
+
+def version_mismatch(
+    message: str, details: dict[str, Any] | None = None
+) -> DeviceBootstrapError:
+    return DeviceBootstrapError(
+        code=DaemonErrorCode.DEVICE_AGENT_VERSION_MISMATCH,
+        message=message,
+        retryable=False,
+        details=details or {},
+        http_status=200,
+    )
+
+
+def capability_mismatch(
+    message: str, details: dict[str, Any] | None = None
+) -> DeviceBootstrapError:
+    return DeviceBootstrapError(
+        code=DaemonErrorCode.DEVICE_AGENT_CAPABILITY_MISMATCH,
+        message=message,
+        retryable=False,
+        details=details or {},
+        http_status=200,
+    )
+
+
+def accessibility_not_ready(
+    message: str, details: dict[str, Any] | None = None
+) -> DeviceBootstrapError:
+    return DeviceBootstrapError(
+        code=DaemonErrorCode.ACCESSIBILITY_NOT_READY,
+        message=message,
+        retryable=True,
+        details=details or {},
+        http_status=200,
+    )
+
+
+def device_rpc_failed(
+    message: str,
+    details: dict[str, Any] | None = None,
+    retryable: bool = True,
+) -> DeviceBootstrapError:
+    return DeviceBootstrapError(
+        code=DaemonErrorCode.DEVICE_RPC_FAILED,
+        message=message,
+        retryable=retryable,
+        details=details or {},
+        http_status=200,
+    )
+
+
+def device_rpc_transport_reset(
+    message: str, details: dict[str, Any] | None = None
+) -> DeviceBootstrapError:
+    return DeviceBootstrapError(
+        code=DaemonErrorCode.DEVICE_RPC_TRANSPORT_RESET,
+        message=message,
+        retryable=True,
+        details=details or {},
+        http_status=200,
+    )