mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/sim/registry.py

@@ -0,0 +1,161 @@
+"""The simulators Mobster created (`simulators.json`) and their port slots; one missing from it is never touched."""
+
+import contextlib
+import errno
+import fcntl
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from ..devices import listening
+from .models import SimError
+
+REGISTRY = "simulators.json"
+LOCK = "simulators.lock"
+FIELDS = ("udid", "name", "device_type", "runtime", "wda_port", "mjpeg_port", "created_at", "last_used_at")
+LOCK_TIMEOUT = 30.0
+LOCK_POLL = .05
+
+DEFAULT_PORT_BASE = 8310
+MJPEG_OFFSET = 1000
+SLOTS = 40
+# Never these: the USB iPhone's relay (8100, 9100), the Mac app's API (8765), and the ranges the benchmark
+# simulators use (8200–8299 and their MJPEG 9200–9299).
+RESERVED = frozenset({8100, 8765, 9100, *range(8200, 8300), *range(9200, 9300)})
+
+
+def now():
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+class Registry:
+    def __init__(self, data_dir):
+        self.data_dir = Path(data_dir)
+        self.path = self.data_dir / REGISTRY
+        self.lock_path = self.data_dir / LOCK
+
+    @contextlib.contextmanager
+    def locked(self, timeout=LOCK_TIMEOUT):
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self.lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+        try:
+            end = time.monotonic() + timeout
+            while True:
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except OSError as exc:
+                    if exc.errno not in (errno.EWOULDBLOCK, errno.EAGAIN) or time.monotonic() >= end:
+                        raise SimError("busy", f"Another Mobster process has held {self.lock_path} for "
+                                               f"{timeout:g} s.", "Wait for it to finish, then try again.") from None
+                    time.sleep(LOCK_POLL)
+            yield
+        finally:
+            os.close(fd)  # closing the descriptor releases the lock
+
+    def read(self):
+        # a damaged file is an error, never an empty list: a forgotten UDID leaves its simulator behind for good
+        try:
+            text = self.path.read_text()
+        except FileNotFoundError:
+            return []
+        try:
+            data = json.loads(text)
+            entries = data["simulators"] if isinstance(data, dict) else None
+            if not isinstance(entries, list) or not all(isinstance(entry, dict) and entry.get("udid")
+                                                        for entry in entries):
+                raise ValueError
+        except (ValueError, KeyError, TypeError):
+            raise SimError("simulator", f"{self.path} is damaged, so Mobster can't tell which simulators "
+                                        "are its own.",
+                           "Delete Mobster's simulators in Xcode (their names start with “Mobster · ”), then "
+                           f"remove {self.path}.") from None
+        return [normalize(entry) for entry in entries]
+
+    def write(self, entries):
+        """Replace the file atomically. Call it under ``locked()``."""
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps({"version": 1, "simulators": [normalize(entry) for entry in entries]},
+                             indent=2, ensure_ascii=False) + "\n"
+        fd, temporary = tempfile.mkstemp(prefix=".simulators.", suffix=".json", dir=self.data_dir)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as stream:
+                stream.write(payload)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, self.path)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                os.unlink(temporary)
+            raise
+
+    @contextlib.contextmanager
+    def edit(self):
+        """Read, let the caller change the list in place, and write it back if it changed, all under the lock."""
+        with self.locked():
+            entries = self.read()
+            before = json.dumps(entries, sort_keys=True)
+            yield entries
+            if json.dumps(entries, sort_keys=True) != before:
+                self.write(entries)
+
+
+def normalize(entry):
+    """Exactly the registry's fields, in order."""
+    return {field: entry.get(field) for field in FIELDS}
+
+
+# -- ports -------------------------------------------------------------------------------------------------
+
+def port_base(environ=None):
+    """$MOBSTER_SIM_PORT_BASE, default 8310."""
+    environ = os.environ if environ is None else environ
+    text = str(environ.get("MOBSTER_SIM_PORT_BASE") or "").strip()
+    if not text:
+        return DEFAULT_PORT_BASE
+    try:
+        base = int(text)
+    except ValueError:
+        base = -1
+    if not 1024 <= base <= 65535 - MJPEG_OFFSET - SLOTS:
+        raise SimError("environment", f"MOBSTER_SIM_PORT_BASE is {text!r}; it must be a port from 1024 to "
+                                      f"{65535 - MJPEG_OFFSET - SLOTS}.", "Unset it to use 8310.")
+    return base
+
+
+def slot_ports(base, slot):
+    """(WebDriverAgent port, MJPEG port) of a slot: base + slot, and that plus 1000."""
+    wda = base + slot
+    return wda, wda + MJPEG_OFFSET
+
+
+def allowed(wda, mjpeg):
+    return wda not in RESERVED and mjpeg not in RESERVED and 1024 <= wda and mjpeg <= 65535
+
+
+def free_slot(base, taken=(), busy=listening):
+    taken = set(taken)
+    for slot in range(SLOTS):
+        wda, mjpeg = slot_ports(base, slot)
+        if not allowed(wda, mjpeg) or wda in taken or mjpeg in taken:
+            continue
+        if busy(wda) or busy(mjpeg):
+            continue
+        return wda, mjpeg
+    last = slot_ports(base, SLOTS - 1)[0]
+    raise SimError("simulator", f"Every port from {base} to {last} is in use or reserved, so there is no "
+                                "room for another simulator's WebDriverAgent.",
+                   "Delete unused ones with `mobster sim prune`, or set MOBSTER_SIM_PORT_BASE to a free range.")
+
+
+def taken_ports(entries, skip_udid=None):
+    ports = set()
+    for entry in entries:
+        if entry.get("udid") == skip_udid:
+            continue
+        for key in ("wda_port", "mjpeg_port"):
+            if entry.get(key):
+                ports.add(int(entry[key]))
+    return ports

