androidctl 0.1.0__py3-none-any.whl

androidctld/daemon/server.py

@@ -0,0 +1,286 @@
+"""HTTP server for androidctld."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from collections.abc import Callable
+from http.server import BaseHTTPRequestHandler
+from typing import Any
+
+from androidctld import SERVICE_NAME, __version__
+from androidctld.auth.active_registry import ActiveDaemonRecord, ActiveDaemonRegistry
+from androidctld.auth.token_store import DaemonTokenStore
+from androidctld.commands.service import CommandService
+from androidctld.config import DaemonConfig
+from androidctld.daemon.active_slot import ActiveSlotCoordinator
+from androidctld.daemon.envelope import error_envelope, success_envelope
+from androidctld.daemon.http_host import DaemonHttpHost
+from androidctld.daemon.ingress import DaemonIngress
+from androidctld.daemon.service import DaemonService
+from androidctld.errors import DaemonError, DaemonErrorCode, bad_request
+from androidctld.logging import configure_logging
+from androidctld.runtime.store import RuntimeStore
+from androidctld.runtime_policy import (
+    DAEMON_HTTP_MAX_REQUEST_BODY_BYTES,
+    DAEMON_HTTP_SOCKET_TIMEOUT_SECONDS,
+)
+
+
+class AndroidctldHttpServer:
+    def __init__(
+        self,
+        config: DaemonConfig,
+        token_store: DaemonTokenStore | None = None,
+        active_registry: ActiveDaemonRegistry | None = None,
+        runtime_store: RuntimeStore | None = None,
+        command_service: CommandService | None = None,
+        logger: logging.Logger | None = None,
+        shutdown_callback: Callable[[], None] | None = None,
+    ) -> None:
+        self._config = config
+        self._token_store = token_store or DaemonTokenStore(self._config)
+        self._active_registry = active_registry or ActiveDaemonRegistry(self._config)
+        self._logger = logger or configure_logging()
+        self._runtime_store = runtime_store or RuntimeStore(self._config)
+        self._shutdown_callback = shutdown_callback or (lambda: None)
+        self._closing = False
+        self._shutdown_after_close_requested = False
+        self._stop_lock = threading.Lock()
+        self._stop_completed = False
+        self._service = DaemonService(
+            runtime_store=self._runtime_store,
+            command_service=command_service or CommandService(self._runtime_store),
+            bound_owner_id=self._config.owner_id,
+        )
+        self._ingress = DaemonIngress(
+            token_provider=self._token_store.current_token,
+            owner_id_provider=lambda: self._config.owner_id,
+            dispatcher=self,
+        )
+        self._active_slot = ActiveSlotCoordinator(
+            config=self._config,
+            active_registry=self._active_registry,
+            existing_token_reader=lambda: DaemonTokenStore.load_existing_token(
+                self._config.token_file_path
+            ),
+        )
+        self._http_host = DaemonHttpHost(config=self._config, logger=self._logger)
+
+    @property
+    def active_record(self) -> ActiveDaemonRecord | None:
+        return self._active_slot.active_record
+
+    def handle(
+        self,
+        method: str,
+        path: str,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> tuple[int, dict[str, Any]]:
+        if (
+            self._closing
+            and method == "POST"
+            and path
+            in {
+                "/runtime/get",
+                "/runtime/close",
+                "/commands/run",
+            }
+        ):
+            raise DaemonError(
+                code=DaemonErrorCode.RUNTIME_BUSY,
+                message="daemon is shutting down",
+                retryable=True,
+                details={"reason": "daemon_shutting_down"},
+                http_status=200,
+            )
+        return self._service.handle(
+            method=method,
+            path=path,
+            headers=headers,
+            body=body,
+        )
+
+    def start(self) -> ActiveDaemonRecord:
+        with self._stop_lock:
+            if self._http_host.is_running:
+                raise RuntimeError("androidctld server is already running")
+
+            self._closing = False
+            self._shutdown_after_close_requested = False
+            self._stop_completed = False
+            self._active_slot.acquire()
+            try:
+                host, port = self._http_host.start(self._build_handler())
+                active_record = self._active_slot.prepare(
+                    host=host,
+                    port=port,
+                    token=self._token_store.current_token(),
+                )
+                self._http_host.wait_until_ready(record=active_record)
+                self._active_slot.publish(active_record)
+                self._logger.info("androidctld listening on %s:%s", host, port)
+                return active_record
+            except Exception:
+                self._active_slot.clear_record()
+                self._http_host.stop()
+                self._active_slot.release_owner()
+                self._stop_completed = True
+                raise
+
+    def stop(self) -> None:
+        with self._stop_lock:
+            if self._stop_completed:
+                return
+            try:
+                if self._http_host.is_running:
+                    self._http_host.stop()
+            finally:
+                self._active_slot.clear_record()
+                self._active_slot.release_owner()
+                self._stop_completed = True
+                self._logger.info("androidctld stopped")
+
+    def _build_handler(self) -> type[BaseHTTPRequestHandler]:
+        outer = self
+
+        class RequestHandler(BaseHTTPRequestHandler):
+            server_version = f"{SERVICE_NAME}/{__version__}"
+            protocol_version = "HTTP/1.1"
+
+            def setup(self) -> None:
+                super().setup()
+                self.connection.settimeout(DAEMON_HTTP_SOCKET_TIMEOUT_SECONDS)
+
+            def do_POST(self) -> None:
+                outer._handle(self)
+
+            def do_GET(self) -> None:
+                outer._handle(self)
+
+            def log_message(self, fmt: str, *args: Any) -> None:
+                outer._logger.info("http %s", fmt % args)
+
+        return RequestHandler
+
+    def _handle(self, handler: BaseHTTPRequestHandler) -> None:
+        try:
+            body = self._read_body(handler)
+            result = self._ingress.handle(
+                method=handler.command,
+                path=handler.path,
+                headers=self._normalize_headers(handler),
+                body=body,
+            )
+            if result.shutdown_after_write:
+                self._enter_closing_gate()
+                try:
+                    self._write_json(
+                        handler,
+                        result.status_code,
+                        success_envelope(result.payload),
+                    )
+                except OSError:
+                    self._logger.info("close response write failed", exc_info=True)
+                finally:
+                    self._request_shutdown_after_close()
+                return
+            self._write_json(
+                handler,
+                result.status_code,
+                success_envelope(result.payload),
+            )
+        except DaemonError as error:
+            self._write_json(handler, error.http_status, error_envelope(error))
+        except Exception:  # pragma: no cover - defensive fallback
+            self._logger.exception("unexpected daemon failure")
+            daemon_error = DaemonError(
+                code=DaemonErrorCode.INTERNAL_COMMAND_FAILURE,
+                message="unexpected daemon failure",
+                retryable=False,
+                details={},
+                http_status=500,
+            )
+            self._write_json(
+                handler, daemon_error.http_status, error_envelope(daemon_error)
+            )
+
+    def _enter_closing_gate(self) -> None:
+        if self._closing:
+            return
+        self._closing = True
+
+    def _request_shutdown_after_close(self) -> None:
+        if self._shutdown_after_close_requested:
+            return
+        self._shutdown_after_close_requested = True
+        self._shutdown_callback()
+
+    def _read_body(self, handler: BaseHTTPRequestHandler) -> bytes:
+        content_length_header = handler.headers.get("Content-Length")
+        if content_length_header is None:
+            return b""
+        content_length_raw = content_length_header.strip()
+        if not content_length_raw:
+            raise bad_request("invalid Content-Length header")
+        try:
+            content_length = int(content_length_raw)
+        except ValueError as error:
+            raise bad_request("invalid Content-Length header") from error
+        if content_length < 0:
+            raise bad_request("invalid Content-Length header")
+        if content_length > DAEMON_HTTP_MAX_REQUEST_BODY_BYTES:
+            handler.close_connection = True
+            raise DaemonError(
+                code=DaemonErrorCode.DAEMON_BAD_REQUEST,
+                message="request body too large",
+                retryable=False,
+                details={
+                    "reason": "request_body_too_large",
+                    "max": DAEMON_HTTP_MAX_REQUEST_BODY_BYTES,
+                    "contentLength": content_length,
+                },
+                http_status=413,
+            )
+        try:
+            body = handler.rfile.read(content_length)
+        except TimeoutError as error:
+            handler.close_connection = True
+            raise DaemonError(
+                code=DaemonErrorCode.DAEMON_BAD_REQUEST,
+                message="request body read timed out",
+                retryable=False,
+                details={"reason": "request_body_timeout"},
+                http_status=408,
+            ) from error
+        if len(body) != content_length:
+            handler.close_connection = True
+            raise bad_request(
+                "incomplete request body",
+                {
+                    "reason": "incomplete_body",
+                    "contentLength": content_length,
+                    "bytesRead": len(body),
+                },
+            )
+        return body
+
+    def _normalize_headers(self, handler: BaseHTTPRequestHandler) -> dict[str, str]:
+        return dict(handler.headers.items())
+
+    def _write_json(
+        self,
+        handler: BaseHTTPRequestHandler,
+        status_code: int,
+        payload: dict[str, Any],
+    ) -> None:
+        body = json.dumps(payload, ensure_ascii=True, separators=(",", ":")).encode(
+            "utf-8"
+        )
+        handler.send_response(status_code)
+        handler.send_header("Content-Type", "application/json; charset=utf-8")
+        handler.send_header("Content-Length", str(len(body)))
+        handler.end_headers()
+        handler.wfile.write(body)

androidctld/daemon/service.py

@@ -0,0 +1,99 @@
+"""Route dispatch for androidctld daemon."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from androidctl_contracts.daemon_api import RuntimeGetResult, RuntimePayload
+from androidctld import __version__
+from androidctld.commands.service import CommandService
+from androidctld.errors import bad_request
+from androidctld.runtime import RuntimeKernel
+from androidctld.runtime.screen_state import get_authoritative_current_basis
+from androidctld.runtime.store import RuntimeStore
+from androidctld.schema.daemon_api import (
+    HealthResult,
+    parse_command_run_request,
+    require_empty_payload,
+)
+
+
+class DaemonService:
+    def __init__(
+        self,
+        runtime_store: RuntimeStore,
+        command_service: CommandService,
+        bound_owner_id: str | None = None,
+    ) -> None:
+        self._runtime_store = runtime_store
+        self._runtime_kernel = RuntimeKernel(runtime_store)
+        self._command_service = command_service
+        self._bound_owner_id = bound_owner_id
+
+    def handle(
+        self,
+        method: str,
+        path: str,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> tuple[int, dict[str, Any]]:
+        del headers
+        if method != "POST":
+            raise bad_request(
+                "use POST for daemon endpoints", {"path": path, "method": method}
+            )
+        payload = self._parse_body(body)
+        if path == "/health":
+            return 200, self._handle_health(payload)
+        if path == "/runtime/get":
+            return 200, self._handle_runtime_get(payload)
+        if path == "/runtime/close":
+            return 200, self._handle_runtime_close(payload)
+        if path == "/commands/run":
+            return 200, self._handle_commands_run(payload)
+        raise bad_request("path not found", {"path": path})
+
+    def _parse_body(self, body: bytes) -> dict[str, Any]:
+        if not body or not body.strip():
+            return {}
+        try:
+            payload = json.loads(body.decode("utf-8"))
+        except ValueError as error:
+            raise bad_request("request body must be valid JSON") from error
+        if not isinstance(payload, dict):
+            raise bad_request("request body must be a JSON object")
+        return payload
+
+    def _handle_health(self, payload: dict[str, Any]) -> dict[str, Any]:
+        require_empty_payload(payload, "health")
+        runtime = self._runtime_store.get_runtime()
+        return HealthResult(
+            service="androidctld",
+            version=__version__,
+            workspace_root=runtime.workspace_root.as_posix(),
+            owner_id=self._bound_owner_id or "",
+        ).model_dump(mode="json")
+
+    def _handle_runtime_get(self, payload: dict[str, Any]) -> dict[str, Any]:
+        require_empty_payload(payload, "runtime/get")
+        runtime = self._runtime_kernel.ensure_runtime()
+        basis = get_authoritative_current_basis(runtime)
+        runtime_payload_kwargs: dict[str, Any] = {
+            "workspace_root": runtime.workspace_root.as_posix(),
+            "artifact_root": runtime.artifact_root.as_posix(),
+            "status": runtime.status,
+        }
+        if basis is not None:
+            runtime_payload_kwargs["current_screen_id"] = basis.screen_id
+        return RuntimeGetResult(
+            runtime=RuntimePayload(**runtime_payload_kwargs)
+        ).model_dump(mode="json")
+
+    def _handle_runtime_close(self, payload: dict[str, Any]) -> dict[str, Any]:
+        require_empty_payload(payload, "runtime/close")
+        return self._command_service.close_runtime()
+
+    def _handle_commands_run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        request = parse_command_run_request(payload)
+        return self._command_service.run(command=request.command)

androidctld/device/__init__.py

@@ -0,0 +1 @@
+"""Device transport and RPC primitives for androidctld."""

androidctld/device/action_models.py

@@ -0,0 +1,154 @@
+"""Typed outbound device action request models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from androidctld.refs.models import NodeHandle
+
+
+@dataclass(frozen=True)
+class HandleTarget:
+    handle: NodeHandle
+
+
+@dataclass(frozen=True)
+class CoordinatesTarget:
+    x: int
+    y: int
+
+
+@dataclass(frozen=True)
+class NoneTarget:
+    pass
+
+
+TapTarget: TypeAlias = HandleTarget | CoordinatesTarget
+
+
+@dataclass(frozen=True)
+class TapActionRequest:
+    target: TapTarget
+    timeout_ms: int
+
+
+@dataclass(frozen=True)
+class LongTapActionRequest:
+    target: TapTarget
+    timeout_ms: int
+
+
+@dataclass(frozen=True)
+class TypeActionRequest:
+    target: HandleTarget
+    text: str
+    timeout_ms: int
+    submit: bool = False
+
+
+@dataclass(frozen=True)
+class NodeActionRequest:
+    target: HandleTarget
+    action: str
+    timeout_ms: int
+
+
+@dataclass(frozen=True)
+class ScrollActionRequest:
+    target: HandleTarget
+    direction: str
+    timeout_ms: int
+
+
+@dataclass(frozen=True)
+class SwipeActionRequest:
+    target: NoneTarget
+    direction: str
+    timeout_ms: int
+
+
+@dataclass(frozen=True)
+class GlobalActionRequest:
+    target: NoneTarget
+    action: str
+    timeout_ms: int
+
+
+@dataclass(frozen=True)
+class LaunchAppActionRequest:
+    target: NoneTarget
+    package_name: str
+    timeout_ms: int
+
+
+@dataclass(frozen=True)
+class OpenUrlActionRequest:
+    target: NoneTarget
+    url: str
+    timeout_ms: int
+
+
+DeviceActionTarget: TypeAlias = HandleTarget | CoordinatesTarget | NoneTarget
+
+DeviceActionRequest: TypeAlias = (
+    TapActionRequest
+    | LongTapActionRequest
+    | TypeActionRequest
+    | NodeActionRequest
+    | ScrollActionRequest
+    | SwipeActionRequest
+    | GlobalActionRequest
+    | LaunchAppActionRequest
+    | OpenUrlActionRequest
+)
+
+
+@dataclass(frozen=True)
+class BuiltDeviceActionRequest:
+    payload: DeviceActionRequest
+    request_handle: NodeHandle | None = None
+    dispatched_handle: NodeHandle | None = None
+    submit_route: str | None = None
+
+
+def required_action_kind_for_request(request: DeviceActionRequest) -> str:
+    if isinstance(request, TapActionRequest):
+        return "tap"
+    if isinstance(request, LongTapActionRequest):
+        return "longTap"
+    if isinstance(request, TypeActionRequest):
+        return "type"
+    if isinstance(request, NodeActionRequest):
+        return "node"
+    if isinstance(request, ScrollActionRequest):
+        return "scroll"
+    if isinstance(request, SwipeActionRequest):
+        return "gesture"
+    if isinstance(request, GlobalActionRequest):
+        return "global"
+    if isinstance(request, LaunchAppActionRequest):
+        return "launchApp"
+    if isinstance(request, OpenUrlActionRequest):
+        return "openUrl"
+    raise TypeError(f"unsupported device action request: {type(request)!r}")
+
+
+__all__ = [
+    "CoordinatesTarget",
+    "DeviceActionRequest",
+    "DeviceActionTarget",
+    "GlobalActionRequest",
+    "HandleTarget",
+    "LaunchAppActionRequest",
+    "LongTapActionRequest",
+    "NodeActionRequest",
+    "NoneTarget",
+    "OpenUrlActionRequest",
+    "ScrollActionRequest",
+    "SwipeActionRequest",
+    "TapActionRequest",
+    "TapTarget",
+    "TypeActionRequest",
+    "required_action_kind_for_request",
+]

androidctld/device/action_serialization.py

@@ -0,0 +1,121 @@
+"""Serialization helpers for outbound device action requests."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from androidctld.device.action_models import (
+    CoordinatesTarget,
+    DeviceActionRequest,
+    DeviceActionTarget,
+    GlobalActionRequest,
+    HandleTarget,
+    LaunchAppActionRequest,
+    LongTapActionRequest,
+    NodeActionRequest,
+    NoneTarget,
+    OpenUrlActionRequest,
+    ScrollActionRequest,
+    SwipeActionRequest,
+    TapActionRequest,
+    TypeActionRequest,
+)
+from androidctld.device.adapters import dump_node_handle
+
+
+def dump_device_action_request(
+    request: DeviceActionRequest,
+) -> dict[str, Any]:
+    if isinstance(request, TapActionRequest):
+        return {
+            "kind": "tap",
+            "target": dump_device_action_target(request.target),
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, LongTapActionRequest):
+        return {
+            "kind": "longTap",
+            "target": dump_device_action_target(request.target),
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, TypeActionRequest):
+        return {
+            "kind": "type",
+            "target": dump_device_action_target(request.target),
+            "input": {
+                "text": request.text,
+                "replace": True,
+                "submit": request.submit,
+                "ensureFocused": True,
+            },
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, NodeActionRequest):
+        return {
+            "kind": "node",
+            "target": dump_device_action_target(request.target),
+            "node": {"action": request.action},
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, ScrollActionRequest):
+        return {
+            "kind": "scroll",
+            "target": dump_device_action_target(request.target),
+            "scroll": {"direction": request.direction},
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, SwipeActionRequest):
+        if not isinstance(request.target, NoneTarget):
+            raise TypeError("swipe action requires none target")
+        return {
+            "kind": "gesture",
+            "target": dump_device_action_target(request.target),
+            "gesture": {"direction": request.direction},
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, GlobalActionRequest):
+        return {
+            "kind": "global",
+            "target": dump_device_action_target(request.target),
+            "global": {"action": request.action},
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, LaunchAppActionRequest):
+        return {
+            "kind": "launchApp",
+            "target": dump_device_action_target(request.target),
+            "intent": {
+                "packageName": request.package_name,
+            },
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    if isinstance(request, OpenUrlActionRequest):
+        return {
+            "kind": "openUrl",
+            "target": dump_device_action_target(request.target),
+            "intent": {
+                "url": request.url,
+            },
+            "options": {"timeoutMs": request.timeout_ms},
+        }
+    raise TypeError(f"unsupported device action request: {type(request)!r}")
+
+
+def dump_device_action_target(target: DeviceActionTarget) -> dict[str, Any]:
+    if isinstance(target, HandleTarget):
+        return {
+            "kind": "handle",
+            "handle": dump_node_handle(target.handle),
+        }
+    if isinstance(target, CoordinatesTarget):
+        return {
+            "kind": "coordinates",
+            "x": target.x,
+            "y": target.y,
+        }
+    if isinstance(target, NoneTarget):
+        return {"kind": "none"}
+    raise TypeError(f"unsupported device action target: {type(target)!r}")
+
+
+__all__ = ["dump_device_action_request", "dump_device_action_target"]