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

fix(mqtt): browse-commit writes a bindable address + a Request-rebirth affordance

Browse Source 
Two gaps the Task 23/24 review found, both blocking Task 26's live gate.

Gap 1 — browse-commit produced a silently dead MQTT tag. RawBrowseCommitMapper
had no `Mqtt` case, so a committed leaf fell through to the generic
`{"address": …}` key. Neither MqttTagDefinitionFactory entry point reads
`address`: the tag deployed clean and reported BadNodeIdUnknown forever, with
no signal at commit time. Predates Task 23 (Plain was affected too), but Task 23
built the Sparkplug metric tree precisely so an operator could browse and commit
a binding.

The address is a DESCRIPTOR, not a reference string, and it cannot be recovered
from the browse node id: `{group}/{node}[/{device}]::{metric}` where a metric
name legitimately contains `/` (`Node Control/Rebirth`) — the ambiguity
MetricSeparator's remarks already name. So the session STATES it, via a new
`AttributeInfo.AddressFields` seam, and the mapper reads it. Which keys are
emitted is also how the mapper learns Plain vs Sparkplug — the driver type
reaching it is just `Mqtt`, and the mode lives on the driver config. Key names
are single-sourced in the new `MqttTagConfigKeys` (producer, mapper, factory),
with the literals pinned by a test so a symmetric rename cannot silently unbind
already-persisted blobs. A leaf with no stated address is refused at commit in
words rather than committed dead.

Gap 2 — RequestRebirthAsync had no UI. Task 23 shipped it backend-only; Task 26
step 1 assumes the button, and Task 25's runbook notes the picker tree stays
empty until a birth lands, so it is the only way to fill it on demand. Added to
the /raw browse modal: scope = the clicked tree node (device/metric resolve up to
their edge node, group fans out and is refused whole past 32), an explicit
two-click confirm naming the resolved scope and its consequence, the outcome or
the refusal shown rather than swallowed. Offered only for a Sparkplug session
(new `IRebirthCapableBrowseSession.RebirthAvailable` — one session class serves
both modes, so a type test alone would draw a button that can only throw) and
only to a DriverOperator; the server-side gate remains the boundary.

