feat(opcua): FB-7 surgical DataType/array-shape in-place tag writes

Widen the F10b surgical address-space path so a changed equipment tag whose
only differences are DataType / IsArray / ArrayLength (on top of the existing
Writable / Historizing) is applied IN PLACE on the live node instead of forcing
a full RebuildAddressSpace that drops every client's subscriptions server-wide.

ISurgicalAddressSpaceSink.UpdateTagAttributes gains (dataType, isArray,
arrayLength); the DeferredAddressSpaceSink wrapper forwards all six args (the
prod-inertness seam). OtOpcUaNodeManager swaps DataType + ValueRank +
ArrayDimensions in place, and on a real shape change (a) resets the node to
BadWaitingForInitialData so no stale wrong-typed value is exposed (closes the
prior brief-value-type-mismatch objection) and (b) raises a Part 3
GeneralModelChangeEvent (verb=DataTypeChanged) so model-aware clients re-read
the definition. A Writable/Historizing-only change leaves the shape untouched
(no reset, no model event) — original behaviour preserved byte-for-byte.

AddressSpaceApplier.TagDeltaIsSurgicalEligible adds the three shape fields to
its whitelist; FullName/Name/DriverInstanceId/alarm differences still rebuild.

Tests: new NodeManagerSurgicalShapeUpdateTests boots a real server to prove the
in-place swap + value reset + the no-reset backward-compat path + the model-event
builder; AddressSpaceApplierTests invert the two former DataType/IsArray-rebuild
cases to surgical and assert the shape args land; DeferredAddressSpaceSinkTests
assert the shape args forward. 273/273 OpcUaServer.Tests green; full solution builds.
This commit is contained in:
Joseph Doherty
2026-06-19 03:21:03 -04:00
parent a325ec54c7
commit fb094fa566
8 changed files with 458 additions and 70 deletions
@@ -74,12 +74,17 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink, ISurgical
/// surgical capability. Returns false otherwise — before the real <c>SdkAddressSpaceSink</c> is
/// swapped in (inner is still the null sink), or any inner sink that isn't surgical — so the caller
/// (AddressSpaceApplier) falls back to a full rebuild. Without this forward the surgical optimization is
/// inert on every driver-role host, because actors inject THIS wrapper, not the inner sink.</summary>
/// inert on every driver-role host, because actors inject THIS wrapper, not the inner sink. ALL six args
/// (including the FB-7 DataType/array-shape ones) MUST be forwarded — a partial forward silently drops the
/// shape update on every driver-role host.</summary>
/// <param name="variableNodeId">The node ID of the variable to update in place.</param>
/// <param name="writable">Whether the node should be read/write.</param>
/// <param name="historianTagname">null ⇒ not historized; non-null ⇒ Historizing + historian binding.</param>
/// <param name="dataType">The OPC UA built-in data type name to apply in place.</param>
/// <param name="isArray">When true the node becomes a 1-D array; when false scalar.</param>
/// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is true.</param>
/// <returns>True when the inner sink applied the update; false when it lacks the capability or the node is missing.</returns>
public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname)
public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength)
=> _inner is ISurgicalAddressSpaceSink surgical
&& surgical.UpdateTagAttributes(variableNodeId, writable, historianTagname);
&& surgical.UpdateTagAttributes(variableNodeId, writable, historianTagname, dataType, isArray, arrayLength);
}
@@ -2,12 +2,25 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
/// <summary>Optional capability on an address-space sink: surgical in-place attribute updates on an
/// EXISTING variable node, used by AddressSpaceApplier to avoid a full RebuildAddressSpace for pure-property
/// tag changes (Writable / Historizing). A sink that does not implement it ⇒ caller falls back to a
/// full rebuild (safe default).</summary>
/// tag changes (Writable / Historizing / DataType / array-shape). A sink that does not implement it ⇒ caller
/// falls back to a full rebuild (safe default).</summary>
public interface ISurgicalAddressSpaceSink
{
/// <summary>Update an existing variable node's Writable (AccessLevel + inbound-write handler) and
/// Historizing (+ historian-tagname binding) IN PLACE, notifying subscribers (ClearChangeMasks)
/// without a rebuild. Returns false if the node does not exist (caller should rebuild instead).</summary>
bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname);
/// <summary>Update an existing variable node's surgically-updatable attributes IN PLACE, notifying
/// subscribers (ClearChangeMasks) without a rebuild — so client MonitoredItems on the node survive.
/// Covers Writable (AccessLevel + inbound-write handler), Historizing (+ historian-tagname binding),
/// and the node's presentation shape: <paramref name="dataType"/> (the OPC UA DataType) and
/// <paramref name="isArray"/>/<paramref name="arrayLength"/> (ValueRank + ArrayDimensions). When the
/// shape actually changes, the implementation resets the node's value to BadWaitingForInitialData
/// (no stale wrong-typed value is exposed until the driver republishes) and raises a Part 3
/// GeneralModelChangeEvent (verb=DataTypeChanged) so model-aware clients re-read the node definition.
/// Returns false if the node does not exist (caller should rebuild instead).</summary>
/// <param name="variableNodeId">The folder-scoped node id of the variable to update in place.</param>
/// <param name="writable">When true the node becomes read/write (with the inbound-write handler); otherwise read-only.</param>
/// <param name="historianTagname">null ⇒ not historized; non-null ⇒ Historizing with the HistoryRead bit and tagname binding.</param>
/// <param name="dataType">The OPC UA built-in data type name (e.g. "Boolean", "Int32", "Float").</param>
/// <param name="isArray">When true the node is a 1-D array (ValueRank=OneDimension); when false scalar.</param>
/// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is true; ignored for scalars.</param>
/// <returns>True when the in-place update was applied; false when the node is missing (caller rebuilds).</returns>
bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength);
}
@@ -95,13 +95,15 @@ public sealed class AddressSpaceApplier
// respawn (DriverHostActor → ApplyVirtualTags), so it skips the rebuild and PRESERVES every
// client's server-wide subscriptions. Any structural / node-affecting vtag change (Name/
// FolderPath/DataType) — or any non-vtag change anywhere — still forces a full rebuild.
// F10b (surgical tag write): a CHANGED equipment tag whose ONLY differences are Writable /
// IsHistorized / HistorianTagname (a plain value variable — no alarm condition node) can be
// updated IN PLACE on the existing node via ISurgicalAddressSpaceSink.UpdateTagAttributes
// (see TagDeltaIsSurgicalEligible), again avoiding the full rebuild and preserving subscriptions.
// Any other tag difference (DataType/IsArray/ArrayLength/FullName/identity/alarm) — or a sink
// that lacks the surgical capability, or a node that turns out missing — falls back to a full
// rebuild (safe default).
// F10b + FB-7 (surgical tag write): a CHANGED equipment tag whose ONLY differences are Writable /
// IsHistorized / HistorianTagname / DataType / IsArray / ArrayLength (a plain value variable — no
// alarm condition node) can be updated IN PLACE on the existing node via
// ISurgicalAddressSpaceSink.UpdateTagAttributes (see TagDeltaIsSurgicalEligible), avoiding the full
// rebuild and preserving subscriptions. The shape fields (DataType/IsArray/ArrayLength) are now
// surgical because the sink swaps DataType + ValueRank + ArrayDimensions in place and raises a
// GeneralModelChangeEvent. Any other tag difference (FullName/Name/DriverInstanceId/identity/alarm) —
// or a sink that lacks the surgical capability, or a node that turns out missing — falls back to a
// full rebuild (safe default).
var structuralRebuild =
plan.AddedEquipment.Count > 0 || plan.RemovedEquipment.Count > 0 || plan.ChangedEquipment.Count > 0 ||
plan.AddedAlarms.Count > 0 || plan.RemovedAlarms.Count > 0 || plan.ChangedAlarms.Count > 0 ||
@@ -125,15 +127,16 @@ public sealed class AddressSpaceApplier
var allApplied = true;
foreach (var d in surgicalTagDeltas)
{
// Compute the node id + writable + historian EXACTLY as MaterialiseEquipmentTags would
// so the in-place update matches what a rebuild would have produced.
// Compute the node id + writable + historian + shape EXACTLY as MaterialiseEquipmentTags
// would so the in-place update matches what a rebuild would have produced. Array tags are
// forced read-only (same as EnsureVariable: the driver write path doesn't handle arrays).
var nodeId = EquipmentNodeIds.Variable(d.Current.EquipmentId, d.Current.FolderPath, d.Current.Name);
var writable = d.Current.Writable && !d.Current.IsArray;
var historian = d.Current.IsHistorized
? (string.IsNullOrWhiteSpace(d.Current.HistorianTagname) ? d.Current.FullName : d.Current.HistorianTagname)
: null;
bool ok;
try { ok = surgical.UpdateTagAttributes(nodeId, writable, historian); }
try { ok = surgical.UpdateTagAttributes(nodeId, writable, historian, d.Current.DataType, d.Current.IsArray, d.Current.ArrayLength); }
catch (Exception ex)
{
_logger.LogError(ex, "AddressSpaceApplier: surgical UpdateTagAttributes threw for {Node}", nodeId);
@@ -389,11 +392,15 @@ public sealed class AddressSpaceApplier
Historize = d.Current.Historize,
}).Equals(d.Current);
// F10b: a CHANGED equipment tag whose ONLY differences are Writable / IsHistorized / HistorianTagname
// (a plain value variable — no alarm condition node) can be updated IN PLACE on the existing node via
// ISurgicalAddressSpaceSink.UpdateTagAttributes, avoiding a full rebuild (preserving subscriptions).
// DataType / IsArray / ArrayLength / FullName / DriverInstanceId / identity / alarm differences fall
// through to a rebuild — the override-unequal default also covers any future field.
// F10b + FB-7: a CHANGED equipment tag whose ONLY differences are Writable / IsHistorized /
// HistorianTagname / DataType / IsArray / ArrayLength (a plain value variable — no alarm condition node)
// can be updated IN PLACE on the existing node via ISurgicalAddressSpaceSink.UpdateTagAttributes,
// avoiding a full rebuild (preserving subscriptions). The presentation-shape fields (DataType / IsArray /
// ArrayLength) join the whitelist now that the surgical sink swaps DataType + ValueRank + ArrayDimensions
// in place (and raises a GeneralModelChangeEvent). FullName / DriverInstanceId / Name / identity / alarm
// differences still fall through to a rebuild — FullName/DriverInstanceId re-route the node to a different
// driver point, Name re-derives the NodeId, and an alarm flip turns the node into a Part 9 condition. The
// override-unequal default also covers any future field.
private static bool TagDeltaIsSurgicalEligible(AddressSpacePlan.EquipmentTagDelta d) =>
d.Previous.Alarm is null && d.Current.Alarm is null &&
(d.Previous with
@@ -401,6 +408,9 @@ public sealed class AddressSpaceApplier
Writable = d.Current.Writable,
IsHistorized = d.Current.IsHistorized,
HistorianTagname = d.Current.HistorianTagname,
DataType = d.Current.DataType,
IsArray = d.Current.IsArray,
ArrayLength = d.Current.ArrayLength,
}).Equals(d.Current);
/// <summary>The "no-event" condition state written to a removed equipment / alarm node before the
@@ -1386,12 +1386,38 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
}
/// <summary>F10b surgical counterpart of <see cref="EnsureVariable"/>: update an EXISTING tag variable's
/// Writable (AccessLevel + <see cref="OnEquipmentTagWrite"/> handler) and Historizing (+ historian-tagname
/// binding) in place and notify subscribers, WITHOUT a rebuild — so client MonitoredItems on the node
/// survive. Returns false when the node id is unknown (caller falls back to a full rebuild).</summary>
public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname)
/// Writable (AccessLevel + <see cref="OnEquipmentTagWrite"/> handler), Historizing (+ historian-tagname
/// binding), and presentation shape (<paramref name="dataType"/> → <c>DataType</c>;
/// <paramref name="isArray"/>/<paramref name="arrayLength"/> → <c>ValueRank</c> + <c>ArrayDimensions</c>)
/// in place and notify subscribers, WITHOUT a rebuild — so client MonitoredItems on the node survive.
/// Returns false when the node id is unknown (caller falls back to a full rebuild).
/// <para>
/// FB-7: when the shape (DataType / ValueRank / ArrayDimensions) ACTUALLY changes, two extra things
/// happen. (1) The node's value is reset to <c>BadWaitingForInitialData</c> (Value=null) so no value
/// still typed to the OLD DataType is exposed between this update and the driver's next publish — the
/// same fresh-node state <see cref="EnsureVariable"/> creates, which closes the "brief value-type
/// mismatch" window. (2) A Part 3 <c>GeneralModelChangeEvent</c> (verb=<c>DataTypeChanged</c>) is
/// raised from the Server object so model-aware clients re-read the node definition. A Writable /
/// Historizing-only change (DataType + array-ness unchanged) skips both — its value stays valid and
/// there is no model change to report (preserves the original surgical behaviour exactly).
/// </para>
/// <para>
/// The model-change event is built under <c>Lock</c> but reported AFTER the lock is released —
/// mirroring <see cref="RevertOptimisticWriteIfNeeded"/>: <c>Server.ReportEvent</c> re-enters the
/// server's own subscription/event path, so holding the node <c>Lock</c> across it risks a
/// lock-order inversion.
/// </para></summary>
/// <param name="variableNodeId">The folder-scoped node id of the variable to update in place.</param>
/// <param name="writable">When true the node becomes read/write with the inbound-write handler; otherwise read-only.</param>
/// <param name="historianTagname">null ⇒ not historized; non-null ⇒ Historizing with the HistoryRead bit and tagname binding.</param>
/// <param name="dataType">The OPC UA built-in data type name to apply (e.g. "Boolean", "Int32", "Float").</param>
/// <param name="isArray">When true the node becomes a 1-D array (ValueRank=OneDimension); when false scalar.</param>
/// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is true; ignored for scalars.</param>
/// <returns>True when the in-place update was applied; false when the node id is unknown.</returns>
public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength)
{
ArgumentException.ThrowIfNullOrEmpty(variableNodeId);
BaseDataVariableState? shapeChangedNode = null;
lock (Lock)
{
if (!_variables.TryGetValue(variableNodeId, out var v)) return false;
@@ -1403,8 +1429,89 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
v.OnWriteValue = writable ? OnEquipmentTagWrite : null;
if (historized) _historizedTagnames[variableNodeId] = historianTagname!;
else _historizedTagnames.TryRemove(variableNodeId, out _);
// FB-7: swap DataType + ValueRank + ArrayDimensions in place, but only when they actually differ
// from the live node — a Writable/Historizing-only change leaves the shape untouched (no value
// reset, no model-change event), preserving the original surgical behaviour byte-for-byte.
var newDataType = ResolveBuiltInDataType(dataType);
var newValueRank = isArray ? ValueRanks.OneDimension : ValueRanks.Scalar;
if (v.DataType != newDataType || v.ValueRank != newValueRank || ArrayLengthDiffers(v, isArray, arrayLength))
{
v.DataType = newDataType;
v.ValueRank = newValueRank;
v.ArrayDimensions = isArray
? new ReadOnlyList<uint>(new UInt32Collection(new[] { arrayLength ?? 0u }))
: null;
// Drop the stale (old-typed) value — mirrors EnsureVariable's fresh-node state so a client
// never reads a value whose runtime type contradicts the just-changed DataType.
v.Value = null;
v.StatusCode = StatusCodes.BadWaitingForInitialData;
v.Timestamp = DateTime.MinValue;
shapeChangedNode = v;
}
v.ClearChangeMasks(SystemContext, includeChildren: false);
return true;
}
// Report OUTSIDE Lock (see the method remarks) — only when the shape actually changed.
if (shapeChangedNode is not null) ReportNodeShapeChangedEvent(shapeChangedNode);
return true;
}
/// <summary>True when the node's current 1-D array length differs from the requested one (both must be
/// arrays for the comparison to matter — a scalar↔array transition is already caught by the ValueRank
/// check in <see cref="UpdateTagAttributes"/>, so this only fires for an array-to-array length edit).</summary>
private static bool ArrayLengthDiffers(BaseDataVariableState v, bool isArray, uint? arrayLength)
{
if (!isArray) return false; // scalar target ⇒ ValueRank check owns the diff
if (v.ArrayDimensions is not { Count: > 0 }) return true; // was scalar/empty ⇒ shape differs
return v.ArrayDimensions[0] != (arrayLength ?? 0u);
}
/// <summary>Build (but do not report) the Part 3 <c>GeneralModelChangeEvent</c> announcing that
/// <paramref name="variable"/>'s definition changed (DataType / ValueRank / ArrayDimensions). Verb =
/// <c>DataTypeChanged</c> — the model-change verb the SDK exposes for an attribute-shape change (there is
/// no separate ValueRank verb). <c>internal</c> (not private) so a node-manager test can assert the
/// populated Changes structure at the nearest deterministic seam (the end-to-end <c>Server.ReportEvent</c>
/// dispatch would need a subscribed event monitored-item to observe).</summary>
/// <param name="variable">The variable whose shape changed.</param>
/// <returns>A populated, unreported <see cref="GeneralModelChangeEventState"/>.</returns>
internal GeneralModelChangeEventState BuildNodeShapeChangedEvent(BaseDataVariableState variable)
{
var e = new GeneralModelChangeEventState(null);
e.Initialize(
SystemContext,
source: null,
severity: EventSeverity.Medium,
message: new LocalizedText($"Node {variable.NodeId} definition changed (DataType/ValueRank)"));
var change = new ModelChangeStructureDataType
{
Affected = variable.NodeId,
AffectedType = variable.TypeDefinitionId,
Verb = (byte)ModelChangeStructureVerbMask.DataTypeChanged,
};
// SetChildValue lazily creates + sets the Changes property (same pattern the audit-event builder
// relies on for its child PropertyStates).
e.SetChildValue(SystemContext, BrowseNames.Changes, new[] { change }, false);
return e;
}
/// <summary>Report the built <c>GeneralModelChangeEvent</c> through the SDK server, guarding against the
/// event path being disabled / having no subscribers / a transient failure — a surprise here MUST NOT
/// break the in-place update that already happened (mirrors <see cref="ReportAuditEvent"/>).</summary>
/// <param name="variable">The variable whose shape changed.</param>
private void ReportNodeShapeChangedEvent(BaseDataVariableState variable)
{
try
{
Server.ReportEvent(SystemContext, BuildNodeShapeChangedEvent(variable));
}
catch (Exception ex)
{
// Model-change reporting disabled / no monitored items / server shutting down ⇒ ReportEvent may
// no-op or throw; either way the in-place update already stands. Log to the SDK trace, don't rethrow.
#pragma warning disable CS0618 // Utils.LogError is [Obsolete] in favour of an ITelemetryContext this manager doesn't carry.
Utils.LogError(ex, "OtOpcUaNodeManager: failed to report GeneralModelChangeEvent for {0}", variable.NodeId);
#pragma warning restore CS0618
}
}
@@ -65,13 +65,17 @@ public sealed class SdkAddressSpaceSink : IOpcUaAddressSpaceSink, ISurgicalAddre
public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
=> _nodeManager.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, historianTagname, isArray, arrayLength);
/// <summary>F10b: surgically update an existing variable node's Writable + Historizing in place
/// (no rebuild). Returns false when the node does not exist (caller falls back to a full rebuild).</summary>
/// <summary>F10b: surgically update an existing variable node's Writable + Historizing + presentation
/// shape (DataType / array-ness) in place (no rebuild). Returns false when the node does not exist
/// (caller falls back to a full rebuild).</summary>
/// <param name="variableNodeId">The variable node identifier.</param>
/// <param name="writable">When true the node becomes read/write with the inbound-write handler; otherwise read-only.</param>
/// <param name="historianTagname">null ⇒ not historized; non-null ⇒ Historizing with the HistoryRead bit and tagname binding.</param>
public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname)
=> _nodeManager.UpdateTagAttributes(variableNodeId, writable, historianTagname);
/// <param name="dataType">The OPC UA built-in data type name to apply in place.</param>
/// <param name="isArray">When true the node becomes a 1-D array; when false scalar.</param>
/// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is true.</param>
public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength)
=> _nodeManager.UpdateTagAttributes(variableNodeId, writable, historianTagname, dataType, isArray, arrayLength);
/// <summary>Rebuilds the entire OPC UA address space.</summary>
public void RebuildAddressSpace() => _nodeManager.RebuildAddressSpace();