fix(history): advertise HistoryServerCapabilities from the wired backend (#881)
v2-ci / unit-tests (push) Has been cancelled

Every Boolean under Server/ServerCapabilities/HistoryServerCapabilities read
false (the SDK default) even though data and event history were served, so a
spec-following client skipped HistoryRead entirely.

Each backend now declares what it serves through its own interface:
- IHistorianDataSource.ReadCapabilities (Data / Events / ServerTimestamps):
  Gateway Data|Events; SqlServer + QuestDb add ServerTimestamps (they store
  ServerTimeUtc, the Gateway stamps read time); Null declares None. A
  reflection guard requires every production source to declare it itself.
- IHistorianDataUpdater.Capabilities (required member): SqlServer and QuestDb
  declare Insert/Replace/Update/DeleteRaw/DeleteAtTime; the Gateway provider
  has no updater.

The node manager writes the flags on every source/updater assignment
(AdvertisedHistoryCapabilities), and the same declarations drive dispatch:
an update the updater does not declare is BadHistoryOperationUnsupported
without reaching it, the HistoryWrite AccessLevel bit follows a non-empty
declaration, and event-history notifier promotion follows the Events flag.
Event and annotation update flags stay false (nothing dispatches them).

Tests: booted-server wire test per backend + Null + a SqlServer->Gateway
rewire pairing on one session; dispatch gating unit test; the #801 live
gate now asserts the Gateway flags (not run here).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-12 10:31:29 -05:00
parent ac4c4d40dc
commit b27b5b9cc1
17 changed files with 526 additions and 15 deletions
@@ -412,6 +412,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
_historianDataSource = value ?? NullHistorianDataSource.Instance;
SyncAdvertisedAggregates();
RefreshEventHistoryCapability();
SyncAdvertisedHistoryCapabilities();
}
}
@@ -425,7 +426,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
/// </summary>
private void RefreshEventHistoryCapability()
{
var wired = _historianDataSource is not NullHistorianDataSource;
var wired = ServesEventHistory(_historianDataSource);
lock (Lock)
{
foreach (var (nodeId, folder) in _notifierFolders)
@@ -457,7 +458,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
/// </summary>
private void RefreshHistoryWriteCapability()
{
var historyWritable = _historianDataUpdater is not null;
var historyWritable = HistoryWritable(_historianDataUpdater);
lock (Lock)
{
foreach (var (key, variable) in _variables)
@@ -478,6 +479,47 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
internal bool IsEventHistorySource(string folderNodeId, AddressSpaceRealm realm = AddressSpaceRealm.Uns) =>
_eventNotifierSources.ContainsKey(MapKey(realm, folderNodeId));
/// <summary>Whether <paramref name="source"/> declares event history — the ONE rule the notifier HistoryRead bit,
/// the event-history source registration and <c>AccessHistoryEventsCapability</c> share (lmxopcua#881).</summary>
private static bool ServesEventHistory(IHistorianDataSource source) =>
(source.ReadCapabilities & HistorianReadCapabilities.Events) != 0;
/// <summary>Whether <paramref name="updater"/> performs any update — what the <c>HistoryWrite</c> AccessLevel bit of a
/// historized node follows. An updater that declares no operation admits nothing, so the bit stays off.</summary>
private static bool HistoryWritable(IHistorianDataUpdater? updater) =>
updater is not null && updater.Capabilities != HistoryUpdateCapabilities.None;
/// <summary>
/// lmxopcua#881 — write the Boolean <c>HistoryServerCapabilities</c> properties from the wired source's
/// <see cref="IHistorianDataSource.ReadCapabilities"/> and updater's <see cref="IHistorianDataUpdater.Capabilities"/>
/// (<see cref="AdvertisedHistoryCapabilities"/>). Re-run on every source or updater assignment; the Null default
/// with no updater advertises all-false, the SDK's own default. Never throws: a failure is logged and the
/// previous advertisement stays — HistoryRead / HistoryUpdate dispatch enforce the same declarations regardless.
/// </summary>
internal void SyncAdvertisedHistoryCapabilities()
{
try
{
var flags = AdvertisedHistoryCapabilities.For(_historianDataSource, _historianDataUpdater);
if (AdvertisedHistoryCapabilities.Apply(Server, flags))
{
_logger.LogInformation(
"OtOpcUaNodeManager: advertising history capabilities for historian {Source} (updater {Updater}): {Flags}",
_historianDataSource.GetType().Name, _historianDataUpdater?.GetType().Name ?? "none", flags);
}
else
{
_logger.LogWarning(
"OtOpcUaNodeManager: could not advertise HistoryServerCapabilities for historian {Source}; HistoryRead/HistoryUpdate still enforce the backend's declared capabilities",
_historianDataSource.GetType().Name);
}
}
catch (Exception ex)
{
_logger.LogWarning(ex, "OtOpcUaNodeManager: failed to sync the advertised history capabilities");
}
}
/// <summary>
/// Trim <c>HistoryServerCapabilities/AggregateFunctions</c> (i=11201) to the current source's
/// <see cref="IHistorianDataSource.SupportedAggregates"/> (null ⇒ all, <see cref="AdvertisedAggregateFunctions.ServedBy"/>).
@@ -540,6 +582,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
{
_historianDataUpdater = value;
RefreshHistoryWriteCapability();
SyncAdvertisedHistoryCapabilities();
}
}
@@ -3878,7 +3921,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
{
if (!_notifierFolders.TryAdd(folder.NodeId, folder)) return;
folder.EventNotifier = EventNotifiers.SubscribeToEvents;
if (_historianDataSource is not NullHistorianDataSource)
if (ServesEventHistory(_historianDataSource))
{
// A historian is wired: advertise event history on this notifier and register it as a source.
// The equipment-folder NodeId identifier IS the equipment id IS the ReadEventsAsync sourceName.
@@ -4056,7 +4099,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
var historized = historianTagname is not null;
// The SDK exposes the flags separately (no CurrentReadWrite composite): ReadWrite is
// CurrentRead | CurrentWrite, with the HistoryRead bit OR-ed in when historized.
var access = ComposeAccessLevel(writable, historized, _historianDataUpdater is not null);
var access = ComposeAccessLevel(writable, historized, HistoryWritable(_historianDataUpdater));
var variable = new EquipmentVariableState(parent, Lock)
{
NodeId = new NodeId(variableNodeId, ns),
@@ -4154,7 +4197,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
{
if (!_variables.TryGetValue(key, out var v)) return false;
var historized = historianTagname is not null;
var access = ComposeAccessLevel(writable, historized, _historianDataUpdater is not null);
var access = ComposeAccessLevel(writable, historized, HistoryWritable(_historianDataUpdater));
v.AccessLevel = access;
v.UserAccessLevel = access;
v.Historizing = historized;
@@ -8140,18 +8183,22 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
{
// One "now" per request, so every item of the batch is judged against the same bound.
var latest = LatestAcceptedSourceTime();
ServeHistoryUpdate(context, nodesToProcess, results, errors, handle =>
ServeHistoryUpdate(context, nodesToProcess, results, errors, (handle, declared) =>
{
var details = nodesToUpdate[handle.Index];
HistoryUpdateMode mode;
HistoryUpdateCapabilities needs;
switch (details.PerformInsertReplace)
{
case PerformUpdateType.Insert: mode = HistoryUpdateMode.Insert; break;
case PerformUpdateType.Replace: mode = HistoryUpdateMode.Replace; break;
case PerformUpdateType.Update: mode = HistoryUpdateMode.Update; break;
case PerformUpdateType.Insert: mode = HistoryUpdateMode.Insert; needs = HistoryUpdateCapabilities.InsertData; break;
case PerformUpdateType.Replace: mode = HistoryUpdateMode.Replace; needs = HistoryUpdateCapabilities.ReplaceData; break;
case PerformUpdateType.Update: mode = HistoryUpdateMode.Update; needs = HistoryUpdateCapabilities.UpdateData; break;
default: return null; // Remove (and anything unknown) ⇒ unsupported
}
// lmxopcua#881: an operation the backend does not declare (and so does not advertise) is unsupported.
if (!Declares(declared, needs)) return null;
var items = details.UpdateValues.ToArray() ?? [];
return (updater, tagname, who, ct) => UpdateDataAsync(updater, tagname, mode, items, latest, who, ct);
});
@@ -8166,12 +8213,12 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
List<NodeHandle> nodesToProcess,
IDictionary<NodeId, NodeState> cache)
{
ServeHistoryUpdate(context, nodesToProcess, results, errors, handle =>
ServeHistoryUpdate(context, nodesToProcess, results, errors, (handle, declared) =>
{
var details = nodesToUpdate[handle.Index];
// Deleting the modified-value trail itself (Part 11 IsDeleteModified) is not supported: the trail is the
// audit record of every change and is aged out only by retention.
if (details.IsDeleteModified) return null;
if (details.IsDeleteModified || !Declares(declared, HistoryUpdateCapabilities.DeleteRaw)) return null;
var start = SdkValueBoundary.ToClrTimestamp(details.StartTime);
var end = SdkValueBoundary.ToClrTimestamp(details.EndTime);
// Part 11 requires both bounds of a raw delete; DateTime.MinValue is the wire's "unspecified". Refuse
@@ -8195,8 +8242,9 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
List<NodeHandle> nodesToProcess,
IDictionary<NodeId, NodeState> cache)
{
ServeHistoryUpdate(context, nodesToProcess, results, errors, handle =>
ServeHistoryUpdate(context, nodesToProcess, results, errors, (handle, declared) =>
{
if (!Declares(declared, HistoryUpdateCapabilities.DeleteAtTime)) return null;
var times = (nodesToUpdate[handle.Index].ReqTimes.ToArray() ?? []).Select(t => t.ToDateTime()).ToList();
return async (updater, tagname, who, ct) =>
{
@@ -8215,6 +8263,10 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
});
}
/// <summary>Whether <paramref name="updater"/> declares <paramref name="operation"/> (lmxopcua#881).</summary>
private static bool Declares(IHistorianDataUpdater updater, HistoryUpdateCapabilities operation) =>
(updater.Capabilities & operation) == operation;
/// <summary>
/// A HistoryUpdate timestamp as UTC. Wire timestamps are UTC; an in-process caller can hand a
/// <see cref="DateTimeKind.Local"/> value, which is converted (comparing its raw ticks against a UTC bound would be
@@ -8318,13 +8370,14 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
/// <param name="nodesToProcess">The handles the base dispatcher admitted.</param>
/// <param name="results">The service-level results list.</param>
/// <param name="errors">The service-level errors list.</param>
/// <param name="plan">Builds a node's operation from its details, or returns null when unsupported.</param>
/// <param name="plan">Builds a node's operation from its details and the wired updater (whose declared
/// <see cref="IHistorianDataUpdater.Capabilities"/> it checks), or returns null when unsupported.</param>
private void ServeHistoryUpdate(
ServerSystemContext context,
List<NodeHandle> nodesToProcess,
IList<HistoryUpdateResult> results,
IList<ServiceResult> errors,
Func<NodeHandle, Func<IHistorianDataUpdater, string, HistoryUpdateContext, CancellationToken, Task<HistoryUpdateResult>>?> plan)
Func<NodeHandle, IHistorianDataUpdater, Func<IHistorianDataUpdater, string, HistoryUpdateContext, CancellationToken, Task<HistoryUpdateResult>>?> plan)
{
nodesToProcess = AuthorizeHistoryUpdate(context, nodesToProcess, results, errors);
if (nodesToProcess.Count == 0) return;
@@ -8338,7 +8391,7 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2, INodeManager3
Func<IHistorianDataUpdater, string, HistoryUpdateContext, CancellationToken, Task<HistoryUpdateResult>> Operation)>(nodesToProcess.Count);
foreach (var handle in nodesToProcess)
{
var operation = updater is null ? null : plan(handle);
var operation = updater is null ? null : plan(handle, updater);
if (operation is null || !TryGetHistorizedTagname(handle.NodeId, out var tagname) || tagname is null)
{
errors[handle.Index] = StatusCodes.BadHistoryOperationUnsupported;