meshbench 0.0.5__py3-none-any.whl

meshbench/__init__.py

@@ -0,0 +1,157 @@
+"""Drive a MeshBench workbench from Python.
+
+    from meshbench import Workbench
+
+    with Workbench.headless(fixture="fife-strict", seed=9001) as wb:
+        wb.sim.run(timedelta(minutes=5))
+        print(wb.provenance())
+        print(wb.events.total(), "events")
+
+Two layers. `wb.call(verb, params)` is the whole API and stays public, so a
+verb this package has not shaped is one line away rather than a blocker; above
+it sit `wb.nodes`, `wb.sim`, `wb.firmware`, `wb.events`, `wb.project`,
+`wb.live` and a node's own console.
+
+Every wait is a method - `node.wait_running()`, `sim.run()`,
+`firmware.wait_started()` - never a sleep in a script. They poll today and will
+subscribe later, and no script changes when they do.
+
+A wait measured in simulated time is not a wait measured in yours:
+`sim.run(minutes=5)` is five minutes of the mesh's own clock, and on 155
+emulated nodes that is a great deal longer than five of yours.
+"""
+
+from ._socket import (
+    BINARY_ENV,
+    PROTOCOL,
+    RENDEZVOUS_ENV,
+    SOCKET_ENV,
+    default_address,
+    default_socket_path,
+)
+from .boundary import Boundary
+from .checks import Assertions, Check, Report, Schedule
+from .device import Device
+from .errors import (
+    BadParams,
+    Closing,
+    Conflict,
+    MeshbenchError,
+    NotFound,
+    ProtocolMismatch,
+    Refused,
+    Timeout,
+    Unavailable,
+    UnknownVerb,
+    VersionMismatch,
+)
+from .live import DEFAULT_WINDOW, Live
+from .nodes import Node, Nodes
+from .pairing import paired_release, pairing_note, release
+from .parts import Console, Events, Firmware, Job, Project, Sim
+from .sessions import SESSIONS_ENV, Session, sessions, sessions_dir
+from .sets import (
+    DEFAULT_PRESET,
+    Board,
+    Class,
+    Kind,
+    Preset,
+    Role,
+    Strategy,
+    Tab,
+    Transport,
+)
+from .subscribe import Notification, Subscription, subscribe
+from .types import (
+    Aimed,
+    Antenna,
+    Build,
+    BuildDetails,
+    CardSlot,
+    Event,
+    Hello,
+    ImportPreview,
+    JobInfo,
+    NameMatch,
+    NodeInfo,
+    NodeStat,
+    Provenance,
+    Screen,
+    Shot,
+    SimState,
+)
+from .workbench import Workbench
+
+__all__ = [
+    "SESSIONS_ENV",
+    "Session",
+    "sessions",
+    "sessions_dir",
+    "Schedule",
+    "BINARY_ENV",
+    "Boundary",
+    "Transport",
+    "Tab",
+    "Strategy",
+    "Role",
+    "Class",
+    "Live",
+    "DEFAULT_WINDOW",
+    "ImportPreview",
+    "NameMatch",
+    "Report",
+    "Preset",
+    "Kind",
+    "DEFAULT_PRESET",
+    "Check",
+    "Board",
+    "Device",
+    "Assertions",
+    "PROTOCOL",
+    "RENDEZVOUS_ENV",
+    "SOCKET_ENV",
+    "BadParams",
+    "Build",
+    "BuildDetails",
+    "Aimed",
+    "Antenna",
+    "CardSlot",
+    "Closing",
+    "Conflict",
+    "Console",
+    "Event",
+    "Events",
+    "Firmware",
+    "Hello",
+    "Job",
+    "JobInfo",
+    "MeshbenchError",
+    "Node",
+    "NodeInfo",
+    "NodeStat",
+    "Nodes",
+    "NotFound",
+    "Project",
+    "ProtocolMismatch",
+    "Provenance",
+    "Refused",
+    "Sim",
+    "Screen",
+    "Shot",
+    "SimState",
+    "Timeout",
+    "Unavailable",
+    "UnknownVerb",
+    "VersionMismatch",
+    "paired_release",
+    "pairing_note",
+    "release",
+    "Notification",
+    "Subscription",
+    "subscribe",
+    "Workbench",
+    "default_address",
+    "default_socket_path",
+]
+
+__version__ = "0.0.5"

meshbench/_socket.py

