plexus-python 0.7.1__tar.gz → 0.8.0__tar.gz

{plexus_python-0.7.1 → plexus_python-0.8.0}/AGENTS.md

@@ -7,8 +7,8 @@ Machine-readable interface for AI assistants and automation scripts.
 | Variable                | Description                           | Default                          |
 | ----------------------- | ------------------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key for authentication (required) | none                             |
-| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://plexus-gateway.fly.dev`   |
+| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://gateway.plexus.company`   |
 
 ## CLI Commands
 

{plexus_python-0.7.1 → plexus_python-0.8.0}/API.md

@@ -30,7 +30,7 @@ Then control streaming, recording, and configuration from [app.plexus.company/de
 Send data directly via HTTP:
 
 ```bash
-curl -X POST https://plexus-gateway.fly.dev/ingest \
+curl -X POST https://gateway.plexus.company/ingest \
   -H "x-api-key: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -94,14 +94,14 @@ x-api-key: plx_xxxxx
 }
 ```
 
-| Field        | Type   | Required | Description                                    |
-| ------------ | ------ | -------- | ---------------------------------------------- |
-| `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`) |
-| `value`      | any    | Yes      | See supported value types below                |
+| Field        | Type   | Required | Description                                                                                                                                                                                             |
+| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`)                                                                                                                                                          |
+| `value`      | any    | Yes      | See supported value types below                                                                                                                                                                         |
 | `timestamp`  | float  | No       | Unix timestamp in seconds (or ms if ≥ 1e12). Omit to use device time. Over WebSocket, the Python SDK applies a server-synced clock correction when omitted — see [Clock correction](#clock-correction). |
-| `source_id`  | string | Yes      | Your source identifier                         |
-| `tags`       | object | No       | Key-value labels                               |
-| `session_id` | string | No       | Group data into sessions                       |
+| `source_id`  | string | Yes      | Your source identifier                                                                                                                                                                                  |
+| `tags`       | object | No       | Key-value labels                                                                                                                                                                                        |
+| `session_id` | string | No       | Group data into sessions                                                                                                                                                                                |
 
 ### Supported Value Types
 
@@ -152,7 +152,7 @@ For real-time UI-controlled streaming, devices connect via WebSocket.
 
 ### Device Authentication
 
-Devices authenticate using an API key. The `source_id` in the request is the device's *desired* name; the server may return a different, auto-suffixed name in the `authenticated` frame if the desired name is already claimed by another device (see [Device identity](../README.md#device-identity) in the README).
+Devices authenticate using an API key. The `source_id` in the request is the device's _desired_ name; the server may return a different, auto-suffixed name in the `authenticated` frame if the desired name is already claimed by another device (see [Device identity](../README.md#device-identity) in the README).
 
 ```json
 // Device → Server
