androidctl 0.1.0__py3-none-any.whl

androidctld/auth/active_registry.py

@@ -0,0 +1,266 @@
+"""active.json persistence for androidctld."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager, suppress
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, cast
+
+from pydantic import ValidationError
+
+from androidctl_contracts.user_state import ActiveDaemonRecord
+from androidctld.auth.secret_files import write_secret_json_file_atomically
+from androidctld.config import DaemonConfig, normalize_loopback_host
+from androidctld.daemon.ownership_probe import (
+    OwnershipHealthProbe,
+    OwnershipHealthProbeResult,
+    OwnershipHealthStatus,
+)
+from androidctld.schema.persistence import (
+    ActiveDaemonFile,
+    build_persistence_model,
+)
+
+__all__ = ["ActiveDaemonRecord", "ActiveDaemonRegistry"]
+
+
+class ActiveDaemonRegistry:
+    _LOCK_ACQUIRE_TIMEOUT_SECONDS = 2.0
+    _LOCK_RETRY_INTERVAL_SECONDS = 0.01
+    _LOCK_STALE_SECONDS = 30.0
+
+    def __init__(
+        self,
+        config: DaemonConfig,
+        *,
+        live_checker: (
+            Callable[[ActiveDaemonRecord], OwnershipHealthProbeResult] | None
+        ) = None,
+    ) -> None:
+        self._config = config
+        self._live_checker = live_checker or self._default_live_checker
+
+    def build_record(self, host: str, port: int, token: str) -> ActiveDaemonRecord:
+        pid = os.getpid()
+        started_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+        return ActiveDaemonRecord(
+            pid=pid,
+            host=normalize_loopback_host(host),
+            port=port,
+            token=token,
+            started_at=started_at,
+            workspace_root=self._config.workspace_root.as_posix(),
+            owner_id=self._config.owner_id,
+        )
+
+    def publish(self, record: ActiveDaemonRecord) -> None:
+        self._config.state_dir.mkdir(parents=True, exist_ok=True)
+        with self._active_lock():
+            existing = self.read()
+            if existing is not None and self._active_record_conflicts(
+                existing,
+                record,
+            ):
+                raise RuntimeError("live daemon already owns active slot")
+            payload = self._build_active_file_payload(record)
+            self._write_active_file_atomically(payload)
+
+    def clear(self, *, record: ActiveDaemonRecord | None = None) -> None:
+        with self._active_lock():
+            if record is not None:
+                try:
+                    active_file = self._read_active_file_model()
+                except FileNotFoundError:
+                    return
+                except OSError:
+                    return
+                except (ValueError, json.JSONDecodeError, ValidationError):
+                    pass
+                else:
+                    if (
+                        active_file.pid != record.pid
+                        or active_file.started_at != record.started_at
+                    ):
+                        return
+            try:
+                self._config.active_file_path.unlink()
+            except FileNotFoundError:
+                return
+
+    def restore(self, record: ActiveDaemonRecord) -> None:
+        payload = self._build_active_file_payload(record)
+        with self._active_lock():
+            self._write_active_file_atomically(payload)
+
+    def read(self) -> ActiveDaemonRecord | None:
+        if not self._config.active_file_path.exists():
+            return None
+        try:
+            record = self._read_active_file_model()
+        except OSError:
+            return None
+        except (ValueError, json.JSONDecodeError, ValidationError):
+            with suppress(OSError):
+                self._config.active_file_path.unlink()
+            return None
+        return ActiveDaemonRecord(
+            pid=record.pid,
+            host=record.host,
+            port=record.port,
+            token=record.token,
+            started_at=record.started_at,
+            workspace_root=record.workspace_root,
+            owner_id=record.owner_id,
+        )
+
+    def _active_record_conflicts(
+        self,
+        existing: ActiveDaemonRecord,
+        record: ActiveDaemonRecord,
+    ) -> bool:
+        if existing.identity == record.identity:
+            return False
+        probe_result = self._live_checker(existing)
+        if probe_result.is_live:
+            return True
+        if probe_result.status == OwnershipHealthStatus.UNREACHABLE:
+            return False
+        return self._is_pid_live(existing.pid)
+
+    def _default_live_checker(
+        self,
+        record: ActiveDaemonRecord,
+    ) -> OwnershipHealthProbeResult:
+        return OwnershipHealthProbe().probe_active_record(
+            record,
+            expected_workspace_root=self._config.workspace_root.as_posix(),
+            expected_owner_id=self._config.owner_id,
+        )
+
+    def _read_active_file_model(self) -> ActiveDaemonFile:
+        with self._config.active_file_path.open("r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+        return ActiveDaemonFile.model_validate(payload)
+
+    @staticmethod
+    def _build_active_file_payload(record: ActiveDaemonRecord) -> dict[str, object]:
+        return cast(
+            dict[str, object],
+            build_persistence_model(
+                ActiveDaemonFile,
+                pid=record.pid,
+                host=normalize_loopback_host(record.host),
+                port=record.port,
+                token=record.token,
+                started_at=record.started_at,
+                workspace_root=record.workspace_root,
+                owner_id=record.owner_id,
+            ).model_dump(by_alias=True, mode="json"),
+        )
+
+    @staticmethod
+    def _is_pid_live(pid: int) -> bool:
+        if pid <= 0:
+            return False
+        if platform.system() == "Windows":
+            return ActiveDaemonRegistry._windows_is_pid_live(pid)
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True
+        except OSError:
+            return False
+        return True
+
+    @staticmethod
+    def _windows_is_pid_live(pid: int, kernel32: Any | None = None) -> bool:
+        import ctypes
+
+        process_query_limited_information = 0x1000
+        still_active = 259
+        if kernel32 is None:
+            windll = getattr(ctypes, "windll", None)
+            if windll is None:
+                return False
+            kernel32 = windll.kernel32
+
+        process_handle = kernel32.OpenProcess(
+            process_query_limited_information,
+            False,
+            pid,
+        )
+        if not process_handle:
+            return False
+
+        try:
+            exit_code = ctypes.c_ulong(0)
+            if not kernel32.GetExitCodeProcess(process_handle, ctypes.byref(exit_code)):
+                return False
+            return exit_code.value == still_active
+        finally:
+            kernel32.CloseHandle(process_handle)
+
+    @contextmanager
+    def _active_lock(self) -> Iterator[None]:
+        lock_path = self._config.active_lock_path
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        deadline = time.monotonic() + self._LOCK_ACQUIRE_TIMEOUT_SECONDS
+        while True:
+            fd: int | None = None
+            try:
+                fd = os.open(
+                    lock_path,
+                    os.O_CREAT | os.O_EXCL | os.O_WRONLY,
+                    0o600,
+                )
+                os.write(fd, str(os.getpid()).encode("utf-8"))
+                os.close(fd)
+                fd = None
+                break
+            except FileExistsError:
+                if self._recover_stale_lock(lock_path):
+                    continue
+                if time.monotonic() >= deadline:
+                    raise RuntimeError("timed out acquiring active slot lock") from None
+                time.sleep(self._LOCK_RETRY_INTERVAL_SECONDS)
+            finally:
+                if fd is not None:
+                    os.close(fd)
+        try:
+            yield
+        finally:
+            with suppress(FileNotFoundError):
+                lock_path.unlink()
+
+    def _recover_stale_lock(self, lock_path: Path) -> bool:
+        try:
+            raw = lock_path.read_text(encoding="utf-8").strip()
+            pid = int(raw) if raw else -1
+        except (OSError, ValueError):
+            pid = -1
+        if pid > 0 and self._is_pid_live(pid):
+            return False
+        try:
+            lock_age_seconds = time.time() - lock_path.stat().st_mtime
+        except OSError:
+            return False
+        if pid <= 0 and lock_age_seconds < self._LOCK_STALE_SECONDS:
+            return False
+        try:
+            lock_path.unlink()
+        except FileNotFoundError:
+            return True
+        except OSError:
+            return False
+        return True
+
+    def _write_active_file_atomically(self, payload: dict[str, object]) -> None:
+        write_secret_json_file_atomically(self._config.active_file_path, payload)

androidctld/auth/secret_files.py

@@ -0,0 +1,52 @@
+"""Restricted atomic writers for daemon-local sensitive state."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+from androidctld.schema.persistence_io import dump_formatted_json
+
+SECRET_FILE_MODE = 0o600
+SECRET_DIR_MODE = 0o700
+
+
+def write_secret_json_file_atomically(path: Path, payload: dict[str, Any]) -> None:
+    """Write sensitive daemon JSON state via a restricted atomic sidecar."""
+    _ensure_secret_parent_dir(path.parent)
+    temp_path = _unique_temp_path(path)
+    fd: int | None = None
+    try:
+        fd = os.open(
+            temp_path,
+            os.O_CREAT | os.O_EXCL | os.O_WRONLY,
+            SECRET_FILE_MODE,
+        )
+        if os.name == "posix":
+            os.fchmod(fd, SECRET_FILE_MODE)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            fd = None
+            dump_formatted_json(handle, payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_path, path)
+    except BaseException:
+        if fd is not None:
+            os.close(fd)
+        raise
+    finally:
+        with suppress(FileNotFoundError):
+            temp_path.unlink()
+
+
+def _unique_temp_path(path: Path) -> Path:
+    return path.with_name(f"{path.name}.{os.getpid()}.{uuid.uuid4().hex}.tmp")
+
+
+def _ensure_secret_parent_dir(path: Path) -> None:
+    path.mkdir(parents=True, exist_ok=True)
+    if os.name == "posix":
+        os.chmod(path, SECRET_DIR_MODE)

