# OpcUaClient driver factory — Design

**Date:** 2026-06-13
**Status:** Approved — ready for implementation planning
**Scope:** Register the OpcUaClient driver factory so OpcUaClient driver instances are actually constructed instead of stubbed. Fixes a real bug AND yields the first end-to-end live equipment-tag value (proving the live-value router shipped in `c4435e4f`).

## Goal

Make `DriverType="OpcUaClient"` instances real: the runtime currently logs `"no factory for driver type OpcUaClient … falling back to stub"`, so OpcUaClient drivers never connect, subscribe, or publish. After this, an OpcUaClient equipment tag (`TagConfig.FullName = "<upstream NodeId>"`) subscribes to the upstream server and publishes values, which the (already-shipped) `FullName→NodeId` router delivers to the materialised variable.

## Root cause (confirmed)

- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Drivers/DriverFactoryBootstrap.cs:98-107` (`Register`) wires AbCip/AbLegacy/FOCAS/Galaxy/Modbus/S7/TwinCAT factories — but **omits OpcUaClient**.
- The `Driver.OpcUaClient` project has **no `…FactoryExtensions` class** (only `OpcUaClientDriver.cs` + `OpcUaClientDriverProbe.cs`). So there is nothing to register.
- Result: `IDriverFactory.TryCreate("OpcUaClient", …)` returns null → `DriverInstanceActor` falls back to a stub. (Note: this is the *missing-factory* stub path, distinct from `ShouldStub`, which only stubs windows-only `"Galaxy"`/`"Historian.Wonderware"`. OpcUaClient is cross-platform, so once a factory exists it runs as a real driver — including in docker-dev Linux.)

## Approach — mirror `ModbusDriverFactoryExtensions`

The OpcUaClient config JSON **is** the `OpcUaClientDriverOptions` shape — the probe already does `JsonSerializer.Deserialize<OpcUaClientDriverOptions>(configJson, _opts)` with `_opts = { PropertyNameCaseInsensitive = true, UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip }`. So no DTO is needed.

### Components

1. **NEW `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriverFactoryExtensions.cs`** — mirrors `ModbusDriverFactoryExtensions`:
   - `const string DriverTypeName = "OpcUaClient";`
   - `private static readonly JsonSerializerOptions JsonOptions = new() { PropertyNameCaseInsensitive = true, UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip };` (same as the probe).
   - `public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)` → `registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory));`
   - `public static OpcUaClientDriver CreateInstance(string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory = null)`:
     deserialize → throw if null → `new OpcUaClientDriver(options, driverInstanceId, loggerFactory?.CreateLogger<OpcUaClientDriver>())`.
   - Validate required: at minimum a usable endpoint (`EndpointUrl` or `EndpointUrls`) — but keep validation light; the driver's `InitializeAsync` already fails clearly on a bad endpoint, and a too-strict factory could reject valid configs. (Match Modbus's level: it only checks `Host` is present.) Decision: deserialize-and-construct; let `InitializeAsync` own connection validation. Optionally a null/empty-endpoint guard with a clear message.

2. **MODIFY `DriverFactoryBootstrap.cs`** — add one line to `Register`:
   `Driver.OpcUaClient.OpcUaClientDriverFactoryExtensions.Register(registry, loggerFactory);`
   (The Host already references the `Driver.OpcUaClient` project and registers `OpcUaClientDriverProbe`.)

## Error handling

- Null/invalid config JSON → `InvalidOperationException` naming the instance (mirrors Modbus). Connection/endpoint problems surface through `InitializeAsync` (the driver's existing failover-sweep diagnostics), not the factory.

## Testing (no bUnit)

- **Unit (xUnit + Shouldly):** `OpcUaClientDriverFactoryExtensions.CreateInstance` with a representative config JSON (e.g. `{"EndpointUrl":"opc.tcp://host:4840","SecurityMode":"None","AutoAcceptCertificates":true}`) returns an `OpcUaClientDriver` whose `DriverType == "OpcUaClient"` and `DriverInstanceId` matches; null/garbage JSON throws. (Mirror the Modbus factory test; place in the OpcUaClient driver's test project, or `Admin.Tests` if that's where factory tests live — confirm at plan time.)
- **Live docker-dev `/run` (agent-driven; login disabled) — the payoff:** the `MAIN-opcua-eq` OpcUaClient driver + `FastUInt1` tag (`{"FullName":"ns=3;s=FastUInt1"}`) are **already authored + deployed** in the dev rig (left from the router live-verify); opc-plc sim is up at `opc.tcp://10.100.0.35:50000`. Rebuild central on the branch, redeploy, and confirm: (a) the logs no longer say "no factory for driver type OpcUaClient" — the driver connects to opc-plc + subscribes; (b) the variable `ns=2;s=EQ-55297329838d/FastUInt1` on the OtOpcUa server (`opc.tcp://localhost:4840`) shows a **live, changing value** via Client.CLI `read`/`subscribe` (not `BadWaitingForInitialData`). **This live-proves the router (`c4435e4f`) end-to-end with a real driver.**

## Out of scope

- Protocol-driver (Modbus/S7) equipment-tag↔tag-table linkage (the larger gap — separate milestone).
- Galaxy gateway availability.
- Any change to the OpcUaClient driver's connection/subscribe logic (it already works; it just was never instantiated).

## Hard rules

Stage by path; never `git add .`; never stage `sql_login.txt` / `src/Server/.../Host/pki/` / `pending.md` / `current.md`. No force-push, no `--no-verify`. No Configuration/EF migration change. Build on a feature branch off master.