feat(historian): QuestDb provider, registry + consumer-gated validator, compose env

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
2026-10-11 02:23:21 -04:00
parent 18e85265f9
commit 13d628a07f
8 changed files with 351 additions and 0 deletions
@@ -0,0 +1,106 @@
+using System.Collections.Frozen;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian;
+using ZB.MOM.WW.OtOpcUa.Runtime.Historian;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.QuestDb;
+
+/// <summary>
+///     <see cref="IHistorianBackendProvider"/> for the QuestDB historian. Supports every
+///     <see cref="HistorianValueKind"/> and HistoryUpdate (soft delete). All seams share ONE connection helper, ONE
+///     schema bootstrapper, ONE tag catalog (R7: the only "known tag" authority) and ONE WAL visibility wait, so the
+///     schema is ensured once and known tags are cached once.
+/// </summary>
+/// <remarks>
+///     The shared state is built on the first <c>Create*</c> call, not in the constructor: the constructor does no
+///     validation and no I/O, so resolving the provider for a backend nobody consumes never fails on its options
+///     (they are validated, consumer-gated, by the host's <c>ServerHistorianOptionsValidator</c>). The first
+///     <c>Create*</c> call's service provider supplies the logger factory the shared pieces log through.
+/// </remarks>
+public sealed class QuestDbHistorianProvider : IHistorianBackendProvider
+{
+    private static readonly FrozenSet<HistorianValueKind> Kinds =
+        Enum.GetValues<HistorianValueKind>().ToFrozenSet();
+
+    private readonly QuestDbHistorianOptions _options;
+    private readonly object _initLock = new();
+    private Shared? _shared;
+
+    /// <summary>Creates the provider over the <c>ServerHistorian:QuestDb</c> options (validated elsewhere).</summary>
+    /// <param name="options">The <c>ServerHistorian:QuestDb</c> options.</param>
+    public QuestDbHistorianProvider(QuestDbHistorianOptions options)
+    {
+        _options = options ?? throw new ArgumentNullException(nameof(options));
+    }
+
+    /// <inheritdoc />
+    public string Name => "QuestDb";
+
+    /// <inheritdoc />
+    public IReadOnlySet<HistorianValueKind> SupportedKinds => Kinds;
+
+    private static ILoggerFactory Loggers(IServiceProvider sp) =>
+        (sp.GetService(typeof(ILoggerFactory)) as ILoggerFactory) ?? NullLoggerFactory.Instance;
+
+    private Shared Get(IServiceProvider sp)
+    {
+        if (Volatile.Read(ref _shared) is { } built) return built;
+        lock (_initLock)
+        {
+            if (_shared is { } raced) return raced;
+            var loggers = Loggers(sp);
+            var conn = new QuestDbConnection(_options);
+            var bootstrap = new QuestDbSchemaBootstrapper(conn, _options, loggers.CreateLogger<QuestDbSchemaBootstrapper>());
+            var wal = new QuestDbWalVisibility(conn, _options.VisibilityTimeout, loggers.CreateLogger<QuestDbWalVisibility>());
+            var shared = new Shared(conn, bootstrap, new QuestDbTagCatalog(conn, bootstrap, wal), wal);
+            Volatile.Write(ref _shared, shared);
+            return shared;
+        }
+    }
+
+    /// <inheritdoc />
+    public IHistorianDataSource CreateDataSource(IServiceProvider sp)
+    {
+        var s = Get(sp);
+        return new QuestDbHistorianDataSource(s.Conn, s.Bootstrap, s.Catalog,
+            Loggers(sp).CreateLogger<QuestDbHistorianDataSource>());
+    }
+
+    /// <inheritdoc />
+    public IHistorianValueWriter CreateValueWriter(IServiceProvider sp)
+    {
+        var s = Get(sp);
+        return new QuestDbHistorianValueWriter(s.Conn, s.Catalog, s.Wal,
+            Loggers(sp).CreateLogger<QuestDbHistorianValueWriter>());
+    }
+
+    /// <inheritdoc />
+    public IAlarmHistorianWriter CreateAlarmWriter(IServiceProvider sp)
+    {
+        var s = Get(sp);
+        return new QuestDbAlarmHistorianWriter(s.Conn, s.Bootstrap, s.Wal,
+            Loggers(sp).CreateLogger<QuestDbAlarmHistorianWriter>());
+    }
+
+    /// <inheritdoc />
+    public IHistorianProvisioning CreateProvisioning(IServiceProvider sp)
+    {
+        var s = Get(sp);
+        return new QuestDbTagProvisioner(s.Conn, s.Bootstrap, s.Catalog, s.Wal,
+            Loggers(sp).CreateLogger<QuestDbTagProvisioner>());
+    }
+
+    /// <inheritdoc />
+    /// <remarks>The soft-delete updater: deletes write tombstones (INSERT only, never QuestDB UPDATE/DELETE).</remarks>
+    public IHistorianDataUpdater? CreateUpdater(IServiceProvider sp)
+    {
+        var s = Get(sp);
+        return new QuestDbHistorianDataUpdater(s.Conn, s.Catalog, s.Wal,
+            Loggers(sp).CreateLogger<QuestDbHistorianDataUpdater>());
+    }
+
+    private sealed record Shared(
+        QuestDbConnection Conn, QuestDbSchemaBootstrapper Bootstrap, QuestDbTagCatalog Catalog, QuestDbWalVisibility Wal);
+}