lmxopcua/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/HistoryBounds.cs

using Opc.Ua;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;

namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;

/// <summary>
///     The end bound still owed to a HistoryRead-Raw read with <c>ReturnBounds = true</c> (Gitea #691). It rides the
///     continuation point, because Part 11 returns the end bound with the LAST page only.
/// </summary>
/// <param name="AtUtc">The request's end time (the later bound of a forward read, the earlier of a reverse one).</param>
/// <param name="Reverse">The read is newest-first (<c>StartTime &gt; EndTime</c>, including an end-only read).</param>
/// <param name="Inclusive">
///     <c>false</c> only for <c>StartTime == EndTime</c>: the samples AT that instant are the data, so the end bound is the
///     first sample strictly after it (Part 11 Table 1 footnote c). Otherwise the end bound is the sample at or beyond the
///     end time, and the data window excludes the end time.
/// </param>
/// <param name="Open">The end time was not given (a one-sided read's sentinel): there is no end bound to look up.</param>
/// <param name="DataExhausted">The data is drained and the end bound did not fit on the previous page.</param>
/// <param name="LastReturnedUtc">The last value's time returned on an earlier page (stamps an open bound's placeholder).</param>
/// <param name="Resolved">
///     Gitea #692: the end bound an earlier page already looked up (a stored sample — never a placeholder), so the page that
///     returns it does not read the backend again. <c>null</c> = not looked up yet.
/// </param>
internal sealed record HistoryEndBound(
    DateTime AtUtc, bool Reverse, bool Inclusive, bool Open, bool DataExhausted = false, DateTime? LastReturnedUtc = null,
    DataValueSnapshot? Resolved = null);

/// <summary>
///     Gitea #691: OPC UA Part 11 bounding values for HistoryRead-Raw (<c>ReadRawModifiedDetails.ReturnBounds</c>), composed
///     in the server from every backend's existing raw read — the ONE authority, so SqlServer, QuestDB, Gateway and Null
///     answer identically.
/// </summary>
/// <remarks>
///     <para>
///         <b>What a bound is</b> (Part 11 §4.6, Table 1). Forward: the start bound is the stored sample AT or immediately
///         BEFORE StartTime, the end bound the one AT or immediately AFTER EndTime. Reverse mirrors it: the start bound is at
///         or after StartTime, the end bound at or before EndTime. A sample exactly on a bound IS the bound: on the start it
///         is already the first sample of the data (the window includes StartTime), so nothing extra is added; on the end it is
///         added (the window excludes EndTime). <c>StartTime == EndTime</c> reads forward, and its end bound is the first
///         sample strictly after the instant. A bound is a stored sample of any quality — a Bad sample is returned as stored.
///     </para>
///     <para>
///         <b>Missing bound.</b> <c>Bad_BoundNotFound</c>, a null value, stamped with the bound's time. A one-sided read's
///         missing side (no EndTime / no StartTime) is never looked up; it is <c>Bad_BoundNotFound</c> stamped one second after
///         (forward) or before (reverse) the previous returned value (Table 1 footnotes a and b).
///     </para>
///     <para>
///         <b>Lookups.</b> "At or before T" is a newest-first read of <c>(0, T]</c> capped at one — native on a backend that
///         declares <see cref="IHistorianDataSource.SupportsReverseRaw"/>, otherwise <see cref="ReverseRawReader"/>'s walk-back
///         from bounded forward reads (the Gateway: NOT AVEVA's synthetic boundary row, which is stamped at the query start
///         rather than at the prior sample's own time). "At or after T" is a forward read of <c>[T, MaxValue)</c> capped at one (on a
///         forward-only backend ending at now + <see cref="ReverseRawReader.LookAhead"/> instead — #691 review);
///         "strictly after T" starts one storage resolution later (lossless: nothing is stored in between). Inside a tie
///         cluster the bound is the cluster's first sample in the read's direction — the forward read's first, the reverse
///         read's first (the forward order's last).
///     </para>
///     <para>
///         <b>Resolution.</b> "On the bound" compares at the backend's storage resolution, because a microsecond backend
///         (QuestDB) truncates the window bounds it is sent: a sample at <c>⌊T⌋</c> is inside a window starting at <c>T</c>
///         there, so it must not also be returned as the start bound.
///     </para>
/// </remarks>
internal static class HistoryBounds
{
    private static readonly TimeSpan OpenBoundStep = TimeSpan.FromSeconds(1);

    /// <summary>
    ///     Gitea #692: the placeholders this server synthesised (<see cref="NotFound"/>), by reference. A placeholder is known by
    ///     this marker, never by its shape: a stored row can legitimately carry <c>Bad_BoundNotFound</c> with a null value (a
    ///     client may write one through HistoryUpdate), and that row is data.
    /// </summary>
    private static readonly System.Runtime.CompilerServices.ConditionalWeakTable<DataValueSnapshot, object> Placeholders = new();

    private static readonly object PlaceholderMark = new();