androidctld/auth/token_store.py

@@ -0,0 +1,59 @@
+"""Daemon token management."""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+
+from androidctld.auth.secret_files import write_secret_json_file_atomically
+from androidctld.config import DaemonConfig
+
+
+@dataclass
+class DaemonTokenStore:
+    config: DaemonConfig | None = None
+    _token: str = ""
+
+    def current_token(self) -> str:
+        if self._token:
+            return self._token
+        token_path = self._token_path()
+        if token_path is not None:
+            loaded = self._load_token(token_path)
+            if loaded:
+                self._token = loaded
+                return self._token
+        self._token = secrets.token_urlsafe(32)
+        if token_path is not None:
+            self._persist_token(token_path, self._token)
+        return self._token
+
+    @classmethod
+    def load_existing_token(cls, path: Path) -> str | None:
+        return cls._load_token(path)
+
+    def _token_path(self) -> Path | None:
+        if self.config is None:
+            return None
+        return self.config.token_file_path
+
+    @staticmethod
+    def _load_token(path: Path) -> str | None:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError, json.JSONDecodeError):
+            return None
+        if not isinstance(payload, dict):
+            return None
+        token = payload.get("token")
+        if isinstance(token, str):
+            token = token.strip()
+            if token:
+                return token
+        return None
+
+    @staticmethod
+    def _persist_token(path: Path, token: str) -> None:
+        write_secret_json_file_atomically(path, {"token": token})

