Phase 3 PR 35 — IHistoryProvider gains ReadAtTimeAsync + ReadEventsAsync; GalaxyProxyDriver implements both. Extends Core.Abstractions.IHistoryProvider with two new methods that round out the OPC UA Part 11 HistoryRead surface (HistoryReadAtTime + HistoryReadEvents are the last two modes not covered by the PR 19-era ReadRawAsync + ReadProcessedAsync) and wires GalaxyProxyDriver to call the existing PR-10/PR-11 IPC contracts the Host already implements.

Interface additions use C# default interface implementations that throw NotSupportedException — existing IHistoryProvider implementations keep compiling, only drivers whose backend carries the relevant capability override. This matches the 'capabilities are optional per driver' design already used by IHistoryProvider.ReadProcessedAsync's docs (Modbus / OPC UA Client drivers never had an event historian and the default-throw path lets callers see BadHistoryOperationUnsupported naturally). New HistoricalEvent record models one historian row (EventId, SourceName, EventTimeUtc + ReceivedTimeUtc — process vs historian-persist timestamps, Message, Severity mapped to OPC UA's 1-1000 range); HistoricalEventsResult pairs the event list with a continuation-point token for future batching. Both live in Core.Abstractions so downstream (Proxy, Host, Server) reference a single domain shape — no Shared-contract leak into the driver-facing interface. GalaxyProxyDriver.ReadAtTimeAsync maps the domain DateTime[] to Unix-ms longs, calls CallAsync on the existing MessageKind.HistoryReadAtTimeRequest, and trusts the Host's one-sample-per-requested-timestamp contract (the Host pads with bad-quality snapshots for timestamps it can't interpolate; re-aligning on the Proxy side would duplicate the Host's interpolation policy logic). ReadEventsAsync does the same for HistoryReadEventsRequest; ToHistoricalEvent translates GalaxyHistoricalEvent (MessagePack-annotated, Unix-ms) to the domain record, explicitly tagging DateTimeKind.Utc on both timestamp fields so downstream serializers (JSON, OPC UA types) don't apply an unexpected local-time offset. Tests — HistoricalEventMappingTests (3 new Proxy.Tests unit cases): every field maps correctly from wire to domain; null SourceName and null DisplayText preserve through the mapping (system events without a source come out with null so callers can distinguish them from alarm events); both timestamps come out as DateTimeKind.Utc (regression guard against a future refactor using DateTime.FromFileTimeUtc or similar that defaults to Unspecified). Driver.Galaxy.Proxy.Tests Unit suite: 17 pass / 0 fail (14 prior + 3 new). Full solution build clean, 0 errors. Scope exclusions — DriverNodeManager HistoryRead service-handler wiring (on the OPC UA Server side, where HistoryReadAtTime and HistoryReadEvents service requests land) and the full-loop integration test (OPC UA client → server → IPC → Host → HistorianDataSource → back) are deferred to a focused follow-up PR. The capability surface is the load-bearing change; wiring the service handlers is mechanical in comparison and worth its own PR for reviewability. docs/v2/lmx-followups.md #1 updated with the split. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-18 16:08:27 -04:00
parent 2584379e75
commit bf329b05d8
4 changed files with 221 additions and 11 deletions
--- a/src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IHistoryProvider.cs
+++ b/src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IHistoryProvider.cs
@@ -30,6 +30,52 @@ public interface IHistoryProvider
        TimeSpan interval,
        HistoryAggregateType aggregate,
        CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Read one sample per requested timestamp — OPC UA HistoryReadAtTime service. The
