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
@@ -124,4 +124,28 @@ public sealed class TagConfigIntentTests
{
Should.NotThrow(() => TagConfigIntent.Parse(cfg));
}
// ---- lmxopcua#899: historianReadOnly ----
[Theory]
[InlineData("{\"isHistorized\":true,\"historianReadOnly\":true}", true)]
[InlineData("{\"isHistorized\":true,\"historianReadOnly\":false}", false)]
[InlineData("{\"isHistorized\":true}", false)]
[InlineData("{\"isHistorized\":true,\"historianReadOnly\":\"true\"}", false)]
[InlineData("{\"isHistorized\":true,\"historianreadonly\":true}", false)]
[InlineData(null, false)]
public void HistorianReadOnly_is_true_only_for_a_json_true(string? cfg, bool expected)
=> TagConfigIntent.Parse(cfg).HistorianReadOnly.ShouldBe(expected);
[Theory]
[InlineData("{\"historianReadOnly\":\"true\"}", true)]
[InlineData("{\"historianReadOnly\":1}", true)]
[InlineData("{\"historianReadOnly\":null}", true)]
[InlineData("{\"historianReadOnly\":true}", false)]
[InlineData("{\"historianReadOnly\":false}", false)]
[InlineData("{}", false)]
[InlineData("not json {", false)]
[InlineData(null, false)]
public void HasMalformedHistorianReadOnly_flags_only_a_present_non_boolean(string? cfg, bool expected)
=> TagConfigIntent.HasMalformedHistorianReadOnly(cfg).ShouldBe(expected);
}
@@ -0,0 +1,55 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
using ZB.MOM.WW.OtOpcUa.Configuration.Validation;
namespace ZB.MOM.WW.OtOpcUa.Configuration.Tests;
/// <summary>
/// lmxopcua#899: <c>historianReadOnly</c> must be a JSON boolean. The runtime honours only a bool <c>true</c>, so a
/// string <c>"true"</c> would deploy as an OWNED tag whose foreign historian tag then gets provisioned (upserted)
/// and recorded into — the deploy gate refuses it instead.
/// </summary>
[Trait("Category", "Unit")]
public sealed class DraftValidatorHistorianReadOnlyTests
{
private static DraftSnapshot Draft(params Tag[] tags) => new()
{
GenerationId = 1, ClusterId = "c",
DriverInstances =
[
new DriverInstance
{
DriverInstanceId = "di", ClusterId = "c", Name = "mb", DriverType = "Modbus", DriverConfig = "{}",
},
],
Devices = [new Device { DeviceId = "dev", DriverInstanceId = "di", Name = "plc", DeviceConfig = "{}" }],
Tags = tags,
};
private static Tag TagRow(string id, string tagConfig) => new()
{
TagId = id, DeviceId = "dev", Name = id, DataType = "Int32", AccessLevel = TagAccessLevel.Read, TagConfig = tagConfig,
};
[Theory]
[InlineData("{\"isHistorized\":true,\"historianReadOnly\":\"true\"}")]
[InlineData("{\"isHistorized\":true,\"historianReadOnly\":1}")]
[InlineData("{\"historianReadOnly\":null}")]
public void A_non_boolean_historianReadOnly_is_a_deploy_error(string tagConfig)
{
var errors = DraftValidator.Validate(Draft(TagRow("t-bad", tagConfig)));
errors.ShouldContain(e => e.Code == "HistorianReadOnlyInvalid" && e.Context == "t-bad");
}
[Theory]
[InlineData("{\"isHistorized\":true,\"historianTagname\":\"SysTimeSec\",\"historianReadOnly\":true}")]
[InlineData("{\"isHistorized\":true,\"historianReadOnly\":false}")]
[InlineData("{\"isHistorized\":true}")]
public void A_boolean_or_absent_historianReadOnly_passes(string tagConfig)
{
var errors = DraftValidator.Validate(Draft(TagRow("t-ok", tagConfig)));
errors.ShouldNotContain(e => e.Code == "HistorianReadOnlyInvalid");
}
}
@@ -0,0 +1,48 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions.Tests.Historian;
/// <summary>
/// lmxopcua#898: a raw tag's <c>DataType</c> is an OPC UA built-in name. Every name the AdminUI offers
/// (<c>RawTagModal.DataTypes</c>) must resolve the way the historian provisioning hook expects, or be explicitly
/// unresolved — <c>Float</c>/<c>Double</c>/<c>Byte</c>/<c>SByte</c> used to be silently dropped.
/// </summary>
public sealed class HistorianDataTypeNamesTests
{
[Theory]
[InlineData("Boolean", DriverDataType.Boolean)]
[InlineData("SByte", DriverDataType.Int16)] // lossless widening; Int1 creation is server-degenerate
[InlineData("Byte", DriverDataType.Int16)] // lossless widening
[InlineData("Int16", DriverDataType.Int16)]
[InlineData("UInt16", DriverDataType.UInt16)]
[InlineData("Int32", DriverDataType.Int32)]
[InlineData("UInt32", DriverDataType.UInt32)]
[InlineData("Int64", DriverDataType.Int64)]
[InlineData("UInt64", DriverDataType.UInt64)]
[InlineData("Float", DriverDataType.Float32)]
[InlineData("Double", DriverDataType.Float64)]
[InlineData("String", DriverDataType.String)]
[InlineData("DateTime", DriverDataType.DateTime)]
// DriverDataType spellings are still accepted, case-insensitively and trimmed.
[InlineData("Float32", DriverDataType.Float32)]
[InlineData("float64", DriverDataType.Float64)]
[InlineData(" double ", DriverDataType.Float64)]
[InlineData("Reference", DriverDataType.Reference)]
public void Resolves(string name, DriverDataType expected)
{
HistorianDataTypeNames.TryResolve(name, out var resolved).ShouldBeTrue();
resolved.ShouldBe(expected);
}
[Theory]
[InlineData("Guid")]
[InlineData("ByteString")]
[InlineData("3")] // Enum.TryParse would take a bare number
[InlineData("Int16,Int32")] // ...or a flags-style list
[InlineData("")]
[InlineData(" ")]
[InlineData(null)]
public void Does_not_resolve(string? name) => HistorianDataTypeNames.TryResolve(name, out _).ShouldBeFalse();
}