feat(snmp): devices you add, test and read on the SNMP page (milestone 491)

The operator, reviewing SNMP on #5214: "this system looks incomplete like
there's something missing from it". The one device shown was plugin.yaml's
example (core-switch 192.168.1.1, community public), polled every minute;
devices could only be defined by editing YAML in the image; a failed poll was
logged at DEBUG and stored nowhere, so the page said "waiting for the next
poll" forever; v3 ran as v2c; counters showed as lifetime totals.

- Devices are rows (snmp_devices, migration snmp_001): address, port,
  v1/v2c community or a v3 user with auth/priv protocols and keys (secrets
  encrypted), presets plus custom readings, an optional host binding, and
  the newest poll's outcome. The YAML device list and its example are gone.
- The SNMP page adds, edits and deletes them (admin, audited, with
  get_audit_entities so the audit log names and links a device). Readings
  come from presets (system uptime, interface traffic by number, UPS-MIB,
  Linux net-snmp) and custom "OID name [unit]" lines.
- One GET per device with every OID, devices polled at once. The outcome is
  written to the row in words ("No reply from … within 5 s. Check the address
  and port, that SNMP is on, and the community"), with readings it lacks.
  v1's whole-request error drops that OID and asks again. SNMPv3 signs in
  with USM (MD5/SHA-1/SHA-2, DES/3DES/AES).
- Test asks the unsaved form's device for its name, description, uptime and
  interfaces by number. It is an admin's explicit action; every page reads
  only stored rows (System 178's ruling).
- Each reading has a unit; a counter is stored as a per-second rate (bytes as
  bit/s), a reset or wrap skipped. The page, widget and host panel say values
  in units and why a device is silent; the device page draws a chart per
  reading on a dated axis.

Tests: readings and presets, the form and its secrets, v3 checks, rates,
the poller against a stand-in pysnmp (one GET, v1 retry, timeout wording,
USM), the pages, and an integration test of the poll writing outcomes and
rates on Postgres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/integration/test_snmp_poll.py

@@ -0,0 +1,76 @@
+"""Integration: an SNMP poll writes each device's outcome to its row and its
+answers to the metric tables, a counter as a rate (milestone 491).
+Requires STEWARD_DATABASE_URL."""
+from __future__ import annotations
+
+import asyncio
+import os
+import uuid
+
+import pytest
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+def app():
+    if not os.environ.get("STEWARD_DATABASE_URL"):
+        pytest.skip("needs Postgres")
+    from steward.app import create_app
+    return create_app(testing=False)
+
+
+def test_a_poll_records_why_a_device_is_silent_and_what_another_answered(app):
+    from sqlalchemy import select
+
+    from plugins.snmp import scheduler
+    from plugins.snmp.models import SnmpDevice
+    from plugins.snmp.poller import PollResult
+    from steward.models.metrics import PluginMetricLatest
+
+    tag = uuid.uuid4().hex[:8]
+    up, down = f"sw-{tag}", f"ups-{tag}"
+    counts = iter([1_000.0, 61_000.0])
+
+    async def fake_poll(address, port, creds, oids):
+        if address == "10.9.9.9":
+            return PollResult(error="No reply from 10.9.9.9:161 within 5 s.")
+        keys = dict((k, o) for o, k in oids)
+        assert {"uptime", "if1_in", "if1_status"} <= set(keys) and creds.community == "public"
+        return PollResult(readings={"uptime": 8_640_000.0, "if1_status": 1.0, "if1_in": next(counts)},
+                          missing=["if1_out"])
+
+    async def go():
+        from steward.core.crypto import encrypt_secret
+        async with app.db_sessionmaker() as s:
+            async with s.begin():
+                s.add(SnmpDevice(name=up, address="10.9.9.1", presets=["system", "interfaces"],
+                                 interfaces="1", community=encrypt_secret("public")))
+                s.add(SnmpDevice(name=down, address="10.9.9.9", presets=["ups"],
+                                 community=encrypt_secret("public")))
+        scheduler.RATES = None
+        await scheduler._do_poll(app, poll=fake_poll)
+        first = await _latest(app, up)
+        await asyncio.sleep(1.1)
+        await scheduler._do_poll(app, poll=fake_poll)
+        async with app.db_sessionmaker() as s:
+            rows = {d.name: d for d in (await s.execute(
+                select(SnmpDevice).where(SnmpDevice.name.in_([up, down])))).scalars()}
+            async with s.begin():
+                for d in rows.values():
+                    await s.delete(d)
+        return first, await _latest(app, up), rows
+
+    async def _latest(app, name):
+        async with app.db_sessionmaker() as s:
+            return {r.metric_name: r.value for r in (await s.execute(select(PluginMetricLatest).where(
+                PluginMetricLatest.source_module == "snmp", PluginMetricLatest.resource_name == name))).scalars()}
+
+    first, second, rows = asyncio.run(go())
+    assert rows[up].last_error is None and rows[up].last_ok_at is not None and rows[up].missing == ["if1_out"]
+    assert rows[down].last_error == "No reply from 10.9.9.9:161 within 5 s." and rows[down].last_ok_at is None
+    assert rows[down].last_polled_at is not None
+    assert first == {"uptime": 8_640_000.0, "if1_status": 1.0}          # a counter needs two samples
+    # 60,000 bytes over the 1.1 s or more between the polls, stored as bits
+    # per second: at most 436 kbit/s, and above 150 unless a poll took seconds.
+    assert 150_000 < second["if1_in"] <= 436_364