+    ///     driver interpolates (or returns the prior-boundary sample) when no exact match
+    ///     exists. Optional; drivers that can't interpolate throw <see cref="NotSupportedException"/>.
+    /// </summary>
+    /// <remarks>
+    ///     Default implementation throws. Drivers opt in by overriding; keeps existing
+    ///     <c>IHistoryProvider</c> implementations compiling without forcing a ReadAtTime path
+    ///     they may not have a backend for.
+    /// </remarks>
+    Task<HistoryReadResult> ReadAtTimeAsync(
+        string fullReference,
+        IReadOnlyList<DateTime> timestampsUtc,
+        CancellationToken cancellationToken)
+        => throw new NotSupportedException(
+            $"{GetType().Name} does not implement ReadAtTimeAsync. " +
+            "Drivers whose backends support at-time reads override this method.");
+
+    /// <summary>
+    ///     Read historical alarm/event records — OPC UA HistoryReadEvents service. Distinct
+    ///     from the live event stream — historical rows come from an event historian (Galaxy's
+    ///     Alarm Provider history log, etc.) rather than the driver's active subscription.
+    /// </summary>
+    /// <param name="sourceName">
+    ///     Optional filter: null means "all sources", otherwise restrict to events from that
+    ///     source-object name. Drivers may ignore the filter if the backend doesn't support it.
+    /// </param>
+    /// <param name="startUtc">Inclusive lower bound on <c>EventTimeUtc</c>.</param>
+    /// <param name="endUtc">Exclusive upper bound on <c>EventTimeUtc</c>.</param>
+    /// <param name="maxEvents">Upper cap on returned events — the driver's backend enforces this.</param>
+    /// <param name="cancellationToken">Request cancellation.</param>
+    /// <remarks>
+    ///     Default implementation throws. Only drivers with an event historian (Galaxy via the
+    ///     Wonderware Alarm &amp; Events log) override. Modbus / the OPC UA Client driver stay
+    ///     with the default and let callers see <c>BadHistoryOperationUnsupported</c>.
+    /// </remarks>
+    Task<HistoricalEventsResult> ReadEventsAsync(
+        string? sourceName,
+        DateTime startUtc,
+        DateTime endUtc,
+        int maxEvents,
+        CancellationToken cancellationToken)
+        => throw new NotSupportedException(
+            $"{GetType().Name} does not implement ReadEventsAsync. " +
+            "Drivers whose backends have an event historian override this method.");
 }

 /// <summary>Result of a HistoryRead call.</summary>
@@ -48,3 +94,29 @@ public enum HistoryAggregateType
    Total,
    Count,
 }
+
+/// <summary>
+///     One row returned by <see cref="IHistoryProvider.ReadEventsAsync"/> — a historical
+///     alarm/event record, not the OPC UA live-event stream. Fields match the minimum set the
+///     Server needs to populate a <c>HistoryEventFieldList</c> for HistoryReadEvents responses.
+/// </summary>
+/// <param name="EventId">Stable unique id for the event — driver-specific format.</param>
+/// <param name="SourceName">Source object that emitted the event. May differ from the <c>sourceName</c> filter the caller passed (fuzzy matches).</param>
+/// <param name="EventTimeUtc">Process-side timestamp — when the event actually occurred.</param>
+/// <param name="ReceivedTimeUtc">Historian-side timestamp — when the historian persisted the row; may lag <paramref name="EventTimeUtc"/> by the historian's buffer flush cadence.</param>
+/// <param name="Message">Human-readable message text.</param>
+/// <param name="Severity">OPC UA severity (1-1000). Drivers map their native priority scale onto this range.</param>
+public sealed record HistoricalEvent(
+    string EventId,
+    string? SourceName,
+    DateTime EventTimeUtc,
+    DateTime ReceivedTimeUtc,
+    string? Message,
+    ushort Severity);
+
+/// <summary>Result of a <see cref="IHistoryProvider.ReadEventsAsync"/> call.</summary>
+/// <param name="Events">Events in chronological order by <c>EventTimeUtc</c>.</param>
+/// <param name="ContinuationPoint">Opaque token for the next call when more events are available; null when complete.</param>
+public sealed record HistoricalEventsResult(
+    IReadOnlyList<HistoricalEvent> Events,
+    byte[]? ContinuationPoint);
--- a/src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Proxy/GalaxyProxyDriver.cs
+++ b/src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Proxy/GalaxyProxyDriver.cs
@@ -339,6 +339,64 @@ public sealed class GalaxyProxyDriver(GalaxyProxyOptions options)
        return new HistoryReadResult(samples, ContinuationPoint: null);
    }

