iowap-node 2.3.20__py3-none-any.whl

nodes/common/cli/cli_node.py

@@ -0,0 +1,249 @@
+"""CLI node subcommands — list/info/busy/idle/clear-status/status (T-117 split).
+
+Handler signatures are plain ``(client, args) -> int``; the
+``node_cli.with_client`` decorator is applied at parser-registration time
+in the facade. ``log`` is referenced lazily via ``node_cli.log`` (the
+facade logger) so this module does not need its own logger instance and
+stays decoupled.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import nodes.common.node_cli as _cli
+from nodes.common.node_config import load_active_profile, load_active_status, write_active_status
+from nodes.common.node_utils import load_meta
+from nodes.common.relay_client import RelayClient
+
+
+def _cmd_node_list(client: RelayClient, args) -> int:
+    """List all nodes registered on the relay server."""
+    try:
+        resp = client._get_with_retry("/relay/v2/discovery/nodes")
+        resp.raise_for_status()
+        data = resp.json()
+    except Exception as exc:
+        print(f"failed to query nodes: {exc}", file=sys.stderr)
+        return 1
+
+    nodes = data.get("nodes", [])
+    if args.json:
+        print(json.dumps(nodes, default=str))
+        return 0
+    if not nodes:
+        print("(no nodes registered on the server)")
+        return 0
+
+    print(f"Nodes ({len(nodes)} total):\n")
+    for n in nodes:
+        nid = n.get("node_id", "?")
+        name = n.get("node_name", "?")
+        status = n.get("status", "?")
+        avail = "✅" if n.get("available", False) else "❌"
+        endpoint = n.get("endpoint", "-")
+        role = n.get("role", "-")
+        caps_raw = n.get("capabilities", "")
+        caps = ", ".join(c.get("name", "?") for c in caps_raw) if isinstance(caps_raw, list) else str(caps_raw)[:60]
+        last_seen = n.get("last_seen", "?")[:19] if n.get("last_seen") else "?"
+        print(f"  {avail} {name:20}  ID={nid}")
+        print(f"      Status:   {status:10} Role: {role}")
+        print(f"      Endpoint: {endpoint}")
+        print(f"      Last:     {last_seen}")
+        print(f"      Caps:     {caps}")
+        # T-072: show node-level description (truncated for the list view).
+        desc = n.get("description", "")
+        if desc:
+            print(f"      Desc:     {desc[:60]}{'...' if len(desc) > 60 else ''}")
+        print()
+    return 0
+
+
+def _cmd_node_info(client: RelayClient, args) -> int:
+    """Show detailed info for a single node."""
+    try:
+        resp = client._get_with_retry("/relay/v2/discovery/nodes?status=all")
+        resp.raise_for_status()
+        data = resp.json()
+    except Exception as exc:
+        print(f"failed to query nodes: {exc}", file=sys.stderr)
+        return 1
+
+    nodes = data.get("nodes", [])
+    # Some older server versions treat ``status=all`` as a literal status filter
+    # (returning an empty list). Fall back to the unfiltered endpoint so the
+    # command still works for offline/pending nodes.
+    if not nodes:
+        try:
+            resp = client._get_with_retry("/relay/v2/discovery/nodes")
+            resp.raise_for_status()
+            nodes = resp.json().get("nodes", [])
+        except Exception:
+            pass
+    node = None
+    for n in nodes:
+        if n.get("node_id") == args.node_id:
+            node = n
+            break
+
+    if not node:
+        print(f"Node '{args.node_id}' not found.")
+        return 1
+
+    if args.json:
+        print(json.dumps(node, default=str))
+        return 0
+    print(f"Node:        {node.get('node_name', '?')}")
+    print(f"ID:          {node.get('node_id', '?')}")
+    print(f"Status:      {node.get('status', '?')}")
+    print(f"Role:        {node.get('role', '-')}")
+    print(f"Available:   {'yes' if node.get('available', False) else 'no'}")
+    print(f"Endpoint:    {node.get('endpoint', '-')}")
+    print(f"Load:        {node.get('load', 0):.1f}")
+    print(f"Queue Depth: {node.get('queue_depth', 0)}")
+    print(f"Last Seen:   {node.get('last_seen', '?')}")
+    print(f"Registered:  {node.get('registered_at', '?')}")
+    # T-072: show the full node-level description.
+    desc = node.get("description", "")
+    if desc:
+        print(f"Description: {desc}")
+
+    caps_raw = node.get("capabilities", "")
+    if isinstance(caps_raw, list) and caps_raw:
+        print(f"\nCapabilities ({len(caps_raw)}):")
+        for c in caps_raw:
+            cname = c.get("name", "?")
+            cver = c.get("version", "?")
+            cavail = "✅" if c.get("available", False) else "❌"
+            print(f"  {cavail} {cname:25} v{cver}")
+    elif caps_raw:
+        print(f"\nCapabilities: {caps_raw}")
+
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# node busy / idle / status (T-084) — status stored in active YAML profile
+# ---------------------------------------------------------------------------
+
+
+def _save_requested_status(status: str) -> None:
+    """Persist the operator-requested node status into the active YAML profile.
+
+    The heartbeat loop reads the YAML ``status`` field and forwards it
+    to the server on the next heartbeat, where the transition is validated
+    against the central registry. The YAML file is the only source for the
+    daemon so the requested status survives restarts.
+    """
+    write_active_status(status)
+
+
+def _clear_requested_status() -> None:
+    """Remove the operator-requested status so the node returns to auto."""
+    write_active_status(None)
+
+
+def _cmd_node_busy(client: RelayClient, args) -> int:
+    """node-cli node busy — mark this node as busy.
+
+    Persists ``status: busy`` into the meta file so the next heartbeat
+    forwards it to the server. The server validates the transition
+    (online/idle → busy) via the central status registry; an invalid
+    transition is silently ignored on the server side.
+
+    With ``--once`` the daemon is not affected and a single heartbeat
+    carrying the new status is sent immediately.
+    """
+    _save_requested_status("busy")
+    if args.once:
+        caps = load_active_profile()
+        client.heartbeat(caps, {})
+    if args.json:
+        print(json.dumps({"status": "busy", "persisted": True, "once": bool(args.once)}))
+        return 0
+    print("✅ Node marked busy — next heartbeat will forward the new status.")
+    if not args.once:
+        print("   Send SIGHUP or restart the daemon to pick up the change immediately.")
+    return 0
+
+
+def _cmd_node_idle(client: RelayClient, args) -> int:
+    """node-cli node idle — mark this node as idle (available for claims)."""
+    _save_requested_status("idle")
+    if args.once:
+        caps = load_active_profile()
+        client.heartbeat(caps, {})
+    if args.json:
+        print(json.dumps({"status": "idle", "persisted": True, "once": bool(args.once)}))
+        return 0
+    print("✅ Node marked idle — next heartbeat will forward the new status.")
+    if not args.once:
+        print("   Send SIGHUP or restart the daemon to pick up the change immediately.")
+    return 0
+
+
+def _cmd_node_clear_status(client: RelayClient, args) -> int:
+    """node-cli node clear-status — remove an explicit status request.
+
+    After this the node returns to automatic status handling (the
+    server sets it to ``online`` on the next heartbeat and may later
+    flip it to ``busy`` via the auto-busy load tracking).
+    """
+    _clear_requested_status()
+    if args.once:
+        caps = load_active_profile()
+        client.heartbeat(caps, {})
+    if args.json:
+        print(json.dumps({"status": None, "persisted": True, "once": bool(args.once)}))
+        return 0
+    print("✅ Explicit node status cleared — auto handling restored.")
+    return 0
+
+
+def _cmd_node_status(client: RelayClient, args) -> int:
+    """node-cli node status — show the local + server-side node status.
+
+    Reports the operator-requested status from the active YAML profile
+    (if any) and queries the server for the authoritative current
+    status of this node.
+    """
+    meta = load_meta()
+    requested = load_active_status()
+    server_status: Optional[str] = None
+    server_load = None
+    server_queue = None
+    try:
+        resp = client._get_with_retry("/relay/v2/discovery/nodes?status=all")
+        if resp.status_code == 200:
+            nodes = resp.json().get("nodes", [])
+            if not nodes:
+                resp = client._get_with_retry("/relay/v2/discovery/nodes")
+                nodes = resp.json().get("nodes", []) if resp.status_code == 200 else []
+            for n in nodes:
+                if n.get("node_id") == meta.get("node_id"):
+                    server_status = n.get("status")
+                    server_load = n.get("load")
+                    server_queue = n.get("queue_depth")
+                    break
+    except Exception as exc:  # noqa: BLE001
+        _cli.log.warning("could not query server-side node status: %s", exc)
+
+    if args.json:
+        print(json.dumps({
+            "node_id": meta.get("node_id"),
+            "requested_status": requested,
+            "server_status": server_status,
+            "load": server_load,
+            "queue_depth": server_queue,
+        }, default=str))
+        return 0
+    print(f"Node:             {meta.get('node_name', meta.get('node_id', '?'))}")
+    print(f"Requested status: {requested or '(auto)'}")
+    print(f"Server status:    {server_status or '-'}")
+    if server_load is not None:
+        print(f"Server load:      {server_load}")
+    if server_queue is not None:
+        print(f"Server queue:     {server_queue}")
+    return 0

nodes/common/cli/cli_route.py

@@ -0,0 +1,92 @@
+"""CLI route subcommands — register/unregister/list temp bridge routes (T-136).
+
+Handler signatures are plain ``(client, args) -> int``; the
+``node_cli.with_client`` decorator is applied at parser-registration time
+in the facade. Errors are printed to stderr and the command returns 1 so
+the caller (operator or script) sees a clear failure without a logger
+dependency.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from nodes.common.relay_client import RelayClient
+
+
+def _cmd_route_register(client: RelayClient, args) -> int:
+    """node-cli route register — open a temporary bridge route (T-136)."""
+    try:
+        result = client.register_temp_route(
+            path=args.path,
+            method=args.method,
+            upstream=args.upstream,
+            ttl_seconds=args.ttl,
+            channel_id=args.channel,
+            description=args.description or "",
+        )
+    except Exception as exc:  # noqa: BLE001
+        print(f"failed to register route: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(result, default=str))
+        return 0
+    print("✅ Temp route registered")
+    print(f"   Path:        {result.get('path')}")
+    print(f"   Method:      {result.get('method')}")
+    print(f"   Channel:     {result.get('channel_id')}")
+    print(f"   Expires at:  {result.get('expires_at')}")
+    return 0
+
+
+def _cmd_route_unregister(client: RelayClient, args) -> int:
+    """node-cli route unregister — revoke a temp route before its TTL (T-136)."""
+    try:
+        client.unregister_temp_route(path=args.path, method=args.method)
+    except Exception as exc:  # noqa: BLE001
+        print(f"failed to unregister route: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps({"status": "deleted", "path": args.path, "method": args.method}))
+        return 0
+    print("✅ Temp route deleted")
+    print(f"   Path:   {args.path}")
+    print(f"   Method: {args.method}")
+    return 0
+
+
+def _cmd_route_list(client: RelayClient, args) -> int:
+    """node-cli route list — list this node's own routes (T-136)."""
+    try:
+        routes = client.list_temp_routes()
+    except Exception as exc:  # noqa: BLE001
+        print(f"failed to list routes: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(routes, default=str))
+        return 0
+
+    if not routes:
+        print("(no routes registered for this node)")
+        return 0
+
+    print(f"Routes ({len(routes)} total):\n")
+    for r in routes:
+        path = r.get("path", "?")
+        method = r.get("method", "?")
+        auth = r.get("auth", "?")
+        upstream = r.get("upstream", "-")
+        expires = r.get("expires_at") or "permanent"
+        channel = r.get("channel_id") or "-"
+        kind = "temp" if r.get("expires_at") else "perm "
+        print(f"  [{kind}] {method:6} {path}")
+        print(f"          auth:     {auth}")
+        print(f"          upstream: {upstream}")
+        print(f"          channel:  {channel}")
+        print(f"          expires:  {expires}")
+        print()
+    return 0

nodes/common/cli/cli_server.py

@@ -0,0 +1,248 @@
+"""T-178: first-class node registration + unauthenticated server status CLI.
+
+``_cmd_node_register`` needs no RelayClient (registration happens *before*
+any state files exist); the server status commands reuse the T-177
+``probe_server()`` logic at module level so they work without meta/token.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import httpx
+
+import nodes.common.node_cli as _cli
+from nodes.common import node_utils
+from nodes.common.node_utils import save_meta, save_token
+from nodes.common.relay_client import _parse_prometheus_gauges
+
+REGISTER_PATH = "/relay/v2/auth/register"
+DEFAULT_PORT = 8788
+
+
+def normalize_base_url(server: str) -> str:
+    """Normalize a server argument to a usable base URL.
+
+    ``192.0.2.60`` → ``http://192.0.2.60:8788``; a ``host:port`` keeps
+    its port; a full URL is kept as-is (trailing slash stripped).
+    """
+    server = server.strip().rstrip("/")
+    if server.startswith(("http://", "https://")):
+        return server
+    host, sep, port = server.rpartition(":")
+    if sep and port.isdigit():
+        return f"http://{host}:{port}"
+    return f"http://{server}:{DEFAULT_PORT}"
+
+
+# ---------------------------------------------------------------------------
+# node register (T-178)
+# ---------------------------------------------------------------------------
+
+
+def _cmd_node_register(args) -> int:
+    """node-cli node register <server> — register this node and persist state.
+
+    Chicken-and-egg-free: runs without meta/token files and creates them.
+    Never writes anything on failure.
+    """
+    import socket
+
+    base_url = normalize_base_url(args.server)
+    name = args.name or socket.gethostname()
+
+    # Guard: refuse to clobber an existing node identity unless --force.
+    meta_path = node_utils.META_PATH
+    if meta_path.exists() and not args.force:
+        print(
+            f"node state already exists at {meta_path} "
+            f"(node already registered?). Use --force to re-register.",
+            file=sys.stderr,
+        )
+        return 1
+
+    body = {
+        "node_name": name,
+        "endpoint": None,
+        "role": "node",
+        "capabilities": [],
+    }
+    try:
+        resp = httpx.post(f"{base_url}{REGISTER_PATH}", json=body, timeout=args.timeout)
+        resp.raise_for_status()
+        data = resp.json()
+    except httpx.HTTPStatusError as exc:
+        print(
+            f"registration failed: HTTP {exc.response.status_code}: {exc.response.text[:200]}",
+            file=sys.stderr,
+        )
+        return 1
+    except Exception as exc:  # noqa: BLE001
+        print(f"registration failed: {exc}", file=sys.stderr)
+        return 1
+
+    node_id = data.get("node_id")
+    token = data.get("token")
+    if not node_id or not token:
+        print(f"unexpected registration response: {json.dumps(data)[:200]}", file=sys.stderr)
+        return 1
+
+    meta = {
+        "node_id": node_id,
+        "node_name": name,
+        "endpoint": None,
+        "registration_secret": data.get("registration_secret"),
+        "capabilities": [],
+        "base_url": base_url,
+    }
+    save_meta(meta)
+    save_token(token, data.get("expires_at"))
+
+    if args.json:
+        print(json.dumps({"ok": True, **meta, "status": data.get("status", "pending")}, default=str))
+        return 0
+
+    print(f"✅ Node registered: {name} (ID={node_id})")
+    print(f"   Server:  {base_url}")
+    print(f"   Status:  {data.get('status', 'pending')}")
+    if data.get("expires_at"):
+        print(f"   Token:   temporary tp_-token, expires {data['expires_at']}")
+    print()
+    print("   ⏳ Node is pending — an admin must approve it (dashboard or admin API)")
+    print("      before it can claim work.")
+    print("   Next: node-cli capabilities publish <profile> && node-daemon")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# server health / metrics (T-178; probe logic from T-177)
+# ---------------------------------------------------------------------------
+
+
+def probe_server_endpoint(
+    base_url: str,
+    *,
+    timeout: float = 10.0,
+    verify: str | bool = True,
+) -> dict[str, Any]:
+    """GET /health + /ready + /metrics without client state.
+
+    Module-level mirror of ``RelayClient.probe_server()`` (T-177) so the CLI
+    can probe a server *before* the node has meta/token files. Never raises;
+    returns ``{"ok": False, "error": ...}`` on failure.
+    """
+    result: dict[str, Any] = {"ok": False, "error": ""}
+    try:
+        r = httpx.get(f"{base_url}/health", timeout=timeout, verify=verify)
+        r.raise_for_status()
+        health = r.json()
+        result["version"] = health.get("version")
+        result["mode"] = health.get("mode")
+    except Exception as exc:  # noqa: BLE001 — probe must never throw
+        result["error"] = f"health: {exc}"
+        return result
+    try:
+        r = httpx.get(f"{base_url}/ready", timeout=timeout, verify=verify)
+        r.raise_for_status()
+        ready = r.json()
+        result["database"] = ready.get("database")
+        result["scheduler"] = ready.get("scheduler")
+    except Exception as exc:  # noqa: BLE001
+        # /health OK but /ready down → server is up but degraded.
+        result["error"] = f"ready: {exc}"
+    try:
+        r = httpx.get(f"{base_url}/metrics", timeout=timeout, verify=verify)
+        r.raise_for_status()
+        result.update(_parse_prometheus_gauges(r.text))
+    except Exception as exc:  # noqa: BLE001
+        result["error"] = f"metrics: {exc}"
+    result["ok"] = not result["error"]
+    return result
+
+
+def resolve_server(server: str | None, as_json: bool = False) -> str | None:
+    """Resolve the server argument: arg → config file / node state → error."""
+    if server:
+        return normalize_base_url(server)
+    cfg = _cli.load_json(node_utils.CONFIG_PATH, default={}) or {}
+    base = cfg.get("base_url")
+    if not base and node_utils.META_PATH.exists():
+        meta = _cli.load_json(node_utils.META_PATH, default={}) or {}
+        base = meta.get("base_url")
+    if base:
+        return str(base).rstrip("/")
+    msg = "no server given and no base_url in relay_config.json or node state"
+    if as_json:
+        print(json.dumps({"ok": False, "error": msg}))
+    else:
+        print(msg, file=sys.stderr)
+    return None
+
+
+def _fmt_num(val: Any) -> str:
+    """Display helper: 4.0 → '4', 12.87 → '12.87'."""
+    if isinstance(val, float) and val.is_integer():
+        return str(int(val))
+    return str(val)
+
+
+def _cmd_server_health(args) -> int:
+    """node-cli server health [server] — one-shot server status probe."""
+    base_url = resolve_server(args.server, getattr(args, "json", False))
+    if base_url is None:
+        return 1
+    data = probe_server_endpoint(base_url)
+    if args.json:
+        print(json.dumps(data, default=str))
+        return 0 if data["ok"] else 1
+    if not data["ok"]:
+        print(f"❌ Server unreachable: {data['error']}", file=sys.stderr)
+        return 1
+    print(f"✅ {base_url} — IOWAP {data.get('version', '?')} ({data.get('mode', '?')})")
+    print(f"   Database:  {data.get('database', '?')}")
+    print(f"   Scheduler: {data.get('scheduler', '?')}")
+    total = data.get("nodes_total")
+    online = data.get("nodes_online")
+    if total is not None:
+        print(f"   Nodes:     {_fmt_num(online)}/{_fmt_num(total)} online")
+    if data.get("queue_depth") is not None:
+        print(f"   Queue:     {_fmt_num(data.get('queue_depth'))} tasks waiting")
+    completed = data.get("tasks_completed")
+    failed = data.get("tasks_failed")
+    if completed is not None:
+        print(f"   Tasks:     {_fmt_num(completed)} completed, {_fmt_num(failed)} failed")
+    return 0
+
+
+def _cmd_server_metrics(args) -> int:
+    """node-cli server metrics [server] — merged probe dict, Prometheus fields."""
+    base_url = resolve_server(args.server, getattr(args, "json", False))
+    if base_url is None:
+        return 1
+    data = probe_server_endpoint(base_url)
+    if not data["ok"]:
+        msg = f"server unreachable: {data['error']}"
+        if args.json:
+            print(json.dumps({"ok": False, "error": msg}))
+        else:
+            print(f"❌ {msg}", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(data, default=str))
+        return 0
+    print(f"Server metrics ({base_url}):")
+    for key in sorted(data):
+        if key in ("ok", "error"):
+            continue
+        val = data[key]
+        if isinstance(val, dict):
+            print(f"  {key}:")
+            for sub, sv in sorted(val.items()):
+                print(f"    {sub:24} {sv}")
+        elif isinstance(val, float) and val.is_integer():
+            print(f"  {key:28} {int(val)}")
+        else:
+            print(f"  {key:28} {val}")
+    return 0