dohertj2/lmxopcua
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(mtconnect): agent-client observation write (HTTP POST, AllowPut surface)

Browse Source
This commit is contained in:
Joseph Doherty
2026-08-05 06:16:35 -04:00
parent b5e39e1f32
commit 9f17d7efa2
4 changed files with 580 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/IMTConnectAgentClient.cs
+84 -1
View File
@@ -1,5 +1,27 @@
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
/// <summary>
/// The result of a <see cref="IMTConnectAgentClient.WriteObservationAsync"/> call, as the
/// <b>Agent</b> answered it. A transport failure is never represented here — it throws (see the
/// method's contract), so an outcome always means "the Agent replied, and this is what it said".
/// </summary>
/// <param name="Accepted">
/// <c>true</c> when the Agent took the observation: a 2xx response whose body is not an
/// <c>MTConnectError</c> document. <c>false</c> is a refusal, and
/// <see cref="AgentError"/> then always carries text.
/// </param>
/// <param name="AgentError">
/// Why the Agent refused, in its own words where it supplied any — the joined
/// <c>errorCode: text</c> of the <c>MTConnectError</c> document, or the HTTP status line for a
/// non-2xx answer. <c>null</c> if and only if <see cref="Accepted"/> is <c>true</c>.
/// <para>
/// This is Agent-authored text destined for a <b>log line</b>, never for a driver's
/// <c>LastError</c> (which is type-only by repo-wide discipline) and never for an OPC UA
/// status code's own message.
/// </para>
/// </param>
public sealed record MTConnectWriteOutcome(bool Accepted, string? AgentError);
/// <summary>
/// The seam between the MTConnect driver and an MTConnect Agent's HTTP surface
/// (<c>/probe</c>, <c>/current</c>, <c>/sample</c>). This interface is transport-neutral by
@@ -17,7 +39,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
/// <c>/sample</c> long poll. (Task 0 planned to build on the TrakHound MTConnect.NET libraries;
/// Tasks 6 and 7 proved they can neither parse a document nor frame the stream socket-free, and
/// dropped the references — see the Task 0 CORRECTION block in the plan.) A fake for tests only
/// needs to implement these three instance members; <see cref="IsSequenceGap"/> is a static
/// needs to implement these four instance members; <see cref="IsSequenceGap"/> is a static
/// protocol rule that lives here, rather than on the implementation, so a consumer written
/// against this seam never has to reference the concrete client.
/// </para>
@@ -88,6 +110,67 @@ public interface IMTConnectAgentClient : IDisposable
/// <param name="ct">Cancellation token; cancelling is the contracted way to end the stream.</param>
IAsyncEnumerable<MTConnectStreamsResult> SampleAsync(long from, CancellationToken ct);
/// <summary>
/// Sets the Agent's observation for one DataItem, through the Agent's <c>AllowPut</c>
/// surface (<c>POST {agent}/{deviceName}?{dataItemId}={value}</c>).
/// </summary>
/// <remarks>
/// <para>
/// <b>This is observation injection, not machine command.</b> The value lands in the
/// Agent's observation buffer exactly as if an adapter had reported it — every consumer
/// of that Agent then sees it, and the next adapter/SHDR update for the same DataItem
/// overwrites it. Nothing is sent to the machine. It is also gated twice and off at both
/// gates by default: the Agent's own <c>AllowPut</c> (<c>agent.cfg</c>) and the driver's
/// <c>write.enabled</c>.
/// </para>
/// <para>
/// <b>A refusal is a return value; a transport failure is an exception.</b> The split is
/// the whole point of the outcome type, and it is what lets the driver map the two to
/// different OPC UA status codes without inspecting exception text:
/// <list type="bullet">
/// <item>
/// The Agent answered and <b>took</b> the observation (2xx, body empty or not an
/// <c>MTConnectError</c>) ⇒ <see cref="MTConnectWriteOutcome.Accepted"/>. An
/// <b>empty 2xx body is acceptance</b> — that is what a cppagent actually sends,
/// so treating a body-less answer as suspect would refuse every successful write.
/// </item>
/// <item>
/// The Agent answered and <b>refused</b> — a non-2xx status, or an
/// <c>MTConnectError</c> document served (as Agents do) under <b>HTTP 200</b> ⇒
/// not accepted, with the Agent's own text in
/// <see cref="MTConnectWriteOutcome.AgentError"/>. The 200-with-error shape is
/// why the status code alone can never decide this.
/// </item>
/// <item>
/// The Agent could not be <b>reached or did not answer in time</b> ⇒ throws
/// (<see cref="HttpRequestException"/>, or a <see cref="TimeoutException"/> for
/// the per-call deadline; <see cref="OperationCanceledException"/> when
/// <paramref name="cancellationToken"/> is cancelled or the client is disposed).
/// Folding these into a <c>false</c> outcome would make "the machine's Agent is
/// unreachable" indistinguishable from "the Agent rejected this DataItem" —
/// identical to the caller, opposite in what an operator must do about it.
/// </item>
/// </list>
/// </para>
/// <para>
/// <b>The write is a URL, so escaping is this seam's job, not the caller's.</b>
/// <paramref name="dataItemId"/> and <paramref name="value"/> are passed <i>unescaped</i>
/// and are percent-encoded by the implementation. A caller that pre-escaped would
/// double-encode and write a literal <c>%20</c> into the Agent's buffer, which the Agent
/// accepts — so the corruption is silent and shows up only as a wrong value on read-back.
/// </para>
/// </remarks>
/// <param name="deviceName">
/// The device that owns the DataItem — the path segment of the request. Required even on a
/// single-device Agent, because the Agent's PUT surface is addressed per device.
/// </param>
/// <param name="dataItemId">The DataItem's <c>id</c>, as declared by <c>/probe</c>. Unescaped.</param>
/// <param name="value">The value to report, already rendered to its invariant string form. Unescaped.</param>
/// <param name="cancellationToken">Cancellation token.</param>
/// <returns>What the Agent said — see the remarks.</returns>
Task<MTConnectWriteOutcome> WriteObservationAsync(
string deviceName, string dataItemId, string value, CancellationToken cancellationToken);
/// <summary>
/// Has the Agent's ring buffer overflowed past the sequence the caller expected next? True
/// when the chunk's oldest retained sequence is <i>strictly</i> newer than
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectAgentClient.cs
+163 -6
View File
@@ -1,6 +1,8 @@
using System.Globalization;
using System.Runtime.CompilerServices;
using System.Text;
using System.Xml;
using System.Xml.Linq;
using Microsoft.Extensions.Logging;
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
@@ -75,6 +77,7 @@ public sealed class MTConnectAgentClient : IMTConnectAgentClient, IDisposable
private readonly ILogger? _logger;
private readonly Uri _probeUri;
private readonly Uri _currentUri;
private readonly string _agentRoot;
private readonly string _sampleUriBase;
private readonly string _sampleQuerySuffix;
private readonly TimeSpan _requestTimeout;
@@ -133,6 +136,7 @@ public sealed class MTConnectAgentClient : IMTConnectAgentClient, IDisposable
// Agent and an idle one both emit at least one chunk per heartbeat.
_streamIdleTimeout = TimeSpan.FromMilliseconds((2L * options.HeartbeatMs) + options.RequestTimeoutMs);
_agentRoot = ResolveAgentRoot(options);
_probeUri = BuildRequestUri(options, "probe");
_currentUri = BuildRequestUri(options, "current");
_sampleUriBase = BuildRequestUri(options, "sample").AbsoluteUri;
@@ -242,6 +246,139 @@ public sealed class MTConnectAgentClient : IMTConnectAgentClient, IDisposable
}
}
/// <inheritdoc/>
/// <remarks>
/// Issued on <c>_http</c>, the <b>unary</b> client — the write is a short request/response
/// and must be bounded by <c>RequestTimeoutMs</c> like the other unary legs. Sending it on
/// the streaming client would inherit that client's infinite timeout, and a frozen Agent
/// would park a write forever with nothing to bound it (the streaming leg's heartbeat
/// watchdog protects a multipart body, not a one-shot POST).
/// </remarks>
public async Task<MTConnectWriteOutcome> WriteObservationAsync(
string deviceName, string dataItemId, string value, CancellationToken cancellationToken)
{
ObjectDisposedException.ThrowIf(_disposed, this);
ArgumentException.ThrowIfNullOrWhiteSpace(deviceName);
ArgumentException.ThrowIfNullOrWhiteSpace(dataItemId);
ArgumentNullException.ThrowIfNull(value);
var uri = BuildWriteUri(deviceName, dataItemId, value);
using var lifetime = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, _disposeCts.Token);
using var deadline = CancellationTokenSource.CreateLinkedTokenSource(lifetime.Token);
deadline.CancelAfter(_requestTimeout);
using var request = new HttpRequestMessage(HttpMethod.Post, uri);
HttpResponseMessage response;
try
{
response = await _http.SendAsync(request, deadline.Token).ConfigureAwait(false);
}
catch (OperationCanceledException) when (!lifetime.IsCancellationRequested)
{
throw TimedOut(uri);
}
using (response)
{
string body;
try
{
body = await response.Content.ReadAsStringAsync(deadline.Token).ConfigureAwait(false);
}
catch (OperationCanceledException) when (!lifetime.IsCancellationRequested)
{
throw TimedOut(uri);
}
// Deliberately NOT EnsureSuccessStatusCode: a refused write is an answer, and the caller
// needs it as a value it can map to a per-tag status code rather than as an exception
// indistinguishable from the Agent being unreachable.
var agentError = DescribeAgentError(body);
if (!response.IsSuccessStatusCode)
{
var status = $"HTTP {(int)response.StatusCode} {response.ReasonPhrase}".TrimEnd();
return new MTConnectWriteOutcome(
Accepted: false, agentError is null ? status : $"{status}: {agentError}");
}
// An MTConnectError document under HTTP 200 is how an Agent actually refuses; the status
// code alone would report it as a success.
return agentError is null
? new MTConnectWriteOutcome(Accepted: true, AgentError: null)
: new MTConnectWriteOutcome(Accepted: false, agentError);
}
}
/// <summary>
/// The Agent's <c>AllowPut</c> URL: the device as a path segment, the DataItem id and value
/// as a query pair. Every caller-supplied part is percent-encoded here — see the seam's
/// contract for why escaping cannot be the caller's job.
/// </summary>
private Uri BuildWriteUri(string deviceName, string dataItemId, string value)
{
var device = Uri.EscapeDataString(deviceName.Trim());
var query = $"{Uri.EscapeDataString(dataItemId)}={Uri.EscapeDataString(value)}";
return new Uri($"{_agentRoot}/{device}?{query}", UriKind.Absolute);
}
/// <summary>
/// The Agent's own refusal text when <paramref name="body"/> is an <c>MTConnectError</c>
/// document, else <c>null</c> (including for an empty body, a non-XML body, and any other
/// MTConnect document).
/// </summary>
/// <remarks>
/// Read by <see cref="XName.LocalName"/> only, like every other document this driver parses:
/// the namespace URI carries the MTConnect version, so a qualified match would silently stop
/// recognising errors the day an Agent is upgraded — and an unrecognised error reads as a
/// successful write.
/// </remarks>
private static string? DescribeAgentError(string body)
{
if (string.IsNullOrWhiteSpace(body))
{
return null;
}
XElement? root;
try
{
root = XDocument.Parse(body).Root;
}
catch (XmlException)
{
// Not XML at all — an Agent that answered 2xx with a plain-text or HTML body has not
// refused anything, so this is not the place to invent a failure.
return null;
}
if (root is null || !MTConnectXml.IsNamed(root, "MTConnectError"))
{
return null;
}
var errors = root.Descendants()
.Where(e => MTConnectXml.IsNamed(e, "Error"))
.Select(e =>
{
var code = MTConnectXml.OptionalAttribute(e, "errorCode");
var text = e.Value.Trim();
return code is null ? text : $"{code}: {text}";
})
.Where(text => text.Length > 0)
.ToList();
// An error document with no readable detail is still a refusal; reporting it as null would
// turn it back into an acceptance.
return errors.Count == 0
? "The Agent answered with an MTConnectError document carrying no error detail."
: string.Join("; ", errors);
}
/// <inheritdoc/>
public void Dispose()
{
@@ -379,7 +516,31 @@ public sealed class MTConnectAgentClient : IMTConnectAgentClient, IDisposable
return boundary;
}
private static Uri BuildRequestUri(MTConnectDriverOptions options, string request)
/// <summary>
/// A read path's request URI, scoped to the configured device. Reads <see cref="_agentRoot"/>,
/// so it may only be called after that field is assigned — which the constructor does first.
/// </summary>
private Uri BuildRequestUri(MTConnectDriverOptions options, string request)
{
var deviceName = options.DeviceName?.Trim();
var deviceSegment = string.IsNullOrEmpty(deviceName) ? string.Empty : $"/{Uri.EscapeDataString(deviceName)}";
return new Uri($"{_agentRoot}{deviceSegment}/{request}", UriKind.Absolute);
}
/// <summary>
/// Validates <see cref="MTConnectDriverOptions.AgentUri"/> and reduces it to the base every
/// request path is appended to: its left part up to and including the path (so a proxied
/// Agent keeps its prefix), with any trailing slash removed so callers can append
/// <c>/segment</c> unconditionally.
/// </summary>
/// <remarks>
/// Extracted rather than duplicated because the write path resolves its device at call time,
/// not at construction: two copies of this rule would drift, and the drift would surface as
/// writes landing on a URL the reads never used — against an Agent that answers 200 either
/// way.
/// </remarks>
private static string ResolveAgentRoot(MTConnectDriverOptions options)
{
var agentUri = options.AgentUri?.Trim();
if (string.IsNullOrEmpty(agentUri))
@@ -395,11 +556,7 @@ public sealed class MTConnectAgentClient : IMTConnectAgentClient, IDisposable
$"{nameof(MTConnectDriverOptions.AgentUri)} '{agentUri}' is not an absolute http(s) URI.", nameof(options));
}
var root = parsed.GetLeftPart(UriPartial.Path).TrimEnd('/');
var deviceName = options.DeviceName?.Trim();
var deviceSegment = string.IsNullOrEmpty(deviceName) ? string.Empty : $"/{Uri.EscapeDataString(deviceName)}";
return new Uri($"{root}{deviceSegment}/{request}", UriKind.Absolute);
return parsed.GetLeftPart(UriPartial.Path).TrimEnd('/');
}
/// <summary>
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/CannedAgentClient.cs
+26
View File
@@ -355,6 +355,32 @@ internal sealed class CannedAgentClient : IMTConnectAgentClient, IDisposable
}
}
/// <summary>
/// Every write this Agent was asked to take, in order — the record a driver-level write test
/// asserts against (which DataItem, on which device, carrying what).
/// </summary>
public ConcurrentQueue<(string DeviceName, string DataItemId, string Value)> Writes { get; } = new();
/// <summary>
/// What <see cref="WriteObservationAsync"/> answers with. Defaults to acceptance; set it to a
/// refusal to script the Agent's <c>MTConnectError</c> leg.
/// </summary>
public MTConnectWriteOutcome WriteOutcome { get; set; } = new(Accepted: true, AgentError: null);
/// <summary>When set, a write throws this instead of answering — the transport-failure leg.</summary>
public Exception? WriteFailure { get; set; }
/// <inheritdoc/>
public Task<MTConnectWriteOutcome> WriteObservationAsync(
string deviceName, string dataItemId, string value, CancellationToken cancellationToken)
{
ObjectDisposedException.ThrowIf(IsDisposed, this);
cancellationToken.ThrowIfCancellationRequested();
Writes.Enqueue((deviceName, dataItemId, value));
return WriteFailure is null ? Task.FromResult(WriteOutcome) : throw WriteFailure;
}
/// <summary>
/// Queues a chunk onto the scripted <c>/sample</c> stream and waits until the consumer has
/// processed it. This is the deterministic replacement for "wait a bit and hope the pump
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/MTConnectAgentClientWriteTests.cs
+307
View File
@@ -0,0 +1,307 @@
using System.Net;
using System.Text;
using Shouldly;
using Xunit;
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests;
/// <summary>
/// The wire contract of <see cref="MTConnectAgentClient.WriteObservationAsync"/> — the Agent's
/// <c>AllowPut</c> surface. Everything here runs through a stubbed
/// <see cref="HttpMessageHandler"/> via the internal test-seam constructor, so the verb, the
/// exact request URI, and each response shape are asserted with no socket and no Agent.
/// </summary>
/// <remarks>
/// <para>
/// <b>The URI assertions are the point of this class, not incidental detail.</b> A write is
/// nothing but a URL: get the escaping or the device segment wrong and the Agent still
/// answers 200, having stored a value under a DataItem id nobody asked about — a corruption
/// with no error anywhere, visible only on a later read-back. There is no encoder to unit
/// test, so this is the only place that shape is pinned.
/// </para>
/// <para>
/// <b>The refusal legs pin the split the seam contract rests on:</b> an Agent that answered
/// and said no is a returned outcome, while an Agent that could not be reached throws. The
/// 200-carrying-an-<c>MTConnectError</c> case is why the status code alone can never decide
/// it — that is the shape a real cppagent uses to report every objection.
/// </para>
/// </remarks>
[Trait("Category", "Unit")]
public sealed class MTConnectAgentClientWriteTests
{
// ── stub handler ─────────────────────────────────────────────────────────
/// <summary>Answers every request with a canned response (or throws) via a delegate, with no socket.</summary>
private sealed class StubHandler(Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> respond)
: HttpMessageHandler
{
protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct) =>
respond(request, ct);
}
/// <summary>Records the requests it is handed, then answers each with <paramref name="respond"/>.</summary>
private sealed class RecordingHandler(Func<HttpRequestMessage, HttpResponseMessage> respond) : HttpMessageHandler
{
public List<(HttpMethod Method, Uri Uri)> Requests { get; } = [];
protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
{
Requests.Add((request.Method, request.RequestUri!));
return Task.FromResult(respond(request));
}
}
private static MTConnectDriverOptions Options(string agentUri = "http://stub-agent:5000") =>
new() { AgentUri = agentUri };
private static HttpResponseMessage Ok(string body = "") => new(HttpStatusCode.OK)
{
Content = new StringContent(body, Encoding.UTF8, "text/plain"),
};
private static HttpResponseMessage XmlOk(string xml) => new(HttpStatusCode.OK)
{
Content = new StringContent(xml, Encoding.UTF8, "text/xml"),
};
/// <summary>Exactly the shape a cppagent uses to refuse: an error document served under HTTP 200.</summary>
private const string MTConnectErrorXml =
"""
<?xml version="1.0" encoding="UTF-8"?>
<MTConnectError xmlns="urn:mtconnect.org:MTConnectError:1.3">
<Header creationTime="2026-08-05T12:00:00Z" sender="stub-agent" instanceId="1" version="1.3.0.12" bufferSize="1"/>
<Errors>
<Error errorCode="UNSUPPORTED">Cannot find device data item: nosuchitem</Error>
</Errors>
</MTConnectError>
""";
// ── verb + URI ───────────────────────────────────────────────────────────
[Fact]
public async Task A_write_is_issued_as_a_POST()
{
var handler = new RecordingHandler(_ => Ok());
using var client = new MTConnectAgentClient(Options(), handler);
await client.WriteObservationAsync("StubDevice", "dev1_msg", "hello", CancellationToken.None);
handler.Requests.ShouldHaveSingleItem().Method.ShouldBe(HttpMethod.Post);
}
/// <summary>
/// The device is a <b>path segment</b> and the DataItem id/value are a <b>query pair</b> —
/// the Agent's documented AllowPut shape. Asserted as the whole URI rather than in parts,
/// because a fragment-wise assertion passes on a URI that is assembled in the wrong order.
/// </summary>
[Fact]
public async Task The_request_uri_is_the_agents_AllowPut_shape()
{
var handler = new RecordingHandler(_ => Ok());
using var client = new MTConnectAgentClient(Options(), handler);
await client.WriteObservationAsync("StubDevice", "dev1_msg", "hello", CancellationToken.None);
handler.Requests.ShouldHaveSingleItem().Uri.AbsoluteUri
.ShouldBe("http://stub-agent:5000/StubDevice?dev1_msg=hello");
}
/// <summary>
/// A value carrying a space, an <c>&amp;</c> and a <c>=</c> — each of which silently ends the
/// query pair early if it reaches the wire raw — plus a DataItem id needing the same
/// treatment. Unescaped, the Agent would take a 200 and store the truncated value.
/// </summary>
[Fact]
public async Task The_dataItemId_and_value_are_percent_encoded()
{
var handler = new RecordingHandler(_ => Ok());
using var client = new MTConnectAgentClient(Options(), handler);
await client.WriteObservationAsync(
"Stub Device", "dev1 msg&x", "Coolant low = 20% & rising", CancellationToken.None);
handler.Requests.ShouldHaveSingleItem().Uri.AbsoluteUri.ShouldBe(
"http://stub-agent:5000/Stub%20Device?dev1%20msg%26x=Coolant%20low%20%3D%2020%25%20%26%20rising");
}
/// <summary>
/// The base URI's own path is preserved (an Agent behind a reverse-proxy prefix) and a
/// trailing slash does not double up — the same left-part rule the read paths use.
/// </summary>
[Fact]
public async Task A_based_agent_uri_keeps_its_path_prefix_and_does_not_double_its_slash()
{
var handler = new RecordingHandler(_ => Ok());
using var client = new MTConnectAgentClient(Options("http://stub-agent:5000/mtconnect/"), handler);
await client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", CancellationToken.None);
handler.Requests.ShouldHaveSingleItem().Uri.AbsoluteUri
.ShouldBe("http://stub-agent:5000/mtconnect/StubDevice?dev1_msg=hi");
}
/// <summary>
/// The <c>deviceName</c> argument decides the path — <b>not</b> the options' device scope. A
/// multi-device Agent is addressed per write, so an implementation that reused the read
/// paths' scoped URI would write every DataItem onto one device.
/// </summary>
[Fact]
public async Task The_device_segment_comes_from_the_argument_not_the_configured_device_scope()
{
var handler = new RecordingHandler(_ => Ok());
using var client = new MTConnectAgentClient(
new MTConnectDriverOptions { AgentUri = "http://stub-agent:5000", DeviceName = "ScopedDevice" },
handler);
await client.WriteObservationAsync("OtherDevice", "dev2_msg", "hi", CancellationToken.None);
handler.Requests.ShouldHaveSingleItem().Uri.AbsoluteUri
.ShouldBe("http://stub-agent:5000/OtherDevice?dev2_msg=hi");
}
// ── acceptance ───────────────────────────────────────────────────────────
/// <summary>
/// An empty 2xx body is what a real cppagent sends on success. Treating a body-less answer
/// as anything but acceptance would refuse every write that actually worked.
/// </summary>
[Fact]
public async Task An_empty_200_is_accepted()
{
using var client = new MTConnectAgentClient(Options(), new StubHandler((_, _) => Task.FromResult(Ok())));
var outcome = await client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", CancellationToken.None);
outcome.Accepted.ShouldBeTrue();
outcome.AgentError.ShouldBeNull();
}
/// <summary>A 200 carrying a non-MTConnect body is still acceptance — only an error document refuses.</summary>
[Fact]
public async Task A_200_whose_body_is_not_an_error_document_is_accepted()
{
using var client = new MTConnectAgentClient(
Options(), new StubHandler((_, _) => Task.FromResult(Ok("<html><body>OK</body></html>"))));
var outcome = await client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", CancellationToken.None);
outcome.Accepted.ShouldBeTrue();
outcome.AgentError.ShouldBeNull();
}
// ── refusal ──────────────────────────────────────────────────────────────
/// <summary>
/// The load-bearing refusal: HTTP 200 with an <c>MTConnectError</c> body.
/// <c>EnsureSuccessStatusCode</c> never fires here, so an implementation that trusted the
/// status code would report every rejected write as a success.
/// </summary>
[Fact]
public async Task An_MTConnectError_under_200_is_a_refusal_carrying_the_agents_own_text()
{
using var client = new MTConnectAgentClient(
Options(), new StubHandler((_, _) => Task.FromResult(XmlOk(MTConnectErrorXml))));
var outcome = await client.WriteObservationAsync(
"StubDevice", "nosuchitem", "hi", CancellationToken.None);
outcome.Accepted.ShouldBeFalse();
outcome.AgentError.ShouldNotBeNull();
outcome.AgentError.ShouldContain("UNSUPPORTED");
outcome.AgentError.ShouldContain("Cannot find device data item: nosuchitem");
}
[Fact]
public async Task A_non_success_status_is_a_refusal_naming_the_status()
{
using var client = new MTConnectAgentClient(
Options(),
new StubHandler((_, _) => Task.FromResult(new HttpResponseMessage(HttpStatusCode.NotFound)
{
Content = new StringContent(string.Empty),
})));
var outcome = await client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", CancellationToken.None);
outcome.Accepted.ShouldBeFalse();
outcome.AgentError.ShouldNotBeNull();
outcome.AgentError.ShouldContain("404");
}
// ── transport failure throws, never a false outcome ──────────────────────
/// <summary>
/// "Unreachable" must stay distinguishable from "rejected". Returning
/// <c>Accepted = false</c> here would collapse a comms fault into a per-tag refusal, which
/// the driver maps to a different status code and an operator resolves differently.
/// </summary>
[Fact]
public async Task A_transport_failure_propagates_rather_than_becoming_a_refusal()
{
var boom = new HttpRequestException("dial failed");
using var client = new MTConnectAgentClient(
Options(), new StubHandler((_, _) => Task.FromException<HttpResponseMessage>(boom)));
var thrown = await Should.ThrowAsync<HttpRequestException>(
() => client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", CancellationToken.None));
thrown.ShouldBeSameAs(boom);
}
/// <summary>
/// A frozen Agent must surface as a bounded <see cref="TimeoutException"/> naming the URI,
/// not park the caller — the same per-call deadline discipline the read legs carry
/// (arch-review R2-01).
/// </summary>
[Fact(Timeout = 10000)]
public async Task A_frozen_agent_times_out_within_the_per_call_deadline()
{
using var client = new MTConnectAgentClient(
new MTConnectDriverOptions { AgentUri = "http://stub-agent:5000", RequestTimeoutMs = 300 },
new StubHandler(async (_, ct) =>
{
await Task.Delay(Timeout.Infinite, ct);
throw new UnreachableException();
}));
await Should.ThrowAsync<TimeoutException>(
() => client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", CancellationToken.None));
}
/// <summary>Local stand-in so the stub handler's "never returns" branch has a throw statement to satisfy flow analysis.</summary>
private sealed class UnreachableException : Exception;
/// <summary>Cancelling is cancellation, never a refusal — the caller's own token wins over the deadline.</summary>
[Fact]
public async Task A_cancelled_token_surfaces_as_cancellation_not_as_a_refusal()
{
using var cts = new CancellationTokenSource();
using var client = new MTConnectAgentClient(
Options(),
new StubHandler(async (_, ct) =>
{
await Task.Delay(Timeout.Infinite, ct);
throw new UnreachableException();
}));
var write = client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", cts.Token);
await cts.CancelAsync();
await Should.ThrowAsync<OperationCanceledException>(() => write);
}
// ── disposal ─────────────────────────────────────────────────────────────
[Fact]
public async Task Writing_through_a_disposed_client_throws_ObjectDisposedException()
{
var client = new MTConnectAgentClient(Options(), new StubHandler((_, _) => Task.FromResult(Ok())));
client.Dispose();
await Should.ThrowAsync<ObjectDisposedException>(
() => client.WriteObservationAsync("StubDevice", "dev1_msg", "hi", CancellationToken.None));
}
}