v3(s7): apply Modbus RawTags exemplar to the S7 driver

Rename S7EquipmentTagParser -> S7TagDefinitionFactory; TryParse(reference) -> FromTagConfig(tagConfig, rawPath, out def) (drops the leading-{ heuristic, keys the def by RawPath, adds inverse ToTagConfig). Replace S7DriverOptions.Tags (pre-declared S7TagDefinition list) with RawTags (IReadOnlyList<RawTagEntry>); the driver builds its RawPath->def table from RawTags at Initialize via the factory (skip+log on miss), resolver is byName-only, DiscoverAsync + init guards + address pre-parse now run off that table. Factory retires the pre-declared DTO tag path (RawTags binding only). Cli BuildOptions serialises typed defs to RawTagEntry. Tests migrated to a S7RawTags helper + FromTagConfig; parser test files renamed. Coordinator's EquipmentTagConfigInspector S7 rename left to Wave-B coordinator; Driver.S7.IntegrationTests (Docker-gated) left red per scope. Driver.S7 + Cli build green; Driver.S7.Tests 264/264, S7.Cli.Tests 49/49.
2026-07-15 20:11:04 -04:00
parent c379e246d0
commit 1e26b9ab58
21 changed files with 425 additions and 251 deletions
@@ -51,8 +51,7 @@ public sealed class S7Driver
        _plcFactory = plcFactory ?? new S7PlcFactory();
        _logger = logger ?? NullLogger<S7Driver>.Instance;
        _resolver = new EquipmentTagRefResolver<S7TagDefinition>(
-            r => _tagsByName.TryGetValue(r, out var t) ? t : null,
-            r => S7EquipmentTagParser.TryParse(r, out var d) ? d : null);
+            r => _tagsByRawPath.TryGetValue(r, out var t) ? t : null);
        // CONV-1: the polling overlay runs on the shared PollGroupEngine (structural array diff +
        // drain-before-dispose + capped-exponential failure backoff + caller-token-filtered OCE),
        // retiring the bespoke S7 poll fork. minInterval 100 ms matches the S7 scan-mailbox floor;
@@ -104,12 +103,15 @@ public sealed class S7Driver
    /// <summary>OPC UA StatusCode used for a genuine device fault (CPU error, hardware fault).</summary>
    private const uint StatusBadDeviceFailure = 0x808B0000u;

-    private readonly Dictionary<string, S7TagDefinition> _tagsByName = new(StringComparer.OrdinalIgnoreCase);
-    private readonly Dictionary<string, S7ParsedAddress> _parsedByName = new(StringComparer.OrdinalIgnoreCase);
+    // v3: the RawPath → definition table. Keyed by RawPath (the v3 tag identity, == def.Name),
+    // case-sensitive ordinal. Built in InitializeAsync from _options.RawTags via the pure factory.
+    private readonly Dictionary<string, S7TagDefinition> _tagsByRawPath = new(StringComparer.Ordinal);
+    // Pre-parsed S7 address per tag, keyed by RawPath (== def.Name). Populated alongside
+    // _tagsByRawPath at init so a config typo fails fast here rather than as a per-read fault.
+    private readonly Dictionary<string, S7ParsedAddress> _parsedByRawPath = new(StringComparer.Ordinal);

-    // Resolves a read/write/subscribe fullReference to a tag definition, bridging the two
-    // authoring models: an authored tag-table entry (by name) OR an equipment tag whose
-    // reference is its raw TagConfig JSON (parsed once via S7EquipmentTagParser, cached).
+    // Resolves a read/write/subscribe fullReference (a RawPath in v3) to a tag definition by a single
+    // authored-table hit; a miss is a miss (the driver surfaces BadNodeIdUnknown, never a parse attempt).
    private readonly EquipmentTagRefResolver<S7TagDefinition> _resolver;

    /// <summary>
@@ -175,6 +177,24 @@ public sealed class S7Driver
            if (HasConfigBody(driverConfigJson))
                _options = S7DriverFactoryExtensions.ParseOptions(_driverInstanceId, driverConfigJson);

