androidctl 0.1.0__py3-none-any.whl

androidctld/daemon/envelope.py

@@ -0,0 +1,30 @@
+"""JSON envelope helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from androidctl_contracts.daemon_api import DaemonErrorEnvelope
+from androidctl_contracts.errors import DaemonError as ContractDaemonError
+from androidctl_contracts.errors import DaemonErrorCode as ContractDaemonErrorCode
+from androidctld.errors import DaemonError
+
+
+def success_envelope(result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "ok": True,
+        "result": result,
+    }
+
+
+def error_envelope(error: DaemonError) -> dict[str, Any]:
+    try:
+        contract_error = error.to_contract_error()
+    except ValueError:
+        contract_error = ContractDaemonError(
+            code=ContractDaemonErrorCode.INTERNAL_COMMAND_FAILURE,
+            message="unexpected daemon failure",
+            retryable=False,
+            details={},
+        )
+    return DaemonErrorEnvelope(error=contract_error).model_dump()

androidctld/daemon/http_host.py

@@ -0,0 +1,123 @@
+"""HTTP host lifecycle and readiness probing for androidctld."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from collections.abc import Callable
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Protocol
+from urllib.error import HTTPError, URLError
+from urllib.request import OpenerDirector, ProxyHandler, Request, build_opener
+
+from androidctl_contracts.daemon_api import (
+    OWNER_HEADER_NAME,
+    DaemonSuccessEnvelope,
+    HealthResult,
+)
+from androidctld import SERVICE_NAME
+from androidctld.auth.active_registry import ActiveDaemonRecord
+from androidctld.config import TOKEN_HEADER_NAME, DaemonConfig
+
+
+class _Opener(Protocol):
+    def open(self, request: Request, timeout: float) -> Any: ...
+
+
+class DaemonHttpHost:
+    _READY_TIMEOUT_SECONDS = 2.0
+    _READY_POLL_INTERVAL_SECONDS = 0.05
+
+    def __init__(
+        self,
+        *,
+        config: DaemonConfig,
+        logger: logging.Logger,
+        opener_factory: Callable[[], _Opener | OpenerDirector] | None = None,
+    ) -> None:
+        self._config = config
+        self._logger = logger
+        self._opener_factory: Callable[[], _Opener | OpenerDirector]
+        self._opener_factory = opener_factory or self._build_proxy_bypassing_opener
+        self._server: ThreadingHTTPServer | None = None
+        self._thread: threading.Thread | None = None
+
+    @property
+    def is_running(self) -> bool:
+        return self._server is not None
+
+    @property
+    def ready_poll_interval_seconds(self) -> float:
+        return self._READY_POLL_INTERVAL_SECONDS
+
+    def start(self, handler_class: type[BaseHTTPRequestHandler]) -> tuple[str, int]:
+        if self._server is not None:
+            raise RuntimeError("androidctld server is already running")
+        host = self._config.host
+        httpd = ThreadingHTTPServer((host, self._config.port), handler_class)
+        httpd.daemon_threads = True
+        try:
+            thread = threading.Thread(
+                target=httpd.serve_forever,
+                name="androidctld-http",
+                daemon=True,
+            )
+            thread.start()
+        except Exception:
+            httpd.server_close()
+            raise
+        self._server = httpd
+        self._thread = thread
+        _, port = httpd.server_address[:2]
+        return host, port
+
+    def wait_until_ready(
+        self,
+        *,
+        record: ActiveDaemonRecord,
+        owner_id: str | None = None,
+    ) -> None:
+        deadline = time.monotonic() + self._READY_TIMEOUT_SECONDS
+        health_url = f"http://{record.host}:{record.port}/health"
+        headers = {
+            TOKEN_HEADER_NAME: record.token,
+            OWNER_HEADER_NAME: owner_id or self._config.owner_id,
+        }
+        opener = self._opener_factory()
+        while True:
+            request = Request(health_url, method="POST", data=b"{}", headers=headers)
+            try:
+                with opener.open(
+                    request, timeout=self._READY_POLL_INTERVAL_SECONDS
+                ) as response:
+                    payload = json.loads(response.read().decode("utf-8"))
+                envelope = DaemonSuccessEnvelope[HealthResult].model_validate(payload)
+                if envelope.result.service == SERVICE_NAME:
+                    return
+            except HTTPError as error:
+                error.close()
+            except (OSError, URLError, ValueError, json.JSONDecodeError):
+                pass
+            if time.monotonic() >= deadline:
+                raise RuntimeError(
+                    "timed out waiting for androidctld readiness health check"
+                )
+            time.sleep(self._READY_POLL_INTERVAL_SECONDS)
+
+    def stop(self) -> None:
+        server = self._server
+        thread = self._thread
+        self._server = None
+        self._thread = None
+        if server is None:
+            return
+        server.shutdown()
+        server.server_close()
+        if thread is not None:
+            thread.join(timeout=2.0)
+
+    @staticmethod
+    def _build_proxy_bypassing_opener() -> OpenerDirector:
+        return build_opener(ProxyHandler({}))

