fix(history): advertise HistoryServerCapabilities from the wired backend (#881)

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
2026-11-12 10:31:29 -05:00
parent ac4c4d40dc
commit b27b5b9cc1
17 changed files with 526 additions and 15 deletions
@@ -0,0 +1,107 @@
+using Opc.Ua;
+using Opc.Ua.Server;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;
+
+/// <summary>
+///     The Boolean <c>Server/ServerCapabilities/HistoryServerCapabilities</c> properties (Part 11 §5.4.2) as the server
+///     advertises them for one wired historian (lmxopcua#881).
+/// </summary>
+/// <param name="AccessHistoryData"><c>AccessHistoryDataCapability</c>.</param>
+/// <param name="AccessHistoryEvents"><c>AccessHistoryEventsCapability</c>.</param>
+/// <param name="ServerTimestampSupported"><c>ServerTimestampSupported</c>.</param>
+/// <param name="InsertData"><c>InsertDataCapability</c>.</param>
+/// <param name="ReplaceData"><c>ReplaceDataCapability</c>.</param>
+/// <param name="UpdateData"><c>UpdateDataCapability</c>.</param>
+/// <param name="DeleteRaw"><c>DeleteRawCapability</c>.</param>
+/// <param name="DeleteAtTime"><c>DeleteAtTimeCapability</c>.</param>
+internal sealed record HistoryCapabilityFlags(
+    bool AccessHistoryData,
+    bool AccessHistoryEvents,
+    bool ServerTimestampSupported,
+    bool InsertData,
+    bool ReplaceData,
+    bool UpdateData,
+    bool DeleteRaw,
+    bool DeleteAtTime)
+{
+    // Insert/Replace/Update/DeleteEvent and InsertAnnotation have no members: the node manager dispatches no event or
+    // annotation HistoryUpdate to any backend (the SDK base leaves UpdateEventDetails / UpdateStructureDataDetails
+    // BadHistoryOperationUnsupported), so they are always advertised false.
+}
+
+/// <summary>
+///     Derive and write the <c>HistoryServerCapabilities</c> Booleans from what the wired backend DECLARES — the
+///     source's <see cref="IHistorianDataSource.ReadCapabilities"/> and the updater's
+///     <see cref="IHistorianDataUpdater.Capabilities"/>. The same declarations gate HistoryRead-Events (notifier
+///     registration) and HistoryUpdate dispatch, so the advertisement cannot claim an operation the server refuses, or
+///     hide one it serves. <c>AggregateFunctions</c> (<see cref="AdvertisedAggregateFunctions"/>) and
+///     <c>MaxReturnDataValues</c> (<see cref="HistoryPaging.AdvertiseMaxReturnDataValues"/>) have their own sync;
+///     <c>MaxReturnEventValues</c> stays the SDK's 0 (no limit: <c>NumValuesPerNode = 0</c> returns every event).
+/// </summary>
+internal static class AdvertisedHistoryCapabilities
+{
+    /// <summary>The flags for <paramref name="source"/> + <paramref name="updater"/> — pure, unit-testable.</summary>
+    /// <param name="source">The wired data source (the Null source declares nothing).</param>
+    /// <param name="updater">The wired updater, or <c>null</c> when the backend has no HistoryUpdate path.</param>
+    /// <returns>The flags to advertise.</returns>
+    public static HistoryCapabilityFlags For(IHistorianDataSource source, IHistorianDataUpdater? updater)
+    {
+        var read = source.ReadCapabilities;
+        var update = updater?.Capabilities ?? HistoryUpdateCapabilities.None;
+        bool Has(HistoryUpdateCapabilities op) => (update & op) == op;
+        return new HistoryCapabilityFlags(
+            AccessHistoryData: (read & HistorianReadCapabilities.Data) != 0,
+            AccessHistoryEvents: (read & HistorianReadCapabilities.Events) != 0,
+            ServerTimestampSupported: (read & HistorianReadCapabilities.ServerTimestamps) != 0,
+            InsertData: Has(HistoryUpdateCapabilities.InsertData),
+            ReplaceData: Has(HistoryUpdateCapabilities.ReplaceData),
+            UpdateData: Has(HistoryUpdateCapabilities.UpdateData),
+            DeleteRaw: Has(HistoryUpdateCapabilities.DeleteRaw),
+            DeleteAtTime: Has(HistoryUpdateCapabilities.DeleteAtTime));
+    }
+
+    /// <summary>
+    ///     Write <paramref name="flags"/> onto the server's <c>HistoryServerCapabilities</c> node (the event / annotation
+    ///     properties are written false). Idempotent; a re-sync overwrites. Never throws.
+    /// </summary>
+    /// <param name="server">The running server.</param>
+    /// <param name="flags">The flags.</param>
+    /// <returns><c>true</c> when written; <c>false</c> when the diagnostics manager or node is missing, or the SDK failed.</returns>
+    public static bool Apply(IServerInternal? server, HistoryCapabilityFlags flags)
+    {
+        if (server?.DiagnosticsNodeManager is not DiagnosticsNodeManager diagnostics) return false;
+        try
+        {
+            var caps = diagnostics.GetDefaultHistoryCapabilitiesAsync().AsTask().GetAwaiter().GetResult();
+            if (caps is null) return false;
+
+            void Set(PropertyState<bool>? property, bool value)
+            {
+                if (property is null) return; // optional in the nodeset — nothing to advertise
+                property.Value = value;
+                property.ClearChangeMasks(diagnostics.SystemContext, false);
+            }
+
+            Set(caps.AccessHistoryDataCapability, flags.AccessHistoryData);
+            Set(caps.AccessHistoryEventsCapability, flags.AccessHistoryEvents);
+            Set(caps.ServerTimestampSupported, flags.ServerTimestampSupported);
+            Set(caps.InsertDataCapability, flags.InsertData);
+            Set(caps.ReplaceDataCapability, flags.ReplaceData);
+            Set(caps.UpdateDataCapability, flags.UpdateData);
+            Set(caps.DeleteRawCapability, flags.DeleteRaw);
+            Set(caps.DeleteAtTimeCapability, flags.DeleteAtTime);
+            Set(caps.InsertEventCapability, false);
+            Set(caps.ReplaceEventCapability, false);
+            Set(caps.UpdateEventCapability, false);
+            Set(caps.DeleteEventCapability, false);
+            Set(caps.InsertAnnotationCapability, false);
+            return true;
+        }
+        catch (Exception)
+        {
+            return false; // advisory: the caller logs; dispatch enforces the declarations regardless
+        }
+    }
+}
@@ -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;