@@ -286,7 +286,7 @@ import requests
 import time
 
 requests.post(
-    "https://plexus-gateway.fly.dev/ingest",
+    "https://gateway.plexus.company/ingest",
     headers={"x-api-key": "plx_xxxxx"},
     json={
         "points": [{
@@ -302,7 +302,7 @@ requests.post(
 ### JavaScript
 
 ```javascript
-await fetch("https://plexus-gateway.fly.dev/ingest", {
+await fetch("https://gateway.plexus.company/ingest", {
   method: "POST",
   headers: {
     "x-api-key": "plx_xxxxx",
@@ -344,7 +344,7 @@ func main() {
     }
 
     body, _ := json.Marshal(points)
-    req, _ := http.NewRequest("POST", "https://plexus-gateway.fly.dev/ingest", bytes.NewBuffer(body))
+    req, _ := http.NewRequest("POST", "https://gateway.plexus.company/ingest", bytes.NewBuffer(body))
     req.Header.Set("x-api-key", "plx_xxxxx")
     req.Header.Set("Content-Type", "application/json")
 
@@ -363,7 +363,7 @@ func main() {
 // field entirely if you cannot guarantee NTP sync at send time.
 void sendToPlexus(const char* metric, float value) {
     HTTPClient http;
-    http.begin("https://plexus-gateway.fly.dev/ingest");
+    http.begin("https://gateway.plexus.company/ingest");
     http.addHeader("Content-Type", "application/json");
     http.addHeader("x-api-key", "plx_xxxxx");
 
@@ -386,7 +386,7 @@ void sendToPlexus(const char* metric, float value) {
 API_KEY="plx_xxxxx"
 SOURCE_ID="sensor-001"
 
-curl -X POST https://plexus-gateway.fly.dev/ingest \
+curl -X POST https://gateway.plexus.company/ingest \
   -H "x-api-key: $API_KEY" \
   -H "Content-Type: application/json" \
   -d "{
@@ -430,8 +430,6 @@ while True:
         px.send("attitude.pitch", msg.pitch)
 ```
 
-See [docs.plexus.dev/recipes](https://docs.plexus.dev/recipes) for more.
-
 ## Python SDK with Sensor Drivers
 
 For Raspberry Pi and other Linux devices, the Python SDK includes sensor drivers:
@@ -492,15 +490,18 @@ px.send("temperature", 72.5, timestamp=t)        # your timestamp → used as-is
 ```
 
 **When to pass an explicit timestamp:**
+
 - You have a reliable wall-clock source (GPS, trusted hardware RTC, host NTP)
 - You are replaying or backfilling historical data
 - Your sensor provides its own wall-clock timestamp
 
 **When to omit timestamp:**
+
 - The device may have booted without NTP (Raspberry Pi, Jetson, field robots without network on first boot)
 - You have no reliable external time source
 
 **Known limitations:**
+
 - The clock offset refreshes only on WebSocket reconnect. A device with a drifting RTC that stays connected for many days will accumulate uncorrected drift between reconnects proportional to the drift rate.
 - HTTP transport (`transport="http"`) does not receive clock sync — timestamps default to the device clock uncorrected.
 - `send_batch()` takes one shared `timestamp` for the whole batch, not per-point. For per-point timestamps, call `send()` in a loop.

{plexus_python-0.7.1 → plexus_python-0.8.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.8.0] - 2026-07-02 - Command concurrency control
+
+### Added
+
+- `concurrency` option on `on_command()` / `register_command()`. Defaults to `"accept"`
+  (unchanged behavior — overlapping invocations run concurrently). Set `"reject"` to refuse a
+  new invocation with an error result (`command already in progress: <name>`) while a previous
+  invocation of the same command is still running. Use it for handlers that drive exclusive
+  hardware (e.g. a pump init) so a client retry or double-click can't start two at once.
+  Protection is per command name; the immediate ack is still sent before the handler runs.
+
 ## [0.7.1] - 2026-06-02 - Remove install_id / source_id auto-suffix
 
 ### Changed
@@ -184,7 +195,7 @@
 
 ### Changed
 
-- Gateway WebSocket URL (`wss://plexus-gateway.fly.dev`) is now the SDK
+- Gateway WebSocket URL (`wss://gateway.plexus.company`) is now the SDK
   default — no need to pass `ws_url` explicitly.
 - Removed the `[plexus]   endpoint: …` line from the connection printout.
 
@@ -342,7 +353,7 @@ Breaking. `plexus-python` is now just the thin client — no agent, adapters, se
 
 ### Changed
 
-- Default ingest endpoint points directly at the Plexus gateway (`https://plexus-gateway.fly.dev/ingest`), not the Next.js app proxy
+- Default ingest endpoint points directly at the Plexus gateway (`https://gateway.plexus.company/ingest`), not the Next.js app proxy
 - Client raises `ValueError` clearly when no API key is available, instead of invoking a login flow
 
 ## [0.1.0] - Initial release

{plexus_python-0.7.1 → plexus_python-0.8.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.7.1
+Version: 0.8.0
 Summary: Thin Python SDK for Plexus — send telemetry in one line
-Project-URL: Homepage, https://plexus.dev
-Project-URL: Documentation, https://docs.plexus.dev
+Project-URL: Homepage, https://plexus.company
+Project-URL: Documentation, https://docs.plexus.company
 Project-URL: Repository, https://github.com/plexus-oss/plexus-python
 Project-URL: Issues, https://github.com/plexus-oss/plexus-python/issues
-Author-email: Plexus <hello@plexus.dev>
+Author-email: Plexus <info@plexus.company>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: fleet,hardware,iot,monitoring,observability,telemetry
@@ -270,8 +270,8 @@ The SDK sends an `ack` frame before invoking the handler, then a `result` frame
 | 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              | `wss://plexus-gateway.fly.dev`   |
+| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://gateway.plexus.company`   |
 
 ## Architecture
 

{plexus_python-0.7.1 → plexus_python-0.8.0}/README.md

@@ -233,8 +233,8 @@ The SDK sends an `ack` frame before invoking the handler, then a `result` frame
 | 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              | `wss://plexus-gateway.fly.dev`   |
+| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://gateway.plexus.company`   |
 
 ## Architecture
 

{plexus_python-0.7.1 → plexus_python-0.8.0}/plexus/__init__.py

@@ -10,5 +10,5 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 from plexus.client import Plexus, PlexusError, AuthenticationError, read_mjpeg_frames
 from plexus.config import RetryConfig
 
-__version__ = "0.7.1"
+__version__ = "0.8.0"
 __all__ = ["Plexus", "PlexusError", "AuthenticationError", "RetryConfig", "read_mjpeg_frames"]

{plexus_python-0.7.1 → plexus_python-0.8.0}/plexus/client.py

@@ -686,6 +686,7 @@ class Plexus:
         *,
         description: Optional[str] = None,
         params: Optional[List[Dict[str, Any]]] = None,
+        concurrency: str = "accept",
     ) -> None:
         """Register a command handler (WebSocket transport only).
 
@@ -695,6 +696,12 @@ class Plexus:
 
         Must be called before the first send() so the command is advertised
         in the auth frame.
+
+        concurrency: "accept" (default) runs overlapping invocations of the
+            same command concurrently; "reject" refuses a new invocation with
+            an error result while a previous one is still running. Use
+            "reject" for handlers that drive exclusive hardware (e.g. a pump
+            init) so a retry or double-click can't start two at once.
         """
         ws = self._ensure_ws()
         if ws.is_authenticated:
@@ -704,7 +711,10 @@ class Plexus:
                 "Call on_command() before the first send().",
                 name,
             )
-        ws.register_command(name, handler, description=description, params=params)
+        ws.register_command(
+            name, handler, description=description, params=params,
+            concurrency=concurrency,
+        )
 
     def _send_points(self, points: List[Dict[str, Any]]) -> bool:
         """Send data points to the gateway with retry and buffering.

{plexus_python-0.7.1 → plexus_python-0.8.0}/plexus/config.py

@@ -49,8 +49,8 @@ CONFIG_DIR = Path.home() / ".plexus"
 CONFIG_FILE = CONFIG_DIR / "config.json"
 
 PLEXUS_ENDPOINT = "https://app.plexus.company"
-PLEXUS_GATEWAY_URL = "https://plexus-gateway.fly.dev"
-PLEXUS_GATEWAY_WS_URL = "wss://plexus-gateway.fly.dev"
+PLEXUS_GATEWAY_URL = "https://gateway.plexus.company"
+PLEXUS_GATEWAY_WS_URL = "wss://gateway.plexus.company"
 
 DEFAULT_CONFIG = {
     "api_key": None,

{plexus_python-0.7.1 → plexus_python-0.8.0}/plexus/ws.py

@@ -62,6 +62,11 @@ class _RegisteredCommand:
     handler: CommandHandler
     description: Optional[str] = None
     params: List[Dict[str, Any]] = field(default_factory=list)
+    # "accept" (default): run overlapping invocations concurrently.
+    # "reject": refuse a new invocation with an error result while a
+    # previous one of the same command is still running.
+    concurrency: str = "accept"
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
 
     def to_manifest(self) -> Dict[str, Any]:
         m: Dict[str, Any] = {"name": self.name}
@@ -127,11 +132,24 @@ class WebSocketTransport:
         *,
         description: Optional[str] = None,
         params: Optional[List[Dict[str, Any]]] = None,
+        concurrency: str = "accept",
     ) -> None:
         """Register a command handler. Must be called before start() to be
-        advertised in the auth frame."""
+        advertised in the auth frame.
+
+        concurrency controls what happens when a command arrives while a
+        previous invocation of the *same* command is still running:
+            "accept" (default) — run it concurrently on a new thread.
+            "reject"           — refuse it with an error result until the
+                                 in-flight invocation finishes.
+        """
+        if concurrency not in ("accept", "reject"):
+            raise ValueError(
+                f"concurrency must be 'accept' or 'reject', got {concurrency!r}"
+            )
         self._commands[name] = _RegisteredCommand(
-            name=name, handler=handler, description=description, params=params or []
+            name=name, handler=handler, description=description,
+            params=params or [], concurrency=concurrency,
         )
 
     def start(self) -> None:
@@ -371,13 +389,42 @@ class WebSocketTransport:
             })
             return
 
+        # concurrency="reject": if an invocation is already running, refuse
+        # this one immediately rather than starting a second in parallel.
+        holds_lock = False
+        if reg.concurrency == "reject":
+            if not reg._lock.acquire(blocking=False):
+                self._send_frame({
+                    "type": "command_result",
+                    "id": cmd_id,
+                    "command": command,
+                    "event": "error",
+                    "error": f"command already in progress: {command}",
+                })
+                return
+            holds_lock = True
+
         # 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()
+        try:
+            threading.Thread(
+                target=self._run_handler,
+                args=(reg, cmd_id, command, params, holds_lock),
+                daemon=True,
+            ).start()
+        except Exception as e:
+            # Thread creation failed (e.g. resource exhaustion). Release the
+            # concurrency lock so the command isn't wedged as "in progress",
+            # and report the failure rather than leaving it silently un-acked.
+            if holds_lock:
+                reg._lock.release()
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": f"failed to start command handler: {e}",
+            })
 
     def _run_handler(
         self,
@@ -385,6 +432,7 @@ class WebSocketTransport:
         cmd_id: str,
         command: str,
         params: Dict[str, Any],
+        holds_lock: bool = False,
     ) -> None:
         try:
             result = reg.handler(command, params)
@@ -397,6 +445,11 @@ class WebSocketTransport:
                 "error": str(e),
             })
             return