    /// <summary>The end bound owed by a fresh read over the normalised window.</summary>
    /// <param name="startUtc">The (normalised) start: the later time of a reverse read.</param>
    /// <param name="endUtc">The (normalised) end; a one-sided read's sentinel (tick 0 / MaxValue) is an open bound.</param>
    /// <returns>The pending end bound.</returns>
    public static HistoryEndBound For(DateTime startUtc, DateTime endUtc) =>
        new(endUtc, Reverse: startUtc > endUtc, Inclusive: startUtc != endUtc, Open: IsOpen(endUtc));

    /// <summary>
    ///     Whether a returned value is a <see cref="NotFound"/> placeholder this server synthesised rather than a stored sample
    ///     — by an explicit marker (#692), so a stored row whose status happens to be <c>Bad_BoundNotFound</c> is not taken for one.
    /// </summary>
    /// <param name="value">The value.</param>
    /// <returns><c>true</c> only for an instance <see cref="NotFound"/> produced.</returns>
    public static bool IsPlaceholder(DataValueSnapshot value) => Placeholders.TryGetValue(value, out _);

    /// <summary>The pending end bound to store behind a continuation point, remembering the page's last returned time.</summary>
    /// <param name="bound">The pending end bound (null = bounds not requested).</param>
    /// <param name="page">The page being returned.</param>
    /// <returns>The bound to carry, or null.</returns>
    public static HistoryEndBound? Carry(HistoryEndBound? bound, IReadOnlyList<DataValueSnapshot> page) =>
        bound is null || page.Count == 0 || page[^1].SourceTimestampUtc is not { } last
            ? bound
            : bound with { LastReturnedUtc = last };

    /// <summary>The <c>Bad_BoundNotFound</c> placeholder (null value) stamped at <paramref name="atUtc"/>.</summary>
    /// <param name="atUtc">The bound's time.</param>
    /// <returns>The placeholder.</returns>
    public static DataValueSnapshot NotFound(DateTime atUtc)
    {
        var placeholder = new DataValueSnapshot(null, StatusCodes.BadBoundNotFound, atUtc, atUtc);
        Placeholders.AddOrUpdate(placeholder, PlaceholderMark);
        return placeholder;
    }

    /// <summary>
    ///     The start bound to return ahead of the data, or <c>null</c> when a stored sample sits on StartTime (that sample is
    ///     the bound, and it is already the data's first sample).
    /// </summary>
    public static async Task<DataValueSnapshot?> StartBoundAsync(
        IHistorianDataSource source, string tagname, DateTime startUtc, bool reverse, int maxTieCluster, DateTime nowUtc,
        CancellationToken ct)
    {
        if (IsOpen(startUtc)) return NotFound(startUtc);
        var found = reverse
            ? await EarliestAtOrAfterAsync(source, tagname, startUtc, nowUtc, ct).ConfigureAwait(false)
            : await LatestAtOrBeforeAsync(source, tagname, startUtc, maxTieCluster, nowUtc, ct).ConfigureAwait(false);
        if (found is null) return NotFound(startUtc);
        return SameInstant(Ticks(found), startUtc.Ticks, Resolution(source)) ? null : found;
    }

    /// <summary>The end bound: the stored sample on or beyond the end time, else the placeholder.</summary>
    /// <param name="source">The backend.</param>
    /// <param name="tagname">Historian tag.</param>
    /// <param name="bound">The pending end bound.</param>
    /// <param name="previousReturnedUtc">The last value's time already returned (stamps an open bound's placeholder).</param>
    /// <param name="maxTieCluster">The walk-back's row budget (forward-only backends).</param>
    /// <param name="nowUtc">Now (the walk-back's look-ahead clamp).</param>
    /// <param name="ct">Cancellation.</param>
    public static async Task<DataValueSnapshot> EndBoundAsync(
        IHistorianDataSource source, string tagname, HistoryEndBound bound, DateTime previousReturnedUtc,
        int maxTieCluster, DateTime nowUtc, CancellationToken ct)
    {
        if (bound.Open)
        {
            var ticks = bound.Reverse
                ? Math.Max(0L, previousReturnedUtc.Ticks - OpenBoundStep.Ticks)
                : Math.Min(DateTime.MaxValue.Ticks, previousReturnedUtc.Ticks + OpenBoundStep.Ticks);
            return NotFound(new DateTime(ticks, DateTimeKind.Utc));
        }

        if (bound.Resolved is { } resolved) return resolved; // #692: an earlier page already looked it up

        DataValueSnapshot? found;
        if (bound.Reverse)
            found = await LatestAtOrBeforeAsync(source, tagname, bound.AtUtc, maxTieCluster, nowUtc, ct).ConfigureAwait(false);
        else if (bound.Inclusive)
            found = await EarliestAtOrAfterAsync(source, tagname, bound.AtUtc, nowUtc, ct).ConfigureAwait(false);
        else
        {
            var resolution = Resolution(source);
            found = bound.AtUtc.Ticks > DateTime.MaxValue.Ticks - resolution
                ? null
                : await EarliestAtOrAfterAsync(source, tagname, bound.AtUtc.AddTicks(resolution), nowUtc, ct).ConfigureAwait(false);
        }

        return found ?? NotFound(bound.AtUtc);
    }