Tests: MQTT 545 → 581, AdminUI 781 → 800. The round-trip tests feed the emitted
blob to the REAL factory and were falsified by mutating the emitted key name.

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
This commit is contained in:
Joseph Doherty
2026-07-24 23:43:07 -04:00
parent 767e7031b3
commit 8d9155682d
15 changed files with 988 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/RawBrowseCommitMapper.cs
+117 -3
View File
@@ -3,6 +3,7 @@ using ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors;
using ZB.MOM.WW.OtOpcUa.Commons.Types;
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
@@ -33,6 +34,9 @@ public static class RawBrowseCommitMapper
/// <param name="folderPath">The captured browse-folder nesting above the leaf (root→parent display
/// names); mirrored onto nested TagGroups only when <paramref name="createGroups"/> is true.</param>
/// <param name="createGroups">When true, mirror <paramref name="folderPath"/> as nested TagGroups.</param>
/// <param name="addressFields">The leaf's structured address (<see cref="AttributeInfo.AddressFields"/>),
/// for a driver whose binding is a tuple rather than a single reference string; null for every driver
/// whose address is the <paramref name="fullName"/> itself.</param>
/// <returns>The assembled import row.</returns>
public static RawTagImportRow MapLeaf(
string driverType,
@@ -42,10 +46,11 @@ public static class RawBrowseCommitMapper
string defaultDataType,
string? groupPrefix,
IReadOnlyList<string>? folderPath,
bool createGroups)
bool createGroups,
IReadOnlyDictionary<string, string>? addressFields = null)
{
var dataType = MapDataType(driverDataType) ?? defaultDataType;
var tagConfig = BuildTagConfig(driverType, fullName);
var tagConfig = BuildTagConfig(driverType, fullName, addressFields);
var mirrored = createGroups && folderPath is { Count: > 0 }
? string.Join(RawPaths.Separator, folderPath)
: null;
@@ -96,13 +101,25 @@ public static class RawBrowseCommitMapper
/// address field to <paramref name="fullName"/> and leaving every other field at its model default. Reuses
/// the <c>&lt;Driver&gt;TagConfigModel</c> for driver types that have a typed editor; the model-less Galaxy
/// driver gets the canonical camelCase <c>attributeRef</c> key directly.
/// <para>
/// <b>MQTT is the one driver whose address is not a single string</b> — a Sparkplug tag binds by a
/// <c>(group, edgeNode, device?, metric)</c> tuple — so it is built from the browse session's stated
/// <paramref name="addressFields"/> instead. See <see cref="BuildMqttTagConfig"/>.
/// </para>
/// </summary>
/// <param name="driverType">The owning device's driver type.</param>
/// <param name="fullName">The leaf's driver-side full reference to write into the address field.</param>
/// <param name="addressFields">The leaf's structured address, when the driver binds by a tuple —
/// see <see cref="BuildMqttTagConfig"/>. Ignored by every single-reference driver.</param>
/// <returns>The serialised driver-typed <c>TagConfig</c> JSON.</returns>
public static string BuildTagConfig(string driverType, string fullName)
public static string BuildTagConfig(
string driverType,
string fullName,
IReadOnlyDictionary<string, string>? addressFields = null)
{
var address = fullName ?? "";
if (Is(driverType, DriverTypeNames.Mqtt))
return BuildMqttTagConfig(address, addressFields);
if (Is(driverType, DriverTypeNames.OpcUaClient))
return new OpcUaClientTagConfigModel { NodeId = address }.ToJson();
if (Is(driverType, DriverTypeNames.AbCip))
@@ -123,6 +140,103 @@ public static class RawBrowseCommitMapper
return WriteSingleKey("address", address);
}
/// <summary>
/// Builds the <c>TagConfig</c> for a browse-committed <b>MQTT</b> leaf, whose address is a
/// <i>descriptor</i> rather than a single reference string: <c>topic</c> in Plain mode, and the
/// <c>groupId</c>/<c>edgeNodeId</c>/<c>deviceId?</c>/<c>metricName</c> tuple in Sparkplug B mode.
/// </summary>
/// <param name="fullName">The leaf's browse node id — the Plain-mode fallback address only.</param>
/// <param name="addressFields">The structured address the browse session stated.</param>
/// <returns>The serialised <c>TagConfig</c> JSON.</returns>
/// <remarks>
/// <para>
/// <b>The address is read from <paramref name="addressFields"/>, never parsed out of
/// <paramref name="fullName"/>.</b> A Sparkplug browse node id is
/// <c>{group}/{node}[/{device}]::{metric}</c>, and a metric name legitimately contains <c>/</c>
/// (<c>Node Control/Rebirth</c>) — so splitting the id cannot recover the tuple in general, and a
/// mapper that guessed would silently bind the wrong metric. The session that decoded the birth
/// already holds the decomposition and hands it over; this method only picks the keys it knows.
/// </para>
/// <para>
/// <b>Plain vs Sparkplug is likewise stated, not inferred</b> — the driver <i>type</i> reaching
/// here is just <c>Mqtt</c>, and the mode lives on the driver config, not on the tag. The
/// producing session knows its own mode and says so by which keys it emits: a
/// <c>metricName</c> ⇒ Sparkplug, a <c>topic</c> ⇒ Plain. (The blob deliberately carries no
/// <c>mode</c> key: <c>MqttTagDefinitionFactory</c> takes the shape from the driver's mode and
/// would ignore one, and <c>MqttTagConfigModel</c> re-infers it from these same keys.)
/// </para>
/// <para>
/// Keys are <b>whitelisted</b>, not splatted: these values came off a broker, and everything
/// beyond the address (payload format, JSONPath, QoS, dataType) stays at the driver's own
/// defaults for the operator to author afterwards. A leaf with no stated address at all is
/// rejected before this is reached — see <see cref="DescribeUncommittableLeaf"/>.
/// </para>
/// </remarks>
private static string BuildMqttTagConfig(string fullName, IReadOnlyDictionary<string, string>? addressFields)
{
if (TryGetField(addressFields, MqttTagConfigKeys.MetricName) is { } metricName)
{
var o = new JsonObject
{
[MqttTagConfigKeys.GroupId] = TryGetField(addressFields, MqttTagConfigKeys.GroupId) ?? "",
[MqttTagConfigKeys.EdgeNodeId] = TryGetField(addressFields, MqttTagConfigKeys.EdgeNodeId) ?? "",
[MqttTagConfigKeys.MetricName] = metricName,
};
// Absent, not blank, for a node-level metric — the two describe the same scope to the
// factory, but only the absent form says "this metric has no device" to a reader.
if (TryGetField(addressFields, MqttTagConfigKeys.DeviceId) is { } deviceId)
o[MqttTagConfigKeys.DeviceId] = deviceId;
return o.ToJsonString();
}
// Plain: the session states the topic; the node id is the same value and is the fallback for a
// session that stated nothing (a shape DescribeUncommittableLeaf refuses upstream).
return WriteSingleKey(
MqttTagConfigKeys.Topic,
TryGetField(addressFields, MqttTagConfigKeys.Topic) ?? fullName);
}
/// <summary>
/// Describes why a selected browse leaf cannot be committed as a working tag, or <c>null</c> when it
/// can. The AdminUI calls this before mapping so an unbindable selection fails <b>at commit, in
/// words</b>.
/// </summary>
/// <param name="driverType">The owning device's driver type.</param>
/// <param name="browseName">The leaf's browse name, for the message.</param>
/// <param name="addressFields">The structured address the browse session stated, if any.</param>
/// <returns>The operator-facing reason, or <c>null</c> when the leaf is committable.</returns>
/// <remarks>
/// Only MQTT can fail this today, and only in one shape: a leaf whose attribute lookup returned
/// nothing, so no address was stated. Committing it anyway is the defect this whole seam exists
/// to close — a Sparkplug tuple cannot be reconstructed from the node id, so the row would deploy
/// clean and then report <c>BadNodeIdUnknown</c> forever with nothing to point at. Every
/// single-reference driver is unaffected: its address IS the node id.
/// </remarks>
public static string? DescribeUncommittableLeaf(
string driverType,
string browseName,
IReadOnlyDictionary<string, string>? addressFields)
{
if (!Is(driverType, DriverTypeNames.Mqtt)) return null;
if (TryGetField(addressFields, MqttTagConfigKeys.MetricName) is not null) return null;
if (TryGetField(addressFields, MqttTagConfigKeys.Topic) is not null) return null;
return $"'{browseName}' could not be committed: the browse session reported no MQTT address for it "
+ "(its attribute lookup returned nothing). Re-open the browser and re-select it, or author "
+ "the tag manually.";
}
/// <summary>Reads one non-blank address field, or <c>null</c> when it is absent or blank.</summary>
/// <param name="fields">The stated address fields, or null.</param>
/// <param name="key">The field to read.</param>
/// <returns>The trimmed value, or <c>null</c>.</returns>
private static string? TryGetField(IReadOnlyDictionary<string, string>? fields, string key)
=> fields is not null && fields.TryGetValue(key, out var v) && !string.IsNullOrWhiteSpace(v)
? v.Trim()
: null;
/// <summary>
/// Combines a target-group path prefix with an optional mirrored sub-path, matching the WP5 CSV import
/// combine semantics: blank collapses to null, and a present prefix + suffix join with the RawPath