feat(historian): HistoryReadEvents over equipment-folder notifiers + event-field projection

src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs

@@ -46,6 +46,15 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
     /// Keyed by NodeId → the actual <see cref="FolderState"/> so <see cref="RebuildAddressSpace"/> can
     /// pass the folder to <c>RemoveRootNotifier</c> on teardown.</summary>
     private readonly Dictionary<NodeId, FolderState> _notifierFolders = new();
+    /// <summary>Phase C (Task 4): event-notifier folder NodeId-identifier → the event-history source
+    /// name passed to <see cref="IHistorianDataSource.ReadEventsAsync"/>. The equipment-folder NodeId
+    /// identifier IS the equipment id, which IS the sourceName, so key and value are the same string;
+    /// the map's presence (not its value) is what makes a folder an event-history source. Populated by
+    /// <see cref="EnsureFolderIsEventNotifier"/> only when a real historian is wired at promotion time,
+    /// and the <see cref="HistoryReadEvents"/> override resolves an inbound request's notifier NodeId
+    /// against it (a miss ⇒ <c>BadHistoryOperationUnsupported</c>). Cleared on
+    /// <see cref="RebuildAddressSpace"/>.</summary>
+    private readonly ConcurrentDictionary<string, string> _eventNotifierSources = new(StringComparer.Ordinal);
     private FolderState? _root;
 
     /// <summary>Initializes a new instance of the <see cref="OtOpcUaNodeManager"/> class with the OPC UA server and configuration.</summary>
@@ -170,6 +179,14 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
     internal BaseDataVariableState? TryGetVariable(string nodeId) =>
         _variables.TryGetValue(nodeId, out var variable) ? variable : null;
 
+    /// <summary>Look up a materialised folder node by its NodeId string, or null if not present.
+    /// Exposed for tests so they can resolve an equipment folder's NodeId (e.g. the event-notifier
+    /// node a HistoryReadEvents request targets).</summary>
+    /// <param name="nodeId">The folder node identifier.</param>
+    /// <returns>The cached <see cref="FolderState"/>, or null when none is registered.</returns>
+    internal FolderState? TryGetFolder(string nodeId) =>
+        _folders.TryGetValue(nodeId, out var folder) ? folder : null;
+
     /// <summary>
     ///     Apply a value write from <see cref="IOpcUaAddressSpaceSink.WriteValue"/>. Creates the
     ///     variable node on first call; subsequent calls update Value + StatusCode +
@@ -803,10 +820,31 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
     /// <summary>Promote <paramref name="folder"/> to <see cref="EventNotifiers.SubscribeToEvents"/> and
     /// register it as a root notifier (idempotent — guarded by <see cref="_notifierFolders"/>) so the
     /// alarm condition has a notifier path to the Server object for T16's event propagation.</summary>
+    /// <remarks>
+    ///     Phase C (Task 4): when a real historian is wired at promotion time (the source is NOT the
+    ///     <see cref="NullHistorianDataSource"/>), the folder ALSO gets the
+    ///     <see cref="EventNotifiers.HistoryRead"/> bit OR-ed in (keeping SubscribeToEvents) and registers
+    ///     its NodeId identifier as an event-history source so the <see cref="HistoryReadEvents"/> override
+    ///     accepts it. The HistoryRead-events bit is therefore only advertised when a historian is wired at
+    ///     the moment of promotion: the Host wires the source at <c>StartAsync</c> — BEFORE any deployment
+    ///     materialises alarms — so the normal boot ordering promotes folders with the bit set. A folder
+    ///     promoted while the source is still Null advertises live-event subscription but NOT event history
+    ///     until the next <see cref="RebuildAddressSpace"/> re-promotes it (acceptable, documented). The
+    ///     HistoryRead bit + source registration happen inside the same first-time
+    ///     <see cref="_notifierFolders"/> block so the idempotency guard covers them too.
+    /// </remarks>
     private void EnsureFolderIsEventNotifier(FolderState folder)
     {
         if (!_notifierFolders.TryAdd(folder.NodeId, folder)) return;
         folder.EventNotifier = EventNotifiers.SubscribeToEvents;
+        if (_historianDataSource is not NullHistorianDataSource)
+        {
+            // 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.
+            folder.EventNotifier = (byte)(folder.EventNotifier | EventNotifiers.HistoryRead);
+            var sourceName = folder.NodeId.Identifier?.ToString() ?? string.Empty;
+            _eventNotifierSources[sourceName] = sourceName;
+        }
         AddRootNotifier(folder);
         folder.ClearChangeMasks(SystemContext, includeChildren: false);
     }
