feat(historian): SQL Server retention purge (RetentionDays, Primary-gated, applock) (#667)

src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs

@@ -326,6 +326,14 @@ if (hasDriver)
         builder.Services.AddSingleton<IHistorianValueWriter>(sp => sp.GetRequiredService<IHistorianBackendProvider>().CreateValueWriter(sp));
     }
 
+    // Historian retention (#667). Only a backend that manages retention in-process returns a purger
+    // (SqlServer with RetentionDays set); otherwise the service is inert. Primary-gated via IHistorizationRoleView.
+    if (serverHistorianOptions.Enabled)
+        builder.Services.AddHostedService(sp => new HistorianRetentionService(
+            sp.GetRequiredService<IHistorianBackendProvider>().CreateRetention(sp),
+            sp.GetService<ZB.MOM.WW.OtOpcUa.Runtime.Redundancy.IHistorizationRoleView>(),
+            sp.GetService<ILogger<HistorianRetentionService>>()));
+
     // Bind every cross-platform driver factory before AddAkka resolves IDriverFactory — replaces
     // the F7-default NullDriverFactory with a real DriverFactoryRegistryAdapter so DriverHostActor
     // can materialise real IDriver instances on deploy.

src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/HistorianRetentionService.cs

@@ -0,0 +1,95 @@
+using System.Diagnostics;
+using System.Diagnostics.Metrics;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Commons.Observability;
+using ZB.MOM.WW.OtOpcUa.Runtime.Redundancy;
+
+namespace ZB.MOM.WW.OtOpcUa.Runtime.Historian;
+
+/// <summary>
+///     Timer that drives an <see cref="IHistorianRetention"/> purge. Each tick is gated on
+///     <see cref="IHistorizationRoleView.ShouldRecordHistorizedValues"/> so only the node that is writing
+///     history purges it (an unknown role allows, matching the capture gate). A null retention (backend has
+///     none, or no window configured) makes the service inert. Never throws out of the loop.
+/// </summary>
+public sealed class HistorianRetentionService : BackgroundService
+{
+    /// <summary>Counter of rows purged, tagged <c>table</c>.</summary>
+    public const string PurgedCounterName = "otopcua.historian.retention.purged";
+
+    private static readonly Counter<long> Purged = OtOpcUaTelemetry.Meter.CreateCounter<long>(
+        PurgedCounterName, unit: "{row}", description: "Historian rows deleted by the retention purge.");
+
+    private readonly IHistorianRetention? _retention;
+    private readonly IHistorizationRoleView? _roleView;
+    private readonly ILogger _log;
+    private readonly KeyValuePair<string, object?>[] _extraTags;
+
+    /// <summary>Creates the service.</summary>
+    /// <param name="retention">Backend purge seam; null makes the service inert.</param>
+    /// <param name="roleView">Primary gate; null means always run.</param>
+    /// <param name="log">Logger.</param>
+    /// <param name="extraTags">Extra tags added to every counter increment (tests use a unique one).</param>
+    public HistorianRetentionService(IHistorianRetention? retention, IHistorizationRoleView? roleView,
+        ILogger<HistorianRetentionService>? log = null, params KeyValuePair<string, object?>[] extraTags)
+    {
+        _retention = retention;
+        _roleView = roleView;
+        _log = (ILogger?)log ?? NullLogger.Instance;
+        _extraTags = extraTags;
+    }
+
+    /// <summary>Runs one gated tick. Never throws.</summary>
+    /// <param name="ct">Cancellation.</param>
+    /// <returns>True when a purge pass ran.</returns>
+    public async Task<bool> TickAsync(CancellationToken ct)
+    {
+        if (_retention is null) return false;
+        if (_roleView is { ShouldRecordHistorizedValues: false })
+        {
+            _log.LogDebug("Historian retention purge skipped: this node is not the recording node.");
+            return false;
+        }
+
+        try
+        {
+            var results = await _retention.PurgeAsync(ct).ConfigureAwait(false);
+            foreach (var r in results)
+            {
+                if (r.Rows <= 0) continue;
+                var tags = new TagList { { "table", r.Table } };
+                foreach (var t in _extraTags) tags.Add(t);
+                Purged.Add(r.Rows, tags);
+                _log.LogInformation("Historian retention purged {Rows} rows from {Table}.", r.Rows, r.Table);
+            }
+            return true;
+        }
+        catch (OperationCanceledException) when (ct.IsCancellationRequested)
+        {
+            return false;
+        }
+        catch (Exception ex)
+        {
+            _log.LogWarning(ex, "Historian retention purge failed; will retry next interval.");
+            return false;
+        }
+    }
+
+    /// <inheritdoc/>
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        if (_retention is null) return;
+        try
+        {
+            using var timer = new PeriodicTimer(_retention.Interval);
+            await TickAsync(stoppingToken).ConfigureAwait(false);
+            while (await timer.WaitForNextTickAsync(stoppingToken).ConfigureAwait(false))
+                await TickAsync(stoppingToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
+        {
+        }
+    }
+}

src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/IHistorianBackendProvider.cs

@@ -39,4 +39,9 @@ public interface IHistorianBackendProvider
     /// <param name="sp">Service provider.</param>
     /// <returns>The updater, or <c>null</c> when the backend does not support HistoryUpdate.</returns>
     IHistorianDataUpdater? CreateUpdater(IServiceProvider sp);
+
+    /// <summary>Creates the retention purge seam, if the backend manages retention in-process.</summary>
+    /// <param name="sp">Service provider.</param>
+    /// <returns>The purger, or <c>null</c> (default) when the backend has no retention or enforces it itself.</returns>
+    IHistorianRetention? CreateRetention(IServiceProvider sp) => null;
 }

src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/IHistorianRetention.cs

@@ -0,0 +1,25 @@
+namespace ZB.MOM.WW.OtOpcUa.Runtime.Historian;
+
+/// <summary>Rows removed from one historian table by a single purge pass.</summary>
+/// <param name="Table">Unqualified table name (the <c>table</c> tag on the retention counter).</param>
+/// <param name="Rows">Rows deleted.</param>
+public sealed record RetentionPurgeResult(string Table, long Rows);
+
+/// <summary>
+///     Backend-side retention purge: deletes history older than the backend's configured retention window.
+///     Created by <see cref="IHistorianBackendProvider.CreateRetention"/> and driven on a timer by
+///     <see cref="HistorianRetentionService"/>, which owns scheduling and the Primary gate.
+/// </summary>
+public interface IHistorianRetention
+{
+    /// <summary>How often <see cref="HistorianRetentionService"/> should run a pass.</summary>
+    TimeSpan Interval { get; }
+
+    /// <summary>
+    ///     Runs one purge pass. Returns an empty list when the pass was skipped (another process holds the
+    ///     purge lock). Implementations honour cancellation between batches.
+    /// </summary>
+    /// <param name="ct">Cancellation.</param>
+    /// <returns>Per-table deleted-row counts.</returns>
+    Task<IReadOnlyList<RetentionPurgeResult>> PurgeAsync(CancellationToken ct);
+}