androidctld/daemon/ingress.py

@@ -0,0 +1,112 @@
+"""Daemon ingress boundary for authenticated request dispatch."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from androidctl_contracts.command_results import RetainedResultEnvelope
+from androidctl_contracts.daemon_api import OWNER_HEADER_NAME
+from androidctld.config import TOKEN_HEADER_NAME
+from androidctld.errors import DaemonError, DaemonErrorCode, unauthorized
+
+
+class DaemonDispatcher(Protocol):
+    def handle(
+        self,
+        method: str,
+        path: str,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> tuple[int, dict[str, Any]]: ...
+
+
+@dataclass(frozen=True)
+class IngressResult:
+    status_code: int
+    payload: dict[str, Any]
+    shutdown_after_write: bool = False
+
+
+class DaemonIngress:
+    def __init__(
+        self,
+        *,
+        token_provider: Callable[[], str | None],
+        owner_id_provider: Callable[[], str | None],
+        dispatcher: DaemonDispatcher,
+    ) -> None:
+        self._token_provider = token_provider
+        self._owner_id_provider = owner_id_provider
+        self._dispatcher = dispatcher
+
+    def handle(
+        self,
+        *,
+        method: str,
+        path: str,
+        headers: dict[str, str],
+        body: bytes,
+    ) -> IngressResult:
+        self._require_token(headers)
+        self._require_owner(headers)
+        status_code, payload = self._dispatcher.handle(
+            method=method,
+            path=path,
+            headers=headers,
+            body=body,
+        )
+        return IngressResult(
+            status_code=status_code,
+            payload=payload,
+            shutdown_after_write=_should_shutdown_after_write(
+                method=method,
+                path=path,
+                status_code=status_code,
+                payload=payload,
+            ),
+        )
+
+    def _require_token(self, headers: dict[str, str]) -> None:
+        expected = self._token_provider()
+        supplied = self._header_value(headers, TOKEN_HEADER_NAME)
+        if not expected or supplied != expected:
+            raise unauthorized()
+
+    def _require_owner(self, headers: dict[str, str]) -> None:
+        owner_id = self._owner_id_provider()
+        if not owner_id:
+            return
+        supplied = self._header_value(headers, OWNER_HEADER_NAME)
+        if supplied == owner_id:
+            return
+        raise DaemonError(
+            code=DaemonErrorCode.WORKSPACE_BUSY,
+            message="workspace daemon is owned by a different shell or agent",
+            retryable=False,
+            details={"ownerId": owner_id},
+            http_status=200,
+        )
+
+    def _header_value(self, headers: dict[str, str], header_name: str) -> str | None:
+        for key, value in headers.items():
+            if key.lower() == header_name.lower():
+                return value.strip()
+        return None
+
+
+def _should_shutdown_after_write(
+    *,
+    method: str,
+    path: str,
+    status_code: int,
+    payload: dict[str, Any],
+) -> bool:
+    if method != "POST" or path != "/runtime/close" or status_code != 200:
+        return False
+    try:
+        result = RetainedResultEnvelope.model_validate(payload)
+    except ValueError:
+        return False
+    return result.ok is True and result.command == "close"

androidctld/daemon/ownership_probe.py

@@ -0,0 +1,204 @@
+"""Listener health evidence for daemon ownership records."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Protocol
+from urllib.error import HTTPError, URLError
+from urllib.request import OpenerDirector, ProxyHandler, Request, build_opener
+
+from androidctl_contracts.daemon_api import (
+    OWNER_HEADER_NAME,
+    DaemonErrorEnvelope,
+    DaemonSuccessEnvelope,
+    HealthResult,
+)
+from androidctl_contracts.user_state import ActiveDaemonRecord
+from androidctld import SERVICE_NAME
+from androidctld.config import TOKEN_HEADER_NAME, normalize_loopback_host
+
+
+class _Opener(Protocol):
+    def open(self, request: Request, timeout: float) -> Any: ...
+
+
+class OwnershipHealthStatus(str, Enum):
+    LIVE_MATCH = "live_match"
+    LIVE_MISMATCH = "live_mismatch"
+    UNREACHABLE = "unreachable"
+    UNPROBEABLE = "unprobeable"
+
+
+@dataclass(frozen=True)
+class OwnershipHealthProbeResult:
+    status: OwnershipHealthStatus
+    token: str | None = None
+
+    @property
+    def is_live(self) -> bool:
+        return self.status in {
+            OwnershipHealthStatus.LIVE_MATCH,
+            OwnershipHealthStatus.LIVE_MISMATCH,
+        }
+
+
+class OwnershipHealthProbe:
+    _TIMEOUT_SECONDS = 0.15
+
+    def __init__(
+        self,
+        *,
+        opener_factory: Callable[[], _Opener | OpenerDirector] | None = None,
+        timeout_seconds: float | None = None,
+    ) -> None:
+        self._opener_factory = opener_factory or self._build_proxy_bypassing_opener
+        self._timeout_seconds = timeout_seconds or self._TIMEOUT_SECONDS
+
+    def probe(
+        self,
+        *,
+        host: str,
+        port: int,
+        owner_id: str,
+        workspace_root: str,
+        expected_workspace_root: str,
+        expected_owner_id: str,
+        tokens: Iterable[str],
+    ) -> OwnershipHealthProbeResult:
+        if port <= 0:
+            return OwnershipHealthProbeResult(OwnershipHealthStatus.UNPROBEABLE)
+        try:
+            normalized_host = normalize_loopback_host(host)
+        except ValueError:
+            return OwnershipHealthProbeResult(OwnershipHealthStatus.UNPROBEABLE)
+
+        opener = self._opener_factory()
+        url = f"http://{self._url_host(normalized_host)}:{port}/health"
+        mismatch: OwnershipHealthProbeResult | None = None
+        for token in self._probe_tokens(tokens):
+            headers = {
+                TOKEN_HEADER_NAME: token,
+                OWNER_HEADER_NAME: owner_id,
+            }
+            request = Request(url, method="POST", data=b"{}", headers=headers)
+            try:
+                with opener.open(request, timeout=self._timeout_seconds) as response:
+                    payload = json.loads(response.read().decode("utf-8"))
+            except HTTPError as error:
+                try:
+                    payload = json.loads(error.read().decode("utf-8"))
+                except (OSError, ValueError, json.JSONDecodeError):
+                    error.close()
+                    continue
+                error.close()
+            except (OSError, URLError, ValueError, json.JSONDecodeError):
+                continue
+
+            status = self._classify_health_payload(
+                payload,
+                token=token,
+                owner_id=owner_id,
+                workspace_root=workspace_root,
+                expected_workspace_root=expected_workspace_root,
+                expected_owner_id=expected_owner_id,
+            )
+            if status is None:
+                continue
+            if status.status == OwnershipHealthStatus.LIVE_MATCH:
+                return status
+            if status.status == OwnershipHealthStatus.LIVE_MISMATCH:
+                mismatch = status
+                continue
+            return status
+        if mismatch is not None:
+            return mismatch
+        return OwnershipHealthProbeResult(OwnershipHealthStatus.UNREACHABLE)
+
+    def _classify_health_payload(
+        self,
+        payload: object,
+        *,
+        token: str,
+        owner_id: str,
+        workspace_root: str,
+        expected_workspace_root: str,
+        expected_owner_id: str,
+    ) -> OwnershipHealthProbeResult | None:
+        try:
+            envelope = DaemonSuccessEnvelope[HealthResult].model_validate(payload)
+        except ValueError:
+            return self._classify_error_payload(payload)
+
+        result = envelope.result
+        if result.service != SERVICE_NAME:
+            return None
+        if (
+            result.workspace_root == expected_workspace_root
+            and result.owner_id == expected_owner_id
+            and workspace_root == expected_workspace_root
+            and owner_id == expected_owner_id
+        ):
+            return OwnershipHealthProbeResult(
+                OwnershipHealthStatus.LIVE_MATCH,
+                token=token,
+            )
+        return OwnershipHealthProbeResult(OwnershipHealthStatus.LIVE_MISMATCH)
+
+    @staticmethod
+    def _classify_error_payload(
+        payload: object,
+    ) -> OwnershipHealthProbeResult | None:
+        try:
+            envelope = DaemonErrorEnvelope.model_validate(payload)
+        except ValueError:
+            return None
+        if envelope.error.code.value in {"DAEMON_UNAUTHORIZED", "WORKSPACE_BUSY"}:
+            return OwnershipHealthProbeResult(OwnershipHealthStatus.LIVE_MISMATCH)
+        return None
+
+    def probe_active_record(
+        self,
+        record: ActiveDaemonRecord,
+        *,
+        expected_workspace_root: str,
+        expected_owner_id: str,
+    ) -> OwnershipHealthProbeResult:
+        return self.probe(
+            host=record.host,
+            port=record.port,
+            owner_id=record.owner_id,
+            workspace_root=record.workspace_root,
+            expected_workspace_root=expected_workspace_root,
+            expected_owner_id=expected_owner_id,
+            tokens=(record.token,),
+        )
+
+    @staticmethod
+    def _unique_tokens(tokens: Iterable[str]) -> list[str]:
+        unique: list[str] = []
+        seen: set[str] = set()
+        for token in tokens:
+            token = token.strip()
+            if not token or token in seen:
+                continue
+            unique.append(token)
+            seen.add(token)
+        return unique
+
+    @classmethod
+    def _probe_tokens(cls, tokens: Iterable[str]) -> list[str]:
+        unique = cls._unique_tokens(tokens)
+        return unique or [""]
+
+    @staticmethod
+    def _url_host(host: str) -> str:
+        if ":" in host and not host.startswith("["):
+            return f"[{host}]"
+        return host
+
+    @staticmethod
+    def _build_proxy_bypassing_opener() -> OpenerDirector:
+        return build_opener(ProxyHandler({}))