feat(mqtt): write-through (IWritable) — Plain publish + Sparkplug NCMD/DCMD (#508)
MqttDriver implemented no IWritable, so every MQTT node materialized read-only
regardless of what the operator authored. It now publishes.
Plain -> the tag's writeTopic; UTF-8 text (Raw/Scalar) or a bare JSON
literal (Json)
Sparkplug -> DCMD for a device metric, NCMD for an edge-node metric, carrying
the metric BY NAME with an explicit Datatype and no seq
Both at QoS 0, retain:false. Retain is deliberately not configurable — a retained
command is replayed by the broker on every future subscribe, including the
device's own reconnect, so one stale write would be re-applied forever.
writeTopic is a new, separate TagConfig key, and its ABSENCE is meaningful: the
write is refused BadNotWritable and the node is discovered ViewOnly. The issue's
"do not skip" warning drove the design — the one outcome worse than read-only
nodes is a node that looks writable, returns Good and publishes nothing. Reusing
the read topic would be worse still: it would echo back and read as a confirmed
device value. Browse-time writability is computed by the SAME encoder the write
path uses, so a node cannot advertise writability it would then refuse.
Good means published, not applied — MQTT has no application-level write ack, so
this is Galaxy's optimistic-Good posture and inherits its property: a failed
DEVICE write can never be surfaced. A failed PUBLISH is reported Bad; the
optimism covers what the device did with the command, never whether it was sent.
WriteIdempotent stays default-off.
The encoder is pure and lives in .Contracts, so both wire shapes are testable
without a broker. Unrepresentable values and types with no Sparkplug encoding are
refused rather than coerced — a Reference must not silently become a String on
the wire, and "not-a-number" must not become 0 on a live plant.
LIVE GATE PASSED against the real Mosquitto fixture on 10.100.0.35: 21/21
integration tests, including 6 new ones that observe the published message with
an INDEPENDENT broker subscriber — a fake asserting "publish was called" could
not tell the feature working from the feature publishing to the wrong topic.
The gate earned its keep: the NCMD test initially failed because NCMD is a SHARED
channel — the driver publishes its own rebirth request (Node Control/Rebirth) on
the very topic an edge-node metric write uses, and it arrived first. Correct
driver behaviour, wrong test; the watcher now matches on metric name. Documented,
because anything consuming that topic needs to know. DCMD has no contention.
Offline: 24 encoder + 9 driver tests. The four new status constants are NAMED so
StatusCodeParityTests can see them (#497/#519) — it went 258 -> 262 and validated
each against the pinned SDK.
Also corrects the Mqtt.md "Known gaps" table: prunes the six rows closed in this
round, and fixes the #507 row, which still described rediscovery as inert after
that issue was closed as superseded and its injection path deleted.
Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,304 @@
|
||||
using System.Globalization;
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
using Google.Protobuf;
|
||||
using Org.Eclipse.Tahu.Protobuf;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
|
||||
using TahuDataType = Org.Eclipse.Tahu.Protobuf.DataType;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// Why a write could not be encoded. Maps 1:1 onto the status the driver returns, so the reason a
|
||||
/// write was refused is decided here — once, purely — rather than at the transport.
|
||||
/// </summary>
|
||||
public enum MqttWriteEncodeError
|
||||
{
|
||||
/// <summary>Encoding succeeded.</summary>
|
||||
None = 0,
|
||||
|
||||
/// <summary>
|
||||
/// The tag declares no write destination: a Plain tag with no <c>writeTopic</c>. Deliberately a
|
||||
/// hard refusal — see <see cref="MqttWriteEncoder"/>'s remarks on why a silent no-op would be
|
||||
/// worse than the honest read-only behaviour this replaced.
|
||||
/// </summary>
|
||||
NoWriteDestination,
|
||||
|
||||
/// <summary>The value is null, or cannot be represented in the tag's declared data type.</summary>
|
||||
ValueNotRepresentable,
|
||||
|
||||
/// <summary>The tag's declared data type has no Sparkplug command encoding.</summary>
|
||||
UnsupportedDataType,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Encodes an outbound MQTT write — the payload bytes and the topic to publish them on — for both
|
||||
/// ingest shapes (Gitea #508). Pure: no I/O, no transport, no clock beyond the Sparkplug command
|
||||
/// timestamp, so the whole encode contract is unit-testable without a broker.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>A missing write destination is a refusal, never a no-op.</b> Before #508 the driver
|
||||
/// implemented no <c>IWritable</c> at all, so every MQTT node materialised read-only — honest, if
|
||||
/// limited. The one outcome that would be strictly worse is a node that <em>looks</em> writable,
|
||||
/// accepts a write, returns Good and publishes nothing. So a Plain tag with no <c>writeTopic</c>
|
||||
/// yields <see cref="MqttWriteEncodeError.NoWriteDestination"/> and the driver surfaces
|
||||
/// <c>BadNotWritable</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The write topic is deliberately separate from the read topic.</b> A tag legitimately reads
|
||||
/// <c>.../state</c> and writes <c>.../set</c>, so the destination is its own authored field rather
|
||||
/// than being inferred from <see cref="MqttTagDefinition.Topic"/>. Publishing a command back onto
|
||||
/// the tag's own read topic would, on a broker with no device behind it, echo straight back and
|
||||
/// read as a confirmed device value.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Sparkplug writes are commands, not data.</b> A metric under a device encodes as a DCMD, one
|
||||
/// owned by the edge node itself as an NCMD, addressed by the tag's stable
|
||||
/// <c>(group, edgeNode, device?, metric)</c> tuple — never by the per-birth alias, which may be
|
||||
/// reused for a different metric across a rebirth. No <c>seq</c> is stamped, for the reason
|
||||
/// <see cref="RebirthRequester"/> documents at length: the sequence stream belongs to the messages
|
||||
/// an edge node itself publishes, and a strict node validating a host-supplied one against its own
|
||||
/// counter would have grounds to reject the command.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>jsonPath is not applied on write.</b> It is a read-side extraction from the read topic's
|
||||
/// document, and the write topic is a different topic whose payload shape nothing in the tag config
|
||||
/// describes. A <see cref="MqttPayloadFormat.Json"/> write therefore emits the value as a bare JSON
|
||||
/// literal. Reconstructing a wrapped document from an extraction path would be guesswork, and
|
||||
/// guessing a payload shape is how a write lands somewhere nobody authored.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class MqttWriteEncoder
|
||||
{
|
||||
/// <summary>QoS for an outbound write. See the remarks on <see cref="TryEncode"/>.</summary>
|
||||
public const int WriteQos = 0;
|
||||
|
||||
/// <summary>
|
||||
/// Encodes one write for the tag <paramref name="def"/> under the driver's <paramref name="mode"/>.
|
||||
/// </summary>
|
||||
/// <param name="mode">The driver's ingest shape — chosen by driver config, never sniffed from the tag.</param>
|
||||
/// <param name="def">The resolved tag definition.</param>
|
||||
/// <param name="value">The value to write.</param>
|
||||
/// <param name="encoded">The topic + payload to publish, when this returns <see cref="MqttWriteEncodeError.None"/>.</param>
|
||||
/// <returns>The encode outcome.</returns>
|
||||
/// <remarks>
|
||||
/// <b>QoS 0, retain <see langword="false"/>.</b> Retain is the one that matters: a retained
|
||||
/// command would be replayed by the broker to the device on every future subscribe — including
|
||||
/// the device's own reconnect — so a single stale write would be re-applied forever. This is the
|
||||
/// same hazard <see cref="RebirthRequester"/> avoids for NCMD, and the reason neither is
|
||||
/// configurable.
|
||||
/// </remarks>
|
||||
public static MqttWriteEncodeError TryEncode(
|
||||
MqttMode mode,
|
||||
MqttTagDefinition def,
|
||||
object? value,
|
||||
out MqttEncodedWrite encoded)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(def);
|
||||
encoded = default;
|
||||
|
||||
return mode == MqttMode.SparkplugB
|
||||
? TryEncodeSparkplug(def, value, out encoded)
|
||||
: TryEncodePlain(def, value, out encoded);
|
||||
}
|
||||
|
||||
/// <summary>Encodes a Plain-mode write: the value's text/JSON rendering onto the tag's write topic.</summary>
|
||||
/// <param name="def">The resolved tag definition.</param>
|
||||
/// <param name="value">The value to write.</param>
|
||||
/// <param name="encoded">The topic + payload on success.</param>
|
||||
/// <returns>The encode outcome.</returns>
|
||||
private static MqttWriteEncodeError TryEncodePlain(
|
||||
MqttTagDefinition def,
|
||||
object? value,
|
||||
out MqttEncodedWrite encoded)
|
||||
{
|
||||
encoded = default;
|
||||
|
||||
if (string.IsNullOrWhiteSpace(def.WriteTopic))
|
||||
{
|
||||
return MqttWriteEncodeError.NoWriteDestination;
|
||||
}
|
||||
|
||||
if (value is null)
|
||||
{
|
||||
// No MQTT payload means "the value is null" — a zero-length payload is a legitimate
|
||||
// clear-the-retained-message instruction, which is a different operation entirely.
|
||||
return MqttWriteEncodeError.ValueNotRepresentable;
|
||||
}
|
||||
|
||||
string text;
|
||||
if (def.PayloadFormat == MqttPayloadFormat.Json)
|
||||
{
|
||||
try
|
||||
{
|
||||
text = JsonSerializer.Serialize(value);
|
||||
}
|
||||
catch (NotSupportedException)
|
||||
{
|
||||
return MqttWriteEncodeError.ValueNotRepresentable;
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
// Raw and Scalar are both "the payload's UTF-8 text" on the read side; the write side
|
||||
// mirrors that. Invariant culture, or a comma decimal separator on a European host would
|
||||
// publish a number the device cannot parse.
|
||||
text = value is IFormattable f
|
||||
? f.ToString(null, CultureInfo.InvariantCulture)
|
||||
: value.ToString() ?? "";
|
||||
}
|
||||
|
||||
encoded = new MqttEncodedWrite(def.WriteTopic!.Trim(), Encoding.UTF8.GetBytes(text));
|
||||
return MqttWriteEncodeError.None;
|
||||
}
|
||||
|
||||
/// <summary>Encodes a Sparkplug-mode write as an NCMD (node metric) or DCMD (device metric).</summary>
|
||||
/// <param name="def">The resolved tag definition.</param>
|
||||
/// <param name="value">The value to write.</param>
|
||||
/// <param name="encoded">The topic + payload on success.</param>
|
||||
/// <returns>The encode outcome.</returns>
|
||||
private static MqttWriteEncodeError TryEncodeSparkplug(
|
||||
MqttTagDefinition def,
|
||||
object? value,
|
||||
out MqttEncodedWrite encoded)
|
||||
{
|
||||
encoded = default;
|
||||
|
||||
if (def.GroupId is not { Length: > 0 } groupId
|
||||
|| def.EdgeNodeId is not { Length: > 0 } edgeNodeId
|
||||
|| def.MetricName is not { Length: > 0 } metricName)
|
||||
{
|
||||
// A Sparkplug tag's command address IS its binding tuple, so an incomplete tuple is the
|
||||
// Sparkplug equivalent of a missing write topic rather than a different kind of failure.
|
||||
return MqttWriteEncodeError.NoWriteDestination;
|
||||
}
|
||||
|
||||
if (value is null)
|
||||
{
|
||||
return MqttWriteEncodeError.ValueNotRepresentable;
|
||||
}
|
||||
|
||||
var metric = new Payload.Types.Metric { Name = metricName };
|
||||
var error = ApplyValue(metric, def.DataType, value);
|
||||
if (error != MqttWriteEncodeError.None)
|
||||
{
|
||||
return error;
|
||||
}
|
||||
|
||||
var timestampMs = (ulong)DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
|
||||
metric.Timestamp = timestampMs;
|
||||
|
||||
var payload = new Payload { Timestamp = timestampMs };
|
||||
payload.Metrics.Add(metric);
|
||||
|
||||
// A device metric is commanded with DCMD addressed to that device; an edge-node metric with
|
||||
// NCMD. Sending a device metric as NCMD would address the node, which does not own it.
|
||||
var isDevice = def.DeviceId is { Length: > 0 };
|
||||
var topic = SparkplugTopic.Format(
|
||||
groupId,
|
||||
isDevice ? SparkplugMessageType.DCMD : SparkplugMessageType.NCMD,
|
||||
edgeNodeId,
|
||||
isDevice ? def.DeviceId : null);
|
||||
|
||||
encoded = new MqttEncodedWrite(topic, payload.ToByteArray());
|
||||
return MqttWriteEncodeError.None;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Sets the metric's typed value field and its <c>Datatype</c> from the tag's declared type.
|
||||
/// </summary>
|
||||
/// <param name="metric">The metric being built.</param>
|
||||
/// <param name="dataType">The tag's declared driver data type.</param>
|
||||
/// <param name="value">The value to convert.</param>
|
||||
/// <returns>The encode outcome.</returns>
|
||||
/// <remarks>
|
||||
/// <c>Datatype</c> is set explicitly rather than left for the node to infer, for the same reason
|
||||
/// <see cref="RebirthRequester"/> sets it: a node that treats a missing or ambiguous field as
|
||||
/// malformed drops the command silently, and a silently-dropped write is the failure mode this
|
||||
/// whole feature must not have.
|
||||
/// </remarks>
|
||||
private static MqttWriteEncodeError ApplyValue(
|
||||
Payload.Types.Metric metric,
|
||||
DriverDataType dataType,
|
||||
object value)
|
||||
{
|
||||
try
|
||||
{
|
||||
switch (dataType)
|
||||
{
|
||||
case DriverDataType.Boolean:
|
||||
metric.Datatype = (uint)TahuDataType.Boolean;
|
||||
metric.BooleanValue = Convert.ToBoolean(value, CultureInfo.InvariantCulture);
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.Int16:
|
||||
metric.Datatype = (uint)TahuDataType.Int16;
|
||||
metric.IntValue = unchecked((uint)Convert.ToInt16(value, CultureInfo.InvariantCulture));
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.Int32:
|
||||
metric.Datatype = (uint)TahuDataType.Int32;
|
||||
metric.IntValue = unchecked((uint)Convert.ToInt32(value, CultureInfo.InvariantCulture));
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.Int64:
|
||||
metric.Datatype = (uint)TahuDataType.Int64;
|
||||
metric.LongValue = unchecked((ulong)Convert.ToInt64(value, CultureInfo.InvariantCulture));
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.UInt16:
|
||||
metric.Datatype = (uint)TahuDataType.Uint16;
|
||||
metric.IntValue = Convert.ToUInt16(value, CultureInfo.InvariantCulture);
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.UInt32:
|
||||
metric.Datatype = (uint)TahuDataType.Uint32;
|
||||
metric.IntValue = Convert.ToUInt32(value, CultureInfo.InvariantCulture);
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.UInt64:
|
||||
metric.Datatype = (uint)TahuDataType.Uint64;
|
||||
metric.LongValue = Convert.ToUInt64(value, CultureInfo.InvariantCulture);
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.Float32:
|
||||
metric.Datatype = (uint)TahuDataType.Float;
|
||||
metric.FloatValue = Convert.ToSingle(value, CultureInfo.InvariantCulture);
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.Float64:
|
||||
metric.Datatype = (uint)TahuDataType.Double;
|
||||
metric.DoubleValue = Convert.ToDouble(value, CultureInfo.InvariantCulture);
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.String:
|
||||
metric.Datatype = (uint)TahuDataType.String;
|
||||
metric.StringValue = value as string ?? Convert.ToString(value, CultureInfo.InvariantCulture) ?? "";
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
case DriverDataType.DateTime:
|
||||
metric.Datatype = (uint)TahuDataType.DateTime;
|
||||
metric.LongValue = (ulong)new DateTimeOffset(
|
||||
Convert.ToDateTime(value, CultureInfo.InvariantCulture).ToUniversalTime())
|
||||
.ToUnixTimeMilliseconds();
|
||||
return MqttWriteEncodeError.None;
|
||||
|
||||
default:
|
||||
// DriverDataType.Reference and anything added later: refuse rather than guess a
|
||||
// wire representation. An unsupported type must not become a String on the wire.
|
||||
return MqttWriteEncodeError.UnsupportedDataType;
|
||||
}
|
||||
}
|
||||
catch (Exception ex) when (ex is InvalidCastException or FormatException or OverflowException)
|
||||
{
|
||||
return MqttWriteEncodeError.ValueNotRepresentable;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>One encoded outbound write: where it goes and what it carries.</summary>
|
||||
/// <param name="Topic">The concrete topic to publish on.</param>
|
||||
/// <param name="Payload">The encoded message body.</param>
|
||||
public readonly record struct MqttEncodedWrite(string Topic, byte[] Payload);
|
||||
Reference in New Issue
Block a user