feat(snmp): explicit host binding (host_id / steward_host) with implicit fallback

SNMP devices map onto a Steward host's detail page via _devices_for_host,
which previously matched the device's `host` field (the SNMP poll target)
against the Host's address/name — a coincidence of strings that breaks when
the poll target differs from how the Host is recorded.

Add two optional per-device config fields that decouple the binding from the
poll target:
  • host_id      — exact Steward Host UUID match (the explicit link)
  • steward_host — friendly bind by Host name or address (case-insensitive)

An explicit binding is exclusive: a device bound to host A never implicitly
matches host B by a coincidental address. No explicit binding → existing
implicit `host`-string match (fully backward compatible).

host_panel passes host.id and badges explicitly-bound devices. plugin.yaml
documents the new fields. Tests cover explicit id/name, exclusivity, wrong
uuid, and legacy fallback.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Jg27rgypiW2efULXJDtMC

plugins/snmp/plugin.yaml

@@ -15,6 +15,16 @@ tags:
 config:
   poll_interval_seconds: 60
   # Each device is polled independently. OIDs must resolve to numeric values.
+  #
+  # `host` is the SNMP poll target (IP/hostname we query). A device also shows
+  # up on a Steward Host's detail page when it maps to that host. By default
+  # that mapping is implicit: `host` is matched against the Host's address or
+  # name. To bind explicitly instead — e.g. when you poll by IP but the Host is
+  # recorded by DNS name, or for an SNMP-only switch/PDU/UPS — add ONE of:
+  #   host_id:      "<steward-host-uuid>"   # exact Host.id match
+  #   steward_host: "switch01"              # Host name OR address (case-insensitive)
+  # An explicit binding is exclusive: the device then maps ONLY to that host,
+  # never implicitly to another by a coincidental address string.
   devices:
     - name: "core-switch"
       host: "192.168.1.1"

plugins/snmp/routes.py

@@ -93,15 +93,40 @@ async def index():
                                  poll_interval=poll_interval)
 
 
-def _devices_for_host(devices_cfg: list, address: str | None, name: str | None) -> list[dict]:
-    """SNMP devices whose configured `host` matches a Steward host's address or
-    name (case-insensitive). SNMP devices are config-defined by IP/hostname, so
-    this is how they map onto a host's page."""
+def _device_binds_to_host(d: dict, keys: set[str], host_id: str) -> bool:
+    """Does config device `d` belong on the host identified by `keys`
+    (lowercased {address, name}) / `host_id`?
+
+    A device may declare an **explicit** binding that decouples "which Steward
+    host this belongs to" from "where to poll" (the `host` field):
+      • `host_id`       — the Steward Host UUID (exact match), the explicit link.
+      • `steward_host`  — a friendly bind by Host name or address (case-insensitive).
+    An explicit binding is **exclusive**: a device bound to host A must not also
+    match host B by a coincidental poll-target string. Only when no explicit
+    binding is present do we fall back to the implicit `host`-string match
+    (backward compatible with configs that only set `host`).
+    """
+    explicit_id = str(d.get("host_id", "")).strip()
+    explicit_name = str(d.get("steward_host", "")).strip().lower()
+    if explicit_id or explicit_name:
+        if explicit_id and host_id and explicit_id == host_id:
+            return True
+        return bool(explicit_name and explicit_name in keys)
+    return str(d.get("host", "")).strip().lower() in keys
+
+
+def _devices_for_host(devices_cfg: list, address: str | None, name: str | None,
+                      host_id: str | None = None) -> list[dict]:
+    """SNMP devices that map onto a Steward host's page. Prefers an explicit
+    per-device binding (`host_id` / `steward_host`); otherwise falls back to
+    matching the device's `host` (poll target) against the host's address or
+    name (case-insensitive). See `_device_binds_to_host` for the precedence."""
     keys = {(address or "").strip().lower(), (name or "").strip().lower()}
     keys.discard("")
+    hid = (host_id or "").strip()
     return [
         d for d in devices_cfg
-        if isinstance(d, dict) and str(d.get("host", "")).strip().lower() in keys
+        if isinstance(d, dict) and _device_binds_to_host(d, keys, hid)
     ]
 
 