androidctld/commands/__init__.py

@@ -0,0 +1 @@
+"""Command handling for androidctld."""

androidctld/commands/assembly.py

@@ -0,0 +1,231 @@
+"""Command service object-graph assembly helpers."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from androidctld.actions.executor import ActionExecutor
+from androidctld.actions.repair import ActionCommandRepairer
+from androidctld.actions.settle import ActionSettler
+from androidctld.artifacts.writer import ArtifactWriter
+from androidctld.commands.dispatch import CommandDispatch
+from androidctld.commands.executor import CommandExecutor
+from androidctld.commands.handlers.action import ActionCommandHandler
+from androidctld.commands.handlers.connect import ConnectCommandHandler
+from androidctld.commands.handlers.list_apps import ListAppsCommandHandler
+from androidctld.commands.handlers.observe import ObserveCommandHandler
+from androidctld.commands.handlers.screenshot import ScreenshotCommandHandler
+from androidctld.commands.handlers.wait import WaitCommandHandler
+from androidctld.commands.orchestration import CommandRunOrchestrator
+from androidctld.device.bootstrap import DeviceBootstrapper
+from androidctld.device.interfaces import (
+    DeviceClientFactory,
+    DeviceClientProvider,
+    DeviceRuntimeClient,
+)
+from androidctld.runtime import RuntimeKernel, RuntimeLifecycleLease, RuntimeStore
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.semantics.compiler import SemanticCompiler
+from androidctld.snapshots.refresh import ScreenRefreshService
+from androidctld.snapshots.service import SnapshotService
+from androidctld.waits.loop import WaitRuntimeLoop
+
+SleepFn = Callable[[float], None]
+TimeFn = Callable[[], float]
+
+__all__ = ["CommandServiceAssembly", "SleepFn", "assemble_command_service"]
+
+
+class _RuntimePersistencePort:
+    def __init__(
+        self,
+        *,
+        runtime_kernel: RuntimeKernel,
+        runtime_store: RuntimeStore,
+    ) -> None:
+        self._runtime_kernel = runtime_kernel
+        self._runtime_store = runtime_store
+
+    def ensure_runtime(self) -> WorkspaceRuntime:
+        return self._runtime_kernel.ensure_runtime()
+
+    def persist_runtime(self, runtime: WorkspaceRuntime) -> None:
+        self._runtime_store.persist_runtime(runtime)
+
+
+@dataclass(slots=True)
+class CommandServiceAssembly:
+    sleep_fn: SleepFn
+    time_fn: TimeFn
+    runtime_kernel: RuntimeKernel
+    runtime_store: _RuntimePersistencePort
+    bootstrapper: DeviceBootstrapper
+    snapshot_service: SnapshotService
+    semantic_compiler: SemanticCompiler
+    device_client_factory: DeviceClientFactory
+    artifact_writer: ArtifactWriter
+    screen_refresh: ScreenRefreshService
+    action_executor: ActionExecutor
+    wait_runtime_loop: WaitRuntimeLoop
+    connect_handler: ConnectCommandHandler
+    observe_handler: ObserveCommandHandler
+    list_apps_handler: ListAppsCommandHandler
+    action_handler: ActionCommandHandler
+    wait_handler: WaitCommandHandler
+    screenshot_handler: ScreenshotCommandHandler
+    orchestrator: CommandRunOrchestrator
+    dispatch: CommandDispatch
+    executor: CommandExecutor
+
+
+def assemble_command_service(
+    *,
+    runtime_store: RuntimeStore,
+    bootstrapper: DeviceBootstrapper | None = None,
+    snapshot_service: SnapshotService | None = None,
+    semantic_compiler: SemanticCompiler | None = None,
+    artifact_writer: ArtifactWriter | None = None,
+    device_client_factory: DeviceClientFactory | None = None,
+    sleep_fn: SleepFn | None = None,
+    time_fn: TimeFn | None = None,
+) -> CommandServiceAssembly:
+    resolved_sleep_fn = sleep_fn or time.sleep
+    resolved_time_fn = time_fn or time.monotonic
+    runtime_kernel = RuntimeKernel(
+        runtime_store,
+        sleep_fn=resolved_sleep_fn,
+        time_fn=resolved_time_fn,
+    )
+    persistence_port = _RuntimePersistencePort(
+        runtime_kernel=runtime_kernel,
+        runtime_store=runtime_store,
+    )
+    resolved_bootstrapper = bootstrapper or DeviceBootstrapper()
+    default_snapshot_service = SnapshotService(
+        bootstrapper=resolved_bootstrapper,
+        runtime_kernel=runtime_kernel,
+    )
+    resolved_snapshot_service = snapshot_service or default_snapshot_service
+    resolved_semantic_compiler = semantic_compiler or SemanticCompiler()
+    resolved_device_client_factory = _resolve_device_client_factory(
+        snapshot_service=resolved_snapshot_service,
+        explicit_factory=device_client_factory,
+    )
+    resolved_artifact_writer = artifact_writer or ArtifactWriter()
+    screen_refresh = ScreenRefreshService(
+        runtime_kernel=runtime_kernel,
+        semantic_compiler=resolved_semantic_compiler,
+        artifact_writer=resolved_artifact_writer,
+    )
+    action_executor = ActionExecutor(
+        device_client_factory=resolved_device_client_factory,
+        screen_refresh=screen_refresh,
+        settler=ActionSettler(
+            snapshot_service=resolved_snapshot_service,
+            semantic_compiler=resolved_semantic_compiler,
+            sleep_fn=resolved_sleep_fn,
+            time_fn=resolved_time_fn,
+        ),
+        repairer=ActionCommandRepairer(
+            snapshot_service=resolved_snapshot_service,
+            screen_refresh=screen_refresh,
+        ),
+        runtime_kernel=runtime_kernel,
+    )
+    wait_runtime_loop = WaitRuntimeLoop(
+        snapshot_service=resolved_snapshot_service,
+        screen_refresh=screen_refresh,
+        device_client_factory=resolved_device_client_factory,
+        sleep_fn=resolved_sleep_fn,
+        time_fn=resolved_time_fn,
+    )
+    connect_handler = ConnectCommandHandler(
+        runtime_kernel=runtime_kernel,
+        bootstrapper=resolved_bootstrapper,
+        snapshot_service=resolved_snapshot_service,
+        screen_refresh=screen_refresh,
+    )
+    observe_handler = ObserveCommandHandler(
+        runtime_kernel=runtime_kernel,
+        snapshot_service=resolved_snapshot_service,
+        screen_refresh=screen_refresh,
+    )
+    list_apps_handler = ListAppsCommandHandler(
+        runtime_kernel=runtime_kernel,
+        bootstrapper=resolved_bootstrapper,
+    )
+    action_handler = ActionCommandHandler(
+        runtime_kernel=runtime_kernel,
+        action_executor=action_executor,
+    )
+    wait_handler = WaitCommandHandler(
+        runtime_kernel=runtime_kernel,
+        wait_runtime_loop=wait_runtime_loop,
+    )
+    screenshot_handler = ScreenshotCommandHandler(
+        runtime_kernel=runtime_kernel,
+        device_client_factory=resolved_device_client_factory,
+        artifact_writer=resolved_artifact_writer,
+    )
+    orchestrator = CommandRunOrchestrator(
+        serial_admission=runtime_store.begin_serial_command,
+        time_fn=resolved_time_fn,
+    )
+    dispatch = CommandDispatch(
+        connect_handler=connect_handler,
+        observe_handler=observe_handler,
+        list_apps_handler=list_apps_handler,
+        action_handler=action_handler,
+        wait_handler=wait_handler,
+        screenshot_handler=screenshot_handler,
+    )
+    executor = CommandExecutor(handlers=dispatch.build_handlers())
+    return CommandServiceAssembly(
+        sleep_fn=resolved_sleep_fn,
+        time_fn=resolved_time_fn,
+        runtime_kernel=runtime_kernel,
+        runtime_store=persistence_port,
+        bootstrapper=resolved_bootstrapper,
+        snapshot_service=resolved_snapshot_service,
+        semantic_compiler=resolved_semantic_compiler,
+        device_client_factory=resolved_device_client_factory,
+        artifact_writer=resolved_artifact_writer,
+        screen_refresh=screen_refresh,
+        action_executor=action_executor,
+        wait_runtime_loop=wait_runtime_loop,
+        connect_handler=connect_handler,
+        observe_handler=observe_handler,
+        list_apps_handler=list_apps_handler,
+        action_handler=action_handler,
+        wait_handler=wait_handler,
+        screenshot_handler=screenshot_handler,
+        orchestrator=orchestrator,
+        dispatch=dispatch,
+        executor=executor,
+    )
+
+
+def _resolve_device_client_factory(
+    *,
+    snapshot_service: object,
+    explicit_factory: DeviceClientFactory | None,
+) -> DeviceClientFactory:
+    if explicit_factory is not None:
+        return explicit_factory
+    if isinstance(snapshot_service, DeviceClientProvider):
+        return snapshot_service.device_client
+    return _missing_device_client_factory
+
+
+def _missing_device_client_factory(
+    session: WorkspaceRuntime,
+    *,
+    lifecycle_lease: RuntimeLifecycleLease | None = None,
+) -> DeviceRuntimeClient:
+    del session, lifecycle_lease
+    raise RuntimeError(
+        "CommandService requires device_client_factory when snapshot_service "
+        "does not provide device_client()"
+    )