using System.Runtime.CompilerServices;
using Google.Protobuf.WellKnownTypes;
using Microsoft.Extensions.Logging.Abstractions;
using Opc.Ua;
using Opc.Ua.Client;
using Shouldly;
using Xunit;
using ZB.MOM.WW.HistorianGateway.Contracts.Grpc;
using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
using ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway;
using static ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests.ServerEventRig;
namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests;
///
/// Gitea #886 over a real SDK session, with the production Gateway backend on a deterministic AVEVA-shaped gateway: a
/// REAL equipment folder — whose id (EqA) is not a Galaxy object name — serves the AVEVA history of the Galaxy
/// objects behind its native conditions, here two (Oven_007 and OvenDoor_07): each object's own events
/// and its attribute alarms, never a prefix sibling (Oven_0070), merged in time order across paging and reverse
/// reads, with the live condition's SourceNode / ConditionName and the live Galaxy severity, and only behind the
/// folder's own HistoryRead verdict.
///
///
/// Topology, as the applier builds it from a Galaxy deployment: raw folder Plant/Galaxy/Oven7 holds two native
/// conditions, TempHi (attributeRef Oven_007.TempHiAlarm) and DoorOpen
/// (OvenDoor_07.DoorAlarm), both wired to equipment EqA; raw folder Plant/Galaxy/Line3 holds
/// Jam (Line3_Conveyor.JamAlarm), wired to EqB. The fake gateway filters a per-source read more
/// loosely than the real one (Source_Object begins with the source), so the sibling's rows reach OtOpcUa and
/// their absence is OtOpcUa's filter at work.
///
public sealed class GalaxyEquipmentEventHistoryWireTests
{
private const string OvenFolder = "Plant/Galaxy/Oven7";
private const string LineFolder = "Plant/Galaxy/Line3";
private const string TempHi = OvenFolder + "/TempHi";
private const string DoorOpen = OvenFolder + "/DoorOpen";
private const string Jam = LineFolder + "/Jam";
private static readonly DateTime Epoch = new(2026, 11, 10, 11, 0, 0, DateTimeKind.Utc);
/// The stored AVEVA rows. A null condition variable is an object-level system event.
private static readonly AvevaRow[] Stored =
[
new("o-stop", "Oven_007", "Oven_007", "System.Stop", 0, 999, null),
new("l-set", "Line3_Conveyor.Belt", "Line3_Conveyor", "Alarm.Set", 1, 300, "Line3_Conveyor.JamAlarm"),
new("o-temp-set", "Oven_007.Temp", "Oven_007", "Alarm.Set", 2, 500, "Oven_007.TempHiAlarm"),
new("d-set", "OvenDoor_07.Door", "OvenDoor_07", "Alarm.Set", 2, 700, "OvenDoor_07.DoorAlarm"), // a tie across objects
new("a-oven-tie", "Oven_007.Temp", "Oven_007", "Alarm.Ack", 2, 500, "Oven_007.TempHiAlarm"), // and within one, stored later
new("o-press-set", "Oven_007.Pressure", "Oven_007", "Alarm.Set", 3, 100, "Oven_007.PressureHiAlarm"), // no live condition here
new("s-set", "Oven_0070.Temp", "Oven_0070", "Alarm.Set", 4, 500, "Oven_0070.TempHiAlarm"), // prefix sibling
new("d-clear", "OvenDoor_07.Door", "OvenDoor_07", "Alarm.Clear", 5, 700, "OvenDoor_07.DoorAlarm"),
new("o-temp-clear", "Oven_007.Temp", "Oven_007", "Alarm.Clear", 6, 500, "oven_007.temphialarm"), // Galaxy names: any case
new("l-clear", "Line3_Conveyor.Belt", "Line3_Conveyor", "Alarm.Clear", 7, 300, "Line3_Conveyor.JamAlarm"),
new("o-start", "Oven_007", "Oven_007", "System.Start", 8, 999, null),
];
/// EqA's events forward: by time, then source (the folder's ordinal-sorted list: OvenDoor_07 before
/// Oven_007), then the order the gateway returned them in — so a-oven-tie follows o-temp-set.
private static readonly string[] EqAEvents =
["o-stop", "d-set", "o-temp-set", "a-oven-tie", "o-press-set", "d-clear", "o-temp-clear", "o-start"];
/// EqA's events reverse: newest first; the Gateway's walked-back reverse read orders ties by EventId,
/// descending, as it did before #886.
private static readonly string[] EqAEventsReverse =
["o-start", "o-temp-clear", "d-clear", "o-press-set", "o-temp-set", "d-set", "a-oven-tie", "o-stop"];
[Fact]
public async Task An_equipment_folder_serves_the_aveva_history_of_every_galaxy_object_behind_it()
{
var ct = TestContext.Current.CancellationToken;
await using var rig = await StartAsync("GalaxyEqHistory", encrypted: false, ct);
var gateway = new AvevaShapedGateway();
rig.Nm.HistorianDataSource = new GatewayHistorianDataSource(gateway, NullLogger.Instance);
Materialise(rig);
rig.Enforce(false, [Key()]);
using var session = await rig.ConnectAsync(anonymous: true, ct);
var all = await ReadAsync(session, Uns(session, EqA), forward: true, page: 0, ct);
all.Status.ShouldBe(StatusCodes.Good);
all.Rows.Select(r => r.Id).ShouldBe(EqAEvents);
gateway.Requested.ShouldBe(new[] { EqA, "OvenDoor_07", "Oven_007" },
"the folder's own source and one request per Galaxy object behind it (no multi-source request exists)");
gateway.Yielded.ShouldContain("s-set", "the sibling's rows reached OtOpcUa, so their absence is its filter's doing");
var byId = all.Rows.ToDictionary(r => r.Id);
// Each event keeps the source the historian reported.
byId["o-temp-set"].Source.ShouldBe("Oven_007.Temp");
byId["o-stop"].Source.ShouldBe("Oven_007");
// A row naming a condition that fires on this folder carries that live condition (any-case reference).
byId["o-temp-set"].SourceNode.ShouldBe(TempHi);
byId["o-temp-clear"].SourceNode.ShouldBe(TempHi);
byId["o-temp-set"].ConditionName.ShouldBe("TempHi");
byId["d-set"].SourceNode.ShouldBe(DoorOpen);
byId["d-set"].ConditionName.ShouldBe("DoorOpen");
// An alarm of the object with no condition wired here: served (object rule), but names no node.
byId["o-press-set"].SourceNode.ShouldBeNull();
byId["o-press-set"].ConditionName.ShouldBe("PressureHiAlarm");
// A system event has no condition at all.
byId["o-stop"].SourceNode.ShouldBeNull();
byId["o-stop"].ConditionName.ShouldBeNull();
// Severity follows the live Galaxy table, AVEVA priority 1 = most urgent (lmxopcua#887): 500 → 750 (High),
// 700 → 500 (Medium), 100 → 1000 (Critical); a system event (priority 999, AVEVA severity 0) is not an alarm → 1.
byId["o-temp-set"].Severity.ShouldBe((ushort)750);
byId["d-set"].Severity.ShouldBe((ushort)500);
byId["o-press-set"].Severity.ShouldBe((ushort)1000);
byId["o-stop"].Severity.ShouldBe((ushort)1);
// The raw device folder the conditions hang under reads the same objects (live: a condition fires on its parent).
var raw = await ReadAsync(session, Raw(session, OvenFolder), forward: true, page: 0, ct);
raw.Rows.Select(r => r.Id).ShouldBe(EqAEvents);
}
[Fact]
public async Task Paging_and_reverse_reads_walk_the_merged_sources_exactly_once()
{
var ct = TestContext.Current.CancellationToken;
await using var rig = await StartAsync("GalaxyEqHistoryPaging", encrypted: false, ct);
var gateway = new AvevaShapedGateway();
rig.Nm.HistorianDataSource = new GatewayHistorianDataSource(gateway, NullLogger.Instance);
Materialise(rig);
rig.Enforce(false, [Key()]);
using var session = await rig.ConnectAsync(anonymous: true, ct);
var node = Uns(session, EqA);
foreach (var page in new uint[] { 1, 2, 3, 4 })
{
var paged = await ReadAsync(session, node, forward: true, page, ct);
paged.Rows.Select(r => r.Id).ShouldBe(EqAEvents, $"forward, {page} a page");
paged.Pages.ShouldBeGreaterThan(1);
var reverse = await ReadAsync(session, node, forward: false, page, ct);
reverse.Rows.Select(r => r.Id).ShouldBe(EqAEventsReverse, $"reverse, {page} a page (newest first, ties descending)");
}
var reverseWhole = await ReadAsync(session, node, forward: false, page: 0, ct);
reverseWhole.Rows.Select(r => r.Id).ShouldBe(EqAEventsReverse);
}
[Fact]
public async Task With_the_acl_on_a_denied_folder_reads_none_of_its_galaxy_objects()
{
var ct = TestContext.Current.CancellationToken;
await using var rig = await StartAsync("GalaxyEqHistoryAcl", encrypted: false, ct);
var gateway = new AvevaShapedGateway();
rig.Nm.HistorianDataSource = new GatewayHistorianDataSource(gateway, NullLogger.Instance);
Materialise(rig);
// Anonymous is granted EqB only: EqA, behind which sit Oven_007 and OvenDoor_07, is denied.
rig.Enforce(true, [Key()], EquipmentGrant(EqB, NodePermissions.ReadOnly));
using var session = await rig.ConnectAsync(anonymous: true, ct);
var denied = await ReadAsync(session, Uns(session, EqA), forward: true, page: 0, ct);
denied.Status.ShouldBe(StatusCodes.BadUserAccessDenied);
denied.HistoryDataIsNull.ShouldBeTrue("a denied folder discloses none of its events");
gateway.Requested.ShouldBeEmpty("the folder verdict is decided before any source is read (fail closed)");
// Positive control: the same session, on the folder it IS granted, gets that folder's Galaxy object.
var granted = await ReadAsync(session, Uns(session, EqB), forward: true, page: 0, ct);
granted.Status.ShouldBe(StatusCodes.Good);
granted.Rows.Select(r => (r.Id, r.SourceNode)).ShouldBe(new (string, string?)[] { ("l-set", Jam), ("l-clear", Jam) });
gateway.Requested.ShouldBe(new[] { EqB, "Line3_Conveyor" });
}
[Fact]
public async Task A_rebuild_forgets_the_galaxy_sources_until_the_conditions_are_bound_again()
{
var ct = TestContext.Current.CancellationToken;
await using var rig = await StartAsync("GalaxyEqHistoryRebuild", encrypted: false, ct);
var gateway = new AvevaShapedGateway();
rig.Nm.HistorianDataSource = new GatewayHistorianDataSource(gateway, NullLogger.Instance);
Materialise(rig);
rig.Enforce(false, [Key()]);
// The redeploy re-creates the same conditions and wiring, but (here) binds no Galaxy reference: the folder is back
// to its own source alone — a stale binding would keep reading the old objects.
rig.Sink.RebuildAddressSpace();
Materialise(rig, bind: false);
using var session = await rig.ConnectAsync(anonymous: true, ct);
var read = await ReadAsync(session, Uns(session, EqA), forward: true, page: 0, ct);
read.Status.ShouldBe(StatusCodes.GoodNoData);
gateway.Requested.ShouldBe(new[] { EqA });
}
/// Materialises the topology the applier builds from the Galaxy deployment (see the class remarks).
private static void Materialise(ServerEventRig rig, bool bind = true)
{
rig.Sink.EnsureFolder(OvenFolder, parentNodeId: null, displayName: "Oven7", realm: AddressSpaceRealm.Raw);
rig.Sink.EnsureFolder(LineFolder, parentNodeId: null, displayName: "Line3", realm: AddressSpaceRealm.Raw);
rig.EnsureEquipment();
foreach (var (id, folder, name, reference, equipment) in new[]
{
(TempHi, OvenFolder, "TempHi", "Oven_007.TempHiAlarm", EqA),
(DoorOpen, OvenFolder, "DoorOpen", "OvenDoor_07.DoorAlarm", EqA),
(Jam, LineFolder, "Jam", "Line3_Conveyor.JamAlarm", EqB),
})
{
rig.Sink.MaterialiseAlarmCondition(id, folder, name, "OffNormalAlarm", 700, AddressSpaceRealm.Raw, isNative: true);
if (bind) rig.Sink.BindNativeAlarmHistory(id, AddressSpaceRealm.Raw, reference);
rig.Sink.WireAlarmNotifiers(id, AddressSpaceRealm.Raw, [equipment], AddressSpaceRealm.Uns);
}
}
private static NodeId Uns(ISession session, string id) =>
new(id, (ushort)session.NamespaceUris.GetIndex(V3NodeIds.UnsNamespaceUri));
private static NodeId Raw(ISession session, string id) =>
new(id, (ushort)session.NamespaceUris.GetIndex(V3NodeIds.RawNamespaceUri));
private static async Task ReadAsync(ISession session, NodeId node, bool forward, uint page, CancellationToken ct)
{
var filter = new EventFilter();
foreach (var leaf in new[] { "EventId", "SourceName", "SourceNode", "Severity", "ConditionName" })
{
var type = leaf == "ConditionName" ? ObjectTypeIds.ConditionType : ObjectTypeIds.BaseEventType;
filter.SelectClauses += new SimpleAttributeOperand(type, new QualifiedName(leaf)) { AttributeId = Attributes.Value };
}
var (from, to) = (Epoch.AddMinutes(-1), Epoch.AddMinutes(1));
var details = new ReadEventDetails
{
StartTime = forward ? from : to, EndTime = forward ? to : from, NumValuesPerNode = page, Filter = filter,
};
var rows = new List();
ByteString point = default;
var pages = 0;
StatusCode first = StatusCodes.Good;
var historyDataIsNull = true;
do
{
var response = await session.HistoryReadAsync(null, new ExtensionObject(details), TimestampsToReturn.Both, false,
new HistoryReadValueId[] { new() { NodeId = node, ContinuationPoint = point } }, ct);
var result = response.Results.ToList().ShouldHaveSingleItem();
if (pages++ == 0) { first = result.StatusCode; historyDataIsNull = result.HistoryData.IsNull; }
if (StatusCode.IsBad(result.StatusCode)) break;
if (!result.HistoryData.IsNull && ExtensionObject.ToEncodeable(result.HistoryData) is HistoryEvent he)
foreach (var e in he.Events.ToList())
{
var f = e.EventFields.ToList();
rows.Add(new Row(
System.Text.Encoding.UTF8.GetString(f[0].GetByteString().Span),
f[1].GetString(),
f[2].IsNull ? null : f[2].GetNodeId().IdentifierAsString,
f[3].GetUInt16(),
f[4].IsNull ? null : f[4].GetString()));
}
point = result.ContinuationPoint;
} while (!point.IsEmpty && pages < 60);
return new EventRead(first, historyDataIsNull, rows, pages);
}
private sealed record AvevaRow(string Id, string Source, string Object, string Type, int Second, int Priority, string? ConditionVariable);
private sealed record Row(string Id, string? Source, string? SourceNode, ushort Severity, string? ConditionName);
private sealed record EventRead(StatusCode Status, bool HistoryDataIsNull, List Rows, int Pages);
///
/// A deterministic gateway answering ReadEvents with AVEVA-shaped rows — SourceName =
/// Source_ProcessVariable and lower-case properties as vd03's HistorianGateway returns them — filtered loosely
/// on source_object, in event-time order with no intra-timestamp order guarantee (here: storage order).
///
private sealed class AvevaShapedGateway : IHistorianGatewayClient
{
private readonly List _requested = [];
private readonly List _yielded = [];
public IReadOnlyList Requested { get { lock (_requested) return _requested.ToList(); } }
public IReadOnlyList Yielded { get { lock (_yielded) return _yielded.ToList(); } }
public async IAsyncEnumerable ReadEventsAsync(
string? sourceName, DateTime startUtc, DateTime endUtc, int maxEvents, [EnumeratorCancellation] CancellationToken ct)
{
lock (_requested) _requested.Add(sourceName);
await Task.Yield();
foreach (var s in Stored.OrderBy(s => s.Second))
{
var at = Epoch.AddSeconds(s.Second);
if (at < startUtc || at > endUtc) continue; // the gateway's end is inclusive
if (sourceName is not null && !s.Object.StartsWith(sourceName, StringComparison.Ordinal)) continue;
lock (_yielded) _yielded.Add(s.Id);
var ts = Timestamp.FromDateTime(at);
var e = new HistorianEvent
{
Id = s.Id, SourceName = s.Source, Type = s.Type, Namespace = "Application Server", EventTime = ts, ReceivedTime = ts,
};
e.Properties["source_object"] = s.Object;
e.Properties["source_processvariable"] = s.Source;
e.Properties["priority"] = s.Priority.ToString(System.Globalization.CultureInfo.InvariantCulture);
// AVEVA's own scale, as vd03 stores it: 0 for an event that is not an alarm, else the priority's 1–4 band.
// Only the 0 is read (not an alarm → Severity 1); an alarm's value comes from its priority.
e.Properties["severity"] = s.ConditionVariable is null ? "0"
: (s.Priority <= 250 ? "1" : s.Priority <= 500 ? "2" : s.Priority <= 750 ? "3" : "4");
if (s.ConditionVariable is not null)
{
e.Properties["source_conditionvariable"] = s.ConditionVariable;
e.Properties["alarm_id"] = $"guid-{s.ConditionVariable.ToLowerInvariant()}";
}
yield return e;
}
}
public Task TagExistsAsync(string tag, CancellationToken ct) => throw new NotSupportedException();
public IAsyncEnumerable ReadRawAsync(string tag, DateTime startUtc, DateTime endUtc, int maxValues, CancellationToken ct) =>
throw new NotSupportedException();
public IAsyncEnumerable ReadAggregateAsync(string tag, DateTime startUtc, DateTime endUtc,
RetrievalMode mode, TimeSpan interval, CancellationToken ct) => throw new NotSupportedException();
public Task> ReadAtTimeAsync(string tag, IReadOnlyList timestampsUtc, CancellationToken ct) =>
throw new NotSupportedException();
public Task WriteLiveValuesAsync(string tag, IReadOnlyList values, CancellationToken ct) =>
throw new NotSupportedException();
public Task SendEventAsync(HistorianEvent evt, CancellationToken ct) => throw new NotSupportedException();
public Task EnsureTagsAsync(IReadOnlyList definitions, CancellationToken ct) =>
throw new NotSupportedException();
public Task ProbeAsync(CancellationToken ct) => Task.FromResult(true);
public Task GetConnectionStatusAsync(CancellationToken ct) => Task.FromResult(new ConnectionStatus());
public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}
}