Merge branch 'feat/mqtt-sparkplug-driver'
# Conflicts: # src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverTypeNames.cs # src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Drivers/DriverConfigModal.razor # src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/EndpointRouteBuilderExtensions.cs # src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/TagEditors/TagConfigEditorMap.cs # src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/TagEditors/TagConfigValidator.cs # src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/ZB.MOM.WW.OtOpcUa.AdminUI.csproj # src/Server/ZB.MOM.WW.OtOpcUa.Host/Drivers/DriverFactoryBootstrap.cs
This commit is contained in:
Joseph Doherty
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,192 @@
|
||||
using System.Buffers;
|
||||
using System.Text.Json;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Microsoft.Extensions.Logging.Abstractions;
|
||||
using MQTTnet;
|
||||
using MQTTnet.Protocol;
|
||||
using ZB.MOM.WW.OtOpcUa.Commons.Browsing;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser;
|
||||
|
||||
/// <summary>
|
||||
/// Bespoke MQTT address-picker browser: opens a short-lived, <b>strictly passive</b> observation
|
||||
/// window against the broker named by the form's JSON.
|
||||
/// <para>
|
||||
/// MQTT has no discovery protocol, so there is nothing to enumerate — the browser subscribes
|
||||
/// to a wildcard (<c>#</c> / <c>{topicPrefix}/#</c> in plain mode, <c>spBv1.0/{groupId}/#</c>
|
||||
/// in Sparkplug mode) and lets <see cref="MqttBrowseSession"/> accumulate whatever arrives:
|
||||
/// a topic segment tree in plain mode, a Group → EdgeNode → Device → Metric tree decoded from
|
||||
/// observed birth certificates in Sparkplug mode. Nothing on any browse path publishes — in
|
||||
/// either mode: an operator opening a picker must not be able to inject a message into a
|
||||
/// running plant. The session's operator-triggered <c>RequestRebirthAsync</c> is the sole
|
||||
/// sanctioned publish, and it is never reached by <c>OpenAsync</c> or by any browse call.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Layering note.</b> Unlike every other bespoke browser here, this project references the
|
||||
/// runtime <c>.Driver</c> project (to reuse <c>MqttConnection.BuildClientOptions</c> rather
|
||||
/// than fork the TLS / CA-pin path). That is a known, deliberate exception with a documented
|
||||
/// cost and a documented clean fix — see the comment on that <c>ProjectReference</c> in
|
||||
/// <c>ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser.csproj</c> before copying this project as a
|
||||
/// template.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public sealed class MqttDriverBrowser : IDriverBrowser
|
||||
{
|
||||
/// <summary>Floor on the open budget — a 1 s <c>ConnectTimeoutSeconds</c> would make browse unusable.</summary>
|
||||
internal const int MinOpenBudgetSeconds = 5;
|
||||
|
||||
/// <summary>Ceiling on the open budget — the picker must never hang on an unreachable broker.</summary>
|
||||
internal const int MaxOpenBudgetSeconds = 30;
|
||||
|
||||
/// <summary>Marks the transient browse identity in the broker's client-id/session logs.</summary>
|
||||
internal const string BrowseClientIdPrefix = "-browse-";
|
||||
|
||||
private readonly ILogger<MqttDriverBrowser> _logger;
|
||||
|
||||
/// <summary>
|
||||
/// Creates a browser. <b>Connection-free by contract</b> — the universal browser's
|
||||
/// <c>CanBrowse</c> constructs a throwaway instance purely to ask which driver type it
|
||||
/// handles, so the constructor must never touch the network.
|
||||
/// </summary>
|
||||
/// <param name="logger">Optional logger; defaults to <see cref="NullLogger{T}"/>. Never receives credentials.</param>
|
||||
public MqttDriverBrowser(ILogger<MqttDriverBrowser>? logger = null) =>
|
||||
_logger = logger ?? NullLogger<MqttDriverBrowser>.Instance;
|
||||
|
||||
/// <inheritdoc />
|
||||
public string DriverType => DriverTypeNames.Mqtt;
|
||||
|
||||
/// <inheritdoc />
|
||||
/// <remarks>
|
||||
/// Connects with a browse-only client id, subscribes the wildcard at QoS 0, and hands back a
|
||||
/// session that serves whatever the subscription observes. The whole open is bounded by
|
||||
/// <see cref="OpenBudget"/>; nothing here publishes.
|
||||
/// </remarks>
|
||||
public async Task<IBrowseSession> OpenAsync(string configJson, CancellationToken cancellationToken)
|
||||
{
|
||||
// MqttJson.Options — the ONE shared instance across factory / probe / driver / browser
|
||||
// (see its remarks). Parsing the same DriverConfig blob through a second, divergent
|
||||
// JsonSerializerOptions is this repo's documented systemic enum bug: the picker would accept
|
||||
// a `mode` / `protocolVersion` spelling the deployed driver rejects, or vice versa.
|
||||
var opts = JsonSerializer.Deserialize<MqttDriverOptions>(configJson, MqttJson.Options)
|
||||
?? throw new InvalidOperationException("Mqtt options deserialized to null.");
|
||||
|
||||
var filter = BuildRootFilter(opts);
|
||||
var suffix = BuildBrowseClientIdSuffix();
|
||||
var clientOptions = MqttConnection.BuildClientOptions(ToBrowseOptions(opts), suffix, _logger);
|
||||
|
||||
using var openCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
|
||||
openCts.CancelAfter(OpenBudget(opts));
|
||||
|
||||
var client = new MqttClientFactory().CreateMqttClient();
|
||||
var session = new MqttBrowseSession(opts.Mode, client, _logger);
|
||||
try
|
||||
{
|
||||
// Runs on MQTTnet's dispatcher: record and return, nothing else.
|
||||
client.ApplicationMessageReceivedAsync += args =>
|
||||
{
|
||||
var payload = args.ApplicationMessage.Payload;
|
||||
ReadOnlySpan<byte> body = payload.IsSingleSegment ? payload.FirstSpan : payload.ToArray();
|
||||
session.Observe(args.ApplicationMessage.Topic, body);
|
||||
return Task.CompletedTask;
|
||||
};
|
||||
|
||||
await client.ConnectAsync(clientOptions, openCts.Token).ConfigureAwait(false);
|
||||
|
||||
// QoS 0: a transient observation window has no delivery guarantee to offer and should
|
||||
// cost the broker as little as possible.
|
||||
var subscribeOptions = new MqttClientSubscribeOptionsBuilder()
|
||||
.WithTopicFilter(f => f
|
||||
.WithTopic(filter)
|
||||
.WithQualityOfServiceLevel(MqttQualityOfServiceLevel.AtMostOnce))
|
||||
.Build();
|
||||
await client.SubscribeAsync(subscribeOptions, openCts.Token).ConfigureAwait(false);
|
||||
|
||||
_logger.LogInformation(
|
||||
"AdminUI MQTT browse session opened against {Host}:{Port} in {Mode} mode observing "
|
||||
+ "'{Filter}' (read-only).",
|
||||
opts.Host, opts.Port, opts.Mode, filter);
|
||||
|
||||
return session;
|
||||
}
|
||||
catch
|
||||
{
|
||||
await session.DisposeAsync().ConfigureAwait(false); // owns the client — disconnects + disposes
|
||||
throw;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The wildcard the observation window subscribes to.
|
||||
/// <para>
|
||||
/// <b>Plain mode:</b> the whole broker (<c>#</c>) unless the config scopes it with a
|
||||
/// topic prefix.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Sparkplug mode:</b> the Sparkplug namespace only —
|
||||
/// <c>spBv1.0/{groupId}/#</c>, matching the group the deployed driver itself subscribes
|
||||
/// (design §3.1), or <c>spBv1.0/#</c> when no group has been authored yet, so the picker
|
||||
/// can discover which groups exist. The Plain-mode topic prefix is deliberately ignored:
|
||||
/// it is a different mode's key, and honouring it would silently narrow the window to a
|
||||
/// prefix that cannot match a Sparkplug topic at all.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
/// <param name="options">The browse configuration.</param>
|
||||
/// <returns>The MQTT topic filter to subscribe.</returns>
|
||||
internal static string BuildRootFilter(MqttDriverOptions options)
|
||||
{
|
||||
if (options.Mode == MqttMode.SparkplugB)
|
||||
{
|
||||
var groupId = (options.Sparkplug?.GroupId ?? string.Empty).Trim();
|
||||
return groupId.Length == 0 ? "spBv1.0/#" : $"spBv1.0/{groupId}/#";
|
||||
}
|
||||
|
||||
var prefix = (options.Plain?.TopicPrefix ?? string.Empty).Trim();
|
||||
if (prefix.Length == 0) return "#";
|
||||
if (!prefix.EndsWith('/')) prefix += "/";
|
||||
return prefix + "#";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A unique per-session client-id suffix. A broker disconnects an existing client when a new
|
||||
/// one CONNECTs with the <i>same</i> client id, so sharing the driver's id would knock the
|
||||
/// live driver offline every time an operator opened the picker.
|
||||
/// </summary>
|
||||
/// <returns>The suffix appended to the configured client id.</returns>
|
||||
internal static string BuildBrowseClientIdSuffix() =>
|
||||
BrowseClientIdPrefix + Guid.NewGuid().ToString("N")[..8];
|
||||
|
||||
/// <summary>
|
||||
/// Projects the authored options into the ones the browse CONNECT uses. Clean session is
|
||||
/// forced: a transient browse identity must not leave queued-message state behind on the
|
||||
/// broker after the picker closes.
|
||||
/// <para>
|
||||
/// ⚠ <b>THE landmine — a Last Will would break the read-only guarantee from outside it.</b>
|
||||
/// <c>MqttDriverOptions</c> (and <c>MqttSparkplugOptions</c>) carry no will, <b>re-verified
|
||||
/// when Task 23 unsealed Sparkplug browse</b>, so there is nothing to strip and the
|
||||
/// projection stays a single <c>CleanSession</c> override. If a will is ever added — NDEATH
|
||||
/// <i>is</i> a will message — it MUST be cleared here: a will is published by the
|
||||
/// <i>broker</i>, not by us, so it is invisible to
|
||||
/// <see cref="MqttBrowseSession.PublishCountForTest"/>, and any ungraceful end to a browse
|
||||
/// session (crash, dropped link, the disconnect deadline expiring) would then fire an
|
||||
/// NDEATH under the plant's own edge-node identity — killing a live Sparkplug node because
|
||||
/// an operator opened an address picker. <c>MqttBrowseSessionTests</c>'
|
||||
/// <c>MqttDriverOptions_CarryNothingWillShaped_…</c> is the reflection guard that turns that
|
||||
/// "there is nothing to strip" into a checked fact rather than a claim.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
/// <param name="options">The authored configuration.</param>
|
||||
/// <returns>The configuration the browse CONNECT is built from.</returns>
|
||||
internal static MqttDriverOptions ToBrowseOptions(MqttDriverOptions options) =>
|
||||
options with { CleanSession = true };
|
||||
|
||||
/// <summary>
|
||||
/// Whole-open bound (connect + subscribe), clamped to
|
||||
/// <see cref="MinOpenBudgetSeconds"/>–<see cref="MaxOpenBudgetSeconds"/> around the config's
|
||||
/// own connect deadline.
|
||||
/// </summary>
|
||||
/// <param name="options">The browse configuration.</param>
|
||||
/// <returns>The clamped open budget.</returns>
|
||||
internal static TimeSpan OpenBudget(MqttDriverOptions options) =>
|
||||
TimeSpan.FromSeconds(Math.Clamp(options.ConnectTimeoutSeconds, MinOpenBudgetSeconds, MaxOpenBudgetSeconds));
|
||||
}
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<Nullable>enable</Nullable>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<LangVersion>latest</LangVersion>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
<RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser</RootNamespace>
|
||||
<AssemblyName>ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser</AssemblyName>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Commons\ZB.MOM.WW.OtOpcUa.Commons.csproj"/>
|
||||
<ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts\ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts.csproj"/>
|
||||
<!--
|
||||
┌──────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ KNOWN, DELIBERATE EXCEPTION to the .Browser → .Contracts pattern. │
|
||||
│ DO NOT COPY THIS LINE INTO A NEW DRIVER'S BROWSER WITHOUT READING THIS. │
|
||||
└──────────────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Every other bespoke browser in this repo (OpcUaClient, Galaxy) references only its own
|
||||
.Contracts project plus its transport package. This one also references the runtime
|
||||
.Driver project. That is a real widening, not a free one, and it was accepted knowingly:
|
||||
|
||||
WHY: the browse CONNECT reuses MqttConnection.BuildClientOptions, which owns the TLS
|
||||
posture, the PEM CA-pin chain validator, the credential handling and the protocol
|
||||
version mapping (~100 lines). A second copy here would be a silent security
|
||||
divergence — browse quietly not honouring a pinned CA while the runtime driver does.
|
||||
The method is pure (no I/O, no network), so the dependency costs nothing at run time.
|
||||
|
||||
WHAT IT COSTS: the AdminUI's project graph does NOT otherwise include Core.csproj
|
||||
(only Host.csproj and the runtime Driver.* projects do). Referencing this browser
|
||||
from the AdminUI therefore pulls in Core + Polly.Core + Serilog at build/deploy time.
|
||||
|
||||
THE CLEAN FIX (deferred, not blocked): a small leaf project — say
|
||||
ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Transport (net10, refs .Contracts + MQTTnet) — holding
|
||||
BuildClientOptions/ConfigureTls/the CA-pin helpers, referenced by BOTH .Driver and
|
||||
.Browser. Note the obvious-looking alternative does NOT work: those members cannot
|
||||
move into .Contracts, because .Contracts is deliberately transport-free (Task 1
|
||||
removed its MQTTnet reference to keep it so) and BuildClientOptions returns
|
||||
MqttClientOptions, an MQTTnet type.
|
||||
-->
|
||||
<ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Driver.Mqtt\ZB.MOM.WW.OtOpcUa.Driver.Mqtt.csproj"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="MQTTnet"/>
|
||||
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests"/>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
@@ -0,0 +1,225 @@
|
||||
using System.ComponentModel.DataAnnotations;
|
||||
using System.Text;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// MQTT / Sparkplug B driver configuration. Bound from <c>DriverConfig</c> JSON at
|
||||
/// driver-host registration time. Models the settings documented in
|
||||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// A record (not a plain class) so a future secret-resolution seam can produce a
|
||||
/// credential-resolved copy with a <c>with</c> expression — mirrors
|
||||
/// <c>OpcUaClientDriverOptions</c>. <see cref="Mode"/> selects the ingest shape;
|
||||
/// <see cref="Sparkplug"/> and <see cref="Plain"/> are nullable sub-objects — only the one
|
||||
/// matching <see cref="Mode"/> is populated.
|
||||
/// </remarks>
|
||||
public sealed record MqttDriverOptions
|
||||
{
|
||||
/// <summary>Broker hostname or IP address.</summary>
|
||||
public string Host { get; init; } = "localhost";
|
||||
|
||||
/// <summary>Broker TCP port.</summary>
|
||||
[Range(1, 65535)]
|
||||
public int Port { get; init; } = 8883;
|
||||
|
||||
/// <summary>
|
||||
/// MQTT client identifier sent at CONNECT. Leave unset to let the driver generate one
|
||||
/// (a stable per-instance id is recommended so broker-side ACLs / session state persist
|
||||
/// across reconnects).
|
||||
/// </summary>
|
||||
public string? ClientId { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// When <c>true</c>, connect over TLS. Default <c>true</c> — this driver never ships an
|
||||
/// anonymous/plaintext-by-default posture; a deployment must opt into <c>false</c> for an
|
||||
/// on-prem/dev broker with no TLS listener.
|
||||
/// </summary>
|
||||
public bool UseTls { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// When <c>true</c>, accept any self-signed / untrusted broker certificate. Dev/on-prem
|
||||
/// escape hatch only — mirrors the <c>ServerHistorian</c> TLS knobs. Must stay
|
||||
/// <c>false</c> in production so MITM attacks against the broker connection fail closed.
|
||||
/// </summary>
|
||||
public bool AllowUntrustedServerCertificate { get; init; } = false;
|
||||
|
||||
/// <summary>
|
||||
/// PEM CA file pinning the broker's TLS chain. <c>null</c>/empty uses the OS trust
|
||||
/// store.
|
||||
/// </summary>
|
||||
public string? CaCertificatePath { get; init; }
|
||||
|
||||
/// <summary>Username for broker authentication. <c>null</c> connects without a username.</summary>
|
||||
public string? Username { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Password for broker authentication. Blank in committed JSON — supply via env, never
|
||||
/// commit or log.
|
||||
/// </summary>
|
||||
public string? Password { get; init; } = "";
|
||||
|
||||
/// <summary>MQTT protocol version to negotiate at CONNECT.</summary>
|
||||
public MqttProtocolVersion ProtocolVersion { get; init; } = MqttProtocolVersion.V500;
|
||||
|
||||
/// <summary>Whether to request a clean session (v3.1.1) / clean start (v5.0) at CONNECT.</summary>
|
||||
public bool CleanSession { get; init; } = true;
|
||||
|
||||
/// <summary>Keep-alive interval sent at CONNECT.</summary>
|
||||
[Range(1, int.MaxValue)]
|
||||
public int KeepAliveSeconds { get; init; } = 30;
|
||||
|
||||
/// <summary>Bounded connect deadline (see design §8) — the driver never hangs past this.</summary>
|
||||
[Range(1, int.MaxValue)]
|
||||
public int ConnectTimeoutSeconds { get; init; } = 15;
|
||||
|
||||
/// <summary>Initial reconnect backoff after a connection drop.</summary>
|
||||
[Range(1, int.MaxValue)]
|
||||
public int ReconnectMinBackoffSeconds { get; init; } = 1;
|
||||
|
||||
/// <summary>Cap on the exponential reconnect backoff.</summary>
|
||||
[Range(1, int.MaxValue)]
|
||||
public int ReconnectMaxBackoffSeconds { get; init; } = 30;
|
||||
|
||||
/// <summary>
|
||||
/// Ceiling on an inbound message body, in bytes. A larger message is refused before any
|
||||
/// decode or parse and degrades its own tags to <c>BadDecodingError</c>. Default 1 MiB.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Decode and parse both run synchronously on MQTTnet's shared dispatcher thread, so their
|
||||
/// cost is paid by <i>every</i> subscription, not just the offending topic — without a bound,
|
||||
/// one publisher shipping a multi-megabyte body stalls the whole driver's delivery. "Unbounded"
|
||||
/// is deliberately not offered; a non-positive value falls back to the driver's own 1 MiB
|
||||
/// default. The literal is duplicated from <c>MqttSubscriptionManager.DefaultMaxPayloadBytes</c>
|
||||
/// because this <c>.Contracts</c> assembly is <i>referenced by</i> the driver assembly and
|
||||
/// cannot reference it back; the manager's constructor is the single enforcement point.
|
||||
/// </remarks>
|
||||
[Range(1, int.MaxValue)]
|
||||
public int MaxPayloadBytes { get; init; } = 1024 * 1024;
|
||||
|
||||
/// <summary>Selects the ingest shape — Plain topics or Sparkplug B.</summary>
|
||||
public MqttMode Mode { get; init; } = MqttMode.Plain;
|
||||
|
||||
/// <summary>
|
||||
/// The cluster's authored raw MQTT tags, as delivered by the deploy artifact: each carries the
|
||||
/// tag's <b>RawPath</b> (its v3 identity and driver wire reference) plus its <c>TagConfig</c>
|
||||
/// blob. <see cref="MqttDriver"/> maps each through <see cref="MqttTagDefinitionFactory"/> at
|
||||
/// initialize and re-registers the set <b>wholesale</b> on every reinitialize, so a redeploy
|
||||
/// that drops a tag stops feeding it.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// This is also the <b>only</b> source of the driver's discoverable node set — plain MQTT has
|
||||
/// no browsable address space, and a tag that is not authored here is never materialized no
|
||||
/// matter how much traffic its topic carries. Mirrors <c>ModbusDriverOptions.RawTags</c> /
|
||||
/// <c>FocasDriverOptions.RawTags</c>.
|
||||
/// </remarks>
|
||||
public IReadOnlyList<RawTagEntry> RawTags { get; init; } = [];
|
||||
|
||||
/// <summary>
|
||||
/// Sparkplug-only settings. Populated when <see cref="Mode"/> is
|
||||
/// <see cref="MqttMode.SparkplugB"/>; <c>null</c> in Plain mode.
|
||||
/// </summary>
|
||||
public MqttSparkplugOptions? Sparkplug { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Plain-mode-only settings. Populated when <see cref="Mode"/> is
|
||||
/// <see cref="MqttMode.Plain"/>; <c>null</c> in Sparkplug B mode.
|
||||
/// </summary>
|
||||
public MqttPlainOptions? Plain { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Record-generated <c>ToString()</c> member printer, overridden so <see cref="Password"/>
|
||||
/// never renders in plaintext — this DTO routinely lands in logs / exception messages /
|
||||
/// debugger watches, and the plan's cross-cutting rule is explicit: never commit or log
|
||||
/// creds. A set password prints as <c>***</c>; unset (<c>null</c>/empty) renders
|
||||
/// distinguishably so the redaction can't be mistaken for a real secret.
|
||||
/// </summary>
|
||||
private bool PrintMembers(StringBuilder builder)
|
||||
{
|
||||
var passwordDisplay = Password switch
|
||||
{
|
||||
null => "<null>",
|
||||
"" => "<empty>",
|
||||
_ => "***",
|
||||
};
|
||||
|
||||
builder.Append("Host = ").Append(Host);
|
||||
builder.Append(", Port = ").Append(Port);
|
||||
builder.Append(", ClientId = ").Append(ClientId);
|
||||
builder.Append(", UseTls = ").Append(UseTls);
|
||||
builder.Append(", AllowUntrustedServerCertificate = ").Append(AllowUntrustedServerCertificate);
|
||||
builder.Append(", CaCertificatePath = ").Append(CaCertificatePath);
|
||||
builder.Append(", Username = ").Append(Username);
|
||||
builder.Append(", Password = ").Append(passwordDisplay);
|
||||
builder.Append(", ProtocolVersion = ").Append(ProtocolVersion);
|
||||
builder.Append(", CleanSession = ").Append(CleanSession);
|
||||
builder.Append(", KeepAliveSeconds = ").Append(KeepAliveSeconds);
|
||||
builder.Append(", ConnectTimeoutSeconds = ").Append(ConnectTimeoutSeconds);
|
||||
builder.Append(", ReconnectMinBackoffSeconds = ").Append(ReconnectMinBackoffSeconds);
|
||||
builder.Append(", ReconnectMaxBackoffSeconds = ").Append(ReconnectMaxBackoffSeconds);
|
||||
builder.Append(", MaxPayloadBytes = ").Append(MaxPayloadBytes);
|
||||
builder.Append(", Mode = ").Append(Mode);
|
||||
builder.Append(", Sparkplug = ").Append(Sparkplug);
|
||||
builder.Append(", Plain = ").Append(Plain);
|
||||
// Count only: a deployment routinely authors thousands of raw tags and each carries a full
|
||||
// TagConfig blob, so printing the list would turn any log of this DTO into a config dump.
|
||||
builder.Append(", RawTags = ").Append(RawTags.Count).Append(" tag(s)");
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Sparkplug B settings for an <see cref="MqttDriverOptions"/> instance in
|
||||
/// <see cref="MqttMode.SparkplugB"/> mode. See
|
||||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||||
/// </summary>
|
||||
public sealed record MqttSparkplugOptions
|
||||
{
|
||||
/// <summary>Sparkplug group id — the driver subscribes <c>spBv1.0/{GroupId}/#</c>.</summary>
|
||||
public string GroupId { get; init; } = "";
|
||||
|
||||
/// <summary>
|
||||
/// Sparkplug Host Application identity — published as <c>spBv1.0/STATE/{HostId}</c>
|
||||
/// (Sparkplug v3.0).
|
||||
/// </summary>
|
||||
public string HostId { get; init; } = "";
|
||||
|
||||
/// <summary>
|
||||
/// When <c>true</c>, this driver instance acts as the Sparkplug Primary Host
|
||||
/// Application. At most one primary host may exist per host-id per broker.
|
||||
/// </summary>
|
||||
public bool ActAsPrimaryHost { get; init; } = false;
|
||||
|
||||
/// <summary>
|
||||
/// When <c>true</c>, a detected sequence-number gap triggers a Sparkplug rebirth
|
||||
/// request (NCMD) rather than silently continuing with stale metric state.
|
||||
/// </summary>
|
||||
public bool RequestRebirthOnGap { get; init; } = true;
|
||||
|
||||
/// <summary>
|
||||
/// How long, in seconds, browse/discovery collects NBIRTH/DBIRTH traffic before
|
||||
/// considering the observed metric set stable.
|
||||
/// </summary>
|
||||
[Range(1, int.MaxValue)]
|
||||
public int BirthObservationWindowSeconds { get; init; } = 15;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Plain-MQTT-mode settings for an <see cref="MqttDriverOptions"/> instance in
|
||||
/// <see cref="MqttMode.Plain"/> mode. See
|
||||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||||
/// </summary>
|
||||
public sealed record MqttPlainOptions
|
||||
{
|
||||
/// <summary>
|
||||
/// Optional prefix prepended when the driver needs to compose a topic (e.g. discovery
|
||||
/// scoping); per-tag topics are authored explicitly and are unaffected.
|
||||
/// </summary>
|
||||
public string TopicPrefix { get; init; } = "";
|
||||
|
||||
/// <summary>Default QoS used when a tag's own <c>qos</c> is unset.</summary>
|
||||
[Range(0, 2)]
|
||||
public int DefaultQos { get; init; } = 1;
|
||||
}
|
||||
@@ -0,0 +1,53 @@
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// The <b>single</b> <see cref="JsonSerializerOptions"/> instance every MQTT driver-config seam
|
||||
/// parses <see cref="MqttDriverOptions"/> through — the runtime factory
|
||||
/// (<c>MqttDriverFactoryExtensions</c>), the Test-connect probe (<c>MqttDriverProbe</c>), the
|
||||
/// driver's own <c>ReinitializeAsync</c> re-parse, and the address-picker browser
|
||||
/// (<c>MqttDriverBrowser</c>).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Why one instance, and why here.</b> Divergent per-seam options are this repo's
|
||||
/// documented systemic enum bug: an AdminUI-authored config with an enum-valued field is
|
||||
/// accepted by the seam that carries a <see cref="JsonStringEnumConverter"/> and faults the
|
||||
/// one that does not, so "Test connect" goes green and the deployed driver dies. Two other
|
||||
/// drivers already carry a copy per seam. Rather than repeat that, this driver keeps exactly
|
||||
/// one instance.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// It lives in <c>.Contracts</c> — the assembly that owns <see cref="MqttDriverOptions"/> and
|
||||
/// the three enums the converter exists for — rather than in the factory or the probe,
|
||||
/// because <c>.Contracts</c> is the <i>only</i> assembly all four consumers already reference.
|
||||
/// In particular the browser lives in its own assembly and reaches the runtime <c>.Driver</c>
|
||||
/// project only through a deliberate, documented layering exception that is scheduled to be
|
||||
/// removed (see the <c>ProjectReference</c> comment in the browser's csproj); anchoring the
|
||||
/// options in <c>.Driver</c> would resurrect the duplicate the day that reference goes away.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Not a general-purpose JSON policy.</b> <c>UnmappedMemberHandling.Skip</c> means an
|
||||
/// unknown key is ignored rather than rejected — deliberate, so a config blob authored
|
||||
/// against a newer driver still binds — and <c>PropertyNameCaseInsensitive</c> accepts both
|
||||
/// the camelCase the AdminUI emits and the PascalCase a hand-edited blob may carry. A
|
||||
/// <see cref="JsonSerializerOptions"/> becomes read-only on first use, so this instance is
|
||||
/// safe to share across threads and must never be mutated after startup.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class MqttJson
|
||||
{
|
||||
/// <summary>
|
||||
/// The shared options. Enum-valued knobs (<see cref="MqttMode"/>,
|
||||
/// <see cref="MqttProtocolVersion"/>, <see cref="MqttPayloadFormat"/>) round-trip by
|
||||
/// <b>name</b>; numeric ordinals still bind, so an older blob is not broken by this.
|
||||
/// </summary>
|
||||
public static readonly JsonSerializerOptions Options = new()
|
||||
{
|
||||
PropertyNameCaseInsensitive = true,
|
||||
UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip,
|
||||
Converters = { new JsonStringEnumConverter() },
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// Selects the ingest shape an <see cref="MqttDriverOptions"/> instance uses. See
|
||||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||||
/// </summary>
|
||||
public enum MqttMode
|
||||
{
|
||||
/// <summary>Plain MQTT — the driver subscribes to authored topics directly.</summary>
|
||||
Plain,
|
||||
|
||||
/// <summary>Sparkplug B — the driver decodes Tahu-encoded NBIRTH/DBIRTH/NDATA/DDATA payloads.</summary>
|
||||
SparkplugB,
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// How a Plain-mode MQTT tag's payload is decoded. See
|
||||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.3.
|
||||
/// </summary>
|
||||
public enum MqttPayloadFormat
|
||||
{
|
||||
/// <summary>The payload is a JSON document; a JSONPath selects the value (<c>jsonPath</c>).</summary>
|
||||
Json,
|
||||
|
||||
/// <summary>The payload bytes are used as-is (e.g. binary / opaque).</summary>
|
||||
Raw,
|
||||
|
||||
/// <summary>The payload is a bare scalar string (e.g. <c>"23.5"</c>), parsed by <c>dataType</c>.</summary>
|
||||
Scalar,
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// MQTT wire protocol version negotiated at CONNECT. See
|
||||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||||
/// </summary>
|
||||
public enum MqttProtocolVersion
|
||||
{
|
||||
/// <summary>MQTT 3.1.1.</summary>
|
||||
V311,
|
||||
|
||||
/// <summary>MQTT 5.0.</summary>
|
||||
V500,
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// The <c>TagConfig</c> JSON key names that make up an MQTT tag's <b>address</b>, in the two shapes
|
||||
/// the driver binds by: a single <see cref="Topic"/> (Plain) or the
|
||||
/// <see cref="GroupId"/>/<see cref="EdgeNodeId"/>/<see cref="DeviceId"/>/<see cref="MetricName"/>
|
||||
/// tuple (Sparkplug B).
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// These exist because the address is produced in one place and consumed in another, and the
|
||||
/// two used to agree only by coincidence: the AdminUI browse-commit mapper writes the blob,
|
||||
/// <see cref="MqttTagDefinitionFactory"/> reads it, and a key-name drift between them is not a
|
||||
/// compile error — it is a tag that deploys clean, resolves to nothing, and reports
|
||||
/// <c>BadNodeIdUnknown</c> at runtime with no authoring-time signal at all. Single-sourcing
|
||||
/// the names makes that drift impossible rather than merely unlikely.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Address keys only.</b> The behavioural keys (<c>payloadFormat</c>, <c>jsonPath</c>,
|
||||
/// <c>dataType</c>, <c>qos</c>, <c>retainSeed</c>) are deliberately not here — nothing produces
|
||||
/// them from a browse, so they carry no cross-component drift risk.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class MqttTagConfigKeys
|
||||
{
|
||||
/// <summary>The concrete MQTT topic a Plain-mode tag subscribes to.</summary>
|
||||
public const string Topic = "topic";
|
||||
|
||||
/// <summary>The Sparkplug group id — the first segment of the tag's binding tuple.</summary>
|
||||
public const string GroupId = "groupId";
|
||||
|
||||
/// <summary>The Sparkplug edge-node id.</summary>
|
||||
public const string EdgeNodeId = "edgeNodeId";
|
||||
|
||||
/// <summary>The Sparkplug device id; absent for a metric published by the edge node itself.</summary>
|
||||
public const string DeviceId = "deviceId";
|
||||
|
||||
/// <summary>The Sparkplug metric's stable name — the tag's binding key across rebirths.</summary>
|
||||
public const string MetricName = "metricName";
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// The driver's internal per-tag descriptor — the parsed form of an authored raw tag's
|
||||
/// <c>TagConfig</c> JSON, produced by <see cref="MqttTagDefinitionFactory.FromTagConfig"/> and
|
||||
/// looked up through the shared <see cref="EquipmentTagRefResolver{TDef}"/> exactly as Modbus does.
|
||||
/// 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 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">
|
||||
/// The definition's identity: the tag's <b>RawPath</b> — the cluster-scoped slash path that is the
|
||||
/// v3 driver wire reference. This is the key <see cref="EquipmentTagRefResolver{TDef}"/> resolves
|
||||
/// on, the key <c>OnDataChange</c> must publish under, and the key <c>DriverHostActor</c> fans out
|
||||
/// to the raw + UNS NodeIds. It is emphatically <b>not</b> the authored <c>TagConfig</c> blob: the
|
||||
/// pre-v3 blob-as-reference shape is retired, and publishing under a blob key would silently miss
|
||||
/// the RawPath-keyed fan-out while every unit test still passed.
|
||||
/// </param>
|
||||
/// <param name="Topic">The concrete MQTT topic this tag subscribes to (Plain mode).</param>
|
||||
/// <param name="PayloadFormat">How the received payload is decoded (Plain mode).</param>
|
||||
/// <param name="JsonPath">
|
||||
/// JSONPath selecting the value inside a <see cref="MqttPayloadFormat.Json"/> payload. Defaults
|
||||
/// to the document root (<c>$</c>) when the blob omits it; meaningless for
|
||||
/// <see cref="MqttPayloadFormat.Raw"/> / <see cref="MqttPayloadFormat.Scalar"/>.
|
||||
/// </param>
|
||||
/// <param name="DataType">
|
||||
/// The tag's declared value type. Explicit authoring is strongly preferred — payload-shape
|
||||
/// inference is the brittle fallback (design §4).
|
||||
/// </param>
|
||||
/// <param name="Qos">
|
||||
/// The per-tag subscription QoS (0–2), or <see langword="null"/> to inherit the driver-level
|
||||
/// <see cref="MqttPlainOptions.DefaultQos"/>.
|
||||
/// </param>
|
||||
/// <param name="RetainSeed">
|
||||
/// 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="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">
|
||||
/// 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">
|
||||
/// 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,
|
||||
string Topic,
|
||||
MqttPayloadFormat PayloadFormat,
|
||||
string JsonPath,
|
||||
DriverDataType DataType,
|
||||
int? Qos,
|
||||
bool RetainSeed,
|
||||
bool DataTypeAuthored = true,
|
||||
string? GroupId = null,
|
||||
string? EdgeNodeId = null,
|
||||
string? DeviceId = null,
|
||||
string? MetricName = null);
|
||||
@@ -0,0 +1,290 @@
|
||||
using System.Text.Json;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// v3 pure mapper: turns an authored raw tag's <c>TagConfig</c> JSON (the shape produced by the
|
||||
/// AdminUI <c>MqttTagConfigModel</c>) into an <see cref="MqttTagDefinition"/>. Under v3 a tag's
|
||||
/// identity is its <b>RawPath</b> (a cluster-scoped slash path), not the address blob — so the
|
||||
/// produced definition's <see cref="MqttTagDefinition.Name"/> is the RawPath the driver was handed,
|
||||
/// which is exactly the wire reference the driver's <c>RawPath → def</c> resolver keys on. The driver
|
||||
/// builds that table by mapping each <see cref="RawTagEntry"/> the deploy artifact delivers through
|
||||
/// <see cref="FromTagConfig"/>.
|
||||
/// <para>
|
||||
/// Two entry points carry deliberately different strictness contracts.
|
||||
/// <see cref="FromTagConfig"/> is the <b>runtime</b> path: it never throws, and anything
|
||||
/// malformed returns <see langword="false"/> so the driver surfaces <c>BadNodeIdUnknown</c>
|
||||
/// rather than a misleading <c>Good</c> off a wrong-typed default. <see cref="Inspect"/> is the
|
||||
/// <b>deploy-time</b> path: it returns human-readable warnings so a bad tag config surfaces at
|
||||
/// deploy instead of silently going dark at runtime.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <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
|
||||
/// each carry one solely to serve their <c>Driver.<X>.Cli</c> project, which synthesises
|
||||
/// <see cref="RawTagEntry"/> blobs from operator flags; the MQTT plan defines no
|
||||
/// <c>Mqtt.Cli</c>. The AdminUI typed editor does not need one either — the
|
||||
/// <c><Driver>TagConfigModel</c> template serialises through its own preserved
|
||||
/// <c>JsonObject</c> key bag and references no driver factory (verified: no
|
||||
/// <c>TagDefinitionFactory</c> reference exists anywhere under the AdminUI project). Add the
|
||||
/// inverse when a real caller appears, not before.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public static class MqttTagDefinitionFactory
|
||||
{
|
||||
/// <summary>The JSONPath applied when a Json-format blob omits <c>jsonPath</c>: the document root.</summary>
|
||||
private const string RootJsonPath = "$";
|
||||
|
||||
/// <summary>The MQTT wildcard characters — illegal in a <em>tag's</em> (concrete) subscription topic.</summary>
|
||||
private static readonly char[] TopicWildcards = ['+', '#'];
|
||||
|
||||
/// <summary>
|
||||
/// Maps an authored <c>TagConfig</c> object to a typed definition keyed by <paramref name="rawPath"/>.
|
||||
/// The input is always an authored TagConfig JSON object (there is no name-vs-blob heuristic in v3).
|
||||
/// Enum fields (<c>payloadFormat</c> / <c>dataType</c>) and <c>qos</c> are read STRICTLY — a
|
||||
/// present-but-invalid (typo'd) value rejects the whole tag (returns <see langword="false"/> ⇒ the
|
||||
/// driver surfaces <c>BadNodeIdUnknown</c>) rather than silently defaulting to a wrong-typed Good or
|
||||
/// a downgraded delivery guarantee. Never throws.
|
||||
/// <para>
|
||||
/// A <b>wildcard</b> topic (<c>+</c> / <c>#</c>) is deliberately NOT rejected here: it is
|
||||
/// ambiguous rather than unparseable, and <see cref="Inspect"/> is the operator-visible surface
|
||||
/// for it. Rejecting it at runtime would turn an authoring mistake into a silent
|
||||
/// <c>BadNodeIdUnknown</c> with no stated cause.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
/// <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 <paramref name="tagConfig"/> is a valid MQTT tag-config object.</returns>
|
||||
public static bool FromTagConfig(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;
|
||||
|
||||
// topic is the whole point of a Plain-mode tag — without one there is nothing to subscribe
|
||||
// to, so an absent/blank value is a hard reject rather than a defaulted empty subscription.
|
||||
var topic = ReadString(root, MqttTagConfigKeys.Topic);
|
||||
if (string.IsNullOrWhiteSpace(topic)) return false;
|
||||
|
||||
// Strict enum reads: a present-but-invalid (typo'd) value rejects the whole tag
|
||||
// (→ 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;
|
||||
|
||||
// qos is read with the same strictness, for the same reason: silently absorbing a malformed
|
||||
// "qos":"high" / "qos":1.5 / "qos":5 into the driver-level default would hand the operator a
|
||||
// WEAKER delivery guarantee than the one they authored, with nothing to show for it.
|
||||
if (!TryReadQosStrict(root, out var qos)) return false;
|
||||
|
||||
var jsonPath = ReadString(root, "jsonPath");
|
||||
if (string.IsNullOrEmpty(jsonPath)) jsonPath = RootJsonPath;
|
||||
|
||||
def = new MqttTagDefinition(
|
||||
Name: rawPath,
|
||||
Topic: topic,
|
||||
PayloadFormat: payloadFormat,
|
||||
JsonPath: jsonPath,
|
||||
DataType: dataType,
|
||||
Qos: qos,
|
||||
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, MqttTagConfigKeys.GroupId);
|
||||
var edgeNodeId = ReadString(root, MqttTagConfigKeys.EdgeNodeId);
|
||||
var metricName = ReadString(root, MqttTagConfigKeys.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, MqttTagConfigKeys.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, MqttTagConfigKeys.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; }
|
||||
catch (FormatException) { return false; }
|
||||
catch (InvalidOperationException) { return false; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Deploy-time inspection of an equipment-tag <c>TagConfig</c> blob. Returns human-readable
|
||||
/// warnings for a structurally unparseable blob (which the runtime turns into a silent
|
||||
/// <c>BadNodeIdUnknown</c>), for present-but-invalid <c>payloadFormat</c> / <c>dataType</c> /
|
||||
/// <c>qos</c> values, and for a <b>wildcard</b> tag topic (a tag bound to <c>+</c> / <c>#</c>
|
||||
/// would receive values from many topics — ambiguous, and almost never what the operator meant).
|
||||
/// Empty when the blob is clean or is not an equipment-tag TagConfig object. Never throws.
|
||||
/// </summary>
|
||||
/// <param name="reference">The equipment tag's TagConfig JSON.</param>
|
||||
/// <returns>The warnings; empty when clean.</returns>
|
||||
public static IReadOnlyList<string> Inspect(string reference)
|
||||
{
|
||||
var warnings = new List<string>();
|
||||
if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
|
||||
try
|
||||
{
|
||||
using var doc = JsonDocument.Parse(reference);
|
||||
var root = doc.RootElement;
|
||||
if (root.ValueKind != JsonValueKind.Object)
|
||||
{
|
||||
warnings.Add("Mqtt TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
|
||||
return warnings;
|
||||
}
|
||||
foreach (var w in new[]
|
||||
{
|
||||
TagConfigJson.DescribeInvalidEnum<MqttPayloadFormat>(root, "payloadFormat"),
|
||||
TagConfigJson.DescribeInvalidEnum<DriverDataType>(root, "dataType"),
|
||||
DescribeInvalidQos(root),
|
||||
})
|
||||
{
|
||||
if (w is not null) warnings.Add(w);
|
||||
}
|
||||
var topic = ReadString(root, "topic");
|
||||
if (topic.IndexOfAny(TopicWildcards) >= 0)
|
||||
{
|
||||
warnings.Add(
|
||||
$"value '{topic}' for 'topic' contains an MQTT wildcard (+ or #); a tag's topic must be " +
|
||||
"concrete, or the tag will be fed by every matching topic.");
|
||||
}
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
warnings.Add("Mqtt TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
|
||||
}
|
||||
return warnings;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Strict <c>qos</c> read, mirroring <see cref="TagConfigJson.TryReadEnumStrict{TEnum}"/>'s
|
||||
/// absent / valid / present-but-invalid split: absent ⇒ <see langword="null"/> (the driver-level
|
||||
/// <see cref="MqttPlainOptions.DefaultQos"/> wins); a JSON integer in 0–2 ⇒ that value; anything
|
||||
/// else present (non-number, non-integer, or out of range) ⇒ the read FAILS.
|
||||
/// </summary>
|
||||
/// <param name="o">The TagConfig root object.</param>
|
||||
/// <param name="qos">The parsed QoS, or <see langword="null"/> when the field is absent.</param>
|
||||
/// <returns><see langword="false"/> only when <c>qos</c> is present but not a legal MQTT QoS.</returns>
|
||||
private static bool TryReadQosStrict(JsonElement o, out int? qos)
|
||||
{
|
||||
qos = null;
|
||||
if (!o.TryGetProperty("qos", out var e)) return true; // absent
|
||||
if (e.ValueKind != JsonValueKind.Number || !e.TryGetInt32(out var v)) return false;
|
||||
if (v is < 0 or > 2) return false;
|
||||
qos = v;
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A human-readable warning for a present-but-invalid <c>qos</c> field, or <see langword="null"/>
|
||||
/// when it is absent or valid — the <c>qos</c> counterpart of
|
||||
/// <see cref="TagConfigJson.DescribeInvalidEnum{TEnum}"/>.
|
||||
/// </summary>
|
||||
/// <param name="o">The TagConfig root object.</param>
|
||||
/// <returns>The warning text, or <see langword="null"/>.</returns>
|
||||
private static string? DescribeInvalidQos(JsonElement o)
|
||||
{
|
||||
if (!o.TryGetProperty("qos", out var e)) return null;
|
||||
if (e.ValueKind == JsonValueKind.Number && e.TryGetInt32(out var v) && v is >= 0 and <= 2) return null;
|
||||
return $"value '{e.GetRawText()}' for 'qos' is not a valid MQTT QoS; valid: 0, 1, 2";
|
||||
}
|
||||
|
||||
private static string ReadString(JsonElement o, string name)
|
||||
=> o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.String
|
||||
? e.GetString() ?? ""
|
||||
: "";
|
||||
|
||||
private static bool ReadBoolOrDefault(JsonElement o, string name, bool defaultValue)
|
||||
=> o.TryGetProperty(name, out var e) && e.ValueKind is JsonValueKind.True or JsonValueKind.False
|
||||
? e.GetBoolean()
|
||||
: defaultValue;
|
||||
}
|
||||
@@ -0,0 +1,261 @@
|
||||
// =====================================================================================================
|
||||
// VENDORED THIRD-PARTY FILE — DO NOT EDIT. Re-vendor from upstream instead (recipe below).
|
||||
//
|
||||
// Upstream project Eclipse Tahu — the Sparkplug B reference implementation
|
||||
// Upstream repo https://github.com/eclipse-tahu/tahu
|
||||
// Upstream path sparkplug_b/sparkplug_b.proto
|
||||
// Pinned commit 5736e404889d4b95910613040a99ba79589ffb13 (master, 2023-11-06)
|
||||
// Permalink https://raw.githubusercontent.com/eclipse-tahu/tahu/5736e404889d4b95910613040a99ba79589ffb13/sparkplug_b/sparkplug_b.proto
|
||||
// git blob SHA-1 bf72ab5f09a333afabcb40fd45362ffbb0c8c5bd (matches the tree entry at that commit)
|
||||
// content SHA-256 4432c5c483b7fb9732d0594c98a2e97dca5e517e39c5374a8b918d837f0b4a19 (8330 bytes)
|
||||
// last modified 46f25e79f34234e6145d11108660dfd9133ae50d (2022-05-16, template_ref comment fix)
|
||||
// License Eclipse Public License 2.0 (EPL-2.0) — https://www.eclipse.org/legal/epl-2.0/
|
||||
// Copyright (c) Cirrus Link Solutions and others. The upstream copyright + SPDX
|
||||
// header is preserved verbatim as the first lines of the copied body below.
|
||||
//
|
||||
// Everything from line 38 down ("// * Copyright (c) 2015, 2018 Cirrus Link Solutions…") is a
|
||||
// BYTE-FOR-BYTE copy of the upstream file. Only these header lines were added. To re-verify:
|
||||
//
|
||||
// curl -sSL <permalink above> -o /tmp/upstream.proto
|
||||
// tail -n +38 src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts/Protos/sparkplug_b.proto > /tmp/vendored.proto
|
||||
// diff /tmp/upstream.proto /tmp/vendored.proto && shasum -a 256 /tmp/vendored.proto
|
||||
//
|
||||
// WHY VENDORED rather than a NuGet package: SparkplugNet is the only .NET Sparkplug library and it is
|
||||
// stale (1.3.10, 2024-07-02), transitively pins MQTTnet 4.3.6.1152 against this repo's MQTTnet 5.2.0,
|
||||
// and ships net6.0/net8.0 only — no net10.0 TFM. So the schema is vendored and decoded directly with
|
||||
// Google.Protobuf, over the same single MQTTnet-5 client the plain-MQTT path already uses.
|
||||
//
|
||||
// WHY THE proto2 FILE and not the sibling sparkplug_b_c_sharp.proto that upstream also ships: this is
|
||||
// the NORMATIVE Sparkplug B schema (the C# sibling is a lossy proto3 restatement that drops explicit
|
||||
// presence and rewrites the `extensions` ranges as `google.protobuf.Any`). protoc from Grpc.Tools
|
||||
// generates valid C# from proto2, and the generated namespace is identical (Org.Eclipse.Tahu.Protobuf,
|
||||
// PascalCased from `package org.eclipse.tahu.protobuf` — there is no `option csharp_namespace`). Keeping
|
||||
// proto2 buys explicit presence — Has{Name,Alias,Seq,IsNull,Datatype} — which the decoder needs to tell
|
||||
// "field absent" from "field present and zero" (an NBIRTH legitimately carries seq = 0, and a DATA
|
||||
// metric legitimately omits `name` and carries only `alias`).
|
||||
// =====================================================================================================
|
||||
|
||||
// * Copyright (c) 2015, 2018 Cirrus Link Solutions and others
|
||||
// *
|
||||
// * This program and the accompanying materials are made available under the
|
||||
// * terms of the Eclipse Public License 2.0 which is available at
|
||||
// * http://www.eclipse.org/legal/epl-2.0.
|
||||
// *
|
||||
// * SPDX-License-Identifier: EPL-2.0
|
||||
// *
|
||||
// * Contributors:
|
||||
// * Cirrus Link Solutions - initial implementation
|
||||
|
||||
//
|
||||
// To compile:
|
||||
// cd client_libraries/java
|
||||
// protoc --proto_path=../../ --java_out=src/main/java ../../sparkplug_b.proto
|
||||
//
|
||||
|
||||
syntax = "proto2";
|
||||
|
||||
package org.eclipse.tahu.protobuf;
|
||||
|
||||
option java_package = "org.eclipse.tahu.protobuf";
|
||||
option java_outer_classname = "SparkplugBProto";
|
||||
|
||||
enum DataType {
|
||||
// Indexes of Data Types
|
||||
|
||||
// Unknown placeholder for future expansion.
|
||||
Unknown = 0;
|
||||
|
||||
// Basic Types
|
||||
Int8 = 1;
|
||||
Int16 = 2;
|
||||
Int32 = 3;
|
||||
Int64 = 4;
|
||||
UInt8 = 5;
|
||||
UInt16 = 6;
|
||||
UInt32 = 7;
|
||||
UInt64 = 8;
|
||||
Float = 9;
|
||||
Double = 10;
|
||||
Boolean = 11;
|
||||
String = 12;
|
||||
DateTime = 13;
|
||||
Text = 14;
|
||||
|
||||
// Additional Metric Types
|
||||
UUID = 15;
|
||||
DataSet = 16;
|
||||
Bytes = 17;
|
||||
File = 18;
|
||||
Template = 19;
|
||||
|
||||
// Additional PropertyValue Types
|
||||
PropertySet = 20;
|
||||
PropertySetList = 21;
|
||||
|
||||
// Array Types
|
||||
Int8Array = 22;
|
||||
Int16Array = 23;
|
||||
Int32Array = 24;
|
||||
Int64Array = 25;
|
||||
UInt8Array = 26;
|
||||
UInt16Array = 27;
|
||||
UInt32Array = 28;
|
||||
UInt64Array = 29;
|
||||
FloatArray = 30;
|
||||
DoubleArray = 31;
|
||||
BooleanArray = 32;
|
||||
StringArray = 33;
|
||||
DateTimeArray = 34;
|
||||
}
|
||||
|
||||
message Payload {
|
||||
|
||||
message Template {
|
||||
|
||||
message Parameter {
|
||||
optional string name = 1;
|
||||
optional uint32 type = 2;
|
||||
|
||||
oneof value {
|
||||
uint32 int_value = 3;
|
||||
uint64 long_value = 4;
|
||||
float float_value = 5;
|
||||
double double_value = 6;
|
||||
bool boolean_value = 7;
|
||||
string string_value = 8;
|
||||
ParameterValueExtension extension_value = 9;
|
||||
}
|
||||
|
||||
message ParameterValueExtension {
|
||||
extensions 1 to max;
|
||||
}
|
||||
}
|
||||
|
||||
optional string version = 1; // The version of the Template to prevent mismatches
|
||||
repeated Metric metrics = 2; // Each metric includes a name, datatype, and optionally a value
|
||||
repeated Parameter parameters = 3;
|
||||
optional string template_ref = 4; // MUST be a reference to a template definition if this is an instance (i.e. the name of the template definition) - MUST be omitted for template definitions
|
||||
optional bool is_definition = 5;
|
||||
extensions 6 to max;
|
||||
}
|
||||
|
||||
message DataSet {
|
||||
|
||||
message DataSetValue {
|
||||
|
||||
oneof value {
|
||||
uint32 int_value = 1;
|
||||
uint64 long_value = 2;
|
||||
float float_value = 3;
|
||||
double double_value = 4;
|
||||
bool boolean_value = 5;
|
||||
string string_value = 6;
|
||||
DataSetValueExtension extension_value = 7;
|
||||
}
|
||||
|
||||
message DataSetValueExtension {
|
||||
extensions 1 to max;
|
||||
}
|
||||
}
|
||||
|
||||
message Row {
|
||||
repeated DataSetValue elements = 1;
|
||||
extensions 2 to max; // For third party extensions
|
||||
}
|
||||
|
||||
optional uint64 num_of_columns = 1;
|
||||
repeated string columns = 2;
|
||||
repeated uint32 types = 3;
|
||||
repeated Row rows = 4;
|
||||
extensions 5 to max; // For third party extensions
|
||||
}
|
||||
|
||||
message PropertyValue {
|
||||
|
||||
optional uint32 type = 1;
|
||||
optional bool is_null = 2;
|
||||
|
||||
oneof value {
|
||||
uint32 int_value = 3;
|
||||
uint64 long_value = 4;
|
||||
float float_value = 5;
|
||||
double double_value = 6;
|
||||
bool boolean_value = 7;
|
||||
string string_value = 8;
|
||||
PropertySet propertyset_value = 9;
|
||||
PropertySetList propertysets_value = 10; // List of Property Values
|
||||
PropertyValueExtension extension_value = 11;
|
||||
}
|
||||
|
||||
message PropertyValueExtension {
|
||||
extensions 1 to max;
|
||||
}
|
||||
}
|
||||
|
||||
message PropertySet {
|
||||
repeated string keys = 1; // Names of the properties
|
||||
repeated PropertyValue values = 2;
|
||||
extensions 3 to max;
|
||||
}
|
||||
|
||||
message PropertySetList {
|
||||
repeated PropertySet propertyset = 1;
|
||||
extensions 2 to max;
|
||||
}
|
||||
|
||||
message MetaData {
|
||||
// Bytes specific metadata
|
||||
optional bool is_multi_part = 1;
|
||||
|
||||
// General metadata
|
||||
optional string content_type = 2; // Content/Media type
|
||||
optional uint64 size = 3; // File size, String size, Multi-part size, etc
|
||||
optional uint64 seq = 4; // Sequence number for multi-part messages
|
||||
|
||||
// File metadata
|
||||
optional string file_name = 5; // File name
|
||||
optional string file_type = 6; // File type (i.e. xml, json, txt, cpp, etc)
|
||||
optional string md5 = 7; // md5 of data
|
||||
|
||||
// Catchalls and future expansion
|
||||
optional string description = 8; // Could be anything such as json or xml of custom properties
|
||||
extensions 9 to max;
|
||||
}
|
||||
|
||||
message Metric {
|
||||
|
||||
optional string name = 1; // Metric name - should only be included on birth
|
||||
optional uint64 alias = 2; // Metric alias - tied to name on birth and included in all later DATA messages
|
||||
optional uint64 timestamp = 3; // Timestamp associated with data acquisition time
|
||||
optional uint32 datatype = 4; // DataType of the metric/tag value
|
||||
optional bool is_historical = 5; // If this is historical data and should not update real time tag
|
||||
optional bool is_transient = 6; // Tells consuming clients such as MQTT Engine to not store this as a tag
|
||||
optional bool is_null = 7; // If this is null - explicitly say so rather than using -1, false, etc for some datatypes.
|
||||
optional MetaData metadata = 8; // Metadata for the payload
|
||||
optional PropertySet properties = 9;
|
||||
|
||||
oneof value {
|
||||
uint32 int_value = 10;
|
||||
uint64 long_value = 11;
|
||||
float float_value = 12;
|
||||
double double_value = 13;
|
||||
bool boolean_value = 14;
|
||||
string string_value = 15;
|
||||
bytes bytes_value = 16; // Bytes, File
|
||||
DataSet dataset_value = 17;
|
||||
Template template_value = 18;
|
||||
MetricValueExtension extension_value = 19;
|
||||
}
|
||||
|
||||
message MetricValueExtension {
|
||||
extensions 1 to max;
|
||||
}
|
||||
}
|
||||
|
||||
optional uint64 timestamp = 1; // Timestamp at message sending time
|
||||
repeated Metric metrics = 2; // Repeated forever - no limit in Google Protobufs
|
||||
optional uint64 seq = 3; // Sequence number
|
||||
optional string uuid = 4; // UUID to track message type in terms of schema definitions
|
||||
optional bytes body = 5; // To optionally bypass the whole definition above
|
||||
extensions 6 to max; // For third party extensions
|
||||
}
|
||||
@@ -0,0 +1,139 @@
|
||||
// `SparkplugDataType` is an ALIAS for the vendored proto's generated `Org.Eclipse.Tahu.Protobuf.DataType`
|
||||
// enum, not a second, hand-maintained enum. See the remarks on `SparkplugDataTypeExtensions` below for
|
||||
// the reasoning; the short version is that a duplicate enum is a drift hazard this repo has a documented
|
||||
// systemic bug class around (see CLAUDE.md "Driver enum-serialization bug"), and `Payload.Types.Metric`'s
|
||||
// wire-level `Datatype` field is a raw `uint32` anyway — nothing structurally forces a second CLR enum to
|
||||
// exist, so the lowest-risk shape is for `SparkplugDataType` to be the exact same type as the generated
|
||||
// one, not a value-compatible lookalike that some cast has to bridge.
|
||||
global using SparkplugDataType = Org.Eclipse.Tahu.Protobuf.DataType;
|
||||
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// Maps a Sparkplug B metric <see cref="SparkplugDataType"/> (the vendored Eclipse Tahu proto's
|
||||
/// generated <c>Org.Eclipse.Tahu.Protobuf.DataType</c> enum — see the <c>global using</c> alias
|
||||
/// above) to a driver-agnostic <see cref="DriverDataType"/>, per design doc §3.5.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Why an alias, not a duplicate enum.</b> The obvious "clean seam" shape is a fresh
|
||||
/// <c>Driver.Mqtt.Contracts</c>-owned enum with its own <c>ToDriverDataType()</c> — but that
|
||||
/// creates a second definition of the same 35-member vocabulary that has to be hand-kept in
|
||||
/// sync with whatever Eclipse Tahu's <c>sparkplug_b.proto</c> defines, which is exactly the
|
||||
/// enum-drift shape this repo already has a name for (CLAUDE.md's "Driver enum-serialization
|
||||
/// bug (AdminUI authoring)" — a systemic mismatch between two enums meant to describe the same
|
||||
/// thing). It also does not match how the decoder actually produces values: Sparkplug's
|
||||
/// <c>Metric.datatype</c> wire field is a raw <c>uint32</c> (see <c>sparkplug_b.proto</c> line
|
||||
/// 230 — <c>optional uint32 datatype = 4</c>), not the <c>DataType</c> enum type itself, so
|
||||
/// <c>SparkplugCodec</c> (Task 16) already casts the decoded value straight to the generated
|
||||
/// <c>Org.Eclipse.Tahu.Protobuf.DataType</c> (locally aliased there as <c>TahuDataType</c>).
|
||||
/// A second, hand-duplicated enum would force every downstream consumer (Tasks 18/19/20/21) to
|
||||
/// cast between two value-compatible-but-nominally-different enums to call this extension
|
||||
/// method — extra surface for exactly zero benefit, since both "enums" would need to enumerate
|
||||
/// the identical 35 members in the identical order to stay castable.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Making <see cref="SparkplugDataType"/> a <c>global using</c> alias for the generated type
|
||||
/// sidesteps all of that: there is no second definition to drift, by construction — the alias
|
||||
/// and the generated enum are the exact same CLR type. <see cref="ToDriverDataType"/> below is
|
||||
/// written as an extension on <see cref="SparkplugDataType"/> purely for call-site readability;
|
||||
/// it is equally callable as <c>someDecodedDatatype.ToDriverDataType()</c> against a plain
|
||||
/// <c>Org.Eclipse.Tahu.Protobuf.DataType</c> value with no cast, which is exactly the shape
|
||||
/// <c>SparkplugCodec</c>'s decoded metrics hand back.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Drift guard.</b> Because there is only one enum, <c>SparkplugDataTypeTests</c>'
|
||||
/// completeness test (<c>ToDriverDataType_HandlesEveryGeneratedDataTypeMember_...</c>) can
|
||||
/// enumerate <c>Enum.GetValues<SparkplugDataType>()</c> — which, being the alias, is
|
||||
/// literally the live generated member set — and assert every member is either mapped or on
|
||||
/// the explicit unsupported list below. If Eclipse Tahu's proto ever gains a member, that test
|
||||
/// picks it up automatically and fails until this map makes an explicit decision about it,
|
||||
/// rather than the new member silently falling through a duplicate-enum's stale default.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Per design §3.5: <c>Int8</c>/<c>UInt8</c> widen to <see cref="DriverDataType.Int16"/> /
|
||||
/// <see cref="DriverDataType.UInt16"/> (no OPC UA signed-byte distinction is needed and
|
||||
/// <see cref="DriverDataType"/> has no 8-bit members at all); <c>Float</c>/<c>Double</c> map to
|
||||
/// <see cref="DriverDataType.Float32"/> / <see cref="DriverDataType.Float64"/> — note there is
|
||||
/// no <c>DriverDataType.Double</c> member, only <c>Float64</c>; <c>Text</c>/<c>UUID</c>
|
||||
/// (generated as <c>Uuid</c> — protoc mangles the wire spelling, see
|
||||
/// <c>SparkplugProtoCodegenTests.DataTypeEnum_CSharpNamesAreProtocMangled_NotTheProtoSpelling</c>)
|
||||
/// /<c>Bytes</c>/<c>File</c> all fall back to <see cref="DriverDataType.String"/> (v1 base64/raw
|
||||
/// fallback for Bytes/File, per design); every <c>*Array</c> variant maps to its scalar element
|
||||
/// type (<see cref="IsSparkplugArray"/> carries the "and it's an array" bit separately, since
|
||||
/// <see cref="DriverDataType"/> itself has no array concept — that lives at the OPC UA
|
||||
/// ValueRank/ArrayDimensions layer the address-space builder owns). <c>DataSet</c>/
|
||||
/// <c>Template</c>/<c>PropertySet</c>/<c>PropertySetList</c>/<c>Unknown</c> are unsupported in
|
||||
/// v1 and map to <see langword="null"/> — deliberately, not a guessed
|
||||
/// <see cref="DriverDataType.String"/>, so a caller has to make an explicit skip-or-warn
|
||||
/// decision (unlike Galaxy's <c>DataTypeMap</c>, which silently defaults unknown codes to
|
||||
/// <c>String</c> for legacy wire-compatibility reasons that do not apply here).
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class SparkplugDataTypeExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Maps a Sparkplug metric datatype to the equivalent <see cref="DriverDataType"/>, or
|
||||
/// <see langword="null"/> if the type is unsupported in v1 (<c>DataSet</c>, <c>Template</c>,
|
||||
/// <c>PropertySet</c>, <c>PropertySetList</c>, <c>Unknown</c>). Callers must treat
|
||||
/// <see langword="null"/> as an explicit "skip and warn", never coerce it to a guessed type.
|
||||
/// </summary>
|
||||
public static DriverDataType? ToDriverDataType(this SparkplugDataType dataType) => dataType switch
|
||||
{
|
||||
SparkplugDataType.Int8 => DriverDataType.Int16,
|
||||
SparkplugDataType.Int16 => DriverDataType.Int16,
|
||||
SparkplugDataType.Int32 => DriverDataType.Int32,
|
||||
SparkplugDataType.Int64 => DriverDataType.Int64,
|
||||
SparkplugDataType.Uint8 => DriverDataType.UInt16,
|
||||
SparkplugDataType.Uint16 => DriverDataType.UInt16,
|
||||
SparkplugDataType.Uint32 => DriverDataType.UInt32,
|
||||
SparkplugDataType.Uint64 => DriverDataType.UInt64,
|
||||
SparkplugDataType.Float => DriverDataType.Float32,
|
||||
SparkplugDataType.Double => DriverDataType.Float64,
|
||||
SparkplugDataType.Boolean => DriverDataType.Boolean,
|
||||
SparkplugDataType.String => DriverDataType.String,
|
||||
SparkplugDataType.DateTime => DriverDataType.DateTime,
|
||||
SparkplugDataType.Text => DriverDataType.String,
|
||||
SparkplugDataType.Uuid => DriverDataType.String,
|
||||
SparkplugDataType.Bytes => DriverDataType.String,
|
||||
SparkplugDataType.File => DriverDataType.String,
|
||||
|
||||
SparkplugDataType.Int8Array => DriverDataType.Int16,
|
||||
SparkplugDataType.Int16Array => DriverDataType.Int16,
|
||||
SparkplugDataType.Int32Array => DriverDataType.Int32,
|
||||
SparkplugDataType.Int64Array => DriverDataType.Int64,
|
||||
SparkplugDataType.Uint8Array => DriverDataType.UInt16,
|
||||
SparkplugDataType.Uint16Array => DriverDataType.UInt16,
|
||||
SparkplugDataType.Uint32Array => DriverDataType.UInt32,
|
||||
SparkplugDataType.Uint64Array => DriverDataType.UInt64,
|
||||
SparkplugDataType.FloatArray => DriverDataType.Float32,
|
||||
SparkplugDataType.DoubleArray => DriverDataType.Float64,
|
||||
SparkplugDataType.BooleanArray => DriverDataType.Boolean,
|
||||
SparkplugDataType.StringArray => DriverDataType.String,
|
||||
SparkplugDataType.DateTimeArray => DriverDataType.DateTime,
|
||||
|
||||
// Unsupported v1 (design §3.5): DataSet/Template are deferred scope; PropertySet/
|
||||
// PropertySetList are PropertyValue-only metadata types that never legitimately appear as a
|
||||
// Metric's own datatype; Unknown is the proto's explicit "placeholder for future expansion"
|
||||
// (index 0). All five fall through here deliberately rather than being listed with a fake
|
||||
// mapping.
|
||||
_ => null,
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// Whether <paramref name="dataType"/> is one of the 13 <c>*Array</c> variants. Combine with
|
||||
/// <see cref="ToDriverDataType"/> (which already returns the *element* type for an array
|
||||
/// variant) to build an OPC UA ValueRank=1 array node per design §3.5.
|
||||
/// </summary>
|
||||
public static bool IsSparkplugArray(this SparkplugDataType dataType) => dataType switch
|
||||
{
|
||||
SparkplugDataType.Int8Array or SparkplugDataType.Int16Array or SparkplugDataType.Int32Array
|
||||
or SparkplugDataType.Int64Array or SparkplugDataType.Uint8Array or SparkplugDataType.Uint16Array
|
||||
or SparkplugDataType.Uint32Array or SparkplugDataType.Uint64Array or SparkplugDataType.FloatArray
|
||||
or SparkplugDataType.DoubleArray or SparkplugDataType.BooleanArray or SparkplugDataType.StringArray
|
||||
or SparkplugDataType.DateTimeArray => true,
|
||||
_ => false,
|
||||
};
|
||||
}
|
||||
+36
@@ -0,0 +1,36 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<Nullable>enable</Nullable>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
</PropertyGroup>
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
|
||||
</ItemGroup>
|
||||
|
||||
<!-- Sparkplug B (P2): the vendored Eclipse Tahu schema is compiled here, in the one assembly all
|
||||
four MQTT projects reference. Message-only codegen (GrpcServices="None") — Sparkplug rides MQTT,
|
||||
there is no gRPC service, so no Grpc.Core.Api runtime reference is needed (Commons, this repo's
|
||||
other locally-compiled proto, takes one only because it generates service stubs).
|
||||
|
||||
Google.Protobuf is a SERIALIZATION dependency, not a transport one, so .Contracts stays
|
||||
transport-free: it still has no MQTTnet reference (dropped in Task 1) and Google.Protobuf's own
|
||||
graph is framework-only. Grpc.Tools is build-time (PrivateAssets=all) and flows to no consumer.
|
||||
|
||||
Build-platform note (inherited, not new): Grpc.Tools' bundled linux_arm64 protoc segfaults
|
||||
(exit 139) under Apple-Silicon Docker, which is why docker-dev/Dockerfile pins its build stage
|
||||
to the linux/amd64 platform. That pin already exists for the Commons proto; this project adds
|
||||
a second .proto to the same already-pinned build, not a new constraint. -->
|
||||
<ItemGroup>
|
||||
<PackageReference Include="Google.Protobuf"/>
|
||||
<PackageReference Include="Grpc.Tools">
|
||||
<PrivateAssets>all</PrivateAssets>
|
||||
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
|
||||
</PackageReference>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<Protobuf Include="Protos\sparkplug_b.proto" GrpcServices="None"/>
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
@@ -0,0 +1,63 @@
|
||||
using System.Collections.Concurrent;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// Thread-safe last-observed-value store backing <see cref="IReadable"/> for MQTT/Sparkplug B.
|
||||
/// MQTT is a subscribe-first protocol — the driver holds one live broker connection and values
|
||||
/// arrive pushed, not polled. But the OPC UA server still issues polled <c>IReadable.ReadAsync</c>
|
||||
/// batches, so this cache is the bridge: the subscription path (message handler) calls
|
||||
/// <see cref="Update"/> with the newest observed value per reference, and the read path serves
|
||||
/// the most recent one via <see cref="Read"/>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Keyed by <c>RawPath</c> — the v3 driver-reference identity (see
|
||||
/// <c>EquipmentTagRefResolver<TDef></c> and <see cref="MqttTagDefinition.Name"/>,
|
||||
/// which <b>is</b> the RawPath) — never a topic/JSON-path-derived key. The parameter is
|
||||
/// therefore named <c>rawPath</c> throughout rather than "topic" or "key" to keep that identity
|
||||
/// fact visible at every call site.
|
||||
/// </remarks>
|
||||
public sealed class LastValueCache
|
||||
{
|
||||
// OPC UA BadWaitingForInitialData (0x80320000) — the repo-wide convention for "no value has
|
||||
// been observed yet" (mirrored by CalculationDriver before its first evaluation,
|
||||
// VirtualTagEngine for a freshly-materialised node, and OtOpcUaNodeManager /
|
||||
// AddressSpaceApplier for a just-deployed variable). MQTT is subscribe-first, so an unseen
|
||||
// RawPath is in exactly that state until its first publish arrives. Deliberately NOT
|
||||
// GoodNoData — that code is reserved (see NullHistorianDataSource, OtOpcUaNodeManager
|
||||
// HistoryRead paths) for "the historian window held no samples", a different question from
|
||||
// "has this live reference ever been observed".
|
||||
private const uint BadWaitingForInitialData = 0x80320000u;
|
||||
|
||||
private readonly ConcurrentDictionary<string, DataValueSnapshot> _values = new();
|
||||
|
||||
/// <summary>
|
||||
/// Record the newest observed value for <paramref name="rawPath"/>. Called from the MQTT
|
||||
/// subscription/message-handling path. A <c>null</c> or empty <paramref name="rawPath"/>
|
||||
/// is a no-op — never throws.
|
||||
/// </summary>
|
||||
/// <param name="rawPath">The RawPath identifying the tag.</param>
|
||||
/// <param name="snapshot">The newest observed value/quality/timestamps for that tag.</param>
|
||||
public void Update(string rawPath, DataValueSnapshot snapshot)
|
||||
{
|
||||
if (string.IsNullOrEmpty(rawPath)) return;
|
||||
_values[rawPath] = snapshot;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Read the last observed value for <paramref name="rawPath"/>. Never throws: a
|
||||
/// <c>null</c>/empty <paramref name="rawPath"/> or a RawPath never observed both return a
|
||||
/// <see cref="BadWaitingForInitialData"/> snapshot rather than an exception, so a batch read
|
||||
/// covering many references degrades per-reference instead of failing the whole call.
|
||||
/// </summary>
|
||||
/// <param name="rawPath">The RawPath identifying the tag.</param>
|
||||
/// <returns>The last observed snapshot, or a BadWaitingForInitialData snapshot if none has been observed.</returns>
|
||||
public DataValueSnapshot Read(string rawPath)
|
||||
{
|
||||
if (!string.IsNullOrEmpty(rawPath) && _values.TryGetValue(rawPath, out var snapshot))
|
||||
return snapshot;
|
||||
|
||||
return new DataValueSnapshot(null, BadWaitingForInitialData, null, DateTime.UtcNow);
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,84 @@
|
||||
using System.Text.Json;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Hosting;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// Registers the MQTT / Sparkplug B driver with the <see cref="DriverFactoryRegistry"/>. The
|
||||
/// Host's <c>DriverFactoryBootstrap</c> calls <see cref="Register"/> once at startup; the
|
||||
/// driver-instance bootstrapper then materialises <c>DriverInstance</c> rows of type
|
||||
/// <see cref="DriverTypeNames.Mqtt"/> into live <see cref="MqttDriver"/> instances.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Direct deserialization, no intermediate DTO.</b> The <c>DriverConfig</c> blob binds
|
||||
/// straight onto <see cref="MqttDriverOptions"/> — the same shape
|
||||
/// <see cref="MqttDriverProbe"/>, <c>MqttDriverBrowser</c> and
|
||||
/// <see cref="MqttDriver.ReinitializeAsync"/> already bind, and the shape the options record
|
||||
/// was designed for (every knob carries its own default, and <c>rawTags</c> is a plain
|
||||
/// <see cref="RawTagEntry"/> list needing no translation). Mirrors
|
||||
/// <c>OpcUaClientDriverFactoryExtensions</c>. <c>ModbusDriverFactoryExtensions</c>' separate
|
||||
/// DTO exists to service a legacy nullable-everything blob plus string→enum parsing this
|
||||
/// driver does with a converter instead; copying it here would add a <i>fourth</i> parse
|
||||
/// shape for one config, which is precisely the divergence
|
||||
/// <see cref="MqttJson.Options"/> exists to prevent.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Connection-free.</b> <see cref="CreateInstance"/> parses and constructs only — the
|
||||
/// <see cref="MqttDriver"/> constructor touches no network, and the registry contract
|
||||
/// forbids the factory from calling <c>InitializeAsync</c> itself (the driver host owns the
|
||||
/// retry semantics).
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class MqttDriverFactoryExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Driver type name — matches <c>DriverInstance.DriverType</c> values. Sourced from
|
||||
/// <see cref="DriverTypeNames.Mqtt"/> so the registration key can never drift from the
|
||||
/// constant the dispatch maps, the probe and the browser reference.
|
||||
/// </summary>
|
||||
public const string DriverTypeName = DriverTypeNames.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// Register the MQTT factory with the driver registry. The optional
|
||||
/// <paramref name="loggerFactory"/> is captured at registration time and used to construct an
|
||||
/// <see cref="ILogger{MqttDriver}"/> per driver instance — without it the driver runs with no
|
||||
/// logger (standalone/test callers stay unchanged).
|
||||
/// </summary>
|
||||
/// <param name="registry">The driver factory registry to register with.</param>
|
||||
/// <param name="loggerFactory">Optional logger factory used to create per-instance loggers.</param>
|
||||
public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(registry);
|
||||
registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory));
|
||||
}
|
||||
|
||||
/// <summary>Public for the Server-side bootstrapper + test consumers.</summary>
|
||||
/// <param name="driverInstanceId">Stable logical id of the driver instance.</param>
|
||||
/// <param name="driverConfigJson">The <c>DriverConfig</c> JSON blob for the instance.</param>
|
||||
/// <param name="loggerFactory">Optional logger factory for the per-instance logger.</param>
|
||||
/// <returns>A configured, not-yet-connected <see cref="MqttDriver"/>.</returns>
|
||||
/// <exception cref="ArgumentException">
|
||||
/// <paramref name="driverInstanceId"/> or <paramref name="driverConfigJson"/> is blank.
|
||||
/// </exception>
|
||||
/// <exception cref="InvalidOperationException">The config blob deserialised to <c>null</c>.</exception>
|
||||
/// <exception cref="JsonException">The config blob is not valid JSON for the options shape.</exception>
|
||||
public static MqttDriver CreateInstance(
|
||||
string driverInstanceId,
|
||||
string driverConfigJson,
|
||||
ILoggerFactory? loggerFactory = null)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);
|
||||
|
||||
// MqttJson.Options — the one shared instance (see its remarks). A local copy here is the
|
||||
// repo's documented systemic enum bug in the making.
|
||||
var options = JsonSerializer.Deserialize<MqttDriverOptions>(driverConfigJson, MqttJson.Options)
|
||||
?? throw new InvalidOperationException(
|
||||
$"MQTT driver config for '{driverInstanceId}' deserialised to null");
|
||||
|
||||
return new MqttDriver(options, driverInstanceId, loggerFactory?.CreateLogger<MqttDriver>());
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,226 @@
|
||||
using System.Diagnostics;
|
||||
using System.Net.Sockets;
|
||||
using System.Security.Authentication;
|
||||
using System.Text.Json;
|
||||
using Microsoft.Extensions.Logging.Abstractions;
|
||||
using MQTTnet;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||||
|
||||
/// <summary>
|
||||
/// CONNECT-handshake probe for the <see cref="MqttDriverOptions"/>-shaped driver config.
|
||||
/// Opens a bounded MQTT CONNECT against the configured broker; a CONNACK-accepted response
|
||||
/// (<c>MqttClientConnectResultCode.Success</c>) is the "device is answering" proof (green +
|
||||
/// latency). Refused/TLS/auth/timeout failures each surface a targeted message. Mirrors
|
||||
/// <c>ModbusDriverProbe</c>'s shape.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Reuses <see cref="MqttConnection.BuildClientOptions"/></b> for the connect (TLS,
|
||||
/// CA-pin, credentials, protocol-version mapping) rather than hand-rolling a second
|
||||
/// connect path — a duplicate would be a security divergence. A distinct client-id suffix
|
||||
/// (see <see cref="ProbeClientIdPrefix"/>) keeps a probe from colliding with the driver's
|
||||
/// own session: an MQTT broker disconnects an existing client when a new one CONNECTs
|
||||
/// with the same client id, so a probe that reused the driver's id would knock the
|
||||
/// running driver offline every time an operator clicked "Test connect".
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>A broker-rejected CONNACK is not a thrown exception.</b> Live-probed against
|
||||
/// MQTTnet 5.2.0.1603: <c>IMqttClient.ConnectAsync</c> returns a
|
||||
/// <c>MqttClientConnectResult</c> whose <c>ResultCode</c> carries the broker's CONNACK
|
||||
/// reason (e.g. <c>NotAuthorized</c>, <c>BadUserNameOrPassword</c>) — it does
|
||||
/// <b>not</b> throw for a rejected CONNACK. Only transport-level failures throw, and
|
||||
/// their shape varies by where the failure occurs: a closed/refused port throws
|
||||
/// <c>MqttCommunicationException</c> wrapping a <see cref="SocketException"/>; an
|
||||
/// untrusted broker certificate throws <c>MqttCommunicationException</c> wrapping an
|
||||
/// <see cref="AuthenticationException"/>; a broker that accepts the TCP handshake and
|
||||
/// then never answers CONNACK throws either <c>MqttConnectingFailedException</c>
|
||||
/// (wrapping "Connection closed") or a bare <see cref="OperationCanceledException"/>
|
||||
/// ("MQTT connect canceled"), inconsistently, depending on whether MQTTnet's own
|
||||
/// internal <c>Timeout</c> or the deadline token wins the race. Consequently this probe —
|
||||
/// like <see cref="MqttConnection.Classify"/> — never switches on exception type to
|
||||
/// detect a timeout; it checks the deadline token itself, which is authoritative
|
||||
/// regardless of which exception shape MQTTnet happened to throw.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class MqttDriverProbe : IDriverProbe
|
||||
{
|
||||
/// <summary>
|
||||
/// Marks the transient probe identity in the broker's client-id/session logs — mirrors the
|
||||
/// browser's own <c>-browse-{guid8}</c> suffix so the two transient sessions are
|
||||
/// distinguishable in broker-side logs, and so a probe can never collide with (and knock
|
||||
/// offline) the driver's own live session.
|
||||
/// </summary>
|
||||
internal const string ProbeClientIdPrefix = "-probe-";
|
||||
|
||||
/// <inheritdoc />
|
||||
public string DriverType => DriverTypeNames.Mqtt;
|
||||
|
||||
/// <inheritdoc />
|
||||
public async Task<DriverProbeResult> ProbeAsync(string configJson, TimeSpan timeout, CancellationToken ct)
|
||||
{
|
||||
MqttDriverOptions? options;
|
||||
try
|
||||
{
|
||||
// MqttJson.Options — the one shared instance across factory / probe / driver / browser
|
||||
// (see its remarks): enums must round-trip by NAME or an AdminUI-authored config that
|
||||
// Test-connect accepts would fault the deployed driver.
|
||||
options = JsonSerializer.Deserialize<MqttDriverOptions>(configJson, MqttJson.Options);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
return new DriverProbeResult(false, $"Config JSON is invalid: {ex.Message}", null);
|
||||
}
|
||||
|
||||
if (options is null)
|
||||
{
|
||||
return new DriverProbeResult(false, "Config JSON deserialized to null.", null);
|
||||
}
|
||||
|
||||
if (string.IsNullOrWhiteSpace(options.Host) || options.Port is <= 0 or > 65535)
|
||||
{
|
||||
return new DriverProbeResult(false, "Config has no host/port to probe.", null);
|
||||
}
|
||||
|
||||
// Honour the config's own connectTimeoutSeconds (factory parity, mirrors
|
||||
// ModbusDriverProbe) — the caller's timeout is the fallback when the config omits it.
|
||||
var effectiveSeconds = options.ConnectTimeoutSeconds > 0
|
||||
? options.ConnectTimeoutSeconds
|
||||
: (int)Math.Ceiling(timeout.TotalSeconds);
|
||||
if (effectiveSeconds <= 0)
|
||||
{
|
||||
effectiveSeconds = 1;
|
||||
}
|
||||
|
||||
// Rebuild with the resolved timeout so BuildClientOptions' own WithTimeout(...) and this
|
||||
// method's deadline agree — both must expire at the same instant for the deadline check
|
||||
// below to be a reliable signal regardless of which of the two actually threw.
|
||||
var probeOptions = options with { ConnectTimeoutSeconds = effectiveSeconds };
|
||||
|
||||
MqttClientOptions clientOptions;
|
||||
try
|
||||
{
|
||||
clientOptions = MqttConnection.BuildClientOptions(
|
||||
probeOptions,
|
||||
ProbeClientIdPrefix + Guid.NewGuid().ToString("N")[..8],
|
||||
NullLogger.Instance);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
// Never let a configured Password reach the message — BuildClientOptions itself never
|
||||
// logs it, and no exception path through it can format credential values.
|
||||
return new DriverProbeResult(false, $"Config could not be used to build a connection: {ex.Message}", null);
|
||||
}
|
||||
|
||||
var target = $"{probeOptions.Host}:{probeOptions.Port}";
|
||||
var sw = Stopwatch.StartNew();
|
||||
|
||||
using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(effectiveSeconds));
|
||||
using var linked = CancellationTokenSource.CreateLinkedTokenSource(ct, deadline.Token);
|
||||
|
||||
using var client = new MqttClientFactory().CreateMqttClient();
|
||||
|
||||
MqttClientConnectResult result;
|
||||
try
|
||||
{
|
||||
result = await client.ConnectAsync(clientOptions, linked.Token).ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
return new DriverProbeResult(false, Classify(target, ex, ct, deadline, effectiveSeconds), null);
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
if (result.ResultCode != MqttClientConnectResultCode.Success)
|
||||
{
|
||||
return new DriverProbeResult(false, ClassifyRejectedConnack(target, result.ResultCode), null);
|
||||
}
|
||||
|
||||
sw.Stop();
|
||||
return new DriverProbeResult(true, "MQTT CONNECT OK", sw.Elapsed);
|
||||
}
|
||||
finally
|
||||
{
|
||||
await DisconnectBestEffortAsync(client, effectiveSeconds).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Maps a broker-rejected CONNACK (<see cref="MqttClientConnectResult.ResultCode"/> not
|
||||
/// <c>Success</c> — never an exception, see the type remarks) to a targeted, credential-free
|
||||
/// message.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Delegates to <see cref="MqttConnection.DescribeConnackRejection"/> so the "Test connect"
|
||||
/// button and the running driver report an identical rejection in identical words — they now
|
||||
/// both classify CONNACK, and disagreeing about it was the exact confusion the Task-13 live
|
||||
/// gate surfaced.
|
||||
/// </remarks>
|
||||
private static string ClassifyRejectedConnack(string target, MqttClientConnectResultCode code)
|
||||
=> MqttConnection.DescribeConnackRejection(target, code);
|
||||
|
||||
/// <summary>
|
||||
/// Classifies a thrown connect failure. Precedence mirrors
|
||||
/// <see cref="MqttConnection.Classify"/>: caller cancellation, then the deadline, then the
|
||||
/// exception's own shape — the deadline check is authoritative regardless of which exception
|
||||
/// type MQTTnet happened to throw (see the type remarks for why exception type alone is not
|
||||
/// reliable here).
|
||||
/// </summary>
|
||||
private static string Classify(
|
||||
string target,
|
||||
Exception ex,
|
||||
CancellationToken callerToken,
|
||||
CancellationTokenSource deadline,
|
||||
int effectiveSeconds)
|
||||
{
|
||||
if (callerToken.IsCancellationRequested)
|
||||
{
|
||||
return "Probe was cancelled.";
|
||||
}
|
||||
|
||||
if (deadline.IsCancellationRequested)
|
||||
{
|
||||
return $"Probe timed out after {effectiveSeconds}s.";
|
||||
}
|
||||
|
||||
// Walk to the root cause — MQTTnet wraps transport/TLS failures one or two levels deep.
|
||||
var root = ex;
|
||||
while (root.InnerException is not null)
|
||||
{
|
||||
root = root.InnerException;
|
||||
}
|
||||
|
||||
return root switch
|
||||
{
|
||||
SocketException se => $"Connect to {target} failed: {se.SocketErrorCode}",
|
||||
AuthenticationException => $"TLS handshake with {target} failed: {root.Message}",
|
||||
_ => $"Connect to {target} failed: {root.Message}",
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Best-effort teardown of a session this probe established. Failure here is not the
|
||||
/// probe's business — the CONNECT outcome already decided Ok/failure — and it must never be
|
||||
/// allowed to hang past the connect budget.
|
||||
/// </summary>
|
||||
private static async Task DisconnectBestEffortAsync(IMqttClient client, int timeoutSeconds)
|
||||
{
|
||||
if (!client.IsConnected)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using var disconnectDeadline = new CancellationTokenSource(TimeSpan.FromSeconds(timeoutSeconds));
|
||||
await client.DisconnectAsync(new MqttClientDisconnectOptions(), disconnectDeadline.Token)
|
||||
.ConfigureAwait(false);
|
||||
}
|
||||
catch
|
||||
{
|
||||
// Best-effort only.
|
||||
}
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,263 @@
|
||||
using System.Collections.Frozen;
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
using TahuDataType = Org.Eclipse.Tahu.Protobuf.DataType;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
|
||||
|
||||
/// <summary>
|
||||
/// One <c>(edgeNode, device)</c> scope's metric catalog, as declared by its most recent
|
||||
/// NBIRTH/DBIRTH: the alias→metric cache <b>and</b> the stable name→metric index, rebuilt wholesale
|
||||
/// on every birth. Design doc §3.6 invariants #1 and #2.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>The alias is a per-birth cache; the NAME is the binding key.</b> Sparkplug's alias
|
||||
/// mechanism exists to shrink DATA payloads — a BIRTH declares <c>name ↔ alias</c> and every
|
||||
/// subsequent DATA metric carries only the alias — and the alias is scoped to <i>that one
|
||||
/// birth</i>. After a rebirth an edge node is entirely free to point alias 5 at a different
|
||||
/// metric. So an authored tag binds by <see cref="SparkplugMetricBinding.Name"/>; the alias is
|
||||
/// only ever the lookup that turns an incoming DATA metric back into a name. Binding a tag to
|
||||
/// an alias instead means a rebirth silently starts routing Pressure into a Temperature tag —
|
||||
/// <b>good quality, plausible values, completely wrong</b>, and invisible unless something
|
||||
/// specifically reuses an alias across a rebirth.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b><see cref="RebuildFromBirth"/> REPLACES; it never merges or upserts.</b> The whole
|
||||
/// snapshot — both indexes — is built fresh and published in one assignment. An alias the new
|
||||
/// birth did not declare is gone, including when the new birth declares no metrics at all. This
|
||||
/// is the single behaviour the type exists to guarantee: a merge (or an "optimisation" that
|
||||
/// skips an empty birth) reintroduces exactly the stale-alias mis-route above.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Both indexes are replaced together, from the same birth.</b> They are deliberately held
|
||||
/// in one type rather than split across an "alias table" and a separate "birth cache": they are
|
||||
/// two views of one birth, and any seam between them is somewhere the two can be replaced
|
||||
/// independently and skew — an alias resolving through the new birth into a name catalog still
|
||||
/// holding the old one.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Thread-safety: an immutable snapshot swapped atomically</b>, the same discipline
|
||||
/// <c>MqttSubscriptionManager.AuthoredTable</c> uses and for the same reason — this is read on
|
||||
/// MQTTnet's shared dispatcher thread as messages arrive, and a reader must never see a
|
||||
/// half-rebuilt map. No lock is taken on any path.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Last values do not live here.</b> The running last-observed value per tag is
|
||||
/// <see cref="LastValueCache"/>'s, keyed by RawPath — the identity every publish in this driver
|
||||
/// is made under. A second copy keyed by metric name would be a duplicate source of truth with
|
||||
/// a different key, and it would grow with every metric the plant births whether or not any tag
|
||||
/// was ever authored for it. A birth's own values flow straight through the ingest path to that
|
||||
/// cache; nothing is retained here.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class AliasTable
|
||||
{
|
||||
private volatile Snapshot _snapshot = Snapshot.Empty;
|
||||
|
||||
/// <summary>How many distinct metrics the most recent birth declared.</summary>
|
||||
public int Count => _snapshot.Metrics.Length;
|
||||
|
||||
/// <summary>
|
||||
/// Every metric the most recent birth declared. The consumer's STALE fan-out on a death, and
|
||||
/// the discovery path's "which metrics does this scope have" question, both read this.
|
||||
/// </summary>
|
||||
public IReadOnlyList<SparkplugMetricBinding> Metrics => _snapshot.Metrics;
|
||||
|
||||
/// <summary>
|
||||
/// Replaces this scope's whole catalog with <paramref name="birthMetrics"/> — the metrics of one
|
||||
/// NBIRTH/DBIRTH payload, exactly as <see cref="SparkplugCodec"/> projected them.
|
||||
/// </summary>
|
||||
/// <param name="birthMetrics">The birth payload's metrics.</param>
|
||||
/// <returns>
|
||||
/// What was installed, and what was refused — the caller's only window onto a malformed birth,
|
||||
/// since this type takes no logger.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Only an unusable NAME is a rejection.</b> A metric with a blank/absent name cannot be
|
||||
/// bound to an authored tag by any route, and storing it alias-only would create a binding
|
||||
/// that can never resolve (or, worse, one that matches a tag whose authored metric name
|
||||
/// happens to be blank), so it is dropped and counted.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>A missing datatype is NOT a rejection</b> — it becomes
|
||||
/// <see cref="TahuDataType.Unknown"/>. Dropping such a metric would turn every DATA message
|
||||
/// for its alias into an unknown-alias event, which the ingest state machine answers with a
|
||||
/// rebirth request; the edge node would answer with the same malformed birth, and the pair
|
||||
/// would loop. Kept as Unknown, the typed layer refuses the value once
|
||||
/// (<c>ToDriverDataType()</c> returns null for it) and nothing storms.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>An alias claimed by two metrics in one birth resolves to neither.</b> Any choice
|
||||
/// between them is a coin flip between two different signals, which is the mis-route this
|
||||
/// type exists to prevent; the alias is dropped (the consumer sees an unknown alias and can
|
||||
/// request a rebirth) while both metrics stay bindable by name. A duplicate <i>name</i>, by
|
||||
/// contrast, is last-wins: the name is the binding key, so evicting it would take the
|
||||
/// authored tag dark entirely.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public BirthApplyResult RebuildFromBirth(IEnumerable<SparkplugMetric> birthMetrics)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(birthMetrics);
|
||||
|
||||
var byName = new Dictionary<string, SparkplugMetricBinding>(StringComparer.Ordinal);
|
||||
var byAlias = new Dictionary<ulong, SparkplugMetricBinding>();
|
||||
HashSet<ulong>? collidedAliases = null;
|
||||
var rejectedUnnamed = 0;
|
||||
var duplicateNames = 0;
|
||||
var aliasCollisions = 0;
|
||||
|
||||
foreach (var metric in birthMetrics)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(metric.Name))
|
||||
{
|
||||
rejectedUnnamed++;
|
||||
continue;
|
||||
}
|
||||
|
||||
var binding = new SparkplugMetricBinding(metric.Name, metric.Alias, metric.DataType ?? TahuDataType.Unknown);
|
||||
|
||||
if (!byName.TryAdd(binding.Name, binding))
|
||||
{
|
||||
duplicateNames++;
|
||||
byName[binding.Name] = binding;
|
||||
}
|
||||
|
||||
if (binding.Alias is { } alias && !byAlias.TryAdd(alias, binding))
|
||||
{
|
||||
aliasCollisions++;
|
||||
(collidedAliases ??= []).Add(alias);
|
||||
}
|
||||
}
|
||||
|
||||
if (collidedAliases is not null)
|
||||
{
|
||||
foreach (var alias in collidedAliases)
|
||||
{
|
||||
byAlias.Remove(alias);
|
||||
}
|
||||
}
|
||||
|
||||
// A duplicate name is last-wins in `byName`, so the alias index can still hold the losing
|
||||
// binding — drop those too rather than let an alias resolve to a name that resolves elsewhere.
|
||||
if (duplicateNames > 0)
|
||||
{
|
||||
foreach (var alias in byAlias.Where(kv => !ReferenceEquals(byName[kv.Value.Name], kv.Value))
|
||||
.Select(kv => kv.Key).ToList())
|
||||
{
|
||||
byAlias.Remove(alias);
|
||||
}
|
||||
}
|
||||
|
||||
// THE replace. One assignment of a fully-built snapshot — no merge, no upsert, and no
|
||||
// short-circuit for an empty birth (an empty birth legitimately clears the scope).
|
||||
_snapshot = new Snapshot(
|
||||
byAlias.ToFrozenDictionary(),
|
||||
byName.ToFrozenDictionary(StringComparer.Ordinal),
|
||||
[.. byName.Values]);
|
||||
|
||||
return new BirthApplyResult(byName.Count, rejectedUnnamed, aliasCollisions, duplicateNames);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Resolves a DATA metric's alias to the metric the <b>most recent</b> birth bound it to, or
|
||||
/// <see langword="null"/> when this birth declared no such alias.
|
||||
/// </summary>
|
||||
/// <param name="alias">The alias carried by an inbound DATA metric.</param>
|
||||
/// <returns>The binding, or <see langword="null"/> — which the consumer treats as an unknown alias.</returns>
|
||||
public SparkplugMetricBinding? Resolve(ulong alias) =>
|
||||
_snapshot.ByAlias.TryGetValue(alias, out var binding) ? binding : null;
|
||||
|
||||
/// <summary>The <see cref="Resolve(ulong)"/> try-shape.</summary>
|
||||
/// <param name="alias">The alias carried by an inbound DATA metric.</param>
|
||||
/// <param name="binding">The binding when this returns <see langword="true"/>.</param>
|
||||
/// <returns><see langword="true"/> when the most recent birth declared this alias.</returns>
|
||||
public bool TryResolve(ulong alias, [NotNullWhen(true)] out SparkplugMetricBinding? binding)
|
||||
{
|
||||
binding = Resolve(alias);
|
||||
return binding is not null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Resolves by the stable metric name — the binding key. Used for a DATA metric that carried its
|
||||
/// name rather than an alias (aliases are optional in Sparkplug), and to answer "does this scope
|
||||
/// publish the metric this tag was authored against".
|
||||
/// </summary>
|
||||
/// <param name="name">The stable metric name. Matched ordinally; Sparkplug names are case-sensitive.</param>
|
||||
/// <returns>The binding, or <see langword="null"/>.</returns>
|
||||
public SparkplugMetricBinding? ResolveByName(string name) =>
|
||||
!string.IsNullOrEmpty(name) && _snapshot.ByName.TryGetValue(name, out var binding) ? binding : null;
|
||||
|
||||
/// <summary>The <see cref="ResolveByName"/> try-shape.</summary>
|
||||
/// <param name="name">The stable metric name.</param>
|
||||
/// <param name="binding">The binding when this returns <see langword="true"/>.</param>
|
||||
/// <returns><see langword="true"/> when the most recent birth declared this metric.</returns>
|
||||
public bool TryResolveByName(string name, [NotNullWhen(true)] out SparkplugMetricBinding? binding)
|
||||
{
|
||||
binding = ResolveByName(name);
|
||||
return binding is not null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// One birth's catalog, immutable and published in a single assignment so the dispatcher thread
|
||||
/// always reads one whole birth's worth of state.
|
||||
/// </summary>
|
||||
/// <param name="ByAlias">Alias → binding, for the birth that declared it. Collided aliases are absent.</param>
|
||||
/// <param name="ByName">Stable metric name → binding — the index authored tags bind through.</param>
|
||||
/// <param name="Metrics">Every declared metric, for the STALE fan-out and discovery.</param>
|
||||
private sealed record Snapshot(
|
||||
FrozenDictionary<ulong, SparkplugMetricBinding> ByAlias,
|
||||
FrozenDictionary<string, SparkplugMetricBinding> ByName,
|
||||
SparkplugMetricBinding[] Metrics)
|
||||
{
|
||||
public static readonly Snapshot Empty = new(
|
||||
FrozenDictionary<ulong, SparkplugMetricBinding>.Empty,
|
||||
FrozenDictionary<string, SparkplugMetricBinding>.Empty,
|
||||
[]);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>One metric as its birth declared it: the stable name, the per-birth alias, the datatype.</summary>
|
||||
/// <param name="Name">
|
||||
/// The stable metric name — <b>the binding key</b>. An authored tag's <c>metricName</c> matches
|
||||
/// against this, never against <paramref name="Alias"/>.
|
||||
/// </param>
|
||||
/// <param name="Alias">
|
||||
/// The alias this birth assigned, or <see langword="null"/> when the birth declared none (legal —
|
||||
/// such a publisher sends names in DATA too). <b>Valid only until the next birth for this scope.</b>
|
||||
/// </param>
|
||||
/// <param name="DataType">
|
||||
/// The datatype the birth declared, or <see cref="TahuDataType.Unknown"/> when it declared none.
|
||||
/// This is the <i>only</i> place a DATA metric's datatype can come from — DATA carries none.
|
||||
/// </param>
|
||||
public sealed record SparkplugMetricBinding(string Name, ulong? Alias, TahuDataType DataType)
|
||||
{
|
||||
/// <summary>
|
||||
/// Applies <see cref="SparkplugCodec.ReinterpretSigned"/> to a raw DATA value using
|
||||
/// <b>this birth's</b> datatype.
|
||||
/// </summary>
|
||||
/// <param name="rawValue">The raw <see cref="SparkplugMetric.Value"/> from a DATA metric.</param>
|
||||
/// <returns>The signed value for a signed-integer datatype; <paramref name="rawValue"/> otherwise.</returns>
|
||||
/// <remarks>
|
||||
/// Exposed here because this is the one object that holds the datatype at the moment a DATA
|
||||
/// value is being resolved, and forgetting the call is silent: Sparkplug carries Int8/16/32/64
|
||||
/// as two's complement in an <i>unsigned</i> proto field, so a metric whose value is -42
|
||||
/// publishes as 4294967254 — plausible, Good quality, and invisible until someone reads a gauge.
|
||||
/// </remarks>
|
||||
public object? Reinterpret(object? rawValue) => SparkplugCodec.ReinterpretSigned(rawValue, DataType);
|
||||
}
|
||||
|
||||
/// <summary>What one <see cref="AliasTable.RebuildFromBirth"/> installed, and what it refused.</summary>
|
||||
/// <param name="Accepted">Distinct named metrics installed.</param>
|
||||
/// <param name="RejectedUnnamed">Metrics dropped for carrying no usable name.</param>
|
||||
/// <param name="AliasCollisions">Aliases claimed by more than one metric, and therefore left unresolvable.</param>
|
||||
/// <param name="DuplicateNames">Metrics whose name a later metric in the same birth overwrote.</param>
|
||||
public readonly record struct BirthApplyResult(
|
||||
int Accepted,
|
||||
int RejectedUnnamed,
|
||||
int AliasCollisions,
|
||||
int DuplicateNames)
|
||||
{
|
||||
/// <summary>Whether the birth was malformed in any way worth logging.</summary>
|
||||
public bool HasAnomaly => RejectedUnnamed > 0 || AliasCollisions > 0 || DuplicateNames > 0;
|
||||
}
|
||||
@@ -0,0 +1,234 @@
|
||||
using System.Collections.Concurrent;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
|
||||
|
||||
/// <summary>
|
||||
/// The driver's live Sparkplug birth state: one <see cref="AliasTable"/> per
|
||||
/// <see cref="SparkplugScope"/>, with the spec's node→device invalidation rules applied on birth
|
||||
/// and on death. Design doc §3.6 invariants #2 and #4.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Scoping.</b> A scope is the full <c>(group, edgeNode, device?)</c> triple — never the
|
||||
/// device id alone and never <c>node/device</c> without the group, or one plant's
|
||||
/// <c>Filler1</c> would answer for another's. A node-scoped birth (NBIRTH) owns the metrics the
|
||||
/// edge node publishes itself; each DBIRTH owns its device's. They are separate scopes because
|
||||
/// Sparkplug gives them separate alias spaces: alias 5 on <c>EdgeA</c> and alias 5 on
|
||||
/// <c>EdgeA/Filler1</c> are unrelated metrics.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>An NBIRTH invalidates every device under that node.</b> Per the Sparkplug spec an NBIRTH
|
||||
/// means the edge node (re)started and must re-publish a DBIRTH for each of its devices, so
|
||||
/// every previously published DBIRTH is void. Keeping a device's alias table across its node's
|
||||
/// rebirth is the same stale-alias mis-route as
|
||||
/// <see cref="AliasTable.RebuildFromBirth"/> guards against, one scope up — and it is easier to
|
||||
/// miss, because nothing about the DBIRTH itself changed. The invalidated devices are returned
|
||||
/// (<see cref="NodeBirthOutcome.InvalidatedDevices"/>) rather than merely dropped, so the
|
||||
/// consumer can fan STALE out over their metrics without a lookup against a table that has
|
||||
/// already been evicted.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>A death evicts, it does not blank.</b> After an NDEATH/DDEATH the scope is <i>absent</i>,
|
||||
/// which is what makes a DATA message arriving before the next birth a data-before-birth event
|
||||
/// (⇒ request a rebirth, §3.6 invariant #3) rather than a silent unknown-alias drop against a
|
||||
/// table that still looks alive.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Thread-safety.</b> A <see cref="ConcurrentDictionary{TKey,TValue}"/> of scopes, each
|
||||
/// holding an <see cref="AliasTable"/> whose own state is an atomically swapped immutable
|
||||
/// snapshot. A rebirth <i>rebuilds the existing table in place</i> rather than replacing the
|
||||
/// table object, so a consumer holding a reference to a scope's table always observes the newest
|
||||
/// birth instead of quietly reading a detached older one. No lock is taken on any path — this is
|
||||
/// read (and written) on MQTTnet's shared dispatcher thread.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Not a value store.</b> See the remarks on <see cref="AliasTable"/>: running values belong
|
||||
/// to <see cref="LastValueCache"/>, keyed by RawPath.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class BirthCache
|
||||
{
|
||||
private readonly ConcurrentDictionary<SparkplugScope, AliasTable> _scopes = new();
|
||||
|
||||
/// <summary>How many scopes currently hold a live birth.</summary>
|
||||
public int Count => _scopes.Count;
|
||||
|
||||
/// <summary>A snapshot of the scopes currently holding a live birth.</summary>
|
||||
public IReadOnlyList<SparkplugScope> Scopes => [.. _scopes.Keys];
|
||||
|
||||
/// <summary>
|
||||
/// Applies an NBIRTH: rebuilds the edge node's own catalog and <b>invalidates every device</b>
|
||||
/// under it, per the Sparkplug spec.
|
||||
/// </summary>
|
||||
/// <param name="groupId">The Sparkplug group id.</param>
|
||||
/// <param name="edgeNodeId">The Sparkplug edge-node id.</param>
|
||||
/// <param name="birthMetrics">The NBIRTH payload's metrics.</param>
|
||||
/// <returns>The node's apply result plus the devices this birth invalidated, with their metrics.</returns>
|
||||
public NodeBirthOutcome ApplyNodeBirth(string groupId, string edgeNodeId, IEnumerable<SparkplugMetric> birthMetrics)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(groupId);
|
||||
ArgumentException.ThrowIfNullOrEmpty(edgeNodeId);
|
||||
ArgumentNullException.ThrowIfNull(birthMetrics);
|
||||
|
||||
// Devices first: a device table must never outlive the node birth that voided it, whatever the
|
||||
// node's own rebuild does.
|
||||
var invalidated = Evict(scope => scope.DeviceId is not null && scope.IsUnder(groupId, edgeNodeId));
|
||||
|
||||
var result = TableFor(new SparkplugScope(groupId, edgeNodeId, null)).RebuildFromBirth(birthMetrics);
|
||||
return new NodeBirthOutcome(result, invalidated);
|
||||
}
|
||||
|
||||
/// <summary>Applies a DBIRTH: rebuilds exactly that device's catalog, wholesale.</summary>
|
||||
/// <param name="groupId">The Sparkplug group id.</param>
|
||||
/// <param name="edgeNodeId">The Sparkplug edge-node id.</param>
|
||||
/// <param name="deviceId">The Sparkplug device id.</param>
|
||||
/// <param name="birthMetrics">The DBIRTH payload's metrics.</param>
|
||||
/// <returns>What the birth installed, and what it refused.</returns>
|
||||
public BirthApplyResult ApplyDeviceBirth(
|
||||
string groupId,
|
||||
string edgeNodeId,
|
||||
string deviceId,
|
||||
IEnumerable<SparkplugMetric> birthMetrics)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(groupId);
|
||||
ArgumentException.ThrowIfNullOrEmpty(edgeNodeId);
|
||||
ArgumentException.ThrowIfNullOrEmpty(deviceId);
|
||||
ArgumentNullException.ThrowIfNull(birthMetrics);
|
||||
|
||||
return TableFor(new SparkplugScope(groupId, edgeNodeId, deviceId)).RebuildFromBirth(birthMetrics);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The scope's catalog, or <see langword="null"/> when no live birth has been seen for it —
|
||||
/// which is the consumer's data-before-birth signal.
|
||||
/// </summary>
|
||||
/// <param name="scope">The scope to look up.</param>
|
||||
/// <returns>The catalog, or <see langword="null"/>.</returns>
|
||||
public AliasTable? Find(SparkplugScope scope) => _scopes.TryGetValue(scope, out var table) ? table : null;
|
||||
|
||||
/// <summary>
|
||||
/// Applies an NDEATH: forgets the edge node and every device under it, returning what was
|
||||
/// forgotten so the consumer can emit STALE for those metrics.
|
||||
/// </summary>
|
||||
/// <param name="groupId">The Sparkplug group id.</param>
|
||||
/// <param name="edgeNodeId">The Sparkplug edge-node id.</param>
|
||||
/// <returns>The evicted scopes and their metrics; empty when nothing was live.</returns>
|
||||
public IReadOnlyList<SparkplugScopeMetrics> ForgetNode(string groupId, string edgeNodeId)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(groupId);
|
||||
ArgumentException.ThrowIfNullOrEmpty(edgeNodeId);
|
||||
|
||||
return Evict(scope => scope.IsUnder(groupId, edgeNodeId));
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Applies a DDEATH: forgets exactly one device, returning its metrics for the STALE fan-out.
|
||||
/// The node's own catalog is untouched.
|
||||
/// </summary>
|
||||
/// <param name="groupId">The Sparkplug group id.</param>
|
||||
/// <param name="edgeNodeId">The Sparkplug edge-node id.</param>
|
||||
/// <param name="deviceId">The Sparkplug device id.</param>
|
||||
/// <param name="removed">The evicted scope and its metrics when this returns <see langword="true"/>.</param>
|
||||
/// <returns><see langword="true"/> when the device had a live birth to forget.</returns>
|
||||
public bool TryForgetDevice(
|
||||
string groupId,
|
||||
string edgeNodeId,
|
||||
string deviceId,
|
||||
out SparkplugScopeMetrics removed)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(groupId);
|
||||
ArgumentException.ThrowIfNullOrEmpty(edgeNodeId);
|
||||
ArgumentException.ThrowIfNullOrEmpty(deviceId);
|
||||
|
||||
var scope = new SparkplugScope(groupId, edgeNodeId, deviceId);
|
||||
if (_scopes.TryRemove(scope, out var table))
|
||||
{
|
||||
removed = new SparkplugScopeMetrics(scope, table.Metrics);
|
||||
return true;
|
||||
}
|
||||
|
||||
removed = default;
|
||||
return false;
|
||||
}
|
||||
|
||||
/// <summary>Forgets every scope — the disconnect/reinitialise reset.</summary>
|
||||
public void Clear() => _scopes.Clear();
|
||||
|
||||
/// <summary>
|
||||
/// The scope's catalog, created empty on first use. Rebuilds happen <b>in place</b> on the
|
||||
/// returned instance, so a consumer holding it observes the newest birth rather than a detached
|
||||
/// older one.
|
||||
/// </summary>
|
||||
/// <param name="scope">The scope.</param>
|
||||
/// <returns>The scope's catalog.</returns>
|
||||
private AliasTable TableFor(SparkplugScope scope) => _scopes.GetOrAdd(scope, static _ => new AliasTable());
|
||||
|
||||
/// <summary>Removes every scope matching <paramref name="predicate"/>, capturing their metrics first.</summary>
|
||||
/// <param name="predicate">Which scopes to evict.</param>
|
||||
/// <returns>The evicted scopes and the metrics they held.</returns>
|
||||
private List<SparkplugScopeMetrics> Evict(Func<SparkplugScope, bool> predicate)
|
||||
{
|
||||
List<SparkplugScopeMetrics>? evicted = null;
|
||||
|
||||
// ConcurrentDictionary enumeration is weakly consistent, which is exactly right here: this runs
|
||||
// on the dispatcher thread and only needs to see the scopes that existed when the birth/death
|
||||
// arrived.
|
||||
foreach (var scope in _scopes.Keys)
|
||||
{
|
||||
if (!predicate(scope) || !_scopes.TryRemove(scope, out var table))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
(evicted ??= []).Add(new SparkplugScopeMetrics(scope, table.Metrics));
|
||||
}
|
||||
|
||||
return evicted ?? [];
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A Sparkplug metric-namespace scope: an edge node, or one device under it. The identity every
|
||||
/// birth, death and alias resolution is keyed by.
|
||||
/// </summary>
|
||||
/// <param name="GroupId">The Sparkplug group id.</param>
|
||||
/// <param name="EdgeNodeId">The Sparkplug edge-node id.</param>
|
||||
/// <param name="DeviceId">The Sparkplug device id, or <see langword="null"/> for the node's own scope.</param>
|
||||
public readonly record struct SparkplugScope(string GroupId, string EdgeNodeId, string? DeviceId)
|
||||
{
|
||||
/// <summary>Whether this is a device scope (a DBIRTH's) rather than an edge node's own.</summary>
|
||||
public bool IsDevice => DeviceId is not null;
|
||||
|
||||
/// <summary>The owning edge node's scope — this instance itself when it is already node-scoped.</summary>
|
||||
public SparkplugScope NodeScope => DeviceId is null ? this : new SparkplugScope(GroupId, EdgeNodeId, null);
|
||||
|
||||
/// <summary>Whether this scope belongs to the given edge node (the node's own scope included).</summary>
|
||||
/// <param name="groupId">The Sparkplug group id.</param>
|
||||
/// <param name="edgeNodeId">The Sparkplug edge-node id.</param>
|
||||
/// <returns><see langword="true"/> when both segments match ordinally.</returns>
|
||||
public bool IsUnder(string groupId, string edgeNodeId) =>
|
||||
string.Equals(GroupId, groupId, StringComparison.Ordinal)
|
||||
&& string.Equals(EdgeNodeId, edgeNodeId, StringComparison.Ordinal);
|
||||
|
||||
/// <inheritdoc/>
|
||||
public override string ToString() =>
|
||||
DeviceId is null ? $"{GroupId}/{EdgeNodeId}" : $"{GroupId}/{EdgeNodeId}/{DeviceId}";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A scope's metrics, captured at the moment it was evicted — the STALE fan-out's input, taken
|
||||
/// before the eviction so it cannot race a re-birth of the same scope.
|
||||
/// </summary>
|
||||
/// <param name="Scope">The scope that was evicted.</param>
|
||||
/// <param name="Metrics">The metrics its last birth declared.</param>
|
||||
public readonly record struct SparkplugScopeMetrics(SparkplugScope Scope, IReadOnlyList<SparkplugMetricBinding> Metrics);
|
||||
|
||||
/// <summary>The result of an NBIRTH: the node's own apply, plus the devices it invalidated.</summary>
|
||||
/// <param name="Result">What the node's catalog rebuild installed and refused.</param>
|
||||
/// <param name="InvalidatedDevices">
|
||||
/// The device scopes this NBIRTH voided, with the metrics they held — the STALE fan-out's input
|
||||
/// until each device re-DBIRTHs.
|
||||
/// </param>
|
||||
public readonly record struct NodeBirthOutcome(
|
||||
BirthApplyResult Result,
|
||||
IReadOnlyList<SparkplugScopeMetrics> InvalidatedDevices);
|
||||
@@ -0,0 +1,146 @@
|
||||
using Google.Protobuf;
|
||||
using Org.Eclipse.Tahu.Protobuf;
|
||||
using TahuDataType = Org.Eclipse.Tahu.Protobuf.DataType;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
|
||||
|
||||
/// <summary>
|
||||
/// The one seam through which a Sparkplug NCMD is published — <see cref="MqttConnection"/> is the
|
||||
/// production implementation once it grows a publish leg (Task 21); tests substitute a fake so the
|
||||
/// encode/topic/QoS/retain contract is exercisable without a broker. Deliberately narrower than
|
||||
/// "publish anything": a Sparkplug driver's only outbound traffic is NCMD/DCMD, so this is not a
|
||||
/// general MQTT client abstraction in waiting.
|
||||
/// </summary>
|
||||
public interface IMqttPublishTransport
|
||||
{
|
||||
/// <summary>
|
||||
/// Publishes one application message. Implementations must be bounded — a broker that accepts
|
||||
/// PUBLISH and never completes it (QoS > 0 awaiting PUBACK) must fail at a deadline, not
|
||||
/// hang; <see cref="RebirthRequester.RequestAsync"/> supplies one, but an implementation used
|
||||
/// directly by a future caller must not rely on that.
|
||||
/// </summary>
|
||||
/// <param name="topic">The concrete topic to publish on.</param>
|
||||
/// <param name="payload">The message body.</param>
|
||||
/// <param name="qos">Requested QoS, 0–2.</param>
|
||||
/// <param name="retain">The MQTT <c>retain</c> flag.</param>
|
||||
/// <param name="cancellationToken">Caller cancellation.</param>
|
||||
Task PublishAsync(string topic, byte[] payload, int qos, bool retain, CancellationToken cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Encodes and publishes a Sparkplug B rebirth request — an NCMD carrying the well-known
|
||||
/// <c>Node Control/Rebirth</c> boolean metric, addressed to one edge node's command topic. See
|
||||
/// Sparkplug B v3.0 spec §6/§7 and design doc §3.6.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b><see cref="Build"/> is pure.</b> It does no I/O and touches no transport, so it is
|
||||
/// trivially unit-testable and safe to call from anywhere (the ingest state machine on a
|
||||
/// detected gap, the browser on an operator click) without pulling in a live connection. The
|
||||
/// bounded, transport-facing publish is the separate <see cref="RequestAsync"/> overload.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>No <c>seq</c>.</b> Sparkplug's sequence-number stream (§6.4.1) belongs to the messages an
|
||||
/// edge node itself publishes (NBIRTH/NDATA/DBIRTH/DDATA/NDEATH/DDEATH) — it is how a host
|
||||
/// detects a gap in <i>that node's</i> outbound stream. An NCMD flows the other direction, host
|
||||
/// → node, and is not a member of the node's sequence at all: stamping one on here would not be
|
||||
/// "wrong per spec" so much as meaningless, and a strict edge-node implementation that validated
|
||||
/// it against its own counter would have grounds to reject the command outright.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>QoS 0, retain <see langword="false"/> — always.</b> NCMD is ordinary Sparkplug command
|
||||
/// traffic, published at the same QoS 0 the spec uses for NDATA/DDATA/NBIRTH/DBIRTH (only
|
||||
/// NDEATH — the broker-issued Will — and STATE use QoS 1). <see langword="retain"/> is the one
|
||||
/// that matters operationally: a retained NCMD would be replayed by the broker to the edge node
|
||||
/// on <i>every</i> future subscribe — including the node's own reconnect — driving it into a
|
||||
/// permanent rebirth loop from a single stale command. See the carry-forward landmine on
|
||||
/// <c>MqttDriverBrowser</c>/NDEATH-as-Will for the sibling failure shape this type must not
|
||||
/// introduce on the publish side.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b><c>Datatype</c> and both timestamps are set.</b> <c>Node Control/Rebirth</c> is Boolean;
|
||||
/// setting <see cref="Payload.Types.Metric.Datatype"/> explicitly (rather than leaving it for the
|
||||
/// node to infer) and stamping both the metric and payload <c>timestamp</c> matches what a
|
||||
/// well-behaved command payload carries per spec §6.4.13 and what the Task-25 simulator (and any
|
||||
/// real Cirrus-Link-derived edge node) expects to validate against. An edge node that treats a
|
||||
/// missing/ambiguous field as malformed and silently drops the command would otherwise leave the
|
||||
/// driver retrying forever with no visible error — the whole point of a rebirth request is to
|
||||
/// recover from exactly that kind of silent desync, so the request itself must not risk being
|
||||
/// the next cause of one.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class RebirthRequester
|
||||
{
|
||||
/// <summary>The well-known Sparkplug B node-control metric name that triggers a rebirth.</summary>
|
||||
public const string RebirthMetricName = "Node Control/Rebirth";
|
||||
|
||||
/// <summary>
|
||||
/// Default bounded deadline for <see cref="RequestAsync"/> when the caller does not supply one.
|
||||
/// Deliberately this type's own value rather than <c>MqttDriverOptions.ConnectTimeoutSeconds</c>
|
||||
/// — that knob already governs every MQTTnet connect/subscribe operation, and repurposing it
|
||||
/// would couple the rebirth-publish budget to the connect budget in a way neither side could
|
||||
/// tune independently (the same reasoning <c>MqttConnection.SubscribeAsync</c> documents for its
|
||||
/// own deadline).
|
||||
/// </summary>
|
||||
public static readonly TimeSpan DefaultRequestTimeout = TimeSpan.FromSeconds(5);
|
||||
|
||||
/// <summary>
|
||||
/// Builds the wire bytes and target topic for a rebirth-request NCMD, without publishing it.
|
||||
/// </summary>
|
||||
/// <param name="groupId">The Sparkplug group id.</param>
|
||||
/// <param name="edgeNodeId">The Sparkplug edge-node id to address the command to.</param>
|
||||
/// <returns>The NCMD topic (<c>spBv1.0/{groupId}/NCMD/{edgeNodeId}</c>) and its encoded payload.</returns>
|
||||
/// <exception cref="ArgumentException"><paramref name="groupId"/>/<paramref name="edgeNodeId"/> is null or empty.</exception>
|
||||
public static (string Topic, byte[] Bytes) Build(string groupId, string edgeNodeId)
|
||||
{
|
||||
// Validates both ids and does the topic assembly — see the "don't hand-concatenate" remark on
|
||||
// SparkplugTopic.Format itself.
|
||||
var topic = SparkplugTopic.Format(groupId, SparkplugMessageType.NCMD, edgeNodeId);
|
||||
|
||||
var timestampMs = (ulong)DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();
|
||||
|
||||
var payload = new Payload { Timestamp = timestampMs };
|
||||
payload.Metrics.Add(new Payload.Types.Metric
|
||||
{
|
||||
Name = RebirthMetricName,
|
||||
Datatype = (uint)TahuDataType.Boolean,
|
||||
Timestamp = timestampMs,
|
||||
BooleanValue = true,
|
||||
});
|
||||
|
||||
return (topic, payload.ToByteArray());
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Builds and publishes a rebirth-request NCMD under a bounded deadline. QoS 0, retain
|
||||
/// <see langword="false"/> — see the type remarks for why both are fixed rather than
|
||||
/// configurable.
|
||||
/// </summary>
|
||||
/// <param name="transport">The publish seam — the live connection, or a test fake.</param>
|
||||
/// <param name="groupId">The Sparkplug group id.</param>
|
||||
/// <param name="edgeNodeId">The Sparkplug edge-node id to address the command to.</param>
|
||||
/// <param name="cancellationToken">Caller cancellation; linked with the publish deadline.</param>
|
||||
/// <param name="timeout">
|
||||
/// The publish deadline. Defaults to <see cref="DefaultRequestTimeout"/> when omitted or
|
||||
/// non-positive.
|
||||
/// </param>
|
||||
/// <exception cref="ArgumentException"><paramref name="groupId"/>/<paramref name="edgeNodeId"/> is null or empty.</exception>
|
||||
/// <exception cref="ArgumentNullException"><paramref name="transport"/> is null.</exception>
|
||||
public static async Task RequestAsync(
|
||||
IMqttPublishTransport transport,
|
||||
string groupId,
|
||||
string edgeNodeId,
|
||||
CancellationToken cancellationToken,
|
||||
TimeSpan? timeout = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(transport);
|
||||
|
||||
var (topic, bytes) = Build(groupId, edgeNodeId);
|
||||
|
||||
var deadlineSpan = timeout is { } t && t > TimeSpan.Zero ? t : DefaultRequestTimeout;
|
||||
using var deadline = new CancellationTokenSource(deadlineSpan);
|
||||
using var linked = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken, deadline.Token);
|
||||
|
||||
await transport.PublishAsync(topic, bytes, qos: 0, retain: false, linked.Token).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,386 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
|
||||
|
||||
/// <summary>
|
||||
/// Per-edge-node Sparkplug B stream-continuity state: the wrapping <c>seq</c> counter that says
|
||||
/// whether the driver has missed a message, and the <c>bdSeq</c> session token that ties an
|
||||
/// NDEATH to the NBIRTH it belongs to. Design doc §3.6 invariant #3.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>One instance per edge node — this object <i>is</i> the edge node's stream state.</b> It
|
||||
/// holds no key and no map. Sparkplug numbers messages per edge node (an edge node's devices
|
||||
/// share its counter, so a DDATA advances the same sequence an NDATA does), and the ingest
|
||||
/// state machine already keeps per-scope state for the alias table and birth cache; giving
|
||||
/// this type a second internal dictionary would mean two maps whose lifetimes must be kept in
|
||||
/// step by hand, and a tracker that outlived a removed edge node would go on answering
|
||||
/// questions about a stream nobody is reading.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>This type detects; it does not react.</b> It never publishes, never requests a rebirth
|
||||
/// and never emits a quality change — the ingest state machine reads its verdicts and decides.
|
||||
/// The split matters because "was a message lost" is a fact about the wire, while "request a
|
||||
/// rebirth now" is a policy gated on <c>requestRebirthOnGap</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Thread-safe under a plain monitor.</b> Sparkplug messages arrive on MQTTnet's shared
|
||||
/// dispatcher thread while the reconnect path can call <see cref="Reset"/> from another, and
|
||||
/// every operation here is a read-modify-write of two coupled fields — the immutable-snapshot
|
||||
/// discipline <c>MqttSubscriptionManager</c> uses fits a set that is swapped wholesale, not a
|
||||
/// counter that is advanced. The critical sections are a handful of instructions each and
|
||||
/// nothing inside them can block, so the simple lock this repo uses elsewhere
|
||||
/// (<c>MqttDriver._hostLock</c>) is the right shape.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Nothing here throws, for any input.</b> Same reasoning as
|
||||
/// <see cref="SparkplugCodec"/>: this sits behind an unauthenticated firehose on the
|
||||
/// dispatcher thread, so a spec-violating publisher gets a verdict, never an exception that
|
||||
/// would stall delivery for every subscription on the connection.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed class SequenceTracker
|
||||
{
|
||||
/// <summary>
|
||||
/// The largest legal Sparkplug <c>seq</c>. The counter is a byte on the wire in spirit but a
|
||||
/// <c>uint64</c> in the schema, so the range check lives here — see <see cref="Accept"/>.
|
||||
/// </summary>
|
||||
public const ulong MaxSeq = 255;
|
||||
|
||||
private readonly object _gate = new();
|
||||
|
||||
/// <summary>The last credible sequence number, meaningful only when <see cref="_hasLastSeq"/>.</summary>
|
||||
private byte _lastSeq;
|
||||
|
||||
/// <summary>Whether any credible sequence number has been observed since the last reset.</summary>
|
||||
private bool _hasLastSeq;
|
||||
|
||||
/// <summary>Whether the current baseline was established by a birth rather than adopted mid-stream.</summary>
|
||||
private bool _birthSynchronized;
|
||||
|
||||
/// <summary>The current session's <c>bdSeq</c>, or null when no birth has supplied one.</summary>
|
||||
private ulong? _birthBdSeq;
|
||||
|
||||
/// <summary>
|
||||
/// Whether the current sequence baseline came from a birth. <see langword="false"/> also after
|
||||
/// a first message that was <i>not</i> a birth — the driver joined mid-stream and holds no
|
||||
/// alias table, which is a different situation from a gap even though both call for a rebirth.
|
||||
/// </summary>
|
||||
public bool IsBirthSynchronized
|
||||
{
|
||||
get { lock (_gate) return _birthSynchronized; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The last credible sequence number observed, or <see langword="null"/> when none has been —
|
||||
/// before the first message, or after <see cref="Reset"/>.
|
||||
/// </summary>
|
||||
public byte? LastSeq
|
||||
{
|
||||
get { lock (_gate) return _hasLastSeq ? _lastSeq : null; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The <c>bdSeq</c> of the most recent birth, or <see langword="null"/> when no birth has
|
||||
/// supplied one. This is the token <see cref="IsDeathForCurrentSession"/> matches against.
|
||||
/// </summary>
|
||||
public ulong? BirthBdSeq
|
||||
{
|
||||
get { lock (_gate) return _birthBdSeq; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Records an <b>NBIRTH</b>: restarts the sequence at the birth's <c>seq</c> and adopts its
|
||||
/// <c>bdSeq</c> as the current session token.
|
||||
/// </summary>
|
||||
/// <param name="seq">
|
||||
/// The birth payload's <c>seq</c> — <see cref="SparkplugPayload.Seq"/>, which is
|
||||
/// <see langword="null"/> when the message carried none.
|
||||
/// </param>
|
||||
/// <param name="bdSeq">
|
||||
/// The birth's session token, read from its <c>bdSeq</c> metric with
|
||||
/// <see cref="TryReadBdSeq"/>; <see langword="null"/> when the birth carried none.
|
||||
/// </param>
|
||||
/// <returns>
|
||||
/// <see langword="true"/> when the birth established a usable sequence baseline;
|
||||
/// <see langword="false"/> when its <c>seq</c> was absent or out of range.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>An NBIRTH is never a gap.</b> It restarts the sequence by definition, so it must not
|
||||
/// be run through <see cref="Accept"/> — doing so would flag a gap on the very message
|
||||
/// that just resynchronized everything, and answer a birth with a request for another one.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>A DBIRTH must NOT be offered here — it belongs to <see cref="Accept"/>.</b> Only the
|
||||
/// NBIRTH restarts the sequence; a DBIRTH carries the next number in the edge node's
|
||||
/// ongoing stream, and only the NBIRTH (with the NDEATH) carries <c>bdSeq</c> at all.
|
||||
/// Routing a DBIRTH here would do two wrong things at once: silently rebase the sequence
|
||||
/// mid-stream, and — because the DBIRTH has no <c>bdSeq</c> to pass — <b>wipe the node's
|
||||
/// session token to null</b>. A stale Last Will arriving afterwards would then find
|
||||
/// nothing to be compared against, fall through the fail-toward-stale rule in
|
||||
/// <see cref="IsDeathForCurrentSession"/>, and kill the live node this type exists to
|
||||
/// protect. The method is named for the node deliberately, so that call site reads wrong.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>An in-range <c>seq</c> other than the spec-required 0 is adopted, not refused.</b>
|
||||
/// Refusing it would leave the tracker unsynchronized against a publisher whose stream is
|
||||
/// otherwise perfectly followable, and every message that followed would demand a fresh
|
||||
/// rebirth — the storm this type exists to prevent, arrived at by being strict.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The <c>bdSeq</c> is recorded even when the <c>seq</c> was unusable.</b> Session
|
||||
/// identity and position-in-stream are independent facts; discarding the tie because the
|
||||
/// sequence number was garbled would leave the next NDEATH unmatchable, which is the one
|
||||
/// thing that lets a stale will kill a live node.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public bool AcceptNodeBirth(ulong? seq, ulong? bdSeq = null)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
_birthBdSeq = bdSeq;
|
||||
|
||||
if (seq is not { } value || value > MaxSeq)
|
||||
{
|
||||
_hasLastSeq = false;
|
||||
_birthSynchronized = false;
|
||||
return false;
|
||||
}
|
||||
|
||||
_lastSeq = (byte)value;
|
||||
_hasLastSeq = true;
|
||||
_birthSynchronized = true;
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Offers the next sequenced message's <c>seq</c> — <b>DBIRTH</b>, NDATA, DDATA or DDEATH —
|
||||
/// and reports whether the stream is still contiguous.
|
||||
/// </summary>
|
||||
/// <param name="seq">
|
||||
/// The payload's <c>seq</c> — <see cref="SparkplugPayload.Seq"/>, which is
|
||||
/// <see langword="null"/> when the message carried none.
|
||||
/// </param>
|
||||
/// <returns>
|
||||
/// <see langword="true"/> when this <c>seq</c> is the one that follows the last;
|
||||
/// <see langword="false"/> when a message was missed, when the value is out of range, or when
|
||||
/// it is absent. A <see langword="false"/> is the caller's cue to request a rebirth.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>The wrap is the whole point: next-expected is <c>(last + 1) & 0xFF</c>, so
|
||||
/// 255 → 0 is the sequence continuing, not a gap.</b> Getting the boundary wrong fails
|
||||
/// loudly in one direction and silently in the other. Read the wrap as a gap and every
|
||||
/// edge node is asked to rebirth once per 256 messages, so a busy node spends its life
|
||||
/// republishing births instead of publishing data. Miss a real gap and the driver serves
|
||||
/// values it knows are behind the device, at Good quality, indefinitely.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>A gap is reported once, then the tracker resynchronizes onto the observed value.</b>
|
||||
/// Holding the baseline at the pre-gap number would make every following message report a
|
||||
/// gap too, so a single lost message would become a permanent rebirth storm.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>An out-of-range <c>seq</c> is refused, never masked into range.</b> The codec hands
|
||||
/// this over as a <see cref="ulong"/> precisely so a spec-violating publisher's value is
|
||||
/// not silently truncated into a plausible-looking one, and masking would finish the job
|
||||
/// it declined to do: with the baseline at 255, a <c>seq</c> of 256 masks to 0 — exactly
|
||||
/// the value the wrap expects next — and the bogus message would be accepted as
|
||||
/// contiguous. Refused values do not become the baseline either, so the next genuine
|
||||
/// message is still measured against the last credible one.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The first message is not a gap</b> — there is nothing to measure it against. It is
|
||||
/// adopted as the baseline, and <see cref="IsBirthSynchronized"/> stays
|
||||
/// <see langword="false"/> to record that the driver joined mid-stream.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>NDEATH must not be offered here.</b> An NDEATH is the broker-published Last Will and
|
||||
/// carries no <c>seq</c> at all; feeding it in would report a gap on a message that never
|
||||
/// had a place in the sequence. It is tied to its birth by
|
||||
/// <see cref="IsDeathForCurrentSession"/> instead. A DDEATH is published by the edge node
|
||||
/// and <i>is</i> sequenced, so it does belong here.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public bool Accept(ulong? seq)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
// Refused without becoming the baseline: see the out-of-range remarks above.
|
||||
if (seq is not { } value || value > MaxSeq)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
var current = (byte)value;
|
||||
|
||||
if (!_hasLastSeq)
|
||||
{
|
||||
_lastSeq = current;
|
||||
_hasLastSeq = true;
|
||||
return true;
|
||||
}
|
||||
|
||||
var expected = (byte)((_lastSeq + 1) & 0xFF);
|
||||
|
||||
// Resynchronize even on a gap — one lost message must not become a permanent storm.
|
||||
_lastSeq = current;
|
||||
|
||||
return current == expected;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Reports whether an NDEATH belongs to the session currently believed alive — the
|
||||
/// <c>bdSeq</c> tie of §3.6 invariant #3.
|
||||
/// </summary>
|
||||
/// <param name="deathBdSeq">
|
||||
/// The death payload's <c>bdSeq</c>, read with <see cref="TryReadBdSeq"/>;
|
||||
/// <see langword="null"/> when it carried none.
|
||||
/// </param>
|
||||
/// <returns>
|
||||
/// <see langword="true"/> when the death applies and the node's metrics should go stale;
|
||||
/// <see langword="false"/> when it is a previous session's will and must be ignored.
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>What this prevents.</b> An edge node's connection drops, it reconnects and publishes
|
||||
/// a fresh NBIRTH — and only <i>then</i> does the broker notice the old connection died
|
||||
/// and deliver its retained Last Will. The NDEATH arrives after the NBIRTH, carrying the
|
||||
/// previous session's <c>bdSeq</c>. Without this comparison that stale will marks a live,
|
||||
/// freshly-born node dead and drives every one of its tags to Bad quality, with no further
|
||||
/// message coming to correct it until the node happens to rebirth again.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Unknowns fail toward stale, deliberately.</b> A death arriving before any birth was
|
||||
/// seen, a death carrying no <c>bdSeq</c>, or a birth that carried none all resolve to
|
||||
/// <see langword="true"/>. The two error directions are not symmetric: acting on a death
|
||||
/// wrongly marks tags stale until the next birth restores them (§3.6 invariant #4, a
|
||||
/// self-correcting error an operator can see), while ignoring a real death leaves a dead
|
||||
/// node's last values flowing at Good quality forever. Only a <i>positive mismatch</i> —
|
||||
/// two known, different tokens — is evidence enough to discard a death.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Pure.</b> It answers a question and changes nothing, so the caller can ask it while
|
||||
/// logging or deciding. A death that <i>is</i> acted on needs no reset here: the node is
|
||||
/// offline, and the next birth calls <see cref="AcceptNodeBirth"/> which restarts the sequence
|
||||
/// anyway.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public bool IsDeathForCurrentSession(ulong? deathBdSeq)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
if (_birthBdSeq is not { } birth || deathBdSeq is not { } death)
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
return birth == death;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Returns the tracker to its virgin state: no sequence baseline, not birth-synchronized, no
|
||||
/// session token.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The reconnect seam (§3.6 invariant #5 — late join). After a dropped connection the driver
|
||||
/// has missed an unknown number of messages, so the baseline it was holding is no longer
|
||||
/// evidence of anything: carrying it across would let the stream look contiguous purely
|
||||
/// because the edge node happened to publish the right number of messages while the driver was
|
||||
/// away.
|
||||
/// </remarks>
|
||||
public void Reset()
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
_lastSeq = 0;
|
||||
_hasLastSeq = false;
|
||||
_birthSynchronized = false;
|
||||
_birthBdSeq = null;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Reads the <c>bdSeq</c> session token out of a decoded NBIRTH or NDEATH payload.
|
||||
/// </summary>
|
||||
/// <param name="payload">The decoded payload; <see langword="null"/> and invalid are both handled.</param>
|
||||
/// <param name="bdSeq">The token on success; <c>0</c> otherwise.</param>
|
||||
/// <returns><see langword="true"/> when the payload carried a usable <c>bdSeq</c> metric.</returns>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b><c>bdSeq</c> is not a top-level payload field</b> — unlike <c>seq</c> it rides as an
|
||||
/// ordinary metric named <c>bdSeq</c>, which is why reading it is a helper rather than a
|
||||
/// property. The name is matched exactly (ordinal): the spec fixes it, so a case variant
|
||||
/// is far more likely to be a different metric than a typo of this one.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Signed values are reinterpreted before they are judged.</b> Sparkplug carries
|
||||
/// <c>Int64</c> as two's complement in an unsigned field, so a negative <c>bdSeq</c>
|
||||
/// reaches the projection as an enormous <see cref="ulong"/>. Read raw it would become a
|
||||
/// plausible-looking session token minted out of nonsense; run through
|
||||
/// <see cref="SparkplugCodec.ReinterpretSigned"/> it is visibly negative and refused.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>The value is treated as an opaque token, not as a 0–255 counter.</b> Its only job
|
||||
/// here is equality against the birth's, and a range check could never make a match more
|
||||
/// or less correct — it could only discard the one piece of evidence tying a death to its
|
||||
/// birth. This is the opposite call from <c>seq</c>, whose range is load-bearing precisely
|
||||
/// because its arithmetic wraps.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static bool TryReadBdSeq(SparkplugPayload? payload, out ulong bdSeq)
|
||||
{
|
||||
bdSeq = 0;
|
||||
|
||||
if (payload is not { IsValid: true })
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
foreach (var metric in payload.Metrics)
|
||||
{
|
||||
if (!string.Equals(metric.Name, "bdSeq", StringComparison.Ordinal))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (metric.ValueKind != SparkplugValueKind.Scalar)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
var value = metric.DataType is { } datatype
|
||||
? SparkplugCodec.ReinterpretSigned(metric.Value, datatype)
|
||||
: metric.Value;
|
||||
|
||||
switch (value)
|
||||
{
|
||||
case ulong u:
|
||||
bdSeq = u;
|
||||
return true;
|
||||
case uint u:
|
||||
bdSeq = u;
|
||||
return true;
|
||||
case long l when l >= 0:
|
||||
bdSeq = (ulong)l;
|
||||
return true;
|
||||
case int i when i >= 0:
|
||||
bdSeq = (ulong)i;
|
||||
return true;
|
||||
case short s when s >= 0:
|
||||
bdSeq = (ulong)s;
|
||||
return true;
|
||||
case sbyte sb when sb >= 0:
|
||||
bdSeq = (ulong)sb;
|
||||
return true;
|
||||
default:
|
||||
// Negative, or a wire type no integer token can come from.
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,313 @@
|
||||
using Google.Protobuf;
|
||||
using Org.Eclipse.Tahu.Protobuf;
|
||||
using TahuDataType = Org.Eclipse.Tahu.Protobuf.DataType;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
|
||||
|
||||
/// <summary>
|
||||
/// Decodes Sparkplug-B wire bytes into <see cref="SparkplugPayload"/> — the driver-side projection
|
||||
/// the ingest state machine consumes. Decode only; the NCMD <i>encode</i> path lives in
|
||||
/// <c>RebirthRequester</c>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Nothing here throws, for any input.</b> This runs on MQTTnet's shared dispatcher thread,
|
||||
/// behind an unauthenticated firehose the plant's edge nodes publish into. An escaping
|
||||
/// exception would not degrade one tag — it would stall or kill delivery for every
|
||||
/// subscription on the connection. Garbage bytes, a truncated body, a zero-length payload, a
|
||||
/// valid protobuf of some other schema and a pathologically nested Template all resolve to a
|
||||
/// verdict: <see cref="TryDecode"/> returns <see langword="false"/> and
|
||||
/// <see cref="Decode"/> returns <see cref="SparkplugPayload.Invalid"/>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Zero-length input is invalid, not empty.</b> Protobuf would happily parse zero bytes as
|
||||
/// "a Payload with every field defaulted", but in Sparkplug an empty MQTT body is never a
|
||||
/// legitimate message — treating it as a well-formed payload carrying no metrics is how a
|
||||
/// truncated-to-nothing body gets mistaken for a real one. It is reported as invalid.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Explicit presence is preserved, everywhere.</b> The vendored schema is proto2 precisely
|
||||
/// so absence and zero stay distinguishable, and every projection below reads
|
||||
/// <c>Has{Seq,Name,Alias,Datatype,Timestamp,IsNull}</c> rather than testing a value against its
|
||||
/// default. Two cases make this load-bearing rather than pedantic: a Sparkplug NBIRTH is
|
||||
/// REQUIRED to carry <c>seq = 0</c>, and every DATA metric after a birth carries an alias with
|
||||
/// <b>no</b> name and <b>no</b> datatype. A zero-check decoder reports "no sequence" for every
|
||||
/// birth and "" for every DATA metric name.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>Values are projected raw — nothing is coerced or reinterpreted here.</b> A metric's value
|
||||
/// arrives as the CLR type of the wire field that carried it (see
|
||||
/// <see cref="SparkplugMetric.Value"/>); coercion against the authored tag's declared
|
||||
/// <c>DriverDataType</c> is the consumer's job, and follows this driver's standing rule that a
|
||||
/// value which does not fit is refused rather than silently converted. The one wire-level
|
||||
/// translation this type does offer is <see cref="ReinterpretSigned"/>, because Sparkplug's
|
||||
/// two's-complement-in-an-unsigned-field encoding of signed integers is a property of the
|
||||
/// <i>wire</i>, not of the tag.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b><c>DataSet</c> and <c>Template</c> metrics are out of scope for v1.</b> They decode to
|
||||
/// <see cref="SparkplugValueKind.Unsupported"/> with a null value — deliberately visible, so a
|
||||
/// consumer can warn about a metric it cannot serve instead of silently treating it as one
|
||||
/// that was never published.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class SparkplugCodec
|
||||
{
|
||||
/// <summary>Decodes Sparkplug-B wire bytes, reporting success rather than throwing.</summary>
|
||||
/// <param name="wire">The MQTT message body.</param>
|
||||
/// <param name="payload">
|
||||
/// The decoded payload on success; <see cref="SparkplugPayload.Invalid"/> otherwise. Never
|
||||
/// <see langword="null"/>.
|
||||
/// </param>
|
||||
/// <returns>
|
||||
/// <see langword="true"/> when the bytes parsed as a Sparkplug-B <c>Payload</c>. Protobuf is a
|
||||
/// permissive, self-describing-only-by-convention format, so this means "parsed" rather than
|
||||
/// "was genuinely produced by a Sparkplug edge node" — unknown fields are preserved by
|
||||
/// Google.Protobuf and simply ignored here.
|
||||
/// </returns>
|
||||
public static bool TryDecode(ReadOnlySpan<byte> wire, out SparkplugPayload payload)
|
||||
{
|
||||
payload = SparkplugPayload.Invalid;
|
||||
|
||||
if (wire.IsEmpty)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
var proto = Payload.Parser.ParseFrom(wire);
|
||||
|
||||
var metrics = proto.Metrics.Count == 0
|
||||
? []
|
||||
: new SparkplugMetric[proto.Metrics.Count];
|
||||
|
||||
for (var i = 0; i < proto.Metrics.Count; i++)
|
||||
{
|
||||
metrics[i] = ProjectMetric(proto.Metrics[i]);
|
||||
}
|
||||
|
||||
payload = new SparkplugPayload(
|
||||
IsValid: true,
|
||||
Seq: proto.HasSeq ? proto.Seq : null,
|
||||
TimestampMs: proto.HasTimestamp ? proto.Timestamp : null,
|
||||
Metrics: metrics);
|
||||
|
||||
return true;
|
||||
}
|
||||
catch (Exception)
|
||||
{
|
||||
// Deliberately broad, and deliberately spanning the projection as well as the parse.
|
||||
// InvalidProtocolBufferException covers malformed, truncated and over-nested input, but
|
||||
// this is the dispatcher-thread boundary and the projection walks an attacker-shaped
|
||||
// object graph: the contract is a verdict for EVERY input, so a guard that stopped at
|
||||
// the parse would be a contract with a hole in it. Narrowing the catch would trade the
|
||||
// guarantee for a taxonomy nobody downstream can act on.
|
||||
payload = SparkplugPayload.Invalid;
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Decodes Sparkplug-B wire bytes, returning <see cref="SparkplugPayload.Invalid"/> when they
|
||||
/// cannot be decoded.
|
||||
/// </summary>
|
||||
/// <param name="wire">The MQTT message body.</param>
|
||||
/// <returns>The decoded payload — never <see langword="null"/>.</returns>
|
||||
/// <remarks>
|
||||
/// The convenience shape. <b>Check <see cref="SparkplugPayload.IsValid"/>:</b> an undecodable
|
||||
/// body and a genuinely metric-less one both present as an empty
|
||||
/// <see cref="SparkplugPayload.Metrics"/>, and only the flag tells them apart. Prefer
|
||||
/// <see cref="TryDecode"/> where the verdict drives control flow.
|
||||
/// </remarks>
|
||||
public static SparkplugPayload Decode(ReadOnlySpan<byte> wire) =>
|
||||
TryDecode(wire, out var payload) ? payload : SparkplugPayload.Invalid;
|
||||
|
||||
/// <summary>
|
||||
/// Reinterprets a raw metric value as the signed integer Sparkplug encoded it as, when its
|
||||
/// datatype is a signed integer type; returns the value unchanged for every other datatype.
|
||||
/// </summary>
|
||||
/// <param name="value">
|
||||
/// A <see cref="SparkplugMetric.Value"/> — a <see cref="uint"/> for the 8/16/32-bit arms, a
|
||||
/// <see cref="ulong"/> for the 64-bit arm.
|
||||
/// </param>
|
||||
/// <param name="datatype">The metric's Sparkplug datatype, from its birth or its own field.</param>
|
||||
/// <returns>
|
||||
/// <see cref="sbyte"/> / <see cref="short"/> / <see cref="int"/> / <see cref="long"/> for the
|
||||
/// signed integer datatypes; <paramref name="value"/> untouched otherwise (including when it is
|
||||
/// <see langword="null"/> or not the wire type the datatype implies).
|
||||
/// </returns>
|
||||
/// <remarks>
|
||||
/// Sparkplug carries <c>Int8</c>/<c>Int16</c>/<c>Int32</c> in the <b>unsigned</b>
|
||||
/// <c>int_value</c> field and <c>Int64</c> in the unsigned <c>long_value</c> field, as two's
|
||||
/// complement. Handing the raw field to a consumer publishes <c>4294967254</c> for a tag whose
|
||||
/// value is <c>-42</c> — a wrong value that looks entirely plausible, arrives with Good
|
||||
/// quality, and is invisible until someone reads a gauge. This is the single call that undoes
|
||||
/// it, and it is separate from the decode itself because a DATA metric carries no datatype of
|
||||
/// its own: only the consumer, holding the alias table built from the birth, knows which
|
||||
/// datatype applies.
|
||||
/// </remarks>
|
||||
public static object? ReinterpretSigned(object? value, TahuDataType datatype) => datatype switch
|
||||
{
|
||||
TahuDataType.Int8 when value is uint raw => unchecked((sbyte)raw),
|
||||
TahuDataType.Int16 when value is uint raw => unchecked((short)raw),
|
||||
TahuDataType.Int32 when value is uint raw => unchecked((int)raw),
|
||||
TahuDataType.Int64 when value is ulong raw => unchecked((long)raw),
|
||||
_ => value,
|
||||
};
|
||||
|
||||
/// <summary>Projects one generated metric onto the driver-side shape, presence intact.</summary>
|
||||
/// <param name="metric">The generated metric.</param>
|
||||
/// <returns>The projection.</returns>
|
||||
private static SparkplugMetric ProjectMetric(Payload.Types.Metric metric)
|
||||
{
|
||||
var (kind, value) = ProjectValue(metric);
|
||||
|
||||
return new SparkplugMetric(
|
||||
Name: metric.HasName ? metric.Name : null,
|
||||
Alias: metric.HasAlias ? metric.Alias : null,
|
||||
|
||||
// Cast, never filter: an index this build's enum does not define is a future Sparkplug
|
||||
// revision or a misbehaving publisher, and dropping it would deny the mapping layer the
|
||||
// only evidence it has.
|
||||
DataType: metric.HasDatatype ? (TahuDataType)metric.Datatype : null,
|
||||
TimestampMs: metric.HasTimestamp ? metric.Timestamp : null,
|
||||
ValueKind: kind,
|
||||
Value: value);
|
||||
}
|
||||
|
||||
/// <summary>Resolves a metric's value <c>oneof</c> to a kind plus a raw CLR value.</summary>
|
||||
/// <param name="metric">The generated metric.</param>
|
||||
/// <returns>The value kind and the projected value.</returns>
|
||||
/// <remarks>
|
||||
/// <c>is_null</c> wins over the <c>oneof</c>: the Sparkplug spec's whole reason for the field is
|
||||
/// that some datatypes have no spare sentinel, so a publisher that sets it means "null" even if
|
||||
/// a value field is also populated.
|
||||
/// </remarks>
|
||||
private static (SparkplugValueKind Kind, object? Value) ProjectValue(Payload.Types.Metric metric)
|
||||
{
|
||||
if (metric.HasIsNull && metric.IsNull)
|
||||
{
|
||||
return (SparkplugValueKind.Null, null);
|
||||
}
|
||||
|
||||
return metric.ValueCase switch
|
||||
{
|
||||
Payload.Types.Metric.ValueOneofCase.IntValue => (SparkplugValueKind.Scalar, metric.IntValue),
|
||||
Payload.Types.Metric.ValueOneofCase.LongValue => (SparkplugValueKind.Scalar, metric.LongValue),
|
||||
Payload.Types.Metric.ValueOneofCase.FloatValue => (SparkplugValueKind.Scalar, metric.FloatValue),
|
||||
Payload.Types.Metric.ValueOneofCase.DoubleValue => (SparkplugValueKind.Scalar, metric.DoubleValue),
|
||||
Payload.Types.Metric.ValueOneofCase.BooleanValue => (SparkplugValueKind.Scalar, metric.BooleanValue),
|
||||
Payload.Types.Metric.ValueOneofCase.StringValue => (SparkplugValueKind.Scalar, metric.StringValue),
|
||||
|
||||
// Copied out of the ByteString: the projection must outlive the parsed message.
|
||||
Payload.Types.Metric.ValueOneofCase.BytesValue =>
|
||||
(SparkplugValueKind.Scalar, metric.BytesValue.ToByteArray()),
|
||||
|
||||
// v1 scope boundary — decoded as a visible refusal, not as an exception or a silent drop.
|
||||
Payload.Types.Metric.ValueOneofCase.DatasetValue => (SparkplugValueKind.Unsupported, null),
|
||||
Payload.Types.Metric.ValueOneofCase.TemplateValue => (SparkplugValueKind.Unsupported, null),
|
||||
Payload.Types.Metric.ValueOneofCase.ExtensionValue => (SparkplugValueKind.Unsupported, null),
|
||||
|
||||
_ => (SparkplugValueKind.Absent, null),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A decoded Sparkplug-B payload: the driver-side projection of the generated <c>Payload</c>,
|
||||
/// carrying only what the ingest state machine consumes.
|
||||
/// </summary>
|
||||
/// <param name="IsValid">
|
||||
/// <see langword="false"/> for a payload that could not be decoded. An invalid payload also has an
|
||||
/// empty <paramref name="Metrics"/> list, so <b>this flag is the only thing distinguishing an
|
||||
/// undecodable body from a legitimately metric-less one</b>.
|
||||
/// </param>
|
||||
/// <param name="Seq">
|
||||
/// The payload sequence number, or <see langword="null"/> when the message carried none. Kept as
|
||||
/// the wire's <see cref="ulong"/> rather than narrowed to a byte: the Sparkplug range is 0–255, but
|
||||
/// a publisher that violates it is reporting a fact the consumer should be able to see and reject,
|
||||
/// not one this layer should silently truncate into a plausible-looking sequence number.
|
||||
/// </param>
|
||||
/// <param name="TimestampMs">The payload timestamp in Sparkplug epoch milliseconds, or null when absent.</param>
|
||||
/// <param name="Metrics">The payload's metrics, in wire order. Never <see langword="null"/>.</param>
|
||||
public sealed record SparkplugPayload(
|
||||
bool IsValid,
|
||||
ulong? Seq,
|
||||
ulong? TimestampMs,
|
||||
IReadOnlyList<SparkplugMetric> Metrics)
|
||||
{
|
||||
/// <summary>The shared "could not decode this" result.</summary>
|
||||
public static readonly SparkplugPayload Invalid = new(false, null, null, []);
|
||||
}
|
||||
|
||||
/// <summary>One decoded Sparkplug metric.</summary>
|
||||
/// <param name="Name">
|
||||
/// The metric's stable name, or <see langword="null"/> when the message omitted it — which every
|
||||
/// real DATA metric after a birth does, carrying only <paramref name="Alias"/>. Distinguishing
|
||||
/// this from an empty string is the reason the vendored schema is proto2.
|
||||
/// </param>
|
||||
/// <param name="Alias">The per-birth alias, or <see langword="null"/> when the metric carried none.</param>
|
||||
/// <param name="DataType">
|
||||
/// The metric's declared datatype, or <see langword="null"/> when absent (again, the normal case
|
||||
/// for a DATA metric — its datatype comes from the birth). An index this build's enum does not
|
||||
/// define is preserved as an undefined enum value rather than dropped.
|
||||
/// </param>
|
||||
/// <param name="TimestampMs">
|
||||
/// The metric's own acquisition timestamp in Sparkplug epoch milliseconds, or
|
||||
/// <see langword="null"/> when it carried none — in which case the payload's timestamp applies.
|
||||
/// </param>
|
||||
/// <param name="ValueKind">
|
||||
/// What <paramref name="Value"/> means. Check this before reading the value: a null value is
|
||||
/// ambiguous between "explicitly null", "absent" and "a kind v1 does not support".
|
||||
/// </param>
|
||||
/// <param name="Value">
|
||||
/// The <b>raw</b> wire value, boxed: <see cref="uint"/> (<c>int_value</c>), <see cref="ulong"/>
|
||||
/// (<c>long_value</c>), <see cref="float"/>, <see cref="double"/>, <see cref="bool"/>,
|
||||
/// <see cref="string"/> or <see cref="byte"/><c>[]</c> — and <see langword="null"/> for every
|
||||
/// <paramref name="ValueKind"/> other than <see cref="SparkplugValueKind.Scalar"/>.
|
||||
/// <para>
|
||||
/// <b>Signed integers arrive as their unsigned two's-complement wire value</b> — a
|
||||
/// <c>DataType.Int32</c> metric holding -42 is a <see cref="uint"/> of 4294967254 here. Run it
|
||||
/// through <see cref="SparkplugCodec.ReinterpretSigned"/> with the metric's datatype (from the
|
||||
/// birth, for a DATA metric) before publishing it.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Boxing is deliberate: the consumer coerces against the authored tag's declared
|
||||
/// <c>DriverDataType</c> and hands the result to a <c>DataValueSnapshot</c>, which boxes
|
||||
/// anyway, so a discriminated-union shape would buy an unboxing hop and cost every consumer a
|
||||
/// switch over a dozen arms.
|
||||
/// </para>
|
||||
/// </param>
|
||||
public readonly record struct SparkplugMetric(
|
||||
string? Name,
|
||||
ulong? Alias,
|
||||
TahuDataType? DataType,
|
||||
ulong? TimestampMs,
|
||||
SparkplugValueKind ValueKind,
|
||||
object? Value);
|
||||
|
||||
/// <summary>What a decoded metric's <see cref="SparkplugMetric.Value"/> represents.</summary>
|
||||
/// <remarks>
|
||||
/// Three of the four members have a null <see cref="SparkplugMetric.Value"/> and mean entirely
|
||||
/// different things, which is exactly why the distinction is carried explicitly rather than left
|
||||
/// for a consumer to infer from a null.
|
||||
/// </remarks>
|
||||
public enum SparkplugValueKind
|
||||
{
|
||||
/// <summary>The metric's value <c>oneof</c> carried nothing at all.</summary>
|
||||
Absent = 0,
|
||||
|
||||
/// <summary>The metric set <c>is_null</c>: it exists, and its value is explicitly null.</summary>
|
||||
Null,
|
||||
|
||||
/// <summary><see cref="SparkplugMetric.Value"/> holds the raw wire value.</summary>
|
||||
Scalar,
|
||||
|
||||
/// <summary>
|
||||
/// A <c>DataSet</c>, <c>Template</c> or extension value — decoded and reported, but not
|
||||
/// supported in v1. The consumer should warn and skip the metric rather than treat it as
|
||||
/// missing.
|
||||
/// </summary>
|
||||
Unsupported,
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,291 @@
|
||||
using System.Diagnostics.CodeAnalysis;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Sparkplug;
|
||||
|
||||
/// <summary>
|
||||
/// The Sparkplug B topic-namespace element that identifies a message's purpose — the third
|
||||
/// segment of <c>spBv1.0/{group}/{type}/{node}[/{device}]</c>, or the second segment of the
|
||||
/// differently-shaped <c>spBv1.0/STATE/{hostId}</c>. See design doc §3.1/§3.6 and Sparkplug B
|
||||
/// v3.0 spec §6 (Topic Namespace Elements).
|
||||
/// </summary>
|
||||
public enum SparkplugMessageType
|
||||
{
|
||||
/// <summary>Node birth certificate — (re)publishes an edge node's full metric/alias set.</summary>
|
||||
NBIRTH,
|
||||
|
||||
/// <summary>Device birth certificate — (re)publishes a device's full metric/alias set.</summary>
|
||||
DBIRTH,
|
||||
|
||||
/// <summary>Node data — incremental metric updates owned by the edge node itself.</summary>
|
||||
NDATA,
|
||||
|
||||
/// <summary>Device data — incremental metric updates for a device under the edge node.</summary>
|
||||
DDATA,
|
||||
|
||||
/// <summary>Node death certificate (the edge node's MQTT Will) — the node has gone offline.</summary>
|
||||
NDEATH,
|
||||
|
||||
/// <summary>Device death certificate — the device has gone offline (published by its edge node).</summary>
|
||||
DDEATH,
|
||||
|
||||
/// <summary>Node command — a write/rebirth request addressed to the edge node.</summary>
|
||||
NCMD,
|
||||
|
||||
/// <summary>Device command — a write request addressed to a device under the edge node.</summary>
|
||||
DCMD,
|
||||
|
||||
/// <summary>
|
||||
/// Primary-host online/offline state. Shaped differently from every other message type — see
|
||||
/// the remarks on <see cref="SparkplugTopic"/> and <see cref="SparkplugTopic.HostId"/>.
|
||||
/// </summary>
|
||||
STATE,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A parsed Sparkplug B MQTT topic. See design doc §3.1/§3.6 and Sparkplug B v3.0 spec §6.
|
||||
/// </summary>
|
||||
/// <param name="Type">The message's purpose.</param>
|
||||
/// <param name="GroupId">
|
||||
/// The Sparkplug group id. <see langword="null"/> for <see cref="SparkplugMessageType.STATE"/>,
|
||||
/// always populated otherwise.
|
||||
/// </param>
|
||||
/// <param name="EdgeNodeId">
|
||||
/// The Sparkplug edge-node id. <see langword="null"/> for <see cref="SparkplugMessageType.STATE"/>,
|
||||
/// always populated otherwise.
|
||||
/// </param>
|
||||
/// <param name="DeviceId">
|
||||
/// The Sparkplug device id, present only for the device-scoped message types
|
||||
/// (<see cref="SparkplugMessageType.DBIRTH"/>/<see cref="SparkplugMessageType.DDATA"/>/
|
||||
/// <see cref="SparkplugMessageType.DDEATH"/>/<see cref="SparkplugMessageType.DCMD"/>);
|
||||
/// <see langword="null"/> for node-scoped messages and for <see cref="SparkplugMessageType.STATE"/>.
|
||||
/// </param>
|
||||
/// <param name="HostId">
|
||||
/// The primary-host id, populated only for <see cref="SparkplugMessageType.STATE"/>; carries the
|
||||
/// third topic segment of <c>spBv1.0/STATE/{hostId}</c> (or the second segment of the legacy
|
||||
/// pre-3.0 <c>STATE/{hostId}</c> form). <see langword="null"/> for every other message type.
|
||||
/// </param>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Never throws on arbitrary input.</b> <see cref="TryParse"/> is the primitive everything
|
||||
/// else is built on — it is fed every topic string the broker delivers under a
|
||||
/// <c>spBv1.0/{groupId}/#</c> subscription, none of it validated ahead of time, so it returns
|
||||
/// <see langword="false"/> for anything malformed rather than throwing. <see cref="Parse"/> is
|
||||
/// a throwing convenience wrapper for call sites (tests, hand-built topics) that already know
|
||||
/// the string is well-formed.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <b>STATE does not fit the <c>{group}/{type}/{node}</c> mould — handled honestly, not
|
||||
/// force-fit.</b> The Sparkplug v3.0 spec shapes the primary-host state topic as
|
||||
/// <c>spBv1.0/STATE/{hostId}</c>: the message-type segment sits where a group id would
|
||||
/// otherwise be, and there is no edge-node or device segment at all. Pre-3.0 peers additionally
|
||||
/// published a bare <c>STATE/{hostId}</c> with no <c>spBv1.0</c> namespace prefix. This parser
|
||||
/// targets the v3.0 form and tolerates the legacy one on receive (design §3.1); <see cref="Format"/>
|
||||
/// and <see cref="FormatState"/> only ever produce the v3.0 form. A parsed STATE topic carries
|
||||
/// its host id in <see cref="HostId"/> and leaves <see cref="GroupId"/>/<see cref="EdgeNodeId"/>/
|
||||
/// <see cref="DeviceId"/> <see langword="null"/> — every other message type is the mirror image
|
||||
/// (<see cref="GroupId"/>/<see cref="EdgeNodeId"/> populated, <see cref="HostId"/> null).
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Group/edge-node/device/host segments are treated as opaque identifiers: validated only for
|
||||
/// non-emptiness and the absence of the MQTT wildcard characters <c>+</c>/<c>#</c> (a broker
|
||||
/// never delivers a PUBLISH on a topic containing either, so a topic string that does is
|
||||
/// malformed, not a legitimate id worth preserving). No further character-set restriction is
|
||||
/// applied — Sparkplug does not constrain id charsets beyond "not a topic-level separator".
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public sealed record SparkplugTopic(
|
||||
SparkplugMessageType Type,
|
||||
string? GroupId,
|
||||
string? EdgeNodeId,
|
||||
string? DeviceId,
|
||||
string? HostId)
|
||||
{
|
||||
private const string Namespace = "spBv1.0";
|
||||
|
||||
/// <summary>
|
||||
/// Attempts to parse <paramref name="topic"/> as a Sparkplug B topic. Never throws — returns
|
||||
/// <see langword="false"/> (and a <see langword="null"/> <paramref name="result"/>) for
|
||||
/// anything that is not a well-formed Sparkplug topic, including <see langword="null"/>/empty
|
||||
/// input, wrong namespace, an unrecognised message-type segment, a device-scoped message
|
||||
/// missing its device segment (or vice versa), or a segment containing an MQTT wildcard.
|
||||
/// </summary>
|
||||
public static bool TryParse(string? topic, [NotNullWhen(true)] out SparkplugTopic? result)
|
||||
{
|
||||
result = null;
|
||||
if (string.IsNullOrEmpty(topic))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
var segments = topic.Split('/');
|
||||
|
||||
// Legacy pre-3.0 STATE form: `STATE/{hostId}`, no `spBv1.0` namespace prefix.
|
||||
if (segments.Length == 2 && segments[0] == "STATE")
|
||||
{
|
||||
return TryBuildState(segments[1], out result);
|
||||
}
|
||||
|
||||
if (segments.Length < 2 || segments[0] != Namespace)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
// v3.0 STATE form: `spBv1.0/STATE/{hostId}`.
|
||||
if (segments[1] == "STATE")
|
||||
{
|
||||
return segments.Length == 3 && TryBuildState(segments[2], out result);
|
||||
}
|
||||
|
||||
// Every other message type: `spBv1.0/{group}/{type}/{node}[/{device}]`.
|
||||
if (segments.Length is not (4 or 5))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
if (!TryParseMessageType(segments[2], out var type))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
var groupId = segments[1];
|
||||
var edgeNodeId = segments[3];
|
||||
if (!IsValidSegment(groupId) || !IsValidSegment(edgeNodeId))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
var expectsDevice = IsDeviceScoped(type);
|
||||
var hasDeviceSegment = segments.Length == 5;
|
||||
if (expectsDevice != hasDeviceSegment)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
string? deviceId = null;
|
||||
if (hasDeviceSegment)
|
||||
{
|
||||
deviceId = segments[4];
|
||||
if (!IsValidSegment(deviceId))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
result = new SparkplugTopic(type, groupId, edgeNodeId, deviceId, null);
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Parses <paramref name="topic"/>, throwing <see cref="FormatException"/> if it is not a
|
||||
/// well-formed Sparkplug B topic. See <see cref="TryParse"/> for the non-throwing form.
|
||||
/// </summary>
|
||||
public static SparkplugTopic Parse(string? topic)
|
||||
{
|
||||
if (TryParse(topic, out var result))
|
||||
{
|
||||
return result;
|
||||
}
|
||||
|
||||
throw new FormatException($"'{topic}' is not a valid Sparkplug B topic.");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Builds a Sparkplug B topic string for a non-STATE message — e.g.
|
||||
/// <c>Format("Plant1", SparkplugMessageType.NCMD, "EdgeA")</c> for the Task 20 write path, so
|
||||
/// it does not have to hand-concatenate segments itself.
|
||||
/// </summary>
|
||||
/// <exception cref="ArgumentException">
|
||||
/// <paramref name="groupId"/>/<paramref name="edgeNodeId"/> is null/empty, or
|
||||
/// <paramref name="type"/> is <see cref="SparkplugMessageType.STATE"/> (use
|
||||
/// <see cref="FormatState"/> instead — STATE has no group/edge-node/device segments).
|
||||
/// </exception>
|
||||
public static string Format(string groupId, SparkplugMessageType type, string edgeNodeId, string? deviceId = null)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(groupId);
|
||||
ArgumentException.ThrowIfNullOrEmpty(edgeNodeId);
|
||||
if (type == SparkplugMessageType.STATE)
|
||||
{
|
||||
throw new ArgumentException("Use FormatState to build a STATE topic.", nameof(type));
|
||||
}
|
||||
|
||||
return deviceId is null
|
||||
? $"{Namespace}/{groupId}/{type}/{edgeNodeId}"
|
||||
: $"{Namespace}/{groupId}/{type}/{edgeNodeId}/{deviceId}";
|
||||
}
|
||||
|
||||
/// <summary>Builds the v3.0 STATE topic string <c>spBv1.0/STATE/{hostId}</c>.</summary>
|
||||
public static string FormatState(string hostId)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrEmpty(hostId);
|
||||
return $"{Namespace}/STATE/{hostId}";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Formats this instance back to its topic string (always the v3.0 STATE form for STATE
|
||||
/// topics, even if this instance was parsed from the legacy no-prefix form).
|
||||
/// </summary>
|
||||
/// <exception cref="InvalidOperationException">
|
||||
/// A required field for this instance's <see cref="Type"/> is <see langword="null"/> — i.e.
|
||||
/// this instance was not built by <see cref="TryParse"/>/<see cref="Parse"/> and violates the
|
||||
/// invariants documented on the type.
|
||||
/// </exception>
|
||||
public string ToTopicString() => Type == SparkplugMessageType.STATE
|
||||
? FormatState(HostId ?? throw new InvalidOperationException("STATE topic is missing HostId."))
|
||||
: Format(
|
||||
GroupId ?? throw new InvalidOperationException("Non-STATE topic is missing GroupId."),
|
||||
Type,
|
||||
EdgeNodeId ?? throw new InvalidOperationException("Non-STATE topic is missing EdgeNodeId."),
|
||||
DeviceId);
|
||||
|
||||
private static bool TryBuildState(string hostId, out SparkplugTopic? result)
|
||||
{
|
||||
result = null;
|
||||
if (!IsValidSegment(hostId))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
result = new SparkplugTopic(SparkplugMessageType.STATE, null, null, null, hostId);
|
||||
return true;
|
||||
}
|
||||
|
||||
private static bool TryParseMessageType(string segment, out SparkplugMessageType type)
|
||||
{
|
||||
switch (segment)
|
||||
{
|
||||
case nameof(SparkplugMessageType.NBIRTH):
|
||||
type = SparkplugMessageType.NBIRTH;
|
||||
return true;
|
||||
case nameof(SparkplugMessageType.DBIRTH):
|
||||
type = SparkplugMessageType.DBIRTH;
|
||||
return true;
|
||||
case nameof(SparkplugMessageType.NDATA):
|
||||
type = SparkplugMessageType.NDATA;
|
||||
return true;
|
||||
case nameof(SparkplugMessageType.DDATA):
|
||||
type = SparkplugMessageType.DDATA;
|
||||
return true;
|
||||
case nameof(SparkplugMessageType.NDEATH):
|
||||
type = SparkplugMessageType.NDEATH;
|
||||
return true;
|
||||
case nameof(SparkplugMessageType.DDEATH):
|
||||
type = SparkplugMessageType.DDEATH;
|
||||
return true;
|
||||
case nameof(SparkplugMessageType.NCMD):
|
||||
type = SparkplugMessageType.NCMD;
|
||||
return true;
|
||||
case nameof(SparkplugMessageType.DCMD):
|
||||
type = SparkplugMessageType.DCMD;
|
||||
return true;
|
||||
default:
|
||||
type = default;
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
private static bool IsDeviceScoped(SparkplugMessageType type) => type is
|
||||
SparkplugMessageType.DBIRTH or SparkplugMessageType.DDATA or SparkplugMessageType.DDEATH or SparkplugMessageType.DCMD;
|
||||
|
||||
private static bool IsValidSegment(string segment) =>
|
||||
segment.Length > 0 && segment.IndexOf('+') < 0 && segment.IndexOf('#') < 0;
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<Nullable>enable</Nullable>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<LangVersion>latest</LangVersion>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
<GenerateDocumentationFile>true</GenerateDocumentationFile>
|
||||
<NoWarn>$(NoWarn);CS1591</NoWarn>
|
||||
<RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.Mqtt</RootNamespace>
|
||||
<AssemblyName>ZB.MOM.WW.OtOpcUa.Driver.Mqtt</AssemblyName>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts\ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts.csproj"/>
|
||||
<ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
|
||||
<ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core\ZB.MOM.WW.OtOpcUa.Core.csproj"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="MQTTnet"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Tests"/>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
Reference in New Issue
Block a user