test(runtime): recording subscribable driver factory + enabled-driver v3 seed

2026-08-20 09:42:33 -04:00
parent daaeb854d6
commit b3a71f6655
4 changed files with 235 additions and 8 deletions
@@ -521,3 +521,19 @@ drifted (it claimed the field was set at the end of `PushDesiredSubscriptions`;
 `ApplyDesiredSubscriptions`) — deleted with the field rather than corrected. The stale
 "dropped-driver fallback" comment on the old `SendAuthoredOnly` local function was rewritten as the
 `SendDesiredSubscriptions` remarks naming the three real consumers.
+
+### T4 — test harness (seeder `enabled` flag + recording driver factory)
+
+Test-only, additive, source-compatible: every pre-existing `SeedV3Deployment` / `SpawnHostAndApply`
+call site compiles and behaves identically (the new parameters are trailing and default to today's
+values). Gate: `--filter "…~DriverHostActor|…~DriverInstanceActor"` → **179/179 passed** (the plan
+named `--filter "…~V3"`, which matches nothing — the seeder's four consumers are all `DriverHostActor*`
+classes; the wider filter is the same set plus more).
+
+**Deviation (recorded).** The plan lists one new seeder parameter (`enabled`); a second was needed and
+added: `IReadOnlyDictionary<string, string>? tagConfigByTag = null`. The seeder hard-codes
+`TagConfig = "{}"` on every tag, and a raw tag's alarm is derived *only* from `TagConfig.alarm` via
+`TagConfigIntent.Parse` (`AddressSpaceComposer.cs:769-772`) — so without it there is no way to seed the
+alarm-bearing raw tag that `Operator_restart_re_subscribes_alarm_refs_too` (a test the plan itself
+specifies) requires. It is trailing and optional, so it is the same source-compatible shape as
+`enabled`.
@@ -25,7 +25,7 @@
    {
      "id": "T4",
      "subject": "Test harness: V3ArtifactSeeder enabled flag + RecordingSubscribableDriver(Factory) with a crash seam",
-      "status": "pending",
+      "status": "done",
      "blockedBy": []
    },
    {
@@ -188,3 +188,196 @@ internal sealed class StubHandle : ISubscriptionHandle
    /// <summary>Gets the diagnostic ID of the subscription.</summary>
    public string DiagnosticId => "stub-sub";
 }
