unstrap 0.3.2__py3-none-win_amd64.whl

unstrap/__init__.py

@@ -0,0 +1,3 @@
+"""Unstrap: copy Garmin device data off the device over USB (MTP) and upload it."""
+
+__version__ = "0.3.2"

unstrap/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m unstrap`: what autostart registers when uvx isn't available."""
+
+import sys
+
+from unstrap.cli import main
+
+sys.exit(main())

unstrap/api.py

@@ -0,0 +1,224 @@
+"""HTTP client for the Unstrap sync API (plan §4). Retries only what is safe to retry."""
+
+from __future__ import annotations
+
+import platform
+import random
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from unstrap import __version__, trace
+from unstrap.transport import DeviceInfo, RemoteFile
+
+DEFAULT_SERVER = "https://unstrap.sweatstack.no"
+MAX_ATTEMPTS = 5
+REPORT_TIMEOUT_SECONDS = 5.0  # a failure report is best effort: never make a failure slower
+
+
+class ApiError(Exception):
+    """The server said no. `message` is meant for people and is printed as-is."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class ClientTooOld(ApiError):
+    pass
+
+
+class ServerUnreachable(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class HashedFile:
+    path: str
+    size: int
+    sha256: str
+
+    def as_json(self) -> dict[str, Any]:
+        return {"path": self.path, "size": self.size, "sha256": self.sha256}
+
+
+def user_agent(mtp_rs_version: str | None) -> str:
+    system = f"{platform.system()} {platform.machine()}".strip()
+    return f"unstrap/{__version__} ({system}; mtp-rs/{mtp_rs_version or 'none'})"
+
+
+class Api:
+    def __init__(
+        self,
+        base_url: str = DEFAULT_SERVER,
+        *,
+        agent: str | None = None,
+        client: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = client or httpx.Client(timeout=httpx.Timeout(60.0, connect=15.0))
+        self._agent = agent or user_agent(None)
+        self._sleep = sleep
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- plumbing ---------------------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        token: str | None = None,
+        json: Any = None,
+        content: bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        h = {"user-agent": self._agent, **(headers or {})}
+        if token:
+            h["authorization"] = f"Bearer {token}"
+        url = f"{self.base_url}/api/v1{path}"
+        last: Exception | None = None
+        for attempt in range(MAX_ATTEMPTS):
+            try:
+                with trace.timed(f"{method} {path}"):
+                    res = self._client.request(method, url, json=json, content=content, headers=h)
+            except httpx.TransportError as e:
+                last = e
+                self._backoff(attempt, None)
+                continue
+            if res.status_code == 429 or res.status_code >= 500:
+                last = ApiError(res.status_code, *_error(res))
+                self._backoff(attempt, res.headers.get("retry-after"))
+                continue
+            if res.status_code >= 400:
+                code, message = _error(res)
+                if res.status_code == 426:
+                    raise ClientTooOld(426, code, message)
+                raise ApiError(res.status_code, code, message)
+            try:
+                data: dict[str, Any] = res.json()
+            except ValueError as e:
+                # E.g. a captive portal or proxy answering in HTML (review M3).
+                raise ServerUnreachable(
+                    f"Unexpected answer from {self.base_url} (a Wi-Fi login page or proxy?)"
+                ) from e
+            return data
+        if isinstance(last, ApiError):
+            raise last
+        raise ServerUnreachable(f"Can't reach {self.base_url}: {last}")
+
+    def _backoff(self, attempt: int, retry_after: str | None) -> None:
+        if attempt + 1 >= MAX_ATTEMPTS:
+            return
+        if retry_after and retry_after.isdigit():
+            delay = min(float(retry_after), 60.0)
+        else:
+            delay = min(2.0**attempt, 30.0) * (0.5 + random.random() / 2)
+        self._sleep(delay)
+
+    # -- endpoints --------------------------------------------------------------------------------
+
+    def healthz(self) -> bool:
+        try:
+            res = self._client.get(f"{self.base_url}/healthz", headers={"user-agent": self._agent})
+        except httpx.TransportError:
+            return False
+        return res.status_code == 200
+
+    def start(self, device: DeviceInfo, listing: Sequence[RemoteFile]) -> dict[str, Any]:
+        dev: dict[str, Any] = {"usb_serial": device.usb_serial, "unit_id": device.unit_id}
+        if device.product:
+            dev["product"] = device.product[:100]
+        if device.firmware:
+            dev["firmware"] = device.firmware[:32]
+        body = {"device": dev, "listing": [{"path": f.path, "size": f.size} for f in listing]}
+        return self._request("POST", "/syncs", json=body)
+
+    def prove(
+        self, sync_id: int, token: str, nonce: str, proofs: list[dict[str, str]]
+    ) -> dict[str, Any]:
+        body = {"nonce": nonce, "proofs": proofs}
+        return self._request("POST", f"/syncs/{sync_id}/prove", token=token, json=body)
+
+    def check(self, sync_id: int, token: str, files: Sequence[HashedFile]) -> list[str]:
+        body = {"files": [f.as_json() for f in files]}
+        res = self._request("POST", f"/syncs/{sync_id}/check", token=token, json=body)
+        return list(res["missing"])
+
+    def put_blob(self, sync_id: int, token: str, file: HashedFile, data: bytes) -> bool:
+        headers = {
+            "unstrap-path": quote(file.path, safe=""),
+            "content-type": "application/octet-stream",
+        }
+        res = self._request(
+            "PUT",
+            f"/syncs/{sync_id}/blobs/{file.sha256}",
+            token=token,
+            content=data,
+            headers=headers,
+        )
+        return bool(res.get("stored"))
+
+    def finish(
+        self,
+        sync_id: int,
+        token: str,
+        files: Sequence[HashedFile],
+        stats: dict[str, int | str | bool],
+        errors: list[str],
+        *,
+        timings: dict[str, int] | None = None,
+        env: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "files": [f.as_json() for f in files],
+            "stats": stats,
+            "errors": errors[:100],
+        }
+        if timings:
+            body["timings"] = timings
+        if env:
+            body["env"] = env
+        return self._request("POST", f"/syncs/{sync_id}/finish", token=token, json=body)
+
+    # -- diagnostics (plan 004): one attempt, short timeout, never raises ------------------------
+
+    def report_failure(self, sync_id: int, token: str, body: dict[str, Any]) -> bool:
+        """Tell the server why this sync gave up; it ends the sync with that reason."""
+        return self._best_effort(f"/syncs/{sync_id}/report", body, token=token)
+
+    def report_error(self, body: dict[str, Any]) -> bool:
+        """An anonymous report of a failure before any sync existed."""
+        return self._best_effort("/reports", body)
+
+    def _best_effort(self, path: str, body: dict[str, Any], token: str | None = None) -> bool:
+        headers = {"user-agent": self._agent}
+        if token:
+            headers["authorization"] = f"Bearer {token}"
+        try:
+            res = self._client.post(
+                f"{self.base_url}/api/v1{path}",
+                json=body,
+                headers=headers,
+                timeout=REPORT_TIMEOUT_SECONDS,
+            )
+        except Exception:  # best effort: a report never becomes a second failure
+            return False
+        return res.status_code < 300
+
+
+def _error(res: httpx.Response) -> tuple[str, str]:
+    try:
+        err = res.json()["error"]
+        return str(err["code"]), str(err["message"])
+    except (ValueError, KeyError, TypeError):
+        return "http_error", f"Server returned HTTP {res.status_code}."

unstrap/autostart.py

@@ -0,0 +1,375 @@
+"""`unstrap autostart`: run `unstrap listen` in the background at login.
+
+macOS: a LaunchAgent (launchd), restarted if it crashes. Linux: a systemd user service, likewise.
+Windows (plan 003): the current user's Run key (no admin; listed in Task Manager > Startup apps),
+running pythonw.exe so no console window opens, and started right away. Everything that touches
+the system (commands, home directory, uid, PATH lookups, registry, processes) is injected, so
+tests touch none of it.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import re
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Callable, Iterator, Mapping
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path, PureWindowsPath
+from typing import Protocol
+
+from unstrap import __version__
+from unstrap.api import DEFAULT_SERVER
+from unstrap.console import NO_WINDOW
+from unstrap.install import WINDOWS_INSTALL_COMMAND, from_uvx  # uvx envs can be cleaned away
+
+LABEL = "no.sweatstack.unstrap"
+SERVICE = "unstrap.service"
+BOOTOUT_WAIT_SECONDS = 10.0
+LINGER_HINT = (
+    "This needs a systemd user session. On a headless machine or over SSH, run "
+    "`loginctl enable-linger $USER` first."
+)
+
+RUN_KEY = r"Software\Microsoft\Windows\CurrentVersion\Run"
+RUN_VALUE = "Unstrap"
+
+Runner = Callable[[list[str]], subprocess.CompletedProcess[str]]
+
+
+class AutostartError(Exception):
+    pass
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        cmd, capture_output=True, text=True, timeout=60, check=False, creationflags=NO_WINDOW
+    )
+
+
+class Registry(Protocol):
+    """The one registry value autostart owns on Windows: HKCU\\...\\Run\\Unstrap."""
+
+    def get(self) -> str | None: ...
+    def set(self, command: str) -> None: ...
+    def delete(self) -> None: ...
+
+
+class RunKey:
+    """The real HKCU Run key (Windows only)."""
+
+    def get(self) -> str | None:
+        if sys.platform != "win32":
+            return None
+        import winreg  # noqa: PLC0415 (Windows-only module)
+
+        try:
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, RUN_KEY) as key:
+                value, _kind = winreg.QueryValueEx(key, RUN_VALUE)
+                return str(value)
+        except OSError:
+            return None
+
+    def set(self, command: str) -> None:
+        if sys.platform != "win32":
+            raise AutostartError("The Run key exists on Windows only.")
+        import winreg  # noqa: PLC0415
+
+        with winreg.CreateKey(winreg.HKEY_CURRENT_USER, RUN_KEY) as key:
+            winreg.SetValueEx(key, RUN_VALUE, 0, winreg.REG_SZ, command)
+
+    def delete(self) -> None:
+        if sys.platform != "win32":
+            return
+        import winreg  # noqa: PLC0415
+
+        try:
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, RUN_KEY, 0, winreg.KEY_SET_VALUE) as key:
+                winreg.DeleteValue(key, RUN_VALUE)
+        except FileNotFoundError:
+            pass
+
+
+def _spawn(cmd: list[str]) -> None:
+    """Start a process that outlives us, with no console window (Windows)."""
+    flags = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
+        subprocess, "CREATE_NEW_PROCESS_GROUP", 0
+    )
+    subprocess.Popen(
+        cmd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        close_fds=True,
+        creationflags=flags | NO_WINDOW,
+    )
+
+
+@dataclass
+class System:
+    """The bits of the OS autostart uses; the defaults are the real ones."""
+
+    name: str  # platform.system(): "Darwin", "Linux", ...
+    home: Path = field(default_factory=Path.home)
+    uid: int = field(default_factory=lambda: os.getuid() if hasattr(os, "getuid") else -1)
+    which: Callable[[str], str | None] = shutil.which
+    run: Runner = _run
+    executable: str = sys.executable
+    prefix: str = sys.prefix  # this Python environment
+    sleep: Callable[[float], None] = time.sleep
+    env: Mapping[str, str] = field(default_factory=lambda: dict(os.environ))
+    registry: Registry = field(default_factory=RunKey)
+    spawn: Callable[[list[str]], None] = _spawn
+    pid: int = field(default_factory=os.getpid)
+
+
+def is_pinned(cmd: list[str]) -> bool:
+    """Whether `cmd` (from listen_command) runs a PyPI version through uvx."""
+    return len(cmd) > 1 and cmd[1].startswith("unstrap==")
+
+
+def listen_command(
+    system: System, *, server: str, device: str | None, notify: bool = True
+) -> list[str]:
+    """What the OS runs: this very environment's Python, unless that is a throwaway uvx one.
+    Then uvx, pinned to this version so it keeps working from uv's cache, offline; after an
+    upgrade, `uvx unstrap@latest autostart` registers the new version. (Only from uvx: a dev
+    or unreleased build pinned like that would fetch a different release from PyPI.)"""
+    if system.name == "Windows":
+        if from_uvx(system.prefix):
+            # uvx's environment can be cleaned away, and uvx.exe opens a console window.
+            raise AutostartError(
+                f"On Windows, install Unstrap first (Windows key + R, then paste):\n  "
+                f"{WINDOWS_INSTALL_COMMAND}"
+            )
+        # pythonw.exe: the same environment's Python without a console window.
+        pythonw = str(PureWindowsPath(system.executable).with_name("pythonw.exe"))
+        cmd = [pythonw, "-m", "unstrap", "listen"]
+        return _with_options(cmd, server=server, device=device, notify=notify)
+    uvx = system.which("uvx") if from_uvx(system.prefix) else None
+    if uvx:
+        cmd = [os.path.abspath(uvx), f"unstrap=={__version__}", "listen"]
+    else:
+        cmd = [system.executable, "-m", "unstrap", "listen"]
+    return _with_options(cmd, server=server, device=device, notify=notify)
+
+
+def _with_options(cmd: list[str], *, server: str, device: str | None, notify: bool) -> list[str]:
+    if server.rstrip("/") != DEFAULT_SERVER:
+        cmd += ["--server", server]
+    if device:
+        cmd += ["--device", device]
+    if not notify:
+        cmd.append("--no-notify")
+    return cmd
+
+
+def plist_path(system: System) -> Path:
+    return system.home / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+
+
+def unit_path(system: System) -> Path:
+    return system.home / ".config" / "systemd" / "user" / SERVICE
+
+
+def log_path(system: System) -> Path:
+    if system.name == "Windows":
+        return data_dir(system) / "unstrap.log"
+    return system.home / "Library" / "Logs" / "unstrap.log"
+
+
+def data_dir(system: System) -> Path:
+    """Windows: %LOCALAPPDATA%\\Unstrap (the background listener's log and pid file)."""
+    local = system.env.get("LOCALAPPDATA") or str(system.home / "AppData" / "Local")
+    return Path(local) / "Unstrap"
+
+
+def pid_path(system: System) -> Path:
+    return data_dir(system) / "listen.pid"
+
+
+@contextmanager
+def recorded(system: System) -> Iterator[None]:
+    """While `listen` runs on Windows, its pid is on file, so autostart can stop it (before an
+    update, or with --off). Elsewhere launchd and systemd do that job."""
+    if system.name != "Windows":
+        yield
+        return
+    path = pid_path(system)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(str(system.pid))
+    try:
+        yield
+    finally:
+        try:
+            if path.read_text().strip() == str(system.pid):
+                path.unlink()
+        except OSError:
+            pass
+
+
+def stop_listener(system: System) -> bool:
+    """Stop the background listener recorded in the pid file, if it is still running.
+
+    Windows locks a running program's files, so the installer must stop it before updating.
+    Only a Python process is stopped: after a reboot the recorded pid may belong to anything.
+    """
+    path = pid_path(system)
+    try:
+        pid = int(path.read_text().strip())
+    except (OSError, ValueError):
+        return False
+    stopped = False
+    try:
+        found = system.run(["tasklist", "/FI", f"PID eq {pid}", "/FO", "CSV", "/NH"])
+        if "python" in found.stdout.lower():
+            system.run(["taskkill", "/PID", str(pid), "/F"])
+            system.sleep(1.0)  # let Windows release the files
+            stopped = True
+    except (OSError, subprocess.SubprocessError):
+        pass
+    path.unlink(missing_ok=True)
+    return stopped
+
+
+def launch_agent(cmd: list[str], log: Path) -> bytes:
+    return plistlib.dumps(
+        {
+            "Label": LABEL,
+            "ProgramArguments": cmd,
+            "RunAtLoad": True,
+            "KeepAlive": True,
+            "ProcessType": "Background",
+            "StandardOutPath": str(log),
+            "StandardErrorPath": str(log),
+        }
+    )
+
+
+def systemd_unit(cmd: list[str]) -> str:
+    return (
+        "[Unit]\n"
+        "Description=Unstrap: sync Garmin devices when they are connected\n"
+        "\n"
+        "[Service]\n"
+        f"ExecStart={' '.join(_systemd_quote(a) for a in cmd)}\n"
+        "Restart=on-failure\n"
+        "RestartSec=10\n"
+        "\n"
+        "[Install]\n"
+        "WantedBy=default.target\n"
+    )
+
+
+def _systemd_quote(arg: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9_./=:@+,-]+", arg):
+        arg = '"' + arg.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    # systemd expands %specifiers and $VARIABLES in ExecStart; keep them literal.
+    return arg.replace("%", "%%").replace("$", "$$")
+
+
+def installed(system: System) -> str | None:
+    """Where autostart is registered (the LaunchAgent, unit file or Run key), if it is."""
+    if system.name == "Windows":
+        return f"HKCU\\{RUN_KEY}\\{RUN_VALUE}" if system.registry.get() else None
+    path = {"Darwin": plist_path, "Linux": unit_path}.get(system.name)
+    if path is None:
+        return None
+    p = path(system)
+    return str(p) if p.is_file() else None
+
+
+def enable(system: System, cmd: list[str]) -> list[str]:
+    """Install and start; returns lines to show the user."""
+    if system.name == "Darwin":
+        plist, log = plist_path(system), log_path(system)
+        plist.parent.mkdir(parents=True, exist_ok=True)
+        log.parent.mkdir(parents=True, exist_ok=True)
+        plist.write_bytes(launch_agent(cmd, log))
+        _call(system, ["launchctl", "bootout", f"gui/{system.uid}/{LABEL}"], check=False)
+        _wait_until_unloaded(system)  # bootout is asynchronous; bootstrap fails while it runs
+        _call(system, ["launchctl", "bootstrap", f"gui/{system.uid}", str(plist)])
+        return [f"Installed {plist}", f"Logs: {log}"]
+    if system.name == "Linux":
+        unit = unit_path(system)
+        unit.parent.mkdir(parents=True, exist_ok=True)
+        unit.write_text(systemd_unit(cmd))
+        try:
+            _call(system, ["systemctl", "--user", "daemon-reload"])
+            _call(system, ["systemctl", "--user", "enable", SERVICE])
+            # restart, not start: re-running autostart after an upgrade replaces the old process.
+            _call(system, ["systemctl", "--user", "restart", SERVICE])
+        except AutostartError as e:
+            unit.unlink(missing_ok=True)  # half-installed must not look "on" (doctor)
+            raise AutostartError(f"{e}\n{LINGER_HINT}") from e
+        return [f"Installed {unit}", "Logs: journalctl --user -u unstrap"]
+    if system.name == "Windows":
+        stop_listener(system)  # re-running autostart (e.g. after an update) replaces it
+        system.registry.set(subprocess.list2cmdline(cmd))
+        system.spawn(cmd)  # now, not only from the next login
+        return [
+            "Starts at login: Task Manager > Startup apps > Unstrap",
+            f"Logs: {log_path(system)}",
+        ]
+    raise AutostartError(f"Autostart isn't supported on {system.name or 'this system'}.")
+
+
+def disable(system: System) -> list[str]:
+    """Stop and remove; fine if it was never installed."""
+    if system.name == "Darwin":
+        plist = plist_path(system)
+        _call(system, ["launchctl", "bootout", f"gui/{system.uid}/{LABEL}"], check=False)
+        return [_remove(plist)]
+    if system.name == "Linux":
+        unit = unit_path(system)
+        _call(system, ["systemctl", "--user", "disable", "--now", SERVICE], check=False)
+        line = _remove(unit)
+        _call(system, ["systemctl", "--user", "daemon-reload"])
+        return [line]
+    if system.name == "Windows":
+        stopped = stop_listener(system)
+        was = system.registry.get() is not None
+        system.registry.delete()
+        if was:
+            return ["Removed Unstrap from the startup apps."]
+        return ["Stopped the running listener." if stopped else "Autostart was not installed."]
+    raise AutostartError(f"Autostart isn't supported on {system.name or 'this system'}.")
+
+
+def _wait_until_unloaded(system: System) -> None:
+    waited = 0.0
+    while waited < BOOTOUT_WAIT_SECONDS and _succeeds(
+        system, ["launchctl", "print", f"gui/{system.uid}/{LABEL}"]
+    ):
+        system.sleep(0.5)
+        waited += 0.5
+
+
+def _succeeds(system: System, cmd: list[str]) -> bool:
+    try:
+        return system.run(cmd).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def _remove(path: Path) -> str:
+    if not path.exists():
+        return "Autostart was not installed."
+    path.unlink()
+    return f"Removed {path}"
+
+
+def _call(system: System, cmd: list[str], *, check: bool = True) -> None:
+    try:
+        res = system.run(cmd)
+    except (OSError, subprocess.SubprocessError) as e:
+        if check:
+            raise AutostartError(f"Can't run {cmd[0]}: {e}") from e
+        return
+    if check and res.returncode != 0:
+        detail = (res.stderr or res.stdout or "").strip() or f"exit code {res.returncode}"
+        raise AutostartError(f"{' '.join(cmd)} failed: {detail}")