lmxopcua/docs/plans/2026-06-16-stillpending-phase-5-probes-design.md

# Still-Pending Phase 5 — Test-Connect protocol handshakes — design

> **Status:** approved 2026-06-16. Parent roadmap: `docs/plans/2026-06-15-stillpending-backlog-design.md` (Phase 5).
> Source backlog: `stillpending.md` §2 ("Test-Connect probes are TCP-only") + plan
> `2026-05-28-adminui-driver-pages` Phase 7 + `2026-06-12-historian-tcp-transport` task 9.
> Branch `feat/stillpending-phase-5-probes` off master `050f5c4b`. Phases 0–4 already shipped.

## Goal

Replace the bare-TCP `socket.ConnectAsync` Test-Connect probes with **real protocol handshakes** so a
*live-but-rejecting* device reads **RED**, not green. Today a firewalled port, a non-Modbus TCP server, a
PLC at the wrong rack/slot, or a down-but-port-forwarded OPC UA endpoint all surface a healthy tick — the
operator gets a false "connection OK" and only discovers the truth when the driver faults at deploy.

## Grounding (verified this session)

- **All 8 probes are byte-identical TCP-only** boilerplate (`deserialize → ExtractTarget → Socket.ConnectAsync
  → close`): Modbus, S7, AbCip, AbLegacy, TwinCAT, OpcUaClient, Galaxy, FOCAS.
- **Historian.Wonderware is ALREADY a real handshake** — it sends a `Hello` and confirms `HelloAck`
  (`WonderwareHistorianDriverProbe.cs:54-71`). So §2's "task 9 / historian probe" is **already done**; this
  phase does not touch it (only documents it).
- **Every driver already owns the handshake primitive** in its client code — no new package references:
  - Modbus: `ModbusTcpTransport.ConnectAsync` + `IModbusTransport.SendAsync(unitId, pdu, ct)`.
  - S7: `new Plc(cpu, host, port, rack, slot).OpenAsync(ct)` (COTP CR/CC + S7 setup-communication).
  - AbCip / AbLegacy: `libplctag` Tag `InitializeAsync` (opens the EIP session + first CIP op).
  - TwinCAT: `AdsClient.Connect(netId, port)` + `ReadStateAsync` (`AdsTwinCATClient.cs:90,194`).
  - OpcUaClient: `DiscoveryClient.GetEndpointsAsync` (no session / cert / auth — `OpcUaClientDriver.cs:422`).
  - Galaxy: the `MxGateway.Client` gRPC channel + one lightweight unary call.
  - FOCAS: `cnc_allclibhndl3` via the existing wire P/Invoke (`Wire.WireFocasClient`).
- **Probe dispatch** clamps the timeout to 1–60 s and passes a cancelled-on-timeout `ct`
  (`AdminOperationsActor.cs:284-291`). Probes MUST honour it and MUST NOT mutate state (read-only handshakes).
- **A proven skip-gated E2E harness exists** (`DriverTestConnectE2eTests`) targeting the live Modbus sim with
  happy / wrong-port / black-hole scenarios, auto-skipping when the fixture is unreachable. The dev-rig sims
  (Modbus `:5020`, AbCip `:44818`, S7 `:1102`, opc-plc `:50000`) and the mxaccessgw (`10.100.0.48:5120`) are
  reachable from the dev Mac, so 5 of the 8 are live-verifiable agent-side.

## Architecture

**Per-probe, no shared scaffold.** Each probe stays self-contained in its own driver project (matches the
existing intentional copy-paste style, keeps all 8 projects disjoint → parallelizable like Phase 4, and avoids
adding socket/handshake logic to the `Core.Abstractions` contracts project). Each in-scope probe keeps its TCP
preflight and **adds one handshake step**, reusing the driver's own client primitive.

**New three-way result contract** (the operator value — message templates kept consistent across all 8):

| Outcome | Result |
|---|---|
| TCP connect fails | `Ok=false` · `"Connect failed: {SocketError}"` *(unchanged)* |
| TCP ok **+ handshake ok** | `Ok=true` · latency · descriptive msg (e.g. `"Modbus FC03 OK"`, `"OPC UA: N endpoint(s)"`, `"S7 connected (CPU …)"`, `"CIP session OK"`, `"ADS state: Run"`, `"gateway gRPC OK"`) |
| TCP ok **but handshake rejected** | `Ok=false` · `"Reachable at {host}:{port} but {proto} handshake failed: {detail}"` ← **the new behavior** |
| timeout | `Ok=false` · `"Probe timed out after {n}s."` *(unchanged)* |

`IDriverProbe` / `DriverProbeResult` are **unchanged** — no Commons / Core contract touch, no DI change
(the 8 probes are already registered in `DriverFactoryBootstrap.AddOtOpcUaDriverProbes`).

## Per-driver handshake + degradation

### Tier A — real handshake, live-verifiable on the rig (agent-driven)
1. **Modbus** — `ConnectAsync` then `SendAsync` one **FC03** (Read Holding Registers, qty 1 @ addr 0, unit
   from config/default 1). Any well-formed MBAP reply that echoes the TxId with protocol-id 0 — **including a
   Modbus exception PDU (0x83…)** — proves a real Modbus device ⇒ `Ok`. A malformed/non-MBAP reply or silence
   ⇒ handshake-fail. Sim `:5020`.
2. **OpcUaClient** — `DiscoveryClient.GetEndpointsAsync` (no session, no app-cert, no auth). ≥1 endpoint ⇒
   `Ok` (`"OPC UA: N endpoint(s)"`); a non-OPC-UA TCP server throws/times out ⇒ handshake-fail. opc-plc `:50000`.
