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

feat(mqtt): Sparkplug ingest state machine (birth/alias/seq/rebirth/death→stale)

Browse Source 
Task 21 — the design doc's §3.6 correctness core. `SparkplugIngestor` owns the
authored `(group, node, device?, metric) → RawPath` index, the live `BirthCache`,
one `SequenceTracker` per authored edge node, and the rebirth policy; it routes
NBIRTH/DBIRTH/NDATA/DDATA/NDEATH/DDEATH/STATE into `OnDataChange` +
`LastValueCache`, or into a bounded, per-node-debounced rebirth NCMD.

Invariants held (and each pinned by a falsifiability control):
- Published reference is the RawPath, never a composed Sparkplug reference —
  `DriverHostActor`'s dual-namespace fan-out is RawPath-keyed.
- Tags bind by stable metric NAME; the alias is only the per-birth lookup, so an
  alias reused across a rebirth cannot mis-route.
- Every value goes through `SparkplugMetricBinding.Reinterpret` before publish.
- NDEATH never reaches `SequenceTracker.Accept` (it carries no seq); it is tied to
  its birth by bdSeq instead.
- An invalid payload mutates nothing — no tracker, no alias table, no eviction.
- `HandleMessage` never throws on MQTTnet's dispatcher thread.

Supporting changes:
- `MqttTagDefinitionFactory.FromSparkplugTagConfig` — the driver had no way to
  parse the Sparkplug descriptor keys at all; the P1 stub fields on
  `MqttTagDefinition` were never populated. Mode selects the parser, never a
  blob heuristic. `dataType` becomes optional in the Sparkplug shape (the birth
  declares it), recorded via the new `DataTypeAuthored` flag.
- `MqttConnection` implements `IMqttPublishTransport` (bounded, refusal throws).
- `MqttDriver` dispatches every capability by mode, subscribes `spBv1.0/{group}/#`
  (+ the configured STATE topic) once at connect, and re-subscribes + requests a
  late-join rebirth on reconnect. `IngestIdentity` now names `MqttSparkplugOptions`,
  closing the silent same-ingest gap its own ⚠️ comment warned about.

Primary-host STATE *publishing* is explicitly out of scope and warned about at
construction: it needs the retained-OFFLINE Last Will set at CONNECT time, and
shipping the ONLINE half alone is worse than shipping neither.

