feat(mtconnect): IReadable via /current, ordered per-ref snapshots (Task 10)
One deadline-bounded /current per batch, answered out of that one whole-device document: N references cost one round-trip, one snapshot each, in request order, duplicates included. DEVIATION (deliberate, from the plan's implied shared-index write): the response is indexed into a PER-CALL snapshot index, never into the driver's shared observation index. That index is written by Task 11's /sample pump and is last-write-wins with no timestamp arbitration; a read folding its /current into it would be a second writer racing the first, and /current is frequently the OLDER document (the Agent composes it while the pump's newer delta is in flight). Losing that race rolls a subscribed value backwards and leaves it there until the data item next changes. Both paths coerce through the same MTConnectObservationIndex logic, so a read and a subscription report a given observation identically -- the read path is simply a pure function of (document, authored tags). Failure posture is the inverse of InitializeAsync: nothing but genuine caller cancellation crosses the capability boundary. Unreachable Agent / blown deadline / unusable answer => every ref codes BadCommunicationError and the driver degrades (never downgrading Faulted); no client at all (pre-initialize, faulted, post-shutdown) => BadNotConnected with health untouched. The index's BadWaitingForInitialData / BadNodeIdUnknown / BadNoCommunication / BadNotSupported distinctions pass through unmodified. 21 tests pinning arity, order, duplicates, empty batch, one-round-trip, each Bad code, read-time freshness, the anti-clobber invariant, the deadline, and cancellation-propagates-but-agent-failure-does-not. CannedAgentClient gains a cancellation-observing CurrentGate (still no timers or sleeps of its own). Test csproj takes the AbCip/S7 OTOPCUA0001 NoWarn -- this suite calls the capability directly by design. 329/329 green.
This commit is contained in:
Joseph Doherty
@@ -42,14 +42,19 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
|
||||
/// <c>nextSequence</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Scope.</b> This type currently implements <see cref="IDriver"/> only.
|
||||
/// <c>IReadable</c> (Task 10), <c>ISubscribable</c> (Task 11), <c>ITagDiscovery</c>
|
||||
/// (Task 12) and <c>IHostConnectivityProbe</c>/<c>IRediscoverable</c> (Task 13) are added on
|
||||
/// top of the state this class already caches — the probe model, the Agent
|
||||
/// <c>instanceId</c>, and the observation index.
|
||||
/// <b>Scope.</b> This type currently implements <see cref="IDriver"/> and
|
||||
/// <see cref="IReadable"/>. <c>ISubscribable</c> (Task 11), <c>ITagDiscovery</c> (Task 12)
|
||||
/// and <c>IHostConnectivityProbe</c>/<c>IRediscoverable</c> (Task 13) are added on top of
|
||||
/// the state this class already caches — the probe model, the Agent <c>instanceId</c>, and
|
||||
/// the observation index.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The read path never writes the shared observation index</b> — see
|
||||
/// <see cref="ReadAsync"/>. That index has exactly one writer, and Task 11's <c>/sample</c>
|
||||
/// pump is it.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class MTConnectDriver : IDriver
|
||||
public sealed class MTConnectDriver : IDriver, IReadable
|
||||
{
|
||||
/// <summary>
|
||||
/// Coarse per-entry byte weights behind <see cref="GetMemoryFootprint"/>. The contract asks
|
||||
@@ -66,6 +71,20 @@ public sealed class MTConnectDriver : IDriver
|
||||
/// <summary>Estimated retained bytes per authored <see cref="MTConnectTagDefinition"/>.</summary>
|
||||
private const int TagBytesPerEntry = 256;
|
||||
|
||||
/// <summary>
|
||||
/// The Agent could not be reached, answered unusably, or blew the per-call deadline. Distinct
|
||||
/// from the index's <c>BadNoCommunication</c>, which means the Agent answered and said the
|
||||
/// machine has no value — the two failures need different operator responses.
|
||||
/// </summary>
|
||||
private const uint BadCommunicationError = 0x80050000u;
|
||||
|
||||
/// <summary>
|
||||
/// There is no Agent client at all: the driver has not been initialized, its initialize
|
||||
/// faulted, or it has been shut down. Deliberately not one of the index's codes — none of
|
||||
/// them would say "this driver is not running", which is the only true statement available.
|
||||
/// </summary>
|
||||
private const uint BadNotConnected = 0x808A0000u;
|
||||
|
||||
/// <summary>
|
||||
/// Config-JSON reader options, mirroring the sibling driver factories. Note there is
|
||||
/// deliberately <b>no</b> <c>JsonStringEnumConverter</c>: enum-carrying DTO fields stay
|
||||
@@ -137,10 +156,16 @@ public sealed class MTConnectDriver : IDriver
|
||||
public string DriverType => "MTConnect";
|
||||
|
||||
/// <summary>
|
||||
/// The live <c>dataItemId → snapshot</c> map. Consumed by <c>IReadable</c> (Task 10) and the
|
||||
/// <c>/sample</c> pump (Task 11); exposed to tests as the observable proof that
|
||||
/// <see cref="InitializeAsync"/> actually primed it.
|
||||
/// The live <c>dataItemId → snapshot</c> map that backs the <b>subscription</b> surface:
|
||||
/// primed by <see cref="InitializeAsync"/> and thereafter written only by the <c>/sample</c>
|
||||
/// pump (Task 11). Exposed to tests as the observable proof that initialize actually primed
|
||||
/// it — and, in <c>MTConnectReadTests</c>, that <see cref="ReadAsync"/> leaves it alone.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <b>Read does not consume this.</b> <see cref="ReadAsync"/> indexes its own <c>/current</c>
|
||||
/// into a per-call snapshot instead, so the pump keeps a single writer — see the failure
|
||||
/// analysis in <see cref="ReadAsync"/>'s remarks.
|
||||
/// </remarks>
|
||||
internal MTConnectObservationIndex ObservationIndex => Volatile.Read(ref _index);
|
||||
|
||||
/// <summary>
|
||||
@@ -337,6 +362,110 @@ public sealed class MTConnectDriver : IDriver
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>One <c>/current</c> per batch, whatever the batch size.</b> MTConnect's
|
||||
/// <c>/current</c> answers for the whole device (or the whole Agent), so N references
|
||||
/// cost one deadline-bounded round-trip and are answered out of that one document. There
|
||||
/// is no per-reference request to make and none is made.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The response is indexed into a per-call snapshot, NOT into the driver's shared
|
||||
/// observation index.</b> That index is written by the <c>/sample</c> pump (Task 11) and
|
||||
/// is deliberately last-write-wins with no timestamp arbitration. A read that folded its
|
||||
/// <c>/current</c> into it would be a second writer racing the first, and the
|
||||
/// <c>/current</c> document is frequently the <i>older</i> of the two — the Agent
|
||||
/// composes it while the pump's newer delta is already in flight. Losing that race rolls
|
||||
/// a subscribed value backwards and <b>leaves it there until the data item next
|
||||
/// changes</b>, which for an EVENT such as <c>Execution</c> can be hours. Keeping the
|
||||
/// read path a pure function of (document, authored tags) costs one index construction
|
||||
/// per batch — negligible beside the HTTP round-trip that precedes it — and makes it
|
||||
/// impossible for a read to corrupt subscription state. The reference source-of-truth is
|
||||
/// unchanged either way: both paths coerce through the same
|
||||
/// <see cref="MTConnectObservationIndex"/> logic, so a read and a subscription report a
|
||||
/// given observation identically.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Nothing but genuine caller cancellation crosses this boundary.</b> An unreachable
|
||||
/// Agent, a blown deadline, an unusable answer — each fails the batch's <i>values</i>
|
||||
/// (every reference codes <see cref="BadCommunicationError"/>) rather than the batch: an
|
||||
/// exception here would also fail the references that were perfectly readable, and the
|
||||
/// node-manager cannot tell a thrown read from a broken driver. This is the opposite
|
||||
/// posture to <see cref="InitializeAsync"/>, which is specified to throw so the
|
||||
/// runtime's retry/backoff loop can own recovery.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The status-code distinctions the index draws — <c>BadWaitingForInitialData</c> for an
|
||||
/// authored-but-unreported id, <c>BadNodeIdUnknown</c> for an unknown one,
|
||||
/// <c>BadNoCommunication</c> for the Agent's <c>UNAVAILABLE</c> — are passed through
|
||||
/// unmodified. They tell an operator three different things.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
/// <exception cref="ArgumentNullException">
|
||||
/// <paramref name="fullReferences"/> is <c>null</c> — a caller bug, not device data, and the
|
||||
/// one thing this method is loud about (matching <see cref="MTConnectObservationIndex"/>'s
|
||||
/// documented posture).
|
||||
/// </exception>
|
||||
public async Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
|
||||
IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(fullReferences);
|
||||
|
||||
// Checked before anything else: an empty batch must cost the Agent nothing, and there is no
|
||||
// failure it could report.
|
||||
if (fullReferences.Count == 0)
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
var client = _client;
|
||||
var options = _options;
|
||||
|
||||
if (client is null)
|
||||
{
|
||||
// Before InitializeAsync, after a faulted one, or after ShutdownAsync. Health is left
|
||||
// exactly as it is: a read attempted against a driver that was never started (or was
|
||||
// deliberately stopped) is not evidence of degradation.
|
||||
return BadBatch(fullReferences.Count, BadNotConnected);
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
var current = await BoundedAsync(client.CurrentAsync, "/current", options.RequestTimeoutMs, cancellationToken)
|
||||
.ConfigureAwait(false);
|
||||
|
||||
// Built from the SAME authored tags as the shared index, so the authored-vs-unknown
|
||||
// distinction and every coercion behave identically — it is a snapshot, not a variant.
|
||||
var snapshot = new MTConnectObservationIndex(options.Tags);
|
||||
snapshot.Apply(current);
|
||||
|
||||
var results = new DataValueSnapshot[fullReferences.Count];
|
||||
for (var i = 0; i < results.Length; i++)
|
||||
{
|
||||
// Get never throws and never returns null, including for a null/blank reference.
|
||||
results[i] = snapshot.Get(fullReferences[i]);
|
||||
}
|
||||
|
||||
WriteHealth(new DriverHealth(DriverState.Healthy, DateTime.UtcNow, null));
|
||||
|
||||
return results;
|
||||
}
|
||||
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
|
||||
{
|
||||
// The caller asked us to stop. This is the ONLY exception that may propagate: a blown
|
||||
// per-call deadline arrives as the TimeoutException BoundedAsync raises instead, and is
|
||||
// handled below as the Agent failure it is.
|
||||
throw;
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
DegradeAfterReadFailure(ex);
|
||||
|
||||
return BadBatch(fullReferences.Count, BadCommunicationError);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The <c>/probe</c> device model: the cached copy when warm, otherwise a fresh
|
||||
/// deadline-bounded <c>/probe</c> that re-populates the cache. This is the accessor every
|
||||
@@ -609,6 +738,45 @@ public sealed class MTConnectDriver : IDriver
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// One Bad-coded snapshot per requested reference — the shape every read failure degrades
|
||||
/// to. Arity is preserved because the caller indexes the result positionally against the
|
||||
/// references it asked for.
|
||||
/// </summary>
|
||||
private static DataValueSnapshot[] BadBatch(int count, uint status)
|
||||
{
|
||||
// No source timestamp: nothing was observed. The server timestamp is when we gave up.
|
||||
var serverTimestamp = DateTime.UtcNow;
|
||||
var results = new DataValueSnapshot[count];
|
||||
|
||||
for (var i = 0; i < count; i++)
|
||||
{
|
||||
results[i] = new DataValueSnapshot(null, status, null, serverTimestamp);
|
||||
}
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Routes a read failure to the health surface (05/STAB-9's fleet-wide shape): log it and
|
||||
/// degrade, preserving <c>LastSuccessfulRead</c> — the "when did this driver last hear from
|
||||
/// the Agent" diagnostic. Never downgrades <see cref="DriverState.Faulted"/>, which is a
|
||||
/// stronger, config-level signal that a transient read failure must not paper over.
|
||||
/// </summary>
|
||||
private void DegradeAfterReadFailure(Exception ex)
|
||||
{
|
||||
var current = ReadHealth();
|
||||
if (current.State != DriverState.Faulted)
|
||||
{
|
||||
WriteHealth(new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message));
|
||||
}
|
||||
|
||||
_logger.LogWarning(
|
||||
ex,
|
||||
"MTConnect driver {DriverInstanceId} could not read /current from {AgentUri}; the batch is reported Bad.",
|
||||
_driverInstanceId, _options.AgentUri);
|
||||
}
|
||||
|
||||
private static void SafeDispose(IMTConnectAgentClient? client)
|
||||
{
|
||||
if (client is null)
|
||||
|
||||
@@ -81,6 +81,14 @@ internal sealed class CannedAgentClient : IMTConnectAgentClient, IDisposable
|
||||
/// <summary>When set, <c>/current</c> throws this instead of answering.</summary>
|
||||
public Exception? CurrentFailure { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// When set, <c>/current</c> does not answer until this source completes — an Agent that
|
||||
/// accepted the request and then went quiet. The wait is cancellation-observing, so the
|
||||
/// caller's own deadline is what ends it; the test never sleeps and never races a timer it
|
||||
/// did not set. Leave <c>null</c> for the ordinary immediate answer.
|
||||
/// </summary>
|
||||
public TaskCompletionSource? CurrentGate { get; set; }
|
||||
|
||||
/// <summary>Number of <c>/probe</c> requests issued against this client.</summary>
|
||||
public int ProbeCallCount => Volatile.Read(ref _probeCallCount);
|
||||
|
||||
@@ -110,15 +118,21 @@ internal sealed class CannedAgentClient : IMTConnectAgentClient, IDisposable
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
public Task<MTConnectStreamsResult> CurrentAsync(CancellationToken ct)
|
||||
public async Task<MTConnectStreamsResult> CurrentAsync(CancellationToken ct)
|
||||
{
|
||||
ObjectDisposedException.ThrowIf(IsDisposed, this);
|
||||
ct.ThrowIfCancellationRequested();
|
||||
Interlocked.Increment(ref _currentCallCount);
|
||||
|
||||
return CurrentFailure is null
|
||||
? Task.FromResult(Current)
|
||||
: Task.FromException<MTConnectStreamsResult>(CurrentFailure);
|
||||
// The request was accepted; the answer is withheld until the test releases the gate or the
|
||||
// caller's deadline cancels the token.
|
||||
var gate = CurrentGate;
|
||||
if (gate is not null)
|
||||
{
|
||||
await gate.Task.WaitAsync(ct).ConfigureAwait(false);
|
||||
}
|
||||
|
||||
return CurrentFailure is null ? Current : throw CurrentFailure;
|
||||
}
|
||||
|
||||
/// <inheritdoc/>
|
||||
|
||||
@@ -0,0 +1,456 @@
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests;
|
||||
|
||||
/// <summary>
|
||||
/// Task 10 — <see cref="MTConnectDriver"/>'s <see cref="IReadable"/> half: one <c>/current</c>
|
||||
/// per batch, one snapshot per requested reference in request order, and a Bad code for every
|
||||
/// shape of failure. Every test runs against <see cref="CannedAgentClient"/>; no socket is
|
||||
/// opened anywhere in this file.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>The load-bearing assertions are about arity, order, and not-throwing.</b> The caller
|
||||
/// (the runtime's dispatch layer) indexes the returned list <i>positionally</i> against the
|
||||
/// references it asked for, so a length mismatch or a reorder is silent data corruption —
|
||||
/// every value lands on the wrong tag under Good quality. And every failure this driver can
|
||||
/// meet at read time (agent down, deadline blown, unparseable answer, unknown id, driver not
|
||||
/// initialized) must arrive as a Bad-coded snapshot: an exception out of
|
||||
/// <see cref="IReadable.ReadAsync"/> fails the whole batch including the references that
|
||||
/// were perfectly readable.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The one exception that may propagate is genuine caller cancellation</b>, and it is
|
||||
/// pinned here alongside its opposite (an agent failure under an uncancelled token) — the
|
||||
/// two are one <c>catch</c> filter apart in the implementation, and getting the filter
|
||||
/// backwards turns every dead agent into a thrown batch.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class MTConnectReadTests
|
||||
{
|
||||
private const string AgentUri = "http://fixture-agent:5000";
|
||||
|
||||
// Canonical Opc.Ua.StatusCodes numerics, restated here so the test asserts the wire value an
|
||||
// OPC UA client actually sees rather than a driver-private constant it could drift with.
|
||||
private const uint Good = 0x00000000u;
|
||||
private const uint BadMask = 0x80000000u;
|
||||
private const uint BadCommunicationError = 0x80050000u;
|
||||
private const uint BadNoCommunication = 0x80310000u;
|
||||
private const uint BadWaitingForInitialData = 0x80320000u;
|
||||
private const uint BadNodeIdUnknown = 0x80340000u;
|
||||
private const uint BadNotSupported = 0x803D0000u;
|
||||
private const uint BadNotConnected = 0x808A0000u;
|
||||
|
||||
/// <summary>
|
||||
/// Authored tags spanning every read outcome the fixtures can produce: a coercible Good
|
||||
/// value, an <c>UNAVAILABLE</c> one, a TIME_SERIES vector, and one authored id no fixture
|
||||
/// ever reports.
|
||||
/// </summary>
|
||||
private static MTConnectDriverOptions Opts(int requestTimeoutMs = 5000) =>
|
||||
new()
|
||||
{
|
||||
AgentUri = AgentUri,
|
||||
RequestTimeoutMs = requestTimeoutMs,
|
||||
Tags =
|
||||
[
|
||||
new MTConnectTagDefinition("dev1_pos", DriverDataType.Float64),
|
||||
new MTConnectTagDefinition("dev1_execution", DriverDataType.String),
|
||||
new MTConnectTagDefinition("dev1_partcount", DriverDataType.Int32),
|
||||
new MTConnectTagDefinition("dev1_vibration_ts", DriverDataType.Float64, IsArray: true, ArrayDim: 10),
|
||||
new MTConnectTagDefinition("dev1_never_reported", DriverDataType.Int32),
|
||||
],
|
||||
};
|
||||
|
||||
private static (MTConnectDriver Driver, CannedAgentClient Client) NewDriver(
|
||||
MTConnectDriverOptions? options = null)
|
||||
{
|
||||
var client = CannedAgentClient.FromFixtures();
|
||||
|
||||
return (new MTConnectDriver(options ?? Opts(), "mt1", _ => client), client);
|
||||
}
|
||||
|
||||
private static async Task<(MTConnectDriver Driver, CannedAgentClient Client)> InitializedDriverAsync(
|
||||
MTConnectDriverOptions? options = null)
|
||||
{
|
||||
var (driver, client) = NewDriver(options);
|
||||
await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
|
||||
|
||||
return (driver, client);
|
||||
}
|
||||
|
||||
// ---- arity + order: the contract the caller indexes positionally ----
|
||||
|
||||
/// <summary>The plan's TDD case: one snapshot per ref, in order, absent ⇒ Bad rather than a throw.</summary>
|
||||
[Fact]
|
||||
public async Task Read_returns_one_snapshot_per_ref_in_order_absent_ref_is_bad()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_pos", "does-not-exist"], TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(2);
|
||||
res[0].StatusCode.ShouldBe(Good);
|
||||
(res[1].StatusCode & BadMask).ShouldBe(BadMask);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A mixed batch requested in an order that matches neither the document order nor any
|
||||
/// dictionary enumeration order. This is the assertion that catches a driver that answers
|
||||
/// with the index's own key order instead of the request's.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_answers_in_request_order_not_document_order()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(
|
||||
["dev1_program", "dev1_pos", "does-not-exist", "dev1_partcount", "dev1_execution"],
|
||||
TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(5);
|
||||
|
||||
// dev1_program is observed but NOT authored — String is the only coercion that cannot fail.
|
||||
res[0].StatusCode.ShouldBe(Good);
|
||||
res[0].Value.ShouldBe("O1234");
|
||||
|
||||
res[1].StatusCode.ShouldBe(Good);
|
||||
res[1].Value.ShouldBe(123.4567d);
|
||||
|
||||
res[2].StatusCode.ShouldBe(BadNodeIdUnknown);
|
||||
|
||||
res[3].StatusCode.ShouldBe(BadNoCommunication);
|
||||
|
||||
res[4].StatusCode.ShouldBe(Good);
|
||||
res[4].Value.ShouldBe("ACTIVE");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A reference repeated in one request gets a snapshot per occurrence. De-duplicating would
|
||||
/// shorten the list and shift every later reference onto the wrong tag.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_returns_a_snapshot_per_duplicate_occurrence()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(
|
||||
["dev1_pos", "dev1_execution", "dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(3);
|
||||
res[0].StatusCode.ShouldBe(Good);
|
||||
res[0].Value.ShouldBe(123.4567d);
|
||||
res[1].Value.ShouldBe("ACTIVE");
|
||||
res[2].StatusCode.ShouldBe(Good);
|
||||
res[2].Value.ShouldBe(123.4567d);
|
||||
}
|
||||
|
||||
/// <summary>An empty batch is empty — and, being empty, costs the Agent nothing.</summary>
|
||||
[Fact]
|
||||
public async Task Read_of_an_empty_batch_is_empty_and_costs_no_round_trip()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync();
|
||||
var before = client.CurrentCallCount;
|
||||
|
||||
var res = await driver.ReadAsync([], TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(0);
|
||||
client.CurrentCallCount.ShouldBe(before);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A batch of N references costs exactly ONE <c>/current</c>. The whole point of reading the
|
||||
/// Agent's whole-device snapshot is that per-tag round-trips never happen.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_of_many_refs_costs_exactly_one_current_call()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync();
|
||||
var before = client.CurrentCallCount;
|
||||
|
||||
var res = await driver.ReadAsync(
|
||||
["dev1_pos", "dev1_execution", "dev1_partcount", "dev1_program", "does-not-exist", "dev1_pos"],
|
||||
TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(6);
|
||||
client.CurrentCallCount.ShouldBe(before + 1);
|
||||
}
|
||||
|
||||
// ---- status-code fidelity: the index's distinctions must survive the trip ----
|
||||
|
||||
/// <summary>A genuinely unknown id — neither authored nor ever observed.</summary>
|
||||
[Fact]
|
||||
public async Task Read_of_an_unknown_ref_reports_BadNodeIdUnknown()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(["nope"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(BadNodeIdUnknown);
|
||||
res[0].Value.ShouldBeNull();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// An authored id the Agent has never reported is <c>BadWaitingForInitialData</c>, NOT
|
||||
/// <c>BadNodeIdUnknown</c> — collapsing the two would tell an operator their correctly
|
||||
/// authored tag does not exist.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_of_an_authored_but_unreported_ref_reports_BadWaitingForInitialData()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_never_reported"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(BadWaitingForInitialData);
|
||||
}
|
||||
|
||||
/// <summary>The Agent said <c>UNAVAILABLE</c>: reachable Agent, absent machine value.</summary>
|
||||
[Fact]
|
||||
public async Task Read_of_an_unavailable_ref_reports_BadNoCommunication()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_partcount"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(BadNoCommunication);
|
||||
res[0].Value.ShouldBeNull();
|
||||
res[0].SourceTimestampUtc.ShouldNotBeNull();
|
||||
}
|
||||
|
||||
/// <summary>A TIME_SERIES vector is real data this build cannot represent (P1.5 deferral).</summary>
|
||||
[Fact]
|
||||
public async Task Read_of_a_time_series_ref_reports_BadNotSupported()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_vibration_ts"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(BadNotSupported);
|
||||
}
|
||||
|
||||
/// <summary>A blank reference is data, not a programming error — it codes Bad, it does not throw.</summary>
|
||||
[Fact]
|
||||
public async Task Read_of_a_blank_ref_is_bad_not_a_throw()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(["", " ", "dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(3);
|
||||
res[0].StatusCode.ShouldBe(BadNodeIdUnknown);
|
||||
res[1].StatusCode.ShouldBe(BadNodeIdUnknown);
|
||||
res[2].StatusCode.ShouldBe(Good);
|
||||
}
|
||||
|
||||
/// <summary>The authored type is honoured: the Agent's text becomes a CLR value of that type.</summary>
|
||||
[Fact]
|
||||
public async Task Read_coerces_the_agent_text_to_the_authored_type()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(Good);
|
||||
res[0].Value.ShouldBeOfType<double>().ShouldBe(123.4567d);
|
||||
res[0].SourceTimestampUtc.ShouldBe(new DateTime(2026, 7, 24, 12, 0, 0, 200, DateTimeKind.Utc));
|
||||
}
|
||||
|
||||
// ---- freshness: a read is a read, not a replay of the initialize baseline ----
|
||||
|
||||
/// <summary>
|
||||
/// The whole justification for spending a round-trip: an OPC UA Read must reflect the
|
||||
/// device's <i>current</i> state, not whatever <see cref="MTConnectDriver.InitializeAsync"/>
|
||||
/// happened to prime. A driver that served the primed index would pass every other test in
|
||||
/// this file.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_reflects_the_agent_state_at_read_time_not_the_initialize_baseline()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync();
|
||||
|
||||
// The Agent has moved on since the priming /current (sample.xml reports 124.0100).
|
||||
client.Current = CannedAgentClient.Chunk("Fixtures/sample.xml");
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(Good);
|
||||
res[0].Value.ShouldBe(124.01d);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// <b>The anti-clobber pin.</b> <c>ReadAsync</c> indexes its <c>/current</c> into a
|
||||
/// per-call snapshot and never writes the driver's shared observation index — that index has
|
||||
/// exactly one writer, the Task 11 <c>/sample</c> pump. If a read wrote it, a <c>/current</c>
|
||||
/// document older than the pump's newest delta would silently roll a subscribed value
|
||||
/// backwards and leave it there until the next change.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_does_not_write_the_shared_observation_index()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync();
|
||||
var primed = driver.ObservationIndex.Get("dev1_pos");
|
||||
|
||||
client.Current = CannedAgentClient.Chunk("Fixtures/sample.xml");
|
||||
var res = await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
// The read saw the new value...
|
||||
res[0].Value.ShouldBe(124.01d);
|
||||
|
||||
// ...and the shared index still holds exactly what the pump/priming left there.
|
||||
var after = driver.ObservationIndex.Get("dev1_pos");
|
||||
after.Value.ShouldBe(primed.Value);
|
||||
after.Value.ShouldBe(123.4567d);
|
||||
}
|
||||
|
||||
// ---- failure posture: Bad snapshots, never exceptions ----
|
||||
|
||||
/// <summary>
|
||||
/// An unreachable Agent fails the batch's values, not the batch. Every reference codes
|
||||
/// <c>BadCommunicationError</c> and the call returns normally.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_codes_every_ref_bad_when_the_agent_call_fails()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync();
|
||||
client.CurrentFailure = new HttpRequestException("connection refused");
|
||||
|
||||
var res = await driver.ReadAsync(
|
||||
["dev1_pos", "dev1_execution", "does-not-exist"], TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(3);
|
||||
res.ShouldAllBe(r => r.StatusCode == BadCommunicationError);
|
||||
res.ShouldAllBe(r => r.Value == null);
|
||||
}
|
||||
|
||||
/// <summary>An answer the driver cannot make sense of is a Bad batch, not a thrown one.</summary>
|
||||
[Fact]
|
||||
public async Task Read_codes_every_ref_bad_when_the_agent_answer_is_unusable()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync();
|
||||
client.CurrentFailure = new System.Xml.XmlException("unexpected end of document");
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(BadCommunicationError);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A failed read degrades the driver rather than leaving it advertising Healthy, and a later
|
||||
/// successful read restores it. <c>LastSuccessfulRead</c> survives the degradation — it is
|
||||
/// the "when did this driver last hear from the Agent" diagnostic.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_failure_degrades_the_driver_and_a_later_success_restores_it()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync();
|
||||
client.CurrentFailure = new HttpRequestException("connection refused");
|
||||
|
||||
await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
var degraded = driver.GetHealth();
|
||||
degraded.State.ShouldBe(DriverState.Degraded);
|
||||
degraded.LastSuccessfulRead.ShouldNotBeNull();
|
||||
degraded.LastError.ShouldNotBeNullOrWhiteSpace();
|
||||
|
||||
client.CurrentFailure = null;
|
||||
await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
driver.GetHealth().State.ShouldBe(DriverState.Healthy);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// R2-01 — the <c>/current</c> runs under a bounded deadline. An Agent that accepts the
|
||||
/// request and never answers surfaces as a Bad batch on the driver's own clock rather than
|
||||
/// wedging the caller forever.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_is_bounded_by_the_per_call_deadline()
|
||||
{
|
||||
var (driver, client) = await InitializedDriverAsync(Opts(requestTimeoutMs: 50));
|
||||
var gate = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
|
||||
client.CurrentGate = gate;
|
||||
|
||||
try
|
||||
{
|
||||
var res = await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(1);
|
||||
res[0].StatusCode.ShouldBe(BadCommunicationError);
|
||||
}
|
||||
finally
|
||||
{
|
||||
gate.TrySetResult();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The one exception that may cross the capability boundary. Note the contrast with
|
||||
/// <see cref="Read_codes_every_ref_bad_when_the_agent_call_fails"/>: same code path, one
|
||||
/// <c>catch</c> filter apart.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_propagates_genuine_caller_cancellation()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
using var cts = new CancellationTokenSource();
|
||||
await cts.CancelAsync();
|
||||
|
||||
await Should.ThrowAsync<OperationCanceledException>(
|
||||
() => driver.ReadAsync(["dev1_pos"], cts.Token));
|
||||
}
|
||||
|
||||
// ---- reads outside the initialized window ----
|
||||
|
||||
/// <summary>
|
||||
/// A read before <c>InitializeAsync</c> has no Agent to ask. It reports
|
||||
/// <c>BadNotConnected</c> for every reference — it does not throw, it does not
|
||||
/// <c>NullReferenceException</c>, and it does not invent a value.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_before_initialize_is_bad_not_connected()
|
||||
{
|
||||
var (driver, client) = NewDriver();
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_pos", "nope"], TestContext.Current.CancellationToken);
|
||||
|
||||
res.Count.ShouldBe(2);
|
||||
res.ShouldAllBe(r => r.StatusCode == BadNotConnected);
|
||||
client.CurrentCallCount.ShouldBe(0);
|
||||
|
||||
// An un-started driver is Unknown, not Degraded: nothing has failed yet.
|
||||
driver.GetHealth().State.ShouldBe(DriverState.Unknown);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Same posture after <c>ShutdownAsync</c>, and shutting down must stay reported as
|
||||
/// <see cref="DriverState.Unknown"/> — a read attempted against a deliberately stopped
|
||||
/// driver is not a degradation.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_after_shutdown_is_bad_not_connected_and_leaves_health_alone()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
await driver.ShutdownAsync(TestContext.Current.CancellationToken);
|
||||
|
||||
var res = await driver.ReadAsync(["dev1_pos"], TestContext.Current.CancellationToken);
|
||||
|
||||
res[0].StatusCode.ShouldBe(BadNotConnected);
|
||||
driver.GetHealth().State.ShouldBe(DriverState.Unknown);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A <c>null</c> reference list is a caller bug, not device data — the one place this method
|
||||
/// is allowed to be loud, matching <see cref="MTConnectObservationIndex"/>'s documented
|
||||
/// posture ("the only exceptions raised are <c>ArgumentNullException</c> for a null argument").
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Read_of_a_null_ref_list_throws_ArgumentNullException()
|
||||
{
|
||||
var (driver, _) = await InitializedDriverAsync();
|
||||
|
||||
await Should.ThrowAsync<ArgumentNullException>(
|
||||
() => driver.ReadAsync(null!, TestContext.Current.CancellationToken));
|
||||
}
|
||||
}
|
||||
+7
@@ -1,5 +1,12 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<!-- OTOPCUA0001 (arch-review 07/C-1): this suite invokes driver capability methods DIRECTLY to
|
||||
exercise wire-level behavior — the analyzer's documented intentional case ("move the suppression
|
||||
into a NoWarn for the test project"). Not a resilience-dispatch gap. -->
|
||||
<PropertyGroup>
|
||||
<NoWarn>$(NoWarn);OTOPCUA0001</NoWarn>
|
||||
</PropertyGroup>
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<Nullable>enable</Nullable>
|
||||
|
||||
Reference in New Issue
Block a user