Merge branch 'master' into worktree-agent-a720278a57ae41792
Claude-Session: https://claude.ai/code/session_01GT67AD99zQQqpLCVm3p7xk
This commit is contained in:
@@ -271,6 +271,18 @@ item. A `CONDITION` observation's value is taken from its **element name**
|
||||
condition element normalises onto the same `UNAVAILABLE` sentinel as every
|
||||
other category so one comparison covers all three.
|
||||
|
||||
**An empty value is not `UNAVAILABLE` (#824, owner decision 2026-11-11 — Java parity).** A
|
||||
genuinely empty observation (`<Program …></Program>`, `<Program …/>`, or whitespace-only text,
|
||||
which the parser trims to `""`) on a **string-typed** item (`String`/`Reference`, or an unauthored
|
||||
item, which coerces as String) is served **Good `""`** — an Agent can legitimately report a blank
|
||||
`Program`, `Block` or `Message`. On any **non-string** item (numeric, `Boolean`, `DateTime`, a
|
||||
`TIME_SERIES` array) `""` cannot be a value, so it stays **`BadNoCommunication`** with a null value
|
||||
— deliberately not `BadTypeMismatch`, which would tell the operator the Agent sent text of the wrong
|
||||
type and point them at the tag's authored data type; the Agent sent no value at all. Only the literal
|
||||
`UNAVAILABLE` sentinel is the "no value" statement on a string item. Before #824 every empty value
|
||||
was `BadNoCommunication`. A `DATA_SET`/`TABLE`-shaped observation is unaffected (its entry-less
|
||||
form is still Good `{}`; non-`<Entry>` children are still `BadNotSupported`).
|
||||
|
||||
**Integer-valued decimals are served on integral tags (#804).** Agents format integer-valued items as
|
||||
`42.000000`; an `Int*`/`UInt*` tag accepts any decimal whose value *is* an integer in range (`42.000000` → `42`,
|
||||
`1.5e3` → `1500`) losslessly. A real fraction stays `BadOutOfRange` — deliberately stricter than the Java
|
||||
@@ -296,7 +308,7 @@ limitations 4; a probe that does declare one yields a fixed `ArrayDim`).
|
||||
Parsing: the observation text is split on any whitespace, each token parsed
|
||||
invariant-culture. The result is **all-or-nothing** — one non-numeric /
|
||||
non-finite token is `BadTypeMismatch`, a literal `UNAVAILABLE` token or an
|
||||
empty body is `BadNoCommunication`, and a count that disagrees with the
|
||||
empty body is `BadNoCommunication` (an array is non-string, so #824's Good `""` never applies), and a count that disagrees with the
|
||||
observation's own `sampleCount` attribute (or a fixed `ArrayDim`) is
|
||||
`BadDecodingError`. A partial vector is never served as Good. Only a
|
||||
**Float64** array tag is served; any other declared element type stays
|
||||
@@ -677,7 +689,7 @@ deliberately different, kept.
|
||||
| Type inference SAMPLE→Double, numeric EVENT→Int64, else String (`MTConnectTypes`) | covered, **.NET exceeds** (TIME_SERIES → `double[]`, separator-insensitive types) | `MTConnectDataTypeInference` · `MTConnectDataTypeInferenceTests` |
|
||||
| UNAVAILABLE → `Bad_NoCommunication`, null value, source timestamp kept (`MTConnectValues`) | covered | `MTConnectObservationIndex.BuildSnapshot` · `Unavailable_observation_maps_to_BadNoCommunication_with_null_value`, `Unavailable_observation_keeps_the_agent_source_timestamp` |
|
||||
| UNAVAILABLE matched case-insensitively | divergence (kept) | ordinal match on the parser-normalised token, so a free-text EVENT reading "Unavailable" stays a value · `Unavailable_sentinel_is_matched_on_the_exact_literal` |
|
||||
| Blank text on a String node is a Good empty string | divergence (kept) | empty text is `BadNoCommunication` (an empty element is not an empty-string value) |
|
||||
| Blank text on a String node is a Good empty string | **covered** (was a divergence until #824, owner decision 2026-11-11) | `BuildSnapshot` serves Good `""` on a string-typed or unauthored item; a non-string item stays `BadNoCommunication` (Java has no typed node to refuse `""` on); `UNAVAILABLE` unchanged · `Empty_observation_value_on_a_string_item_is_a_Good_empty_string`, `A_parsed_empty_event_on_a_string_item_is_a_Good_empty_string`, controls `Empty_observation_value_on_a_non_string_item_stays_BadNoCommunication`, `Unavailable_on_a_string_item_is_still_BadNoCommunication` |
|
||||
| No fabricated numbers: narrow-integer range checks, float overflow ≠ Infinity, NaN/Infinity refused (`MTConnectValues.coerce`) | covered for integers; **gap → closed** for floats (`1e400`, `NaN`, `Infinity`, `1e39` on Float32 were served Good) | `Coerce`, `NonFiniteStatus` · `A_non_finite_float_is_never_served_as_good` |
|
||||
| Integer-valued decimal (`42.000000`) on an integral node | **gap → closed** (was `BadOutOfRange`) — lossless only; a real fraction is still refused, never truncated (Java truncates) | `TryIntegral` · `An_integer_valued_decimal_converts_losslessly`, control `A_fraction_or_an_out_of_range_decimal_stays_out_of_range` |
|
||||
| Source timestamps preserved; a non-Zulu offset normalised | covered | `ReadTimestampUtc` · `A_timestamp_with_a_non_zulu_offset_is_normalized_to_the_same_utc_instant` |
|
||||
@@ -932,7 +944,7 @@ for anything beyond values-and-conditions.
|
||||
- **Unit tests** — `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/`
|
||||
(canned-XML fixtures, no network) — 714/714 at #804 (2026-11-10). `MTConnectJavaParityTests` holds the #804 gap tests and the ported Java regression cases (see [Java reference parity](#java-reference-parity-804)). Covers
|
||||
discovery tree shape, `MTConnectDataTypeInference`, observation indexing,
|
||||
`UNAVAILABLE` → `BadNoCommunication`, CONDITION state-word mapping,
|
||||
`UNAVAILABLE` → `BadNoCommunication` (an empty string-typed value is Good `""`, #824), CONDITION state-word mapping,
|
||||
multipart chunk framing, and ring-buffer re-baseline paging (both the
|
||||
sequence-gap and the `OUT_OF_RANGE` legs). The write path adds
|
||||
`MTConnectAgentClientWriteTests` (`9f17d7ef` — verb, URL, agent-error-in-200
|
||||
|
||||
@@ -189,8 +189,16 @@ Consequences:
|
||||
- Test Connect (`OpcUaClientDriverProbe`) only calls GetEndpoints on an unsecured discovery channel — no session, so no
|
||||
certificate or host-name check.
|
||||
|
||||
**Policy: `certificateValidation.validateServerHostName`** (driver JSON; AdminUI driver form "Server host-name check";
|
||||
the browser reads the same JSON):
|
||||
**Decision (#837, owner, 2026-11-11): the check stays OPT-IN — unset means off, and it will not become a default.**
|
||||
Turning it on by default would refuse every NAT / port-published / connect-by-IP endpoint whose certificate does not
|
||||
list that exact host, and every link-local IPv6 endpoint, on upgrade; and because the match is loose (first label) it
|
||||
would not deliver the identity guarantee a default implies. Operators enable it per driver where trust is CA-issued
|
||||
and certificate names are fully-qualified and site-unique. The AdminUI shows the toggle in the driver form's
|
||||
**Security** panel (beside mode/policy) as "Server certificate host-name check", with help text covering the NAT/IP
|
||||
caveat, IPv6 zone ids and the loose first-label match.
|
||||
|
||||
**Policy: `certificateValidation.validateServerHostName`** (driver JSON; AdminUI driver form, Security panel,
|
||||
"Server certificate host-name check"; the browser reads the same JSON):
|
||||
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
|
||||
@@ -46,7 +46,7 @@ with a human-readable explanation rather than a false-green TCP-open tick.
|
||||
| **S7** | `Plc.OpenAsync` (COTP CR/CC + S7 setup-communication), check `IsConnected`, then `Close`. Wrong rack/slot or a non-S7 server causes `OpenAsync` to throw → handshake fail. | `"S7 connected (CPU …)"` | `10.100.0.35:1102` (python-snap7 sim) |
|
||||
| **AbCip** | `libplctag` Tag `InitializeAsync` (EIP session + CIP Forward Open). A CIP-level error such as tag-not-found still proves the controller answered CIP → `Ok`. A session/ForwardOpen/connect error → handshake fail. | `"CIP session OK"` | `10.100.0.35:44818` (CIP sim) |
|
||||
| **AbLegacy** | Same `libplctag` `InitializeAsync` handshake as AbCip, PCCC protocol family. | `"CIP session OK"` (PCCC family) | Deferred — no PLC5/SLC sim |
|
||||
| **TwinCAT** | `AdsClient.Connect` + `ReadStateAsync`. See [degrade semantics](#twincat-degrade) below. | `"ADS state: {state}"` | Deferred — no ADS target |
|
||||
| **TwinCAT** | `AdsClient.Connect` + `ReadStateAsync` through the **local AMS router** — no TCP pre-check. See [TwinCAT: no TCP pre-check](#twincat-no-tcp-pre-check) below. | `"ADS state: {state}"` | Z35474 (production TC3 press, read-only, via an in-process TcpRouter) |
|
||||
| **FOCAS** | `cnc_allclibhndl3` via a direct `DllImport("fwlib32")` in the probe. See [degrade semantics](#focas-degrade) below. | `"FOCAS handle OK"` | Deferred — no CNC + FWLIB |
|
||||
| **Galaxy** | gRPC unary call to `GalaxyRepository.TestConnection` on the configured mxaccessgw endpoint. See [auth-rejection rule](#galaxy-auth-rejection) below. | `"gateway gRPC OK"` | `http://10.100.0.48:5120` (mxaccessgw) |
|
||||
| **Heidenhain** | LSV2 `A_LG INSPECT` (password resolved from its `secret:`/`env:` reference) + `R_VR`, through the same read-only allowlist as the driver; a refusal or malformed version record → fail. No logout — the socket close ends the session. | `"LSV2 INSPECT session OK at host:port: <model> NC <version>"` | Deferred — no LSV2 control; simulator-proven |
|
||||
@@ -61,29 +61,36 @@ backend is now the external HistorianGateway (a gRPC client package, not a probe
|
||||
|
||||
## Degrade semantics
|
||||
|
||||
Three drivers have environmental constraints that can prevent the handshake
|
||||
Some drivers have environmental constraints that can prevent the handshake
|
||||
from running on certain hosts. The **degradation principle** is: the probe
|
||||
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 inability to
|
||||
*run* the handshake at all (no FWLIB, no managed router) degrades to the
|
||||
existing TCP-reachability message — still a green tick but annotated.
|
||||
*run* the handshake at all (no FWLIB) degrades to the
|
||||
existing TCP-reachability message — still a green tick but annotated. TwinCAT
|
||||
no longer degrades (see below).
|
||||
|
||||
### TwinCAT degrade
|
||||
### TwinCAT: no TCP pre-check
|
||||
|
||||
Where the handshake is available:
|
||||
TwinCAT is the exception to the "TCP connect fails" row above: it opens **no socket of its own**
|
||||
(#863). The driver has no IP field — an AMS Net ID is a Beckhoff identifier the AMS router maps to a
|
||||
host through its route table, and the AMS port (801/851) is not a TCP port. The probe therefore takes
|
||||
exactly the driver's path (`AdsTwinCATClient.ConnectAsync`): `AdsClient.Connect(netId, port)` through
|
||||
the local AMS router (TwinCAT XAR, or `Beckhoff.TwinCAT.Ads.TcpRouter` hosted in-process), then one
|
||||
read-only `ReadStateAsync`, all inside the probe budget. Until #863 a first-phase check dialled the Net
|
||||
ID's first four octets as an IPv4 address on the AMS port — for Z35474 (`5.118.56.93.1.1`) an
|
||||
unrelated public host — so Test Connect timed out against every real runtime.
|
||||
|
||||
- `AdsClient.Connect(netId, port)` + `ReadStateAsync` → `Ok=true`,
|
||||
`"ADS state: {state}"` (Run / Config / Stop).
|
||||
- An ADS **route-table rejection** from a reachable ADS router is a **true RED**:
|
||||
`"Reachable at {host}:{port} but ADS handshake failed: {detail} — check the
|
||||
target's ADS route table authorizes this host"`. This is the correct result:
|
||||
the driver would also be unable to function without an authorized route.
|
||||
| Outcome | `Ok` | Message |
|
||||
|---------|------|---------|
|
||||
| ReadState succeeds | `true` | `"ADS state: {state}"` (Run / Config / Stop) |
|
||||
| No local AMS router (Beckhoff "Check for a running TwinCAT router instance!", `ClientPortNotOpen`, router not active, ADS client cannot load) | `false` | `"No local AMS router on this host — start TwinCAT XAR or host the Beckhoff TcpRouter; the target was not contacted (…)"` |
|
||||
| Router answered but cannot reach the target (`TargetMachineNotFound`, `TargetPortNotFound`, port/access refused, host unreachable) | `false` | `"No route to {netId}:{port} or target unreachable: {code} — check the local AMS router has a route …"` |
|
||||
| Sync/device timeout code, or the budget expired | `false` | `"Probe timed out after {n}s waiting for ADS state from {netId}:{port} …"` |
|
||||
| Any other ADS error | `false` | `"ADS handshake with {netId}:{port} failed: {code}"` |
|
||||
|
||||
Where the handshake is unavailable (headless server, no TwinCAT runtime, the
|
||||
managed AMS router cannot start):
|
||||
|
||||
- Probe degrades to TCP-reachability: `Ok=true`,
|
||||
`"(ADS handshake unavailable on this host — TCP reachability only)"`.
|
||||
There is **no degrade-to-green** any more: with no TCP check, a host that cannot run the handshake
|
||||
has contacted nothing, so it reports the missing router rather than a green tick. A stock admin node
|
||||
has no AMS router, so TwinCAT Test Connect is red there by design — the driver needs the same router.
|
||||
|
||||
### FOCAS degrade
|
||||
|
||||
|
||||
Reference in New Issue
Block a user