+
+/// <summary>
+///     A per-instance recording driver for the restart / re-subscribe suite (03/S16, U6): unlike
+///     <see cref="SubscribableStubDriver"/> it carries the <b>spec's</b> <see cref="DriverInstanceId"/>
+///     (<see cref="StubDriver"/> hard-codes a constant on a non-virtual member), and it counts and records the
+///     alarm subscription alongside the value one — the two travel in a single
+///     <c>SetDesiredSubscriptions</c> but through two different child code paths, so both need observing.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>The falsification bar these counters exist for:</b> a restart test must assert a FUNCTION the new
+///         incarnation performs — it subscribed, it re-initialised — never that the incarnation exists.
+///         Existence is what
+///         <c>DriverHostActorReconcileTests.RestartDriver_respawns_the_child_without_an_actor_name_collision</c>
+///         asserts, and that test passes against the very defect 03/S16 names.
+///     </para>
+///     <para>
+///         <b><see cref="FireMalformedDataChange"/> is the supervision crash seam</b> — see
+///         <c>DriverHostActorRestartTests</c>'s file remarks for why the obvious alternatives do not work.
+///     </para>
+/// </remarks>
+internal sealed class RecordingSubscribableDriver : IDriver, ISubscribable, IAlarmSource
+{
+    private readonly Lock _gate = new();
+    private readonly StubHandle _handle = new();
+    private readonly RecordingAlarmHandle _alarmHandle = new();
+    private int _initializeCount;
+    private int _shutdownCount;
+    private int _subscribeCount;
+    private int _subscribeAlarmsCount;
+    private IReadOnlyList<string>? _lastSubscribedRefs;
+    private IReadOnlyList<string>? _lastSubscribedAlarmRefs;
+
+    /// <summary>Initializes a new recording driver stamped with the spec's identity.</summary>
+    /// <param name="driverInstanceId">The driver instance id from the spec that created it.</param>
+    /// <param name="driverType">The driver type from the spec that created it.</param>
+    public RecordingSubscribableDriver(string driverInstanceId, string driverType)
+    {
+        DriverInstanceId = driverInstanceId;
+        DriverType = driverType;
+    }
+
+    /// <inheritdoc />
+    public string DriverInstanceId { get; }
+
+    /// <inheritdoc />
+    public string DriverType { get; }
+
+    /// <summary>Number of <see cref="InitializeAsync"/> calls. A supervision restart re-uses the SAME driver
+    /// object (the Props closure captured it), so this going 1 to 2 is how the reprovision is observed.</summary>
+    public int InitializeCount => Volatile.Read(ref _initializeCount);
+
+    /// <summary>Number of <see cref="ShutdownAsync"/> calls — a restart's <c>PostStop</c> raises it.</summary>
+    public int ShutdownCount => Volatile.Read(ref _shutdownCount);
+
+    /// <summary>Number of <see cref="SubscribeAsync"/> calls.</summary>
+    public int SubscribeCount => Volatile.Read(ref _subscribeCount);
+
+    /// <summary>Number of <see cref="SubscribeAlarmsAsync"/> calls.</summary>
+    public int SubscribeAlarmsCount => Volatile.Read(ref _subscribeAlarmsCount);
+
+    /// <summary>The refs passed to the most recent <see cref="SubscribeAsync"/>, or null if never called.</summary>
+    public IReadOnlyList<string>? LastSubscribedRefs
+    {
+        get { lock (_gate) return _lastSubscribedRefs; }
+    }
+
+    /// <summary>The refs passed to the most recent <see cref="SubscribeAlarmsAsync"/>, or null if never called.</summary>
+    public IReadOnlyList<string>? LastSubscribedAlarmRefs
+    {
+        get { lock (_gate) return _lastSubscribedAlarmRefs; }
+    }
+
+    /// <inheritdoc />
+    public Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
+    {
+        Interlocked.Increment(ref _initializeCount);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken) => Task.CompletedTask;
+
+    /// <inheritdoc />
+    public Task ShutdownAsync(CancellationToken cancellationToken)
+    {
+        Interlocked.Increment(ref _shutdownCount);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public DriverHealth GetHealth() => new(DriverState.Healthy, DateTime.UtcNow, null);
+
+    /// <inheritdoc />
+    public event EventHandler<DataChangeEventArgs>? OnDataChange;
+
+    /// <inheritdoc />
+    public Task<ISubscriptionHandle> SubscribeAsync(
+        IReadOnlyList<string> fullReferences, TimeSpan publishingInterval, CancellationToken cancellationToken)
+    {
+        Interlocked.Increment(ref _subscribeCount);
+        lock (_gate) _lastSubscribedRefs = fullReferences.ToArray();
+        return Task.FromResult<ISubscriptionHandle>(_handle);
+    }
+
+    /// <inheritdoc />
+    public Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken) => Task.CompletedTask;
+
+    /// <inheritdoc />
+    public event EventHandler<AlarmEventArgs>? OnAlarmEvent;
+
+    /// <inheritdoc />
+    public Task<IAlarmSubscriptionHandle> SubscribeAlarmsAsync(
+        IReadOnlyList<string> sourceNodeIds, CancellationToken cancellationToken)
+    {
+        Interlocked.Increment(ref _subscribeAlarmsCount);
+        lock (_gate) _lastSubscribedAlarmRefs = sourceNodeIds.ToArray();
+        return Task.FromResult<IAlarmSubscriptionHandle>(_alarmHandle);
+    }
+
+    /// <inheritdoc />
+    public Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken) => Task.CompletedTask;
+
+    /// <inheritdoc />
+    public Task AcknowledgeAsync(
+        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements, CancellationToken cancellationToken) => Task.CompletedTask;
+
+    /// <summary>Fires a well-formed data change (the ordinary production path).</summary>
+    /// <param name="fullRef">The reference whose value changed.</param>
+    /// <param name="value">The new value.</param>
+    public void FireDataChange(string fullRef, object? value) =>
+        OnDataChange?.Invoke(this, new DataChangeEventArgs(
+            _handle, fullRef, new DataValueSnapshot(value, 0u, DateTime.UtcNow, DateTime.UtcNow)));
+
+    /// <summary>
+    ///     Raises <see cref="OnDataChange"/> with a NULL <c>Snapshot</c> — the supervision crash seam.
+    ///     <c>DataChangeEventArgs</c> is a positional record with no null validation, and the actor's
+    ///     <c>OnDataChangeForward</c> dereferences <c>msg.Snapshot</c> unguarded ON THE ACTOR THREAD, so this
+    ///     produces a genuine unhandled exception inside the child, which Akka's default decider turns into a
+    ///     Restart. The fault itself is arbitrary; what is under test is the RECOVERY.
+    /// </summary>
+    /// <param name="fullRef">The reference to name in the malformed event.</param>
+    public void FireMalformedDataChange(string fullRef) =>
+        OnDataChange?.Invoke(this, new DataChangeEventArgs(_handle, fullRef, null!));
+
+    /// <summary>Raises <see cref="OnAlarmEvent"/>; present so the event is not merely written-to-never-read.</summary>
+    /// <param name="conditionId">The condition id to raise.</param>
+    public void FireAlarm(string conditionId) =>
+        OnAlarmEvent?.Invoke(this, new AlarmEventArgs(
+            _alarmHandle, conditionId, conditionId, "AlarmCondition", "test", AlarmSeverity.High, DateTime.UtcNow));
+
+    private sealed class RecordingAlarmHandle : IAlarmSubscriptionHandle
+    {
+        /// <inheritdoc />
+        public string DiagnosticId => "recording-alarm-sub";
+    }
+}
+
+/// <summary>
+///     An <see cref="IDriverFactory"/> that hands out <see cref="RecordingSubscribableDriver"/>s and KEEPS
+///     every one it created, in creation order. The list — not a single "the driver" reference — is the point:
+///     an operator Restart tears the child down and spawns a new one around a NEW driver object, so the
+///     assertion subject is <c>Created[1]</c>, while a SUPERVISION restart re-uses <c>Created[0]</c> (the Props
+///     closure captured it) and part of the assertion is that <c>Created.Count</c> stayed 1.
+/// </summary>
+internal sealed class RecordingSubscribableDriverFactory : IDriverFactory
+{
+    private readonly string _supportedType;
+    private readonly Lock _gate = new();
+    private readonly List<RecordingSubscribableDriver> _created = new();
+
+    /// <summary>Initializes a factory that materialises exactly one driver type.</summary>
+    /// <param name="supportedType">The driver type this factory answers for.</param>
+    public RecordingSubscribableDriverFactory(string supportedType) => _supportedType = supportedType;
+
+    /// <summary>Every driver this factory created, in creation order.</summary>
+    public IReadOnlyList<RecordingSubscribableDriver> Created
+    {
+        get { lock (_gate) return _created.ToArray(); }
+    }
+
+    /// <inheritdoc />
+    public IDriver? TryCreate(string driverType, string driverInstanceId, string driverConfigJson)
+    {
+        if (!string.Equals(driverType, _supportedType, StringComparison.Ordinal)) return null;
+        var driver = new RecordingSubscribableDriver(driverInstanceId, driverType);
+        lock (_gate) _created.Add(driver);
+        return driver;
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyCollection<string> SupportedTypes => new[] { _supportedType };
+}
@@ -9,6 +9,7 @@ using ZB.MOM.WW.OtOpcUa.Commons.Types;
 using ZB.MOM.WW.OtOpcUa.Configuration;
 using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
 using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 using ZB.MOM.WW.OtOpcUa.Runtime.Drivers;
 using ZB.MOM.WW.OtOpcUa.Runtime.OpcUa;

@@ -36,16 +37,28 @@ public static class V3ArtifactSeeder
    /// <param name="rev">The revision hash the deployment is sealed under.</param>
    /// <param name="rawTags">The raw tags to materialise, one per (driver, device, tag).</param>
    /// <param name="unsRefs">UNS references projecting a raw tag (by <c>BackingTag</c>) into an equipment.</param>
+    /// <param name="enabled">Whether the seeded <c>DriverInstances</c> are Enabled — i.e. whether applying this
+    /// artifact actually SPAWNS driver children. Defaults to <c>false</c>, the shape every pre-existing caller
+    /// relies on: the value-routing suites inject values straight into the host and want no children at all.
+    /// The restart/re-subscribe suite (03/S16) passes <c>true</c>, because its whole subject is what a spawned
+    /// child is handed.</param>
+    /// <param name="tagConfigByTag">Optional per-tag <c>TagConfig</c> JSON, keyed by tag name; tags not named
+    /// here keep the default <c>"{}"</c>. The only way to seed an <b>alarm-bearing</b> raw tag (the alarm intent
+    /// is parsed out of <c>TagConfig.alarm</c> by <c>TagConfigIntent</c>), which the alarm-ref half of the
+    /// restart suite needs — an alarm-bearing raw tag is excluded from the VALUE subscription set and carried
+    /// in the alarm one instead, so the two travel through different child code paths.</param>
    /// <returns>The seeded deployment's id.</returns>
    public static DeploymentId SeedV3Deployment(
        IDbContextFactory<OtOpcUaConfigDbContext> db, RevisionHash rev,
        (string Driver, string DriverName, string Device, string Tag, string DataType, bool Writable)[] rawTags,
-        (string Area, string Line, string Equip, string BackingTag, string? Effective)[] unsRefs)
+        (string Area, string Line, string Equip, string BackingTag, string? Effective)[] unsRefs,
+        bool enabled = false,
+        IReadOnlyDictionary<string, string>? tagConfigByTag = null)
    {
        var drivers = rawTags
            .Select(t => (t.Driver, t.DriverName))
            .Distinct()
-            .Select(d => new { DriverInstanceId = d.Driver, RawFolderId = "rf-plant", Name = d.DriverName, DriverType = "Modbus", DriverConfig = "{}", ClusterId = "c1", Enabled = false })
+            .Select(d => new { DriverInstanceId = d.Driver, RawFolderId = "rf-plant", Name = d.DriverName, DriverType = "Modbus", DriverConfig = "{}", ClusterId = "c1", Enabled = enabled })
            .ToArray();
        var devices = rawTags
            .Select(t => (t.Driver, t.Device))
@@ -60,7 +73,7 @@ public static class V3ArtifactSeeder
            Name = t.Tag,
            DataType = t.DataType,
            AccessLevel = t.Writable ? 1 : 0, // TagAccessLevel.ReadWrite = 1
-            TagConfig = "{}",
+            TagConfig = tagConfigByTag is not null && tagConfigByTag.TryGetValue(t.Tag, out var tc) ? tc : "{}",
        }).ToArray();

        // UNS topology: one area/line per distinct (Area, Line); one equipment per (Area, Line, Equip).