+            // v3: build the RawPath → definition table from the authored raw tags BEFORE the config
+            // guards run (they now iterate the mapped table). Each entry's TagConfig blob is mapped by
+            // the pure factory; the entry's WriteIdempotent flag is threaded onto the def (it lives on
+            // the RawTagEntry, not inside the blob). A mapper miss is skipped (logged), never thrown —
+            // one bad tag must not fail the whole driver init.
+            _tagsByRawPath.Clear();
+            _parsedByRawPath.Clear();
+            _resolver.Clear(); // no-op in v3 (the resolver reads the live table by closure); kept for symmetry
+            foreach (var entry in _options.RawTags)
+            {
+                if (S7TagDefinitionFactory.FromTagConfig(entry.TagConfig, entry.RawPath, out var def))
+                    _tagsByRawPath[entry.RawPath] = def with { WriteIdempotent = entry.WriteIdempotent };
+                else
+                    _logger.LogWarning(
+                        "S7 tag config did not map to a definition; skipping. Driver={DriverInstanceId} RawPath={RawPath}",
+                        _driverInstanceId, entry.RawPath);
+            }
+
            // Phase 4d combined config guard. Timer/Counter addresses and the wide/structured
            // types (Int64/UInt64/Float64/String/DateTime) are now SUPPORTED, but only in
            // specific shapes — this rejects the genuinely-unsupported configurations
@@ -220,21 +240,17 @@ public sealed class S7Driver

            // Parse every tag's address once at init so config typos fail fast here instead
            // of surfacing as BadInternalError on every Read against the bad tag. The parser
-            // also rejects bit-offset > 7, DB 0, unknown area letters, etc.
-            _tagsByName.Clear();
-            _parsedByName.Clear();
-            _resolver.Clear(); // drop transient equipment-tag parses so a config change re-parses
-            foreach (var t in _options.Tags)
+            // also rejects bit-offset > 7, DB 0, unknown area letters, etc. Keyed by RawPath
+            // (== def.Name) so Read/Write can pick up the pre-parsed address.
+            foreach (var t in _tagsByRawPath.Values)
            {
-                var parsed = S7AddressParser.Parse(t.Address); // throws FormatException
-                _tagsByName[t.Name] = t;
-                _parsedByName[t.Name] = parsed;
+                _parsedByRawPath[t.Name] = S7AddressParser.Parse(t.Address); // throws FormatException
            }

            _initialized = true;
            _health = new DriverHealth(DriverState.Healthy, DateTime.UtcNow, null);
            _logger.LogInformation("S7Driver connected. Driver={DriverInstanceId} Host={Host} CPU={CpuType} Tags={TagCount}",
-                _driverInstanceId, _options.Host, _options.CpuType, _options.Tags.Count);
+                _driverInstanceId, _options.Host, _options.CpuType, _tagsByRawPath.Count);

            // Kick off the probe loop once the connection is up. Initial HostState stays
            // Unknown until the first probe tick succeeds — avoids broadcasting a premature