@@ -0,0 +1,247 @@
+"""The wire: one JSON request per line, one reply.
+
+Everything above this is shape. This is the whole protocol, and it is small on
+purpose - a client that needed a framework to speak to a local socket would be
+a client nobody could debug.
+
+Two transports, because one does not travel:
+
+- A **unix socket**, where the operating system has one. The filesystem is the
+  access control, and the kernel enforces it.
+- **Loopback TCP with a token**, where it does not. Windows is the case:
+  CPython has never exposed ``socket.AF_UNIX`` there, so a unix socket is not
+  merely awkward from Python on Windows, it is unreachable. The workbench binds
+  127.0.0.1 on an ephemeral port and writes the address and a 128-bit token to
+  a 0600 file; this reads that file and presents the token before anything
+  else. Any local process can open a loopback port, so the token is what stands
+  where the kernel stood.
+
+The choice is by operating system, not by language, so the Go client and this
+one always speak the same thing on the same machine.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import socket
+import sys
+import threading
+from pathlib import Path
+from typing import Any
+
+from .pairing import release
+
+#: Chooses where the workbench answers: a path, or "tcp", or "tcp:host:port".
+SOCKET_ENV = "MESHBENCH_CONTROL_SOCKET"
+
+#: What to run when a client is asked to start a workbench and nothing named a
+#: binary. A checkout has one built but not installed, and every example and
+#: every test then needs the same three lines to find it - so the variable the
+#: test harness already used is honoured by the clients too.
+BINARY_ENV = "MESHBENCH_BINARY"
+
+#: Chooses the file a TCP listener writes its address and token to. Per user by
+#: default, which is wrong for two runs at once - the second would overwrite the
+#: first's - so a client that starts a workbench gives it one of its own.
+RENDEZVOUS_ENV = "MESHBENCH_CONTROL_RENDEZVOUS"
+
+#: The wire version this client speaks. A workbench answering anything else is
+#: refused at connect rather than halfway through a script.
+PROTOCOL = 1
+
+#: The shortest sun_path any platform we run on allows: 108 on Linux, 104 on
+#: macOS and the BSDs.
+MAX_UNIX_PATH = 104
+
+#: Whether this Python can speak to a unix socket at all.
+HAVE_AF_UNIX = hasattr(socket, "AF_UNIX")
+
+
+def _cache_dir() -> Path:
+    """The per-user directory this OS already defines.
+
+    What os.getuid() was standing in for, less portably - it does not exist on
+    Windows at all, so the old default crashed there before it could be wrong.
+    """
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+    elif sys.platform == "darwin":
+        base = os.path.expanduser("~/Library/Caches")
+    else:
+        base = os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache")
+    d = Path(base) / "meshbench"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def rendezvous_path() -> Path:
+    """Where a TCP listener leaves its address and token."""
+    named = os.environ.get(RENDEZVOUS_ENV)
+    if named:
+        p = Path(named)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        return p
+    return _cache_dir() / "control.json"
+
+
+def default_address() -> str:
+    """Where a workbench answers on this operating system unless told otherwise."""
+    env = os.environ.get(SOCKET_ENV)
+    if env:
+        return env
+    if sys.platform == "win32" or not HAVE_AF_UNIX:
+        return "tcp"
+    # Linux keeps exactly the path it has always had: scripts
+    # and tools/soak all name it, and moving it would break them for no gain.
+    runtime = os.environ.get("XDG_RUNTIME_DIR")
+    if runtime:
+        return os.path.join(runtime, "meshbench.sock")
+    # Everywhere else, the per-user cache directory - which on macOS is also
+    # short enough to stay inside sun_path, where $TMPDIR would not be.
+    return str(_cache_dir() / "control.sock")
+
+
+#: Kept for callers written against the old name, which meant the same thing
+#: while a unix socket was the only thing there was.
+default_socket_path = default_address
+
+
+def _read_rendezvous() -> tuple[str, str]:
+    path = rendezvous_path()
+    try:
+        got = json.loads(path.read_text())
+    except OSError as e:
+        raise ConnectionError(f"no workbench has left an address at {path}: {e}") from e
+    except ValueError as e:
+        raise ConnectionError(f"{path} is not readable as an address: {e}") from e
+    return got.get("address", ""), got.get("token", "")
+
+
+def _connect(
+    address: str, timeout: float | None, token: str = ""
+) -> tuple[socket.socket, str]:
+    """Open the socket the address names, and return it with any token.
+
+    A caller that already holds the token says so. That is how a row from
+    sessions() is connected to: two TCP workbenches share one per-user
+    rendezvous file and the second overwrites the first, so the token beside
+    the address in the session's own file is the only one that is certainly
+    its own.
+    """
+    if address == "tcp" or address.startswith("tcp:"):
+        if address == "tcp":
+            host_port, found = _read_rendezvous()
+            token = token or found
+        else:
+            host_port = address[len("tcp:") :]
+            if ":" not in host_port:
+                host_port = "127.0.0.1:" + host_port
+            # A port somebody named still needs the token, and without one in
+            # hand the rendezvous file is the only place it exists.
+            if not token:
+                _, token = _read_rendezvous()
+        host, _, port = host_port.rpartition(":")
+        s = socket.create_connection((host or "127.0.0.1", int(port)), timeout=timeout)
+        return s, token
+
+    path = address[len("unix:") :] if address.startswith("unix:") else address
+    if not HAVE_AF_UNIX:
+        raise ConnectionError(
+            f"{sys.platform} has no unix socket this Python can open, and "
+            f"{path} is one. Start the workbench with -control-socket tcp"
+        )
+    if len(path) > MAX_UNIX_PATH:
+        raise ConnectionError(
+            f"{path} is {len(path)} bytes and a unix socket path may be at "
+            f"most {MAX_UNIX_PATH} - choose a shorter one, or use tcp"
+        )
+    s = socket.socket(socket.AF_UNIX)
+    s.settimeout(timeout)
+    s.connect(path)
+    return s, ""
+
+
+class Connection:
+    """One socket, and the lock that keeps two threads from interleaving.
+
+    The protocol has request ids but the workbench answers in order, so the
+    simplest correct thing is one call at a time. A client that pipelined would
+    have to demultiplex, and nothing here needs the throughput.
+    """
+
+    def __init__(
+        self,
+        address: str | None = None,
+        timeout: float | None = 300.0,
+        token: str = "",
+    ):
+        self.address = address or default_address()
+        self._sock, token = _connect(self.address, timeout, token)
+        self._file = self._sock.makefile("rb")
+        self._lock = threading.Lock()
+        self._next_id = 0
+        if token:
+            # The token first, before anything else on the wire. A loopback
+            # port is reachable by any local process, so this is what stands in
+            # for the permissions a unix socket would have had. The wire
+            # version rides along, so a workbench that cannot speak to this
+            # client says so at the door, and the release beside it so one that
+            # was never meant to be driven by this client says so too.
+            line = {"token": token, "protocol": PROTOCOL, "release": release()}
+            self._sock.sendall((json.dumps(line) + "\n").encode())
+
+    def call(self, verb: str, params: Any = None) -> dict[str, Any]:
+        """Send one verb and return the whole reply, errors included."""
+        with self._lock:
+            self._next_id += 1
+            req: dict[str, Any] = {"id": self._next_id, "method": verb}
+            if self._next_id == 1:
+                # A unix socket has no line of its own to declare the wire
+                # version on, so it goes on the first request: refused there,
+                # before any verb runs, rather than found out from a verb
+                # behaving oddly. Only the first, because the answer cannot
+                # change while the connection is open. The release travels with
+                # it: a client and the workbench it drives must be the same one.
+                req["protocol"] = PROTOCOL
+                req["release"] = release()
+            if params is not None:
+                req["params"] = params
+            self._sock.sendall((json.dumps(req) + "\n").encode())
+            line = self._file.readline()
+            if not line:
+                raise ConnectionError(
+                    f"the workbench at {self.address} closed the connection"
+                )
+            return json.loads(line.decode())
+
+    def shutdown(self) -> None:
+        """Break a read in progress so a streaming reader on another thread can
+        be closed. A plain close would deadlock: readline holds the buffer's
+        lock while it blocks on the socket, and close wants that same lock. A
+        socket shutdown makes the blocked read return instead, and then close is
+        uncontended. Errors are ignored - the socket may already be gone.
+        """
+        with contextlib.suppress(OSError):
+            self._sock.shutdown(socket.SHUT_RDWR)
+
+    def close(self) -> None:
+        try:
+            self._file.close()
+        finally:
+            self._sock.close()
+
+
+def is_live(address: str, token: str = "") -> bool:
+    """Whether something is already answering there.
+
+    A connect rather than a stat: a socket file existing says nothing about
+    whether anybody is behind it, and that difference is the whole question.
+    """
+    try:
+        s, _ = _connect(address, 0.25, token)
+        s.close()
+        return True
+    except (OSError, ConnectionError, ValueError):
+        return False

meshbench/boundary.py

@@ -0,0 +1,124 @@
+"""The study area: which nodes are in the question being asked.
+
+Not the firmware's region concept. A boundary decides what is *studied*; a
+region decides what is *forwarded*. Both words are in this application and
+confusing them is how somebody concludes the RF model is broken.
+
+Set it before importing. The import filters at fetch time, so a boundary set
+afterwards prunes what has already been paid for rather than never fetching it.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from . import errors
+
+if TYPE_CHECKING:  # pragma: no cover - import for typing only
+    from .workbench import Workbench
+
+
+class Boundary:
+    """The study area, however you have it. Live."""
+
+    def __init__(self, wb: Workbench) -> None:
+        self._wb = wb
+
+    def use(self, area: str | Path, name: str = "") -> list[str]:
+        """Take a study area from a place name or from GeoJSON.
+
+        The one to call. A path to a .geojson file is loaded; anything else is
+        searched for by name and the best match accepted. Both end with the
+        area in the study, which is the only thing the caller wanted to say.
+
+        ``name`` renames a single loaded polygon, so a file called
+        ``export(3).geojson`` can still join the study as "Tay catchment".
+        """
+        if _is_a_file(area):
+            return self.load(area, name=name)
+        return [self.accept(self.search(str(area))[0])]
+
+    def search(self, query: str) -> list[str]:
+        """Places matching a name, best first. Needs the network.
+
+        Returns names rather than geometry: the geometry stays at the
+        workbench, and the name is what accept takes.
+        """
+        got = self._wb.call("boundary.set", {"query": query}) or {}
+        found = got.get("names") or []
+        if not found:
+            raise errors.NotFound(
+                "boundary.set", f"nothing is called {query!r}", "not_found"
+            )
+        return found
+
+    def accept(self, name: str) -> str:
+        """Take one of the search results into the study area.
+
+        Areas union rather than replace: a study is often two council areas
+        rather than one.
+        """
+        got = self._wb.call("boundary.accept", {"name": name}) or {}
+        return got.get("accepted", name)
+
+    def load(self, source: str | Path | dict, name: str = "") -> list[str]:
+        """Take a study area from GeoJSON: a path, a document, or a dict.
+
+        A Polygon, a MultiPolygon, a Feature or a FeatureCollection. Each
+        polygon becomes an area named from its ``name`` property, or from
+        ``name``, or from the file.
+
+        The one way to study an area nothing has an administrative name for -
+        a catchment, a valley, the bit north of the river - and the only one
+        that works with no network at all.
+        """
+        params: dict = {}
+        if isinstance(source, dict):
+            params["geojson"] = json.dumps(source)
+        elif _is_a_file(source):
+            params["path"] = str(source)
+        else:
+            params["geojson"] = str(source)
+        if name:
+            params["name"] = name
+        got = self._wb.call("boundary.load", params) or {}
+        return got.get("loaded") or []
+
+    def list(self) -> list[str]:
+        """What the study area is made of."""
+        return (self._wb.call("boundary.list") or {}).get("names") or []
+
+    def remove(self, name: str) -> None:
+        """Take one area back out.
+
+        Changes what is measured, never what is loaded: the nodes stay until
+        something prunes them.
+        """
+        self._wb.call("boundary.remove", {"name": name})
+
+    def prune(self, margin_km: float | None = None) -> int:
+        """Delete the nodes outside the study area, and say how many went.
+
+        For a mesh that was imported before the boundary was set. The margin is
+        kept on purpose: a node just outside still interferes with one just
+        inside, and dropping it makes the inside look quieter than it is.
+        """
+        params = {} if margin_km is None else {"margin_km": margin_km}
+        return (self._wb.call("boundary.prune", params) or {}).get("removed", 0)
+
+
+def _is_a_file(x: object) -> bool:
+    """A path, rather than a place name or a GeoJSON document.
+
+    Judged by extension as well as by existence, so a mistyped path is reported
+    as a missing file rather than searched for as a place - which answers
+    "nothing is called ./bounds/fife.geojson" and sends the reader looking in
+    entirely the wrong direction.
+    """
+    if isinstance(x, Path):
+        return True
+    if not isinstance(x, str) or x.lstrip().startswith("{"):
+        return False
+    return x.endswith((".geojson", ".json")) or Path(x).is_file()