devicectl-core 0.1.0__py3-none-any.whl

devicectl/web/agents.py

@@ -0,0 +1,94 @@
+"""Reading a browser's user agent into something a person can act on.
+
+The link pill counts the browsers on the event stream; this is what tells
+"my other tab" from "someone else on the network holding the device".  Two
+tabs of one browser share an address and a user agent, so what can be said
+is coarse -- which is fine, because the question being answered is only
+whether the other watcher is me.
+
+None of this is a security control.  A user agent is a stranger's header,
+so it is read for a label and never trusted: :func:`name_watchers` drops
+anything unprintable, because those lines are printed to a terminal.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Enough of a user-agent reading to tell two browsers on the same machine
+# apart, in the order that matters: Edge and Opera both claim Chrome, Chrome
+# claims Safari, and every Android is also a Linux.
+_BROWSERS = (
+    ("Edg/", "Edge"),
+    ("OPR/", "Opera"),
+    ("Firefox/", "Firefox"),
+    ("Chrome/", "Chrome"),
+    ("Safari/", "Safari"),
+    ("curl/", "curl"),
+)
+_SYSTEMS = (
+    ("Android", "Android"),
+    ("iPhone", "iPhone"),
+    ("iPad", "iPad"),
+    ("Windows", "Windows"),
+    ("Macintosh", "macOS"),
+    ("CrOS", "ChromeOS"),
+    ("X11", "Linux"),
+    ("Linux", "Linux"),
+)
+
+# How much of an unrecognised user agent is worth showing.
+AGENT_SNIPPET = 40
+
+# Addresses not worth naming: a tab on this machine is the ordinary case.
+LOOPBACK = ("127.0.0.1", "::1", "localhost")
+
+
+def describe_agent(agent: str) -> str:
+    """Return a short name for a browser ("Firefox on Linux")."""
+    if not agent.strip():
+        return "unknown client"
+    browser = next((name for token, name in _BROWSERS if token in agent), "")
+    system = next((name for token, name in _SYSTEMS if token in agent), "")
+    if browser and system:
+        return f"{browser} on {system}"
+    return browser or system or agent.split()[0][:AGENT_SNIPPET]
+
+
+def client_json(client: dict[str, Any]) -> dict[str, Any]:
+    """One watching browser, with its user agent read into something short."""
+    return {
+        "id": client.get("id"),
+        "address": client.get("address") or "",
+        "port": client.get("port"),
+        "agent": client.get("agent") or "",
+        "label": describe_agent(str(client.get("agent") or "")),
+        "since": client.get("since"),
+    }
+
+
+def name_watchers(clients: list[dict[str, Any]]) -> list[str]:
+    """Name the browsers on the stream: one line each, oldest first.
+
+    Two tabs of one browser share a user agent and an address, so they are
+    counted together rather than listed twice.  A watcher somewhere else on
+    the network is named with the address it came from, which is the part
+    that tells it from a tab of my own.  The user agent is a stranger's
+    header and these lines are printed to a terminal, so anything
+    unprintable in it is dropped.
+    """
+    counted: dict[str, int] = {}
+    for client in clients:
+        label = describe_agent(str(client.get("agent") or ""))
+        address = str(client.get("address") or "")
+        if address and address not in LOOPBACK:
+            label = f"{label} at {address}"
+        label = "".join(ch for ch in label if ch.isprintable())
+        counted[label] = counted.get(label, 0) + 1
+    return [
+        f"{label} ({count} tabs)" if count > 1 else label
+        for label, count in counted.items()
+    ]
+
+
+__all__ = ["LOOPBACK", "client_json", "describe_agent", "name_watchers"]

devicectl/web/events.py

@@ -0,0 +1,171 @@
+"""Fan-out of backend events to every connected browser.
+
+One :class:`Broadcaster` per server.  Anything worth telling the UI about --
+the state of the link, a fresh reading, a job's progress -- is published
+here, and every open ``/api/events`` stream gets a copy.  Publishers never
+block: each subscriber owns a bounded queue, and a subscriber that cannot
+keep up loses its oldest events rather than stalling the worker that owns
+the device.
+
+Some events describe *state* rather than an occurrence (the link is idle,
+the reading is this).  Those are published as ``sticky``: the broadcaster
+remembers the latest one per name and replays them to a new subscriber, so a
+browser that connects (or reconnects) sees the current world immediately
+instead of waiting for something to change.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+from dataclasses import dataclass
+from typing import Any
+
+# How many events one slow subscriber may fall behind before it starts
+# losing the oldest ones.  A browser reading a local socket is never this
+# far behind unless it has stopped reading altogether.
+MAX_QUEUED_EVENTS = 256
+
+# How long a stream waits for an event before writing an SSE comment, so a
+# connection that died without a FIN is noticed rather than held forever.
+HEARTBEAT_INTERVAL_S = 15.0
+
+
+@dataclass(frozen=True)
+class Event:
+    """One thing that happened, addressed to every listening browser."""
+
+    name: str
+    data: dict[str, Any]
+    seq: int
+
+
+class Subscription:
+    """One browser's view of the event stream."""
+
+    def __init__(
+        self,
+        broadcaster: "Broadcaster",
+        backlog: list[Event],
+        client: dict[str, Any] | None = None,
+    ) -> None:
+        """Start a subscription pre-loaded with the current sticky state."""
+        self._broadcaster = broadcaster
+        self._queue: queue.Queue[Event | None] = queue.Queue(MAX_QUEUED_EVENTS)
+        self._closed = False
+        self.client: dict[str, Any] = dict(client or {})
+        """Who is on the other end -- see :meth:`Broadcaster.clients`."""
+        for event in backlog:
+            self._offer(event)
+
+    def _offer(self, event: Event | None) -> None:
+        """Queue an event, dropping the oldest if this subscriber lags."""
+        try:
+            self._queue.put_nowait(event)
+        except queue.Full:
+            try:
+                self._queue.get_nowait()  # drop the oldest, keep the newest
+            except queue.Empty:  # pragma: no cover - another thread drained it
+                pass
+            try:
+                self._queue.put_nowait(event)
+            except queue.Full:  # pragma: no cover - refilled in between
+                pass
+
+    def get(self, timeout: float = HEARTBEAT_INTERVAL_S) -> Event | None:
+        """Wait for the next event; None on timeout or once closed."""
+        try:
+            return self._queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def close(self) -> None:
+        """Stop the subscription and wake a reader blocked in :meth:`get`."""
+        if not self._closed:
+            self._closed = True
+            self._broadcaster.unsubscribe(self)
+            self._offer(None)
+
+    @property
+    def closed(self) -> bool:
+        """Whether this subscription has been closed."""
+        return self._closed
+
+    def __enter__(self) -> "Subscription":
+        """Allow use as a context manager, so streams always unsubscribe."""
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        """Close the subscription on the way out."""
+        self.close()
+
+
+class Broadcaster:
+    """Publishes events to every open subscription."""
+
+    def __init__(self) -> None:
+        """Start with no subscribers and no remembered state."""
+        self._lock = threading.Lock()
+        self._subscribers: set[Subscription] = set()
+        self._sticky: dict[str, Event] = {}
+        self._seq = 0
+        self._clients = 0
+
+    def publish(self, name: str, data: dict[str, Any], *, sticky: bool = False) -> None:
+        """Send one event to every subscriber (and remember it, if sticky)."""
+        with self._lock:
+            self._seq += 1
+            event = Event(name=name, data=data, seq=self._seq)
+            if sticky:
+                self._sticky[name] = event
+            subscribers = list(self._subscribers)
+        for subscriber in subscribers:
+            subscriber._offer(event)
+
+    def subscribe(self, client: dict[str, Any] | None = None) -> Subscription:
+        """Open a subscription, pre-loaded with the latest sticky events.
+
+        ``client`` describes who opened it -- address, browser, when -- and
+        is handed back by :meth:`clients` so the UI can say who else is
+        watching rather than only how many.
+        """
+        with self._lock:
+            backlog = [self._sticky[name] for name in sorted(self._sticky)]
+            self._clients += 1
+            described = {"id": str(self._clients), **(client or {})}
+            subscription = Subscription(self, backlog, described)
+            self._subscribers.add(subscription)
+            return subscription
+
+    def clients(self) -> list[dict[str, Any]]:
+        """Describe every browser currently listening, oldest connection first."""
+        with self._lock:
+            watchers = [dict(s.client) for s in self._subscribers if s.client]
+        return sorted(watchers, key=lambda c: (c.get("since") or 0, c.get("id") or ""))
+
+    def unsubscribe(self, subscription: Subscription) -> None:
+        """Forget a subscription (called by :meth:`Subscription.close`)."""
+        with self._lock:
+            self._subscribers.discard(subscription)
+
+    def sticky(self, name: str) -> dict[str, Any] | None:
+        """Return the latest remembered event of one name, if any."""
+        with self._lock:
+            event = self._sticky.get(name)
+            return dict(event.data) if event else None
+
+    @property
+    def subscriber_count(self) -> int:
+        """How many browsers are currently listening."""
+        with self._lock:
+            return len(self._subscribers)
+
+    def shutdown(self) -> None:
+        """Close every subscription, ending all open streams."""
+        with self._lock:
+            subscribers = list(self._subscribers)
+        for subscriber in subscribers:
+            subscriber.close()
+
+
+__all__ = ["HEARTBEAT_INTERVAL_S", "Broadcaster", "Event", "Subscription"]

