feat(historian): Part 11 modified-value history on SqlServer + QuestDB (#668)

Every HistoryUpdate a SQL backend applies now leaves a modification trail (prior value, principal, Part 11 update type, modification time), and HistoryReadRaw with IsReadModified=true serves it as HistoryModifiedData. - Core: HistoryUpdateContext threaded into all three IHistorianDataUpdater methods; IHistorianDataSource.ReadModifiedAsync (default NotSupported => BadHistoryOperationUnsupported on Gateway/Null); HistoryModified* contracts. - SqlServer: schema v2 (002_sample_modified.sql, RequiredVersion=2, docs copy); trail written by OUTPUT ... INTO on the same MERGE/DELETE statement, so a failed update leaves no audit row; retention purges SampleModified per tag on the source-time cutoff; ReadModifiedAsync keyed on (SourceTimeUtc, ModifiedId). - QuestDB: append-only {prefix}sample_modified (TTL like samples), trail row written BEFORE the change (orphan-on-crash, never an untracked change); existence reads now carry the prior value; ReadModifiedAsync. - Node manager: modified reads dispatch + page via the #669 continuation store (HistoryContinuationState gains HistoryCursorKind + LastModifiedId), gated by the existing HistoryRead decision; session principal / key id passed to the updater. IsDeleteModified stays unsupported. - Client.CLI: historyread --modified. - Tests: node-manager dispatch/paging/cursor binding/principal threading, over-the-wire HistoryModifiedData, shared ModifiedValueConformance on both backends, SqlServer atomicity (forced trail failure => no change) + v1->v2 upgrade + retention trail purge. - Docs: Historian.md (Modified-value history section, schema v2 upgrade note), security.md, Client.CLI.md, CLAUDE.md.
2026-10-11 09:26:36 -04:00
parent d803e0eab4
commit cfd403710e
51 changed files with 2173 additions and 195 deletions
@@ -56,6 +56,13 @@ public class HistoryReadCommand : CommandBase
    [CommandOption("interval", Description = "Processing interval in milliseconds for aggregates")]
    public double IntervalMs { get; init; } = 3600000;

+    /// <summary>
+    /// Gets a value indicating whether to read modified-value history (Part 11 IsReadModified) instead of raw samples:
+    /// the prior value each HistoryUpdate replaced or deleted, with its update type, user and modification time.
+    /// </summary>
+    [CommandOption("modified", Description = "Read modified-value history (what HistoryUpdate changed: prior value, update type, user, time) instead of raw samples")]
+    public bool Modified { get; init; }
+
    /// <inheritdoc />
    public override async ValueTask ExecuteAsync(IConsole console)
    {
@@ -64,6 +71,8 @@ public class HistoryReadCommand : CommandBase
            throw new CommandException($"--max must be greater than 0 (was {MaxValues}).");
        if (!string.IsNullOrEmpty(Aggregate) && IntervalMs <= 0)
            throw new CommandException($"--interval must be greater than 0 (was {IntervalMs}).");
+        if (Modified && !string.IsNullOrEmpty(Aggregate))
+            throw new CommandException("--modified and --aggregate cannot be combined.");

        NodeId nodeId;
        try
@@ -119,6 +128,30 @@ public class HistoryReadCommand : CommandBase
            var ct = console.RegisterCancellationHandler();
            (service, _) = await CreateServiceAndConnectAsync(ct);

+            if (Modified)
+            {
+                await console.Output.WriteLineAsync(
+                    $"Modified history for {NodeId} ({start:yyyy-MM-dd HH:mm} -> {end:yyyy-MM-dd HH:mm})");
+                var entries = await service.HistoryReadModifiedAsync(nodeId, start, end, MaxValues, ct);
+                await console.Output.WriteLineAsync();
+                await console.Output.WriteLineAsync(
+                    $"{"Timestamp",-35} {"Prior value",-15} {"Status",-10} {"Update",-8} {"User",-20} {"Modified at"}");
+                foreach (var e in entries)
+                {
+                    var dv = e.Value;
+                    var status = StatusCode.IsGood(dv.StatusCode) ? "Good"
+                        : StatusCode.IsBad(dv.StatusCode) ? "Bad"
+                        : "Uncertain";
+                    await console.Output.WriteLineAsync(
+                        $"{dv.SourceTimestamp.ToString("O"),-35} {dv.Value?.ToString() ?? "(none)",-15} {status,-10} " +
+                        $"{e.UpdateType,-8} {e.UserName ?? "",-20} {e.ModificationTime:O}");
+                }
+
+                await console.Output.WriteLineAsync();
+                await console.Output.WriteLineAsync($"{entries.Count} modifications returned.");
+                return;
+            }
+
            IReadOnlyList<DataValue> values;

            if (string.IsNullOrEmpty(Aggregate))
@@ -206,6 +206,74 @@ internal sealed class DefaultSessionAdapter : ISessionAdapter
        return allValues;
    }

+    /// <inheritdoc />
+    public async Task<IReadOnlyList<Models.HistoryModifiedEntry>> HistoryReadModifiedAsync(
+        NodeId nodeId, DateTime startTime, DateTime endTime, int maxValues, CancellationToken ct)
+    {
+        var details = new ReadRawModifiedDetails
+        {
+            StartTime = startTime,
+            EndTime = endTime,
+            NumValuesPerNode = (uint)maxValues,
+            IsReadModified = true,
+            ReturnBounds = false
+        };
+
+        var nodesToRead = new HistoryReadValueIdCollection
+        {
+            new HistoryReadValueId { NodeId = nodeId }
+        };
+
+        var all = new List<Models.HistoryModifiedEntry>();
+        byte[]? continuationPoint = null;
+
+        do
+        {
+            if (continuationPoint != null)
+                nodesToRead[0].ContinuationPoint = continuationPoint;
+
+            var response = await _session.HistoryReadAsync(
+                null,
+                new ExtensionObject(details),
+                TimestampsToReturn.Both,
+                false,
+                nodesToRead,
+                ct).ConfigureAwait(false);
+
+            var results = response.Results;
+            if (results == null || results.Count == 0)
+                break;
+
+            var result = results[0];
+            HistoryReadStatus.ThrowIfRefused(result.StatusCode, nodeId);
+
+            if (result.HistoryData is ExtensionObject ext && ext.Body is HistoryModifiedData modified)
+            {
+                for (var i = 0; i < modified.DataValues.Count; i++)
+                {
+                    var info = i < modified.ModificationInfos.Count ? modified.ModificationInfos[i] : null;
+                    all.Add(new Models.HistoryModifiedEntry(
+                        modified.DataValues[i],
+                        info?.ModificationTime ?? DateTime.MinValue,
+                        info?.UpdateType ?? default,
+                        info?.UserName));
+                }
+            }
+
+            continuationPoint = result.ContinuationPoint;
+        } while (continuationPoint != null && continuationPoint.Length > 0 && all.Count < maxValues);
+
+        // A read stopped by the client's own cap leaves a server cursor behind; release it.
+        if (continuationPoint is { Length: > 0 })
+        {
+            nodesToRead[0].ContinuationPoint = continuationPoint;
+            await _session.HistoryReadAsync(null, new ExtensionObject(details), TimestampsToReturn.Both, true,
+                nodesToRead, ct).ConfigureAwait(false);
+        }
+
+        return all;
+    }
+
    /// <inheritdoc />
    public async Task<IReadOnlyList<DataValue>> HistoryReadAggregateAsync(
        NodeId nodeId, DateTime startTime, DateTime endTime, NodeId aggregateId, double intervalMs,
@@ -110,6 +110,20 @@ internal interface ISessionAdapter : IDisposable
    Task<IReadOnlyList<DataValue>> HistoryReadRawAsync(NodeId nodeId, DateTime startTime, DateTime endTime,
        int maxValues, CancellationToken ct = default);

+    /// <summary>
+    ///     Reads modified-value history (Part 11, <c>IsReadModified = true</c>): the prior values and modification info
+    ///     the server recorded for every HistoryUpdate in the window, following continuation points.
+    /// </summary>
+    /// <param name="nodeId">The historized node.</param>
+    /// <param name="startTime">Window start.</param>
+    /// <param name="endTime">Window end.</param>
+    /// <param name="maxValues">The maximum number of entries to return.</param>
+    /// <param name="ct">The cancellation token.</param>
+    /// <returns>The modification entries in server order.</returns>
+    Task<IReadOnlyList<Models.HistoryModifiedEntry>> HistoryReadModifiedAsync(NodeId nodeId, DateTime startTime,
+        DateTime endTime, int maxValues, CancellationToken ct = default) =>
+        throw new NotSupportedException("This session adapter does not support modified-value history reads.");
+
    /// <summary>
    ///     Sends a HistoryUpdate request for the supplied details.
    /// </summary>
@@ -193,6 +193,20 @@ public interface IOpcUaClientService : IDisposable
    Task<IReadOnlyList<DataValue>> HistoryReadRawAsync(NodeId nodeId, DateTime startTime, DateTime endTime,
        int maxValues = 1000, CancellationToken ct = default);

+    /// <summary>
+    ///     Reads modified-value history (Part 11, <c>IsReadModified = true</c>): what each HistoryUpdate in the window
+    ///     replaced or deleted, with the server's modification time, update type and user name.
+    /// </summary>
+    /// <param name="nodeId">The historized node.</param>
+    /// <param name="startTime">Window start.</param>
+    /// <param name="endTime">Window end.</param>
+    /// <param name="maxValues">The maximum number of entries to return.</param>
+    /// <param name="ct">The cancellation token.</param>
+    /// <returns>The modification entries in server order.</returns>
+    Task<IReadOnlyList<HistoryModifiedEntry>> HistoryReadModifiedAsync(NodeId nodeId, DateTime startTime,
+        DateTime endTime, int maxValues = 1000, CancellationToken ct = default) =>
+        throw new NotSupportedException("This client service does not support modified-value history reads.");
+
    /// <summary>
    ///     Sends a HistoryUpdate request (insert/replace/update or delete) for the supplied details.
    /// </summary>
@@ -0,0 +1,17 @@
+using Opc.Ua;
+
+namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
+
+/// <summary>
+///     One entry of an OPC UA Part 11 modified-value history read (HistoryReadRaw with <c>IsReadModified = true</c>): the
+///     value as it was BEFORE the modification plus the server's <see cref="ModificationInfo"/>.
+/// </summary>
+/// <param name="Value">The prior value at its source timestamp (an insert had none: null value, Bad status).</param>
+/// <param name="ModificationTime">When the modification was applied.</param>
+/// <param name="UpdateType">The Part 11 update type (Insert / Replace / Update / Delete).</param>
+/// <param name="UserName">Who made the modification (the server's recorded principal).</param>
+public sealed record HistoryModifiedEntry(
+    DataValue Value,
+    DateTime ModificationTime,
+    HistoryUpdateType UpdateType,
+    string? UserName);
@@ -559,6 +559,15 @@ public sealed class OpcUaClientService : IOpcUaClientService
        return await _session!.HistoryReadRawAsync(nodeId, startTime, endTime, maxValues, ct);
    }

+    /// <inheritdoc />
+    public async Task<IReadOnlyList<HistoryModifiedEntry>> HistoryReadModifiedAsync(
+        NodeId nodeId, DateTime startTime, DateTime endTime, int maxValues = 1000, CancellationToken ct = default)
+    {
+        ThrowIfDisposed();
+        ThrowIfNotConnected();
+        return await _session!.HistoryReadModifiedAsync(nodeId, startTime, endTime, maxValues, ct);
+    }
+
    /// <inheritdoc />
    public async Task<HistoryUpdateOutcome> HistoryUpdateAsync(HistoryUpdateDetails details, CancellationToken ct = default)
    {