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
@@ -35,4 +35,21 @@ public sealed class GatewayHistorianProviderTests
Assert.IsType<GatewayTagProvisioner>(p.CreateProvisioning(sp));
await writer.DisposeAsync();
}
/// <summary>lmxopcua#899: ServerHistorian:ProvisionTags reaches the provisioner (CreateOnly on, the default off).</summary>
[Theory]
[InlineData("CreateOnly", true)]
[InlineData("createonly", true)]
[InlineData("CreateOrUpdate", false)]
[InlineData("", false)]
public async Task ProvisionTags_policy_reaches_the_provisioner(string policy, bool createOnly)
{
var p = new GatewayHistorianProvider(new ServerHistorianOptions
{
Endpoint = "http://localhost:5222", UseTls = false, ApiKey = "histgw_test_secret", ProvisionTags = policy,
});
var provisioner = Assert.IsType<GatewayTagProvisioner>(p.CreateProvisioning(Sp()));
Assert.Equal(createOnly, provisioner.CreateOnly);
await provisioner.DisposeAsync();
}
}
@@ -1,3 +1,4 @@
using Grpc.Core;
using Microsoft.Extensions.Logging.Abstractions;
using Xunit;
using ZB.MOM.WW.HistorianGateway.Contracts.Grpc;
@@ -220,4 +221,120 @@ public sealed class GatewayTagProvisionerTests
Assert.Equal(0, result.Skipped);
Assert.Equal(1, result.Failed);
}
// ---- lmxopcua#899: ServerHistorian:ProvisionTags=CreateOnly ------------------------------------------
private static TagOperationResults AllSucceeded(int count)
{
var results = new TagOperationResults();
for (var i = 0; i < count; i++) results.Results.Add(new TagOperationResult { Success = true });
return results;
}
/// <summary>The default (CreateOrUpdate) never looks a tag up — it is the upsert, unchanged.</summary>
[Fact]
public async Task Default_policy_sends_without_an_existence_lookup()
{
var fake = new FakeHistorianGatewayClient { EnsureTagsResult = AllSucceeded(1), TagExistsResult = true };
await Provisioner(fake).EnsureTagsAsync(
new[] { new HistorianTagProvisionRequest("SysTimeSec", DriverDataType.Int32, null, "t") },
TestContext.Current.CancellationToken);
Assert.Equal(0, fake.TagExistsCallCount);
Assert.Equal(1, fake.EnsureTagsCallCount);
Assert.Equal("SysTimeSec", Assert.Single(fake.LastEnsureDefinitions!).TagName);
}
/// <summary>CreateOnly: an EXISTING historian tag never reaches EnsureTags (it would be re-typed), a missing one
/// does (positive control), and the tally counts the kept tag as skipped.</summary>
[Fact]
public async Task CreateOnly_sends_only_tags_the_historian_reports_absent()
{
var fake = new FakeHistorianGatewayClient
{
EnsureTagsResult = AllSucceeded(1),
TagExistsSource = (tag, _) => Task.FromResult(tag == "SysTimeSec"),
};
var p = new GatewayTagProvisioner(fake, NullLogger<GatewayTagProvisioner>.Instance, createOnly: true);
var result = await p.EnsureTagsAsync(new[]
{
new HistorianTagProvisionRequest("SysTimeSec", DriverDataType.Int32, null, "existing"),
new HistorianTagProvisionRequest("OtOpcUa.New", DriverDataType.Float32, null, "new"),
}, TestContext.Current.CancellationToken);
Assert.Equal(2, fake.TagExistsCallCount);
Assert.Equal("OtOpcUa.New", Assert.Single(fake.LastEnsureDefinitions!).TagName);
Assert.Equal(new HistorianProvisionResult(2, Ensured: 1, Skipped: 1, Failed: 0), result);
}
/// <summary>CreateOnly when every tag exists: no EnsureTags call at all.</summary>
[Fact]
public async Task CreateOnly_with_only_existing_tags_makes_no_EnsureTags_call()
{
var fake = new FakeHistorianGatewayClient { TagExistsResult = true };
var p = new GatewayTagProvisioner(fake, NullLogger<GatewayTagProvisioner>.Instance, createOnly: true);
var result = await p.EnsureTagsAsync(
new[] { new HistorianTagProvisionRequest("SysPulse", DriverDataType.Boolean, null, null) },
TestContext.Current.CancellationToken);
Assert.Equal(0, fake.EnsureTagsCallCount);
Assert.Equal(new HistorianProvisionResult(1, Ensured: 0, Skipped: 1, Failed: 0), result);
}
/// <summary>CreateOnly fails closed: a lookup that errors is NOT followed by an upsert; a gRPC NotFound is a clean
/// "absent" and the tag is created.</summary>
[Fact]
public async Task CreateOnly_fails_closed_on_a_lookup_error_and_treats_NotFound_as_absent()
{
var fake = new FakeHistorianGatewayClient
{
EnsureTagsResult = AllSucceeded(1),
TagExistsSource = (tag, _) => tag == "Broken"
? Task.FromException<bool>(new RpcException(new Status(StatusCode.Unavailable, "down")))
: Task.FromException<bool>(new RpcException(new Status(StatusCode.NotFound, "no such tag"))),
};
var p = new GatewayTagProvisioner(fake, NullLogger<GatewayTagProvisioner>.Instance, createOnly: true);
var result = await p.EnsureTagsAsync(new[]
{
new HistorianTagProvisionRequest("Broken", DriverDataType.Float64, null, null),
new HistorianTagProvisionRequest("Missing", DriverDataType.Float64, null, null),
}, TestContext.Current.CancellationToken);
Assert.Equal("Missing", Assert.Single(fake.LastEnsureDefinitions!).TagName);
Assert.Equal(new HistorianProvisionResult(2, Ensured: 1, Skipped: 0, Failed: 1), result);
}
/// <summary>CreateOnly looks up only historizable requests — a deferred type is skipped before any lookup.</summary>
[Fact]
public async Task CreateOnly_does_not_look_up_non_historizable_types()
{
var fake = new FakeHistorianGatewayClient { TagExistsResult = false };
var p = new GatewayTagProvisioner(fake, NullLogger<GatewayTagProvisioner>.Instance, createOnly: true);
var result = await p.EnsureTagsAsync(
new[] { new HistorianTagProvisionRequest("Text", DriverDataType.String, null, null) },
TestContext.Current.CancellationToken);
Assert.Equal(0, fake.TagExistsCallCount);
Assert.Equal(0, fake.EnsureTagsCallCount);
Assert.Equal(1, result.Skipped);
}
/// <summary>lmxopcua#898: a 64-bit integer is skipped up front (the gateway cannot create Int8/UInt8).</summary>
[Fact]
public async Task Sixty_four_bit_integers_are_skipped_not_sent()
{
var fake = new FakeHistorianGatewayClient();
var result = await Provisioner(fake).EnsureTagsAsync(new[]
{
new HistorianTagProvisionRequest("Big", DriverDataType.Int64, null, null),
new HistorianTagProvisionRequest("BigU", DriverDataType.UInt64, null, null),
}, TestContext.Current.CancellationToken);
Assert.Equal(0, fake.EnsureTagsCallCount);
Assert.Equal(new HistorianProvisionResult(2, Ensured: 0, Skipped: 2, Failed: 0), result);
}
}
@@ -11,10 +11,8 @@ public sealed class HistorianTypeMapperTests
[InlineData(DriverDataType.Boolean, HistorianDataType.Int2)] // Int1 analog-tag creation is server-degenerate (issue #441) → store 0/1
[InlineData(DriverDataType.Int16, HistorianDataType.Int2)]
[InlineData(DriverDataType.Int32, HistorianDataType.Int4)]
[InlineData(DriverDataType.Int64, HistorianDataType.Int8)]
[InlineData(DriverDataType.UInt16, HistorianDataType.Uint4)] // fallback: UInt2 write deferred upstream
[InlineData(DriverDataType.UInt32, HistorianDataType.Uint4)]
[InlineData(DriverDataType.UInt64, HistorianDataType.Uint8)]
[InlineData(DriverDataType.Float32, HistorianDataType.Float)]
[InlineData(DriverDataType.Float64, HistorianDataType.Double)]
public void Maps_writable_numeric_types(DriverDataType d, HistorianDataType expected)
@@ -30,6 +28,18 @@ public sealed class HistorianTypeMapperTests
Assert.Contains("not historized in v1", ex.Message); // human-actionable, no tag value leaked
}
/// <summary>lmxopcua#898: HistorianGateway is lossless-cast-or-reject and cannot create Int8/UInt8, so the 64-bit
/// integers are refused here (skipped by the provisioner) instead of being sent to fail.</summary>
[Theory]
[InlineData(DriverDataType.Int64)]
[InlineData(DriverDataType.UInt64)]
public void Sixty_four_bit_integers_are_not_historizable(DriverDataType d)
{
Assert.False(HistorianTypeMapper.IsHistorizable(d));
var ex = Assert.Throws<NotSupportedException>(() => HistorianTypeMapper.ToHistorianDataType(d));
Assert.Contains("losslessly", ex.Message);
}
[Fact] // matrix guard: a new DriverDataType member must be classified (mapped or explicitly deferred)
public void Every_DriverDataType_member_is_classified()
{