fix(historian): address code review on Raw HistoryRead paging

C1 (critical): a boundary tie cluster larger than NumValuesPerNode could
silently truncate a resumed read to GoodNoData, permanently dropping the
un-emitted ties — the (timestamp, skip) cursor cannot advance past a single
timestamp the fixed-(start,end,cap) backend keeps re-returning. Now detected
and failed LOUDLY per node with BadHistoryOperationUnsupported + a log naming
the tag/timestamp/cap; documented in Historian.md with the larger-cap remedy.
Regression test Raw_tie_cluster_larger_than_page_fails_loudly_not_silently.

I3: build HistoryData before Save() so a projection failure can never orphan a
stored continuation cursor.

N1 (YAGNI): drop the never-produced HistoryReadKind enum + Processed-only
Aggregate/IntervalTicks fields from HistoryContinuationState — only Raw pages.

N3: ComputeResumeCursor guards its documented non-empty precondition.

I1: document InMemoryHistoryContinuationStore's eventual-consistency (test double).

Build clean, 182/182 OpcUaServer tests pass.
This commit is contained in:
Joseph Doherty
2026-06-15 05:15:07 -04:00
parent 94c3ca60fc
commit bea0b482d4
6 changed files with 101 additions and 36 deletions
@@ -3,25 +3,12 @@ using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;
/// <summary>
/// The kind of variable-history read a continuation point resumes. Only the two count-capped,
/// time-range arms page server-side (see <see cref="HistoryPaging"/>); AtTime is single-shot
/// (no client count cap, so there is never a "full page" signal to page on) and never produces a
/// continuation point, so it has no entry here.
/// </summary>
internal enum HistoryReadKind
{
/// <summary>HistoryRead-Raw — resumes via <see cref="IHistorianDataSource.ReadRawAsync"/>.</summary>
Raw,
/// <summary>HistoryRead-Processed — resumes via <see cref="IHistorianDataSource.ReadProcessedAsync"/>.</summary>
Processed,
}
/// <summary>
/// The server-side resume state stored behind an opaque continuation point for a single
/// paged variable-history read. Captures exactly enough to continue the SAME logical read from
/// where the previous page stopped: the read kind + tagname, the original (inclusive) end of the
/// window, the next start of the window, and — for Processed — the aggregate + interval.
/// The server-side resume state stored behind an opaque continuation point for a single paged
/// HistoryRead-Raw read. Captures exactly enough to continue the SAME logical read from where the
/// previous page stopped: the tagname, the original (inclusive) end of the window, the next start of
/// the window, and the tie-safe boundary skip. (Only Raw pages server-side — Processed and AtTime
/// carry no client count cap, so they are single-shot and never produce a continuation point; see
/// <see cref="HistoryPaging"/>.)
/// <para>
/// The boundary fields (<see cref="NextStartUtc"/> + <see cref="BoundarySkipCount"/>) encode a
/// tie-safe resume cursor: the next page reads from <see cref="NextStartUtc"/> INCLUSIVE and
@@ -34,7 +21,6 @@ internal enum HistoryReadKind
/// cheap value that unit tests can drive directly.
/// </para>
/// </summary>
/// <param name="Kind">Which variable-history arm this state resumes.</param>
/// <param name="Tagname">The resolved historian tagname (NOT the NodeId) to read from.</param>
/// <param name="NextStartUtc">
/// Inclusive lower bound for the next page — the boundary timestamp the previous page stopped on.
@@ -45,17 +31,12 @@ internal enum HistoryReadKind
/// prior pages and must be dropped from the head of the next page (tie de-dup).
/// </param>
/// <param name="NumValuesPerNode">The client's per-page cap; re-applied to every resumed page.</param>
/// <param name="Aggregate">The aggregate for a Processed read; ignored for Raw.</param>
/// <param name="IntervalTicks">The Processed bucketing interval in ticks; ignored for Raw.</param>
internal sealed record HistoryContinuationState(
HistoryReadKind Kind,
string Tagname,
DateTime NextStartUtc,
DateTime EndUtc,
int BoundarySkipCount,
uint NumValuesPerNode,
HistoryAggregateType Aggregate,
long IntervalTicks);
uint NumValuesPerNode);
/// <summary>
/// Pure server-side continuation-point paging decisions for the count-capped variable-history arms
@@ -111,6 +92,11 @@ internal static class HistoryPaging
out DateTime nextStartUtc,
out int boundarySkipCount)
{
// Enforce the documented precondition at the API boundary rather than relying on the caller's guard
// (the only caller only pages a full, non-empty page, but this is a public static helper).
if (page.Count == 0)
throw new ArgumentOutOfRangeException(nameof(page), "ComputeResumeCursor requires a non-empty page.");
// The boundary is the last returned sample's SourceTimestamp. A sample whose SourceTimestamp is
// null (Bad/unset) cannot anchor a time cursor; fall back to MinValue so the next read covers the
// whole remaining window rather than silently dropping data — duplicates are then de-duped by the