+        finally:
+            # Release the concurrency lock (if held) as soon as the handler
+            # returns, regardless of success or failure.
+            if holds_lock:
+                reg._lock.release()
         self._send_frame({
             "type": "command_result",
             "id": cmd_id,

{plexus_python-0.7.1 → plexus_python-0.8.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.7.1"
+version = "0.8.0"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.10"
 authors = [
-    { name = "Plexus", email = "hello@plexus.dev" }
+    { name = "Plexus", email = "info@plexus.company" }
 ]
 keywords = ["telemetry", "iot", "hardware", "observability", "fleet", "monitoring"]
 classifiers = [
@@ -41,8 +41,8 @@ dev = ["pytest>=9.0.3", "pytest-cov", "ruff", "websockets>=12", "opencv-python-h
 plexus = "plexus.cli:main"
 
 [project.urls]
-Homepage = "https://plexus.dev"
-Documentation = "https://docs.plexus.dev"
+Homepage = "https://plexus.company"
+Documentation = "https://docs.plexus.company"
 Repository = "https://github.com/plexus-oss/plexus-python"
 Issues = "https://github.com/plexus-oss/plexus-python/issues"
 

{plexus_python-0.7.1 → plexus_python-0.8.0}/tests/test_ws.py

@@ -255,6 +255,135 @@ def test_handler_exception_returns_error(gateway):
         t.stop()
 
 
+def test_reject_concurrency_refuses_overlap(gateway):
+    release = threading.Event()
+    started = threading.Event()
+
+    def slow(name, params):
+        started.set()
+        release.wait(timeout=3)
+        return {"done": True}
+
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url=_url(gateway.port),
+    )
+    t.register_command("init", slow, concurrency="reject")
+    t.start()
+    try:
+        assert t.wait_authenticated(timeout=3)
+
+        # First invocation starts and blocks inside the handler.
+        gateway.send_command_sync("cmd-1", "init", {})
+        assert started.wait(timeout=3)
+
+        # Second invocation arrives while the first is still running.
+        gateway.send_command_sync("cmd-2", "init", {})
+
+        # cmd-2 is acked, then rejected with an error — the handler never runs
+        # a second time.
+        assert _wait_until(lambda: any(
+            m.get("type") == "command_result"
+            and m.get("id") == "cmd-2"
+            and m.get("event") == "error"
+            for m in gateway.received
+        ))
+        err = next(
+            m for m in gateway.received
+            if m.get("type") == "command_result"
+            and m.get("id") == "cmd-2" and m.get("event") == "error"
+        )
+        assert "already in progress" in err["error"]
+
+        # Let the first finish; it still returns its result normally.
+        release.set()
+        assert _wait_until(lambda: any(
+            m.get("type") == "command_result"
+            and m.get("id") == "cmd-1" and m.get("event") == "result"
+            for m in gateway.received
+        ))
+
+        # A fresh invocation after the first completes is accepted again.
+        gateway.send_command_sync("cmd-3", "init", {})
+        assert _wait_until(lambda: any(
+            m.get("type") == "command_result"
+            and m.get("id") == "cmd-3" and m.get("event") == "result"
+            for m in gateway.received
+        ))
+    finally:
+        release.set()
+        t.stop()
+
+
+def test_accept_concurrency_allows_overlap(gateway):
+    release = threading.Event()
+    active = []
+    lock = threading.Lock()
+
+    def slow(name, params):
+        with lock:
+            active.append(1)
+        release.wait(timeout=3)
+        return {"done": True}
+
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url=_url(gateway.port),
+    )
+    # Default concurrency is "accept".
+    t.register_command("init", slow)
+    t.start()
+    try:
+        assert t.wait_authenticated(timeout=3)
+        gateway.send_command_sync("cmd-1", "init", {})
+        gateway.send_command_sync("cmd-2", "init", {})
+        # Both handlers run at the same time (neither has returned yet).
+        assert _wait_until(lambda: len(active) == 2)
+    finally:
+        release.set()
+        t.stop()
+
+
+def test_reject_releases_lock_if_thread_start_fails(monkeypatch):
+    import plexus.ws as wsmod
+
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url="ws://127.0.0.1:1",
+    )
+    t.register_command("init", lambda n, p: None, concurrency="reject")
+
+    class _BoomThread:
+        def __init__(self, *a, **k):
+            pass
+
+        def start(self):
+            raise RuntimeError("cannot start thread")
+
+    monkeypatch.setattr(wsmod.threading, "Thread", _BoomThread)
+
+    # Dispatch directly (no socket needed; _send_frame no-ops while _ws is None).
+    # The failed thread start must not leave the concurrency lock held.
+    t._handle_command({"id": "cmd-1", "command": "init", "params": {}})
+
+    reg = t._commands["init"]
+    assert reg._lock.acquire(blocking=False), "lock leaked after thread start failure"
+    reg._lock.release()
+
+
+def test_register_command_rejects_bad_concurrency(gateway):
+    t = WebSocketTransport(
+        api_key="plx_test_abc",
+        source_id="drone-001",
+        ws_url=_url(gateway.port),
+    )
+    with pytest.raises(ValueError, match="concurrency"):
+        t.register_command("x", lambda n, p: None, concurrency="bogus")
+
+
 def test_ensure_device_path():
     from plexus.ws import _ensure_device_path
     assert _ensure_device_path("wss://foo") == "wss://foo/ws/device"