Merge lane C: control plane, host, security (#733)

Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 14:09:08 -04:00
parent 3e0606af58 5097444d56
commit 7bcb6331ed
61 changed files with 6603 additions and 453 deletions
@@ -26,7 +26,11 @@ public sealed class Deployment
    public DateTime CreatedAtUtc { get; init; } = DateTime.UtcNow;

    /// <summary>Gets or sets the serialized artifact blob containing the configuration.</summary>
-    public byte[] ArtifactBlob { get; init; } = Array.Empty<byte>();
+    /// <remarks>
+    ///     Settable (not init-only) so the retention sweep can EMPTY it on an old terminal row. An empty blob
+    ///     is "no artifact" to every reader (#485), so the audit row survives with its bytes retired.
+    /// </remarks>
+    public byte[] ArtifactBlob { get; set; } = Array.Empty<byte>();

    /// <summary>Gets or sets the row version for optimistic concurrency control.</summary>
    public byte[] RowVersion { get; set; } = Array.Empty<byte>();
@@ -0,0 +1,36 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace ZB.MOM.WW.OtOpcUa.Configuration.Migrations
+{
+    /// <summary>
+    ///     Enables <c>ALLOW_SNAPSHOT_ISOLATION</c> on the config database so the deploy path can read every
+    ///     table inside one <c>SNAPSHOT</c> transaction (<c>DraftSnapshotFactory.FromConfigDbAsync</c>):
+    ///     the validator and the artifact composer then see one consistent state instead of two reads
+    ///     an AdminUI save can land between. No schema change — the model snapshot is untouched.
+    /// </summary>
+    /// <remarks>
+    ///     <c>ALTER DATABASE</c> cannot run inside the user transaction the migrator wraps each migration in,
+    ///     hence <c>suppressTransaction: true</c>. Turning the option ON does not need exclusive access (unlike
+    ///     <c>READ_COMMITTED_SNAPSHOT</c>); it waits for in-flight transactions and then takes effect. Down
+    ///     leaves it ON: a database that has run with it is not harmed by keeping it, and switching it OFF
+    ///     would fail any deploy running at that instant.
+    /// </remarks>
+    public partial class EnableSnapshotIsolation : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.Sql(
+                "ALTER DATABASE CURRENT SET ALLOW_SNAPSHOT_ISOLATION ON;",
+                suppressTransaction: true);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            // Deliberately a no-op; see the class remarks.
+        }
+    }
+}
@@ -66,6 +66,23 @@ public sealed class DraftSnapshot
    /// silently dropped when the permission trie is built, so the grant has to be caught here instead.</summary>
    public IReadOnlyList<NodeAcl> NodeAcls { get; init; } = [];

+    /// <summary>
+    ///     Cluster rows. Not read by the row-level rules; carried so the deploy path validates the cluster
+    ///     topology (<see cref="DraftValidator.ValidateClusterTopology"/>) and composes the artifact from
+    ///     the SAME read as every other table — a second read between validate and compose is exactly how
+    ///     an edit ships unvalidated.
+    /// </summary>
+    public IReadOnlyList<ServerCluster> ServerClusters { get; init; } = [];
+
+    /// <summary>Cluster-node rows; see <see cref="ServerClusters"/> for why they ride the snapshot.</summary>
+    public IReadOnlyList<ClusterNode> ClusterNodes { get; init; } = [];
+
+    /// <summary>
+    ///     Data-plane API keys (peppered HMAC only, never a secret). Not validated; carried so the artifact
+    ///     composer ships the keys a driver-only node authenticates against from the one consistent read.
+    /// </summary>
+    public IReadOnlyList<ApiKey> ApiKeys { get; init; } = [];
+
    /// <summary>Prior Equipment rows (any generation, same cluster) for stability checks.</summary>
    public IReadOnlyList<Equipment> PriorEquipment { get; init; } = [];

@@ -1,3 +1,4 @@
+using System.Data;
 using Microsoft.EntityFrameworkCore;

 namespace ZB.MOM.WW.OtOpcUa.Configuration.Validation;
@@ -21,6 +22,16 @@ namespace ZB.MOM.WW.OtOpcUa.Configuration.Validation;
 ///         / <see cref="DraftSnapshot.Site"/> are left null so the path-length rule uses its
 ///         conservative upper bound.
 ///     </para>
