lmxopcua/src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IHistoryProvider.cs

namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;

/// <summary>
///     Driver capability for historical-data reads (OPC UA HistoryRead). Optional —
///     only drivers whose backends carry historian data implement this. Currently:
///     Galaxy (Wonderware Historian via the optional plugin), OPC UA Client (forward
///     to upstream server).
/// </summary>
public interface IHistoryProvider
{
    /// <summary>
    ///     Read raw historical samples for a single attribute over a time range.
    ///     The Core wraps this with continuation-point handling.
    /// </summary>
    Task<HistoryReadResult> ReadRawAsync(
        string fullReference,
        DateTime startUtc,
        DateTime endUtc,
        uint maxValuesPerNode,
        CancellationToken cancellationToken);

    /// <summary>
    ///     Read processed (aggregated) samples — interval-bucketed average / min / max / etc.
    ///     Optional — drivers that only support raw history can throw <see cref="NotSupportedException"/>.
    /// </summary>
    Task<HistoryReadResult> ReadProcessedAsync(
        string fullReference,
        DateTime startUtc,
        DateTime endUtc,
        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>
/// <param name="Samples">Returned samples in chronological order.</param>
/// <param name="ContinuationPoint">Opaque token for the next call when more samples are available; null when complete.</param>
public sealed record HistoryReadResult(
    IReadOnlyList<DataValueSnapshot> Samples,
    byte[]? ContinuationPoint);

/// <summary>Aggregate function for processed history reads. Mirrors OPC UA Part 13 standard aggregates.</summary>
public enum HistoryAggregateType
{
    Average,
    Minimum,
    Maximum,
    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);