Files
lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectXml.cs
T
Joseph Doherty d6392dae17 fix(mtconnect): close Java-driver parity gaps found by the #804 review
- Lift an Agent's MTConnectError body under a non-2xx status (cppagent 2.x serves
  OUT_OF_RANGE as HTTP 400, NO_DEVICE as 404) into the refusal-marked
  InvalidDataException, reading at most 64 KiB. The 400 used to be a transport
  fault, so the OUT_OF_RANGE re-baseline never ran against a real 2.x Agent.
- Run the instanceId restart test on every re-baseline snapshot: on 2.x a restart
  is first seen there (the old cursor gets a 400), and was adopted silently.
- Report the stream Degraded after 3 consecutive re-baselines with no /sample
  chunk (it read Healthy for ever); LastSuccessfulRead keeps advancing.
- Prohibit DTDs on the /probe and write-answer parses; bound the streams walk to
  64 levels (unbounded recursion = uncatchable StackOverflowException).
- Skip structural elements under <Components>/<Devices> instead of failing the probe.
- Never serve a non-finite float as Good; serve integer-valued decimals on
  integral tags losslessly (a real fraction stays BadOutOfRange).
- Merge sibling browse containers that resolve to one folder name.

Unit 678 -> 714, integration 18 -> 20 (live fixture); every gap test failed first.
2026-11-10 23:08:42 -05:00