+///     <para>
+///         <b>One consistent read.</b> On a relational provider the tables are read inside a
+///         <see cref="IsolationLevel.Snapshot"/> transaction, so a <c>/uns</c> or <c>/raw</c> save that
+///         lands mid-read cannot leave half the tables on the new state and half on the old. The deploy path
+///         validates AND composes its artifact from this one snapshot, which is what makes "the artifact the
+///         validator never saw" unrepresentable. SQL Server requires <c>ALLOW_SNAPSHOT_ISOLATION ON</c>
+///         (migration <c>EnableSnapshotIsolation</c>); without it the first query fails with error 3952 and
+///         the deploy is rejected rather than silently read unisolated. A non-relational provider (the
+///         InMemory test provider) and a context already inside a transaction read without one.
+///     </para>
 /// </remarks>
 public static class DraftSnapshotFactory
 {
@@ -29,6 +40,29 @@ public static class DraftSnapshotFactory
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A snapshot populated from the live DB, ready for <see cref="DraftValidator.Validate"/>.</returns>
    public static async Task<DraftSnapshot> FromConfigDbAsync(OtOpcUaConfigDbContext db, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(db);
+
+        var ownsTransaction = db.Database.IsRelational() && db.Database.CurrentTransaction is null;
+        var tx = ownsTransaction
+            ? await db.Database.BeginTransactionAsync(IsolationLevel.Snapshot, ct).ConfigureAwait(false)
+            : null;
+        await using (tx)
+        {
+            var snapshot = await ReadAsync(db, ct).ConfigureAwait(false);
+            // Read-only: committing releases the snapshot's version-store reservation; nothing was written.
+            if (tx is not null) await tx.CommitAsync(ct).ConfigureAwait(false);
+            return snapshot;
+        }
+    }
+
+    // Every composed table is read ORDERED BY ITS NATURAL KEY, server-side. That order IS the deployment
+    // artifact's order (ConfigComposer.Compose serialises the snapshot as given): it is exactly the order the
+    // pre-R03:3.2 composer's own queries produced — the database collation's, case-insensitive on SQL Server —
+    // so the revision hash of an unchanged configuration is byte-identical across the refactor (fix round 1;
+    // pinned by ConfigComposerSqlServerHashStabilityTests). Re-sorting in memory with any other comparer would
+    // re-hash every mixed-case configuration and make drift detection report the whole fleet drifted.
+    private static async Task<DraftSnapshot> ReadAsync(OtOpcUaConfigDbContext db, CancellationToken ct)
        => new DraftSnapshot
        {
            // GenerationId=0 and null Enterprise/Site are intentional conservative fallbacks at the
@@ -36,23 +70,26 @@ public static class DraftSnapshotFactory
            // EquipmentUuid checks run in separate validator passes — no rule here reads these fields.
            GenerationId = 0,            // generation model dropped; placeholder (no rule reads it)
            ClusterId = string.Empty,    // global snapshot; rules compare entity ClusterId fields, not this
+            ServerClusters     = await db.ServerClusters.AsNoTracking().OrderBy(x => x.ClusterId).ToListAsync(ct),
+            ClusterNodes       = await db.ClusterNodes.AsNoTracking().OrderBy(x => x.NodeId).ToListAsync(ct),
            // v3: Namespace entity retired — no namespace list to materialize. The Raw tree
            // (RawFolders/TagGroups) + UnsTagReferences feed the v3 rules (charset, tagname length,
            // effective-leaf uniqueness).
-            RawFolders         = await db.RawFolders.AsNoTracking().ToListAsync(ct),
-            DriverInstances    = await db.DriverInstances.AsNoTracking().ToListAsync(ct),
-            Devices            = await db.Devices.AsNoTracking().ToListAsync(ct),
-            TagGroups          = await db.TagGroups.AsNoTracking().ToListAsync(ct),
-            UnsAreas           = await db.UnsAreas.AsNoTracking().ToListAsync(ct),
-            UnsLines           = await db.UnsLines.AsNoTracking().ToListAsync(ct),
-            Equipment          = await db.Equipment.AsNoTracking().ToListAsync(ct),
-            Tags               = await db.Tags.AsNoTracking().ToListAsync(ct),
-            UnsTagReferences   = await db.UnsTagReferences.AsNoTracking().ToListAsync(ct),
-            VirtualTags        = await db.VirtualTags.AsNoTracking().ToListAsync(ct),
-            ScriptedAlarms     = await db.ScriptedAlarms.AsNoTracking().ToListAsync(ct),
-            Scripts            = await db.Scripts.AsNoTracking().ToListAsync(ct),
-            PollGroups         = await db.PollGroups.AsNoTracking().ToListAsync(ct),
-            NodeAcls           = await db.NodeAcls.AsNoTracking().ToListAsync(ct),
+            RawFolders         = await db.RawFolders.AsNoTracking().OrderBy(x => x.RawFolderId).ToListAsync(ct),
+            DriverInstances    = await db.DriverInstances.AsNoTracking().OrderBy(x => x.DriverInstanceId).ToListAsync(ct),
+            Devices            = await db.Devices.AsNoTracking().OrderBy(x => x.DeviceId).ToListAsync(ct),
+            TagGroups          = await db.TagGroups.AsNoTracking().OrderBy(x => x.TagGroupId).ToListAsync(ct),
+            UnsAreas           = await db.UnsAreas.AsNoTracking().OrderBy(x => x.UnsAreaId).ToListAsync(ct),
+            UnsLines           = await db.UnsLines.AsNoTracking().OrderBy(x => x.UnsLineId).ToListAsync(ct),
+            Equipment          = await db.Equipment.AsNoTracking().OrderBy(x => x.EquipmentId).ToListAsync(ct),
+            Tags               = await db.Tags.AsNoTracking().OrderBy(x => x.TagId).ToListAsync(ct),
+            UnsTagReferences   = await db.UnsTagReferences.AsNoTracking().OrderBy(x => x.UnsTagReferenceId).ToListAsync(ct),
+            VirtualTags        = await db.VirtualTags.AsNoTracking().OrderBy(x => x.VirtualTagId).ToListAsync(ct),
+            ScriptedAlarms     = await db.ScriptedAlarms.AsNoTracking().OrderBy(x => x.ScriptedAlarmId).ToListAsync(ct),
+            Scripts            = await db.Scripts.AsNoTracking().OrderBy(x => x.ScriptId).ToListAsync(ct),
+            PollGroups         = await db.PollGroups.AsNoTracking().OrderBy(x => x.PollGroupId).ToListAsync(ct),
+            NodeAcls           = await db.NodeAcls.AsNoTracking().OrderBy(x => x.NodeAclId).ToListAsync(ct),
+            ApiKeys            = await db.ApiKeys.AsNoTracking().OrderBy(x => x.ApiKeyId).ToListAsync(ct),
            PriorEquipment     = [],   // intentional: no prior-generation table to diff against at this level
            ActiveReservations = await db.ExternalIdReservations
                .AsNoTracking()