androidctl 0.1.0__py3-none-any.whl

androidctld/schema/persistence.py

@@ -0,0 +1,161 @@
+"""Persistence boundary models for androidctld local state."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, TypeVar
+
+from pydantic import (
+    ConfigDict,
+    Field,
+    ValidationError,
+    field_validator,
+)
+
+from androidctld.protocol import RuntimeStatus
+from androidctld.schema.base import ApiModel, to_camel
+from androidctld.schema.core import (
+    SchemaDecodeError,
+    expect_field,
+    expect_int,
+    expect_object,
+)
+from androidctld.schema.validation_errors import validation_error_to_schema_decode_error
+
+RUNTIME_STATE_SCHEMA_VERSION = 1
+RUNTIME_STATE_FILE_NAME = "runtime.json"
+
+EnumT = TypeVar("EnumT", bound=Enum)
+PersistenceModelT = TypeVar("PersistenceModelT", bound="PersistenceModel")
+
+
+def expect_schema_version(
+    payload: object,
+    field_name: str,
+    version: int,
+) -> dict[str, Any]:
+    parsed = expect_object(payload, field_name)
+    actual = expect_int(
+        expect_field(parsed, "schemaVersion", f"{field_name}.schemaVersion"),
+        f"{field_name}.schemaVersion",
+        minimum=1,
+    )
+    if actual != version:
+        raise SchemaDecodeError(
+            f"{field_name}.schemaVersion",
+            f"must be {version}",
+        )
+    return parsed
+
+
+def _strip_string(value: object) -> object:
+    if isinstance(value, str):
+        return value.strip()
+    return value
+
+
+def _coerce_enum(value: object, enum_type: type[EnumT]) -> object:
+    normalized = _strip_string(value)
+    if isinstance(normalized, enum_type):
+        return normalized
+    if isinstance(normalized, str):
+        try:
+            return enum_type(normalized)
+        except ValueError:
+            return normalized
+    return normalized
+
+
+class PersistenceModel(ApiModel):
+    model_config = ConfigDict(
+        strict=True,
+        extra="ignore",
+        alias_generator=to_camel,
+        validate_by_alias=True,
+        validate_by_name=True,
+        use_enum_values=False,
+    )
+
+
+def validate_persistence_payload(
+    model_type: type[PersistenceModelT],
+    payload: object,
+    *,
+    field_name: str,
+    schema_version: int | None,
+) -> PersistenceModelT:
+    if schema_version is None:
+        parsed = expect_object(payload, field_name)
+    else:
+        parsed = expect_schema_version(payload, field_name, schema_version)
+        parsed.pop("schemaVersion", None)
+    try:
+        return model_type.model_validate(parsed)
+    except ValidationError as error:
+        raise validation_error_to_schema_decode_error(
+            error,
+            field_name=field_name,
+        ) from error
+
+
+def build_persistence_model(
+    model_type: type[PersistenceModelT],
+    /,
+    **data: Any,
+) -> PersistenceModelT:
+    return model_type.model_validate(data, by_name=True)
+
+
+class ActiveDaemonFile(PersistenceModel):
+    model_config = ConfigDict(extra="forbid")
+
+    pid: int = Field(ge=0)
+    host: str = Field(min_length=1)
+    port: int = Field(ge=1)
+    token: str = Field(min_length=1)
+    started_at: str = Field(min_length=1)
+    workspace_root: str = Field(min_length=1)
+    owner_id: str = Field(min_length=1)
+
+    @field_validator(
+        "host",
+        "token",
+        "started_at",
+        "workspace_root",
+        "owner_id",
+        mode="before",
+    )
+    @classmethod
+    def _strip_required_strings(cls, value: object) -> object:
+        return _strip_string(value)
+
+
+class RuntimeStateFile(PersistenceModel):
+    model_config = ConfigDict(extra="forbid")
+
+    status: RuntimeStatus
+    screen_sequence: int = Field(default=0, ge=0)
+    updated_at: str = Field(min_length=1)
+
+    @field_validator("status", mode="before")
+    @classmethod
+    def _strip_status(cls, value: object) -> object:
+        return _coerce_enum(value, RuntimeStatus)
+
+    @field_validator("status")
+    @classmethod
+    def _reject_restart_unsafe_ready_status(
+        cls,
+        value: RuntimeStatus,
+    ) -> RuntimeStatus:
+        if value is RuntimeStatus.READY:
+            raise ValueError("persisted runtime status cannot be ready")
+        return value
+
+    @field_validator(
+        "updated_at",
+        mode="before",
+    )
+    @classmethod
+    def _strip_required_strings(cls, value: object) -> object:
+        return _strip_string(value)

androidctld/schema/persistence_io.py

@@ -0,0 +1,41 @@
+"""File I/O helpers for JSON persistence boundaries."""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from pathlib import Path
+from typing import IO, Any
+
+
+def dump_formatted_json(handle: IO[str], payload: object) -> None:
+    json.dump(payload, handle, indent=2, sort_keys=True)
+    handle.write("\n")
+
+
+def atomic_write_json(path: Path, payload: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = path.with_name(f"{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        with temp_path.open("w", encoding="utf-8") as handle:
+            dump_formatted_json(handle, payload)
+        os.replace(temp_path, path)
+    finally:
+        try:
+            temp_path.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError:
+            pass
+
+
+def load_json_object(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        raise ValueError(str(error)) from error
+    if not isinstance(payload, dict):
+        raise ValueError("root JSON value must be an object")
+    return dict(payload)

androidctld/schema/validation_errors.py

@@ -0,0 +1,309 @@
+"""Validation error adapters for boundary models."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Sequence
+from typing import Any, cast
+
+from pydantic import ValidationError
+
+from androidctld.device.errors import DeviceBootstrapError, device_rpc_failed
+from androidctld.errors import DaemonError, bad_request
+from androidctld.schema.core import SchemaDecodeError
+
+_COMMAND_UNION_TAGS = {
+    "connect",
+    "observe",
+    "listApps",
+    "open",
+    "tap",
+    "longTap",
+    "focus",
+    "type",
+    "submit",
+    "scroll",
+    "back",
+    "home",
+    "recents",
+    "notifications",
+    "wait",
+    "screenshot",
+}
+_OPEN_TARGET_UNION_TAGS = {"app", "url"}
+_WAIT_PREDICATE_UNION_TAGS = {
+    "screen-change",
+    "text-present",
+    "gone",
+    "app",
+    "idle",
+}
+
+
+def validation_error_field_path(location: Sequence[Any]) -> str:
+    parts: list[str] = []
+    for item in location:
+        if isinstance(item, int):
+            if not parts:
+                parts.append(f"[{item}]")
+            else:
+                parts[-1] = f"{parts[-1]}[{item}]"
+            continue
+        parts.append(str(item))
+    if not parts:
+        return "root"
+    return ".".join(parts)
+
+
+def _validation_error_leaf(location: Sequence[Any]) -> str:
+    if not location:
+        return "root"
+    return str(location[-1])
+
+
+def _validation_error_container(location: Sequence[Any]) -> tuple[Any, ...]:
+    if location:
+        return tuple(location[:-1])
+    return ()
+
+
+def _prefix_field_name(field_name: str | None, field: str) -> str:
+    if field_name is None:
+        return field
+    if field == "root":
+        return field_name
+    if field.startswith("["):
+        return f"{field_name}{field}"
+    return f"{field_name}.{field}"
+
+
+def _normalize_discriminated_union_location(
+    location: Sequence[Any],
+    *,
+    error_type: str | None = None,
+    ctx: dict[str, Any] | None = None,
+) -> Sequence[Any]:
+    parts = list(location)
+    if error_type == "union_tag_invalid" and ctx is not None:
+        discriminator = ctx.get("discriminator")
+        if isinstance(discriminator, str):
+            parts.append(discriminator.strip("'"))
+
+    normalized: list[Any] = []
+    index = 0
+    while index < len(parts):
+        item = parts[index]
+        normalized.append(item)
+        if (
+            item == "command"
+            and index + 1 < len(parts)
+            and parts[index + 1] in _COMMAND_UNION_TAGS
+        ):
+            index += 2
+            continue
+        if (
+            item == "target"
+            and index + 1 < len(parts)
+            and parts[index + 1] in _OPEN_TARGET_UNION_TAGS
+        ):
+            index += 2
+            continue
+        if (
+            item == "predicate"
+            and index + 1 < len(parts)
+            and parts[index + 1] in _WAIT_PREDICATE_UNION_TAGS
+        ):
+            index += 2
+            continue
+        index += 1
+    return tuple(normalized)
+
+
+def _validation_error_problem(error_type: str, ctx: dict[str, Any] | None) -> str:
+    if error_type in {"bool_type", "bool_parsing"}:
+        return "must be a boolean"
+    if error_type in {"int_type", "int_parsing"}:
+        return "must be an integer"
+    if error_type == "is_instance_of" and ctx is not None:
+        class_name = ctx.get("class")
+        if class_name == "CommandKind":
+            return "must be a supported command kind"
+        if class_name == "RuntimeStatus":
+            return "must be a supported runtime status"
+    if error_type == "list_type":
+        return "must be a list"
+    if error_type in {"dict_type", "model_type"}:
+        return "must be a JSON object"
+    if error_type in {"string_type", "string_sub_type", "string_unicode"}:
+        return "must be a string"
+    if error_type == "value_error" and ctx is not None:
+        error = ctx.get("error")
+        if isinstance(error, ValueError):
+            return str(error)
+    if error_type == "literal_error" and ctx is not None:
+        expected = ctx.get("expected")
+        if expected == "'done', 'partial' or 'timeout'":
+            return "must be one of done|partial|timeout"
+    if error_type == "union_tag_invalid" and ctx is not None:
+        expected_tags = ctx.get("expected_tags")
+        if expected_tags == "'app', 'url'":
+            return "must be app or url"
+    if error_type == "missing":
+        return "is required"
+    if error_type == "extra_forbidden":
+        return "has unsupported fields"
+    if error_type == "greater_than_equal" and ctx is not None:
+        minimum = ctx.get("ge")
+        if isinstance(minimum, int) and not isinstance(minimum, bool):
+            return f"must be an integer >= {minimum}"
+    if error_type == "greater_than" and ctx is not None:
+        minimum = ctx.get("gt")
+        if isinstance(minimum, int) and not isinstance(minimum, bool):
+            return f"must be an integer > {minimum}"
+    if error_type == "string_too_short" and ctx is not None:
+        min_length = ctx.get("min_length")
+        if isinstance(min_length, int) and not isinstance(min_length, bool):
+            if min_length == 1:
+                return "must be a non-empty string"
+            return f"must be a string with at least {min_length} characters"
+    return "is invalid"
+
+
+def _validation_error_field(
+    location: Sequence[Any],
+    *,
+    error_type: str | None = None,
+    ctx: dict[str, Any] | None = None,
+    field_name: str | None = None,
+) -> str:
+    location = _normalize_discriminated_union_location(
+        location,
+        error_type=error_type,
+        ctx=ctx,
+    )
+    return _prefix_field_name(field_name, validation_error_field_path(location))
+
+
+def _validation_error_extra_fields(
+    errors: Sequence[Any],
+    *,
+    field_name: str | None = None,
+) -> tuple[str, list[str]] | None:
+    grouped: dict[tuple[Any, ...], list[str]] = defaultdict(list)
+    order: list[tuple[Any, ...]] = []
+    for raw_item in errors:
+        item = cast(dict[str, Any], raw_item)
+        if str(item["type"]) != "extra_forbidden":
+            continue
+        location = _normalize_discriminated_union_location(
+            cast(Sequence[Any], item["loc"])
+        )
+        container = _validation_error_container(location)
+        if container not in grouped:
+            order.append(container)
+        grouped[container].append(_validation_error_leaf(location))
+    if not grouped:
+        return None
+    chosen = min(order, key=len)  # Same-depth ties intentionally keep first seen.
+    unknown_fields = sorted(grouped[chosen])
+    return (
+        _prefix_field_name(field_name, validation_error_field_path(chosen)),
+        unknown_fields,
+    )
+
+
+def validation_error_to_schema_decode_error(
+    error: ValidationError,
+    *,
+    field_name: str | None = None,
+) -> SchemaDecodeError:
+    errors = error.errors()
+    extra_fields = _validation_error_extra_fields(errors, field_name=field_name)
+    if extra_fields is not None:
+        field, _unknown_fields = extra_fields
+        return SchemaDecodeError(field, "has unsupported fields")
+    first_error = cast(dict[str, Any], errors[0])
+    location = cast(Sequence[Any], first_error["loc"])
+    field = _validation_error_field(
+        location,
+        error_type=str(first_error["type"]),
+        ctx=first_error.get("ctx"),
+        field_name=field_name,
+    )
+    problem = _validation_error_problem(
+        str(first_error["type"]),
+        first_error.get("ctx"),
+    )
+    return SchemaDecodeError(field, problem)
+
+
+def validation_error_to_bad_request(
+    error: ValidationError,
+    *,
+    field_name: str | None = None,
+) -> DaemonError:
+    errors = error.errors()
+    extra_fields = _validation_error_extra_fields(errors, field_name=field_name)
+    if extra_fields is not None:
+        field, unknown_fields = extra_fields
+        return bad_request(
+            f"{field} has unsupported fields",
+            {
+                "field": field,
+                "unknownFields": unknown_fields,
+            },
+        )
+    first_error = cast(dict[str, Any], errors[0])
+    location = cast(Sequence[Any], first_error["loc"])
+    field = _validation_error_field(
+        location,
+        error_type=str(first_error["type"]),
+        ctx=first_error.get("ctx"),
+        field_name=field_name,
+    )
+    problem = _validation_error_problem(
+        str(first_error["type"]),
+        first_error.get("ctx"),
+    )
+    return bad_request(
+        f"{field} {problem}",
+        {"field": field},
+    )
+
+
+def validation_error_to_device_bootstrap_error(
+    error: ValidationError,
+    *,
+    field_name: str | None = None,
+    retryable: bool = False,
+) -> DeviceBootstrapError:
+    errors = error.errors()
+    extra_fields = _validation_error_extra_fields(errors, field_name=field_name)
+    if extra_fields is not None:
+        field, unknown_fields = extra_fields
+        return device_rpc_failed(
+            f"device RPC {field} has unsupported fields",
+            {
+                "field": field,
+                "reason": "invalid_payload",
+                "unknownFields": unknown_fields,
+            },
+            retryable=retryable,
+        )
+    first_error = cast(dict[str, Any], errors[0])
+    location = cast(Sequence[Any], first_error["loc"])
+    field = _validation_error_field(
+        location,
+        error_type=str(first_error["type"]),
+        ctx=first_error.get("ctx"),
+        field_name=field_name,
+    )
+    problem = _validation_error_problem(
+        str(first_error["type"]),
+        first_error.get("ctx"),
+    )
+    return device_rpc_failed(
+        f"device RPC {field} {problem}",
+        {"field": field, "reason": "invalid_payload"},
+        retryable=retryable,
+    )

androidctld/semantics/__init__.py

@@ -0,0 +1 @@
+"""Semantic screen compilation."""