feat(dcl): ServiceLevel-aware OPC UA failover for primary/backup pairs (#138)

Prerequisite for OtOpcUa Warm redundancy (lmxopcua#717): a Warm standby keeps a healthy session but serves BadOutOfService at a standby ServiceLevel (90/50, boot 1), so a connection that lands there sat on Bad quality forever. - OPC UA connections with a backup poll Server_ServiceLevel (i=2267) on the connected endpoint (IServiceLevelReadable, implemented by OpcUaDataConnection; never raises Disconnected). A level < 200 sustained for the degraded window (default 10 s), or the first sample after any (re)connect, triggers a probe of the other endpoint (short-lived session: connect, read, dispose). Switch only when it reports a Healthy (>= 200) higher level, and not within the minimum dwell (default 60 s) of the previous ServiceLevel switch. Both degraded, other unreachable or level unknown: stay put. 250/240 (today's OtOpcUa) never starts a streak. - The switch reuses the failover path: SwitchToOtherEndpoint() now shared by all three triggers, then BecomeReconnecting(ReconnectCause.ServiceLevelFailover) - zero delay, no unstable accounting, ReSubscribeAll on the new endpoint. - Config: OpcUaEndpointConfig.ServiceLevelFailover {enabled, degradedWindowSeconds, minDwellSeconds}, read from the PRIMARY endpoint's JSON only; null = defaults (enabled, 10, 60). Inside the encrypted protocol JSON, so no schema change or migration. Central UI: fields in the Backup card next to Failover Retry Count. Global: ScadaBridge:DataConnection:ServiceLevelPollInterval (2 s) and ServiceLevelProbeTimeout (15 s). - Tests: actor tests per trigger/non-trigger with positive controls, an unsolicited promotion RefreshStart/RefreshEnd test at client and actor level, adapter tests, and a real in-process OPC UA server pair end to end. All 15 mutants killed. - Docs: Component-DataConnectionLayer, components/DataConnectionLayer, Component-CLI. Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
2026-11-13 03:06:45 -05:00
parent 16209831ca
commit 712c5117ee
23 changed files with 1760 additions and 36 deletions
@@ -504,4 +504,58 @@ public class OpcUaEndpointConfigSerializerTests
        Assert.NotNull(config.UserIdentity);
        Assert.Equal(OpcUaUserTokenType.Anonymous, config.UserIdentity!.TokenType);
    }
+
+    /// <summary>
+    /// ScadaBridge#138: the ServiceLevel failover object round-trips through the stored JSON and
+    /// through the flat dict the site hands the adapter, under its documented keys.
+    /// </summary>
+    [Fact]
+    public void ServiceLevelFailover_RoundTrips_JsonAndFlatDict()
+    {
+        var original = new OpcUaEndpointConfig
+        {
+            EndpointUrl = "opc.tcp://otopcua-a:4840",
+            ServiceLevelFailover = new OpcUaServiceLevelFailoverConfig
+            {
+                Enabled = false, DegradedWindowSeconds = 25, MinDwellSeconds = 120,
+            },
+        };
+
+        var json = OpcUaEndpointConfigSerializer.Serialize(original);
+        Assert.Contains("\"serviceLevelFailover\":{\"enabled\":false,\"degradedWindowSeconds\":25,\"minDwellSeconds\":120}", json);
+        var (round, isLegacy) = OpcUaEndpointConfigSerializer.Deserialize(json);
+        Assert.False(isLegacy);
+        Assert.NotNull(round.ServiceLevelFailover);
+        Assert.False(round.ServiceLevelFailover!.Enabled);
+        Assert.Equal(25, round.ServiceLevelFailover.DegradedWindowSeconds);
+        Assert.Equal(120, round.ServiceLevelFailover.MinDwellSeconds);
+
+        var flat = OpcUaEndpointConfigSerializer.ToFlatDict(round);
+        Assert.Equal("False", flat["ServiceLevelFailover.Enabled"]);
+        Assert.Equal("25", flat["ServiceLevelFailover.DegradedWindowSeconds"]);
+        Assert.Equal("120", flat["ServiceLevelFailover.MinDwellSeconds"]);
+        var back = OpcUaEndpointConfigSerializer.FromFlatDict(flat).ServiceLevelFailover;
+        Assert.NotNull(back);
+        Assert.False(back!.Enabled);
+        Assert.Equal(25, back.DegradedWindowSeconds);
+        Assert.Equal(120, back.MinDwellSeconds);
+    }
+
+    /// <summary>
+    /// ScadaBridge#138, upgrade safety: a row stored before the setting existed has no
+    /// <c>serviceLevelFailover</c>; it deserializes as Typed (not Malformed) with the object null,
+    /// and its flat dict gains no new keys — so existing connections are not seen as changed.
+    /// </summary>
+    [Fact]
+    public void ServiceLevelFailover_AbsentFromAnExistingRow_IsNull_AndAddsNoFlatKeys()
+    {
+        const string stored = "{\"endpointUrl\":\"opc.tcp://plant-a:4840\",\"securityMode\":\"none\",\"heartbeat\":null}";
+        var result = OpcUaEndpointConfigSerializer.Deserialize(stored);
+        Assert.Equal(OpcUaConfigParseStatus.Typed, result.Status);
+        Assert.Null(result.Config.ServiceLevelFailover);
+
+        var flat = OpcUaEndpointConfigSerializer.ToFlatDict(result.Config);
+        Assert.DoesNotContain(flat.Keys, k => k.StartsWith("ServiceLevelFailover.", StringComparison.Ordinal));
+        Assert.Null(OpcUaEndpointConfigSerializer.FromFlatDict(flat).ServiceLevelFailover);
+    }
 }
@@ -220,4 +220,30 @@ public class OpcUaEndpointConfigValidatorTests
        var r = OpcUaEndpointConfigValidator.Validate(c, fieldPrefix: "Primary.");
        Assert.Contains(r.Errors, e => e.EntityName == "Primary.UserIdentity.Username");
    }
+
+    /// <summary>ScadaBridge#138: the ServiceLevel failover window and dwell are range-checked, prefixed.</summary>
+    /// <param name="window">Degraded window, seconds.</param>
+    /// <param name="dwell">Minimum dwell, seconds.</param>
+    /// <param name="badField">The field expected to fail, or null when valid.</param>
+    [Theory]
+    [InlineData(10, 60, null)]
+    [InlineData(1, 0, null)]
+    [InlineData(3600, 86400, null)]
+    [InlineData(0, 60, "Primary.ServiceLevelFailover.DegradedWindowSeconds")]
+    [InlineData(3601, 60, "Primary.ServiceLevelFailover.DegradedWindowSeconds")]
+    [InlineData(10, -1, "Primary.ServiceLevelFailover.MinDwellSeconds")]
+    [InlineData(10, 86401, "Primary.ServiceLevelFailover.MinDwellSeconds")]
+    public void Validate_ServiceLevelFailoverRanges(int window, int dwell, string? badField)
+    {
+        var c = Valid();
+        c.ServiceLevelFailover = new OpcUaServiceLevelFailoverConfig
+        {
+            DegradedWindowSeconds = window, MinDwellSeconds = dwell,
+        };
+        var r = OpcUaEndpointConfigValidator.Validate(c, fieldPrefix: "Primary.");
+        if (badField is null)
+            Assert.True(r.IsValid);
+        else
+            Assert.Contains(r.Errors, e => e.EntityName == badField);
+    }
 }