@@ -998,6 +1036,9 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
             // Drop the notifier-folder guard so re-materialised alarms re-promote their (rebuilt)
             // equipment folders to event notifiers.
             _notifierFolders.Clear();
+            // Phase C (Task 4): drop the event-history source registrations alongside the notifier folders
+            // they map; re-materialised alarms re-register them (with the HistoryRead bit) on re-promotion.
+            _eventNotifierSources.Clear();
         }
     }
 
@@ -1124,6 +1165,151 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
         }
     }
 
+    /// <summary>
+    ///     Serve a HistoryRead-Events request over the equipment-folder event-notifier nodes (the folders
+    ///     that own alarm conditions). Each handle's NodeId identifier is resolved against
+    ///     <see cref="_eventNotifierSources"/>: a miss ⇒ <c>BadHistoryOperationUnsupported</c> (a node we own
+    ///     that isn't a registered event-history source — e.g. a plain folder, or one promoted while no
+    ///     historian was wired); a hit block-bridges to <see cref="IHistorianDataSource.ReadEventsAsync"/>
+    ///     for the folder's source name and projects each <see cref="HistoricalEvent"/> into a
+    ///     <see cref="HistoryEventFieldList"/> per the request's event filter. Like the Raw/Processed/AtTime
+    ///     arms this is NOT invoked under the node-manager <c>Lock</c>, so the block-bridge is safe; each
+    ///     handle is served under try/catch so a backend throw becomes a Bad status for THAT node only and
+    ///     never throws out of the batch.
+    /// </summary>
+    protected override void HistoryReadEvents(
+        ServerSystemContext context,
+        ReadEventDetails details,
+        TimestampsToReturn timestampsToReturn,
+        IList<HistoryReadValueId> nodesToRead,
+        IList<SdkHistoryReadResult> results,
+        IList<ServiceResult> errors,
+        List<NodeHandle> nodesToProcess,
+        IDictionary<NodeId, NodeState> cache)
+    {
+        // Snapshot the select clauses once — the same filter projects every node's events.
+        var selectClauses = details.Filter?.SelectClauses ?? new SimpleAttributeOperandCollection();
+
+        foreach (var handle in nodesToProcess)
+        {
+            var idString = handle.NodeId.Identifier?.ToString();
+            if (idString is null || !_eventNotifierSources.TryGetValue(idString, out var sourceName))
+            {
+                // Not a registered event-history source (plain folder / Null-source promotion) ⇒ unsupported.
+                // (The base pre-seeds this same status; set it explicitly so the contract is local + obvious.)
+                errors[handle.Index] = StatusCodes.BadHistoryOperationUnsupported;
+                continue;
+            }
+
+            try
+            {
+                // NOT under the node-manager Lock — block-bridging the async source is safe here.
+                var sourceResult = _historianDataSource.ReadEventsAsync(
+                    sourceName,
+                    details.StartTime,
+                    details.EndTime,
+                    // NumValuesPerNode is uint; ReadEventsAsync takes int (<=0 ⇒ backend default cap).
+                    ClampToInt(details.NumValuesPerNode),
+                    CancellationToken.None).GetAwaiter().GetResult();
+
+                var historyEvent = ProjectEvents(sourceResult.Events, selectClauses);
+                results[handle.Index] = new SdkHistoryReadResult
+                {
+                    // No events ⇒ GoodNoData (the notifier is historized, the window just held no events).
+                    StatusCode = sourceResult.Events.Count == 0 ? StatusCodes.GoodNoData : StatusCodes.Good,
+                    HistoryData = new ExtensionObject(historyEvent),
+                    // We never issue continuation points — every read returns the full window in one shot.
+                    ContinuationPoint = null,
+                };
+                errors[handle.Index] = ServiceResult.Good;
+            }
+            catch (Exception ex)
+            {
+                // One node's backend failure must not throw out of the batch — surface Bad for THIS node
+                // only. This manager carries no ILogger, so log via the SDK's static trace (see ServeNode).
+#pragma warning disable CS0618 // Type or member is obsolete
+                Utils.LogError(ex, "OtOpcUaNodeManager: HistoryReadEvents failed for node {0}", handle.NodeId);
+#pragma warning restore CS0618
+                errors[handle.Index] = StatusCodes.BadHistoryOperationUnsupported;
+            }
+        }
+    }
+
+    /// <summary>Clamp a <see cref="uint"/> request cap to a non-negative <see cref="int"/> for the
+    /// event-read surface (whose <c>maxEvents</c> is signed): values above <see cref="int.MaxValue"/>
+    /// saturate to <see cref="int.MaxValue"/>.</summary>
+    /// <param name="value">The uint cap from the request (<c>NumValuesPerNode</c>).</param>
+    /// <returns>The clamped non-negative int.</returns>
+    private static int ClampToInt(uint value) => value > int.MaxValue ? int.MaxValue : (int)value;
+
+    /// <summary>
+    ///     Project a sequence of <see cref="HistoricalEvent"/>s into an SDK <see cref="HistoryEvent"/> —
+    ///     one <see cref="HistoryEventFieldList"/> per event, each carrying the requested
+    ///     <paramref name="selectClauses"/>' fields in select-clause order (see
+    ///     <see cref="ProjectEventField"/>).
+    /// </summary>
+    /// <param name="events">The historian's event rows.</param>
+    /// <param name="selectClauses">The request's event-filter select clauses (the fields to emit, in order).</param>
+    /// <returns>The populated SDK <see cref="HistoryEvent"/>.</returns>
+    private static HistoryEvent ProjectEvents(
+        IReadOnlyList<HistoricalEvent> events, SimpleAttributeOperandCollection selectClauses)
+    {
+        var fieldLists = new HistoryEventFieldListCollection(events.Count);
+        foreach (var evt in events)
+        {
+            var fields = new VariantCollection(selectClauses.Count);
+            foreach (var operand in selectClauses)
+            {
+                fields.Add(ProjectEventField(evt, operand));
+            }
+
+            fieldLists.Add(new HistoryEventFieldList { EventFields = fields });
+        }
+
+        return new HistoryEvent { Events = fieldLists };
+    }
+
+    /// <summary>
+    ///     Project one <see cref="HistoricalEvent"/> field requested by a select <paramref name="operand"/>
+    ///     into a <see cref="Variant"/>. Mapping is by the operand's BrowsePath LEAF QualifiedName name
+    ///     (case-sensitive, per the OPC UA BaseEventType field names) against the
+    ///     <see cref="HistoricalEvent"/> shape:
+    ///     <c>EventId</c>→ByteString, <c>SourceName</c>→String, <c>Time</c>→DateTime,
+    ///     <c>ReceiveTime</c>→DateTime, <c>Message</c>→LocalizedText, <c>Severity</c>→UInt16. Any other
+    ///     leaf (EventType / SourceNode / ConditionName / an unrecognised name) and an empty BrowsePath ⇒
+    ///     <see cref="Variant.Null"/> — spec-conformant: a field the server can't supply is null.
+    /// </summary>
+    /// <param name="evt">The source event row.</param>
+    /// <param name="operand">The select-clause operand naming the field to project.</param>
+    /// <returns>The projected variant, or <see cref="Variant.Null"/> for an unsupported field.</returns>
+    private static Variant ProjectEventField(HistoricalEvent evt, SimpleAttributeOperand operand)
+    {
+        var leaf = LeafFieldName(operand);
+        return leaf switch
+        {
+            // BaseEventType/EventId is a ByteString — encode the driver-specific string id as UTF-8 bytes.
+            "EventId" => new Variant(System.Text.Encoding.UTF8.GetBytes(evt.EventId ?? string.Empty)),
+            "SourceName" => new Variant(evt.SourceName), // string; null ⇒ Variant.Null
+            "Time" => new Variant(evt.EventTimeUtc),
+            "ReceiveTime" => new Variant(evt.ReceivedTimeUtc),
+            "Message" => new Variant(new LocalizedText(evt.Message ?? string.Empty)),
+            "Severity" => new Variant(evt.Severity), // UInt16
+            // EventType / SourceNode / ConditionName / empty path / unrecognised leaf ⇒ null (spec-conformant).
+            _ => Variant.Null,
+        };
+    }
+
+    /// <summary>Extract the leaf (last) <see cref="QualifiedName.Name"/> from a select operand's BrowsePath,
+    /// or <c>null</c> when the BrowsePath is null/empty.</summary>
+    /// <param name="operand">The select-clause operand.</param>
+    /// <returns>The leaf field name, or null for an empty BrowsePath.</returns>
+    private static string? LeafFieldName(SimpleAttributeOperand operand)
+    {
+        var path = operand.BrowsePath;
+        if (path is null || path.Count == 0) return null;
+        return path[^1].Name;
+    }
+
     /// <summary>
     ///     Block-bridge to the historian source for one node handle and project the result onto the
     ///     service-level results/errors slots. Resolves the node's registered historian tagname first —