    /// <summary>
    ///     Whether a data sample lies inside the data window of a bounded read — a forward window excludes the end time (a
    ///     sample there is the end bound), compared at the storage resolution. A backend whose forward end is inclusive, or a
    ///     resumed read that steps onto the end time, would otherwise return the end bound twice.
    /// </summary>
    public static bool InDataWindow(DataValueSnapshot sample, HistoryEndBound bound, long resolution)
    {
        if (!bound.Inclusive || bound.Open) return true;
        var ts = Align(Ticks(sample), resolution);
        var end = Align(bound.AtUtc.Ticks, resolution);
        return bound.Reverse ? ts > end : ts < end;
    }

    /// <summary>Whether a resumed read's next start is already past the data window (only the end bound remains).</summary>
    public static bool DataWindowDrained(DateTime nextStartUtc, HistoryEndBound bound, long resolution)
    {
        if (!bound.Inclusive || bound.Open) return false;
        var next = Align(nextStartUtc.Ticks, resolution);
        var end = Align(bound.AtUtc.Ticks, resolution);
        return bound.Reverse ? next <= end : next >= end;
    }

    /// <summary>The latest stored sample at or before <paramref name="atUtc"/>, or null.</summary>
    internal static async Task<DataValueSnapshot?> LatestAtOrBeforeAsync(
        IHistorianDataSource source, string tagname, DateTime atUtc, int maxTieCluster, DateTime nowUtc, CancellationToken ct)
    {
        if (atUtc.Ticks == 0) return null;
        var floor = new DateTime(0, DateTimeKind.Utc);
        IReadOnlyList<DataValueSnapshot> rows = source.SupportsReverseRaw
            ? (await source.ReadRawAsync(tagname, atUtc, floor, 1, ct).ConfigureAwait(false)).Samples
            : (await ReverseRawReader.ReadAsync(source, tagname, atUtc, floor, 1, maxTieCluster, nowUtc, 0, ct)
                .ConfigureAwait(false)).Samples;
        var limit = Align(atUtc.Ticks, Resolution(source));
        foreach (var row in rows)
            if (Align(Ticks(row), Resolution(source)) <= limit)
                return row;
        return null;
    }

    /// <summary>The earliest stored sample at or after <paramref name="atUtc"/>, or null.</summary>
    /// <remarks>
    ///     #691 review: on a backend that reads forward only (the Gateway) the read's end is clamped to now +
    ///     <see cref="ReverseRawReader.LookAhead"/> — the same horizon the walk-back uses — and a time beyond it is "not found"
    ///     without a read. The HistorianGateway only checks <c>start &lt;= end</c>, so a <c>DateTime.MaxValue</c> end would
    ///     reach AVEVA as a year-9999 query end (unverified: a rejection, or a fabricated row). The clamp is NOT applied to a
    ///     backend that reads newest-first natively (SqlServer / QuestDB): they bind <c>MaxValue</c> safely (pinned by the
    ///     <c>Extreme_bounds</c> conformance test) and can legitimately hold samples further ahead (HistoryUpdate's
    ///     <c>HistoryUpdateMaxFutureSkew</c> is configurable, and driver-stamped live values carry device time) — clamping
    ///     there would turn a real end bound into <c>Bad_BoundNotFound</c>.
    /// </remarks>
    internal static async Task<DataValueSnapshot?> EarliestAtOrAfterAsync(
        IHistorianDataSource source, string tagname, DateTime atUtc, DateTime nowUtc, CancellationToken ct)
    {
        var endTicks = DateTime.MaxValue.Ticks;
        if (!source.SupportsReverseRaw)
            endTicks = nowUtc.Ticks > DateTime.MaxValue.Ticks - ReverseRawReader.LookAhead.Ticks
                ? DateTime.MaxValue.Ticks
                : nowUtc.Ticks + ReverseRawReader.LookAhead.Ticks;
        if (atUtc.Ticks >= endTicks) return null;
        var rows = (await source.ReadRawAsync(tagname, atUtc, new DateTime(endTicks, DateTimeKind.Utc), 1, ct)
            .ConfigureAwait(false)).Samples;
        var limit = Align(atUtc.Ticks, Resolution(source));
        foreach (var row in rows)
            if (Align(Ticks(row), Resolution(source)) >= limit)
                return row;
        return null;
    }

    private static bool IsOpen(DateTime t) => t.Ticks == 0 || t.Ticks == DateTime.MaxValue.Ticks;

    private static bool SameInstant(long a, long b, long resolution) => Align(a, resolution) == Align(b, resolution);

    private static long Resolution(IHistorianDataSource source) => Math.Max(1L, source.TimestampResolutionTicks);

    private static long Ticks(DataValueSnapshot s) => (s.SourceTimestampUtc ?? DateTime.MinValue).Ticks;

    private static long Align(long ticks, long resolution) => ticks - ticks % resolution;
}