feat(mtconnect): CommsLossConfirmMs AdminUI field, refused-connection fast path reaches native conditions, dedicated live-gate Agent (#852)

- AdminUI MTConnect driver form: "Comms-loss confirm (ms)" in the Reconnect section, always written
  (0 = first refusal, negative = off is never dropped), case-insensitive load, unknown keys preserved,
  advisory at >= 90000 ms (the watchdog fires first). Form output byte-pinned and parsed through
  MTConnectDriver.ParseOptions on the driver side.
- Driver: a confirmed refused-connection outage now annotates every told CONDITION quality-only
  BadNoCommunication (state/ack kept, once per outage, UNAVAILABLE-Bad skipped); the first delivery
  afterwards re-diffs all subscribed conditions so unchanged ones get a quality-only Good.
- docker-dev/docker-compose.mtconnect-gate.yml: throwaway Agent in its adapter's network namespace so a
  stop is a genuine ConnectionRefused (a plain stopped container is a DNS failure = ambiguous).
- Docs: MTConnect.md comms-loss section + live-gate recipe, docker-dev README, drivers.md rule.

Refs #852
This commit is contained in:
Joseph Doherty
2026-11-11 06:23:18 -05:00
parent d1b6cad299
commit 340d9d26b7
11 changed files with 635 additions and 35 deletions
@@ -200,6 +200,75 @@ public sealed class MTConnectDriverFormModelTests
form.WriteEnabled.ShouldBeTrue();
}
// ---- comms-loss confirmation window (#846/#852) --------------------------------------------
[Fact]
public void Comms_loss_window_defaults_to_the_drivers_2000_and_an_absent_key_loads_as_it()
{
new MTConnectDriverForm.MTConnectFormModel().CommsLossConfirmMs.ShouldBe(2000);
MTConnectDriverForm.MTConnectFormModel.FromJson("""{"agentUri":"http://a:5000"}""")
.CommsLossConfirmMs.ShouldBe(2000);
}
[Theory]
[InlineData(-1)] // fast path off — must NOT be dropped like a non-positive timing knob, or it re-enables at 2000
[InlineData(0)] // mark on the first refusal
[InlineData(5000)]
public void Every_comms_loss_window_is_written_as_a_number_and_reloads(int value)
{
var o = Emit(new MTConnectDriverForm.MTConnectFormModel { AgentUri = "http://agent:5000", CommsLossConfirmMs = value });
// A JSON NUMBER (the driver's DTO is int?) — the class of bug where a form emitted a shape the factory DTO
// could not bind.
o["commsLossConfirmMs"]!.GetValueKind().ShouldBe(JsonValueKind.Number);
o["commsLossConfirmMs"]!.GetValue<int>().ShouldBe(value);
MTConnectDriverForm.MTConnectFormModel.FromJson(o.ToJsonString()).CommsLossConfirmMs.ShouldBe(value);
}
[Fact]
public void A_hand_authored_comms_loss_window_loads_from_pascal_case_and_survives_an_unrelated_edit()
{
// The pre-#852 JSON-only path (docs/drivers/MTConnect.md shows the PascalCase spelling).
const string existing = """{"AgentUri":"http://a:5000","CommsLossConfirmMs":-5,"tags":[{"fullName":"x1"}]}""";
var form = MTConnectDriverForm.MTConnectFormModel.FromJson(existing);
form.CommsLossConfirmMs.ShouldBe(-5);
form.SampleCount = 250;
var o = Emit(form, existing);
o["commsLossConfirmMs"]!.GetValue<int>().ShouldBe(-5);
o["tags"]!.AsArray().Count.ShouldBe(1);
}
[Fact]
public void Validate_accepts_negative_and_zero_windows_and_warns_at_the_watchdog()
{
new MTConnectDriverForm.MTConnectFormModel { AgentUri = "http://a:5000", CommsLossConfirmMs = -1 }.Validate().ShouldBeNull();
new MTConnectDriverForm.MTConnectFormModel { AgentUri = "http://a:5000", CommsLossConfirmMs = 0 }.Validate().ShouldBeNull();
new MTConnectDriverForm.MTConnectFormModel { AgentUri = "http://a:5000", CommsLossConfirmMs = 89_999 }.Validate().ShouldBeNull();
new MTConnectDriverForm.MTConnectFormModel { AgentUri = "http://a:5000", CommsLossConfirmMs = 90_000 }
.Validate().ShouldNotBeNull().ShouldContain("watchdog");
}
[Theory]
[InlineData(-1, CommsLossOffDocument)]
[InlineData(0, CommsLossImmediateDocument)]
public void The_comms_loss_documents_are_the_literals_the_driver_test_parses(int value, string expected)
{
// Mirrored in MTConnectFactoryTests.The_comms_loss_window_the_AdminUI_form_emits_binds, which runs these exact
// bytes through MTConnectDriver.ParseOptions — the driver's real options DTO.
MTConnectDriverForm.BuildConfigJson(
new MTConnectDriverForm.MTConnectFormModel { AgentUri = "http://agent:5000", CommsLossConfirmMs = value },
null)
.ShouldBe(expected);
}
private const string CommsLossOffDocument =
"""{"agentUri":"http://agent:5000","requestTimeoutMs":5000,"sampleIntervalMs":1000,"sampleCount":1000,"heartbeatMs":10000,"commsLossConfirmMs":-1,"probe":{"enabled":true,"intervalMs":5000,"timeoutMs":2000},"reconnect":{"minBackoffMs":0,"maxBackoffMs":30000,"backoffMultiplier":2},"write":{"enabled":false}}""";
private const string CommsLossImmediateDocument =
"""{"agentUri":"http://agent:5000","requestTimeoutMs":5000,"sampleIntervalMs":1000,"sampleCount":1000,"heartbeatMs":10000,"commsLossConfirmMs":0,"probe":{"enabled":true,"intervalMs":5000,"timeoutMs":2000},"reconnect":{"minBackoffMs":0,"maxBackoffMs":30000,"backoffMultiplier":2},"write":{"enabled":false}}""";
[Fact]
public void The_write_enabled_document_is_the_literal_the_driver_test_parses()
{
@@ -215,7 +284,7 @@ public sealed class MTConnectDriverFormModelTests
/// <summary>The form's output for a write-enabled instance, mirrored in the driver test suite.</summary>
private const string WriteEnabledDocument =
"""{"agentUri":"http://agent:5000","requestTimeoutMs":5000,"sampleIntervalMs":1000,"sampleCount":1000,"heartbeatMs":10000,"probe":{"enabled":true,"intervalMs":5000,"timeoutMs":2000},"reconnect":{"minBackoffMs":0,"maxBackoffMs":30000,"backoffMultiplier":2},"write":{"enabled":true}}""";
"""{"agentUri":"http://agent:5000","requestTimeoutMs":5000,"sampleIntervalMs":1000,"sampleCount":1000,"heartbeatMs":10000,"commsLossConfirmMs":2000,"probe":{"enabled":true,"intervalMs":5000,"timeoutMs":2000},"reconnect":{"minBackoffMs":0,"maxBackoffMs":30000,"backoffMultiplier":2},"write":{"enabled":true}}""";
// ---- Validate ------------------------------------------------------------------------------
@@ -263,6 +332,7 @@ public sealed class MTConnectDriverFormModelTests
ReconnectMinBackoffMs = 100,
ReconnectMaxBackoffMs = 60000,
ReconnectBackoffMultiplier = 1.5,
CommsLossConfirmMs = -1,
};
var json = MTConnectDriverForm.BuildConfigJson(original, null);
@@ -280,6 +350,7 @@ public sealed class MTConnectDriverFormModelTests
back.ReconnectMinBackoffMs.ShouldBe(100);
back.ReconnectMaxBackoffMs.ShouldBe(60000);
back.ReconnectBackoffMultiplier.ShouldBe(1.5);
back.CommsLossConfirmMs.ShouldBe(-1);
}
[Fact]
@@ -373,6 +444,7 @@ public sealed class MTConnectDriverFormModelTests
dto.SampleIntervalMs.ShouldBe(1000);
dto.SampleCount.ShouldBe(1000);
dto.HeartbeatMs.ShouldBe(10000);
dto.CommsLossConfirmMs.ShouldBe(2000);
dto.Probe.ShouldNotBeNull();
dto.Probe!.Enabled.ShouldBe(true);
dto.Probe.IntervalMs.ShouldBe(5000);
@@ -393,6 +465,7 @@ public sealed class MTConnectDriverFormModelTests
public int? SampleIntervalMs { get; init; }
public int? SampleCount { get; init; }
public int? HeartbeatMs { get; init; }
public int? CommsLossConfirmMs { get; init; }
public WireProbe? Probe { get; init; }
public WireReconnect? Reconnect { get; init; }
public WireWrite? Write { get; init; }