mobile_agent/sim/simctl.py

@@ -0,0 +1,269 @@
+"""`xcrun simctl`: running it, and read-only parsers for its JSON (`simctl list -j`)."""
+
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, NamedTuple, Optional
+
+from .models import SimError
+
+NAME_PREFIX = "Mobster · "
+XCRUN = "/usr/bin/xcrun"
+PNG_HEAD, PNG_TAIL = b"\x89PNG\r\n\x1a\n", b"IEND\xaeB`\x82"  # the signature, and the IEND chunk's type and CRC
+DONE_POLL = 0.05
+DEFAULT_DEVICE_TYPES = ("iPhone 17 Pro", "iPhone 16 Pro", "iPhone 15 Pro")
+DOWNLOAD_RUNTIME = "xcodebuild -downloadPlatform iOS"
+
+
+class Result(NamedTuple):
+    code: Optional[int]   # None: the command could not run, or timed out
+    out: str
+    err: str
+
+    @property
+    def ok(self):
+        return self.code == 0
+
+    @property
+    def timed_out(self):
+        return self.code is None and "did not finish in" in (self.err or "")
+
+    def last_line(self):
+        """The last non-empty line of stderr, else stdout: what a person needs from a failed command."""
+        for text in (self.err, self.out):
+            lines = [line.strip() for line in (text or "").splitlines() if line.strip()]
+            if lines:
+                return lines[-1][:300]
+        return ""
+
+
+def run(argv, timeout=60, env=None, done: Optional[Callable[[], bool]] = None):
+    # `simctl io screenshot` can wait 30 s on CoreSimulatorService after writing its file: `done` ends it early
+    if done is not None:
+        return _run_until(argv, timeout, env, done)
+    try:
+        completed = subprocess.run([str(part) for part in argv], capture_output=True, text=True, timeout=timeout,
+                                   env=env, stdin=subprocess.DEVNULL)
+    except subprocess.TimeoutExpired:
+        return Result(None, "", f"{argv[0]} did not finish in {timeout:g} s")
+    except (OSError, subprocess.SubprocessError) as exc:
+        return Result(None, "", f"{argv[0]} could not run: {exc}")
+    return Result(completed.returncode, completed.stdout or "", completed.stderr or "")
+
+
+def _run_until(argv, timeout, env, done):
+    try:
+        process = subprocess.Popen([str(part) for part in argv], stdin=subprocess.DEVNULL,
+                                   stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, env=env)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return Result(None, "", f"{argv[0]} could not run: {exc}")
+    deadline = time.monotonic() + timeout
+    try:
+        while True:
+            code = process.poll()
+            if done():
+                return Result(0, "", "")
+            if code is not None:
+                return Result(code, "", process.stderr.read().decode("utf-8", "replace"))
+            if time.monotonic() >= deadline:
+                return Result(None, "", f"{argv[0]} did not finish in {timeout:g} s")
+            time.sleep(DONE_POLL)
+    finally:
+        if process.poll() is None:
+            process.kill()
+            process.wait()
+        process.stderr.close()
+
+
+def whole_png(path):
+    """Whether ``path`` holds a complete PNG: the signature at the start and the IEND chunk at the end."""
+    try:
+        with open(path, "rb") as file:
+            if file.read(len(PNG_HEAD)) != PNG_HEAD:
+                return False
+            file.seek(-len(PNG_TAIL), os.SEEK_END)
+            return file.read() == PNG_TAIL
+    except OSError:
+        return False
+
+
+def screenshot(udid, path, *, timeout=30, env=None, runner=run):
+    path = Path(path)
+    path.unlink(missing_ok=True)
+    result = runner([XCRUN, "simctl", "io", str(udid), "screenshot", "--type=png", str(path)], timeout=timeout,
+                    env=env, done=lambda: whole_png(path))
+    return result if not result.ok or whole_png(path) else Result(1, "", "simctl wrote no whole PNG")
+
+
+@dataclass(frozen=True)
+class Runtime:
+    identifier: str
+    name: str              # "iOS 26.4"
+    version: tuple         # (26, 4)
+    available: bool
+    device_types: tuple    # names of the device types it supports; empty when simctl does not say
+
+
+@dataclass(frozen=True)
+class DeviceType:
+    identifier: str
+    name: str              # "iPhone 17 Pro"
+    family: str            # "iPhone"
+    min_runtime: int       # simctl's packed minimum runtime version
+
+
+@dataclass(frozen=True)
+class Device:
+    udid: str
+    name: str
+    state: str             # "Shutdown", "Booted", "Booting", "Shutting Down", "Creating"
+    runtime: str           # the runtime identifier it belongs to
+    device_type: str       # the device type identifier
+
+
+def version_tuple(text):
+    """ "26.4" -> (26, 4); anything unreadable sorts first."""
+    parts = re.findall(r"\d+", str(text or ""))
+    return tuple(int(part) for part in parts) or (0,)
+
+
+def parse_runtimes(data):
+    """iOS runtimes from `simctl list runtimes -j` (or the whole `simctl list -j`)."""
+    runtimes = []
+    for item in (data or {}).get("runtimes") or ():
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or "")
+        platform = str(item.get("platform") or name.split(" ")[0])
+        if platform != "iOS":
+            continue
+        supported = tuple(str(entry.get("name")) for entry in item.get("supportedDeviceTypes") or ()
+                          if isinstance(entry, dict) and entry.get("name"))
+        runtimes.append(Runtime(identifier=str(item.get("identifier") or ""), name=name,
+                                version=version_tuple(item.get("version") or name),
+                                available=bool(item.get("isAvailable")), device_types=supported))
+    return runtimes
+
+
+def parse_device_types(data):
+    types = []
+    for item in (data or {}).get("devicetypes") or ():
+        if not isinstance(item, dict) or not item.get("name"):
+            continue
+        family = str(item.get("productFamily") or str(item["name"]).split(" ")[0])
+        try:
+            minimum = int(item.get("minRuntimeVersion") or 0)
+        except (TypeError, ValueError):
+            minimum = 0
+        types.append(DeviceType(identifier=str(item.get("identifier") or ""), name=str(item["name"]),
+                                family=family, min_runtime=minimum))
+    return types
+
+
+def parse_devices(data):
+    """Every simulator in the default device set, from `simctl list devices -j`."""
+    devices = []
+    for runtime, items in ((data or {}).get("devices") or {}).items():
+        for item in items or ():
+            if not isinstance(item, dict) or not item.get("udid"):
+                continue
+            devices.append(Device(udid=str(item["udid"]), name=str(item.get("name") or ""),
+                                  state=str(item.get("state") or ""), runtime=str(runtime),
+                                  device_type=str(item.get("deviceTypeIdentifier") or "")))
+    return devices
+
+
+def _same(a, b):
+    return " ".join(str(a).split()).casefold() == " ".join(str(b).split()).casefold()
+
+
+def choose_runtime(runtimes, wanted=None):
+    available = sorted((runtime for runtime in runtimes if runtime.available), key=lambda runtime: runtime.version)
+    if not available:
+        from .. import states
+        raise SimError("environment", states.row("no_runtime").message, DOWNLOAD_RUNTIME)
+    if not wanted:
+        return available[-1]
+    text = str(wanted).strip()
+    for runtime in reversed(available):
+        if _same(runtime.name, text) or runtime.identifier == text or _same("iOS " + text, runtime.name):
+            return runtime
+    number = re.sub(r"(?i)^ios\s*", "", text)
+    if re.fullmatch(r"\d+(\.\d+)*", number):
+        prefix = version_tuple(number)
+        for runtime in reversed(available):
+            if runtime.version[:len(prefix)] == prefix:
+                return runtime
+    names = ", ".join(runtime.name for runtime in reversed(available))
+    raise SimError("environment", f"{text} isn't installed. Installed: {names}.", DOWNLOAD_RUNTIME)
+
+
+def supported(device_type, runtime):
+    return not runtime.device_types or device_type.name in runtime.device_types
+
+
+def choose_device_type(device_types, runtime, wanted=None):
+    if wanted:
+        text = str(wanted).strip()
+        match = next((kind for kind in device_types if _same(kind.name, text) or kind.identifier == text), None)
+        if match is None:
+            iphones = [kind.name for kind in device_types
+                       if kind.name.startswith("iPhone") and supported(kind, runtime)]
+            raise SimError("environment", f"{text} isn't a simulator device type in this Xcode. Try one of: "
+                           f"{', '.join(iphones[:6]) or 'none'}.",
+                           "See every type with: xcrun simctl list devicetypes")
+        if not supported(match, runtime):
+            raise SimError("environment", f"{match.name} doesn't run {runtime.name}.",
+                           f"Pick another device, or install its runtime: {DOWNLOAD_RUNTIME}")
+        return match
+    usable = [kind for kind in device_types if kind.name.startswith("iPhone") and supported(kind, runtime)]
+    for name in DEFAULT_DEVICE_TYPES:
+        match = next((kind for kind in usable if kind.name == name), None)
+        if match:
+            return match
+    if not usable:
+        raise SimError("environment", f"No iPhone device type runs {runtime.name}.", DOWNLOAD_RUNTIME)
+    newest = max(kind.min_runtime for kind in usable)
+    return next(kind for kind in usable if kind.min_runtime == newest)
+
+
+def sim_name(device_type, runtime, taken=()):
+    """ "Mobster · iPhone 17 Pro · iOS 26.4", then " · 2", " · 3" … for more of the same pair."""
+    base = f"{NAME_PREFIX}{device_type} · {runtime}"
+    taken = set(taken)
+    if base not in taken:
+        return base
+    number = 2
+    while f"{base} · {number}" in taken:
+        number += 1
+    return f"{base} · {number}"
+
+
+def is_mobster_name(name):
+    return str(name or "").startswith(NAME_PREFIX)
+
+
+UDID = re.compile(r"^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$")
+
+
+def parse_created(out):
+    """The UDID `simctl create` prints, or None."""
+    text = (out or "").strip().upper()
+    return text if UDID.match(text) else None
+
+
+def parse_groups(out):
+    """[(group id, path)] from `simctl get_app_container <udid> <bundle> groups`."""
+    groups = []
+    for line in (out or "").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        slash = line.find("/")
+        if slash < 0:
+            continue
+        groups.append((line[:slash].strip(), line[slash:].strip()))
+    return groups