PyPI - plexus-python - Versions diffs - 0.2.0__py3-none-any.whl → 0.4.1__py3-none-any.whl - Mend

plexus-python 0.2.0py3-none-any.whl → 0.4.1py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

plexus/__init__.py +3 -2
plexus/cli.py +275 -0
plexus/client.py +85 -5
plexus/config.py +48 -0
plexus/ws.py +373 -0
{plexus_python-0.2.0.dist-info → plexus_python-0.4.1.dist-info}/METADATA +53 -2
plexus_python-0.4.1.dist-info/RECORD +11 -0
plexus_python-0.4.1.dist-info/entry_points.txt +2 -0
plexus_python-0.2.0.dist-info/RECORD +0 -8
{plexus_python-0.2.0.dist-info → plexus_python-0.4.1.dist-info}/WHEEL +0 -0
{plexus_python-0.2.0.dist-info → plexus_python-0.4.1.dist-info}/licenses/LICENSE +0 -0

plexus/__init__.py CHANGED Viewed

@@ -8,6 +8,7 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 """
 from plexus.client import Plexus
+from plexus.ws import WebSocketTransport
-__version__ = "0.2.0"
-__all__ = ["Plexus"]
+__version__ = "0.4.1"
+__all__ = ["Plexus", "WebSocketTransport"]

plexus/cli.py ADDED Viewed

@@ -0,0 +1,275 @@
+"""
+Plexus CLI — `plexus init` style auth, plus a few sibling commands.
+Designed to feel like fly.io / vercel CLIs:
+    $ pip install plexus
+    $ plexus init
+    Opening browser to https://app.plexus.company/auth/cli...
+    ✓ Saved API key as cli-<host>. You're set up.
+Implementation:
+- Spin up a local HTTP listener on a random free port.
+- Open the browser to /auth/cli with the callback URL embedded.
+- Block until the browser POSTs (well — redirects with key) to /callback.
+- Verify the `state` parameter matches what we generated.
+- Persist the key via plexus.config.save_config; the SDK already reads
+  `~/.plexus/config.json` for `PLEXUS_API_KEY`.
+Stdlib only — keep dependency footprint minimal.
+"""
+from __future__ import annotations
+import argparse
+import http.server
+import secrets
+import socket
+import socketserver
+import sys
+import threading
+import urllib.parse
+import webbrowser
+from typing import Optional
+from . import config
+DEFAULT_TIMEOUT_SECONDS = 300
+SUCCESS_HTML = """<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Plexus CLI</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+        display: flex; align-items: center; justify-content: center;
+        min-height: 100vh; margin: 0; background: Canvas; color: CanvasText;
+      }
+      .card {
+        max-width: 360px; padding: 32px; border: 1px solid #8884;
+        border-radius: 12px; text-align: center;
+      }
+      h1 { margin: 0 0 8px; font-size: 18px; }
+      p { margin: 0; color: #888; font-size: 14px; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>You're all set</h1>
+      <p>Return to your terminal &mdash; the CLI has your key.</p>
+    </div>
+  </body>
+</html>""".encode("utf-8")
+ERROR_HTML = """<!doctype html>
+<html><head><meta charset="utf-8" /><title>Plexus CLI</title></head>
+<body><pre style="font-family:ui-monospace,monospace;padding:24px">
+Plexus CLI authorization failed. Return to your terminal for details.
+</pre></body></html>""".encode("utf-8")
+class _CallbackResult:
+    key: Optional[str] = None
+    state: Optional[str] = None
+    error: Optional[str] = None
+def _pick_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+def _make_handler(result: _CallbackResult, expected_state: str, done: threading.Event):
+    class Handler(http.server.BaseHTTPRequestHandler):
+        # Silence the default request log — we don't want CLI noise.
+        def log_message(self, *_args, **_kwargs):  # type: ignore[override]
+            return
+        def do_GET(self):  # type: ignore[override]
+            parsed = urllib.parse.urlparse(self.path)
+            if parsed.path != "/callback":
+                self.send_response(404)
+                self.end_headers()
+                return
+            params = urllib.parse.parse_qs(parsed.query)
+            got_state = (params.get("state") or [""])[0]
+            got_key = (params.get("key") or [""])[0]
+            if got_state != expected_state:
+                result.error = "state mismatch"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(ERROR_HTML)
+                done.set()
+                return
+            if not got_key:
+                result.error = "no key in callback"
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(ERROR_HTML)
+                done.set()
+                return
+            result.key = got_key
+            result.state = got_state
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(SUCCESS_HTML)
+            done.set()
+    return Handler
+def _hostname_label() -> str:
+    try:
+        host = socket.gethostname() or "device"
+    except Exception:
+        host = "device"
+    # Strip the trailing .local etc. and clean it for display.
+    safe = host.split(".")[0].lower().replace(" ", "-")
+    return f"cli-{safe}" if safe else "cli"
+def cmd_init(args: argparse.Namespace) -> int:
+    """Open the browser, capture an API key, save it locally."""
+    existing = config.get_api_key()
+    if existing and not args.force:
+        print(
+            "An API key is already configured. "
+            "Re-run with --force to replace it.",
+            file=sys.stderr,
+        )
+        return 1
+    endpoint = config.get_endpoint().rstrip("/")
+    state = secrets.token_urlsafe(24)
+    name = args.name or _hostname_label()
+    port = _pick_free_port()
+    callback = f"http://127.0.0.1:{port}/callback"
+    auth_url = (
+        f"{endpoint}/auth/cli"
+        f"?state={urllib.parse.quote(state)}"
+        f"&callback={urllib.parse.quote(callback)}"
+        f"&name={urllib.parse.quote(name)}"
+    )
+    result = _CallbackResult()
+    done = threading.Event()
+    handler = _make_handler(result, state, done)
+    server = socketserver.TCPServer(("127.0.0.1", port), handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        print(f"Opening {auth_url}")
+        try:
+            webbrowser.open(auth_url, new=1, autoraise=True)
+        except Exception:
+            pass  # User can copy the URL manually.
+        print("Waiting for browser confirmation...", flush=True)
+        finished = done.wait(timeout=args.timeout)
+        if not finished:
+            print(
+                f"Timed out after {args.timeout}s. Re-run `plexus init`.",
+                file=sys.stderr,
+            )
+            return 2
+    finally:
+        server.shutdown()
+        server.server_close()
+    if result.error or not result.key:
+        print(
+            f"Authorization failed: {result.error or 'no key returned'}",
+            file=sys.stderr,
+        )
+        return 3
+    cfg = config.load_config()
+    cfg["api_key"] = result.key
+    config.save_config(cfg)
+    print(f"✓ Saved API key as {name}.")
+    print("  ~/.plexus/config.json")
+    return 0
+def cmd_logout(_args: argparse.Namespace) -> int:
+    """Forget the locally stored API key."""
+    cfg = config.load_config()
+    if not cfg.get("api_key"):
+        print("Nothing to do — no key on file.")
+        return 0
+    cfg["api_key"] = None
+    config.save_config(cfg)
+    print("✓ Cleared local API key.")
+    return 0
+def cmd_whoami(_args: argparse.Namespace) -> int:
+    """Print the prefix of the locally stored key + the configured endpoint."""
+    key = config.get_api_key()
+    endpoint = config.get_endpoint()
+    if not key:
+        print("Not signed in. Run `plexus init` to authorize this machine.")
+        return 1
+    masked = f"{key[:8]}…{key[-4:]}" if len(key) > 12 else key
+    print(f"key:      {masked}")
+    print(f"endpoint: {endpoint}")
+    return 0
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="plexus",
+        description="Plexus CLI — auth, send, query telemetry from your terminal.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    init = sub.add_parser(
+        "init",
+        help="Authorize this machine and save an API key locally.",
+        aliases=["login"],
+    )
+    init.add_argument("--name", help="Label for the issued key (default: cli-<hostname>).")
+    init.add_argument(
+        "--timeout",
+        type=int,
+        default=DEFAULT_TIMEOUT_SECONDS,
+        help="Seconds to wait for the browser callback.",
+    )
+    init.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing local key.",
+    )
+    init.set_defaults(func=cmd_init)
+    logout = sub.add_parser("logout", help="Forget the local API key.")
+    logout.set_defaults(func=cmd_logout)
+    whoami = sub.add_parser("whoami", help="Show the local credential summary.")
+    whoami.set_defaults(func=cmd_whoami)
+    return parser
+def main(argv: Optional[list] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+if __name__ == "__main__":
+    sys.exit(main())

plexus/client.py CHANGED Viewed

@@ -48,7 +48,10 @@ from plexus.config import (
     get_api_key,
     get_endpoint,
     get_gateway_url,
+    get_gateway_ws_url,
+    get_install_id,
     get_source_id,
+    set_source_id,
 )
 logger = logging.getLogger(__name__)
@@ -95,6 +98,8 @@ class Plexus:
         max_buffer_size: int = 10000,
         persistent_buffer: bool = False,
         buffer_path: Optional[str] = None,
+        transport: str = "ws",
+        ws_url: Optional[str] = None,
     ):
         self.api_key = api_key or get_api_key()
         if not self.api_key:
@@ -114,6 +119,12 @@ class Plexus:
         self._session: Optional[requests.Session] = None
         self._store_frames: bool = False
+        if transport not in ("ws", "http"):
+            raise ValueError(f"transport must be 'ws' or 'http', got {transport!r}")
+        self.transport = transport
+        self._ws_url = (ws_url or get_gateway_ws_url())
+        self._ws = None  # lazily constructed in _ensure_ws()
         # Pluggable buffer backend for failed sends
         if persistent_buffer:
             self._buffer: BufferBackend = SqliteBuffer(
@@ -250,16 +261,70 @@ class Plexus:
                 ("position", {"x": 1.0, "y": 2.0}),
             ])
         """
-        ts = timestamp or time.time()
+        ts = timestamp if timestamp is not None else time.time()
         data_points = [self._make_point(m, v, ts, tags) for m, v in points]
         return self._send_points(data_points)
+    def _ensure_ws(self):
+        """Lazily construct and start the WebSocket transport."""
+        if self._ws is not None:
+            return self._ws
+        from plexus.ws import WebSocketTransport
+        from plexus import __version__
+        self._ws = WebSocketTransport(
+            api_key=self.api_key,
+            source_id=self.source_id,
+            ws_url=self._ws_url,
+            install_id=get_install_id(),
+            agent_version=__version__,
+            on_source_id_assigned=self._on_source_id_assigned,
+        )
+        self._ws.start()
+        return self._ws
+    def _on_source_id_assigned(self, assigned: str) -> None:
+        """Callback from WebSocketTransport when the gateway returns an
+        auto-suffixed source_id. Persists it so subsequent runs (and the HTTP
+        fallback path in this process) use the assigned name directly."""
+        self.source_id = assigned
+        try:
+            set_source_id(assigned)
+        except Exception as e:  # pragma: no cover - persistence failure is non-fatal
+            logger.debug("failed to persist assigned source_id: %s", e)
+    def on_command(
+        self,
+        name: str,
+        handler,
+        *,
+        description: Optional[str] = None,
+        params: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Register a command handler (WebSocket transport only).
+        The handler is called as `handler(command_name, params_dict)` and may
+        return a dict (→ `result`) or raise (→ `error`). An `ack` is sent
+        automatically before the handler runs.
+        Must be called before the first send() so the command is advertised
+        in the auth frame.
+        """
+        if self.transport != "ws":
+            raise PlexusError("on_command requires transport='ws'")
+        ws = self._ensure_ws()
+        ws.register_command(name, handler, description=description, params=params)
     def _send_points(self, points: List[Dict[str, Any]]) -> bool:
-        """Send data points to the API with retry and buffering.
+        """Send data points to the gateway with retry and buffering.
-        Retry behavior:
-        - Retries on: Timeout, ConnectionError, HTTP 429 (rate limit), HTTP 5xx
-        - No retry on: HTTP 401/403 (auth errors), HTTP 400/422 (bad request)
+        Path:
+        - transport='ws': try the WebSocket first; if not yet authenticated or
+          the socket fails, fall through to the HTTP path so points still land.
+        - transport='http': always POST /ingest with retries.
+        Retry behavior (HTTP path):
+        - Retries on: Timeout, ConnectionError, HTTP 429, HTTP 5xx
+        - No retry on: HTTP 401/403 (auth), HTTP 400/422 (bad request)
         - After max retries: buffers points locally for next send attempt
         """
         if not self.api_key:
@@ -270,6 +335,18 @@ class Plexus:
         # Include any previously buffered points
         all_points = self._get_buffered_points() + points
+        # Preferred path: WebSocket.
+        if self.transport == "ws":
+            ws = self._ensure_ws()
+            # Brief wait on first call so startup races don't dump every point
+            # into the HTTP fallback path.
+            if not ws.is_authenticated:
+                ws.wait_authenticated(timeout=min(self.timeout, 5.0))
+            if ws.send_points(all_points):
+                self._clear_buffer()
+                return True
+            # Socket unavailable → fall through to HTTP.
         url = f"{self.gateway_url}/ingest"
         last_error: Optional[Exception] = None
@@ -451,6 +528,9 @@ class Plexus:
     def close(self):
         """Close the client and release resources."""
+        if self._ws is not None:
+            self._ws.stop()
+            self._ws = None
         if self._session:
             self._session.close()
             self._session = None

plexus/config.py CHANGED Viewed

@@ -145,6 +145,54 @@ def get_source_id() -> Optional[str]:
     return source_id
+def get_install_id() -> str:
+    """Get the device install ID, generating one if not set.
+    The install_id is a stable per-installation UUID. It is generated lazily
+    on first run (NOT at image-build time) so that cloned SD-card images
+    naturally get distinct install_ids on their first boot. The gateway uses
+    it to tell "same device reconnecting" from "different device claiming the
+    same name" when resolving source_id collisions.
+    Resolution order:
+      1. ``PLEXUS_INSTALL_ID`` env var — lets ephemeral containers (Fly
+         machines, CI runners, Kubernetes pods) pin a stable identity
+         across restarts when the config filesystem is ephemeral. Without
+         this, every redeploy generates a new install_id and the gateway
+         auto-suffixes the source_id to avoid a collision with the prior
+         install ("gw-001" → "gw-001_2" → "gw-001_3"…).
+      2. ``install_id`` in the on-disk config.
+      3. Newly-generated UUID, persisted to config.
+    """
+    env_id = os.environ.get("PLEXUS_INSTALL_ID", "").strip()
+    if env_id:
+        return env_id
+    config = load_config()
+    install_id = config.get("install_id")
+    if not install_id:
+        import uuid
+        install_id = uuid.uuid4().hex
+        config["install_id"] = install_id
+        save_config(config)
+    return install_id
+def set_source_id(source_id: str) -> None:
+    """Persist an updated source_id to the config file.
+    Called by the SDK when the gateway returns an auto-suffixed name so the
+    assigned name is stable across reconnects.
+    """
+    config = load_config()
+    if config.get("source_id") == source_id:
+        return
+    config["source_id"] = source_id
+    save_config(config)
 def get_persistent_buffer() -> bool:
     """Get persistent buffer setting. Default True (store-and-forward enabled)."""
     config = load_config()

plexus/ws.py ADDED Viewed

@@ -0,0 +1,373 @@
+"""
+WebSocket transport for the Plexus Python SDK.
+Wire-compatible with the C SDK (`plexus_ws.c`). Targets the gateway's
+`/ws/device` endpoint and exchanges the same JSON frames:
+    client → {"type": "device_auth", "api_key": ..., "source_id": ...,
+              "install_id": ..., "platform": "python-sdk",
+              "agent_version": ..., "commands": [...]}
+    server → {"type": "authenticated", "source_id": ...}
+The server-returned `source_id` in the `authenticated` frame is
+authoritative: if the gateway auto-suffixed on a collision (e.g. the
+desired name was already claimed by a different install_id), the
+client's `source_id` is updated in place to match.
+    client → {"type": "telemetry", "points": [...]}
+    client → {"type": "heartbeat", "source_id": ..., "agent_version": ...}   # every 30s
+    server → {"type": "typed_command", "id": ..., "command": ..., "params": {...}}
+    client → {"type": "command_result", "id": ..., "command": ..., "event": "ack"}
+    client → {"type": "command_result", "id": ..., "command": ...,
+              "event": "result" | "error", "result": {...} | "error": "..."}
+Runs the read loop on a background daemon thread so callers can stay sync.
+"""
+from __future__ import annotations
+import json
+import logging
+import random
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+try:
+    import websocket  # websocket-client
+except ImportError as e:  # pragma: no cover - import-time failure is obvious
+    raise ImportError(
+        "WebSocket transport requires 'websocket-client'. "
+        "Install with: pip install websocket-client"
+    ) from e
+logger = logging.getLogger(__name__)
+AUTH_TIMEOUT_S = 10.0
+HEARTBEAT_INTERVAL_S = 30.0
+BACKOFF_BASE_S = 1.0
+BACKOFF_MAX_S = 60.0
+CommandHandler = Callable[[str, Dict[str, Any]], Optional[Dict[str, Any]]]
+@dataclass
+class _RegisteredCommand:
+    name: str
+    handler: CommandHandler
+    description: Optional[str] = None
+    params: List[Dict[str, Any]] = field(default_factory=list)
+    def to_manifest(self) -> Dict[str, Any]:
+        m: Dict[str, Any] = {"name": self.name}
+        if self.description:
+            m["description"] = self.description
+        if self.params:
+            m["params"] = self.params
+        return m
+class WebSocketTransport:
+    """Background WebSocket connection to the Plexus gateway.
+    Lifecycle:
+        t = WebSocketTransport(api_key, source_id, ws_url)
+        t.start()
+        t.wait_authenticated(timeout=5)
+        t.send_points([...])
+        t.stop()
+    """
+    def __init__(
+        self,
+        api_key: str,
+        source_id: str,
+        ws_url: str,
+        *,
+        install_id: str = "",
+        agent_version: str = "0.0.0",
+        platform: str = "python-sdk",
+        auto_reconnect: bool = True,
+        on_source_id_assigned: Optional[Callable[[str], None]] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key required")
+        if not source_id:
+            raise ValueError("source_id required")
+        self.api_key = api_key
+        self.source_id = source_id
+        self.install_id = install_id
+        self.ws_url = _ensure_device_path(ws_url)
+        self.agent_version = agent_version
+        self.platform = platform
+        self.auto_reconnect = auto_reconnect
+        self._on_source_id_assigned = on_source_id_assigned
+        self._commands: Dict[str, _RegisteredCommand] = {}
+        self._ws: Optional[websocket.WebSocket] = None
+        self._ws_lock = threading.Lock()
+        self._authenticated = threading.Event()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._backoff_attempt = 0
+    # ------------------------------------------------------------------ public
+    def register_command(
+        self,
+        name: str,
+        handler: CommandHandler,
+        *,
+        description: Optional[str] = None,
+        params: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Register a command handler. Must be called before start() to be
+        advertised in the auth frame."""
+        self._commands[name] = _RegisteredCommand(
+            name=name, handler=handler, description=description, params=params or []
+        )
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._run, name="plexus-ws", daemon=True
+        )
+        self._thread.start()
+    def stop(self, timeout: float = 2.0) -> None:
+        self._stop.set()
+        with self._ws_lock:
+            ws = self._ws
+        if ws is not None:
+            try:
+                ws.close()
+            except Exception:  # pragma: no cover
+                pass
+        if self._thread:
+            self._thread.join(timeout=timeout)
+    def wait_authenticated(self, timeout: float = AUTH_TIMEOUT_S) -> bool:
+        return self._authenticated.wait(timeout=timeout)
+    @property
+    def is_authenticated(self) -> bool:
+        return self._authenticated.is_set()
+    def send_points(self, points: List[Dict[str, Any]]) -> bool:
+        """Send a telemetry frame. Returns False if the socket is not
+        authenticated — caller is expected to fall back to HTTP."""
+        if not points:
+            return True
+        if not self._authenticated.is_set():
+            return False
+        frame = {"type": "telemetry", "points": points}
+        return self._send_frame(frame)
+    # ------------------------------------------------------------------ thread
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                self._connect_and_serve()
+            except Exception as e:
+                logger.warning("plexus ws loop error: %s", e)
+            finally:
+                self._authenticated.clear()
+                with self._ws_lock:
+                    self._ws = None
+            if not self.auto_reconnect or self._stop.is_set():
+                break
+            delay = _backoff_delay(self._backoff_attempt)
+            self._backoff_attempt = min(self._backoff_attempt + 1, 10)
+            logger.info("plexus ws reconnect in %.1fs", delay)
+            if self._stop.wait(timeout=delay):
+                break
+    def _connect_and_serve(self) -> None:
+        ws = websocket.create_connection(self.ws_url, timeout=AUTH_TIMEOUT_S)
+        with self._ws_lock:
+            self._ws = ws
+        # 1. Send device_auth
+        desired_source_id = self.source_id
+        auth = {
+            "type": "device_auth",
+            "api_key": self.api_key,
+            "source_id": desired_source_id,
+            "platform": self.platform,
+            "agent_version": self.agent_version,
+        }
+        if self.install_id:
+            auth["install_id"] = self.install_id
+        if self._commands:
+            auth["commands"] = [c.to_manifest() for c in self._commands.values()]
+        ws.send(json.dumps(auth))
+        # 2. Wait for authenticated
+        ws.settimeout(AUTH_TIMEOUT_S)
+        try:
+            raw = ws.recv()
+        except websocket.WebSocketTimeoutException as e:
+            raise TimeoutError("auth timeout") from e
+        msg = _safe_json(raw)
+        if msg.get("type") != "authenticated":
+            raise RuntimeError(f"auth failed: {msg}")
+        # The gateway may return a different source_id if the desired name
+        # was already claimed by another install — adopt the assigned value
+        # so all subsequent frames (heartbeats, future reconnects) use it.
+        assigned = msg.get("source_id")
+        if isinstance(assigned, str) and assigned and assigned != self.source_id:
+            logger.info(
+                "plexus ws source_id auto-suffixed: requested=%s assigned=%s",
+                desired_source_id, assigned,
+            )
+            self.source_id = assigned
+            if self._on_source_id_assigned is not None:
+                try:
+                    self._on_source_id_assigned(assigned)
+                except Exception as e:  # pragma: no cover - callback errors must not break auth
+                    logger.debug("on_source_id_assigned callback raised: %s", e)
+        self._authenticated.set()
+        self._backoff_attempt = 0
+        logger.info("plexus ws authenticated as %s", self.source_id)
+        # 3. Read loop with heartbeat pump
+        ws.settimeout(1.0)
+        last_heartbeat = time.monotonic()
+        while not self._stop.is_set():
+            now = time.monotonic()
+            if now - last_heartbeat >= HEARTBEAT_INTERVAL_S:
+                self._send_frame({
+                    "type": "heartbeat",
+                    "source_id": self.source_id,
+                    "agent_version": self.agent_version,
+                })
+                last_heartbeat = now
+            try:
+                raw = ws.recv()
+            except websocket.WebSocketTimeoutException:
+                continue
+            except (websocket.WebSocketConnectionClosedException, OSError):
+                logger.info("plexus ws closed")
+                return
+            if not raw:
+                continue
+            self._dispatch(_safe_json(raw))
+    def _dispatch(self, msg: Dict[str, Any]) -> None:
+        mtype = msg.get("type")
+        if mtype == "typed_command":
+            self._handle_command(msg)
+        elif mtype == "error":
+            logger.warning("plexus ws server error: %s", msg.get("detail") or msg)
+        # ignore unknown types — forward-compat
+    def _handle_command(self, msg: Dict[str, Any]) -> None:
+        cmd_id = msg.get("id") or ""
+        command = msg.get("command") or ""
+        params = msg.get("params") or {}
+        # Ack immediately (matches C SDK: plexus_ws.c:275-280)
+        self._send_frame({
+            "type": "command_result",
+            "id": cmd_id,
+            "command": command,
+            "event": "ack",
+        })
+        reg = self._commands.get(command)
+        if reg is None:
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": f"unknown command: {command}",
+            })
+            return
+        # Run the handler off the read-loop thread so a slow handler doesn't
+        # block heartbeats or other inbound frames.
+        threading.Thread(
+            target=self._run_handler,
+            args=(reg, cmd_id, command, params),
+            daemon=True,
+        ).start()
+    def _run_handler(
+        self,
+        reg: _RegisteredCommand,
+        cmd_id: str,
+        command: str,
+        params: Dict[str, Any],
+    ) -> None:
+        try:
+            result = reg.handler(command, params)
+        except Exception as e:
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": str(e),
+            })
+            return
+        self._send_frame({
+            "type": "command_result",
+            "id": cmd_id,
+            "command": command,
+            "event": "result",
+            "result": result if result is not None else {},
+        })
+    def _send_frame(self, frame: Dict[str, Any]) -> bool:
+        with self._ws_lock:
+            ws = self._ws
+        if ws is None:
+            return False
+        try:
+            ws.send(json.dumps(frame))
+            return True
+        except Exception as e:
+            logger.debug("plexus ws send failed: %s", e)
+            return False
+# --------------------------------------------------------------------- helpers
+def _ensure_device_path(url: str) -> str:
+    url = url.rstrip("/")
+    if url.endswith("/ws/device"):
+        return url
+    return url + "/ws/device"
+def _safe_json(raw: Any) -> Dict[str, Any]:
+    if isinstance(raw, (bytes, bytearray)):
+        raw = raw.decode("utf-8", errors="replace")
+    if not isinstance(raw, str):
+        return {}
+    try:
+        obj = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return obj if isinstance(obj, dict) else {}
+def _backoff_delay(attempt: int) -> float:
+    """Exponential backoff with ±25% jitter, capped at BACKOFF_MAX_S.
+    Matches plexus_ws.c:44-52."""
+    base = min(BACKOFF_BASE_S * (2 ** attempt), BACKOFF_MAX_S)
+    jitter = base * 0.25 * (2 * random.random() - 1)
+    return max(0.1, base + jitter)

{plexus_python-0.2.0.dist-info → plexus_python-0.4.1.dist-info}/METADATA RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.2.0
+Version: 0.4.1
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -24,10 +24,12 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.8
 Requires-Dist: requests>=2.28.0
+Requires-Dist: websocket-client>=1.7
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: websockets>=12; extra == 'dev'
 Description-Content-Type: text/markdown
 # plexus-python
@@ -52,6 +54,21 @@ px.send("temperature", 72.5)
 Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
+## Device identity
+Every device needs a unique `source_id`. The recommended way to set one on a real host is the bootstrap script, which requires a device name up front:
+```bash
+curl -sL https://app.plexus.company/setup | bash -s -- \
+  --key plx_xxx --name drone-01
+```
+The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
+**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
 ## Usage
 ```python
@@ -119,13 +136,47 @@ px.buffer_size()
 px.flush_buffer()
 ```
+## Transport
+By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — same wire protocol as the C SDK. This gives you:
+- lower-latency streaming of telemetry,
+- live command delivery from the UI / API to the device.
+If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
+```python
+# default — ws with http fallback
+px = Plexus()
+# force http (legacy)
+px = Plexus(transport="http")
+```
+### Handling commands
+Register a handler before the first `send()` so the command is advertised in the auth frame:
+```python
+def reboot(name, params):
+    delay = params.get("delay_s", 0)
+    # ... reboot logic ...
+    return {"ok": True, "delay": delay}
+px = Plexus()
+px.on_command("reboot", reboot, description="reboot the device")
+px.send("temperature", 72.5)   # opens the socket, waits for auth
+```
+The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
 ## Environment Variables
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
 | `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL (unused in SDK, for compatibility) | `wss://plexus-gateway.fly.dev` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
 ## Architecture

plexus_python-0.4.1.dist-info/RECORD ADDED Viewed

@@ -0,0 +1,11 @@
+plexus/__init__.py,sha256=sIeMuUgTaztA5jYnSxh6T-2lBBjRR7TXQiVHXut5SXI,345
+plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
+plexus/cli.py,sha256=FW5NtWAAcXiWTqpn-e_qMIPilWk8N9jJCLywRKHHmUU,8514
+plexus/client.py,sha256=Hp-qUdLkZ83OQeF_3d2FH5kCZXK9iJOSmO7o0opOR8U,19395
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=upQ9SpekDYa7MltUW5ZDEuCm_E8hEVpxC0QFNP_jT1g,12581
+plexus_python-0.4.1.dist-info/METADATA,sha256=wxlE_vaFRHs-MeS1TnP2gi22OvLWN1Dq_Cpi1QRwVqM,6800
+plexus_python-0.4.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.4.1.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.4.1.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.4.1.dist-info/RECORD,,

plexus_python-0.4.1.dist-info/entry_points.txt ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ [console_scripts]
2	+ plexus = plexus.cli:main

plexus_python-0.2.0.dist-info/RECORD DELETED Viewed

@@ -1,8 +0,0 @@
-plexus/__init__.py,sha256=Kal4qSrpQ6S8-AE7F9UqFkJMvbhTD82kzkO59O-ruEw,282
-plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
-plexus/client.py,sha256=X6gyFYS-CVwcqJt_VzwHuNtsuJhJJzSxH41T7UBv9dE,16212
-plexus/config.py,sha256=RNym2Fon6JOCVi1rXPSRWjPFAdT8DSmokY5JPEljQOc,4450
-plexus_python-0.2.0.dist-info/METADATA,sha256=51nhbClqTy2w07qn--JyzD8wAOnM7OQQhydvYUgswRI,4528
-plexus_python-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plexus_python-0.2.0.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.2.0.dist-info/RECORD,,

{plexus_python-0.2.0.dist-info → plexus_python-0.4.1.dist-info}/WHEEL RENAMED Viewed

File without changes

{plexus_python-0.2.0.dist-info → plexus_python-0.4.1.dist-info}/licenses/LICENSE RENAMED Viewed

File without changes

plexus-python 0.2.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

plexus-python 0.2.0py3-none-any.whl → 0.4.1py3-none-any.whl