benchlab-pytools 3.0.0__py3-none-any.whl

benchlab/launcher.py

@@ -0,0 +1,387 @@
+"""BENCHLAB PyTools v2 – Tool Launcher.
+
+Provides helpers to build a standard args namespace from environment
+variables and to launch one or many consumer tools, either in-process
+or in spawned terminal windows.
+"""
+
+import curses
+import importlib
+import inspect
+import logging
+import os
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+import time
+import traceback
+import types as _types
+from typing import List
+
+from .tools import CONSUMER_TOOLS, ensure_tool_dependencies
+from .sources import cleanup_all_services
+
+logger = logging.getLogger("benchlab.launcher")
+
+
+# ──────────────────────────────────────────────────────────────
+# Shared Helpers
+# ──────────────────────────────────────────────────────────────
+
+def _build_args_namespace() -> _types.SimpleNamespace:
+    """Build a standard args namespace from current environment variables."""
+    return _types.SimpleNamespace(
+        source=os.environ.get("BENCHLAB_DATA_SOURCE", "direct"),
+        interval=float(os.environ.get("POLL_INTERVAL", "1.0")),
+        api_url=os.environ.get("BENCHLAB_API_URL", "http://127.0.0.1:8000"),
+        api_port=int(os.environ.get("API_PORT", "8000")),
+        mqtt_broker=os.environ.get("MQTT_BROKER", "localhost"),
+        mqtt_port=int(os.environ.get("MQTT_PORT", "1883")),
+        service_url=os.environ.get(
+            "BENCHLAB_SERVICE_URL", "http://localhost:8585"),
+    )
+
+
+def _monitor_process(tool_name: str, proc: subprocess.Popen) -> None:
+    """Read stderr from a child process and log it to the parent terminal."""
+    for line in proc.stderr:
+        line = line.decode(errors="replace").rstrip()
+        if line:
+            logger.error(f"[{tool_name}] {line}")
+
+
+def _terminate_spawned_process(proc: subprocess.Popen, force: bool) -> None:
+    """Terminate a spawned terminal-window process (and its children).
+
+    os.killpg/os.getpgid don't exist on Windows, so this mirrors
+    ProcessManager's platform branch: taskkill /T kills the whole
+    process tree rooted at the terminal emulator's PID on Windows,
+    while POSIX uses the process group created via preexec_fn=os.setsid.
+    """
+    try:
+        if not proc or proc.poll() is not None:
+            return
+        if sys.platform == "win32":
+            subprocess.run(
+                ["taskkill", "/T", "/F", "/PID", str(proc.pid)],
+                capture_output=True,
+            )
+        else:
+            sig = signal.SIGKILL if force else signal.SIGTERM
+            os.killpg(os.getpgid(proc.pid), sig)
+    except Exception:
+        pass
+
+
+# ──────────────────────────────────────────────────────────────
+# Single-tool Launch (in-process, blocking)
+# ──────────────────────────────────────────────────────────────
+
+def launch_single_tool(tool_id: str) -> None:
+    """Launch a single tool in-process. Blocks until the tool exits."""
+    tool = CONSUMER_TOOLS[tool_id]
+    print(f"Starting {tool['name']}...")
+    print("Press Ctrl+C to stop.")
+
+    args = _build_args_namespace()
+
+    try:
+        ensure_tool_dependencies(tool_id)
+
+        module = importlib.import_module(tool["module"])
+        func = getattr(module, tool["function"])
+
+        if tool_id == "tui":
+            curses.wrapper(lambda stdscr: func(stdscr, None, args))
+        else:
+            sig = inspect.signature(func)
+            if sig.parameters:
+                func(args)
+            else:
+                logger.warning(
+                    f"{tool['name']}: {tool['module']}."
+                    f"{tool['function']} takes no args. "
+                    "Update it to accept an args parameter."
+                )
+                func()
+
+    except KeyboardInterrupt:
+        logger.info(f"{tool['name']} stopped.")
+    except Exception as e:
+        logger.error(f"{tool['name']} failed: {e}")
+        traceback.print_exc()
+
+
+# ──────────────────────────────────────────────────────────────
+# Multi-tool Launch (spawned terminal windows)
+# ──────────────────────────────────────────────────────────────
+
+def _detect_terminal() -> str | None:
+    # Linux terminal candidates
+    linux_candidates = [
+        "ptyxis",
+        "kitty",
+        "alacritty",
+        "gnome-terminal",
+        "konsole",
+        "xfce4-terminal",
+        "x-terminal-emulator",
+        "xterm",
+    ]
+
+    # Windows terminal candidates
+    windows_candidates = [
+        "wt",           # Windows Terminal (default on Windows 11)
+        "WindowsTerminal",
+        "powershell",   # PowerShell (fallback)
+        "cmd",          # Command Prompt (fallback)
+    ]
+
+    user_term = os.environ.get("TERMINAL")
+    if user_term and shutil.which(user_term):
+        return user_term
+
+    # Check platform-specific candidates first
+    if sys.platform == "win32":
+        for term in windows_candidates:
+            if shutil.which(term):
+                return term
+        # Also check Linux terminals that might be installed on Windows (e.g.,
+        # via WSL or standalone)
+        for term in linux_candidates:
+            if shutil.which(term):
+                return term
+    else:
+        for term in linux_candidates:
+            if shutil.which(term):
+                return term
+
+    return None
+
+
+def _spawn_tool_in_terminal(
+        tool_id: str,
+        args: _types.SimpleNamespace) -> subprocess.Popen:
+    """Spawn tool in a new isolated terminal window (Linux-first, robust)."""
+
+    tool = CONSUMER_TOOLS[tool_id]
+    cmd = [
+        sys.executable, "-m", "benchlab",
+        tool["flag"],
+        "--source", args.source,
+        "--api-url", args.api_url,
+        "--api-port", str(args.api_port),
+        "--mqtt-broker", args.mqtt_broker,
+        "--mqtt-port", str(args.mqtt_port),
+        "--service-url", args.service_url,
+    ]
+
+    env = os.environ.copy()
+    term = _detect_terminal()
+    if not term:
+        raise RuntimeError("No valid terminal emulator found")
+
+    title = f"BENCHLAB - {tool['name']}"
+
+    # --- Ptyxis ---
+    if term == "ptyxis":
+        return subprocess.Popen(
+            [term, "-s", "-T", title, "-x", shlex.join(cmd)],
+            env=env,
+            preexec_fn=os.setsid,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- GNOME Terminal ---
+    if term == "gnome-terminal":
+        return subprocess.Popen(
+            [term, "--title", title, "--", *cmd],
+            env=env,
+            preexec_fn=os.setsid,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- KDE Konsole ---
+    if term == "konsole":
+        return subprocess.Popen(
+            [term, "--new-tab", "-p", f"tabtitle={title}", "-e", *cmd],
+            env=env,
+            preexec_fn=os.setsid,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- XFCE Terminal ---
+    if term == "xfce4-terminal":
+        return subprocess.Popen(
+            [
+                term, "--title", title, "--command",
+                f"bash -lc '{shlex.join(cmd)}; exec bash'",
+            ],
+            env=env,
+            preexec_fn=os.setsid,
+            shell=False,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- Kitty ---
+    if term == "kitty":
+        return subprocess.Popen(
+            [term, "--title", title, *cmd],
+            env=env,
+            preexec_fn=os.setsid,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- Alacritty ---
+    if term == "alacritty":
+        return subprocess.Popen(
+            [term, "--title", title, "-e", *cmd],
+            env=env,
+            preexec_fn=os.setsid,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- Windows Terminal (wt) ---
+    if term == "wt":
+        # Windows Terminal inherits window size from default profile
+        # settings. The actual size depends on the user's Windows Terminal
+        # profile configuration.
+        # For guaranteed sizing, users should configure their default profile
+        # with adequate rows/columns in settings.json (profiles.defaults)
+        wt_cmd = ["wt",
+                  "new-tab",
+                  "--title",
+                  title,
+                  sys.executable,
+                  "-m",
+                  "benchlab",
+                  tool["flag"],
+                  "--source",
+                  args.source,
+                  "--api-url",
+                  args.api_url,
+                  "--api-port",
+                  str(args.api_port),
+                  "--mqtt-broker",
+                  args.mqtt_broker,
+                  "--mqtt-port",
+                  str(args.mqtt_port),
+                  "--service-url",
+                  args.service_url]
+        return subprocess.Popen(wt_cmd, env=env, stderr=subprocess.PIPE)
+
+    # --- PowerShell ---
+    if term == "powershell":
+        # Set explicit window size (120x40) to ensure TUI has enough space
+        ps_script = (
+            f'$title = "{title}"; '
+            f'$command = "{shlex.join(cmd)}"; '
+            f'$Host.UI.RawUI.WindowTitle = $title; '
+            f'$Host.UI.RawUI.BufferSize = New-Object '
+            f'System.Management.Automation.Host.Size(120, 9999); '
+            f'$Host.UI.RawUI.WindowSize = New-Object '
+            f'System.Management.Automation.Host.Size(120, 40); '
+            f'Write-Host "Starting BENCHLAB tool..."; '
+            f'Invoke-Expression $command'
+        )
+        return subprocess.Popen(
+            ["powershell", "-NoExit", "-Command", ps_script],
+            env=env,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- Command Prompt (cmd) ---
+    if term == "cmd":
+        return subprocess.Popen(
+            ["start", title, "cmd", "/k", shlex.join(cmd)],
+            env=env,
+            shell=True,
+            stderr=subprocess.PIPE,
+        )
+
+    # --- Generic fallback (xterm / x-terminal-emulator) ---
+    return subprocess.Popen(
+        [term, "-T", title, "-e", *cmd],
+        env=env,
+        preexec_fn=os.setsid,
+        stderr=subprocess.PIPE,
+    )
+
+
+def launch_tools_concurrent(
+        tool_ids: List[str],
+        source_ready_delay: float = 2.0) -> None:
+    """Spawn each tool in its own terminal window, then wait until interrupted.
+
+    Args:
+        tool_ids: List of tool IDs to launch.
+        source_ready_delay: Time to wait after source is ready before
+            launching tools (default: 2.0s).
+    """
+    args = _build_args_namespace()
+    processes: dict = {}
+    monitors: list = []
+
+    # Wait for the source to be fully ready before spawning any tools
+    if source_ready_delay > 0:
+        logger.info(
+            f"Waiting {source_ready_delay}s for data source to stabilize "
+            "before launching tools...")
+        time.sleep(source_ready_delay)
+
+    for idx, tid in enumerate(tool_ids):
+        tool = CONSUMER_TOOLS[tid]
+        logger.info(f"Launching {tool['name']} in terminal...")
+        proc = _spawn_tool_in_terminal(tid, args)
+
+        # Only consider it a failure if the process exited with a non-zero
+        # code. Some terminal launchers (like Windows Terminal 'wt') exit
+        # immediately with code 0 after successfully launching the
+        # terminal window
+        if proc.poll() is not None and proc.returncode != 0:
+            logger.error(
+                f"{tool['name']} terminal failed to launch "
+                f"(exit code {proc.returncode})")
+            continue
+
+        # Graceful launch: wait between tool spawns to avoid overwhelming
+        # the system. First tool launches immediately after source delay,
+        # subsequent tools wait 1 second each
+        if idx < len(tool_ids) - 1:  # Don't sleep after the last tool
+            time.sleep(1.0)
+
+        processes[tid] = proc
+
+        t = threading.Thread(
+            target=_monitor_process,
+            args=(tool["name"], proc),
+            daemon=True,
+        )
+        t.start()
+        monitors.append(t)
+
+    logger.info(
+        "All tools launched in terminals. Press Ctrl+C to stop launcher.")
+
+    try:
+        while True:
+            time.sleep(0.5)
+    except (KeyboardInterrupt, EOFError):
+        logger.info("Stopping all tools...")
+    finally:
+        logger.info("Stopping all tools...")
+
+        for proc in processes.values():
+            _terminate_spawned_process(proc, force=False)
+
+        time.sleep(1)
+
+        for proc in processes.values():
+            _terminate_spawned_process(proc, force=True)
+
+        cleanup_all_services()
+
+    logger.info("Done.")

benchlab/link/.env.EXAMPLE

@@ -0,0 +1,10 @@
+REMOTE_MQTT_HOST=mqtt.benchlab.io
+REMOTE_MQTT_PORT=443
+REMOTE_MQTT_PATH=/mqtt
+REMOTE_MQTT_TRANSPORT=websockets
+REMOTE_MQTT_PROTOCOL=mqtt.MQTTv5
+REMOTE_MQTT_QOS=1
+REMOTE_MQTT_USER=mqtt_user
+REMOTE_MQTT_PASS=mqtt_pass
+CLIENT_UUID=client_uuid
+MQTT_POLL_RATE=2

benchlab/link/README.md

@@ -0,0 +1,172 @@
+# BENCHLAB Link
+
+## Overview
+
+Benchlab Link is a cloud MQTT publisher. It reads telemetry from any local BENCHLAB data source (direct serial, FastAPI, or MQTT) and republishes it as JSON to a remote/cloud MQTT broker — typically BENCHLAB's SaaS broker, for dashboards, fleet monitoring, or other cloud consumers.
+
+It automatically:
+
+- Connects to a local data source via `DataSourceManager` (direct / fastapi / fastapi_custom / mqtt).
+- Polls each discovered device's telemetry snapshot on a background thread.
+- Publishes a JSON payload per device to the remote broker on a configurable interval.
+- Supports TLS and WebSocket transport for the remote connection.
+- Reconnects automatically if the remote broker connection drops.
+- Handles graceful shutdown on Ctrl+C.
+
+## Features
+
+| Feature | Description |
+|---|---|
+| Local source flexibility | Works with any `--source` supported by the rest of the suite (direct, fastapi, fastapi_custom, mqtt). |
+| Cloud MQTT publishing | Publishes one topic per device, built from a configurable `{uid}` topic pattern. |
+| TLS / WebSocket support | Connects over `websockets` (default) or `tcp` transport, with TLS enabled by default. |
+| Auto-reconnect | If the cloud broker connection drops, Link retries every 5 seconds using a fresh client. |
+| Layered configuration | CLI args > environment variables > `.env` file > `link.config` JSON file > built-in defaults. |
+| Graceful shutdown | Stops the poller thread, disconnects from both the local source and the cloud broker on Ctrl+C. |
+
+## Installation
+
+Link is included in BENCHLAB PyTools. It requires `paho-mqtt` (already a dependency of the suite) and whatever the chosen local `--source` requires (e.g. `benchlab-pycore` for `direct`, `requests` for `fastapi`).
+
+## Usage
+
+Run via the main launcher:
+
+```bash
+python -m benchlab -link
+```
+
+By default this connects to the local `direct` data source and publishes to the remote host configured via env/config (see Configuration below). Combine with the usual `--source` flags to choose a different local source:
+
+```bash
+# Read telemetry from a local FastAPI server instead of direct serial
+python -m benchlab -link --source fastapi --api-url http://127.0.0.1:8000
+
+# Read telemetry from local MQTT
+python -m benchlab -link --source mqtt --mqtt-broker localhost --mqtt-port 1883
+```
+
+Cloud connection settings can be passed directly on the command line, overriding any env var / `.env` / `link.config` value:
+
+```bash
+python -m benchlab -link \
+  --remote-host mqtt.benchlab.io \
+  --remote-port 443 \
+  --remote-user my-device-id \
+  --remote-pass "my-secret" \
+  --topic-pattern "benchlab/{uid}/telemetry"
+
+# Disable TLS (e.g. for a local test broker)
+python -m benchlab -link --remote-host localhost --remote-port 1883 --no-tls
+```
+
+CLI flags (from `benchlab/main.py`):
+
+| Flag | Description |
+|---|---|
+| `-link` | Run the cloud MQTT link publisher |
+| `--remote-host` | Cloud MQTT broker hostname (overrides `REMOTE_MQTT_HOST`) |
+| `--remote-port` | Cloud MQTT broker port (default: 443) |
+| `--remote-user` | Cloud MQTT username (overrides `REMOTE_MQTT_USER`) |
+| `--remote-pass` | Cloud MQTT password (overrides `REMOTE_MQTT_PASS`) |
+| `--no-tls` | Disable TLS for the cloud MQTT connection |
+| `--topic-pattern` | MQTT topic pattern with a `{uid}` token (overrides `LINK_TOPIC_PATTERN`) |
+| `--source` | Local data source: `direct` \| `fastapi` \| `fastapi_custom` \| `mqtt` \| `mqtt_custom` |
+| `--api-url` | FastAPI base URL, when `--source fastapi`/`fastapi_custom` |
+| `--mqtt-broker`, `--mqtt-port` | Local MQTT broker, when `--source mqtt`/`mqtt_custom` |
+
+You can also run the module directly with a pre-built `argparse.Namespace` (as `run_link(args)` is called from `main.py`), or invoke `python -m benchlab.link.link_main` to use env-var-only defaults (`BENCHLAB_DATA_SOURCE`, `MQTT_POLL_RATE`, `BENCHLAB_API_URL`, `MQTT_BROKER`, `MQTT_PORT`).
+
+## Configuration
+
+Configuration is resolved with this priority (highest first):
+
+1. CLI args (`--remote-host`, `--no-tls`, etc. — mirrored into env vars by `main.py`'s `_export_link_env()`)
+2. Environment variables
+3. `.env` file in `benchlab/link/` (only sets a var if it isn't already set in the environment)
+4. `link.config` JSON file (`benchlab/link/link.config` by default, or `LINK_CONFIG_PATH`)
+5. Built-in defaults
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `REMOTE_MQTT_HOST` | *(none — required)* | Cloud MQTT broker hostname |
+| `REMOTE_MQTT_PORT` | `443` | Cloud MQTT broker port |
+| `REMOTE_MQTT_USER` | *(none)* | MQTT username |
+| `REMOTE_MQTT_PASS` | *(none)* | MQTT password |
+| `REMOTE_MQTT_PATH` | `/mqtt` | WebSocket path (used when transport is `websockets`) |
+| `REMOTE_MQTT_TRANSPORT` | `websockets` | Transport: `websockets` or `tcp` |
+| `REMOTE_MQTT_PROTOCOL` | `mqtt.MQTTv5` | MQTT protocol version string; `"5"` in the value selects `MQTTv5`, anything else selects `MQTTv311` |
+| `REMOTE_MQTT_QOS` | `1` | QoS level: 0, 1, or 2 |
+| `REMOTE_MQTT_TLS` | `true` | Enable TLS. Set to `false`/`0`/`no` to disable |
+| `CLIENT_UUID` | *(none)* | Device UUID, used to build the default MQTT client ID |
+| `MQTT_POLL_RATE` | `2` | Poll/publish interval in seconds |
+| `LINK_TOPIC_PATTERN` | `benchlab/{uid}/telemetry` | Topic pattern; `{uid}` (device UID) and `{client_uuid}` (from `CLIENT_UUID`) are replaced for each publish |
+| `LINK_CLIENT_ID` | `benchlab-link-<uuid-or-hostname>` | MQTT client ID sent to the broker |
+| `LINK_CONFIG_PATH` | `benchlab/link/link.config` | Override path to the JSON config file |
+
+### `.env` file
+
+Place a `.env` file in `benchlab/link/` with `KEY=VALUE` pairs — copy `.env.EXAMPLE` as a starting point:
+
+```
+REMOTE_MQTT_HOST=mqtt.benchlab.io
+REMOTE_MQTT_PORT=443
+REMOTE_MQTT_PATH=/mqtt
+REMOTE_MQTT_TRANSPORT=websockets
+REMOTE_MQTT_PROTOCOL=mqtt.MQTTv5
+REMOTE_MQTT_QOS=1
+REMOTE_MQTT_USER=mqtt_user
+REMOTE_MQTT_PASS=mqtt_pass
+CLIENT_UUID=client_uuid
+MQTT_POLL_RATE=2
+```
+
+`.env` values only take effect if the corresponding environment variable is not already set (i.e. they are a fallback, not an override).
+
+### `link.config` JSON file
+
+`benchlab/link/link.config` uses the same settings under snake_case keys:
+
+```json
+{
+  "remote_host":      "mqtt.benchlab.io",
+  "remote_port":      443,
+  "remote_user":      "test-device-001",
+  "remote_pass":      "your-mqtt-password",
+  "remote_tls":       true,
+  "topic_pattern":    "benchlab/{uid}/telemetry",
+  "publish_interval": 1.0,
+  "client_id":        "your-client-uuid"
+}
+```
+
+This file is loaded only as a fallback below env vars/`.env`/CLI args, and is `.gitignore`d — create it locally with real credentials, it is never checked in.
+
+### Topic pattern
+
+`topic_pattern` (default `benchlab/{uid}/telemetry`) is formatted per-device with `.format(uid=uid, client_uuid=client_uuid)`, so both `{uid}` (the device's UID) and `{client_uuid}` (from `CLIENT_UUID`/`client_uuid`, empty string if unset) are supported tokens. For example, a deployment can use `clients/{client_uuid}/devices/{uid}/telemetry` to key topics by tenant/client instead of by device alone. Published payloads are `{"uid": <uid>, ...telemetry fields...}`.
+
+## Troubleshooting
+
+**"No remote MQTT host configured"** — `REMOTE_MQTT_HOST` (or `remote_host` in `link.config`, or `--remote-host`) is not set. Link exits immediately without a host.
+
+**"Failed to connect to `<source>` datasource"** — the local data source (direct/fastapi/mqtt) could not be reached. Verify the device is connected (for `direct`) or the FastAPI/MQTT service is running and reachable at the configured URL/broker.
+
+**"Cloud broker disconnected — retrying in 5s"** — the connection to the remote broker dropped; Link automatically reconnects with a fresh client every 5 seconds. Check network connectivity and credentials if this repeats continuously.
+
+**Connection timeout to cloud broker** — verify `REMOTE_MQTT_PORT` matches the transport (443/`websockets`+TLS is typical for BENCHLAB's cloud broker; local test brokers are often 1883/`tcp` with `--no-tls`), and that `REMOTE_MQTT_PATH` is correct when using `websockets` transport.
+
+**Nothing gets published** — Link only publishes devices it currently has a telemetry snapshot for. Confirm the local data source's `list_devices()`/`snapshot()` calls are returning data; check the local source is healthy first (e.g. hit the FastAPI server's `/health` endpoint) before troubleshooting Link itself.
+
+## See Also
+
+- [BENCHLAB PyTools Documentation](../../README.md) - Main PyTools documentation
+- [BENCHLAB Core README](../core/README.md) - `DataSourceManager` and the data source abstraction Link consumes
+- [MQTT Publisher README](../mqtt/README.md) - the local MQTT source Link can read from
+- [FastAPI Telemetry Server README](../restapi/readme.md) - the local FastAPI source Link can read from
+
+## License
+
+Part of BENCHLAB PyTools. See main project license for details.

benchlab/link/__init__.py

@@ -0,0 +1 @@
+# benchlab/link/__init__.py