fix(historian-gateway): wire dormant GatewayTagProvisioner + provisioning observability/docs

PR #423 shipped GatewayTagProvisioner + unit tests but never registered it in
DI nor passed it into the AddressSpaceApplier, so deploying historized tags used
the no-op NullHistorianProvisioning and never called the gateway's EnsureTags
(confirmed live on wonder-app-vd03: zero EnsureTags calls on a historized deploy).
Addresses HISTORIAN-GATEWAY-INTEGRATION-ISSUES.md.

Issue 1 (wire provisioner):
- Runtime: AddHistorianProvisioning extension (gated on ServerHistorian:Enabled,
  mirrors AddServerHistorian) + NullHistorianProvisioning TryAdd default in
  AddOtOpcUaRuntime; WithOtOpcUaRuntimeActors resolves IHistorianProvisioning and
  passes it into the applier.
- Gateway driver: GatewayHistorian.CreateProvisioner factory (mirrors CreateDataSource).
- Host: Program.cs calls AddHistorianProvisioning after AddServerHistorian.
- Tests: AddHistorianProvisioningTests (config-gated registration + the
  register->resolve->applier->EnsureTags chain).

Issue 2 (observability): AddressSpaceApplier logs the provisioning tally on every
successful dispatch (was gated behind Failed/Skipped > 0), including dispatched=N
so a dispatched=N/requested=0 line flags the dormant no-op. +2 tests.

Issue 3 (30s HistoryRead on unprovisioned tags): root coupling fixed by Issue 1;
documented the CallTimeout knob + coupling. Default left at 30s pending the
multi-data-point investigation the issue requests (lowering risks truncating
legitimate large reads).

Issue 4 (docs): docs/Historian.md gains a "Tag auto-provisioning (EnsureTags)"
section and CLAUDE.md a wiring/gating note (both stress ServerHistorian:Enabled).
Sibling scadaproj/CLAUDE.md carries no false claim -> unchanged.

Pre-existing Serilog observation: anchor CWD to AppContext.BaseDirectory before
AddZbSerilog so the relative file sink stops landing in C:\Windows\System32 under
the Windows-service CWD.

Builds 0-error; Runtime.Tests 355, OpcUaServer.Tests 329, Gateway.Tests 99 (+4
live-skipped) all green.
This commit is contained in:
Joseph Doherty
2026-06-27 23:24:29 -04:00
parent 245316d80d
commit 257214f775
8 changed files with 416 additions and 7 deletions
@@ -47,6 +47,10 @@ public static class ServiceCollectionExtensions
{
services.TryAddSingleton<IAlarmHistorianSink>(NullAlarmHistorianSink.Instance);
services.TryAddSingleton<IHistorianDataSource>(NullHistorianDataSource.Instance);
// Historian tag provisioning. Null default (no-op) so the AddressSpaceApplier resolves a real
// IHistorianProvisioning only when AddHistorianProvisioning registers the gateway-backed one
// (ServerHistorian:Enabled). TryAddSingleton so the gateway registration wins last.
services.TryAddSingleton<IHistorianProvisioning>(NullHistorianProvisioning.Instance);
// VirtualTag historization sink. Null default — the durable AVEVA sink is infra-gated (there is
// no live-data historian write RPC). TryAddSingleton so a deployment that bound a real
// IHistoryWriter earlier wins.
@@ -135,6 +139,39 @@ public static class ServiceCollectionExtensions
return services;
}
/// <summary>
/// Config-gated historian tag provisioning. When the <c>ServerHistorian</c> section has
/// <c>Enabled=true</c>, registers the <paramref name="provisioningFactory"/>-supplied
/// <see cref="IHistorianProvisioning"/> (the gateway-backed <c>GatewayTagProvisioner</c> that calls
/// the gateway's <c>EnsureTags</c>) overriding the <see cref="NullHistorianProvisioning"/> default from
/// <see cref="AddOtOpcUaRuntime"/>. Otherwise a no-op (the Null default stays and deploying historized
/// tags provisions nothing). The provisioner is consumed by the <c>AddressSpaceApplier</c>, which fires
/// a non-blocking <see cref="IHistorianProvisioning.EnsureTagsAsync"/> for added historized tags on
/// every deploy. Gated on the <b>same</b> <c>ServerHistorian:Enabled</c> flag as the read path
/// (<see cref="AddServerHistorian"/>) — provisioning targets the same single gateway. The provisioner
/// is injected so the gateway-backed client can be supplied by the Host, which is the only project that
/// references the driver.
/// </summary>
/// <param name="services">The service collection to register with.</param>
/// <param name="configuration">The configuration carrying the <c>ServerHistorian</c> section.</param>
/// <param name="provisioningFactory">
/// Factory the Host supplies to build the concrete <see cref="IHistorianProvisioning"/>
/// (the gateway-backed provisioner) from the bound options + the resolving provider.
/// </param>
/// <returns>The same <paramref name="services"/> instance for chaining.</returns>
public static IServiceCollection AddHistorianProvisioning(
this IServiceCollection services,
IConfiguration configuration,
Func<ServerHistorianOptions, IServiceProvider, IHistorianProvisioning> provisioningFactory)
{
var opts = configuration.GetSection(ServerHistorianOptions.SectionName).Get<ServerHistorianOptions>();
if (opts is not { Enabled: true }) return services; // leave the Null default from AddOtOpcUaRuntime
// Last-registration-wins over the TryAddSingleton Null default seeded by AddOtOpcUaRuntime.
services.AddSingleton<IHistorianProvisioning>(sp => provisioningFactory(opts, sp));
return services;
}
/// <summary>
/// Spawns the per-node driver-role actors on the host's <see cref="ActorSystem"/>:
/// <see cref="DriverHostActor"/> (one per node), <see cref="DbHealthProbeActor"/>
@@ -252,12 +289,19 @@ public static class ServiceCollectionExtensions
? new ActorHistorizedTagSubscriptionSink(continuousRecorder)
: NullHistorizedTagSubscriptionSink.Instance;
// Historian tag provisioner fed to the applier so deploying historized tags auto-ensures
// them in the historian (EnsureTags). The Host registers the gateway-backed provisioner via
// AddHistorianProvisioning when ServerHistorian:Enabled; otherwise this resolves the no-op
// NullHistorianProvisioning default seeded by AddOtOpcUaRuntime (so the applier's hook is inert).
var provisioning = resolver.GetService<IHistorianProvisioning>();
// OPC UA publish actor — pinned dispatcher, owns the address-space side of the
// pipeline. AddressSpaceApplier is constructed here so the actor + applier share the
// same sink reference (when DeferredAddressSpaceSink swaps later, both see it).
var applier = new AddressSpaceApplier(
addressSpaceSink,
loggerFactory.CreateLogger<AddressSpaceApplier>(),
provisioning: provisioning,
historizedSubscriptions: historizedSubscriptions);
var publishActor = system.ActorOf(
OpcUaPublishActor.Props(