dohertj2/lmxopcua
1
0
Fork 0
Code Issues 32 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(code-review): close all 8 open Mqtt.Browser + Mqtt.Contracts findings

Browse Source 
Browser-002/-003/-004 fixed and -005 resolved as a documented constants change
(eddf5f57); Contracts-004/-005/-006/-007 fixed (93f70504). Both module headers
drop to 0 open findings. Each resolution records the disposition, the RED
evidence, and the deviations from the recommendation where one was taken.
This commit is contained in:
Joseph Doherty
2026-08-10 08:22:47 -04:00
parent 93f70504bd
commit 2dc2075d05
2 changed files with 185 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
code-reviews/Driver.Mqtt.Contracts/findings.md
+113 -9
View File
@@ -7,7 +7,7 @@
| Review date | 2026-08-10 |
| Commit reviewed | `b990adae` |
| Status | Reviewed |
| Open findings | 4 |
| Open findings | 0 |
## Scope
@@ -162,7 +162,7 @@ deliberately excludes `metricName`); pinned by
| Severity | Low |
| Category | Documentation & comments |
| Location | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts/MqttTagDefinitionFactory.cs:124`, `:234`, `:476` |
| Status | Open |
| Status | Resolved |
**Description:** `retainSeed` is the one behavioural key still read leniently.
`ReadBoolOrDefault` returns the default for any non-boolean JSON value, so
@@ -186,7 +186,36 @@ so both gates stay in step; or (b) add an `Inspect` advisory naming the key and
default; or (c) at minimum document the deliberate exception on `ReadBoolOrDefault`.
Option (b) is lowest-risk — it changes no verdict.
**Resolution:** _(open)_
**Resolution (2026-08-10):** Fixed in `93f70504` — option (a), the strict read, chosen over the
"lowest-risk" advisory. The #549–#559 arc's settled contract is that **the parse is the accept
authority** and advisories ride blobs the parse has already ACCEPTED; an advisory here would have
left the driver still serving the inverse of what was authored, and the review's own reason for
recording rather than fixing ("the two surfaces are currently consistent") is satisfied without a
hand-mirrored rule — see below. Every sibling behavioural key in this factory (`payloadFormat`,
`dataType`, `qos`) is already strict, and `retainSeed` is the sharper case of the two: a defaulted
`qos` is a weaker delivery guarantee, whereas a defaulted `retainSeed` is the **inverse** of the
authored intent whenever the author wrote `false` — the only value worth writing at all.
Both mappers now read it through a new `TryReadBoolStrict`, mirroring `TryReadQosStrict`'s
absent / valid / present-but-invalid split, and `DescribeRejection` gained a matching
`DescribeInvalidBool` branch (a rejection, never an advisory: unlike `payloadFormat`, both mappers
read the key, so it can never land on an accepted blob).
**No second gate was bolted on outside Parse, and `MqttTagConfigModel` needed no mirrored rule.**
Its `Validate()` already ends in `TagConfigParseGate.Describe`, which asks *this* parse about the
blob the model was loaded from and words the refusal from *this* `Inspect` — so tightening the
factory tightened the authoring surface in the same change, with no drift surface created. The
model's `RetainSeed` doc now records that its own load stays lenient (a non-boolean reads as
"unset") and why that is safe.
Pinned by `MqttTagDefinitionFactoryTests.FromTagConfig_MalformedRetainSeed_RejectsStrict` /
`FromSparkplugTagConfig_MalformedRetainSeed_RejectsStrict` (over `"false"`, `"true"`, `0`, `1`,
`"yes"`, `null`), `Inspect_MalformedRetainSeed_Warns`, and — as the falsification control that a
reader simply refusing every blob carrying the key would fail —
`FromTagConfig_WellFormedRetainSeed_IsStillHonoured`. 11 RED before the fix. The
authoring↔deploy parity is pinned separately, on the corpus that would catch a future divergence:
`TagConfigNonEnumParityTests.Mqtt_refuses_a_retainSeed_its_reader_refuses` and its paired
`Mqtt_accepts_a_retainSeed_its_reader_accepts`.
### Driver.Mqtt.Contracts-005
@@ -195,7 +224,7 @@ Option (b) is lowest-risk — it changes no verdict.
| Severity | Low |
| Category | Testing coverage |
| Location | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts/MqttDriverOptions.cs:25`, `:71`, `:75`, `:79`, `:83`, `:99`, `:229` |
| Status | Open |
| Status | Resolved |
**Description:** `MqttDriverOptions` / `MqttPlainOptions` carry seven
`System.ComponentModel.DataAnnotations` `[Range]` attributes and **nothing ever runs them**.
@@ -221,7 +250,35 @@ checks the probe and the AdminUI form already carry. If neither, note on each at
that it is descriptive. The enforcing consumer (`MqttSubscriptionManager.BuildFilters`)
lives in `Driver.Mqtt`, outside this module.
**Resolution:** _(open)_
**Resolution (2026-08-10):** Fixed in `93f70504` — the attributes were **deleted**, not wired up,
and the one consequence that actually escaped was closed at the enforcing consumer.
**Wiring them would have broken deliberate behaviour**, which settles the "either/or" the
recommendation leaves open. Two of the seven *contradicted* the real authority: `[Range(1, …)]`
on `KeepAliveSeconds` forbids the **zero** `MqttDriver.Normalize` explicitly admits ("zero
keep-alive is legal MQTT; only a negative one is nonsense"), and the same attribute on
`MaxPayloadBytes` forbids the non-positive value this type's own remarks document as "falls back
to the driver's own 1 MiB default". Running the annotations would have refused two configurations
the driver is written to accept — the "two disagreeing authorities" outcome, arrived at by
enforcement rather than by neglect. So the bounds stay where they are applied
(`MqttDriver.Normalize`, `MqttSubscriptionManager`'s constructor, `MqttConnection.NextBackoff`),
each property names its own, and the type remarks record why there are no `DataAnnotations` here
and why adding one would be documentation that reads like enforcement.
**`MqttPlainOptions.DefaultQos` — the escape the entry identifies — is now clamped** in
`MqttSubscriptionManager`'s constructor, the same single enforcement point that already bounds
`MaxPayloadBytes`. Clamp rather than fall back to the default, deliberately: it matches what
`MqttDriverFormModel.Normalize` already persists (`Math.Clamp(DefaultQos, 0, 2)`), so the
authoring surface and the driver cannot reach different answers for one authored number. Pinned
by `MqttSubscriptionManagerTests.DefaultQos_OutsideTheLegalRange_NeverReachesTheSubscribe`, which
asserts the QoS on the **fake transport's actual SUBSCRIBE** rather than on a property — `5 ⇒ 2`
and `-1 ⇒ 0` were RED, with `0 ⇒ 0` / `2 ⇒ 2` green throughout as the controls.
Scope note: this closes the MQTT half only. The entry's observation that `[Range]` on driver
options is a **repo-wide** convention (`ModbusDriverOptions`, `S7DriverOptions`) still stands, and
those attributes are still unenforced — this change does not touch them, and the evidence above
argues the fleet-wide answer is deletion plus real bounds at each use site rather than a
composition-seam `Validator.TryValidateObject`.
### Driver.Mqtt.Contracts-006
@@ -230,7 +287,7 @@ lives in `Driver.Mqtt`, outside this module.
| Severity | Low |
| Category | Correctness & logic bugs |
| Location | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts/MqttWriteEncoder.cs:281` |
| Status | Open |
| Status | Resolved |
**Description:** Two edge cases in the `DriverDataType.DateTime` write arm. First,
`(ulong)…ToUnixTimeMilliseconds()` on a pre-1970 value wraps a negative `long` into a very
@@ -250,7 +307,27 @@ negative, and convert with an explicit `DateTime.SpecifyKind(…, DateTimeKind.U
`Unspecified` input (or refuse it, which is more in keeping with the file's own posture).
Add a test for each.
**Resolution:** _(open)_
**Resolution (2026-08-10):** Both fixed in `93f70504`.
The epoch bound: `ToUnixTimeMilliseconds()` is now taken into a `long`, and a negative one returns
`ValueNotRepresentable` before anything is written to the metric — Sparkplug's `DateTime` is an
*unsigned* ms-since-epoch, so a pre-1970 instant has no representation at all and the surrounding
"refused, never coerced" rule applies unchanged.
The kind: an `Unspecified` input is converted with `DateTime.SpecifyKind(…, DateTimeKind.Utc)`
rather than `ToUniversalTime()`. The entry offers refusal as "more in keeping with the file's own
posture", and it was not taken — `Convert.ToDateTime("2026-08-10T12:00:00")`, an ordinary authored
string, produces exactly this kind, so refusing would reject a perfectly reasonable write to fix a
determinism problem that reading it as UTC also fixes.
Pinned by `MqttWriteEncoderTests.A_pre_epoch_date_time_is_refused_rather_than_wrapped` (three
instants, incl. `DateTime.MinValue`) with `A_post_epoch_date_time_still_encodes_to_its_unix_milliseconds`
as the falsification control — a guard that refused *every* `DateTime` would satisfy the theory
alone — and `An_unspecified_kind_date_time_encodes_as_utc_not_as_node_local_time`, which asserts
the Unspecified and the same-instant-UTC encodings are byte-identical. ⚠️ That last one can only
go red on a host whose local timezone is not UTC (it was RED here under both `EDT` and
`TZ=Asia/Tokyo`, and is green under `TZ=UTC` either way) — which is the defect itself, and the
reason it is written as an equality between two encodings rather than against a hard-coded number.
### Driver.Mqtt.Contracts-007
@@ -259,7 +336,7 @@ Add a test for each.
| Severity | Low |
| Category | Error handling & resilience |
| Location | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Contracts/Sparkplug/SparkplugTopic.cs:202`, `:232` |
| Status | Open |
| Status | Resolved |
**Description:** `SparkplugTopic` validates asymmetrically. `TryParse` enforces
`IsValidSegment` (non-empty, no `+`/`#`) on every segment it reads, but `Format` and
@@ -279,4 +356,31 @@ succeeded, so the encoder's own guards must stay — `TryEncode` returns an erro
throwing, and that contract must not change. A round-trip property test
(`Parse(t.ToTopicString()) == t` over the parser's own accepted corpus) would pin it.
**Resolution:** _(open)_
**Resolution (2026-08-10):** Fixed in `93f70504` — `Format` and `FormatState` now apply the
parser's own `IsValidSegment` to `groupId` / `edgeNodeId` / `deviceId` / `hostId` through a shared
`ThrowIfNotASegment`, throwing `ArgumentException` as the existing contract does.
One deliberate addition beyond the recommendation's literal wording: the format-side check also
rejects **`/`**. `IsValidSegment` has no reason to test for one — `TryParse` has already split on
it — but on this side it is the difference between one id and two, and it is precisely the shape
the entry describes as "silently adds a segment". Without it the round-trip property the
recommendation asks for would not actually be total, since such a topic re-parses to nothing.
The caution the entry raises is respected: `MqttWriteEncoder`'s own guards stay, so `TryEncode`
still *returns* `NoWriteDestination` for these ids rather than propagating a throw, and that
contract is unchanged. The one production caller that can now throw where it previously produced
a malformed topic is `SparkplugPrimaryHost.StateTopic` (a wildcard `hostId`); it is reached only
from `MqttDriver.StartPrimaryHostAsync`, which is wrapped in a catch that logs a warning and
leaves ingest untouched by design — so the effect is "the host claim declines with a reason"
instead of "publish a protocol violation and lose the connection".
Pinned by `SparkplugTopicTests.Format_SegmentThatIsNotALegalTopicSegment_Throws` (9 cases:
`+`/`#` in each id, `/` in group and device, and an empty `deviceId`) and
`FormatState_HostIdThatIsNotALegalTopicSegment_Throws` — 9 RED before the fix — with
`Format_UnusualButLegalSegments_AreStillAccepted` as the falsification control (a Sparkplug id is
otherwise opaque: spaces, dots, dashes and accents are all legitimate, and a guard that refused
everything would satisfy the throw theories). The closure property is
`Format_Output_AlwaysReParsesToTheSameInstance`, asserted over the **formatter's own output**
across every non-STATE message type plus `FormatState`, rather than over a hand-written topic
list, so a future formatting change cannot leave the corpus describing a shape the type no longer
emits.