scadaproj/ZB.MOM.WW.SPHistorianClient/src/ZB.MOM.WW.SPHistorianClient/HistorianClient.cs

using ZB.MOM.WW.SPHistorianClient.Models;
using ZB.MOM.WW.SPHistorianClient.Protocol;
using ZB.MOM.WW.SPHistorianClient.Transport;
using ZB.MOM.WW.SPHistorianClient.Wcf;

namespace ZB.MOM.WW.SPHistorianClient;

public sealed class HistorianClient : IAsyncDisposable
{
    private readonly HistorianClientOptions _options;
    private readonly IHistorianTransportFactory _transportFactory;
    private readonly Historian2020ProtocolDialect _protocol;

    public HistorianClient(HistorianClientOptions options)
        : this(options, TcpHistorianTransport.Factory)
    {
    }

    internal HistorianClient(HistorianClientOptions options, IHistorianTransportFactory transportFactory)
    {
        _options = options ?? throw new ArgumentNullException(nameof(options));
        _transportFactory = transportFactory ?? throw new ArgumentNullException(nameof(transportFactory));
        _protocol = new Historian2020ProtocolDialect(_options);
    }

    public async Task<bool> ProbeAsync(CancellationToken cancellationToken = default)
    {
        return await HistorianWcfProbe.ProbeAsync(_options, cancellationToken).ConfigureAwait(false);
    }

    public IAsyncEnumerable<HistorianSample> ReadRawAsync(
        string tag,
        DateTime startUtc,
        DateTime endUtc,
        int maxValues,
        CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxValues);
        ValidateTimeRange(startUtc, endUtc);

        return _protocol.ReadRawAsync(tag, startUtc, endUtc, maxValues, cancellationToken);
    }

    public IAsyncEnumerable<HistorianAggregateSample> ReadAggregateAsync(
        string tag,
        DateTime startUtc,
        DateTime endUtc,
        RetrievalMode mode,
        TimeSpan interval,
        CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
        ArgumentOutOfRangeException.ThrowIfLessThanOrEqual(interval, TimeSpan.Zero);
        ValidateTimeRange(startUtc, endUtc);

        return _protocol.ReadAggregateAsync(tag, startUtc, endUtc, mode, interval, cancellationToken);
    }

    public Task<IReadOnlyList<HistorianSample>> ReadAtTimeAsync(
        string tag,
        IReadOnlyList<DateTime> timestampsUtc,
        CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
        ArgumentNullException.ThrowIfNull(timestampsUtc);

        if (timestampsUtc.Count == 0)
        {
            return Task.FromResult<IReadOnlyList<HistorianSample>>(Array.Empty<HistorianSample>());
        }

        return _protocol.ReadAtTimeAsync(tag, timestampsUtc, cancellationToken);
    }

    public IAsyncEnumerable<HistorianBlock> ReadBlocksAsync(
        string tag,
        DateTime startUtc,
        DateTime endUtc,
        CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
        ValidateTimeRange(startUtc, endUtc);
        return _protocol.ReadBlocksAsync(tag, startUtc, endUtc, cancellationToken);
    }

    public IAsyncEnumerable<HistorianEvent> ReadEventsAsync(
        DateTime startUtc,
        DateTime endUtc,
        CancellationToken cancellationToken = default)
    {
        ValidateTimeRange(startUtc, endUtc);
        return _protocol.ReadEventsAsync(startUtc, endUtc, cancellationToken);
    }

    public IAsyncEnumerable<string> BrowseTagNamesAsync(string filter = "*", CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(filter);
        return HistorianWcfTagClient.BrowseTagNamesAsync(_options, filter, cancellationToken);
    }

    public Task<HistorianTagMetadata?> GetTagMetadataAsync(string tag, CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(tag);
        return HistorianWcfTagClient.GetTagMetadataAsync(_options, tag, cancellationToken);
    }

    public Task<HistorianConnectionStatus> GetConnectionStatusAsync(CancellationToken cancellationToken = default)
    {
        return _protocol.GetConnectionStatusAsync(cancellationToken);
    }

    public Task<HistorianStoreForwardStatus> GetStoreForwardStatusAsync(CancellationToken cancellationToken = default)
    {
        return _protocol.GetStoreForwardStatusAsync(cancellationToken);
    }

    public Task<string?> GetSystemParameterAsync(string name, CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(name);
        return _protocol.GetSystemParameterAsync(name, cancellationToken);
    }

    /// <summary>
    /// Creates or updates the named tag in the Historian Runtime database via
    /// <c>EnsureTags2</c>. Currently only <see cref="HistorianDataType.Float"/> is
    /// live-verified. Note: writing data values to the new tag (via a separate
    /// AddStreamedValue/AddS2 path) is NOT supported by the SDK — see
    /// <c>docs/plans/write-commands-reverse-engineering.md</c> for the architectural
    /// finding.
    /// </summary>
    public Task<bool> EnsureTagAsync(HistorianTagDefinition definition, CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(definition);
        return new HistorianWcfTagWriteOrchestrator(_options).EnsureTagAsync(definition, cancellationToken);
    }

    /// <summary>
    /// Deletes the named tag via <c>DeleteTags</c>. **Known issue (2026-05-04):**
    /// the SDK's DelT call returns true but the server-side cascading deletion does
    /// not always complete (the row remains in <c>Runtime.dbo.Tag</c>). The
    /// captured native flow's DelT removes the tag cleanly, so additional priming
    /// or a side call between WCF DelT and server cascade is missing. Use the SMC
    /// fallback to clean up sandbox tags until this is resolved.
    /// </summary>
    public Task<bool> DeleteTagAsync(string tagName, CancellationToken cancellationToken = default)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(tagName);
        return new HistorianWcfTagWriteOrchestrator(_options).DeleteTagAsync(tagName, cancellationToken);
    }

    public ValueTask DisposeAsync()
    {
        return ValueTask.CompletedTask;
    }

    private static void ValidateTimeRange(DateTime startUtc, DateTime endUtc)
    {
        if (startUtc.ToUniversalTime() > endUtc.ToUniversalTime())
        {
            throw new ArgumentException("Start time must be less than or equal to end time.");
        }
    }

}