muxplex-deck 0.5.2__tar.gz → 0.5.3__tar.gz

{muxplex_deck-0.5.2 → muxplex_deck-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: muxplex-deck
-Version: 0.5.2
+Version: 0.5.3
 Summary: Hardware probe/diagnostic app for the Elgato Stream Deck+ (seed of the muxplex sidecar)
 Author: Amplifier
 Author-email: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>

{muxplex_deck-0.5.2 → muxplex_deck-0.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "muxplex-deck"
-version = "0.5.2"
+version = "0.5.3"
 description = "Hardware probe/diagnostic app for the Elgato Stream Deck+ (seed of the muxplex sidecar)"
 readme = "README.md"
 authors = [

{muxplex_deck-0.5.2 → muxplex_deck-0.5.3}/src/muxplex_deck/cli.py

@@ -593,6 +593,60 @@ def check_server_reachable(server_url: str, ca_file: Path | None) -> tuple[str,
         return "warn", f"Server check failed: {exc}"
 
 
+def check_federation_key_auth(
+    server_url: str, federation_key: str, *, verify: bool | str = True
+) -> tuple[str, str]:
+    """Issue ONE authenticated request to confirm `federation_key` is actually accepted.
+
+    `/api/instance-info` (what `check_server_reachable`/`fetch_instance_info`
+    call) is unauthenticated by design on the server -- it proves TLS and
+    reachability, but nothing about a credential. That gap is exactly what
+    let `init` once print a green "Server reachable" check, write config,
+    and offer to install the service for a federation key that was simply
+    wrong -- the user only found out once the running service couldn't
+    authenticate (see AGENTS.md).
+
+    This hits `GET /api/sessions` instead: authenticated, read-only, the
+    same lightweight endpoint the sidecar's own active loop already polls
+    (see `main.py`), with the key sent as `Authorization: Bearer` -- the
+    exact scheme the muxplex server's `auth.py` checks. Returns one of:
+
+      ("ok", ...)      -- HTTP 200: the key is accepted.
+      ("fail", ...)     -- HTTP 401: the key is definitively rejected.
+                           Callers must not save a key that gets this back.
+      ("warn", ...)     -- anything else (timeout, connection error,
+                           unexpected status): could not verify one way or
+                           the other. This is NOT evidence the key is bad --
+                           callers must not print a false success, but also
+                           must not treat an unrelated network hiccup as a
+                           rejected key.
+    """
+    import httpx
+
+    url = f"{server_url.rstrip('/')}/api/sessions"
+    headers = {"Authorization": f"Bearer {federation_key}"}
+    try:
+        with httpx.Client(verify=verify, timeout=5.0) as client:
+            resp = client.get(url, headers=headers)
+    except httpx.TimeoutException as exc:
+        return (
+            "warn",
+            f"Could not verify federation key -- server check timed out: {exc}",
+        )
+    except httpx.ConnectError as exc:
+        return "warn", f"Could not verify federation key -- server unreachable: {exc}"
+    except Exception as exc:  # noqa: BLE001 -- verification must degrade to warn, never raise
+        return "warn", f"Could not verify federation key: {exc}"
+
+    if resp.status_code == 200:
+        return "ok", "Federation key accepted by server"
+    if resp.status_code == 401:
+        return "fail", "Federation key rejected by server (401 Unauthorized)"
+    return "warn", (
+        f"Could not verify federation key -- unexpected response HTTP {resp.status_code}"
+    )
+
+
 def check_service_status() -> tuple[str, str]:
     """Service-state check: not installed / installed but not running / running.
 
@@ -629,6 +683,13 @@ _CHECK_MARKS: dict[str, str] = {
     "ok": "\033[32m\u2713\033[0m",
     "fail": "\033[31m\u2717\033[0m",
     "warn": "\033[33m!\033[0m",
+    # Distinct from "warn": "warn" means a check RAN and found something to
+    # flag; "unknown" means the check could not be run at all yet (e.g. the
+    # currently-running process hasn't published a status write of its own
+    # yet). Conflating the two is what let a dying process's stale-but-
+    # recent status snapshot get reported as definite failures right after
+    # `service restart` -- see AGENTS.md's restart-race incident.
+    "unknown": "\033[36m?\033[0m",
 }
 
 
@@ -789,7 +850,7 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
     fall back to a direct probe -- this keeps `status` useful even before
     the service has ever been installed.
     """
-    from .service import service_is_active
+    from .service import service_is_active, service_main_pid
     from .statusfile import read_status
 
     running = service_is_active()
@@ -825,13 +886,44 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
 
     if data is None:
         print_check(
-            "warn",
+            "unknown",
             "No status file found even though the service is running -- it "
             "may have just started. Try: muxplex-deck service logs",
         )
         print()
         return 0
 
+    # Is this snapshot from the process running RIGHT NOW, or from a
+    # PREVIOUS incarnation? Age alone can't tell: a process that's about to
+    # be replaced (e.g. by `service restart`) can write its LAST status
+    # moments before exiting, so it still looks "fresh" by age even though
+    # it no longer reflects reality -- exactly the restart-race incident in
+    # AGENTS.md (2 false failures reported from a dying process's stale-but-
+    # recent write). Comparing the recorded pid to the service manager's own
+    # live MainPID is the reliable signal; fall back to the age check only
+    # when the live pid can't be determined at all (unsupported platform,
+    # command failure).
+    current_pid = service_main_pid()
+    recorded_pid = data.get("pid")
+    if current_pid is not None:
+        is_current = recorded_pid == current_pid
+    else:
+        is_current = (
+            time.time() - data.get("updated_at", 0)
+        ) <= _STATUS_STALE_THRESHOLD_SECONDS
+
+    if not is_current:
+        print_check(
+            "unknown",
+            f"Status not yet available for the running process (pid "
+            f"{current_pid if current_pid is not None else '?'}) -- the "
+            f"published status is from a previous run (pid {recorded_pid}). "
+            "This is expected right after (re)starting; try again in a "
+            "moment, or: muxplex-deck service logs",
+        )
+        print()
+        return 0
+
     age = time.time() - data.get("updated_at", 0)
     if age > _STATUS_STALE_THRESHOLD_SECONDS:
         print_check(

{muxplex_deck-0.5.2 → muxplex_deck-0.5.3}/src/muxplex_deck/init_wizard.py

@@ -207,10 +207,24 @@ def _resolve_ca(
 def _resolve_federation_key(
     key_file_path: Path,
     *,
+    server_url: str,
+    ca_file: str | None,
     non_interactive: bool,
     input_func: Callable[[str], str],
     getpass_func: Callable[[str], str],
 ) -> None:
+    """Resolve, VALIDATE, and write the federation key.
+
+    A pasted/loaded key is never written on faith. `/api/instance-info`
+    (already used above to verify the server) is unauthenticated and proves
+    nothing about a credential -- this is exactly the gap that let `init`
+    once print a green "Server reachable" check, write config, and offer to
+    install the service for a federation key that was simply wrong; the
+    user only found out once the running service couldn't authenticate
+    (see AGENTS.md). `cli.check_federation_key_auth` issues one real
+    authenticated request and this loops until it's accepted, or the user
+    gives up (Ctrl-C/EOF, handled by `run_init`'s caller).
+    """
     if key_file_path.exists() and key_file_path.stat().st_size > 0:
         if non_interactive:
             print(f"  Federation key: keeping existing {key_file_path}")
@@ -237,17 +251,38 @@ def _resolve_federation_key(
         "read ~/.config/muxplex/federation_key there. SSH fallback:"
     )
     print(f"    scp <your-server>:.config/muxplex/federation_key {key_file_path}")
-    pasted = getpass_func("Federation key (or path): ")
-    value = pasted.strip()
-    candidate_path = Path(value).expanduser() if value else None
 
-    if candidate_path is not None and candidate_path.is_file():
-        key_value = candidate_path.read_text(encoding="utf-8").strip()
-    else:
-        key_value = value
+    verify: bool | str = ca_file if ca_file else True
+    key_value = ""
+    while True:
+        pasted = getpass_func("Federation key (or path): ")
+        value = pasted.strip()
+        candidate_path = Path(value).expanduser() if value else None
+
+        if candidate_path is not None and candidate_path.is_file():
+            key_value = candidate_path.read_text(encoding="utf-8").strip()
+        else:
+            key_value = value
 
-    if not key_value:
-        raise _InitError("no federation key provided")
+        if not key_value:
+            raise _InitError("no federation key provided")
+
+        status, message = cli_mod.check_federation_key_auth(
+            server_url, key_value, verify=verify
+        )
+        if status == "ok":
+            cli_mod.print_check("ok", "Federation key: verified against server")
+            break
+        if status == "fail":
+            cli_mod.print_check("fail", message)
+            print("  Try again -- paste the correct key, or a path to it.")
+            continue
+        # status == "warn": could not verify one way or the other (network
+        # hiccup, timeout) -- not evidence the key itself is wrong, so
+        # don't loop forever on something re-pasting can't fix. Still,
+        # never claim a check that didn't actually run succeeded.
+        cli_mod.print_check("warn", message)
+        break
 
     key_file_path.parent.mkdir(parents=True, exist_ok=True)
     key_file_path.parent.chmod(0o700)
@@ -311,6 +346,8 @@ def _run_init_impl(
     key_file_raw = raw.get("key_file") or config_mod.DEFAULT_KEY_FILE
     _resolve_federation_key(
         config_mod._expand(key_file_raw),
+        server_url=server_url,
+        ca_file=ca_file_value,
         non_interactive=non_interactive,
         input_func=input_func,
         getpass_func=getpass_func,

{muxplex_deck-0.5.2 → muxplex_deck-0.5.3}/src/muxplex_deck/service.py

@@ -72,6 +72,20 @@ _LAUNCHD_ALREADY_LOADED_EXIT = 5
 _LAUNCHD_BOOTOUT_POLL_INTERVAL_SECONDS = 0.2
 _LAUNCHD_BOOTOUT_TIMEOUT_SECONDS = 5.0
 
+# `systemctl restart` / `launchctl bootstrap` both return once the new
+# process has been LAUNCHED, not once it has done anything -- the new
+# sidecar needs at least one poll cycle to open the device (or notice it
+# can't) and publish its first status write via `statusfile.StatusReporter`.
+# Until then, `status.json` still holds the PREVIOUS process's last
+# snapshot, which `muxplex-deck status` would otherwise present as current,
+# healthy truth (the restart-race incident in AGENTS.md: 2 false failures
+# read from a dying process's stale-but-recent write, moments before it
+# exited). `restart` polls for a status write from the NEW process (by pid,
+# via `service_main_pid()`) before reporting success, bounded so a genuinely
+# slow-starting sidecar can't hang the command forever.
+_RESTART_STATUS_POLL_INTERVAL_SECONDS = 0.2
+_RESTART_STATUS_TIMEOUT_SECONDS = 5.0
+
 # Elgato Stream Deck USB vendor id -- used to detect an existing udev rule.
 _ELGATO_VENDOR_ID = "0fd9"
 _UDEV_RULE_DIRS: tuple[Path, ...] = (
@@ -309,6 +323,70 @@ def service_is_active() -> bool:
     return result.returncode == 0
 
 
+def service_main_pid() -> int | None:
+    """Best-effort PID of the currently-running muxplex-deck service process.
+
+    Never raises -- matches `service_is_active()`'s contract: any failure
+    (service manager missing, service not running, unexpected/unparseable
+    output) reads as "cannot determine", which callers must treat as "don't
+    know", never as a false positive or negative on its own.
+
+    This is what lets `status()` (and `_wait_for_fresh_status()` below) tell
+    whether a published `status.json` (`statusfile.build_status()`'s own
+    `pid` field) was written by the process running RIGHT NOW under the
+    service, or by a PREVIOUS incarnation whose last write can look
+    deceptively fresh by age alone -- see the restart-race incident in
+    AGENTS.md: the old process's last write happened moments before it
+    exited, so an age-only staleness check saw it as "recent" and reported
+    it as current truth. Comparing pids is the only way to tell those apart.
+    """
+    if _is_darwin():
+        uid = os.getuid()
+        try:
+            result = subprocess.run(
+                ["launchctl", "print", f"gui/{uid}/{_LAUNCHD_LABEL}"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except FileNotFoundError:
+            return None
+        if result.returncode != 0:
+            return None
+        for line in result.stdout.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("pid = "):
+                try:
+                    return int(stripped[len("pid = ") :].strip())
+                except ValueError:
+                    return None
+        return None
+
+    try:
+        result = subprocess.run(
+            [
+                "systemctl",
+                "--user",
+                "show",
+                "muxplex-deck",
+                "--property=MainPID",
+                "--value",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    if result.returncode != 0:
+        return None
+    try:
+        pid = int(result.stdout.strip())
+    except ValueError:
+        return None
+    return pid if pid > 0 else None
+
+
 def service_is_installed() -> bool:
     """Is the muxplex-deck unit/plist file present on disk?
 
@@ -502,6 +580,56 @@ def _systemd_stop() -> None:
     subprocess.run(["systemctl", "--user", "stop", "muxplex-deck"], check=False)
 
 
+def _wait_for_fresh_status(timeout: float | None = None) -> bool:
+    """Poll until `status.json`'s recorded pid matches the service's live
+    MainPID, or `timeout` elapses.
+
+    See `_RESTART_STATUS_TIMEOUT_SECONDS`'s docstring for why this exists:
+    the process a restart just launched needs at least one poll cycle
+    before it publishes its own status, and comparing pids (not wall-clock
+    age) is the only reliable way to tell "this snapshot belongs to the
+    process running right now" from "this is the previous process's last
+    write" -- the exact restart-race incident in AGENTS.md.
+
+    Returns True once a matching status is observed; False if `timeout`
+    elapses first. Never raises -- `service_main_pid()` and
+    `statusfile.read_status()` are both best-effort/never-raise themselves.
+    """
+    from . import statusfile
+
+    if timeout is None:
+        timeout = _RESTART_STATUS_TIMEOUT_SECONDS
+    deadline = time.monotonic() + timeout
+    while True:
+        current_pid = service_main_pid()
+        if current_pid is not None:
+            data = statusfile.read_status()
+            if data is not None and data.get("pid") == current_pid:
+                return True
+        if time.monotonic() >= deadline:
+            return False
+        time.sleep(_RESTART_STATUS_POLL_INTERVAL_SECONDS)
+
+
+def _report_restart_result(success_message: str) -> None:
+    """Print the final restart line: success only once fresh status is
+    actually observed, otherwise an honest "still waiting" warning.
+
+    Shared by systemd and launchd so both platforms make the same promise:
+    never print a success line for a step (the new process being up and
+    reporting) that was not actually verified -- see AGENTS.md's restart-
+    race incident, which this directly closes.
+    """
+    if _wait_for_fresh_status():
+        _step_ok(success_message)
+    else:
+        _step_warn(
+            "Restart command sent, but the service has not published fresh "
+            f"status within {_RESTART_STATUS_TIMEOUT_SECONDS:.0f}s -- it may "
+            "still be starting. Check: muxplex-deck status"
+        )
+
+
 def _systemd_restart() -> None:
     # `systemctl restart` is a single atomic transaction (unlike launchd's
     # separate bootout + bootstrap), so it needs no unload-race handling --
@@ -513,12 +641,12 @@ def _systemd_restart() -> None:
         text=True,
         check=False,
     )
-    if result.returncode == 0:
-        _step_ok("Restarted the service")
-    else:
+    if result.returncode != 0:
         _report_systemctl_failure("restart", result)
         sys.exit(1)
 
+    _report_restart_result("Restarted the service")
+
 
 def _systemd_status() -> None:
     subprocess.run(
@@ -704,13 +832,15 @@ def _launchd_restart() -> None:
 
     result = _launchd_bootstrap()
     if result.returncode == 0:
-        _step_ok("Restarted the service (launchctl bootstrap)")
+        success_message = "Restarted the service (launchctl bootstrap)"
     elif result.returncode == _LAUNCHD_ALREADY_LOADED_EXIT:
-        _step_ok("Service is running")
+        success_message = "Service is running"
     else:
         _report_launchctl_failure("bootstrap", result)
         sys.exit(1)
 
+    _report_restart_result(success_message)
+
 
 def _launchd_status() -> None:
     uid = os.getuid()