381 lines
20 KiB
C#
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
using System.Globalization;
using System.Xml;
using System.Xml.Linq;
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
/// <summary>
/// The element/attribute reading rules shared by <see cref="MTConnectProbeParser"/> and
/// <see cref="MTConnectStreamsParser"/>. Both documents are the same dialect of XML and must be
/// read by the same rules; keeping one copy is what stops the two parsers drifting apart on the
/// two rules below, either of which fails silently rather than loudly.
/// </summary>
/// <remarks>
/// <para>
/// <b>Rule 1: elements are matched on <see cref="XName.LocalName"/>, ignoring the
/// namespace.</b> The namespace URI carries the MTConnect version
/// (<c>urn:mtconnect.org:MTConnectDevices:1.3</c> … <c>:2.0</c>), so a fully-qualified match
/// would hard-code a version. It also silently drops vendor-extension elements declared in
/// their own namespace, whose standard children still inherit the default MTConnect
/// namespace — the browse tree simply comes back short, with no error anywhere.
/// </para>
/// <para>
/// <b>Rule 2: attributes are read <i>unqualified</i>.</b> A prefixed attribute
/// (<c>xsi:type</c> on a document root, a vendor's <c>x:dataItemId</c>) must never be
/// mistaken for the real <c>type</c> / <c>dataItemId</c>, which would invent a data item the
/// probe never declared.
/// </para>
/// </remarks>
internal static class MTConnectXml
{
/// <summary>
/// The reader settings every <b>tree-building</b> parse of an Agent document uses (the
/// <c>/probe</c> model, an error body, a write answer). The Agent is an unauthenticated peer on
/// the plant network, so a DOCTYPE is refused outright and nothing external is ever resolved —
/// no legitimate MTConnect document carries one. <see cref="XDocument.Parse(string)"/> on its own
/// <i>parses</i> DTDs (it expands internal entities up to ten million characters); the streams
/// parser already prohibited them, and this is what brings the other parses into line (#804).
/// <see cref="XmlReaderSettings.IgnoreWhitespace"/> reproduces <c>XDocument.Parse</c>'s default.
/// </summary>
private static readonly XmlReaderSettings HardenedTreeSettings = new()
{
DtdProcessing = DtdProcessing.Prohibit,
XmlResolver = null,
IgnoreWhitespace = true,
CloseInput = false,
};
/// <summary>Parses <paramref name="xml"/> into a tree with DTDs prohibited (see <see cref="HardenedTreeSettings"/>).</summary>
/// <param name="xml">The document text.</param>
/// <returns>The parsed document.</returns>
/// <exception cref="XmlException">The text is not well-formed, or carries a DOCTYPE.</exception>
public static XDocument ParseHardened(string xml)
{
using var text = new StringReader(xml);
using var reader = XmlReader.Create(text, HardenedTreeSettings);
return XDocument.Load(reader);
}
/// <summary>Loads <paramref name="stream"/> into a tree with DTDs prohibited (see <see cref="HardenedTreeSettings"/>).</summary>
/// <param name="stream">The document bytes; not closed.</param>
/// <returns>The parsed document.</returns>
/// <exception cref="XmlException">The bytes are not well-formed, or carry a DOCTYPE.</exception>
public static XDocument LoadHardened(Stream stream)
{
using var reader = XmlReader.Create(stream, HardenedTreeSettings);
return XDocument.Load(reader);
}
/// <summary>
/// The Agent's <c>MTConnectError</c> document in <paramref name="body"/>, rendered as the
/// refusal-marked <see cref="InvalidDataException"/> every caller already routes (see
/// <see cref="IsAgentRefusal"/>), or <see langword="null"/> when the body is not one.
/// </summary>
/// <remarks>
/// <b>Why this exists (#804).</b> A modern Agent (cppagent 2.x, the fixture's
/// <c>mtconnect/agent:2.7</c>) does not serve its error documents under HTTP 200 the way older
/// ones did: it answers an out-of-range <c>/sample?from=</c> — and a <c>count</c> at or above its
/// buffer — with <b>HTTP 400</b>, and an unknown device with <b>404</b>, each carrying a
/// well-formed <c>MTConnectError</c> body. A status check alone turns those into an
/// <see cref="HttpRequestException"/>, which the pump treats as a transient transport loss and
/// reconnects at the SAME evicted cursor, so the <c>OUT_OF_RANGE</c> re-baseline never ran
/// against a real 2.x Agent. Lifting the document is what routes it.
/// </remarks>
/// <param name="body">The (already size-bounded) response body.</param>
/// <param name="status">The HTTP status the body arrived under, for the message.</param>
/// <param name="expectedRootName">The root the request expected.</param>
/// <param name="subject">How to describe the document.</param>
/// <returns>The refusal to throw, or <see langword="null"/>.</returns>
public static InvalidDataException? AgentRefusalFromErrorBody(
string? body, int status, string expectedRootName, string subject)
{
if (string.IsNullOrWhiteSpace(body))
{
return null;
}
XElement? root;
try
{
root = ParseHardened(body.Trim('', ' ', '\t', '\r', '\n')).Root;
}
catch (XmlException)
{
return null;
}
if (root is null || !IsNamed(root, "MTConnectError"))
{
return null;
}
var ex = new InvalidDataException(
$"{DescribeUnexpectedRoot(root, expectedRootName, subject)} (served under HTTP {status})");
ex.Data[AgentRefusalDataKey] = true;
return ex;
}
/// <summary>Does <paramref name="element"/> have the given local name, whatever its namespace?</summary>
/// <param name="element">The element to test.</param>
/// <param name="localName">The unqualified name to match.</param>
/// <returns><see langword="true"/> if the element has the given local name.</returns>
public static bool IsNamed(XElement element, string localName) =>
string.Equals(element.Name.LocalName, localName, StringComparison.Ordinal);
/// <summary>
/// Does the element the reader is positioned on have the given local name, whatever its
/// namespace?
/// </summary>
/// <remarks>
/// <see cref="MTConnectStreamsParser"/> reads its documents through a forward-only
/// <see cref="XmlReader"/> rather than a materialised tree — one sample chunk is read once
/// and thrown away, so building an <see cref="XDocument"/> for it is pure waste. The reader
/// overloads here exist so that going forward-only did not fork the two silent rules in the
/// type-level remarks: both flavours match on the local name, read attributes unqualified,
/// and produce the same error text.
/// </remarks>
/// <param name="reader">A reader positioned on an element.</param>
/// <param name="localName">The unqualified name to match.</param>
/// <returns><see langword="true"/> if the current element has the given local name.</returns>
public static bool IsNamed(XmlReader reader, string localName) =>
string.Equals(reader.LocalName, localName, StringComparison.Ordinal);
/// <summary>Direct element children of <paramref name="parent"/> with the given local name.</summary>
/// <param name="parent">The element whose children to filter.</param>
/// <param name="localName">The unqualified name to match.</param>
/// <returns>The matching child elements.</returns>
public static IEnumerable<XElement> ChildrenNamed(XElement parent, string localName) =>
parent.Elements().Where(child => IsNamed(child, localName));
/// <summary>
/// Reads an unqualified attribute, normalizing a present-but-empty value to <c>null</c>.
/// See the type-level remarks for why only unqualified attributes are considered.
/// </summary>
/// <param name="element">The element carrying the attribute.</param>
/// <param name="name">The unqualified attribute name.</param>
/// <returns>The attribute value, or <see langword="null"/> when absent or blank.</returns>
public static string? OptionalAttribute(XElement element, string name)
{
var value = element.Attribute(name)?.Value;
return string.IsNullOrWhiteSpace(value) ? null : value;
}
/// <summary>
/// Reads an unqualified attribute off the element the reader is positioned on, normalizing a
/// present-but-empty value to <c>null</c>. See <see cref="IsNamed(XmlReader, string)"/> for
/// why the reader overloads exist.
/// </summary>
/// <remarks>
/// <see cref="XmlReader.GetAttribute(string)"/> matches on the attribute's <i>qualified</i>
/// name, so a prefixed <c>x:dataItemId</c> does not answer to <c>dataItemId</c> — exactly
/// what rule 2 in the type-level remarks requires, and what <see cref="XElement.Attribute"/>
/// does for a namespace-free <see cref="XName"/>.
/// </remarks>
/// <param name="reader">A reader positioned on an element.</param>
/// <param name="name">The unqualified attribute name.</param>
/// <returns>The attribute value, or <see langword="null"/> when absent or blank.</returns>
public static string? OptionalAttribute(XmlReader reader, string name)
{
var value = reader.GetAttribute(name);
return string.IsNullOrWhiteSpace(value) ? null : value;
}
/// <summary>Reads a required unqualified attribute, or throws naming the owner and the attribute.</summary>
/// <param name="element">The element carrying the attribute.</param>
/// <param name="name">The unqualified attribute name.</param>
/// <param name="owner">How to describe the element in the error message.</param>
/// <param name="subject">How to describe the document in the error message (e.g. "/probe response").</param>
/// <returns>The attribute value.</returns>
/// <exception cref="InvalidDataException">The attribute is absent or blank.</exception>
public static string RequiredAttribute(XElement element, string name, string owner, string subject) =>
OptionalAttribute(element, name) ?? throw MissingAttribute(name, owner, subject);
/// <summary>
/// Reads a required unqualified attribute off the element the reader is positioned on, or
/// throws naming the owner and the attribute.
/// </summary>
/// <param name="reader">A reader positioned on an element.</param>
/// <param name="name">The unqualified attribute name.</param>
/// <param name="owner">How to describe the element in the error message.</param>
/// <param name="subject">How to describe the document in the error message.</param>
/// <returns>The attribute value.</returns>
/// <exception cref="InvalidDataException">The attribute is absent or blank.</exception>
public static string RequiredAttribute(XmlReader reader, string name, string owner, string subject) =>
OptionalAttribute(reader, name) ?? throw MissingAttribute(name, owner, subject);
/// <summary>Reads an optional unqualified attribute as an <see cref="int"/>.</summary>
/// <param name="element">The element carrying the attribute.</param>
/// <param name="name">The unqualified attribute name.</param>
/// <param name="owner">How to describe the element in the error message.</param>
/// <param name="subject">How to describe the document in the error message.</param>
/// <returns>The parsed integer, or <see langword="null"/> when the attribute is absent or blank.</returns>
/// <exception cref="InvalidDataException">The attribute is present but not an integer.</exception>
public static int? OptionalIntAttribute(XElement element, string name, string owner, string subject)
{
var raw = OptionalAttribute(element, name);
if (raw is null)
{
return null;
}
if (!int.TryParse(raw, NumberStyles.Integer, CultureInfo.InvariantCulture, out var value))
{
throw new InvalidDataException(
$"MTConnect {subject} is malformed: {owner} has a non-numeric '{name}' attribute ('{raw}').");
}
return value;
}
/// <summary>Reads a required unqualified attribute as a <see cref="long"/>.</summary>
/// <param name="element">The element carrying the attribute.</param>
/// <param name="name">The unqualified attribute name.</param>
/// <param name="owner">How to describe the element in the error message.</param>
/// <param name="subject">How to describe the document in the error message.</param>
/// <returns>The parsed long value.</returns>
/// <exception cref="InvalidDataException">The attribute is absent, blank, or not an integer.</exception>
public static long RequiredLongAttribute(XElement element, string name, string owner, string subject) =>
AsLong(RequiredAttribute(element, name, owner, subject), name, owner, subject);
/// <summary>
/// Reads a required unqualified attribute off the element the reader is positioned on, as a
/// <see cref="long"/>.
/// </summary>
/// <param name="reader">A reader positioned on an element.</param>
/// <param name="name">The unqualified attribute name.</param>
/// <param name="owner">How to describe the element in the error message.</param>
/// <param name="subject">How to describe the document in the error message.</param>
/// <returns>The parsed long value.</returns>
/// <exception cref="InvalidDataException">The attribute is absent, blank, or not an integer.</exception>
public static long RequiredLongAttribute(XmlReader reader, string name, string owner, string subject) =>
AsLong(RequiredAttribute(reader, name, owner, subject), name, owner, subject);
/// <summary>The one spelling of "that attribute is missing", shared by both flavours.</summary>
private static InvalidDataException MissingAttribute(string name, string owner, string subject) =>
new($"MTConnect {subject} is malformed: {owner} has no '{name}' attribute.");
/// <summary>The one spelling of "that attribute is not a number", shared by both flavours.</summary>
private static long AsLong(string raw, string name, string owner, string subject)
{
if (!long.TryParse(raw, NumberStyles.Integer, CultureInfo.InvariantCulture, out var value))
{
throw new InvalidDataException(
$"MTConnect {subject} is malformed: {owner} has a non-numeric '{name}' attribute ('{raw}').");
}
return value;
}
/// <summary>
/// Builds the error message for a document whose root is not what was expected, lifting the
/// Agent's own error text when the response is an <c>MTConnectError</c> document — which
/// Agents return under <b>HTTP 200</b>, so <c>EnsureSuccessStatusCode</c> never fires and
/// this is the only place the operator can learn what the Agent objected to.
/// </summary>
/// <param name="root">The document's actual root element.</param>
/// <param name="expectedRootName">The root element name the caller required.</param>
/// <param name="subject">How to describe the document in the error message.</param>
/// <returns>
/// The exception to throw. For an <c>MTConnectError</c> root (the Agent REFUSED the request) it is marked
/// with <see cref="AgentRefusalDataKey"/> — see <see cref="IsAgentRefusal"/>.
/// </returns>
public static InvalidDataException UnexpectedRoot(XElement root, string expectedRootName, string subject)
{
var ex = new InvalidDataException(DescribeUnexpectedRoot(root, expectedRootName, subject));
// Marked (InvalidDataException is sealed, so not a subtype) so the read path can tell a refusal — the
// Agent answered — from an answer it could not parse at all. Every other handler sees the same exception.
if (IsNamed(root, "MTConnectError"))
{
ex.Data[AgentRefusalDataKey] = true;
}
return ex;
}
/// <summary><see cref="Exception.Data"/> key marking an <c>MTConnectError</c> answer (see <see cref="IsAgentRefusal"/>).</summary>
internal const string AgentRefusalDataKey = "MTConnect.AgentRefusal";
/// <summary>
/// Whether <paramref name="ex"/> is the Agent answering with an <c>MTConnectError</c> document (e.g.
/// <c>NO_DEVICE</c>, <c>INVALID_REQUEST</c>) — a refusal, as opposed to an answer that could not be parsed.
/// </summary>
/// <param name="ex">The exception a parse raised.</param>
/// <returns><see langword="true"/> for a refusal.</returns>
public static bool IsAgentRefusal(Exception ex) =>
ex is InvalidDataException && ex.Data[AgentRefusalDataKey] is true;
/// <summary>
/// The text of <see cref="UnexpectedRoot"/>: the unexpected root, plus the Agent's own error text for an
/// <c>MTConnectError</c> document.
/// </summary>
/// <param name="root">The document's root element.</param>
/// <param name="expectedRootName">The root the caller expected.</param>
/// <param name="subject">How to describe the document.</param>
/// <returns>The message.</returns>
public static string DescribeUnexpectedRoot(XElement root, string expectedRootName, string subject)
{
var message =
$"MTConnect {subject} root element is <{root.Name.LocalName}>, expected <{expectedRootName}>.";
if (!IsNamed(root, "MTConnectError"))
{
return message;
}
var errors = ExtractErrorText(root);
return errors is null ? message : $"{message} The Agent reported: {errors}";
}
/// <summary>
/// The Agent's own words from an <c>MTConnectError</c> document: every <c>&lt;Error&gt;</c>
/// beneath <paramref name="root"/>, rendered <c>errorCode: text</c> where a code is present
/// and joined with <c>"; "</c>. <c>null</c> when the document carries no readable error
/// detail at all (no <c>&lt;Error&gt;</c> elements, or only blank ones).
/// </summary>
/// <remarks>
/// <para>
/// <b>Shared because both callers must read the same document the same way.</b> An
/// Agent's objection reaches this driver through two unrelated doors — a read path that
/// got an error document where it expected a model
/// (<see cref="DescribeUnexpectedRoot"/>), and the write path deciding whether a 200
/// actually accepted the observation. Two copies of this walk would drift on the same
/// two silent rules the type-level remarks describe, and on the write side a missed
/// <c>&lt;Error&gt;</c> does not merely degrade a message: it reads as a successful
/// write.
/// </para>
/// <para>
/// <b><c>null</c> means "no readable detail", NOT "not an error document".</b> Only the
/// caller knows which document it is holding — check the root name first. A caller that
/// treats a <c>null</c> here as "no error occurred" turns a hollow
/// <c>&lt;MTConnectError/&gt;</c> into a success.
/// </para>
/// </remarks>
/// <param name="root">The <c>MTConnectError</c> document's root element.</param>
/// <returns>The Agent's error text, or <see langword="null"/> when no readable detail is present.</returns>
public static string? ExtractErrorText(XElement root)
{
ArgumentNullException.ThrowIfNull(root);
var errors = root.Descendants()
.Where(e => IsNamed(e, "Error"))
.Select(e =>
{
var code = OptionalAttribute(e, "errorCode");
var text = e.Value.Trim();
return code is null ? text : $"{code}: {text}";
})
.Where(text => text.Length > 0)
.ToList();
return errors.Count == 0 ? null : string.Join("; ", errors);
}
}