iowap-node 2.3.20__py3-none-any.whl

nodes/common/cli/cli_bridge.py

@@ -0,0 +1,264 @@
+"""CLI bridge subcommands — upload/download large files via temp bridge routes (T-153).
+
+The bridge way (T-129) streams big files directly storage<->caller instead
+of buffering them through the relay or the artifact store. A caller opens
+a channel by submitting a bridge task (``storage.upload_channel`` /
+``storage.download_channel``, or the backup variants ``backup.create``
+``mode=bridge`` / ``backup.restore``), waits for the stage to complete,
+extracts the public ``upload_url`` / ``download_url``, then streams the
+file against that URL chunkwise.
+
+Handler signatures are plain ``(client, args) -> int``; the
+``node_cli.with_client`` decorator is applied at parser-registration time
+in the facade.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from nodes.common.relay_client import RelayClient
+
+# Chunk size for streaming upload/download (64 KB, same as the storage
+# node writes with).
+_CHUNK = 64 * 1024
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+def _find_result(data: dict[str, Any]) -> dict[str, Any] | None:
+    """Return the first completed stage's result from a task fetch.
+
+    T-005b Response Envelope (iowap-node >= 2.3.12): handler_runner
+    normalizes conforming handler stdout to the Response Envelope and
+    passes it through VERBATIM, so ``stages[].result`` can BE the whole
+    envelope ``{"status": ..., "result": {...}, "error": ...}`` (plus the
+    ``_handler`` debug dict) instead of the flat inner result the
+    pre-T-005b CLI consumers expect. Unwrap exactly one envelope layer;
+    legacy flat results pass through unchanged. An envelope with
+    ``status: "error"`` or a set ``error`` yields None (failed work).
+    """
+    for s in data.get("stages", []):
+        if s.get("status") == "completed" and s.get("result"):
+            res = s["result"]
+            is_envelope = isinstance(res, dict) and (
+                "_handler" in res or {"status", "result", "error"} <= set(res)
+            )
+            if is_envelope:
+                if res.get("status") == "error" or res.get("error"):
+                    return None
+                inner = res.get("result")
+                return inner if isinstance(inner, dict) else {}
+            return res
+    return None
+
+
+def _wait_for_result(client: RelayClient, task_id: str, interval: int) -> dict[str, Any] | None:
+    """Poll a task until it reaches a terminal state; return the completed
+    stage result (or None on failure/not-found)."""
+    while True:
+        data = client.get_task(task_id)
+        if "error" in data:
+            print(f"Task {task_id}: {data['error']}", file=sys.stderr)
+            return None
+        task = data.get("task", {})
+        status = task.get("status", "unknown")
+        if status in ("completed", "failed", "timed_out", "cancelled"):
+            if status != "completed":
+                print(f"Task {task_id} — {status}", file=sys.stderr)
+                return None
+            return _find_result(data)
+        print(f"\r⏳ {status}...", end="", flush=True)
+        time.sleep(max(1, interval))
+
+
+def _bearer(client: RelayClient) -> dict[str, str]:
+    """Authorization header for reaching the caller-authenticated bridge route."""
+    if not client.token:
+        print("no runtime token available", file=sys.stderr)
+        raise SystemExit(1)
+    return {"Authorization": f"Bearer {client.token}"}
+
+
+# ---------------------------------------------------------------------------
+# bridge upload
+# ---------------------------------------------------------------------------
+
+
+def _cmd_bridge_upload(client: RelayClient, args) -> int:
+    file_path = Path(args.file)
+    if not file_path.is_file():
+        print(f"file not found: {file_path}", file=sys.stderr)
+        return 2
+
+    # Choose the bridge task to open the channel: storage or backup.
+    if args.backup:
+        payload: dict[str, Any] = {
+            "source": args.source or file_path.name,
+            "type": args.type or "full",
+            "mode": "bridge",
+            # T-162: preserve the original filename so a restore writes it
+            # back with the right name/suffix.
+            "filename": file_path.name,
+        }
+        capability = "backup.create"
+    else:
+        payload = {"channel_id": args.channel} if args.channel else {}
+        capability = "storage.upload_channel"
+
+    resp = client.submit_simple_task(capability, payload, name=args.name or "",
+                                     priority=args.priority)
+    task_id = resp.get("task_id") or resp.get("id")
+    if not task_id:
+        print(f"no task_id in submit response: {resp}", file=sys.stderr)
+        return 1
+
+    result = _wait_for_result(client, str(task_id), args.interval)
+    if result is None:
+        return 1
+
+    url = result.get("upload_url")
+    if not url:
+        print(f"no upload_url in result: {result}", file=sys.stderr)
+        return 1
+
+    # Stream the file chunkwise to the bridge URL (relay proxies it).
+    # T-162: send the original filename so the storage node preserves it
+    # (instead of storing under the opaque channel id / data.bin).
+    headers = _bearer(client)
+    headers["X-Filename"] = file_path.name
+    try:
+        with file_path.open("rb") as f, httpx.stream(
+            "POST", url, headers=headers, content=f,
+            timeout=httpx.Timeout(30.0, read=None),
+        ) as r:
+            r.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        print(f"bridge upload failed ({exc.response.status_code}): "
+              f"{exc.response.text}", file=sys.stderr)
+        return 1
+    except httpx.HTTPError as exc:
+        print(f"bridge upload failed: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps({"status": "uploaded", "path": str(file_path),
+                          "size_bytes": file_path.stat().st_size,
+                          "channel_id": result.get("channel_id"),
+                          "backup_id": result.get("backup_id")}, default=str))
+    else:
+        tag = result.get("backup_id") or result.get("channel_id") or ""
+        suffix = f" ({tag})" if tag else ""
+        print(f"✅ Uploaded {file_path.stat().st_size} bytes via bridge{suffix}")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# bridge download
+# ---------------------------------------------------------------------------
+
+
+def _cmd_bridge_download(client: RelayClient, args) -> int:
+    if args.backup:
+        capability = "backup.restore"
+        payload: dict[str, Any] = {"backup_id": args.backup}
+    elif args.channel:
+        capability = "storage.download_channel"
+        payload = {"channel_id": args.channel}
+    else:
+        print("bridge download requires --channel <id> or --backup <id>", file=sys.stderr)
+        return 2
+
+    resp = client.submit_simple_task(capability, payload, name=args.name or "",
+                                     priority=args.priority)
+    task_id = resp.get("task_id") or resp.get("id")
+    if not task_id:
+        print(f"no task_id in submit response: {resp}", file=sys.stderr)
+        return 1
+
+    result = _wait_for_result(client, str(task_id), args.interval)
+    if result is None:
+        return 1
+
+    out_path = args.output
+    # NOTE: when out_path is None we do NOT derive a default here — the
+    # storage node echoes the original filename in the X-Filename response
+    # header (T-162), which is only known after the stream starts. We set
+    # the default inside the stream block below, falling back to the
+    # channel/backup id.
+
+    # Small backups may come back inline as data_base64 — write that directly.
+    if "data_base64" in result and not result.get("download_url"):
+        if out_path is None:
+            # Inline path: no X-Filename header, but the backup manifest
+            # carries the original filename (T-162).
+            out_path = Path(
+                result.get("filename")
+                or result.get("channel_id")
+                or result.get("backup_id")
+                or "download"
+            )
+        try:
+            out_path.write_bytes(base64.b64decode(result["data_base64"]))
+        except Exception as exc:  # noqa: BLE001
+            print(f"failed to write inline data: {exc}", file=sys.stderr)
+            return 1
+        if args.json:
+            print(json.dumps({"status": "downloaded", "path": str(out_path),
+                              "size_bytes": out_path.stat().st_size}, default=str))
+        else:
+            print(f"✅ Downloaded {out_path.stat().st_size} bytes to {out_path}")
+        return 0
+
+    url = result.get("download_url")
+    if not url:
+        print(f"no download_url in result: {result}", file=sys.stderr)
+        return 1
+
+    # Stream the response chunkwise to the output file. When no --output
+    # was given, restore the original filename (T-162): prefer the backup
+    # manifest's filename (result.filename), then the channel's X-Filename
+    # response header, then fall back to the channel/backup id.
+    try:
+        with httpx.stream(
+            "GET", url, headers=_bearer(client), timeout=httpx.Timeout(30.0, read=None)
+        ) as r:
+            r.raise_for_status()
+            if out_path is None:
+                header_name = r.headers.get("x-filename")
+                out_path = Path(
+                    result.get("filename")
+                    or header_name
+                    or result.get("channel_id")
+                    or result.get("backup_id")
+                    or "download"
+                )
+            total = 0
+            with out_path.open("wb") as f:
+                for chunk in r.iter_bytes(chunk_size=_CHUNK):
+                    f.write(chunk)
+                    total += len(chunk)
+    except httpx.HTTPStatusError as exc:
+        print(f"bridge download failed ({exc.response.status_code}): "
+              f"{exc.response.text}", file=sys.stderr)
+        return 1
+    except httpx.HTTPError as exc:
+        print(f"bridge download failed: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps({"status": "downloaded", "path": str(out_path),
+                          "size_bytes": out_path.stat().st_size}, default=str))
+    else:
+        print(f"✅ Downloaded {out_path.stat().st_size} bytes to {out_path}")
+    return 0

nodes/common/cli/cli_capabilities.py

@@ -0,0 +1,229 @@
+"""CLI capabilities subcommands — list/validate/publish/diff/current/server/info (T-117 split).
+
+Constants ``ACTIVE_PATH`` and ``PROFILES_DIR`` are referenced lazily via
+``node_config`` (``_nc.ACTIVE_PATH`` / ``_nc.PROFILES_DIR``) so the
+``cl.ACTIVE_PATH`` / ``cl.PROFILES_DIR`` monkeypatches applied by the test
+fixture take effect. ``PID_PATH`` (CLI-specific, lives in the facade) is
+referenced lazily via ``node_cli.PID_PATH`` at call time — this is the
+one tolerated circular access because it only resolves inside a handler
+body, after ``node_cli`` is fully initialised. ``node_daemon.PID_PATH``
+(SSE daemon) is resolved the same lazy way inside the publish handler
+(t_c214ca25: the SSE daemon's pid file must be probed for hot-reload).
+
+The ``with_client``-decorated handlers (server/info) keep the plain
+``(client, args) -> int`` signature; the decorator is applied at
+parser-registration time in the facade.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import nodes.common.node_cli as _cli
+from nodes.common import node_config as _nc
+from nodes.common import node_utils as _nu
+from nodes.common.node_config import (
+    CapabilityValidationError,
+    current_profile_name,
+    diff_profiles,
+    list_profiles,
+    load_profile,
+    profile_path,
+    publish_profile,
+    validate_profile,
+)
+from nodes.common.relay_client import RelayClient, _setup_logging
+
+
+def _cmd_capabilities_list(args) -> int:  # noqa: ARG001
+    profiles = list_profiles()
+    if not profiles:
+        print("(no profiles in %s)" % _nc.PROFILES_DIR)
+        return 0
+    active = current_profile_name()
+    for p in profiles:
+        marker = "*" if active and (p.stem == active or p.name == active) else " "
+        print(f"{marker} {p.stem}")
+    return 0
+
+
+def _cmd_capabilities_validate(args) -> int:
+    _setup_logging(args.log_level)
+    target = args.profile
+    if target is None:
+        if not _nc.ACTIVE_PATH.exists():
+            print("no active profile and no profile name given", file=sys.stderr)
+            return 1
+        path = _nc.ACTIVE_PATH
+        target = "active"
+    else:
+        path = profile_path(target)
+    try:
+        caps = validate_profile(path)
+    except CapabilityValidationError as exc:
+        print(f"INVALID {target}: {exc}", file=sys.stderr)
+        return 1
+    print(f"OK {target} ({len(caps)} capability{'ies' if len(caps) != 1 else ''})")
+    for c in caps:
+        print(f"  - {c['name']} v{c['version']} "
+              f"auto_publish={c['auto_publish']} claimable={c['claimable']} "
+              f"max_parallel={c['max_parallel']} timeout={c['timeout']}")
+    return 0
+
+
+def _cmd_capabilities_publish(args) -> int:
+    _setup_logging(args.log_level)
+    try:
+        active = publish_profile(args.profile)
+    except CapabilityValidationError as exc:
+        print(f"publish FAILED: {exc}", file=sys.stderr)
+        return 1
+    # Best-effort SIGHUP to any running daemon. The SSE daemon writes
+    # node-daemon.pid; the legacy polling daemon writes node-cli.pid —
+    # both install SIGHUP handlers, so notify every live pid file
+    # (t_c214ca25: the old code only probed node-cli.pid and always took
+    # the "daemon not running" branch on SSE-only nodes).
+    from nodes.common.node_daemon import PID_PATH as _DAEMON_PID_PATH
+
+    pids = _nu.sighup_pid_files([_DAEMON_PID_PATH, _cli.PID_PATH])
+    if pids:
+        print(f"published '{args.profile}' -> {active} (sent SIGHUP to pid {', '.join(str(p) for p in pids)})")
+    else:
+        print(f"published '{args.profile}' -> {active} (daemon not running)")
+    return 0
+
+
+def _cmd_capabilities_diff(args) -> int:
+    _setup_logging(args.log_level)
+    if args.profile is None:
+        if not _nc.ACTIVE_PATH.exists():
+            print("no active profile and no profile name given", file=sys.stderr)
+            return 1
+        working_path = _nc.ACTIVE_PATH
+        working_label = "active"
+    else:
+        working_path = profile_path(args.profile)
+        working_label = args.profile
+    try:
+        working = load_profile(working_path)
+    except CapabilityValidationError as exc:
+        print(f"working profile invalid: {exc}", file=sys.stderr)
+        return 1
+    if _nc.ACTIVE_PATH.exists():
+        try:
+            active = load_profile(_nc.ACTIVE_PATH)
+        except CapabilityValidationError as exc:
+            print(f"active profile invalid: {exc}", file=sys.stderr)
+            return 1
+    else:
+        active = []
+    diff = diff_profiles(active, working)
+    if not diff["added"] and not diff["removed"] and not diff["changed"]:
+        print(f"no differences between active and {working_label}")
+        return 0
+    print(f"diff active -> {working_label}:")
+    for c in diff["added"]:
+        print(f"+ {c['name']} v{c['version']}")
+    for name in diff["removed"]:
+        print(f"- {name}")
+    for ch in diff["changed"]:
+        print(f"~ {ch['name']}:")
+        _print_cap_diff(ch["old"], ch["new"])
+    return 0
+
+
+def _print_cap_diff(old: dict[str, Any], new: dict[str, Any]) -> None:
+    keys = ("version", "auto_publish", "claimable", "handler", "max_parallel", "timeout")
+    for k in keys:
+        ov, nv = old.get(k), new.get(k)
+        if ov != nv:
+            print(f"    {k}: {ov!r} -> {nv!r}")
+
+
+def _cmd_capabilities_current(args) -> int:  # noqa: ARG001
+    name = current_profile_name()
+    if name is None:
+        print("(no active profile set)")
+        return 1
+    print(name)
+    return 0
+
+
+def _cmd_capabilities_server(client: RelayClient, args) -> int:
+    """Query capabilities from the relay server (all registered nodes)."""
+    try:
+        resp = client._get_with_retry("/relay/v2/discovery/capabilities")
+        resp.raise_for_status()
+        data = resp.json()
+    except Exception as exc:
+        print(f"failed to query server capabilities: {exc}", file=sys.stderr)
+        return 1
+
+    caps = data.get("capabilities", data) if isinstance(data, dict) else data
+    if args.json:
+        print(json.dumps(caps, default=str))
+        return 0
+    if not caps:
+        print("(no capabilities registered on the server)")
+        return 0
+
+    print(f"Server capabilities ({len(caps)} total):\n")
+    for c in caps:
+        name = c.get("name", "?")
+        ver = c.get("version", "?")
+        avail = c.get("available", False)
+        nodes = c.get("nodes", [])
+        status = "✅" if avail else "❌"
+        node_names = ", ".join(
+            f"{n.get('node_name', '?')} ({n.get('node_id', '?')})" for n in nodes
+        ) if nodes else "(no nodes)"
+        print(f"  {status} {name:20} v{ver:8}  [{node_names}]")
+        desc = c.get("description")
+        if desc:
+            print(f"     {desc}")
+        schema = c.get("input_schema")
+        if schema:
+            print(f"     Input: {json.dumps(schema, indent=6)}")
+        print()
+    return 0
+
+
+def _cmd_capabilities_info(client: RelayClient, args) -> int:
+    """Show detailed info for a single capability registered on the relay."""
+    try:
+        resp = client._get_with_retry(f"/relay/v2/discovery/capabilities/{args.name}")
+        if resp.status_code == 404:
+            print(f"Capability '{args.name}' not found.")
+            return 1
+        resp.raise_for_status()
+        cap = resp.json()
+    except Exception as exc:
+        print(f"failed to query capability: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(cap, default=str))
+        return 0
+    print(f"Name:        {cap.get('name', '?')}")
+    print(f"Type:        {cap.get('type', '-')}")
+    print(f"Version:     {cap.get('version', '?')}")
+    print(f"Available:   {'yes' if cap.get('available', False) else 'no'}")
+    desc = cap.get("description")
+    if desc:
+        print(f"Description: {desc}")
+    schema = cap.get("input_schema")
+    if schema:
+        print("Input Schema:")
+        print(json.dumps(schema, indent=2))
+    nodes = cap.get("nodes", [])
+    if nodes:
+        print(f"\nNodes ({len(nodes)}):")
+        for n in nodes:
+            print(
+                f"  - {n.get('node_name', '?')} ({n.get('node_id', '?')}) "
+                f"(load={n.get('load', 0):.1f}, "
+                f"queue={n.get('queue_depth', 0)})"
+            )
+    return 0

nodes/common/cli/cli_docs.py

@@ -0,0 +1,122 @@
+"""CLI docs subcommand — read relay documentation (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.
+"""
+
+from __future__ import annotations
+
+import html as html_mod
+import json
+import re as _re
+import sys
+
+import httpx
+
+from nodes.common.relay_client import RelayClient
+
+
+def _html_to_text(html: str) -> str:
+    """Best-effort conversion of an HTML document to terminal-friendly text.
+
+    The docs endpoint serves rendered Markdown as HTML. On a headless node
+    we want something readable in the terminal, so we strip tags, expand
+    block elements to newlines, decode the common entities, and collapse
+    excess blank lines. This is intentionally simple — it does not aim to
+    reproduce a full browser.
+    """
+    # Drop <head>…</head> (style/title) entirely.
+    html = _re.sub(r"<head\b.*?</head>", "", html, flags=_re.S | _re.I)
+    # Drop <style>…</style> and <script>…</script>.
+    html = _re.sub(r"<(style|script)\b.*?</\1>", "", html, flags=_re.S | _re.I)
+    # Block-level elements → surrounding newlines.
+    block_tags = (
+        "p", "br", "div", "section", "article", "header", "footer",
+        "h1", "h2", "h3", "h4", "h5", "h6",
+        "ul", "ol", "li", "pre", "blockquote", "table", "tr",
+    )
+    html = _re.sub(
+        rf"</?({ '|'.join(block_tags) })\b[^>]*>",
+        "\n",
+        html,
+        flags=_re.I,
+    )
+    # <td>/<th> → tab separator, <hr> → rule.
+    html = _re.sub(r"</?(td|th)\b[^>]*>", "\t", html, flags=_re.I)
+    html = _re.sub(r"<hr\b[^>]*/?>", "\n----\n", html, flags=_re.I)
+    # Code spans keep their text only.
+    html = _re.sub(r"</?code\b[^>]*>", "", html, flags=_re.I)
+    # Strip all remaining tags.
+    html = _re.sub(r"<[^>]+>", "", html)
+    # Decode HTML entities (&amp; &lt; …).
+    html = html_mod.unescape(html)
+    # Collapse runs of whitespace inside lines, keep newlines.
+    html = _re.sub(r"[ \t]+", " ", html)
+    html = _re.sub(r" *\n *", "\n", html)
+    # Trim leading whitespace per line.
+    html = "\n".join(line.rstrip() for line in html.splitlines())
+    # Collapse 3+ blank lines to 2.
+    html = _re.sub(r"\n{3,}", "\n\n", html)
+    return html.strip()
+
+
+def _cmd_docs(client: RelayClient, args) -> int:
+    """node-cli docs [<name>] — read relay documentation from the server.
+
+    Without an argument, lists all public documents (name + URL).
+    With a name, fetches the document and prints it as readable text.
+    """
+    try:
+        if args.name:
+            resp = client._get_with_retry(f"/relay/v2/docs/{args.name}")
+            if resp.status_code == 404:
+                print(f"Document '{args.name}' not found.", file=sys.stderr)
+                return 1
+            resp.raise_for_status()
+            body = resp.text
+            ctype = resp.headers.get("content-type", "")
+            if "html" in ctype.lower() or body.lstrip().lower().startswith("<!doctype"):
+                print(_html_to_text(body))
+            else:
+                # Server returned JSON with content/markdown, or raw text.
+                try:
+                    data = resp.json()
+                    if isinstance(data, dict):
+                        text = data.get("content") or data.get("markdown")
+                        if text:
+                            print(text)
+                            return 0
+                    if args.json:
+                        print(json.dumps(data, default=str))
+                        return 0
+                    print(json.dumps(data, indent=2, default=str))
+                except (json.JSONDecodeError, ValueError):
+                    print(body)
+            return 0
+
+        # List all docs.
+        resp = client._get_with_retry("/relay/v2/docs")
+        resp.raise_for_status()
+        data = resp.json()
+        docs = data if isinstance(data, list) else data.get("docs", [])
+        if args.json:
+            print(json.dumps(docs, default=str))
+            return 0
+        print(f"Relay documentation ({len(docs)} pages):\n")
+        for doc in docs:
+            name = doc.get("name") or doc.get("title", "?")
+            url = doc.get("url", "")
+            available = doc.get("available", True)
+            marker = "📄" if available else "🚫"
+            print(f"  {marker} {name}")
+            if url:
+                print(f"     {url}")
+            print()
+        return 0
+    except httpx.HTTPStatusError as exc:
+        print(
+            f"docs request failed: {exc.response.status_code} {exc.response.text}",
+            file=sys.stderr,
+        )
+        return 1