58 new tests (MQTT suite 455 → 513, all green).

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
This commit is contained in:
Joseph Doherty
2026-07-24 22:11:41 -04:00
parent 31a98a1bf5
commit 8538fb798b
6 changed files with 3456 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts/MqttTagDefinition.cs
+29 -12
View File
@@ -9,12 +9,20 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
/// See <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.2 / §5.3.
/// <para>
/// The record carries <b>both</b> ingest shapes: the Plain-MQTT fields
/// (<see cref="Topic"/> … <see cref="RetainSeed"/>), populated in P1, and the Sparkplug B
/// descriptor fields (<see cref="GroupId"/>, <see cref="EdgeNodeId"/>,
/// <see cref="DeviceId"/>, <see cref="MetricName"/>), which are deliberate <b>stubs</b> in P1
/// — always <see langword="null"/> until the P2 tasks (15–26) teach the parser to read them.
/// A Sparkplug tag is resolved by the stable <c>(group, node, device, metricName)</c> tuple,
/// never by the per-birth metric alias.
/// (<see cref="Topic"/> … <see cref="RetainSeed"/>), populated by
/// <see cref="MqttTagDefinitionFactory.FromTagConfig"/>, and the Sparkplug B descriptor fields
/// (<see cref="GroupId"/>, <see cref="EdgeNodeId"/>, <see cref="DeviceId"/>,
/// <see cref="MetricName"/>), populated by
/// <see cref="MqttTagDefinitionFactory.FromSparkplugTagConfig"/> (Task 21). A Sparkplug tag is
/// resolved by the stable <c>(group, node, device, metricName)</c> tuple, <b>never</b> by the
/// per-birth metric alias — an alias may be reused across a rebirth for a different metric.
/// </para>
/// <para>
/// <b>Which factory runs is chosen by the driver's <see cref="MqttMode"/>, never sniffed from
/// the blob.</b> A blob carrying both shapes' keys is legal (the AdminUI editor preserves
/// unknown keys through a load→save, so a tag retyped from Plain to Sparkplug keeps its old
/// <c>topic</c>), and a heuristic would make the same authored tag mean two different things
/// depending on which key happened to survive.
/// </para>
/// </summary>
/// <param name="Name">
@@ -44,15 +52,23 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
/// Whether the broker's retained message for <see cref="Topic"/> seeds this tag's initial value
/// on subscribe (the OPC UA initial-data convention). Defaults to <see langword="true"/>.
/// </param>
/// <param name="GroupId">P2 stub — the Sparkplug group id. Always <see langword="null"/> in P1.</param>
/// <param name="EdgeNodeId">P2 stub — the Sparkplug edge-node id. Always <see langword="null"/> in P1.</param>
/// <param name="DataTypeAuthored">
/// Whether <paramref name="DataType"/> came from an authored <c>dataType</c> key or is merely this
/// record's default. Load-bearing in <b>Sparkplug</b> mode only, where <c>dataType</c> is optional:
/// a Sparkplug metric's type is declared by its own birth certificate, so an unauthored tag must
/// take the type the NBIRTH/DBIRTH declared rather than silently coercing every value to the
/// <see cref="DriverDataType.String"/> default. Both factories set it from the key's presence so it
/// means the same thing in either mode; nothing on the Plain ingest path reads it.
/// </param>
/// <param name="GroupId">The Sparkplug group id; <see langword="null"/> for a Plain-mode tag.</param>
/// <param name="EdgeNodeId">The Sparkplug edge-node id; <see langword="null"/> for a Plain-mode tag.</param>
/// <param name="DeviceId">
/// P2 stub — the Sparkplug device id (absent for node-level metrics). Always
/// <see langword="null"/> in P1.
/// The Sparkplug device id, or <see langword="null"/> for a metric published by the edge node
/// itself (and for every Plain-mode tag).
/// </param>
/// <param name="MetricName">
/// P2 stub — the Sparkplug metric name, the tag's stable identity across rebirths. Always
/// <see langword="null"/> in P1.
/// The Sparkplug metric name — the tag's stable identity across rebirths, and the key the ingest
/// state machine binds by. <see langword="null"/> for a Plain-mode tag.
/// </param>
public sealed record MqttTagDefinition(
string Name,
@@ -62,6 +78,7 @@ public sealed record MqttTagDefinition(
DriverDataType DataType,
int? Qos,
bool RetainSeed,
bool DataTypeAuthored = true,
string? GroupId = null,
string? EdgeNodeId = null,
string? DeviceId = null,
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts/MqttTagDefinitionFactory.cs
+96 -4
View File
@@ -20,9 +20,13 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
/// deploy instead of silently going dark at runtime.
/// </para>
/// <para>
/// Sparkplug-descriptor parsing (<c>groupId</c> / <c>edgeNodeId</c> / <c>deviceId</c> /
/// <c>metricName</c>) is a deliberate P1 stub — the fields exist on
/// <see cref="MqttTagDefinition"/> but are never populated here until the P2 tasks fill them.
/// <b>Two runtime entry points, one per ingest shape</b> — <see cref="FromTagConfig"/> (Plain)
/// and <see cref="FromSparkplugTagConfig"/> (Sparkplug B). The caller picks by the driver's
/// <see cref="MqttMode"/>; neither sniffs the blob. That is deliberate: the AdminUI editor
/// preserves unknown keys through a load→save, so a tag retyped from Plain to Sparkplug keeps
/// its old <c>topic</c> and a presence heuristic would make one authored blob mean two
/// different things depending on which key happened to survive. The <i>driver's</i> mode is
/// the single authority.
/// </para>
/// <para>
/// <b>No <c>ToTagConfig</c> inverse — a deliberate YAGNI call.</b> The six sibling factories
@@ -80,6 +84,7 @@ public static class MqttTagDefinitionFactory
// (→ BadNodeIdUnknown) instead of silently defaulting to a wrong-typed Good.
if (!TagConfigJson.TryReadEnumStrict(root, "payloadFormat", MqttPayloadFormat.Json, out var payloadFormat))
return false;
var dataTypeAuthored = root.TryGetProperty("dataType", out _);
if (!TagConfigJson.TryReadEnumStrict(root, "dataType", DriverDataType.String, out var dataType))
return false;
@@ -98,7 +103,94 @@ public static class MqttTagDefinitionFactory
JsonPath: jsonPath,
DataType: dataType,
Qos: qos,
RetainSeed: ReadBoolOrDefault(root, "retainSeed", defaultValue: true));
RetainSeed: ReadBoolOrDefault(root, "retainSeed", defaultValue: true),
DataTypeAuthored: dataTypeAuthored);
return true;
}
catch (JsonException) { return false; }
catch (FormatException) { return false; }
catch (InvalidOperationException) { return false; }
}
/// <summary>
/// Maps an authored <c>TagConfig</c> object to a <b>Sparkplug B</b> definition keyed by
/// <paramref name="rawPath"/>. The tag's binding identity is the stable
/// <c>(groupId, edgeNodeId, deviceId?, metricName)</c> tuple; <c>deviceId</c> is optional (absent
/// means the metric is published by the edge node itself), and there is <b>no</b> <c>topic</c> —
/// a Sparkplug driver subscribes one group-wide filter and routes by the decoded topic + birth
/// certificate, never by a per-tag topic. Never throws.
/// </summary>
/// <remarks>
/// <para>
/// <b><c>dataType</c> is OPTIONAL here, unlike in Plain mode.</b> A Sparkplug metric declares
/// its own datatype in its birth certificate, so an unauthored tag legitimately takes the
/// type the birth declares — that is the whole point of Task 22's <c>UntilStable</c>
/// discovery. It is still read <b>strictly</b> when present (a typo'd value rejects the tag,
/// exactly as in Plain mode) and the outcome is recorded on
/// <see cref="MqttTagDefinition.DataTypeAuthored"/> so the ingest path can tell "the operator
/// declared String" from "nobody declared anything and the record defaulted".
/// </para>
/// <para>
/// <b>Plain-shape keys are read but not required.</b> <c>topic</c>/<c>payloadFormat</c>/
/// <c>jsonPath</c> are meaningless to the Sparkplug ingest path and are deliberately NOT
/// validated — a blob retyped in the editor keeps them, and rejecting the tag for a stale
/// leftover key would take a correctly-authored Sparkplug tag dark with no stated cause.
/// </para>
/// </remarks>
/// <param name="tagConfig">The authored equipment-tag TagConfig JSON.</param>
/// <param name="rawPath">The tag's RawPath — becomes the definition's identity (<c>Name</c>).</param>
/// <param name="def">The mapped definition when this returns <see langword="true"/>.</param>
/// <returns><see langword="true"/> when the blob carries a usable Sparkplug descriptor.</returns>
public static bool FromSparkplugTagConfig(string tagConfig, string rawPath, out MqttTagDefinition def)
{
def = null!;
if (string.IsNullOrWhiteSpace(tagConfig) || tagConfig[0] != '{') return false;
try
{
using var doc = JsonDocument.Parse(tagConfig);
var root = doc.RootElement;
if (root.ValueKind != JsonValueKind.Object) return false;
// The binding tuple. Without all three of these there is nothing a birth certificate could
// ever bind the tag to, so an absent/blank value is a hard reject (→ BadNodeIdUnknown)
// rather than a definition that can never resolve and reports nothing about why.
var groupId = ReadString(root, "groupId");
var edgeNodeId = ReadString(root, "edgeNodeId");
var metricName = ReadString(root, "metricName");
if (string.IsNullOrWhiteSpace(groupId)
|| string.IsNullOrWhiteSpace(edgeNodeId)
|| string.IsNullOrWhiteSpace(metricName))
{
return false;
}
// Optional: a node-level metric has no device segment. Blank normalises to absent so
// "deviceId":"" and an omitted key describe the same scope rather than two.
var deviceId = ReadString(root, "deviceId");
if (string.IsNullOrWhiteSpace(deviceId)) deviceId = null;
// Strict, but only when present — see the remarks.
var dataTypeAuthored = root.TryGetProperty("dataType", out _);
if (!TagConfigJson.TryReadEnumStrict(root, "dataType", DriverDataType.String, out var dataType))
return false;
if (!TryReadQosStrict(root, out var qos)) return false;
def = new MqttTagDefinition(
Name: rawPath,
// Plain-shape fields carried through verbatim; the Sparkplug ingest path reads none of
// them, and a retyped blob's leftovers must not change what the tag means.
Topic: ReadString(root, "topic"),
PayloadFormat: MqttPayloadFormat.Json,
JsonPath: RootJsonPath,
DataType: dataType,
Qos: qos,
RetainSeed: ReadBoolOrDefault(root, "retainSeed", defaultValue: true),
DataTypeAuthored: dataTypeAuthored,
GroupId: groupId,
EdgeNodeId: edgeNodeId,
DeviceId: deviceId,
MetricName: metricName);
return true;
}
catch (JsonException) { return false; }