+    public async Task<HistoryReadResult> ReadAtTimeAsync(
+        string fullReference, IReadOnlyList<DateTime> timestampsUtc, CancellationToken cancellationToken)
+    {
+        var client = RequireClient();
+        var resp = await client.CallAsync<HistoryReadAtTimeRequest, HistoryReadAtTimeResponse>(
+            MessageKind.HistoryReadAtTimeRequest,
+            new HistoryReadAtTimeRequest
+            {
+                SessionId = _sessionId,
+                TagReference = fullReference,
+                TimestampsUtcUnixMs = [.. timestampsUtc.Select(t => new DateTimeOffset(t, TimeSpan.Zero).ToUnixTimeMilliseconds())],
+            },
+            MessageKind.HistoryReadAtTimeResponse,
+            cancellationToken);
+
+        if (!resp.Success)
+            throw new InvalidOperationException($"Galaxy.Host HistoryReadAtTime failed: {resp.Error}");
+
+        // ReadAtTime returns one sample per requested timestamp in the same order — the Host
+        // pads with bad-quality snapshots when a timestamp can't be interpolated, so response
+        // length matches request length exactly. We trust that contract rather than
+        // re-aligning here, because the Host is the source-of-truth for interpolation policy.
+        IReadOnlyList<DataValueSnapshot> samples = [.. resp.Values.Select(ToSnapshot)];
+        return new HistoryReadResult(samples, ContinuationPoint: null);
+    }
+
+    public async Task<HistoricalEventsResult> ReadEventsAsync(
+        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken cancellationToken)
+    {
+        var client = RequireClient();
+        var resp = await client.CallAsync<HistoryReadEventsRequest, HistoryReadEventsResponse>(
+            MessageKind.HistoryReadEventsRequest,
+            new HistoryReadEventsRequest
+            {
+                SessionId = _sessionId,
+                SourceName = sourceName,
+                StartUtcUnixMs = new DateTimeOffset(startUtc, TimeSpan.Zero).ToUnixTimeMilliseconds(),
+                EndUtcUnixMs = new DateTimeOffset(endUtc, TimeSpan.Zero).ToUnixTimeMilliseconds(),
+                MaxEvents = maxEvents,
+            },
+            MessageKind.HistoryReadEventsResponse,
+            cancellationToken);
+
+        if (!resp.Success)
+            throw new InvalidOperationException($"Galaxy.Host HistoryReadEvents failed: {resp.Error}");
+
+        IReadOnlyList<HistoricalEvent> events = [.. resp.Events.Select(ToHistoricalEvent)];
+        return new HistoricalEventsResult(events, ContinuationPoint: null);
+    }
+
+    internal static HistoricalEvent ToHistoricalEvent(GalaxyHistoricalEvent wire) => new(
+        EventId: wire.EventId,
+        SourceName: wire.SourceName,
+        EventTimeUtc: DateTimeOffset.FromUnixTimeMilliseconds(wire.EventTimeUtcUnixMs).UtcDateTime,
+        ReceivedTimeUtc: DateTimeOffset.FromUnixTimeMilliseconds(wire.ReceivedTimeUtcUnixMs).UtcDateTime,
+        Message: wire.DisplayText,
+        Severity: wire.Severity);
+
    /// <summary>
    ///     Maps the OPC UA Part 13 aggregate enum onto the Wonderware Historian
    ///     AnalogSummaryQuery column names consumed by <c>HistorianDataSource.ReadAggregateAsync</c>.