feat(drivers): every driver reports the authored tags it skipped (Gitea #541)

A driver builds its RawPath -> definition table at init and tolerates a per-tag miss: an unmappable TagConfig, an unparseable address, a capability-matrix rejection. That tolerance is right -- one bad tag must not take down the other few thousand. What was missing is any statement of the fact afterwards. A skip is not an error and happens before any read, so the driver stays Healthy, errors/5 min stays 0, Last error stays empty, and Last read advances live off the tags that did map. On the wonder Makino in #540 that reading held while focas-z-34184 ignored 20 of its 22 tags. New optional capability ISkippedTagReporter, backed by a shared SkippedTagLedger so the reset/commit/cap rules are one implementation rather than one per driver. The report -- authored count, exact skipped count, and a capped sample of RawPath + reason -- rides DriverHealthChanged to a new Tags column on /hosts, over the Phase 5 telemetry stream. No table: a driver-only node has no ConfigDb to write to, the lesson from #521. The issue named eight drivers. It is twelve -- every driver in DriverTypeNames.All has an authored-tag skip path. Calculation (no scriptId), MTConnect (no readable DataItem id), Galaxy (no attributeRef) and OpcUaClient (no nodeId) were unlisted, and OpcUaClient's was the quietest of the twelve: NamespaceMap drops such an entry with a bare `continue` and not even a log line. SkippedTagReporterFleetTests pins the invariant reflectively over every IDriver in src/Drivers/, so a thirteenth cannot re-introduce the silence. Sql drops a tag at TWO points and its report is the union of both: a blob that does not map, AND an identifier the 8.1 catalog gate rejects against the live catalog. The second is what schema drift produces -- a renamed column, a dropped view -- months after a deployment sealed green, and reporting only the first would have that driver claim "0 skipped" while polling half its tags, which is worse than reporting nothing because the column would then be actively reassuring. Deliberately additive to driver state, never a change of it. Latching non-Healthy for a config problem would satisfy both halves of the #527 comms-loss conjunction -- 90 s without a successful read AND non-Healthy -- and a driver whose tags were ALL skipped has no successful reads by construction, so it would reconnect-loop forever against a healthy device. Three details that are load-bearing rather than incidental: - The skip digest is part of the publish fingerprint. A skipped tag leaves every other fingerprint component identical to a clean driver's, so without it PublishHealthSnapshot's dedup swallows exactly the publish carrying the signal -- the trap that already bit the rediscovery and host-status channels. The digest covers the sample, not just the counts: a redeploy that fixes one tag and breaks another leaves both counts unchanged. - The count is exact; only the sample is capped, and the tooltip says so when it is showing fewer than it counted. A truncated list that looked complete would have an operator fix twenty tags and believe the job done. - The ledger stages and commits, so an init that throws part-way leaves the previous report standing. A partial snapshot would read as "we now skip fewer tags", the opposite of the truth. The proto field needs no companion presence flag, unlike host_statuses: a singular message field carries real presence in proto3, and a has_ flag would collide with protoc's generated HasSkippedTags. Verified red-first three ways: dropping SkippedTagDigest from the fingerprint fails the two dedup tests, removing the seam from one driver fails the fleet guard, and dropping the catalog-gate leg fails the Sql union test. Full solution builds with zero new warnings against 4e22f024.
2026-08-05 19:23:40 -04:00
parent 4e22f02434
commit 39db75083d
34 changed files with 1572 additions and 30 deletions
@@ -213,4 +213,96 @@ public sealed class HostsDriverViewTests
        row.HostStatuses.ShouldBeNull();
        row.DegradedHosts.ShouldBeEmpty();
    }
+
+    // ---- skipped tags (Gitea #541) ----
+
+    /// <summary>
+    ///     The Makino case from Gitea #540, as the row renders it: every driver-level field reads healthy
+    ///     while 20 of 22 tags are not being polled. The skip field is the only thing on the row that
+    ///     contradicts it.
+    /// </summary>
+    [Fact]
+    public void A_healthy_row_still_reports_the_tags_its_driver_is_ignoring()
+    {
+        var snapshot = Snap("MAIN", "focas-z-34184") with
+        {
+            SkippedTags = new SkippedTagReport(22, 20,
+                [new SkippedTag("Makino/Identity/SeriesNumber", "invalid Address")]),
+        };
+
+        var row = HostsDriverView.Build([snapshot], nodes: null, instances: null).Single().Drivers.Single();
+
+        row.State.ShouldBe("Healthy");
+        row.ErrorCount5Min.ShouldBe(0);
+        row.LastError.ShouldBeNull();
+        row.HasSkippedTags.ShouldBeTrue("the row must contradict its own healthy-looking columns");
+        row.SkippedTags!.SkippedCount.ShouldBe(20);
+    }
+
+    /// <summary>
+    ///     A truncated sample must SAY it is truncated. Without the note a capped list reads as the whole
+    ///     list, and an operator who fixes the twenty named tags believes the job is done.
+    /// </summary>
+    [Fact]
+    public void The_skip_tooltip_admits_when_the_sample_is_shorter_than_the_count()
+    {
+        var snapshot = Snap("MAIN", "drv-a") with
+        {
+            SkippedTags = new SkippedTagReport(500, 137, [new SkippedTag("tag-0", "TagConfig did not map")]),
+        };
+
+        var title = HostsDriverView.Build([snapshot], nodes: null, instances: null)
+            .Single().Drivers.Single().SkippedTagsTitle();
+
+        title.ShouldContain("137 of 500");
+        title.ShouldContain("+136 more not shown");
+    }
+
+    /// <summary>A complete sample carries no truncation note.</summary>
+    [Fact]
+    public void The_skip_tooltip_omits_the_truncation_note_when_the_sample_is_complete()
+    {
+        var snapshot = Snap("MAIN", "drv-a") with
+        {
+            SkippedTags = new SkippedTagReport(5, 1, [new SkippedTag("tag-0", "TagConfig did not map")]),
+        };
+
+        HostsDriverView.Build([snapshot], nodes: null, instances: null)
+            .Single().Drivers.Single().SkippedTagsTitle()
+            .ShouldNotContain("more not shown");
+    }
+
+    /// <summary>
+    ///     A driver polling NONE of its tags gets its own wording — it is the most likely of all to look
+    ///     healthy, because it has no failing reads to report.
+    /// </summary>
+    [Fact]
+    public void A_driver_polling_nothing_is_called_out_as_such()
+    {
+        var snapshot = Snap("MAIN", "drv-a") with
+        {
+            SkippedTags = new SkippedTagReport(3, 3, [new SkippedTag("a", "r")]),
+        };
+
+        var row = HostsDriverView.Build([snapshot], nodes: null, instances: null).Single().Drivers.Single();
+
+        row.SkippedTags!.SkippedEverything.ShouldBeTrue();
+        row.SkippedTagsTitle().ShouldContain("NONE");
+    }
+
+    /// <summary>
+    ///     A driver that cannot report skips keeps null — distinct from one reporting zero. The column
+    ///     renders "—" for the former and "N tags" for the latter, and collapsing them would claim an
+    ///     unreporting driver is positively known to be polling everything.
+    /// </summary>
+    [Fact]
+    public void A_driver_without_a_skip_report_keeps_null_and_claims_nothing()
+    {
+        var row = HostsDriverView.Build([Snap("MAIN", "drv-a")], nodes: null, instances: null)
+            .Single().Drivers.Single();
+
+        row.SkippedTags.ShouldBeNull();
+        row.HasSkippedTags.ShouldBeFalse();
+        row.SkippedTagsTitle().ShouldBeEmpty();
+    }
 }