d6392dae17
- 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.
381 lines
20 KiB
C#
381 lines
20 KiB
C#
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><Error></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><Error></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><Error></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><MTConnectError/></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);
|
||
}
|
||
}
|