lmxopcua/docs/plans/2026-05-28-adminui-driver-pages-design.md

AdminUI — Driver-Specific Pages

Status: Design approved, ready for implementation planning Date: 2026-05-28 Branch: master (work to land on a feature branch)

1. Motivation

Today the AdminUI has a single generic DriverEdit.razor page (src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Clusters/DriverEdit.razor, 323 lines) that edits every driver type via a raw JSON DriverConfig textarea. The page itself flags this as temporary:

Per Q1 of the AdminUI rebuild plan, typed driver editors (Modbus, FOCAS) are deferred… lands in a Phase C.2 follow-up.

This design is that follow-up. Goals:

1. Replace the JSON blob with a typed form per driver type that exposes every supported configuration option.
2. Add three driver-aware operator capabilities to each page: Test Connect, live runtime status, and a driver-specific tag/address picker.
3. Add Reconnect / Restart controls on the status panel for authorized users.

2. Scope

All 9 driver types ship typed pages in this work:

ModbusTcp, AbCip, AbLegacy, S7, TwinCat, FOCAS,
OpcUaClient, Galaxy, Historian.Wonderware

Each typed page exposes the full surface of its driver's options class — the JSON editor is retired; the typed form is the only way to edit driver config from the AdminUI.

3. Architecture

3.1 Project layout

src/Drivers/
  ZB.MOM.WW.OtOpcUa.Driver.<Type>/                     (runtime, unchanged behavior)
  ZB.MOM.WW.OtOpcUa.Driver.<Type>.Contracts/           NEW — POCO options + DataAnnotations only
    <Type>DriverOptions.cs                              (moved from runtime project)

src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/
  Components/Pages/Clusters/Drivers/                    NEW folder
    DriverTypePicker.razor                              route: /clusters/{id}/drivers/new
    DriverEditRouter.razor                              route: /clusters/{id}/drivers/{instanceId}
    ModbusDriverPage.razor                              route: /clusters/{id}/drivers/new/modbus
    GalaxyDriverPage.razor                              route: /clusters/{id}/drivers/new/galaxy
    S7DriverPage.razor
    OpcUaClientDriverPage.razor
    AbCipDriverPage.razor
    AbLegacyDriverPage.razor
    TwinCatDriverPage.razor
    FocasDriverPage.razor
    HistorianWonderwareDriverPage.razor
  Components/Shared/Drivers/                            NEW folder
    DriverFormShell.razor                               panel layout + Save/Cancel/Delete
    DriverIdentitySection.razor                         InstanceId, Name, Namespace, Enabled
    DriverResilienceSection.razor                       Polly overrides
    DriverStatusPanel.razor                             live status + Reconnect/Restart
    DriverTestConnectButton.razor                       per-driver-timeout probe
    DriverTagPicker.razor                               modal shell, hosts per-driver picker body
  Hubs/
    DriverStatusHub.cs                                  NEW SignalR hub at /hubs/driverstatus
    DriverStatusSignalRBridge.cs                        NEW (mirrors FleetStatusSignalRBridge)

3.2 Routing

• /clusters/{ClusterId}/drivers — existing ClusterDrivers.razor list, unchanged.
• /clusters/{ClusterId}/drivers/new — new DriverTypePicker.razor (operator picks driver type).
• /clusters/{ClusterId}/drivers/new/{driverType} — typed new-form for that type.
• /clusters/{ClusterId}/drivers/{DriverInstanceId} — DriverEditRouter.razor reads the row's DriverType, dispatches to the right *DriverPage via <DynamicComponent> (no redirect flicker).

3.3 Schema source

Each driver's Options class moves to a new Driver.<Type>.Contracts csproj — POCO + System.ComponentModel.DataAnnotations attributes only, no NuGet references, no project references. The runtime driver project adds a ProjectReference to its contracts sibling and re-uses the same type (single source of truth, no TypeForwardedTo needed if the namespace is preserved). The AdminUI gains 9 ProjectReferences — all pure POCO, so no native deps (Galaxy COM, FOCAS native libs, OPC UA stack) leak into the AdminUI publish output.

Attributes used:

• [Required], [Range(...)], [RegularExpression(...)] — render as inputs + <ValidationMessage> via DataAnnotationsValidator.
• [Display(Name, Description, GroupName)] — label, help-text under field, panel section.
• [DataType(DataType.Password)] — render as <InputText type="password"> (e.g. mxaccessgw API key).

The *DriverPage.razor files explicitly bind each field (no runtime reflection). Attributes drive labels/help/validation but not field discovery — this avoids the "metadata silently drifts from rendering" trap.

3.4 Persistence