@@ -120,7 +145,7 @@ async def host_panel(host_id: str):
             select(Host).where(Host.id == host_id))).scalar_one_or_none()
         if host is None:
             return ""
-        matched = _devices_for_host(devices_cfg, host.address, host.name)
+        matched = _devices_for_host(devices_cfg, host.address, host.name, host.id)
         if not matched:
             return ""
         names = [d.get("name") or d.get("host", "?") for d in matched]
@@ -131,6 +156,8 @@ async def host_panel(host_id: str):
         "host": d.get("host", ""),
         "oids": d.get("oids", []),
         "readings": latest.get(d.get("name") or d.get("host", "?"), {}),
+        "bound": bool(str(d.get("host_id", "")).strip()
+                      or str(d.get("steward_host", "")).strip()),
     } for d in matched]
     return await render_template("snmp/host_panel.html", devices=devices)
 

plugins/snmp/templates/snmp/host_panel.html

@@ -11,6 +11,10 @@
     <div style="display:flex;align-items:center;gap:0.6rem;margin-bottom:0.5rem;flex-wrap:wrap;">
       <span style="font-weight:600;font-size:0.92rem;">{{ device.name }}</span>
       <span style="font-size:0.78rem;color:var(--text-dim);font-family:ui-monospace,monospace;">{{ device.host }}</span>
+      {% if device.bound %}
+      <span title="Explicitly bound to this host (host_id / steward_host)"
+            style="font-size:0.68rem;color:var(--text-muted);background:var(--bg-elevated);border:1px solid var(--border);border-radius:3px;padding:0.05rem 0.4rem;">bound</span>
+      {% endif %}
       {% if device.readings %}
       <span style="font-size:0.74rem;color:var(--green);">&#9679; reachable</span>
       {% else %}

tests/plugins/snmp/test_host_match.py

@@ -27,3 +27,43 @@ def test_no_match_returns_empty():
 def test_blank_address_and_name_match_nothing():
     # A host with no address/name must not match a device with a blank host.
     assert _devices_for_host(_CFG, "", None) == []
+
+
+def test_implicit_match_unaffected_when_host_id_passed():
+    # Passing the new host_id arg must not break the legacy implicit match.
+    out = _devices_for_host(_CFG, "192.168.1.1", "somehost", host_id="h-1")
+    assert [d["name"] for d in out] == ["core-switch"]
+
+
+# ── Explicit binding ─────────────────────────────────────────────────────────
+
+def test_explicit_host_id_matches_exact_uuid():
+    cfg = [{"name": "sw", "host": "10.0.0.5", "host_id": "uuid-abc"}]
+    out = _devices_for_host(cfg, "10.0.0.9", "other", host_id="uuid-abc")
+    assert [d["name"] for d in out] == ["sw"]
+
+
+def test_explicit_steward_host_matches_by_name_or_address():
+    cfg = [{"name": "pdu", "host": "10.0.0.5", "steward_host": "Switch01"}]
+    # Bind hits the Host's name despite a different poll target / address.
+    by_name = _devices_for_host(cfg, "10.0.0.9", "switch01", host_id="h9")
+    by_addr = _devices_for_host(cfg, "switch01", "whatever", host_id="h9")
+    assert [d["name"] for d in by_name] == ["pdu"]
+    assert [d["name"] for d in by_addr] == ["pdu"]
+
+
+def test_explicit_binding_is_exclusive():
+    # Device polls 192.168.1.1 but is explicitly bound to host A by name.
+    cfg = [{"name": "sw", "host": "192.168.1.1", "steward_host": "hostA"}]
+    # Host B *would* match implicitly by the poll target — but must NOT,
+    # because the explicit binding takes over and points only at host A.
+    hostB = _devices_for_host(cfg, "192.168.1.1", "hostB", host_id="b")
+    hostA = _devices_for_host(cfg, "10.0.0.2", "hostA", host_id="a")
+    assert hostB == []
+    assert [d["name"] for d in hostA] == ["sw"]
+
+
+def test_explicit_host_id_wrong_uuid_does_not_match():
+    cfg = [{"name": "sw", "host": "10.0.0.5", "host_id": "uuid-abc"}]
+    out = _devices_for_host(cfg, "10.0.0.5", "sw", host_id="uuid-zzz")
+    assert out == []