devicectl/web/http.py

@@ -0,0 +1,243 @@
+"""The pieces of HTTP the API handlers actually touch.
+
+The server itself is :mod:`http.server` and the handlers are plain functions,
+so what sits between them is small: a parsed request, a reply ready to write,
+a routing entry that says whether an endpoint changes anything, one
+exception carrying the status to answer with, and a way to say what a
+request was for a recording to keep.
+
+None of it is a framework.  It exists so that a handler is a function of
+``(context, request) -> response`` and can be called directly from a test
+without a socket.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Generic, TypeVar
+from urllib.parse import parse_qs
+
+from devicectl.errors import DeviceError
+
+# The context a handler is given is the program's own -- what it holds is
+# entirely up to the program -- so the routing table is generic over it and
+# the shared server never looks inside.
+CtxT = TypeVar("CtxT")
+
+# Every status either half of the transport answers with, in one place: the
+# server module had grown its own copy of three of these, and a program that
+# wants to say 404 should not have to know which of the two to ask.
+HTTP_OK = 200
+HTTP_SEE_OTHER = 303
+HTTP_BAD_REQUEST = 400
+HTTP_FORBIDDEN = 403
+HTTP_NOT_FOUND = 404
+HTTP_METHOD_NOT_ALLOWED = 405
+HTTP_CONFLICT = 409
+HTTP_PAYLOAD_TOO_LARGE = 413
+HTTP_SERVER_ERROR = 500
+HTTP_UNAVAILABLE = 503
+
+# Query-string spellings of "yes".  Anything else, including an empty value,
+# is false: `?force` alone is not an assertion that force is wanted.
+TRUTHY = ("1", "true", "yes", "on")
+
+
+class ApiError(DeviceError):
+    """A request that cannot be served, with the status to answer."""
+
+    def __init__(self, status: int, message: str) -> None:
+        """Record the HTTP status alongside the message."""
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+@dataclass
+class Request:
+    """One parsed HTTP request."""
+
+    method: str
+    path: str
+    query: dict[str, str] = field(default_factory=dict)
+    body: bytes = b""
+
+    def json(self) -> dict[str, Any]:
+        """Parse the body as a JSON object."""
+        if not self.body:
+            return {}
+        try:
+            doc = json.loads(self.body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise ApiError(HTTP_BAD_REQUEST, f"malformed JSON body: {exc}") from None
+        if not isinstance(doc, dict):
+            raise ApiError(HTTP_BAD_REQUEST, "expected a JSON object")
+        return doc
+
+    def param(self, name: str, default: str = "") -> str:
+        """One query-string parameter."""
+        return self.query.get(name, default)
+
+    def flag(self, name: str, default: bool = False) -> bool:
+        """One query-string parameter read as a boolean."""
+        raw = self.query.get(name)
+        if raw is None:
+            return default
+        return raw.strip().lower() in TRUTHY
+
+
+@dataclass
+class Response:
+    """One reply, ready to write."""
+
+    status: int = 200
+    body: bytes = b""
+    content_type: str = "application/json; charset=utf-8"
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+def ok(payload: Any, status: int = 200) -> Response:
+    """Render a JSON reply.
+
+    ``default=str`` is the last resort for a value no schema function
+    converted -- a ``datetime`` or an ``Enum`` that reached here intact.
+    Rendering it as its own text is a worse answer than the right type but a
+    much better one than a 500 in the middle of a page.
+    """
+    return Response(
+        status=status, body=json.dumps(payload, default=str).encode("utf-8")
+    )
+
+
+@dataclass(frozen=True)
+class Route(Generic[CtxT]):
+    """One endpoint: what runs it, and whether it changes anything.
+
+    Generic over the context so a program's routing table is checked against
+    the context its own handlers take, while the server that dispatches it
+    never needs to know what that is.
+    """
+
+    handler: Callable[[CtxT, Request], Response]
+    write: bool = False
+    """Refused outright when the server was started ``--read-only``."""
+
+    raw_body: bool = False
+    """Takes an uploaded file rather than JSON."""
+
+
+# How much of a request body a recording keeps.  Long enough for every
+# settings change a page sends in one go, short enough that a mistyped
+# upload does not become the report.
+MAX_RECORDED_BODY = 1000
+
+
+def describe_call(
+    request: Request, status: int | None = None, error: str = ""
+) -> tuple[str, str]:
+    """Say what a request was, and how it went, for a recording to keep.
+
+    Two calls per request rather than one: the arriving request, with its
+    body, goes in before the work starts, and the outcome goes in after it,
+    so a recording reads in the order things happened -- what was asked,
+    what that put on the wire, and what came back to the page.  ``status``
+    of ``None`` is the first of those.
+
+    Returns the one-line headline and the body beneath it, which is empty
+    for the outcome: repeating the payload under the answer would double
+    every request in the report.
+    """
+    where = request.path
+    if request.query:
+        where += "?" + "&".join(f"{k}={v}" for k, v in request.query.items())
+    head = f"{request.method} {where}"
+    if status is None:
+        return head, _body(request.body)
+    return f"{head}  ->  {status}" + (f"  {error}" if error else ""), ""
+
+
+def _body(raw: bytes) -> str:
+    """Render a request body as something a person can read, or describe it.
+
+    An uploaded firmware image is a megabyte of nothing anybody can read and
+    is said to be that; JSON is re-rendered rather than passed through, so a
+    page that sends one long line is not one long line here.
+    """
+    if not raw:
+        return ""
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return f"({len(raw)} bytes, not text)"
+    try:
+        text = json.dumps(json.loads(text), indent=2)
+    except json.JSONDecodeError:
+        pass
+    if len(text) > MAX_RECORDED_BODY:
+        return text[:MAX_RECORDED_BODY] + f"\n... ({len(raw)} bytes in all)"
+    return text
+
+
+def parse_query(raw: str) -> dict[str, str]:
+    """Flatten a query string to the last value of each parameter."""
+    return {k: v[-1] for k, v in parse_qs(raw, keep_blank_values=True).items()}
+
+
+def spool(
+    req: Request,
+    *,
+    max_bytes: int,
+    prefix: str,
+    suffix: str = "",
+    too_large: str = "that file is larger than anything this takes",
+) -> Path:
+    """Write an uploaded body to a temporary file, for code that wants a path.
+
+    The uploaded name is kept where the browser sent one, because a firmware
+    image or a settings export is often identified by it; ``suffix`` names
+    the extension to give a file that arrived without one.  The file goes in
+    a directory of its own so :func:`discard` can remove both without
+    guessing what else is in there.
+    """
+    if not req.body:
+        raise ApiError(HTTP_BAD_REQUEST, "no file content was uploaded")
+    if len(req.body) > max_bytes:
+        raise ApiError(HTTP_PAYLOAD_TOO_LARGE, too_large)
+    name = Path(req.param("filename", "upload")).name or "upload"
+    directory = Path(tempfile.mkdtemp(prefix=prefix))
+    path = directory / (name if Path(name).suffix else name + suffix)
+    path.write_bytes(req.body)
+    return path
+
+
+def discard(path: Path) -> None:
+    """Remove a spooled upload and the directory it was written into."""
+    shutil.rmtree(path.parent, ignore_errors=True)
+
+
+__all__ = [
+    "HTTP_BAD_REQUEST",
+    "HTTP_CONFLICT",
+    "HTTP_FORBIDDEN",
+    "HTTP_METHOD_NOT_ALLOWED",
+    "HTTP_NOT_FOUND",
+    "HTTP_OK",
+    "HTTP_PAYLOAD_TOO_LARGE",
+    "HTTP_SEE_OTHER",
+    "HTTP_SERVER_ERROR",
+    "HTTP_UNAVAILABLE",
+    "MAX_RECORDED_BODY",
+    "ApiError",
+    "Request",
+    "Response",
+    "Route",
+    "describe_call",
+    "discard",
+    "ok",
+    "parse_query",
+    "spool",
+]

devicectl/web/progress.py

@@ -0,0 +1,101 @@
+"""A long operation's progress, turned into events for the browser.
+
+The terminal draws a bar per phase, but a browser gets one bar per job, and
+the work behind it usually comes in parts of very different length: a
+download, then a transfer, then whatever the device does on its own once it
+has the file.  Each part gets a slice of the one bar, so it keeps moving
+instead of sitting at 100% for three minutes.
+
+The slices are guesses about duration and nothing depends on them being
+right.  A program with only one phase leaves :class:`Phases` alone and the
+transfer fills the bar.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from devicectl.report import Reporter, Wait
+from devicectl.web.worker import Job
+
+
+@dataclass(frozen=True)
+class Phases:
+    """Where each part of a long job ends, on the one bar the page draws."""
+
+    sending_ends: float = 1.0
+    """Where the transfer finishes.  Below 1.0 leaves room for a wait."""
+
+    waiting_ends: float = 1.0
+    """Where the wait for the device finishes, leaving the last sliver for
+    whatever confirms the operation actually took."""
+
+
+ONE_PHASE = Phases()
+
+
+class JobReporter(Reporter):
+    """Report a long operation's progress onto a :class:`Job`.
+
+    ``start`` is where the transfer begins on the bar -- 0 when the file was
+    uploaded, further along when it had to be fetched first.  Warnings are
+    kept as well as shown, because the job's result is what the browser has
+    left to look at once the run is over.
+    """
+
+    def __init__(
+        self,
+        job: Job,
+        *,
+        start: float = 0.0,
+        phases: Phases = ONE_PHASE,
+        unit: str = "",
+    ) -> None:
+        """Report onto ``job``, with the transfer starting at ``start``.
+
+        ``unit`` names what is being counted -- "block", "page" -- and turns
+        the transfer into a countable line ("block 12 of 340") beside the
+        bar.  Left empty, the bar moves and says nothing, which is right
+        where the count is bytes and the bar already says it.
+        """
+        self.job = job
+        self.start = start
+        self.phases = phases
+        self.unit = unit
+        self.warnings: list[str] = []
+
+    def step(self, message: str) -> None:
+        """Show the new phase as the job's message."""
+        self.job.report(message=message, force=True)
+
+    def detail(self, message: str) -> None:
+        """Show a detail as the job's message; the browser has one line."""
+        self.job.report(message=message, force=True)
+
+    def warn(self, message: str) -> None:
+        """Show a warning and keep it for the job's result."""
+        self.warnings.append(message)
+        self.job.report(message=f"Warning: {message}", force=True)
+
+    def sending(self, sent: int, total: int, elapsed_s: float, label: str = "") -> None:
+        """Move the bar across the transfer's slice."""
+        span = self.phases.sending_ends - self.start
+        counted = f"{self.unit} {sent} of {total}" if self.unit else None
+        self.job.report(self.start + span * (sent / total if total else 1.0), counted)
+
+    def waiting(self, wait: Wait) -> None:
+        """Move the bar across the waiting slice, by elapsed time."""
+        self.job.report(self._waiting_progress(wait))
+
+    def polled(self, wait: Wait) -> None:
+        """Move the bar, and say what the device last answered."""
+        self.job.report(self._waiting_progress(wait), wait.label)
+
+    def _waiting_progress(self, wait: Wait) -> float:
+        """Map elapsed waiting time onto the waiting slice of the bar."""
+        span = self.phases.waiting_ends - self.phases.sending_ends
+        done = min(wait.elapsed_s / wait.deadline_s, 1.0) if wait.deadline_s else 1.0
+        return self.phases.sending_ends + span * done
+
+
+__all__ = ["ONE_PHASE", "JobReporter", "Phases"]