fix(historian): read-only historian bindings + ProvisionTags policy; provision OPC UA type names (#899, #898)
v2-ci / unit-tests (push) Has been cancelled

#899 — EnsureTags is an upsert, so binding a node to an existing AVEVA tag via
historianTagname re-typed/re-described it on every add and host start.
- TagConfig `historianReadOnly: true` (TagConfigIntent -> RawTagPlan.HistorianReadOnly):
  HistoryRead from an existing historian tag that OtOpcUa never provisions and never
  records into (AddressSpaceApplier.IsOwnedHistorizedValue gates both the EnsureTags
  hook and the recorder feed). Node-inert: surgical, not mirrored on UNS refs, in the
  RawTagPlan equality/hash. A non-bool value is the deploy error HistorianReadOnlyInvalid.
  AdminUI: CSV column HistorianReadOnly (strict), TagHistorizeConfig reads via the
  runtime parse.
- ServerHistorian:ProvisionTags = CreateOrUpdate (default, unchanged) | CreateOnly
  (Gateway only: TagExistsAsync first, existing tags left alone, failed lookup not
  sent) | Off. Unknown value / CreateOnly on a SQL backend fail host start.
- Default for an explicit historianTagname stays OWNED: overrides pin owned history
  across renames, a read-only default would silently stop provisioning + recording.

#898 — the hook parsed Tag.DataType (an OPC UA name) as DriverDataType, so historized
Float/Double/Byte/SByte tags were never provisioned. New shared
HistorianDataTypeNames.TryResolve: Float->Float32, Double->Float64, Byte/SByte->Int16
(lossless, provisioned as Int2); unmapped names logged at Information. Gateway now skips
Int64/UInt64 (HistorianGateway cannot create Int8/UInt8: lossless-cast-or-reject).

UPGRADE: the first host start after this provisions (upserts) every existing historized
Float/Double/Byte/SByte tag. Mark foreign-tag bindings historianReadOnly, or set
ServerHistorian:ProvisionTags=CreateOnly/Off, before upgrading (docs/Historian.md).

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-13 01:16:23 -05:00
parent eec87d3f74
commit 6c4d29902e
36 changed files with 1015 additions and 60 deletions
@@ -106,6 +106,41 @@ public sealed class ServerHistorianOptions
/// </summary>
public bool GatewayAtTimeFromRaw { get; init; } = true;
/// <summary>
/// What the tag provisioning hook may do to the historian's tags (lmxopcua#899): <c>CreateOrUpdate</c> (default —
/// the behaviour before #899: <c>EnsureTags</c> is an upsert that creates a missing tag and re-types /
/// re-describes an existing one), <c>CreateOnly</c> (<c>Gateway</c> backend only: each tag is looked up first and
/// an EXISTING one is left exactly as it is; only missing tags are created) or <c>Off</c> (no provisioning at all;
/// HistoryRead and continuous historization are unaffected). Case-insensitive; an unknown value fails host start.
/// A tag's own <c>historianReadOnly: true</c> opts it out of provisioning (and recording) under every policy.
/// </summary>
public string ProvisionTags { get; init; } = nameof(HistorianProvisionPolicy.CreateOrUpdate);
/// <summary>
/// <see cref="ProvisionTags"/> parsed; an unknown value reads as <see cref="HistorianProvisionPolicy.CreateOrUpdate"/>
/// here (the options validator fails host start on it first).
/// </summary>
public HistorianProvisionPolicy ProvisionPolicy =>
TryParseProvisionPolicy(ProvisionTags, out var policy) ? policy : HistorianProvisionPolicy.CreateOrUpdate;
/// <summary>Parses a <see cref="ProvisionTags"/> value (case-insensitive, trimmed; blank ⇒ the default).</summary>
/// <param name="value">The configured value.</param>
/// <param name="policy">The parsed policy.</param>
/// <returns><see langword="true"/> when the value names a policy (or is blank).</returns>
public static bool TryParseProvisionPolicy(string? value, out HistorianProvisionPolicy policy)
{
policy = HistorianProvisionPolicy.CreateOrUpdate;
var v = value?.Trim();
if (string.IsNullOrEmpty(v)) return true;
foreach (var candidate in Enum.GetValues<HistorianProvisionPolicy>())
{
if (!string.Equals(v, candidate.ToString(), StringComparison.OrdinalIgnoreCase)) continue;
policy = candidate;
return true;
}
return false;
}
/// <summary>
/// <c>Gateway</c> backend only: the <c>ServerHistorian:Gateway</c> sub-section — knobs that exist because of the
/// HistorianGateway's wire contract (see <see cref="GatewayHistorianSettings"/>). Ignored by the other backends.
@@ -303,3 +338,16 @@ public sealed class GatewayHistorianSettings
/// </summary>
public TimeSpan ProbeInterval { get; init; } = TimeSpan.FromSeconds(30);
}
/// <summary>What the historian tag provisioning hook may do (<see cref="ServerHistorianOptions.ProvisionTags"/>, lmxopcua#899).</summary>
public enum HistorianProvisionPolicy
{
/// <summary>Create a missing tag and update (re-type, re-describe) an existing one — the upsert, and the default.</summary>
CreateOrUpdate,
/// <summary>Create a missing tag; never touch an existing one (<c>Gateway</c> backend only).</summary>
CreateOnly,
/// <summary>No provisioning.</summary>
Off,
}
@@ -283,6 +283,8 @@ public static class ServiceCollectionExtensions
{
var opts = configuration.GetSection(ServerHistorianOptions.SectionName).Get<ServerHistorianOptions>();
if (opts is not { Enabled: true }) return services; // leave the Null default from AddOtOpcUaRuntime
// ServerHistorian:ProvisionTags=Off (lmxopcua#899): keep the Null default — reads and recording are unaffected.
if (opts.ProvisionPolicy == HistorianProvisionPolicy.Off) return services;
// Last-registration-wins over the TryAddSingleton Null default seeded by AddOtOpcUaRuntime.
services.AddSingleton<IHistorianProvisioning>(sp => provisioningFactory(opts, sp));