From 8730c6e30a64dc28881615c542e982d98f28f85a Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 29 May 2026 07:28:21 -0400 Subject: [PATCH 01/18] docs(dcl): design for MxGateway data connection (2nd protocol) Add design doc for a second data-connection protocol, MxGateway, alongside the OPC UA client. New IDataConnection adapter behind the existing DataConnectionFactory extension point; tag pipe (read/subscribe/write) plus Galaxy hierarchy browse, optional 2nd endpoint for failover. Generalizes the OPC-UA-named browse plumbing to protocol-agnostic browse via IBrowsableDataConnection. No entity/schema changes. --- ...-05-28-mxgateway-data-connection-design.md | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 docs/plans/2026-05-28-mxgateway-data-connection-design.md diff --git a/docs/plans/2026-05-28-mxgateway-data-connection-design.md b/docs/plans/2026-05-28-mxgateway-data-connection-design.md new file mode 100644 index 00000000..c5365ffe --- /dev/null +++ b/docs/plans/2026-05-28-mxgateway-data-connection-design.md @@ -0,0 +1,199 @@ +# MxGateway Data Connection — Design + +**Date:** 2026-05-28 +**Component:** Data Connection Layer (#4), with touches to Commons (#16), Central UI (#9), Host (#15) +**Status:** Approved — ready for implementation planning + +## Summary + +Add a second data-connection protocol, **MxGateway**, alongside the existing OPC UA +client. MxGateway connects to the MxAccess Gateway +(`https://gitea.dohertylan.com/dohertj2`, packages `ZB.MOM.WW.MxGateway.Client` + +`ZB.MOM.WW.MxGateway.Contracts`) over gRPC and exposes an AVEVA/Wonderware +MXAccess-backed Galaxy as a clean tag-value pipe, identical in role to the OPC UA +adapter. + +The Data Connection Layer was built for exactly this: `DataConnectionFactory` +exposes `RegisterAdapter(protocolType, factory)` and every surrounding mechanism +(the `DataConnectionActor` Become/Stash state machine, primary/backup failover, +health reporting, re-subscribe-on-reconnect) is protocol-agnostic. The new +protocol is a single `IDataConnection` adapter plus one registration line — no +changes to the actor, the entity schema, or the failover machinery. + +## Scope + +**In scope (this slice):** +- Read / Subscribe / Write — MxGateway as a clean tag-value pipe. +- Galaxy hierarchy browse for the instance-config tag picker. +- Optional second endpoint for failover (reusing the existing primary/backup model). + +**Out of scope (possible later slices):** +- Native MXAccess alarms (`QueryActiveAlarms` / `StreamAlarms` / `AcknowledgeAlarm`). + ScadaBridge evaluates its own alarms via Alarm Actors from tag values; native + alarms are a new concept. +- Secured writes (`WriteSecured`, operator + verifier userId). Plain writes carry a + configurable `WriteUserId` only. + +## Decisions + +| Decision | Choice | +|---|---| +| Approach | New `IDataConnection` adapter behind the existing factory extension point (not a shared base class, not a separate subsystem). | +| Protocol string | `"MxGateway"` (matches the NuGet package family). | +| Browse plumbing | **Generalized** to protocol-agnostic browse driven by `IBrowsableDataConnection`; OPC UA and MxGateway share one path. | +| Write user context | Optional `WriteUserId` config field, default `0`. No script API change. | +| Endpoint redundancy | Reuse existing primary/backup failover; backup = a second gateway endpoint. | +| ApiKey secret handling | Match whatever OPC UA `UserIdentityConfig` username/password does today. | + +## Section 1 — Adapter & client lifecycle mapping + +New project-internal `MxGatewayDataConnection : IDataConnection, IBrowsableDataConnection` +in `ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/`, wrapping an injected +`IMxGatewayClientFactory` (mirrors the `IOpcUaClientFactory` seam so it is +unit-testable with a fake). + +| `IDataConnection` | MxGateway client | +|---|---| +| `ConnectAsync(details)` | `MxGatewayClient.Create(Endpoint, ApiKey, TLS)` → `OpenSessionAsync` → `RegisterAsync(clientName)` (store `serverHandle`); start background `StreamEventsAsync` consumer loop | +| `SubscribeAsync(tagPath, cb)` | `AddItemAsync` → `AdviseAsync` (or `SubscribeBulkAsync`); map `itemHandle ↔ tagPath ↔ callback`; return subscriptionId | +| `UnsubscribeAsync(id)` | `UnAdviseAsync` + `RemoveItemAsync` | +| `ReadAsync` / `ReadBatchAsync` | `ReadBulkAsync` (uses cached advised value when present) | +| `WriteAsync` / `WriteBatchAsync` | `WriteBulkAsync` with `WriteUserId`; value via `ToMxValue()` | +| `WriteBatchAndWaitAsync` | generic compose: write values → write flag → poll `responsePath` (advised value or `ReadBulk`) until match/timeout | +| `Status` | `ConnectionHealth` tracked across session state | +| `Disconnected` | fired once (Interlocked guard) when `StreamEventsAsync` faults or the channel breaks | + +**Value/quality mapping.** Each `OnDataChange` `MxEvent` carries `item_handle`, +`value` (`MxValue` → `ToClrValue()`), `quality` (OPC-style int), `source_timestamp`, +`statuses`, and `worker_sequence`. Dispatched to the matching tag's +`SubscriptionCallback` as `TagValue(ToClrValue(value), mapQuality(quality, statuses), +source_timestamp)`. Quality: `quality >= 192` → `Good`; bad-category status → `Bad`; +otherwise `Uncertain`. The loop tracks `worker_sequence` and resumes with +`afterWorkerSequence` on reconnect so no change is missed. + +**Reconnection needs no new logic.** The existing `DataConnectionActor` catches +`Disconnected`, pushes bad quality to all subscribed tags, disposes the adapter, and +on retry calls `ConnectAsync` on a fresh adapter then re-subscribes all tags — +identical to OPC UA. + +## Section 2 — Configuration, secrets & endpoint redundancy + +New `MxGatewayEndpointConfig` in Commons (alongside `OpcUaEndpointConfig`) with a +matching `MxGatewayEndpointConfigSerializer` (flat-dict ⇄ JSON) and +`MxGatewayEndpointConfigValidator`. Stored exactly like OPC UA: per-connection JSON +in `DataConnection.PrimaryConfiguration` / `BackupConfiguration`. **Primary/backup +failover works for free** — backup = a second gateway endpoint, round-robin, no +auto-failback, driven by the existing `FailoverRetryCount` state machine. No entity +or migration changes. + +| Key | Type | Default | Notes | +|---|---|---|---| +| `Endpoint` | string | `http://localhost:5000` | Gateway base URL | +| `ApiKey` | string | — | Sent as `authorization: Bearer ` | +| `ClientName` | string | `scadabridge-` | Registration name | +| `WriteUserId` | int | `0` | Applied to every write-back | +| `UseTls` / `CaFile` / `ServerName` | bool/string/string | `false` / — / — | TLS to a secured gateway | +| `ReadTimeoutMs` | int | `5000` | `ReadBulk` per-call timeout | + +**Secrets.** `ApiKey` follows whatever OPC UA `UserIdentityConfig` username/password +does today (same at-rest treatment, same log/telemetry redaction). Match that pattern +exactly; if OPC UA stores credentials in plaintext, `ApiKey` inherits the same known +limitation (not a new regression) — flag during implementation. + +**Shared settings** (`ReconnectInterval`, `TagResolutionRetryInterval`, +`WriteTimeout`) stay in `DataConnectionOptions`, unchanged, applying to all protocols. + +## Section 3 — Protocol-agnostic browse (tag picker) + +`IBrowsableDataConnection` is already protocol-neutral (node ids are opaque strings). +Generalize the OPC-UA-named plumbing so both protocols flow through one path. + +**Renames (site + central + UI):** + +| Today | Becomes | +|---|---| +| `BrowseOpcUaNodeCommand` / `BrowseOpcUaNodeResult` | `BrowseNodeCommand` / `BrowseNodeResult` | +| `OpcUaBrowseService` / `IOpcUaBrowseService` | `BrowseService` / `IBrowseService` | +| `OpcUaBrowserDialog.razor` | `NodeBrowserDialog.razor` | +| `BrowseFailure` / `BrowseFailureKind` | kept (already generic) | + +`DataConnectionManagerActor` resolves the connection, checks +`adapter is IBrowsableDataConnection`, and calls `BrowseChildrenAsync(parentNodeId)` +regardless of protocol (already the OPC UA logic — just drop the "OpcUa" from names). +Adapters without the interface return a "browse not supported" failure (unchanged). + +**MxGateway side.** `MxGatewayDataConnection.BrowseChildrenAsync` wraps +`GalaxyRepositoryClient.BrowseChildrenAsync` (one Galaxy level per call). Mapping: +- Galaxy object → `BrowseNode(NodeId = gobjectId-or-contained-path, + DisplayName = tagName, NodeClass = Object, HasChildren = child_has_children[i])`. +- Each object's attributes → `BrowseNode(NodeId = FullTagReference, + NodeClass = Variable, HasChildren = false)` — Variable rows are the selectable tag + paths stored in instance config. + +`GalaxyRepositoryClient` is a separate gRPC client from `MxGatewayClient`, so the +adapter holds both (same Endpoint + ApiKey): browse uses the read-only repository +client, the hot path uses the gateway client. The tag-picker dialog opens identically +for either protocol; only the tree shape and opaque node-id strings differ. + +## Section 4 — Packaging, DI registration & error classification + +**NuGet feed.** Add a repo-root `nuget.config` declaring the Gitea feed +(`https://gitea.dohertylan.com/api/packages/dohertj2/nuget/index.json`) alongside +nuget.org. Credentials are **not** committed — from the developer's `~/.nuget`, or +for the Docker image build a build-arg/secret-mounted credential (wire into +`docker/deploy.sh`). The DCL project references `ZB.MOM.WW.MxGateway.Client` +(`…Contracts` transitively); both target net10.0. + +**DI registration** in `DataConnectionFactory`: +```csharp +RegisterAdapter("MxGateway", details => new MxGatewayDataConnection( + new MxGatewayClientFactory(_loggerFactory), + _loggerFactory.CreateLogger())); +``` +plus an `MxGatewayGlobalOptions` (parallel to `OpcUaGlobalOptions`) bound in Host. +OPC UA registration untouched. + +**Error classification** (drives bad-quality push vs. synchronous script error): +- *Connection/transport faults* (`MxGatewaySessionException`, gRPC unavailable, stream + break) → `Disconnected` → reconnect + bad quality. Transient. +- *Per-item read/write failures* (`BulkReadResult` / `BulkWriteResult` with + `WasSuccessful = false`: bad tag, MXAccess rejection) → returned to caller (write) or + bad quality (read). Not a disconnect. +- *Auth failures* (`MxGatewayAuthenticationException` / `…AuthorizationException`) → + treated like a failed connect (logged, retried on failover/reconnect cadence); a + rotated key is operationally a connection problem, not per-tag. + +Matches OPC UA's "operations fail immediately to the caller; connection loss triggers +reconnect" split. + +## Section 5 — Testing, docs & deploy + +**Testing** (fake client seam, no live gateway, following the OPC UA adapter style): +- `MxGatewayDataConnection` against a `FakeMxGatewayClient`: connect→register→advise + lifecycle; `OnDataChange` → `TagValue` dispatch incl. quality mapping; read/write/batch + success + per-item failure; `WriteBatchAndWait` match & timeout; `Disconnected` fires + once on stream fault; `worker_sequence` resume on reconnect. +- `MxGatewayEndpointConfigSerializer` / `Validator` round-trip + defaults + + invalid-numeric fallback. +- Browse mapping (object→Object, attribute→Variable, `HasChildren` hint) against a fake + repository client. +- Generalized-browse regression: existing OPC UA browse tests updated to renamed + `BrowseNodeCommand` / `BrowseService` and still passing. + +**Docs (spec travels with code):** +- `Component-DataConnectionLayer.md`: add MxGateway under "Supported Protocols", an + "MxGateway Settings" config table, note `IBrowsableDataConnection` now backs both + protocols. +- `README.md` protocol mentions if any. +- This design doc. + +**Deploy.** `bash docker/deploy.sh` rebuilds the image; only deploy-config change is +NuGet credential wiring for restore. Sites get the adapter automatically (compiled into +Host). No new ports/services — the adapter is an outbound gRPC client to the gateway. + +**Affected components:** DCL (adapter, factory, options), Commons (config type, +serializer, validator, renamed browse messages + `IBrowsableDataConnection` +consumers), Configuration Database (none — no schema change), Central UI (renamed +browse service/dialog, protocol selector + `MxGatewayEndpointEditor` in +`DataConnectionForm` — net-new UI, use `frontend-design` skill), Host (options +binding), tests, docs, `nuget.config`. From 2044023bdda922ef1e124ea4a6bbae06632dc9d2 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 29 May 2026 07:39:44 -0400 Subject: [PATCH 02/18] docs(dcl): implementation plan for MxGateway data connection 19 bite-sized tasks across adapter (TDD), config serializer/validator, browse generalization rename, Central UI protocol selector/editor, packaging, and integration. Co-located task persistence for resumable execution. --- .../2026-05-28-mxgateway-data-connection.md | 956 ++++++++++++++++++ ...28-mxgateway-data-connection.md.tasks.json | 25 + 2 files changed, 981 insertions(+) create mode 100644 docs/plans/2026-05-28-mxgateway-data-connection.md create mode 100644 docs/plans/2026-05-28-mxgateway-data-connection.md.tasks.json diff --git a/docs/plans/2026-05-28-mxgateway-data-connection.md b/docs/plans/2026-05-28-mxgateway-data-connection.md new file mode 100644 index 00000000..3fe83691 --- /dev/null +++ b/docs/plans/2026-05-28-mxgateway-data-connection.md @@ -0,0 +1,956 @@ +# MxGateway Data Connection Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task. + +**Goal:** Add a second data-connection protocol, **MxGateway**, alongside OPC UA — a clean tag-value pipe (read/subscribe/write) plus Galaxy hierarchy browse, with optional second-endpoint failover. + +**Architecture:** A new `MxGatewayDataConnection : IDataConnection, IBrowsableDataConnection` adapter registered behind the existing `DataConnectionFactory` extension point. The adapter talks to the MxAccess Gateway through an `IMxGatewayClient` seam (testable with a fake; the real impl wraps the `ZB.MOM.WW.MxGateway.Client` NuGet package and `GalaxyRepositoryClient`). The OPC-UA-named browse plumbing is renamed to protocol-agnostic names so both protocols share one tag-picker path. No entity/schema changes — primary/backup failover already lives on the `DataConnection` entity. + +**Tech Stack:** .NET 10, Akka.NET (Become/Stash actors), gRPC (`ZB.MOM.WW.MxGateway.Client` + `…Contracts` from the Gitea feed), Blazor Server + Bootstrap, xUnit + FluentAssertions, central NuGet package management. + +**Design doc:** `docs/plans/2026-05-28-mxgateway-data-connection-design.md` + +**Reference skills:** Use @superpowers-extended-cc:test-driven-development for every adapter/serializer task. Use @frontend-design for the two `.razor` UI tasks. + +--- + +## Key facts the implementer needs + +- **Extension point:** `DataConnectionFactory` (`src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/DataConnectionFactory.cs`) registers protocols via `RegisterAdapter("OpcUa", details => …)` in its constructor. Add one line for `"MxGateway"`. +- **Config flow:** stored config JSON → `DeploymentManagerActor.FlattenConnectionConfig(protocol, json)` (`src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/DeploymentManagerActor.cs:759`) → `IDictionary` → `DataConnectionActor` → `adapter.ConnectAsync(details)`. The actor never knows the protocol's config shape; the dict is the contract. `FlattenConnectionConfig` currently branches on `"OpcUa"` and falls back to a generic flat-dict parse for unknown protocols — add an `"MxGateway"` arm. +- **`IDataConnection` contract:** `src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Protocol/IDataConnection.cs`. Methods: `ConnectAsync`, `DisconnectAsync`, `SubscribeAsync(tagPath, SubscriptionCallback, ct)→string`, `UnsubscribeAsync(id)`, `ReadAsync→ReadResult`, `ReadBatchAsync→IReadOnlyDictionary`, `WriteAsync→WriteResult`, `WriteBatchAsync`, `WriteBatchAndWaitAsync→bool`, `Status` (`ConnectionHealth`), `event Action? Disconnected`. Value type: `TagValue(object? Value, QualityCode Quality, DateTimeOffset Timestamp)`; `QualityCode { Good, Bad, Uncertain }`. +- **`IBrowsableDataConnection`:** `src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Protocol/IBrowsableDataConnection.cs` — `BrowseChildrenAsync(string? parentNodeId, ct)→BrowseChildrenResult(IReadOnlyList, bool Truncated)`. `BrowseNode(string NodeId, string DisplayName, BrowseNodeClass NodeClass, bool HasChildren)`; `BrowseNodeClass { Object, Variable, Method, Other }`. Throw `ConnectionNotConnectedException` when no live session. **These record/interface names do NOT change in the rename** — only the OPC-UA-named *command/service/dialog* layer does. +- **OPC UA adapter to mirror:** `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/OpcUaDataConnection.cs`. Note the `_disconnectFired` `Interlocked.Exchange` once-only guard pattern — replicate it. +- **MxGateway client API** (in `~/Desktop/MxAccessGateway/clients/dotnet`): `MxGatewayClient.Create(MxGatewayClientOptions)` → `OpenSessionAsync()→MxGatewaySession`. Session: `RegisterAsync(clientName)→int serverHandle`; `AddItemAsync(serverHandle, itemDef)→int itemHandle`; `AdviseAsync(serverHandle, itemHandle)`; `UnAdviseAsync`/`RemoveItemAsync`; `SubscribeBulkAsync`/`UnsubscribeBulkAsync`; `ReadBulkAsync(serverHandle, tagAddresses, timeout)→IReadOnlyList`; `WriteBulkAsync(serverHandle, IReadOnlyList)→IReadOnlyList`; `StreamEventsAsync(afterWorkerSequence)→IAsyncEnumerable`. Browse: `GalaxyRepositoryClient.Create(options)` → `BrowseChildrenRawAsync(BrowseChildrenRequest)→BrowseChildrenReply`. Value helpers: `MxValueExtensions.ToMxValue(...)`, `.ToClrValue()`; `MxStatusProxyExtensions.IsSuccess()`. +- **`MxEvent`** fields: `family` (`MxEventFamily`), `item_handle`, `value` (`MxValue`), `quality` (int, OPC-style; ≥192 = good), `source_timestamp` (`google.protobuf.Timestamp`), `worker_sequence` (uint64), `body` oneof incl. `on_data_change`. `MxEventFamily.MX_EVENT_FAMILY_ON_DATA_CHANGE = 1`. +- **`BulkReadResult`:** `tag_address`, `item_handle`, `was_successful`, `was_cached`, `value` (`MxValue`), `quality` (int), `source_timestamp`, `statuses`, `error_message`. **`BulkWriteResult`:** `item_handle`, `was_successful`, `hresult?`, `statuses`, `error_message`. +- **`BrowseChildrenReply`:** `children` (`repeated GalaxyObject`), `next_page_token`, `total_child_count`, `child_has_children` (`repeated bool`). **`GalaxyObject`:** `gobject_id`, `tag_name`, `contained_name`, `parent_gobject_id`, `is_area`, `attributes` (`repeated GalaxyAttribute`). **`GalaxyAttribute`:** `attribute_name`, `full_tag_reference`, `data_type_name`, `is_array`, `is_historized`, `is_alarm`. **`BrowseChildrenRequest`** parent oneof: `parent_gobject_id` | `parent_tag_name` | `parent_contained_path`; plus `page_size`, `include_attributes`. +- **Exceptions:** `MxGatewaySessionException`, `MxGatewayAuthenticationException`, `MxGatewayAuthorizationException`, `MxGatewayWorkerException`, `MxGatewayCommandException`, `MxAccessException` — all derive from `MxGatewayException`. +- **Central package management:** versions go in `Directory.Packages.props` (``); projects reference `` with no version. + +--- + +## Task 1: Packaging foundation — Gitea feed + package refs + +**Classification:** small +**Estimated implement time:** ~4 min +**Parallelizable with:** Task 13 (rename track) + +**Files:** +- Create: `nuget.config` (repo root) +- Modify: `Directory.Packages.props` +- Modify: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/ZB.MOM.WW.ScadaBridge.DataConnectionLayer.csproj` + +**Step 1: Create `nuget.config` at repo root** + +```xml + + + + + + + + + +``` + +**Step 2: Add package versions to `Directory.Packages.props`** (under the existing ``; check the published version with `dotnet package search ZB.MOM.WW.MxGateway.Client --source dohertj2-gitea` — README references `0.1.0`, use the latest available): + +```xml + + +``` + +**Step 3: Add the PackageReference to the DCL csproj** (in the first ``, after the OPC UA reference): + +```xml + +``` +(`…Contracts` comes in transitively.) + +**Step 4: Restore and verify** + +Run: `dotnet restore ZB.MOM.WW.ScadaBridge.slnx` +Expected: restore succeeds, the MxGateway packages resolve from the Gitea feed. If it fails with 401, the developer must add feed credentials (see the comment in `nuget.config`) — surface that, don't hardcode a token. + +**Step 5: Commit** + +```bash +git add nuget.config Directory.Packages.props src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/ZB.MOM.WW.ScadaBridge.DataConnectionLayer.csproj +git commit -m "build(dcl): add Gitea feed + ZB.MOM.WW.MxGateway.Client package reference" +``` + +--- + +## Task 2: MxGatewayEndpointConfig type + +**Classification:** small +**Estimated implement time:** ~3 min +**Parallelizable with:** Task 13, Task 14 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Types/DataConnections/MxGatewayEndpointConfig.cs` + +**Step 1: Write the type** (mirrors `OpcUaEndpointConfig` — a mutable POCO with defaults; fields per the design's config table): + +```csharp +namespace ZB.MOM.WW.ScadaBridge.Commons.Types.DataConnections; + +/// +/// Per-endpoint configuration for an MxGateway data connection. Serialized to the +/// typed JSON shape stored in DataConnection.PrimaryConfiguration / +/// BackupConfiguration. Both primary and backup use this same shape — the +/// backup is simply a second gateway endpoint for failover. +/// +public class MxGatewayEndpointConfig +{ + /// Gateway base URL (e.g. "http://localhost:5000"). + public string Endpoint { get; set; } = "http://localhost:5000"; + /// API key sent to the gateway as authorization: Bearer <key>. + public string ApiKey { get; set; } = ""; + /// MXAccess client registration name. Blank → derive "scadabridge-<connName>" at connect time. + public string ClientName { get; set; } = ""; + /// MXAccess user id applied to every write-back. 0 = no user context. + public int WriteUserId { get; set; } + /// Use TLS to a secured gateway. + public bool UseTls { get; set; } + /// Path to the CA certificate (TLS only). + public string CaFile { get; set; } = ""; + /// TLS server-name override. + public string ServerName { get; set; } = ""; + /// ReadBulk per-call timeout in milliseconds. + public int ReadTimeoutMs { get; set; } = 5000; +} +``` + +**Step 2: Build the Commons project** + +Run: `dotnet build src/ZB.MOM.WW.ScadaBridge.Commons/ZB.MOM.WW.ScadaBridge.Commons.csproj` +Expected: PASS. + +**Step 3: Commit** + +```bash +git add src/ZB.MOM.WW.ScadaBridge.Commons/Types/DataConnections/MxGatewayEndpointConfig.cs +git commit -m "feat(commons): add MxGatewayEndpointConfig type" +``` + +--- + +## Task 3: MxGatewayEndpointConfigSerializer + tests + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** Task 4, Task 13, Task 14 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Serialization/MxGatewayEndpointConfigSerializer.cs` +- Test: `tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Serialization/MxGatewayEndpointConfigSerializerTests.cs` + +This is simpler than the OPC UA serializer — MxGateway is net-new, so there is **no legacy flat-dict shape** to fall back to. Provide `Serialize`, `Deserialize` (typed-or-default), `ToFlatDict`, `FromFlatDict`. (Locate the existing OPC UA serializer tests under `tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Serialization/` and mirror their style.) + +**Step 1: Write the failing test** + +```csharp +using FluentAssertions; +using ZB.MOM.WW.ScadaBridge.Commons.Serialization; +using ZB.MOM.WW.ScadaBridge.Commons.Types.DataConnections; +using Xunit; + +namespace ZB.MOM.WW.ScadaBridge.Commons.Tests.Serialization; + +public class MxGatewayEndpointConfigSerializerTests +{ + [Fact] + public void Serialize_then_Deserialize_round_trips_all_fields() + { + var cfg = new MxGatewayEndpointConfig + { + Endpoint = "https://gw:5001", ApiKey = "k", ClientName = "c", + WriteUserId = 7, UseTls = true, CaFile = "/ca.pem", + ServerName = "gw.local", ReadTimeoutMs = 1234 + }; + var json = MxGatewayEndpointConfigSerializer.Serialize(cfg); + var back = MxGatewayEndpointConfigSerializer.Deserialize(json); + back.Should().BeEquivalentTo(cfg); + } + + [Fact] + public void Deserialize_null_or_blank_returns_default() + => MxGatewayEndpointConfigSerializer.Deserialize(null).Endpoint + .Should().Be(new MxGatewayEndpointConfig().Endpoint); + + [Fact] + public void ToFlatDict_FromFlatDict_round_trips() + { + var cfg = new MxGatewayEndpointConfig { Endpoint = "http://x", ApiKey = "k", WriteUserId = 3, ReadTimeoutMs = 999 }; + var dict = MxGatewayEndpointConfigSerializer.ToFlatDict(cfg); + var back = MxGatewayEndpointConfigSerializer.FromFlatDict(dict); + back.Should().BeEquivalentTo(cfg); + } + + [Fact] + public void FromFlatDict_invalid_numeric_falls_back_to_default() + { + var back = MxGatewayEndpointConfigSerializer.FromFlatDict( + new Dictionary { ["ReadTimeoutMs"] = "not-a-number" }); + back.ReadTimeoutMs.Should().Be(new MxGatewayEndpointConfig().ReadTimeoutMs); + } +} +``` + +**Step 2: Run to verify it fails** + +Run: `dotnet test tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/ --filter MxGatewayEndpointConfigSerializerTests` +Expected: FAIL (type does not exist). + +**Step 3: Write the serializer** + +```csharp +using System.Globalization; +using System.Text.Json; +using ZB.MOM.WW.ScadaBridge.Commons.Types.DataConnections; + +namespace ZB.MOM.WW.ScadaBridge.Commons.Serialization; + +/// +/// Serializes to/from the typed JSON stored in +/// DataConnection.PrimaryConfiguration / BackupConfiguration, and flattens +/// it to the IDictionary<string,string> shape IDataConnection.ConnectAsync +/// expects. MxGateway is net-new, so there is no legacy shape to recover. +/// +public static class MxGatewayEndpointConfigSerializer +{ + private static readonly JsonSerializerOptions JsonOpts = new() + { + PropertyNamingPolicy = JsonNamingPolicy.CamelCase, + WriteIndented = false, + }; + + public static string Serialize(MxGatewayEndpointConfig config) + => JsonSerializer.Serialize(config, JsonOpts); + + public static MxGatewayEndpointConfig Deserialize(string? json) + { + if (string.IsNullOrWhiteSpace(json)) return new MxGatewayEndpointConfig(); + try { return JsonSerializer.Deserialize(json, JsonOpts) ?? new MxGatewayEndpointConfig(); } + catch (JsonException) { return new MxGatewayEndpointConfig(); } + } + + public static IDictionary ToFlatDict(MxGatewayEndpointConfig c) => new Dictionary + { + ["Endpoint"] = c.Endpoint, + ["ApiKey"] = c.ApiKey, + ["ClientName"] = c.ClientName, + ["WriteUserId"] = c.WriteUserId.ToString(CultureInfo.InvariantCulture), + ["UseTls"] = c.UseTls.ToString(), + ["CaFile"] = c.CaFile, + ["ServerName"] = c.ServerName, + ["ReadTimeoutMs"] = c.ReadTimeoutMs.ToString(CultureInfo.InvariantCulture), + }; + + public static MxGatewayEndpointConfig FromFlatDict(IDictionary d) + { + var c = new MxGatewayEndpointConfig(); + if (d.TryGetValue("Endpoint", out var ep) && !string.IsNullOrWhiteSpace(ep)) c.Endpoint = ep; + if (d.TryGetValue("ApiKey", out var ak)) c.ApiKey = ak; + if (d.TryGetValue("ClientName", out var cn)) c.ClientName = cn; + if (d.TryGetValue("WriteUserId", out var wu) && int.TryParse(wu, out var wuv)) c.WriteUserId = wuv; + if (d.TryGetValue("UseTls", out var tls) && bool.TryParse(tls, out var tlsv)) c.UseTls = tlsv; + if (d.TryGetValue("CaFile", out var ca)) c.CaFile = ca; + if (d.TryGetValue("ServerName", out var sn)) c.ServerName = sn; + if (d.TryGetValue("ReadTimeoutMs", out var rt) && int.TryParse(rt, out var rtv)) c.ReadTimeoutMs = rtv; + return c; + } +} +``` + +**Step 4: Run tests to verify they pass** + +Run: `dotnet test tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/ --filter MxGatewayEndpointConfigSerializerTests` +Expected: PASS (4 tests). + +**Step 5: Commit** + +```bash +git add src/ZB.MOM.WW.ScadaBridge.Commons/Serialization/MxGatewayEndpointConfigSerializer.cs tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Serialization/MxGatewayEndpointConfigSerializerTests.cs +git commit -m "feat(commons): MxGatewayEndpointConfig serializer + tests" +``` + +--- + +## Task 4: MxGatewayEndpointConfigValidator + tests + +**Classification:** small +**Estimated implement time:** ~3 min +**Parallelizable with:** Task 3, Task 13, Task 14 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Validators/MxGatewayEndpointConfigValidator.cs` +- Test: `tests/ZB.MOM.WW.ScadaBridge.Commons.Tests/Validators/MxGatewayEndpointConfigValidatorTests.cs` + +Mirror `OpcUaEndpointConfigValidator` (returns a list of error strings, prefixed). Rules: `Endpoint` required + must be an absolute `http(s)` URI; `ApiKey` required; `ReadTimeoutMs > 0`; if `UseTls` and `CaFile` set, `CaFile` must be non-blank (warn only if blank — TLS can use system roots). Read the existing validator first to match the exact signature (likely `static IReadOnlyList Validate(MxGatewayEndpointConfig cfg, string prefix)`). + +**Step 1:** Write failing tests (valid config → no errors; blank Endpoint → error; blank ApiKey → error; ReadTimeoutMs 0 → error). **Step 2:** Run, verify FAIL. **Step 3:** Implement. **Step 4:** Run, verify PASS. **Step 5:** Commit `feat(commons): MxGatewayEndpointConfig validator + tests`. + +--- + +## Task 5: Client seam interfaces + MxGatewayGlobalOptions + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** Task 13, Task 14 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/IMxGatewayClient.cs` +- Create: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/MxGatewayGlobalOptions.cs` + +The seam uses **neutral DTOs** (no generated protobuf types) so the adapter and its tests never touch the NuGet package — the real impl (Task 11) translates. This is the same pattern as `IOpcUaClient`. + +**Step 1: Write `IMxGatewayClient.cs`** + +```csharp +using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Protocol; + +namespace ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Adapters; + +/// Connection parameters resolved from the flat config dict. +public record MxGatewayConnectionOptions( + string Endpoint, string ApiKey, string ClientName, int WriteUserId, + bool UseTls, string? CaFile, string? ServerName, int ReadTimeoutMs); + +/// One advised-tag value change pushed from the gateway event stream. +public record MxValueUpdate(string TagPath, object? Value, QualityCode Quality, DateTimeOffset Timestamp); + +/// Per-tag read outcome. +public record MxReadOutcome(string TagPath, bool Success, object? Value, QualityCode Quality, DateTimeOffset Timestamp, string? Error); + +/// Per-tag write outcome. +public record MxWriteOutcome(string TagPath, bool Success, string? Error); + +/// One node in a Galaxy browse level. +public record MxBrowseChild(string NodeId, string DisplayName, BrowseNodeClass NodeClass, bool HasChildren); + +/// +/// Seam over the MxAccess Gateway .NET client + Galaxy repository client. Decouples +/// from the generated gRPC/protobuf types so the +/// adapter is unit-testable with a fake. The real implementation lives in +/// RealMxGatewayClient (Task 11). +/// +public interface IMxGatewayClient : IAsyncDisposable +{ + /// Opens the gateway session and registers the client (Register → serverHandle held internally). + Task ConnectAsync(MxGatewayConnectionOptions options, CancellationToken ct = default); + + /// Closes the session. + Task DisconnectAsync(CancellationToken ct = default); + + /// AddItem + Advise; returns the gateway item handle (as a string subscription id). + Task SubscribeAsync(string tagPath, CancellationToken ct = default); + + /// UnAdvise + RemoveItem for a previously returned subscription id. + Task UnsubscribeAsync(string subscriptionId, CancellationToken ct = default); + + /// Snapshot read of one or more tags (ReadBulk). + Task> ReadAsync(IReadOnlyList tagPaths, CancellationToken ct = default); + + /// Write one or more tag/value pairs (WriteBulk with the configured WriteUserId). + Task> WriteAsync(IReadOnlyList<(string TagPath, object? Value)> writes, CancellationToken ct = default); + + /// One Galaxy browse level (BrowseChildren). parentNodeId null → root. + Task<(IReadOnlyList Children, bool Truncated)> BrowseChildrenAsync(string? parentNodeId, CancellationToken ct = default); + + /// + /// Long-running event consumer. Invokes for each advised-tag + /// data change. Resumes from the last delivered worker sequence on reconnect. Completes + /// (or throws) when the stream ends — the adapter treats that as a disconnect. + /// + Task RunEventLoopAsync(Action onUpdate, CancellationToken ct = default); +} + +/// Builds instances. +public interface IMxGatewayClientFactory +{ + IMxGatewayClient Create(); +} +``` + +**Step 2: Write `MxGatewayGlobalOptions.cs`** + +```csharp +namespace ZB.MOM.WW.ScadaBridge.DataConnectionLayer; + +/// +/// Deployment-wide MxGateway defaults, bound from the "MxGateway" section of +/// appsettings.json. Per-endpoint behavior lives on MxGatewayEndpointConfig. +/// +public class MxGatewayGlobalOptions +{ + /// Prefix used to derive a per-connection client registration name when the connection's ClientName is blank. + public string ClientNamePrefix { get; set; } = "scadabridge"; +} +``` + +**Step 3: Build the DCL project.** Run: `dotnet build src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/`. Expected: PASS. + +**Step 4: Commit** `feat(dcl): MxGateway client seam interfaces + global options`. + +--- + +## Task 6: Adapter — connect / disconnect / status / Disconnected + value mapping + +**Classification:** high-risk +**Estimated implement time:** ~5 min +**Parallelizable with:** Task 13, Task 14 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/MxGatewayDataConnection.cs` +- Create: `tests/ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Tests/Adapters/FakeMxGatewayClient.cs` +- Test: `tests/ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Tests/Adapters/MxGatewayDataConnectionTests.cs` + +> Locate the existing OPC UA adapter test project (the dir holding `OpcUaDataConnectionTests` / fake clients) and place these alongside it; adjust the namespace/paths above if the actual project name differs. + +**Step 1: Write `FakeMxGatewayClient`** — records calls; lets tests push `MxValueUpdate`s into the captured `onUpdate`, and complete/fault the event loop on demand: + +```csharp +using System.Collections.Concurrent; +using ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Adapters; + +namespace ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Tests.Adapters; + +public sealed class FakeMxGatewayClient : IMxGatewayClient, IMxGatewayClientFactory +{ + public MxGatewayConnectionOptions? ConnectedWith; + public readonly List Subscribed = new(); + public readonly TaskCompletionSource EventLoopGate = new(TaskCreationOptions.RunContinuationsAsynchronously); + public Action? OnUpdate; + public Func, IReadOnlyList>? ReadHandler; + public Func, IReadOnlyList>? WriteHandler; + public Func, bool)>? BrowseHandler; + private int _nextHandle; + + public IMxGatewayClient Create() => this; + public Task ConnectAsync(MxGatewayConnectionOptions o, CancellationToken ct = default) { ConnectedWith = o; return Task.CompletedTask; } + public Task DisconnectAsync(CancellationToken ct = default) => Task.CompletedTask; + public Task SubscribeAsync(string tag, CancellationToken ct = default) { Subscribed.Add(tag); return Task.FromResult((++_nextHandle).ToString()); } + public Task UnsubscribeAsync(string id, CancellationToken ct = default) { Subscribed.Remove(id); return Task.CompletedTask; } + public Task> ReadAsync(IReadOnlyList tags, CancellationToken ct = default) => Task.FromResult(ReadHandler!(tags)); + public Task> WriteAsync(IReadOnlyList<(string, object?)> w, CancellationToken ct = default) => Task.FromResult(WriteHandler!(w)); + public Task<(IReadOnlyList, bool)> BrowseChildrenAsync(string? p, CancellationToken ct = default) => Task.FromResult(BrowseHandler!(p)); + public async Task RunEventLoopAsync(Action onUpdate, CancellationToken ct = default) + { + OnUpdate = onUpdate; + using var reg = ct.Register(() => EventLoopGate.TrySetResult()); + await EventLoopGate.Task; // test completes this to end the loop… + ct.ThrowIfCancellationRequested(); // …or faults it to simulate a stream break + } + public ValueTask DisposeAsync() => ValueTask.CompletedTask; + public void FaultEventLoop() => EventLoopGate.TrySetException(new Exception("stream broke")); +} +``` + +**Step 2: Write failing tests** + +```csharp +[Fact] +public async Task ConnectAsync_resolves_options_and_sets_status_connected() { /* connect with a flat dict; assert fake.ConnectedWith.Endpoint + Status == Connected */ } + +[Fact] +public async Task Disconnected_fires_exactly_once_when_event_loop_faults() { /* hook event; FaultEventLoop(); assert raised once */ } +``` + +**Step 3: Implement the adapter core.** Class declaration + connect + the value-mapping helper: + +```csharp +using System.Collections.Concurrent; +using Microsoft.Extensions.Logging; +using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Protocol; +using ZB.MOM.WW.ScadaBridge.Commons.Serialization; +using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums; + +namespace ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Adapters; + +public class MxGatewayDataConnection : IDataConnection, IBrowsableDataConnection +{ + private readonly IMxGatewayClientFactory _clientFactory; + private readonly ILogger _logger; + private IMxGatewayClient? _client; + private ConnectionHealth _status = ConnectionHealth.Disconnected; + private CancellationTokenSource? _eventLoopCts; + // subscriptionId → (tagPath, callback) so the event loop can route updates by tag. + private readonly ConcurrentDictionary _subs = new(); + private readonly ConcurrentDictionary _tagToSub = new(); + private int _disconnectFired; // 0 = not fired, 1 = fired — Interlocked guard, mirrors OpcUaDataConnection. + + public MxGatewayDataConnection(IMxGatewayClientFactory clientFactory, ILogger logger) + { _clientFactory = clientFactory; _logger = logger; } + + public ConnectionHealth Status => _status; + public event Action? Disconnected; + + public async Task ConnectAsync(IDictionary connectionDetails, CancellationToken ct = default) + { + var cfg = MxGatewayEndpointConfigSerializer.FromFlatDict(connectionDetails); + Interlocked.Exchange(ref _disconnectFired, 0); // reset guard on (re)connect, like OPC UA + _client = _clientFactory.Create(); + await _client.ConnectAsync(new MxGatewayConnectionOptions( + cfg.Endpoint, cfg.ApiKey, + string.IsNullOrWhiteSpace(cfg.ClientName) ? "scadabridge" : cfg.ClientName, + cfg.WriteUserId, cfg.UseTls, + string.IsNullOrWhiteSpace(cfg.CaFile) ? null : cfg.CaFile, + string.IsNullOrWhiteSpace(cfg.ServerName) ? null : cfg.ServerName, + cfg.ReadTimeoutMs), ct); + _status = ConnectionHealth.Connected; + + // Background event loop: route each value change to the matching subscription callback. + _eventLoopCts = new CancellationTokenSource(); + _ = Task.Run(() => RunEventLoopAsync(_eventLoopCts.Token)); + } + + private async Task RunEventLoopAsync(CancellationToken ct) + { + try + { + await _client!.RunEventLoopAsync(update => + { + if (_tagToSub.TryGetValue(update.TagPath, out var subId) && _subs.TryGetValue(subId, out var s)) + s.Callback(update.TagPath, new TagValue(update.Value, update.Quality, update.Timestamp)); + }, ct); + } + catch (OperationCanceledException) { /* normal shutdown */ } + catch (Exception ex) + { + _logger.LogWarning(ex, "MxGateway event stream faulted; signalling disconnect"); + RaiseDisconnected(); + } + } + + private void RaiseDisconnected() + { + if (Interlocked.Exchange(ref _disconnectFired, 1) == 0) + { + _status = ConnectionHealth.Disconnected; + Disconnected?.Invoke(); + } + } + + public async Task DisconnectAsync(CancellationToken ct = default) + { + _eventLoopCts?.Cancel(); + if (_client is not null) await _client.DisconnectAsync(ct); + _status = ConnectionHealth.Disconnected; + } + + public async ValueTask DisposeAsync() + { + _eventLoopCts?.Cancel(); + if (_client is not null) await _client.DisposeAsync(); + } + + // SubscribeAsync / UnsubscribeAsync — Task 7 + // ReadAsync / ReadBatchAsync / WriteAsync / WriteBatchAsync — Task 8 + // WriteBatchAndWaitAsync — Task 9 + // BrowseChildrenAsync — Task 10 + // (Throw NotImplementedException stubs for now so the file compiles.) +} +``` + +Add `throw new NotImplementedException()` stubs for the not-yet-implemented interface members so the project builds. + +**Step 4: Run tests, verify PASS.** Run: `dotnet test tests/ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Tests/ --filter MxGatewayDataConnectionTests`. + +**Step 5: Commit** `feat(dcl): MxGatewayDataConnection connect/disconnect/Disconnected + value mapping`. + +--- + +## Task 7: Adapter — subscribe / unsubscribe + event routing + +**Classification:** high-risk +**Estimated implement time:** ~4 min +**Parallelizable with:** Task 13, Task 14 +**Depends on:** Task 6 + +**Files:** +- Modify: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/MxGatewayDataConnection.cs` +- Test: `tests/ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Tests/Adapters/MxGatewayDataConnectionTests.cs` + +**Step 1:** Test: after `SubscribeAsync("Area.Pump.Speed", cb)`, pushing an `MxValueUpdate` for that tag through the fake's `OnUpdate` invokes `cb` with the mapped `TagValue`; `UnsubscribeAsync` stops routing. + +**Step 2:** Run, verify FAIL (NotImplementedException). + +**Step 3:** Implement: + +```csharp +public async Task SubscribeAsync(string tagPath, SubscriptionCallback callback, CancellationToken ct = default) +{ + var subId = await _client!.SubscribeAsync(tagPath, ct); + _subs[subId] = (tagPath, callback); + _tagToSub[tagPath] = subId; + return subId; +} + +public async Task UnsubscribeAsync(string subscriptionId, CancellationToken ct = default) +{ + if (_subs.TryRemove(subscriptionId, out var s)) _tagToSub.TryRemove(s.TagPath, out _); + await _client!.UnsubscribeAsync(subscriptionId, ct); +} +``` + +**Step 4:** Run tests, verify PASS. **Step 5:** Commit `feat(dcl): MxGateway subscribe/unsubscribe + event routing`. + +--- + +## Task 8: Adapter — read / write + error classification + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** Task 13, Task 14 +**Depends on:** Task 6 + +**Files:** +- Modify: `MxGatewayDataConnection.cs` +- Test: `MxGatewayDataConnectionTests.cs` + +**Step 1:** Tests: `ReadAsync` maps a successful `MxReadOutcome` to `ReadResult(true, TagValue, null)` and a failed one to `ReadResult(false, null, error)`; `ReadBatchAsync` returns a dict keyed by tag; `WriteAsync` maps `MxWriteOutcome` success/failure to `WriteResult`; `WriteBatchAsync` returns a per-tag dict. + +**Step 2:** Run, verify FAIL. + +**Step 3:** Implement (single reads/writes delegate to the batch path): + +```csharp +public async Task ReadAsync(string tagPath, CancellationToken ct = default) +{ + var r = (await _client!.ReadAsync(new[] { tagPath }, ct)).Single(); + return r.Success + ? new ReadResult(true, new TagValue(r.Value, r.Quality, r.Timestamp), null) + : new ReadResult(false, null, r.Error); +} + +public async Task> ReadBatchAsync(IEnumerable tagPaths, CancellationToken ct = default) +{ + var list = tagPaths.ToList(); + var results = await _client!.ReadAsync(list, ct); + return results.ToDictionary(r => r.TagPath, r => r.Success + ? new ReadResult(true, new TagValue(r.Value, r.Quality, r.Timestamp), null) + : new ReadResult(false, null, r.Error)); +} + +public async Task WriteAsync(string tagPath, object? value, CancellationToken ct = default) +{ + var w = (await _client!.WriteAsync(new[] { (tagPath, value) }, ct)).Single(); + return new WriteResult(w.Success, w.Error); +} + +public async Task> WriteBatchAsync(IDictionary values, CancellationToken ct = default) +{ + var results = await _client!.WriteAsync(values.Select(kv => (kv.Key, kv.Value)).ToList(), ct); + return results.ToDictionary(w => w.TagPath, w => new WriteResult(w.Success, w.Error)); +} +``` + +Error-classification note for the implementer: per-tag failures (`Success == false`) are returned to the caller as shown — they must NOT raise `Disconnected`. Transport/session faults surface as exceptions from the seam (the real impl in Task 11 throws `MxGatewaySessionException`/gRPC errors), which the `DataConnectionActor` already catches and which the event loop turns into a `Disconnected`. Auth failures are handled at connect time (Task 11). + +**Step 4:** Run tests, verify PASS. **Step 5:** Commit `feat(dcl): MxGateway read/write batch + error classification`. + +--- + +## Task 9: Adapter — WriteBatchAndWaitAsync + +**Classification:** standard +**Estimated implement time:** ~4 min +**Parallelizable with:** Task 13, Task 14 +**Depends on:** Task 8 + +**Files:** +- Modify: `MxGatewayDataConnection.cs` +- Test: `MxGatewayDataConnectionTests.cs` + +**Step 1:** Tests: writes values+flag, then polls `responsePath`; returns `true` when the response value appears before timeout, `false` on timeout. Drive via the fake's `ReadHandler` (return the expected value after N polls / never). + +**Step 2:** Run, verify FAIL. + +**Step 3:** Implement generically (write the batch, write the flag, poll the response path until match or timeout): + +```csharp +public async Task WriteBatchAndWaitAsync( + IDictionary values, string flagPath, object? flagValue, + string responsePath, object? responseValue, TimeSpan timeout, CancellationToken ct = default) +{ + await WriteBatchAsync(values, ct); + await WriteAsync(flagPath, flagValue, ct); + + using var timeoutCts = CancellationTokenSource.CreateLinkedTokenSource(ct); + timeoutCts.CancelAfter(timeout); + try + { + while (!timeoutCts.IsCancellationRequested) + { + var r = await ReadAsync(responsePath, timeoutCts.Token); + if (r.Success && Equals(r.Value?.ToString(), responseValue?.ToString())) return true; + await Task.Delay(TimeSpan.FromMilliseconds(200), timeoutCts.Token); + } + } + catch (OperationCanceledException) when (!ct.IsCancellationRequested) { /* timeout */ } + return false; +} +``` + +(Value comparison uses string projection to tolerate numeric type differences across the gRPC boundary — match the OPC UA adapter's comparison approach if it differs; check `OpcUaDataConnection.WriteBatchAndWaitAsync`.) + +**Step 4:** Run tests, verify PASS. **Step 5:** Commit `feat(dcl): MxGateway WriteBatchAndWait`. + +--- + +## Task 10: Adapter — Galaxy browse (IBrowsableDataConnection) + +**Classification:** standard +**Estimated implement time:** ~4 min +**Parallelizable with:** Task 13, Task 14 +**Depends on:** Task 6 + +**Files:** +- Modify: `MxGatewayDataConnection.cs` +- Test: `MxGatewayDataConnectionTests.cs` + +**Step 1:** Tests: `BrowseChildrenAsync(null)` maps the fake's children to `BrowseChildrenResult` (object→`BrowseNodeClass.Object`, attribute→`Variable`, `HasChildren` preserved, `Truncated` flag passed through); when the seam reports not-connected, the adapter throws `ConnectionNotConnectedException`. + +**Step 2:** Run, verify FAIL. + +**Step 3:** Implement (the seam already returns neutral `MxBrowseChild`s; the Galaxy→node mapping itself lives in the real impl, Task 11): + +```csharp +public async Task BrowseChildrenAsync(string? parentNodeId, CancellationToken ct = default) +{ + if (_status != ConnectionHealth.Connected) + throw new ConnectionNotConnectedException($"MxGateway connection is not connected (status: {_status})."); + + var (children, truncated) = await _client!.BrowseChildrenAsync(parentNodeId, ct); + var nodes = children + .Select(c => new BrowseNode(c.NodeId, c.DisplayName, c.NodeClass, c.HasChildren)) + .ToList(); + return new BrowseChildrenResult(nodes, truncated); +} +``` + +**Step 4:** Run tests, verify PASS. **Step 5:** Commit `feat(dcl): MxGateway Galaxy browse via IBrowsableDataConnection`. + +--- + +## Task 11: RealMxGatewayClient — seam implementation over the NuGet client + +**Classification:** high-risk +**Estimated implement time:** ~5 min +**Parallelizable with:** Task 13, Task 14 +**Depends on:** Task 1, Task 5 + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Adapters/RealMxGatewayClient.cs` + +This is the only file that touches the generated protobuf/gRPC types. It is integration-shaped (no unit test — exercised in Task 19's smoke against a live/staged gateway). Implement `IMxGatewayClient` + `IMxGatewayClientFactory` (`RealMxGatewayClientFactory`). + +**Implementation notes (use the verbatim client API from the design doc / key-facts section):** +- `ConnectAsync`: build `MxGatewayClientOptions { Endpoint = new Uri(o.Endpoint), ApiKey = o.ApiKey, UseTls = o.UseTls, CaCertificatePath = o.CaFile, ServerNameOverride = o.ServerName }`; `_client = MxGatewayClient.Create(opts)`; `_galaxy = GalaxyRepositoryClient.Create(opts)`; `_session = await _client.OpenSessionAsync(ct)`; `_serverHandle = await _session.RegisterAsync(o.ClientName, ct)`; store `o.WriteUserId` and `o.ReadTimeoutMs`. Catch `MxGatewayAuthenticationException`/`MxGatewayAuthorizationException` and rethrow (the actor logs + retries on the reconnect cadence — auth failure is treated like a failed connect). +- `SubscribeAsync(tag)`: `var h = await _session.AddItemAsync(_serverHandle, tag, ct); await _session.AdviseAsync(_serverHandle, h, ct);` track `tag↔h`; return `h.ToString()`. +- `UnsubscribeAsync(id)`: parse handle; `await _session.UnAdviseAsync(_serverHandle, h, ct); await _session.RemoveItemAsync(_serverHandle, h, ct);`. +- `ReadAsync(tags)`: `var results = await _session.ReadBulkAsync(_serverHandle, tags, TimeSpan.FromMilliseconds(_readTimeoutMs), ct);` map each `BulkReadResult` → `MxReadOutcome(r.TagAddress, r.WasSuccessful, r.Value.ToClrValue(), MapQuality(r.Quality, r.Statuses), r.SourceTimestamp.ToDateTimeOffset(), r.WasSuccessful ? null : r.ErrorMessage)`. +- `WriteAsync(writes)`: build `WriteBulkEntry { ItemHandle = handleForTag, Value = value.ToMxValue(), UserId = _writeUserId }` (resolve item handle; AddItem on demand if the tag isn't already advised — keep a tag→handle cache). `await _session.WriteBulkAsync(...)`; map `BulkWriteResult` → `MxWriteOutcome(tag, r.WasSuccessful, r.WasSuccessful ? null : r.ErrorMessage)`. **Value conversion** uses the `ToMxValue()` overloads — pick by runtime type (bool/int/long/float/double/string/DateTime). +- `BrowseChildrenAsync(parentNodeId)`: build `BrowseChildrenRequest { IncludeAttributes = true }`; if `parentNodeId` is non-null set `ParentContainedPath = parentNodeId` (the NodeId we emit for objects is the contained path); `var reply = await _galaxy.BrowseChildrenRawAsync(req, ct);` then map: each `GalaxyObject` → `MxBrowseChild(NodeId: obj.ContainedName-or-derived-path, DisplayName: obj.TagName, NodeClass.Object, HasChildren: reply.ChildHasChildren[i])`; each `GalaxyAttribute` → `MxBrowseChild(NodeId: attr.FullTagReference, DisplayName: attr.AttributeName, NodeClass.Variable, HasChildren: false)`. Truncated = `!string.IsNullOrEmpty(reply.NextPageToken)`. Map any gRPC `RpcException` with `StatusCode.Unavailable` to `ConnectionNotConnectedException`. +- `RunEventLoopAsync(onUpdate, ct)`: `await foreach (var ev in _session.StreamEventsAsync(_lastSeq, ct))` — for each `ev` where `ev.Family == MxEventFamily.OnDataChange`, resolve the tag from `ev.ItemHandle`, `onUpdate(new MxValueUpdate(tag, ev.Value.ToClrValue(), MapQuality(ev.Quality, ev.Statuses), ev.SourceTimestamp.ToDateTimeOffset()))`, then `_lastSeq = ev.WorkerSequence`. Let the loop throw on stream break — the adapter turns that into `Disconnected`. +- `MapQuality(int quality, IReadOnlyList statuses)`: `if (statuses.Any(s => !s.IsSuccess())) return QualityCode.Bad;` `return quality >= 192 ? QualityCode.Good : (quality >= 64 ? QualityCode.Uncertain : QualityCode.Bad);` (192 = OPC Good, 64 = Uncertain band). +- `DisposeAsync`/`DisconnectAsync`: dispose session + both clients. + +**Step 1:** Write the file. **Step 2:** Build the DCL project: `dotnet build src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/` — expected PASS (this is where the generated-type field names are verified against the package; fix any casing mismatches against IntelliSense/the generated `.cs`). **Step 3:** Commit `feat(dcl): RealMxGatewayClient over ZB.MOM.WW.MxGateway.Client`. + +--- + +## Task 12: Factory registration + options binding + config flatten branch + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** Task 13, Task 14 — **NO** (this task and Task 13 both edit `DeploymentManagerActor.cs`; run them sequentially) +**Depends on:** Task 3, Task 5, Task 11 + +**Files:** +- Modify: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/DataConnectionFactory.cs` +- Modify: `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/ServiceCollectionExtensions.cs` +- Modify: `src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/DeploymentManagerActor.cs:759` +- Test: `tests/ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Tests/DataConnectionFactoryTests.cs` (and the SiteRuntime test project for the flatten branch) + +**Step 1: Test** — `factory.Create("MxGateway", new Dictionary())` returns a `MxGatewayDataConnection`; `FlattenConnectionConfig("MxGateway", json)` produces the flat dict from `MxGatewayEndpointConfigSerializer`. Run, verify FAIL. + +**Step 2: Register the adapter** in `DataConnectionFactory` (constructor, after the OPC UA registration). The factory currently takes `ILoggerFactory` + `IOptions`; add an optional `IOptions` param (default `Options.Create(new MxGatewayGlobalOptions())` in the convenience ctor, mirroring the existing OPC UA pattern): + +```csharp +RegisterAdapter("MxGateway", details => new MxGatewayDataConnection( + new RealMxGatewayClientFactory(_loggerFactory), + _loggerFactory.CreateLogger())); +``` + +**Step 3: Bind options** in `ServiceCollectionExtensions.AddDataConnectionLayer` (after the `OpcUaGlobalOptions` bind): + +```csharp + services.AddOptions() + .BindConfiguration("MxGateway"); +``` + +**Step 4: Add the flatten branch** in `DeploymentManagerActor.FlattenConnectionConfig` (before the generic fallback): + +```csharp + if (string.Equals(protocol, "MxGateway", StringComparison.OrdinalIgnoreCase)) + { + var config = Commons.Serialization.MxGatewayEndpointConfigSerializer.Deserialize(json); + return Commons.Serialization.MxGatewayEndpointConfigSerializer.ToFlatDict(config); + } +``` + +**Step 5:** Run tests, verify PASS; build the solution. **Step 6:** Commit `feat(dcl): register MxGateway protocol in factory + config flatten + options binding`. + +--- + +## Task 13: Rename browse message types to protocol-agnostic names + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** Tasks 2–11 (adapter track) — **NOT** Task 12 (shared file `DeploymentManagerActor.cs`) + +Mechanical rename. No new test — the existing browse tests are the regression guard. **Rename map** (old → new): +- `BrowseOpcUaNodeCommand` → `BrowseNodeCommand` +- `BrowseOpcUaNodeResult` → `BrowseNodeResult` +- `CommunicationService.BrowseOpcUaNodeAsync` → `BrowseNodeAsync` + +**Files (every reference — from the inventory):** +- `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/BrowseCommands.cs` (definitions; update the OPC-UA-specific XML doc comments to be protocol-neutral) +- `src/ZB.MOM.WW.ScadaBridge.Communication/CommunicationService.cs:360-371` (method + return type) +- `src/ZB.MOM.WW.ScadaBridge.Communication/Actors/SiteCommunicationActor.cs:155,158` +- `src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/DeploymentManagerActor.cs:152,157` (browse routing — NOT the FlattenConnectionConfig method) +- `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Actors/DataConnectionManagerActor.cs:49,118-142` +- `src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Actors/DataConnectionActor.cs:237,310,435,985-1046` +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/IOpcUaBrowseService.cs`, `OpcUaBrowseService.cs` (type refs only; the service rename is Task 14) +- `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/ReadTagValuesCommand.cs:11` (doc cross-ref) +- Any test files referencing `BrowseOpcUaNode*` (grep the `tests/` tree). + +**Step 1:** `grep -rn "BrowseOpcUaNode" src tests --include="*.cs" --include="*.razor"` to get the live list. **Step 2:** Rename across all hits (keep `BrowseFailure`/`BrowseFailureKind`/`BrowseNode`/`BrowseChildrenResult` unchanged — already generic). **Step 3:** `dotnet build ZB.MOM.WW.ScadaBridge.slnx` — expected PASS. **Step 4:** Run existing browse tests: `dotnet test --filter "FullyQualifiedName~Browse"` — expected PASS. **Step 5:** Commit `refactor(browse): rename BrowseOpcUaNode* to protocol-agnostic BrowseNode*`. + +--- + +## Task 14: Rename browse service + dialog to protocol-agnostic names + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** Tasks 2–11 +**Depends on:** Task 13 + +Mechanical rename within Central UI. **Rename map:** +- `IOpcUaBrowseService` → `IBrowseService`; `OpcUaBrowseService` → `BrowseService` (file renames too) +- `OpcUaBrowserDialog.razor` → `NodeBrowserDialog.razor` (component + file rename) +- Modal title `"Browse OPC UA — @ConnectionName"` → `"Browse — @ConnectionName"` (protocol-neutral) + +**Files:** +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/IOpcUaBrowseService.cs` → `IBrowseService.cs` +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/OpcUaBrowseService.cs` → `BrowseService.cs` (update `BrowseOpcUaNodeAsync` call to `BrowseNodeAsync` from Task 13; update doc comments) +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Dialogs/OpcUaBrowserDialog.razor` → `NodeBrowserDialog.razor` +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/ServiceCollectionExtensions.cs:56` (DI registration) +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/BindingTester.cs:13`, `Services/IBindingTester.cs:19` (type refs) +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Dialogs/TreeRow.razor:49-51` +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Deployment/InstanceConfigure.razor:370,378,410` (`` tag + `_browserRef` type + `OpcUaBrowserDialog?` field) +- `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Dialogs/TestBindingsDialog.razor:146` +- Any CentralUI tests referencing these symbols (grep `tests/`). + +**Step 1:** `grep -rn "OpcUaBrowseService\|IOpcUaBrowseService\|OpcUaBrowserDialog" src tests` for the live list. **Step 2:** Rename (use `git mv` for the file renames). **Step 3:** `dotnet build ZB.MOM.WW.ScadaBridge.slnx` — PASS. **Step 4:** Run CentralUI tests: `dotnet test tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/` — PASS. **Step 5:** Commit `refactor(browse): rename OPC-UA browse service + dialog to protocol-agnostic`. + +--- + +## Task 15: MxGatewayEndpointEditor.razor + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** Task 13 +**Depends on:** Task 3 +**Sub-skill:** @frontend-design + +**Files:** +- Create: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Forms/MxGatewayEndpointEditor.razor` + +Mirror `OpcUaEndpointEditor.razor` (read it first for the parameter/binding/validation-display conventions, and follow the form-layout memory: vertical stacking, read-only fields first, buttons at bottom). Two-way bind a `MxGatewayEndpointConfig` parameter; render inputs for Endpoint, ApiKey (type=password), ClientName, WriteUserId, UseTls (checkbox toggling CaFile/ServerName), ReadTimeoutMs. Show validation errors from `MxGatewayEndpointConfigValidator`. Parameters: `[Parameter] public string Title`, `[Parameter] public MxGatewayEndpointConfig Config`, `[Parameter] public EventCallback ConfigChanged`, `[Parameter] public IReadOnlyList Errors`. + +**Step 1:** Build the editor. **Step 2:** `dotnet build src/ZB.MOM.WW.ScadaBridge.CentralUI/` — PASS. **Step 3:** Commit `feat(centralui): MxGatewayEndpointEditor component`. + +--- + +## Task 16: Protocol selector in DataConnectionForm + +**Classification:** standard +**Estimated implement time:** ~5 min +**Parallelizable with:** none (depends on 15) +**Depends on:** Task 3, Task 15 +**Sub-skill:** @frontend-design + +**Files:** +- Modify: `src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Design/DataConnectionForm.razor` + +Currently hardcodes `Protocol = "OpcUa"` with ``. Add: +- A protocol ` + @RenderFieldError("Endpoint") + +
+ + + @RenderFieldError("ApiKey") +
+ + +
+
+ + +
+
+ + +
+
+ + + @RenderFieldError("ReadTimeoutMs") +
+
+ +
Transport security
+
+
+
+ + +
+
+ @if (Config.UseTls) + { +
+ + +
+
+ + +
+ } +
+ + +@code { + [Parameter, EditorRequired] public MxGatewayEndpointConfig Config { get; set; } = default!; + [Parameter] public string Title { get; set; } = "Endpoint"; + [Parameter] public string IdPrefix { get; set; } = "mxgateway-endpoint"; + [Parameter] public ValidationResult? Errors { get; set; } + + private RenderFragment? RenderFieldError(string field) + { + var match = Errors?.Errors.FirstOrDefault(e => + e.EntityName != null + && (e.EntityName == field || e.EntityName.EndsWith("." + field))); + return match is null + ? null + : @
@match.Message
; + } +} From be32e4a7ff9efe4e1f84062100fabe666d526383 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 29 May 2026 08:02:44 -0400 Subject: [PATCH 14/18] feat(centralui): protocol selector + MxGateway editor in DataConnectionForm Adds an OPC UA | MxGateway protocol dropdown (create-time; locked read-only on edit), branches the primary/backup endpoint editors, serializer, and validator by protocol, and persists DataConnection.Protocol accordingly. Updates form tests: protocol dropdown present on create + MxGateway save round-trips typed JSON with Protocol=MxGateway. --- .../Pages/Design/DataConnectionForm.razor | 148 ++++++++++++++---- .../DataConnectionFormTests.cs | 49 +++++- 2 files changed, 162 insertions(+), 35 deletions(-) diff --git a/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Design/DataConnectionForm.razor b/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Design/DataConnectionForm.razor index 3d8314fe..a96df290 100644 --- a/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Design/DataConnectionForm.razor +++ b/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Design/DataConnectionForm.razor @@ -49,17 +49,45 @@ } +
+ + @if (_protocolLocked) + { + +
Protocol is locked after creation.
+ } + else + { + + } +
Primary endpoint
- + @if (_protocol == "MxGateway") + { + + } + else + { + + }
Backup endpoint @@ -77,11 +105,21 @@ } else { - + @if (_protocol == "MxGateway") + { + + } + else + { + + }
s.Id == _formSiteId)?.Name ?? $"Site {_formSiteId}"; _siteLocked = true; _formName = _editingConnection.Name; + _protocol = string.IsNullOrWhiteSpace(_editingConnection.Protocol) ? "OpcUa" : _editingConnection.Protocol; + _protocolLocked = true; - (_primaryConfig, _primaryIsLegacy) = - OpcUaEndpointConfigSerializer.Deserialize(_editingConnection.PrimaryConfiguration); - - if (!string.IsNullOrWhiteSpace(_editingConnection.BackupConfiguration)) - { - (_backupConfig, _backupIsLegacy) = - OpcUaEndpointConfigSerializer.Deserialize(_editingConnection.BackupConfiguration); - _showBackup = true; - _formFailoverRetryCount = _editingConnection.FailoverRetryCount; - } + LoadConfig(_editingConnection); } } else if (SiteId.HasValue) @@ -177,32 +212,80 @@ } } + private void LoadConfig(DataConnection conn) + { + if (_protocol == "MxGateway") + { + _primaryMx = MxGatewayEndpointConfigSerializer.Deserialize(conn.PrimaryConfiguration); + if (!string.IsNullOrWhiteSpace(conn.BackupConfiguration)) + { + _backupMx = MxGatewayEndpointConfigSerializer.Deserialize(conn.BackupConfiguration); + _showBackup = true; + _formFailoverRetryCount = conn.FailoverRetryCount; + } + } + else + { + (_primaryConfig, _primaryIsLegacy) = + OpcUaEndpointConfigSerializer.Deserialize(conn.PrimaryConfiguration); + if (!string.IsNullOrWhiteSpace(conn.BackupConfiguration)) + { + (_backupConfig, _backupIsLegacy) = + OpcUaEndpointConfigSerializer.Deserialize(conn.BackupConfiguration); + _showBackup = true; + _formFailoverRetryCount = conn.FailoverRetryCount; + } + } + } + private async Task SaveConnection() { _formError = null; if (_formSiteId == 0) { _formError = "Site is required."; return; } if (string.IsNullOrWhiteSpace(_formName)) { _formError = "Name is required."; return; } - _primaryErrors = OpcUaEndpointConfigValidator.Validate(_primaryConfig, "Primary."); - _backupErrors = _showBackup - ? OpcUaEndpointConfigValidator.Validate(_backupConfig, "Backup.") - : null; + string primaryJson; + string? backupJson; - if (!_primaryErrors.IsValid || (_backupErrors is { IsValid: false })) + if (_protocol == "MxGateway") { - _formError = "Fix the errors below before saving."; - return; - } + _primaryErrors = MxGatewayEndpointConfigValidator.Validate(_primaryMx, "Primary."); + _backupErrors = _showBackup + ? MxGatewayEndpointConfigValidator.Validate(_backupMx, "Backup.") + : null; - var primaryJson = OpcUaEndpointConfigSerializer.Serialize(_primaryConfig); - var backupJson = _showBackup ? OpcUaEndpointConfigSerializer.Serialize(_backupConfig) : null; + if (!_primaryErrors.IsValid || (_backupErrors is { IsValid: false })) + { + _formError = "Fix the errors below before saving."; + return; + } + + primaryJson = MxGatewayEndpointConfigSerializer.Serialize(_primaryMx); + backupJson = _showBackup ? MxGatewayEndpointConfigSerializer.Serialize(_backupMx) : null; + } + else + { + _primaryErrors = OpcUaEndpointConfigValidator.Validate(_primaryConfig, "Primary."); + _backupErrors = _showBackup + ? OpcUaEndpointConfigValidator.Validate(_backupConfig, "Backup.") + : null; + + if (!_primaryErrors.IsValid || (_backupErrors is { IsValid: false })) + { + _formError = "Fix the errors below before saving."; + return; + } + + primaryJson = OpcUaEndpointConfigSerializer.Serialize(_primaryConfig); + backupJson = _showBackup ? OpcUaEndpointConfigSerializer.Serialize(_backupConfig) : null; + } try { if (_editingConnection != null) { _editingConnection.Name = _formName.Trim(); - _editingConnection.Protocol = "OpcUa"; + _editingConnection.Protocol = _protocol; _editingConnection.PrimaryConfiguration = primaryJson; _editingConnection.BackupConfiguration = backupJson; _editingConnection.FailoverRetryCount = _showBackup ? _formFailoverRetryCount : 3; @@ -210,7 +293,7 @@ } else { - var conn = new DataConnection(_formName.Trim(), "OpcUa", _formSiteId) + var conn = new DataConnection(_formName.Trim(), _protocol, _formSiteId) { PrimaryConfiguration = primaryJson, BackupConfiguration = backupJson, @@ -233,6 +316,7 @@ { _showBackup = false; _backupConfig = new OpcUaEndpointConfig(); + _backupMx = new MxGatewayEndpointConfig(); _backupIsLegacy = false; _formFailoverRetryCount = 3; } diff --git a/tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/DataConnectionFormTests.cs b/tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/DataConnectionFormTests.cs index b9d378b2..aaac4756 100644 --- a/tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/DataConnectionFormTests.cs +++ b/tests/ZB.MOM.WW.ScadaBridge.CentralUI.Tests/DataConnectionFormTests.cs @@ -44,12 +44,55 @@ public class DataConnectionFormTests : BunitContext } [Fact] - public void NoProtocolDropdown_IsRendered() + public void ProtocolDropdown_IsRendered_OnCreate_WithBothProtocols() { var cut = RenderForCreateSite(1); - Assert.DoesNotContain("Custom", cut.Markup); var labels = cut.FindAll("label").Select(l => l.TextContent.Trim()).ToList(); - Assert.DoesNotContain(labels, l => l == "Protocol"); + Assert.Contains(labels, l => l == "Protocol"); + + // The protocol select offers OPC UA and MxGateway. + var optionTexts = cut.FindAll("option").Select(o => o.TextContent.Trim()).ToList(); + Assert.Contains("OPC UA", optionTexts); + Assert.Contains("MxGateway", optionTexts); + } + + [Fact] + public async Task Save_MxGateway_PersistsTypedJsonAndProtocolMxGateway() + { + DataConnection? captured = null; + await _siteRepo.AddDataConnectionAsync( + Arg.Do(d => captured = d)); + + var cut = RenderForCreateSite(1); + + // Switch protocol to MxGateway — re-renders with the MxGateway editor. + cut.FindAll("select") + .First(s => s.QuerySelectorAll("option").Any(o => o.TextContent.Trim() == "MxGateway")) + .Change("MxGateway"); + + // Name (skip readonly Site plaintext input; MxGateway editor inputs carry placeholders). + cut.FindAll("input[type='text']") + .First(i => !i.HasAttribute("readonly") && i.GetAttribute("placeholder") is null) + .Change("MX-1"); + // Gateway endpoint + cut.FindAll("input[type='text']") + .First(i => i.GetAttribute("placeholder")?.StartsWith("http://") == true) + .Change("http://gw:5000"); + // API key (password input) + cut.FindAll("input[type='password']") + .First(i => i.GetAttribute("placeholder")?.Contains("API key") == true) + .Change("secret"); + + await cut.FindAll("button") + .First(b => b.TextContent.Trim() == "Save").ClickAsync(new()); + + Assert.NotNull(captured); + Assert.Equal("MxGateway", captured!.Protocol); + Assert.NotNull(captured.PrimaryConfiguration); + + using var doc = JsonDocument.Parse(captured.PrimaryConfiguration!); + Assert.Equal("http://gw:5000", + doc.RootElement.GetProperty("endpoint").GetString()); } [Fact] From 569edf29758299bc512ce13cb300a236456d2908 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 29 May 2026 08:03:59 -0400 Subject: [PATCH 15/18] feat(centralui): enable tag picker for MxGateway connections Generalize the browse-button gate from IsOpcUa to IsBrowsable (OPC UA or MxGateway, both implement IBrowsableDataConnection site-side). The generalized NodeBrowserDialog + BrowseNodeCommand path already routes by protocol; non- browsable protocols return NotBrowsable. Test Bindings stays OPC-UA-only (its read path is out of this slice's scope). --- .../Pages/Deployment/InstanceConfigure.razor | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Deployment/InstanceConfigure.razor b/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Deployment/InstanceConfigure.razor index 997e0cc6..7ab70a3f 100644 --- a/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Deployment/InstanceConfigure.razor +++ b/src/ZB.MOM.WW.ScadaBridge.CentralUI/Components/Pages/Deployment/InstanceConfigure.razor @@ -118,7 +118,7 @@ { var connId = GetBindingConnectionId(attr.Name); var canBrowse = connId > 0; - var isOpcUa = IsOpcUa(connId); + var isBrowsable = IsBrowsable(connId); @attr.Name @attr.DataSourceReference @@ -140,7 +140,7 @@ placeholder="@(attr.DataSourceReference ?? "(no default)")" /> - @if (isOpcUa) + @if (isBrowsable) {