Merge feat/675-reverse-event-paging: reverse event HistoryRead paging, end-only backward, Gateway MaxValue pin (#675)

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway/GatewayHistorianDataSource.cs

@@ -125,6 +125,21 @@ public sealed class GatewayHistorianDataSource : IHistorianDataSource, IAsyncDis
         }
     }
 
+    /// <inheritdoc />
+    /// <remarks>
+    ///     A reverse (newest-first) read is refused with <see cref="NotSupportedException"/> — the server reports
+    ///     <c>BadHistoryOperationUnsupported</c> (Gitea #675). The gateway's <c>ReadEvents</c> streams ascending only and
+    ///     rejects <c>end &lt; start</c>, so the only way to serve "the latest N" would be to drain the whole window and
+    ///     keep its tail, an unbounded read the cap exists to prevent. Nothing is sent.
+    /// </remarks>
+    public Task<HistoricalEventsResult> ReadEventsAsync(
+        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, bool reverse,
+        CancellationToken cancellationToken) =>
+        reverse
+            ? throw new NotSupportedException(
+                "The HistorianGateway backend reads events oldest-first only; a reverse (newest-first) events read is not supported.")
+            : ReadEventsAsync(sourceName, startUtc, endUtc, maxEvents, cancellationToken);
+
     /// <inheritdoc />
     public async Task<HistoricalEventsResult> ReadEventsAsync(
         string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents,

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb/QuestDbHistorianDataSource.cs

@@ -361,8 +361,18 @@ public sealed class QuestDbHistorianDataSource : IHistorianDataSource
     ///     <c>maxEvents + 1</c> rows are fetched; when the extra row arrives it is dropped and the continuation point is
     ///     the UTF-8 of <see cref="EventContinuation.Encode"/> for that first not-returned event.
     /// </remarks>
+    public Task<HistoricalEventsResult> ReadEventsAsync(
+        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken cancellationToken) =>
+        ReadEventsAsync(sourceName, startUtc, endUtc, maxEvents, reverse: false, cancellationToken);
+
+    /// <inheritdoc />
+    /// <remarks>
+    ///     Forward is the five-argument read. Reverse (Gitea #675) is the (rounded) <c>(lo, hi]</c> ordered by
+    ///     <c>(ts, event_id)</c> DESCENDING, so <c>LIMIT</c> keeps the latest events; truncation and the continuation point
+    ///     work as forward.
+    /// </remarks>
     public async Task<HistoricalEventsResult> ReadEventsAsync(
-        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken cancellationToken)
+        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, bool reverse, CancellationToken cancellationToken)
     {
         // No stored event can carry a source longer than the limit, so an over-long filter matches nothing.
         if (sourceName is not null && sourceName.Length > HistorianTagNames.MaxLength)
@@ -376,9 +386,9 @@ public sealed class QuestDbHistorianDataSource : IHistorianDataSource
             var bounded = maxEvents > 0 && maxEvents < int.MaxValue;
             var sql =
                 $"SELECT event_id, source, ts, received_utc, message, severity FROM {_conn.EventTable} " +
-                "WHERE ts >= $1 AND ts < $2" +
+                (reverse ? "WHERE ts > $1 AND ts <= $2" : "WHERE ts >= $1 AND ts < $2") +
                 (sourceName is null ? "" : " AND source = $3") +
-                " ORDER BY ts ASC, event_id ASC" +
+                (reverse ? " ORDER BY ts DESC, event_id DESC" : " ORDER BY ts ASC, event_id ASC") +
                 (bounded ? (sourceName is null ? " LIMIT $3" : " LIMIT $4") : "");
 
             await using var conn = await _conn.OpenAsync(cancellationToken).ConfigureAwait(false);

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.SqlServer/SqlServerHistorianDataSource.cs

@@ -320,8 +320,18 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource
     ///     of <c>"{EventTimeUtc.Ticks}|{EventId}"</c> of that first not-returned event (opaque to callers; only
     ///     its presence is contractual).
     /// </remarks>
+    public Task<HistoricalEventsResult> ReadEventsAsync(
+        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken cancellationToken) =>
+        ReadEventsAsync(sourceName, startUtc, endUtc, maxEvents, reverse: false, cancellationToken);
+
+    /// <inheritdoc />
+    /// <remarks>
+    ///     Forward is the five-argument read. Reverse (Gitea #675) is <c>(lo, hi]</c> ordered by
+    ///     <c>(EventTimeUtc, EventId)</c> DESCENDING — the clustered index scanned backwards — so <c>TOP</c> keeps the latest
+    ///     events; truncation and the continuation point work as forward.
+    /// </remarks>
     public async Task<HistoricalEventsResult> ReadEventsAsync(
-        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, CancellationToken cancellationToken)
+        string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, bool reverse, CancellationToken cancellationToken)
     {
         // No stored event can carry a source longer than the column (the alarm writer dead-letters it rather than
         // truncating), so an over-long filter matches nothing — never a truncated prefix of someone else's source.
@@ -334,9 +344,10 @@ public sealed class SqlServerHistorianDataSource : IHistorianDataSource
             var bounded = maxEvents > 0 && maxEvents < int.MaxValue;
             var sql =
                 $"SELECT {(bounded ? "TOP (@take) " : "")}EventId, SourceName, EventTimeUtc, ReceivedTimeUtc, Message, Severity " +
-                $"FROM {_conn.Q("Event")} WHERE EventTimeUtc >= @lo AND EventTimeUtc < @hi" +
+                $"FROM {_conn.Q("Event")} WHERE " +
+                (reverse ? "EventTimeUtc > @lo AND EventTimeUtc <= @hi" : "EventTimeUtc >= @lo AND EventTimeUtc < @hi") +
                 (sourceName is null ? "" : " AND SourceName = @source") +
-                " ORDER BY EventTimeUtc ASC, EventId ASC";
+                (reverse ? " ORDER BY EventTimeUtc DESC, EventId DESC" : " ORDER BY EventTimeUtc ASC, EventId ASC");
 
             await using var conn = await _conn.OpenAsync(cancellationToken).ConfigureAwait(false);
             await using var cmd = _conn.CreateCommand(conn, sql);