Auto: opcuaclient-11 — reverse connect (server-initiated)

Closes #283

docs/drivers/OpcUaClient-Test-Fixture.md

@@ -47,6 +47,13 @@ the tests mock.
 - `OpcUaClientSmokeTests.Client_subscribe_receives_StepUp_data_changes_from_live_server` —
   real `MonitoredItem` subscription against `ns=3;s=FastUInt1` (ticks every
   100 ms); asserts `OnDataChange` fires within 3 s of subscribe
+- `OpcUaClientReverseConnectSmokeTests.Driver_accepts_reverse_connect_from_opc_plc_rc_simulator` —
+  reverse-connect (server-initiated) coverage. Driver binds
+  `opc.tcp://0.0.0.0:4844`, the `opc-plc-rc` docker service dials in via
+  `--rc opc.tcp://host.docker.internal:4844`, and a Read round-trips over
+  the inbound socket. Gated on `OPCUA_RC_SIM=1` because the simulator
+  requires `host.docker.internal` resolution which not every CI runner
+  exposes.
 
 Wire-level surfaces verified: `IDriver` + `IReadable` + `ISubscribable` +
 `IHostConnectivityProbe` (via the Secure Channel exchange).

docs/drivers/OpcUaClient.md

@@ -59,3 +59,70 @@ Flip `WatchModelChanges` to `false` when:
 - The upstream server fires spurious `ModelChangeEvent`s that don't
   reflect real topology changes, causing wasted re-imports. Tighten or
   disable rather than chasing the noise downstream.
+
+## Reverse Connect (server-initiated)
+
+OPC UA's reverse-connect mode flips the transport direction: instead of the
+client dialling the server, the **server** dials the client's listener. The
+upstream sends a `ReverseHello` and the client continues the OPC UA
+handshake on the inbound socket. Required for OT-DMZ deployments where the
+plant firewall only permits outbound traffic from the upstream — the
+gateway opens a listener, the upstream reaches out.
+
+### Configuration
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `ReverseConnect.Enabled` | `false` | Opt-in. When `true`, replaces the failover dial-sweep with a `WaitForConnection` call. |
+| `ReverseConnect.ListenerUrl` | `null` | Local listener URL the SDK binds. Typically `opc.tcp://0.0.0.0:4844` (any interface) or a specific NIC for multi-homed gateways. **Required when `Enabled` is `true`.** |
+| `ReverseConnect.ExpectedServerUri` | `null` | Upstream's `ApplicationUri` to filter inbound dials. `null` accepts the first connection (only safe with one upstream targeting the listener). |
+
+### Shared listener (singleton)
+
+A single underlying `Opc.Ua.Client.ReverseConnectManager` per process keyed
+on `ListenerUrl`. Two driver instances that share a listener URL multiplex
+onto one TCP socket; the SDK demuxes inbound dials by the upstream's
+reported `ServerUri`. The wrapper (`ReverseConnectListener`) is
+reference-counted — first `Acquire` binds the port, last `Release` tears it
+down. Letting drivers come and go independently without races on
+port-bind / port-unbind.
+
+When two drivers share a listener:
+
+- They MUST set `ExpectedServerUri` to disambiguate; otherwise the first
+  upstream to dial in wins regardless of which driver is waiting.
+- They CAN come and go independently; the listener stays alive while at
+  least one driver references it.
+
+### Behaviour
+
+- The dial path is bypassed entirely when `Enabled` is `true`. Failover
+  across multiple `EndpointUrls` doesn't apply — there's no client-side
+  dial to fail over.
+- `ExpectedServerUri` is the SDK's filter parameter to `WaitForConnectionAsync`.
+  Inbound `ReverseHello`s from a different upstream are ignored and the
+  caller keeps waiting.
+- The same `EndpointDescription` derivation runs as the dial path — the
+  first `EndpointUrl` in the candidate list seeds `SecurityPolicy` /
+  `SecurityMode` / `EndpointUrl` for the session-create call. The actual
+  endpoint lives on the upstream and the SDK reconciles after the
+  `ReverseHello`.
+- Cancellation: `Timeout` bounds the wait. A stuck listener with no inbound
+  dial throws after `Timeout` rather than hanging init forever.
+- Shutdown releases the listener reference. The last release stops the
+  listener so the port can be re-bound by a future driver lifecycle.
+
+### Wiring it up on the upstream
+
+The upstream OPC UA server has to be configured to dial out. The `opc-plc`
+simulator does this with `--rc=opc.tcp://<gateway-host>:4844`; for a real
+upstream see your server's reverse-connect docs (most major implementations
+expose a "ReverseConnect.Endpoint" config knob).
+
+### When NOT to use
+
+- Standard plant networks where the gateway can dial the upstream — the
+  conventional dial path is simpler and supports failover natively.
+- Public-internet OPC UA: reverse-connect is a network-policy workaround,
+  not a security primitive. Always pair with `Sign` or `SignAndEncrypt`
+  + a vetted user-token policy.