@@ -114,13 +127,17 @@ public static class V3ArtifactSeeder
    /// <param name="localNode">The host's local node id.</param>
    /// <param name="deploymentId">The deployment to dispatch.</param>
    /// <param name="rev">The revision hash the deployment was sealed under.</param>
+    /// <param name="driverFactory">Optional driver factory forwarded to <c>DriverHostActor.Props</c>. Null (the
+    /// default, preserving every existing call site) leaves the host on its own default, which materialises no
+    /// real drivers. Supply one — with <c>enabled: true</c> on the seed — to actually spawn driver children.</param>
    /// <returns>The host actor plus the publish and mux probes wired into it.</returns>
    public static (IActorRef Actor, TestProbe Publish, TestProbe Mux) SpawnHostAndApply(
        TestKitBase kit, IDbContextFactory<OtOpcUaConfigDbContext> db,
-        NodeId localNode, DeploymentId deploymentId, RevisionHash rev)
+        NodeId localNode, DeploymentId deploymentId, RevisionHash rev,
+        IDriverFactory? driverFactory = null)
    {
        var publish = kit.CreateTestProbe();
-        var (actor, mux, coordinator) = Spawn(kit, db, localNode, publish.Ref);
+        var (actor, mux, coordinator) = Spawn(kit, db, localNode, publish.Ref, driverFactory);

        Dispatch(actor, coordinator, deploymentId, rev);
        publish.ExpectMsg<OpcUaPublishActor.RebuildAddressSpace>(RuntimeActorTestBase.PresenceBudget);
@@ -140,14 +157,14 @@ public static class V3ArtifactSeeder
        TestKitBase kit, IDbContextFactory<OtOpcUaConfigDbContext> db,
        NodeId localNode, DeploymentId deploymentId, RevisionHash rev)
    {
-        var (actor, mux, coordinator) = Spawn(kit, db, localNode, opcUaPublishActor: null);
+        var (actor, mux, coordinator) = Spawn(kit, db, localNode, opcUaPublishActor: null, driverFactory: null);
        Dispatch(actor, coordinator, deploymentId, rev);
        return (actor, mux);
    }

    private static (IActorRef Actor, TestProbe Mux, TestProbe Coordinator) Spawn(
        TestKitBase kit, IDbContextFactory<OtOpcUaConfigDbContext> db, NodeId localNode,
-        IActorRef? opcUaPublishActor)
+        IActorRef? opcUaPublishActor, IDriverFactory? driverFactory)
    {
        var coordinator = kit.CreateTestProbe();
        var mux = kit.CreateTestProbe();
@@ -155,6 +172,7 @@ public static class V3ArtifactSeeder

        var actor = kit.Sys.ActorOf(DriverHostActor.Props(
            db, localNode, coordinator.Ref,
+            driverFactory: driverFactory,
            localRoles: new HashSet<string> { "driver" },
            dependencyMux: mux.Ref,
            opcUaPublishActor: opcUaPublishActor,