@@ -360,7 +376,7 @@ public sealed class S7Driver
    /// </summary>
    private void RejectUnsupportedTagConfigs()
    {
-        foreach (var t in _options.Tags)
+        foreach (var t in _tagsByRawPath.Values)
        {
            var isWide = ByteAnchoredDataTypes.Contains(t.DataType);

@@ -442,7 +458,7 @@ public sealed class S7Driver
    /// </summary>
    private void RejectUnsupportedTagDataTypes()
    {
-        foreach (var t in _options.Tags)
+        foreach (var t in _tagsByRawPath.Values)
        {
            if (UnimplementedDataTypes.Contains(t.DataType))
            {
@@ -573,12 +589,10 @@ public sealed class S7Driver

    private async Task<object> ReadOneAsync(IS7Plc plc, S7TagDefinition tag, CancellationToken ct)
    {
-        // Authored tags pre-parse their address at init (_parsedByName); an equipment-tag ref
-        // (resolved transiently by _resolver) has no _parsedByName entry, so parse its address
-        // on demand. S7AddressParser.Parse throws FormatException on a bad address, which the
-        // caller's catch maps to BadCommunicationError — the same surface a bad authored tag
-        // would have hit at init (transient defs aren't init-validated).
-        var addr = _parsedByName.TryGetValue(tag.Name, out var parsed)
+        // Every tag pre-parses its address at init (_parsedByRawPath); the on-demand
+        // S7AddressParser.Parse is a defensive fallback for a tag not in that table. Parse throws
+        // FormatException on a bad address, which the caller's catch maps to BadCommunicationError.
+        var addr = _parsedByRawPath.TryGetValue(tag.Name, out var parsed)
            ? parsed
            : S7AddressParser.Parse(tag.Address);

@@ -1045,16 +1059,16 @@ public sealed class S7Driver
                    results[i] = new WriteResult(StatusBadNotWritable);
                    continue;
                }
-                // Timer/Counter transient-write guard: a transient equipment-tag ref is always
-                // resolved with Writable=true (S7EquipmentTagParser hardcodes it, and node-level
-                // auth governs writes), so Timer/Counter addresses bypass the !Writable gate above
-                // and would otherwise reach EncodeScalarBlock, which throws NotSupportedException →
-                // BadNotSupported. The docs say Timer/Counter writes return BadNotWritable. Detect
-                // the area here before the call so BOTH authored (caught by guard-d at init) and
-                // transient Timer/Counter writes consistently return BadNotWritable.
+                // Timer/Counter write guard: an equipment tag authored writable=true (S7 mapper
+                // honours the "writable" key, and node-level auth governs writes) whose address is a
+                // Timer/Counter would bypass the !Writable gate above and reach EncodeScalarBlock,
+                // which throws NotSupportedException → BadNotSupported. The docs say Timer/Counter
+                // writes return BadNotWritable. Detect the area here before the call so it
+                // consistently returns BadNotWritable (init guard-d also rejects a writable
+                // Timer/Counter, but the mapper doesn't run that guard).
                // TryParse (not Parse) so a malformed address falls through to the existing
                // error path rather than throwing here.
-                if (_parsedByName.TryGetValue(tag.Name, out var tcParsed)
+                if (_parsedByRawPath.TryGetValue(tag.Name, out var tcParsed)
                        ? tcParsed.Area is S7Area.Timer or S7Area.Counter
                        : (S7AddressParser.TryParse(tag.Address, out tcParsed) && tcParsed.Area is S7Area.Timer or S7Area.Counter))
                {
@@ -1126,11 +1140,11 @@ public sealed class S7Driver
                $"S7 array writes are not yet supported (tag '{tag.Name}'). " +
                "Use individual scalar tags or set Writable=false for read-only arrays.");

-        // Parse the address the same way ReadOneAsync does: authored tags pre-parse at init
-        // (_parsedByName); an equipment-tag ref (resolved transiently) parses on demand. Needed
-        // here so the wide-type write can byte-address the block (the narrow path below addresses
-        // by the raw address string instead).
-        var addr = _parsedByName.TryGetValue(tag.Name, out var parsed)
+        // Parse the address the same way ReadOneAsync does: every tag pre-parses at init
+        // (_parsedByRawPath), with an on-demand parse as a defensive fallback. Needed here so the
+        // wide-type write can byte-address the block (the narrow path below addresses by the raw
+        // address string instead).
+        var addr = _parsedByRawPath.TryGetValue(tag.Name, out var parsed)
            ? parsed
            : S7AddressParser.Parse(tag.Address);

@@ -1370,7 +1384,7 @@ public sealed class S7Driver
    {
        ArgumentNullException.ThrowIfNull(builder);
        var folder = builder.Folder("S7", "S7");
-        foreach (var t in _options.Tags)
+        foreach (var t in _tagsByRawPath.Values)
        {
            // A tag carrying a non-null array count (>= 1) surfaces as a 1-D OPC UA array node.
            // A null count stays scalar. A count of 1 IS a valid 1-element array: the foundation
@@ -1,5 +1,6 @@
 using System.Text.Json;
 using System.Text.Json.Serialization;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 using ZB.MOM.WW.OtOpcUa.Core.Hosting;

 namespace ZB.MOM.WW.OtOpcUa.Driver.S7;
@@ -64,9 +65,10 @@ public static class S7DriverFactoryExtensions
            Rack = dto.Rack ?? 0,
            Slot = dto.Slot ?? 0,
            Timeout = TimeSpan.FromMilliseconds(dto.TimeoutMs ?? 5_000),
-            Tags = dto.Tags is { Count: > 0 }
-                ? [.. dto.Tags.Select(t => BuildTag(t, driverInstanceId))]
-                : [],
+            // v3: the deploy artifact (Wave C) populates rawTags with the cluster's authored raw S7
+            // tags. The driver maps each RawTagEntry's TagConfig blob through S7TagDefinitionFactory
+            // at Initialize; the legacy pre-declared DTO tag path (Name/Address → BuildTag) is retired.
+            RawTags = dto.RawTags is { Count: > 0 } ? [.. dto.RawTags] : [],
            Probe = new S7ProbeOptions
            {
                Enabled = dto.Probe?.Enabled ?? true,
@@ -77,18 +79,6 @@ public static class S7DriverFactoryExtensions
        };
    }

-    private static S7TagDefinition BuildTag(S7TagDto t, string driverInstanceId) =>
-        new(
-            Name: t.Name ?? throw new InvalidOperationException(
-                $"S7 config for '{driverInstanceId}' has a tag missing Name"),
-            Address: t.Address ?? throw new InvalidOperationException(
-                $"S7 tag '{t.Name}' in '{driverInstanceId}' missing Address"),
-            DataType: ParseEnum<S7DataType>(t.DataType, driverInstanceId, "DataType",
-                tagName: t.Name),
-            Writable: t.Writable ?? true,
-            StringLength: t.StringLength ?? 254,
-            WriteIdempotent: t.WriteIdempotent ?? false);
-
    private static T ParseEnum<T>(string? raw, string driverInstanceId, string field,
        string? tagName = null, T? fallback = null) where T : struct, Enum
    {
@@ -127,29 +117,13 @@ public static class S7DriverFactoryExtensions
        public short? Slot { get; init; }
        /// <summary>Gets the connection timeout in milliseconds.</summary>
        public int? TimeoutMs { get; init; }
-        /// <summary>Gets the list of tag definitions.</summary>
-        public List<S7TagDto>? Tags { get; init; }
+        /// <summary>Gets the authored raw tags (RawPath + TagConfig blob + WriteIdempotent) the deploy
+        /// artifact delivers. The driver maps each through <see cref="S7TagDefinitionFactory"/> at Initialize.</summary>
+        public List<RawTagEntry>? RawTags { get; init; }
        /// <summary>Gets the probe configuration.</summary>
        public S7ProbeDto? Probe { get; init; }
    }

-    /// <summary>Data transfer object for S7 tag definition.</summary>
-    internal sealed class S7TagDto
-    {
-        /// <summary>Gets the tag name.</summary>
-        public string? Name { get; init; }
-        /// <summary>Gets the S7 address (e.g., DB1.DBD0).</summary>
-        public string? Address { get; init; }
-        /// <summary>Gets the data type name.</summary>
-        public string? DataType { get; init; }
-        /// <summary>Gets a value indicating whether the tag is writable.</summary>
-        public bool? Writable { get; init; }
-        /// <summary>Gets the string length for string types.</summary>
-        public int? StringLength { get; init; }
-        /// <summary>Gets a value indicating whether write is idempotent.</summary>
-        public bool? WriteIdempotent { get; init; }
-    }
-
    /// <summary>Data transfer object for S7 probe configuration.</summary>
    internal sealed class S7ProbeDto
    {