3. **S7** — `new Plc(...).OpenAsync(ct)` with `ReadTimeout` set first (mirror `S7Driver.cs:164`), check
   `IsConnected`, `Close`. Wrong rack/slot or non-S7 server ⇒ `OpenAsync` throws ⇒ handshake-fail. python-snap7
   `:1102`.
4. **AbCip** — create a `libplctag` Tag for the first configured tag path (else a benign probe name) and
   `InitializeAsync`. Session opens ⇒ `Ok`; a **CIP-level** error (tag-not-found / bad-path) **still counts as
   reachable** (the controller answered CIP); a session/ForwardOpen/connect error ⇒ handshake-fail. CIP sim `:44818`.
5. **Galaxy** — build the `MxGateway.Client` gRPC channel (honour the config's cleartext/TLS) and issue one
   lightweight unary call. **The probe does NOT resolve `secretref:` secrets** — it sends whatever key string is
   in the transient config (possibly empty/unresolved). An `OK` reply ⇒ `Ok`; an **`Unauthenticated` /
   `PermissionDenied`** reply **also ⇒ `Ok`** ("gateway reachable & speaking gRPC; auth not checked") because it
   proves a live mxgw server; `Unavailable` / transport error ⇒ handshake-fail. Gateway `10.100.0.48:5120`.

### Tier B — real handshake, unit-proven only (no rig target → live-verify deferred, honestly recorded)
6. **AbLegacy** — same `libplctag` Init handshake as AbCip but the PCCC protocol family (verified-by-proxy via
   AbCip's identical code path). No PLC5/SLC sim on the rig.
7. **TwinCAT** — `AdsClient.Connect` + `ReadStateAsync` ⇒ `Ok` with the ADS state (Run/Config/Stop). An ADS
   **route-table** rejection is a *true* RED (the driver also cannot function without an authorized route — the
   message says so: *"check the target's ADS route table authorizes this host"*). **Degrade guard:** if
   `AdsClient` cannot construct/connect headless (managed AMS router unavailable), catch and fall back to the
   TCP-preflight result with a *"ADS handshake unavailable on this host — TCP reachability only"* note — never
   worse than today. No TwinCAT target on the rig.
8. **FOCAS** — attempt `cnc_allclibhndl3` via the existing wire P/Invoke. **Degrade guard:** the FWLIB native
   lib is absent on the dev box / Linux containers (`UnimplementedFocasClientFactory` gates the driver), so the
   call throws `DllNotFoundException` / `NotSupportedException` ⇒ catch and fall back to the TCP-preflight result
   with a *"FOCAS handshake unavailable on this host (FWLIB absent) — TCP reachability only"* note. A real
   handshake runs only on a Windows host with FWLIB + a reachable CNC. No CNC on the rig.

**Degradation principle:** the three Tier-B handshakes must NEVER produce a result worse than today's TCP-only
probe. A genuine protocol rejection from a reachable device is a correct RED; an *environmental inability to run
the handshake at all* (no FWLIB, no managed router) degrades to the existing TCP-reachability message.

## Testing & verification

- **Unit (per probe, TDD red→green, xUnit + Shouldly):** in-process `TcpListener` drives — (a) invalid/empty
  config, (b) unreachable → `Connect failed`, (c) **TCP-accepts-then-closes / garbage → handshake-fail** (the
  key new path — cleanly assertable for Modbus via a canned-MBAP server; loopback-accept for the rest), plus
  Modbus's canned-MBAP **happy** path and FOCAS's **degrade** path (DllNotFound on the dev box is the actual CI
  behavior, so it is directly testable). Galaxy's `Unauthenticated⇒Ok` is testable against a tiny in-process
  gRPC server or via the live gateway.
- **Live `/run` (agent-driven, extends `DriverTestConnectE2eTests`, skip-gated):** Modbus, OpcUaClient, S7,
  AbCip against the rig sims; Galaxy against `10.100.0.48:5120`. Each: green vs the live sim, RED vs wrong port
  / non-protocol server, timeout vs a black-hole IP. AbLegacy / TwinCAT / FOCAS live-verify is **honestly
  deferred** (no PLC5/SLC sim, no ADS target, no CNC+FWLIB) — unit-proven + degrade-guarded.
- `dotnet build` clean (production projects are `TreatWarningsAsErrors`) + full `dotnet test` green before merge.
- Final integration review (the three degrade guards + the consistent message contract + no-regression-vs-TCP).
- **No bUnit** — no Razor change (the `DriverTestConnectButton` already renders whatever the probe returns).

## Out of scope / not touched

- Historian.Wonderware probe (already a real Hello/HelloAck handshake).
- `IDriverProbe` / `DriverProbeResult` contract, DI registration, the AdminUI button/Razor, the persisted
  `DriverInstance` row (probes run against transient form config only).
- Plan `2026-05-28-adminui-driver-pages` Phase 9 typed **address pickers** and Phase 10 driver-page E2E — those
  are Phase 6 (AdminUI), not this phase.

## Hard constraints (carried from the parent roadmap)

- **NO Configuration entity / EF migration.** No contract change (`IDriverProbe`/`DriverProbeResult` frozen).
- Stage by path — never `git add .`. Never stage `sql_login.txt`, `src/Server/.../Host/pki/`, `pending.md`,
  `current.md`, `docker-dev/docker-compose.yml`, `stillpending.md`. **Never echo or commit the gateway API key**
  (the Galaxy live-verify sources it without echoing, per the established recipe). No force-push, no `--no-verify`.
- Finish = merge to master + push.