lager-cli 0.34.2__tar.gz → 0.34.4__tar.gz

{lager_cli-0.34.2/lager_cli.egg-info → lager_cli-0.34.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lager-cli
-Version: 0.34.2
+Version: 0.34.4
 Summary: Lager CLI - Box and Docker connectivity
 Home-page: https://github.com/lagerdata/lager
 Author: Lager Data

{lager_cli-0.34.2 → lager_cli-0.34.4}/__init__.py

@@ -7,4 +7,4 @@ Lager CLI
 A Command Line Interface for Lager Data
 """
 
-__version__ = '0.34.2'
+__version__ = '0.34.4'

{lager_cli-0.34.2 → lager_cli-0.34.4}/commands/box/diagnose.py

@@ -120,7 +120,12 @@ def _call(url: str, timeout: float = 8.0) -> dict:
         r = requests.get(url, timeout=timeout, headers=auth_headers_for_box(box_host))
         r = _check_gateway(r, box_host)
         if r.status_code == 404:
-            return {'unavailable': 'endpoint not on this box (pre-0.20 image)'}
+            # Deliberately does not name a version: this is shared by every
+            # diagnose endpoint, and they were not all added in the same
+            # release. Naming 0.20 sent a reader looking for the wrong thing
+            # when a newer endpoint was the one missing.
+            return {'unavailable': 'endpoint not served by this box; '
+                                   'update the box to use this section'}
         if r.status_code >= 400:
             return {'transport_error': f'HTTP {r.status_code}: {r.text[:200]}'}
         return r.json()
@@ -398,6 +403,128 @@ def _classify_jlink(usb_info: dict, jlink_info: dict) -> tuple[str, str]:
     return ('yellow', 'UNCLEAR — review the J-Link section above and rerun if needed.')
 
 
+def _fmt_usbhub_lines(d: dict):
+    """Render the USB-hub section."""
+    devnum = d.get('devnum')
+    lo, hi = d.get('devnum_min'), d.get('devnum_max')
+    med = d.get('devnum_median')
+    churn = f'{devnum}' if devnum is not None else '—'
+    if (devnum is not None and lo is not None and hi is not None
+            and med is not None):
+        # The interpretation, inline, because the raw number means nothing to
+        # someone who does not already know how devnums are assigned.
+        churn += f'   (bench: {lo}–{hi}, median {med})'
+        if devnum > med * 1.3 and devnum >= hi:
+            churn += '  <- far above its peers: this device has re-enumerated'
+
+    visible = d.get('serial_visible_to_sdk')
+    visible_s = {True: 'yes', False: 'NO', None: 'unknown'}.get(visible, 'unknown')
+
+    lines = [
+        f'enumerated:   {d.get("enumerated")}',
+        f'sysfs:        {d.get("sysfs_path") or "—"}',
+        f'devnum:       {churn}',
+        f'seen by SDK:  {visible_s}',
+    ]
+    serials = d.get('sdk_scan_serials')
+    if serials is not None:
+        lines.append(f'  SDK scan:   {", ".join(serials) if serials else "(nothing)"}')
+    if d.get('sdk_scan_error'):
+        lines.append(f'  scan error: {d["sdk_scan_error"]}')
+
+    for dev in (d.get('vendor_devices') or []):
+        lines.append(
+            f'  bus:        {dev.get("sysfs_name")}  {dev.get("vid")}:{dev.get("pid")}'
+            f'  serial={dev.get("serial") or "(none)"}'
+            f'  devnum={dev.get("devnum")}  {dev.get("product") or ""}'.rstrip()
+        )
+
+    if d.get('probe_skipped'):
+        lines.append(f'hub open:     skipped — {d.get("probe_skip_reason")}')
+    elif d.get('hub_opens') is True:
+        lines.append('hub open:     OK')
+    elif d.get('hub_opens') is False:
+        lines.append(f'hub open:     FAILED — {d.get("hub_open_error")}')
+        if d.get('hub_open_detail'):
+            lines.append(f'  detail:     {d["hub_open_detail"]}')
+    for h in (d.get('holders') or []):
+        lines.append(f'  held by:    pid {h.get("pid")} {h.get("command") or ""}'.rstrip())
+    return lines
+
+
+def _classify_usb_hub(d: dict):
+    """(colour, headline) for a USB hub net. Most specific first."""
+    if d.get('unavailable') or d.get('transport_error'):
+        return ('yellow',
+                'UNCLEAR — this box does not serve /diagnose/usbhub. '
+                'Update the box to diagnose hub nets.')
+
+    if d.get('enumerated') is False:
+        return ('red',
+                'NOT ENUMERATED — the kernel does not see this hub at all. '
+                'Check its upstream cable and whether its port has power.')
+
+    if d.get('probe_skipped'):
+        return ('yellow',
+                f'BUSY — {d.get("probe_skip_reason")}. Something else is '
+                f'driving this hub; rerun when it is idle.')
+
+    # The distinction this endpoint exists for: enumerated, and the vendor SDK
+    # still cannot see it. sysfs and lsof both report a healthy device here.
+    if d.get('serial_visible_to_sdk') is False:
+        extra = ''
+        devnum, med = d.get('devnum'), d.get('devnum_median')
+        if devnum is not None and med is not None and devnum > med * 1.3:
+            extra = (f' Its devnum ({devnum}) is well above the rest of the '
+                     f'bench (median {med}), so it has been re-enumerating.')
+        return ('red',
+                'HUB WEDGED (electrical) — the kernel has it enumerated but it '
+                'does not answer its vendor SDK. That is the hub or its cabling, '
+                'not the box software: restarting box services will not help.'
+                + extra)
+
+    if d.get('hub_opens') is False:
+        holders = d.get('holders') or []
+        if holders:
+            who = ', '.join(f'pid {h.get("pid")}' for h in holders)
+            return ('yellow',
+                    f'HUB CLAIMED — the SDK can see it but the open failed and '
+                    f'it is held by {who}.')
+        return ('red', f'HUB WILL NOT OPEN — {d.get("hub_open_error")}')
+
+    if d.get('hub_opens') is True:
+        return ('green',
+                'REACHABLE — the hub enumerated, the SDK sees it, and it opened '
+                'and closed cleanly. This tests the path to the hub, not the '
+                'DUT behind any given port.')
+
+    return ('yellow', 'UNCLEAR — review the section above and rerun if needed.')
+
+
+def _diagnose_usb_hub(box_ip: str, address: str) -> None:
+    """USB-hub branch of `lager diagnose`.
+
+    Fetches the instrument-agnostic host-side USB section plus
+    `/diagnose/usbhub` in parallel, renders them, and classifies.
+    """
+    urls = {
+        'usb': f'http://{box_ip}:9000/diagnose/usb?address={address}',
+        'hub': f'http://{box_ip}:9000/diagnose/usbhub?address={address}',
+    }
+    results: dict[str, dict] = {}
+    with ThreadPoolExecutor(max_workers=2) as pool:
+        futures = {pool.submit(_call, url): name for name, url in urls.items()}
+        for fut in as_completed(futures):
+            results[futures[fut]] = fut.result()
+
+    _print_section('USB (host-side)', results['usb'], _fmt_usb_lines)
+    _print_section('USB hub', results['hub'], _fmt_usbhub_lines)
+
+    color, headline = _classify_usb_hub(results['hub'])
+    click.echo()
+    click.echo(click.style(f'Classification: {headline}', fg=color, bold=True))
+
+
 def _diagnose_debug(box_ip: str, net: str, address: str) -> None:
     """Debug-net (J-Link) branch of `lager diagnose`.
 
@@ -471,6 +598,14 @@ def diagnose(ctx, net, box, net_type):
         _diagnose_debug(resolved_box, net, address)
         return
 
+    # USB hub nets are not USB-TMC either, and the pyvisa probe below has
+    # nothing to say about them. They used to fall through to the generic
+    # "NOT USB-TMC, check the role command yourself" bucket, which is exactly
+    # no help when the question is why a hub will not answer.
+    if role == 'usb':
+        _diagnose_usb_hub(resolved_box, address)
+        return
+
     # Fire the three endpoints in parallel.
     # Port mapping inside the box container:
     #   8080 — hardware_service.py  (/invoke, /diagnose/dispatcher)

{lager_cli-0.34.2 → lager_cli-0.34.4}/commands/box/nets.py

@@ -739,6 +739,7 @@ def _display_table(
     records,
     state_map: dict[str, str | None] | None = None,
     reason_map: dict[str, str] | None = None,
+    code_map: dict[str, str] | None = None,
 ):
     """Render the grouped net table.
 
@@ -850,7 +851,7 @@ def _display_table(
             click.secho(f"{row[0]:<{col_w[0]}}", bold=True, nl=False)
             click.echo("  " + "  ".join(f"{row[i]:<{col_w[i]}}" for i in range(1, len(col_w))))
 
-    _print_state_reasons(records, reason_map)
+    _print_state_reasons(records, reason_map, code_map)
 
 
 # Roles with no live probe report no state by design (uart, spi, i2c, ...).
@@ -858,12 +859,48 @@ def _display_table(
 # on every bench and stops being read.
 _EXPECTED_NO_STATE_REASON = "no probe for role"
 
+# What a classification means for the person reading the footnote, and how
+# loudly to say it. Only "go and look at the hardware" is red; the others are
+# usually a bench in a normal state or a net pointing at the wrong device.
+#
+# Looked up with .get() and ALWAYS optional -- a newer box can send a code this
+# CLI has never heard of, and the box's own `reason` already says everything
+# needed. A KeyError here would crash the exact command someone runs when
+# something is already broken.
+_REASON_CODE_NOTES = {
+    "hub-unreachable": (
+        "the hub is on the USB bus but will not answer. That is hardware:\n"
+        "    check its power and upstream cable. Restarting box services\n"
+        "    will not help.",
+        "red",
+    ),
+    "hub-absent": (
+        "the hub is not on the USB bus at all -- unplugged, or its\n"
+        "    upstream port is off.",
+        "yellow",
+    ),
+    "hub-serial-mismatch": (
+        "hubs are on the bus but none has the serial this net names.\n"
+        "    Check the net's address.",
+        "yellow",
+    ),
+}
+
 
-def _print_state_reasons(records, reason_map: dict[str, str] | None) -> None:
+def _print_state_reasons(
+    records,
+    reason_map: dict[str, str] | None,
+    code_map: dict[str, str] | None = None,
+) -> None:
     """Explain the ``–`` cells, grouped by reason.
 
     Only unexpected ones: a role with no probe is normal. Silent when the box
     sent no reasons at all, which is what an older box does.
+
+    ``code_map`` only ever adds a remedy line under a group. The box's
+    ``reason`` is always printed and always self-sufficient, so an older box
+    that sends no codes, or a newer one sending a code this CLI does not know,
+    both render exactly as they did before.
     """
     if not reason_map:
         return
@@ -879,11 +916,19 @@ def _print_state_reasons(records, reason_map: dict[str, str] | None) -> None:
     if not by_reason:
         return
 
+    code_map = code_map or {}
     click.echo()
     click.secho("Nets reporting no state:", bold=True, err=True)
     for reason in sorted(by_reason):
-        names = ", ".join(by_reason[reason])
-        click.echo(f"    {names}: {reason}", err=True)
+        names = by_reason[reason]
+        click.echo(f"    {', '.join(names)}: {reason}", err=True)
+        # One remedy per group, not per net: four dead nets on one hub are one
+        # fault, and printing the same sentence four times buries it.
+        codes = {code_map.get(n) for n in names}
+        note = _REASON_CODE_NOTES.get(codes.pop()) if len(codes) == 1 else None
+        if note:
+            text, colour = note
+            click.secho(f"    -> {text}", fg=colour, err=True)
     if any(r == "deadline" for r in by_reason):
         click.secho(
             "    Note: 'deadline' is the box's budget for probing every\n"
@@ -2251,6 +2296,10 @@ def state_cmd(ctx: click.Context, box: str | None, as_json: bool) -> None:
     # Why a net has no state. Absent on boxes older than this field; the
     # display and the JSON both have to read as they did before in that case.
     reason_map: dict[str, str] = {}
+    # The machine-readable half of the same answer, where the box sent one.
+    # Never required: an older box sends no codes and everything below falls
+    # back to printing `reason`, which is what it did before this existed.
+    code_map: dict[str, str] = {}
     state_list = _fetch_net_state(resolved_box)
     if state_list is None:
         click.secho(
@@ -2265,6 +2314,9 @@ def state_cmd(ctx: click.Context, box: str | None, as_json: bool) -> None:
             reason = entry.get("reason")
             if reason:
                 reason_map[name] = reason
+                code = entry.get("reason_code")
+                if code:
+                    code_map[name] = code
 
     if as_json:
         merged = []
@@ -2273,11 +2325,14 @@ def state_cmd(ctx: click.Context, box: str | None, as_json: bool) -> None:
             item = {**rec, "live_state": state_map.get(name)}
             if name in reason_map:
                 item["live_state_reason"] = reason_map[name]
+            if name in code_map:
+                item["live_state_reason_code"] = code_map[name]
             merged.append(item)
         click.echo(json.dumps(merged, indent=2))
         return
 
-    _display_table(records, state_map=state_map, reason_map=reason_map)
+    _display_table(records, state_map=state_map, reason_map=reason_map,
+                   code_map=code_map)
 
 
 @nets.command("show", help="Show full details of a saved net, including metadata")

{lager_cli-0.34.2 → lager_cli-0.34.4}/commands/communication/usb.py

@@ -25,6 +25,7 @@ from ...core.net_helpers import (
     list_nets_by_role,
     display_nets_table,
     validate_net_exists,
+    box_command_error,
     echo_box_request_failure,
     NET_HTTP_PORT,
 )
@@ -49,6 +50,18 @@ def _display_usb_nets(ctx: click.Context, box: str) -> None:
     display_nets_table(nets, empty_message="No USB nets found on this box.")
 
 
+# Must exceed the box's own worst case for /usb/command, or the box's
+# structured errors are undeliverable by construction: the client gives up
+# before the answer it is waiting for exists. The handler's bounds are
+# additive — up to `_USB_LOCK_TIMEOUT_S` (10s) queueing on the process-wide
+# hub lock, then up to `HUB_OP_TIMEOUT_S` (30s) in the driver deadline — so a
+# wedged hub answers 504 at ~40s. A 30s client timeout turned that into a
+# transport error, which reads as "the box is unreachable" and hides both the
+# real diagnosis and the fact that the box already scheduled its own recovery.
+# Raise this if either box-side bound grows.
+_USB_COMMAND_TIMEOUT_S = 45
+
+
 def _invoke_remote(
     ctx: click.Context,
     net_name: str,
@@ -68,18 +81,16 @@ def _invoke_remote(
     from ...box_storage import _check_gateway
 
     url = f"http://{target_box}:{NET_HTTP_PORT}/usb/command"
-    # First contact with an Acroname hub runs BrainStem USB discovery on the
-    # box, which can take well over 10s cold; budget for it.
     try:
         resp = requests.post(
             url,
             json={"netname": net_name, "action": command},
-            timeout=30,
+            timeout=_USB_COMMAND_TIMEOUT_S,
             headers=auth_headers_for_box(target_box),
         )
         resp = _check_gateway(resp, target_box)
     except (requests.ConnectionError, requests.Timeout) as e:
-        echo_box_request_failure(target_box, e, timeout=30)
+        echo_box_request_failure(target_box, e, timeout=_USB_COMMAND_TIMEOUT_S)
         ctx.exit(1)
     except requests.RequestException as e:
         click.secho(f"Error: USB request to box failed: {e}", fg='red', err=True)
@@ -99,11 +110,14 @@ def _invoke_remote(
         click.echo(f"[OK] {message}")
         return
 
-    error = result.get('error') or f'USB command failed (HTTP {resp.status_code})'
-    if resp.status_code == 404:
-        error = (f"{error}. This box image does not expose /usb/command; "
-                 f"update the box.")
+    error = box_command_error(
+        result, resp.status_code, '/usb/command',
+        f'USB command failed (HTTP {resp.status_code})')
     click.secho(f"Error: {error}", fg='red', err=True)
+
+    detail = result.get('reason_detail')
+    if detail:
+        click.secho(f"       {detail}", fg='yellow', err=True)
     ctx.exit(1)
 
 

{lager_cli-0.34.2 → lager_cli-0.34.4}/commands/power/battery.py

@@ -21,6 +21,7 @@ import click
 from ...core.net_group import NetGroup
 # Import consolidated helpers from cli.core.net_helpers
 from ...core.net_helpers import (
+    box_command_error,
     require_netname,
     resolve_box,
     validate_net,
@@ -81,10 +82,9 @@ def _run_backend(ctx, box, action: str, **params):
         click.echo(f"\033[92m{result.get('message', 'Command executed')}\033[0m")
         return
 
-    error = result.get('error') or f"battery command failed (HTTP {response.status_code})"
-    if response.status_code == 404:
-        error = (f"{error}. This box image does not expose /battery/command; "
-                 f"update the box.")
+    error = box_command_error(
+        result, response.status_code, '/battery/command',
+        f"battery command failed (HTTP {response.status_code})")
     click.secho(f"Error: {error}", fg='red', err=True)
     raise SystemExit(1)
 

{lager_cli-0.34.2 → lager_cli-0.34.4}/commands/power/supply.py

@@ -24,6 +24,7 @@ import click
 from ...core.net_group import NetGroup
 # Import consolidated helpers from cli.core.net_helpers
 from ...core.net_helpers import (
+    box_command_error,
     require_netname,
     resolve_box,
     validate_net,
@@ -127,10 +128,9 @@ def _run_backend(ctx, box, action: str, **params):
         click.echo(f"[OK] {result.get('message', 'Command executed')}")
         return
 
-    error = result.get('error') or f"supply command failed (HTTP {response.status_code})"
-    if response.status_code == 404:
-        error = (f"{error}. This box image does not expose /supply/command; "
-                 f"update the box.")
+    error = box_command_error(
+        result, response.status_code, '/supply/command',
+        f"supply command failed (HTTP {response.status_code})")
     click.secho(f"Error: {error}", fg='red', err=True)
     raise SystemExit(1)
 

{lager_cli-0.34.2 → lager_cli-0.34.4}/commands/utility/update.py

@@ -103,6 +103,42 @@ def wait_for_box_ready(box_ip, *, timeout_s=60, initial_delay_s=2):
     return False
 
 
+# Files whose contents are secret and whose owner therefore matters as much as
+# their mode. Mode 0600 grants the OWNER alone, so tightening one of these under
+# the wrong owner locks the runtime out of it entirely.
+_SECRET_FILES = ('/etc/lager/org_secrets.json', '/etc/lager/secret_key')
+
+# uid 33 is www-data, the user the container runs as. Hardcoded because it is
+# baked into the container image, not discovered at runtime.
+_CONTAINER_UID = 33
+
+
+def _secret_ownership_shell_cmd(files=_SECRET_FILES, uid=_CONTAINER_UID):
+    """Shell snippet that gives the secret files back to the container user.
+
+    A secrets file copied onto a box by hand belongs to whoever copied it. The
+    boot script then tightens it to 0600 — successfully, because that same user
+    owns it — and uid 33 can no longer read its own secrets. Nothing fails
+    loudly: secret injection just returns empty and scripts break far from the
+    cause.
+
+    Best-effort by construction. `sudo -n` so a box whose sudoers predates the
+    chown grant fails instantly instead of blocking on a password prompt no one
+    is there to answer, and every branch swallows its failure — an unreadable
+    secrets file must never be the reason an update fails. Boxes that miss the
+    repair still get the boot-time warning telling them what to run by hand.
+
+    No chmod: after the chown this user no longer owns the file, and the
+    container tightens the mode itself on the next load.
+    """
+    quoted = ' '.join(shlex.quote(f) for f in files)
+    return (
+        f'for f in {quoted}; do '
+        f'if [ -f "$f" ]; then sudo -n /bin/chown {uid}:{uid} "$f" 2>/dev/null || true; fi; '
+        'done; true'
+    )
+
+
 def _flatten_shell_cmd():
     """Shell snippet that flattens the sparse-checkout layout (`box/` -> root).
 
@@ -1846,6 +1882,27 @@ def _update_logic(ctx, *, box, yes, version, verbose, check, force=False):
     # to be running: 'container-down' falls through to the rebuild path below
     # and brings the box back up. `--force` still skips the early-exit
     # unconditionally.
+    # Secret files must be owned by uid 33 (the container user), not merely
+    # mode 0600. 0600 grants the owner alone, so a secrets file left under a
+    # different owner — e.g. copied onto the box by hand — locks the runtime
+    # out of it the moment anything tightens the mode. The symptom is silent:
+    # secret injection returns empty and scripts fail nowhere near the cause.
+    #
+    # BEFORE the rebuild gate on purpose, like the host-CLI reconcile below.
+    # This is a heal, not part of building an image, and the box that most
+    # needs it is the one already running current code: an operator whose
+    # secrets stopped working reaches for `lager update`, and if the repair
+    # sat after the gate that update would early-exit "already up to date"
+    # and fix nothing. Running it here costs one short SSH round-trip on the
+    # fast path and makes the remedy work whenever it is reached for.
+    #
+    # `lager update` is the only path that runs with real privilege, so it is
+    # where the repair belongs; the box's boot script can only warn when it
+    # lacks the grant. Best-effort throughout — an unreadable secrets file must
+    # never be the reason an update fails — so boxes that miss the repair still
+    # get the boot warning telling them what to run.
+    run_ssh_command_with_output(_secret_ownership_shell_cmd(), timeout_secs=30)
+
     _gate = _rebuild_gate_verdict(
         facts,
         git_sync_confirmed=git_sync_confirmed,
@@ -2323,6 +2380,7 @@ def _update_logic(ctx, *, box, yes, version, verbose, check, force=False):
         ctx.exit(1)
     log_status('OK', 'green')
 
+
     # Persist the build-inputs hash now that /etc/lager is group-writable by this
     # user (Step 10). This is what lets the next run's cache-validity check short-circuit to
     # the no-op fast path instead of rebuilding; a stale hash defeats it. Unlike

{lager_cli-0.34.2 → lager_cli-0.34.4}/core/net_helpers.py

@@ -166,6 +166,28 @@ NET_HTTP_PORT = 9000
 _NET_HTTP_TIMEOUT = 10
 
 
+def box_command_error(result, status_code, endpoint, fallback) -> str:
+    """Build the user-facing error for a failed :9000 command response.
+
+    The "update the box" hint is gated on the SHAPE of the body, not on the
+    status code. Every :9000 command handler sets ``success`` in its own JSON,
+    including its 404s — and a handler's 404 means the net or its instrument
+    was not found, which an update cannot fix. Only Flask's built-in 404, which
+    carries no ``success`` key, means this box image predates the endpoint.
+
+    Keying the hint on the code alone told people to update the box whenever an
+    instrument was unplugged: an absent USB hub reported "device-not-found: No
+    Acroname hub detected on USB with serial 0x… . This box image does not
+    expose /usb/command; update the box." Both halves cannot be true, and the
+    second one sends the diagnosis somewhere the fault never was.
+    """
+    body = result if isinstance(result, dict) else {}
+    error = body.get('error') or fallback
+    if status_code == 404 and 'success' not in body:
+        error = f"{error}. This box image does not expose {endpoint}; update the box."
+    return error
+
+
 def echo_box_request_failure(box_ip: str, exc, timeout=None) -> None:
     """Print the right diagnosis for a failed box HTTP call.
 

{lager_cli-0.34.2 → lager_cli-0.34.4/lager_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lager-cli
-Version: 0.34.2
+Version: 0.34.4
 Summary: Lager CLI - Box and Docker connectivity
 Home-page: https://github.com/lagerdata/lager
 Author: Lager Data