DriverInstance.DriverConfig stays a JSON string column (no schema change). On save: typed form-model serialized via System.Text.Json against the driver's Options class. On load: row's JSON deserialized into the matching Options class with JsonSerializerOptions { UnmappedMemberHandling = Skip } so old/unknown fields are silently dropped on next save. Version skew is bounded by the fact that drivers ship as one host binary.

RowVersion optimistic concurrency unchanged from today's DriverEdit.razor.

4. Test Connect

4.1 Flow

[Browser]              [AdminUI server]              [Cluster]

DriverGalaxyPage       AdminProbeService             AdminOperationsActor
   |                         |                              |
   |-- click TestConnect --->|                              |
   |                         |-- Ask<TestDriverConnect> --->|
   |                         |    (driverType, configJson,  |
   |                         |     timeoutSecs)             |
   |                         |                              |--> spawn transient probe actor
   |                         |                              |    (resolves IDriverProbe by
   |                         |                              |     driverType via DI)
   |                         |                              |<-- ProbeResult (ok, latencyMs)
   |                         |<-- TestDriverConnectResult --|
   |<-- green / red chip ----|

4.2 Components

• IDriverProbe — interface in Core.Abstractions (or equivalent). One implementation per driver type, lives in the driver's runtime project. Reuses the existing IHostConnectivityProbe plumbing where present (FOCAS, TwinCAT confirmed). For drivers without one, the probe is a cheap subset of the real connect path: TCP SocketAsyncOperations for Modbus/AbCip/S7, session open+close for OpcUaClient, MxCommand.Ping for Galaxy. Probes never write.
• TestDriverConnect message in Commons/Messages/Admin — (string driverType, string configJson, TimeSpan timeout). Handler in AdminOperationsActor: resolves the right probe via keyed DI (IServiceProvider.GetRequiredKeyedService<IDriverProbe>(driverType)), deserializes JSON into the matching Options class, calls probe.RunAsync(options, ct). Returns TestDriverConnectResult(bool ok, string? message, TimeSpan? latency).
• AdminProbeService (AdminUI side) — thin wrapper around the existing AdminOperationsActor bridge. Caller passes timeout; service enforces a 60s hard backstop.
• <DriverTestConnectButton> — accepts driver type + Func<string> to build form JSON on-click. Renders button + inline result chip (auto-clears after 30s). Disabled while in-flight.

4.3 Timeout

Each driver's Options class exposes a ProbeTimeout (TimeSpan or int Seconds) with a driver-appropriate default — e.g. Modbus 5s, OpcUaClient 15s, Galaxy 30s. The button reads from the live form (not the persisted row), so an operator can override the timeout per probe attempt. Server-side max = 60s.

4.4 Safety

• Probe spawns a transient actor with the form's config — the live driver actor (using the persisted config) is untouched.
• Probe never mutates the live driver or the database.
• Probe inherits the user context via the existing AdminOperationsActor audit-log entry.

5. Live Status Panel

5.1 Flow

DriverActor          DriverStatusSignalRBridge        DriverStatusPanel (browser)
  |                          ^                                |
  |-- publishes              |-- subscribed in                |
  |   DriverHealthChanged    |   OnInitializedAsync           |
  |   to event stream        |   with InstanceId filter       |
  |                          |                                |
  |                          |-- pushes update -------------->|
  |                                                            |
  |                                                            |-- renders state chip,
  |                                                            |   last-success, error count,
  |                                                            |   Reconnect/Restart buttons

5.2 Reused infrastructure

Driver actors already maintain DriverHealth(state, lastSuccessUtc, lastError) — confirmed in FOCAS (FocasDriver.cs) and TwinCAT. The bridge mirrors the existing FleetStatusSignalRBridge + AlertSignalRBridge pattern. SignalR hub uses the same cookie-auth as existing hubs.

5.3 New components

• DriverStatusHub — single method JoinDriver(string driverInstanceId), adds connection to a per-instance group and immediately replies with the current snapshot.
• DriverStatusSignalRBridge — subscribes to per-cluster driver-health event stream, fans out into SignalR groups keyed by driverInstanceId. Only running drivers publish; Enabled=false instances render "Disabled — not deployed" without subscribing.
• <DriverStatusPanel> — props DriverInstanceId, Enabled. Opens hub on init, calls JoinDriver, registers On<StatusSnapshot>("status", ...). Renders state chip (Healthy / Connecting / Faulted / Unknown) + last-success timestamp ("2s ago") + error count over last 5min + last error message (collapsed, expandable). Disposes hub on dispose.

5.4 Reconnect / Restart controls

Two buttons on the status panel:

• Reconnect — driver actor closes + reopens its transport, keeps actor alive. Fast, idempotent. No confirm dialog.
• Restart — full actor stop + respawn, loses in-memory state. Slower, can interrupt active subscriptions. Confirm dialog required.

Both:

• Gated by authorization policy DriverOperator (mapped to an LDAP group via existing Authentication.Ldap config). Hidden (not just disabled) for unauthorized users — same approach as other AdminUI gated actions.
• Dispatch RestartDriver / ReconnectDriver messages through AdminOperationsActor, which audit-logs each operation.
• Show spinner + inline "Reconnecting…" chip; panel reflects new state via the SignalR push once health changes.
• Disabled when Enabled=false (nothing to restart) and during any in-flight Test Connect on the same page.

5.5 Out of scope this PR

History graphs (latency/error rate over time), deep diagnostics (per-tag last values, queue depths), and per-driver bespoke controls beyond Reconnect/Restart — all follow-ups.

5.6 Edge cases

• Driver not yet deployed (row exists, Enabled=true, cluster hasn't picked it up) — panel shows "Awaiting deployment", DriverHealth.Unknown.
• Edit page open while driver is running — status reflects deployed config, not the form. Banner: "Showing live status for the deployed config — your unsaved changes take effect after Save → next deploy cycle."
• Test Connect + live status — probe runs in a transient actor (Section 4), live status reflects the persistent actor. Don't interfere.

6. Tag / Address Picker

A picker slot on each page, launched as a modal so the config form stays visible behind it.

6.1 Shared shell

<DriverTagPicker> — modal chrome + search box + "use this address" action that emits a string back to the parent (e.g. 4x0001 for Modbus, ns=2;s=Channel.Device.Tag for OPC UA). Where the picked address lands depends on context: from "create equipment / create tag" flow, pushed into that form; standalone, copy-to-clipboard.

6.2 Per-driver bodies — first pass (all static address builders)

Driver	Picker body
Modbus	Register-type dropdown + offset spinner + length → 4x00001-4
AbCip	Tag name + element index, PLC-family hint from form
AbLegacy	File type (N/B/F/I/O/S/T/C/R) + file number + element, PLC-family-aware
S7	Area (DB/M/I/Q) + db-number + offset + S7 type → DB10.DBD20:REAL
TwinCat	ADS variable name (free-text + format hint)
FOCAS	Parameter group dropdown + parameter ID; drives FOCAS function-code lookup
OpcUaClient	Static helper (NodeId free-text) — live browse deferred
Galaxy	Static helper (tag_name.AttributeName free-text) — live browse deferred
Historian.Wonderware	Tag name + retrieval mode + interval

6.3 Deferred to follow-up

• OpcUaClient live browse — open session against configured endpoint, walk address space, return NodeId. Reuses the existing Client.CLI browse path or calls the OPC UA stack inline. Requires endpoint config to be valid (Test Connect first).
• Galaxy live browse — calls mxaccessgw's GalaxyRepository.ListObjects / ListAttributes via gRPC. Returns tag_name.AttributeName. Reuses IGalaxyHierarchySource.
• Historian.Wonderware tag list — pull from historian's tag store.

The picker slot is wired so swapping a static builder for a live browser later is a 1-component swap, not a page rewrite.

7. Error Handling

Failure	Surface
Invalid form input	DataAnnotationsValidator + per-field <ValidationMessage>; Save disabled.
DbUpdateConcurrencyException	Red banner — "Another user changed this driver instance, reload before re-applying." (matches existing pattern)
FK violation (Namespace deleted while edit open)	Catch DbUpdateException — "Namespace <id> no longer exists in this cluster — pick another or recreate it."
Probe — driver-side exception	Probe actor catches, returns (false, ex.Message, null). Red chip with message. Full stack to Serilog with audit context.
Probe — timeout	(false, "Probe timed out after {n}s", null). Server-side 60s backstop.
Probe — DI lookup fails (unknown driver type)	Defensive — (false, "No probe registered for driver type '{type}'", null). Error-level log.
SignalR disconnect	"Reconnecting…" chip + SignalR auto-reconnect. Stale snapshot dimmed after 30s.
Reconnect/Restart on stopped driver	"Driver is not running on any node". Button re-enables.
Authorization denied	Reconnect/Restart buttons hidden for unauthorized users.
Corrupted DriverConfig JSON on row load	Yellow banner — "Saved config could not be parsed against the current schema; falling back to defaults. Save will overwrite." Original JSON preserved in banner for copy-paste.

8. Testing

8.1 Unit tests (tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/ — extend existing project, or create if absent)

• DriverPageFormSerializationTests — 9 drivers × round-trip Options ↔ JSON ↔ form ↔ DB row. Asserts no loss for known fields, unknown fields dropped silently.
• DriverTestConnectButtonTests — render tests: enabled/disabled states, timeout behavior, result chip.
• DriverStatusPanelTests — render snapshots for each DriverState, disabled mode, stale-data dim.
• DriverRestartReconnectAuthorizationTests — buttons hidden without DriverOperator policy.
• Address-builder unit tests per driver — 9 small suites covering canonical address formats.

8.2 Integration tests (tests/Server/.../IntegrationTests/)

• DriverTestConnectE2eTests — Modbus + AbCip + S7 against Docker fixtures (lmxopcua-fix up modbus etc.). Green probe vs sim, red probe vs wrong port, timeout vs black-holed IP.
• DriverReconnectE2eTests — start a driver, click Reconnect, assert Connecting → Healthy transition within N seconds.
• DriverStatusHubE2eTests — open hub, force state change, assert push arrives within 1s.

8.3 Manual smoke (run before PR ship)

Operator on the dev VM with Docker fixtures available:

1. Pre-flight:

   • lmxopcua-fix up modbus standard — Modbus sim running on 10.100.0.35:5020.
   • AdminUI deployed and reachable.
   • LDAP user has the DriverOperator (or FleetAdmin) role.

2. Type picker:

   • Navigate to /clusters/<id>/drivers/new. Verify 9 driver-type cards render.
   • Click "ModbusTcp". Verify the typed form opens on /clusters/<id>/drivers/new/modbustcp.

3. Test Connect (form-driven, no save):

   • Fill in Host=10.100.0.35, Port=5020, leave defaults otherwise.
   • Click "Test Connect". Verify green chip + latency < 100ms.
   • Change port to 9999. Click again. Verify red chip with "ConnectionRefused" or similar.
   • Change host to 1.2.3.4. Click again. Within (default 5s) the chip shows "Probe timed out after 5s".

4. Save + edit:

   • Set valid endpoint back. Save. Verify redirect to /clusters/<id>/drivers.
   • Open the just-saved instance. Verify the typed form pre-populates correctly.

5. Live status panel:

   • In a second browser tab, open the same driver's edit page. Confirm the DriverStatusPanel renders state + last-update.
   • Stop the Modbus sim (lmxopcua-fix down modbus). Within ~30s, verify the panel transitions Healthy → Reconnecting / Faulted (depending on driver state).
   • Bring the sim back up (lmxopcua-fix up modbus standard). Verify Healthy is restored.

6. Reconnect / Restart:

   • Click "Reconnect" on the status panel. Verify a brief "Reconnecting…" chip + a Healthy state push within 5s.
   • Click "Restart". Confirm in the dialog. Verify the actor restarts (full state transition).
   • Verify both buttons are HIDDEN for an unauthorized user (LDAP user without DriverOperator role).

7. Address picker:

   • Click "Pick address" on the Modbus page. Verify the modal opens.
   • Builder: select Holding + offset=10 + length=2. Verify the chip shows 4x00010-2. Click "Use this address" — verify it surfaces in the parent page.
   • Close the modal. Repeat for one other driver type (e.g. S7) to confirm cross-driver wiring.

8. Other 8 driver types — smoke each page renders:

   • Repeat steps 2–4 for each remaining driver type. For Galaxy, the Test Connect uses the mxaccessgw endpoint; for OPC UA, an opc.tcp:// endpoint.

If any step fails, record the failure mode + Razor / actor log excerpts and reopen for fix before PR ship.

8.4 bUnit harness

If the AdminUI tests project doesn't already use bUnit, render tests downgrade to logic-only tests on the @code { } block; Razor markup is covered by integration tests. Decision deferred to implementation plan.

9. Migration / Sequencing

Incremental — driver-by-driver swap-over. Each step compile-clean and shippable on its own:

1. Land 9 Contracts projects + move Options classes. No UI changes.
2. Land shared section components (DriverIdentitySection, DriverResilienceSection, DriverFormShell). Wire into existing DriverEdit.razor first so they're tested in place.
3. Land DriverTypePicker + DriverEditRouter + <DynamicComponent> dispatch.
4. Land driver-specific pages one at a time. After each, route list-page links for that driver type only to the new page; leave others on generic editor.
5. Delete the generic DriverEdit.razor + its route once all 9 typed pages exist.
6. Land DriverStatusHub + bridge + <DriverStatusPanel> (read-only first).
7. Land <DriverTestConnectButton> + IDriverProbe impls + AdminOperationsActor handler.
8. Land Reconnect/Restart on the status panel with DriverOperator policy.
9. Land 9 static address builders inside <DriverTagPicker>.

10. Out of scope (follow-ups)

• Live tag browse for OpcUaClient + Galaxy (Section 6.3).
• Historian.Wonderware tag list pulled from store.
• Status panel history graphs + per-tag diagnostics (Section 5.5).
• Per-driver bespoke controls beyond Reconnect/Restart.
• bUnit setup if not already present (Section 8.4) — decide during implementation planning.