826312befe
Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns, normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping the rationale they annotated. Comment-only: comment-stripped sources are identical to the parent commit.
250 lines
13 KiB
C#
250 lines
13 KiB
C#
using System.Text;
|
||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||
|
||
namespace ZB.MOM.WW.OtOpcUa.Driver.Mqtt;
|
||
|
||
/// <summary>
|
||
/// MQTT / Sparkplug B driver configuration. Bound from <c>DriverConfig</c> JSON at
|
||
/// driver-host registration time. Models the settings documented in
|
||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// A record (not a plain class) so a future secret-resolution seam can produce a
|
||
/// credential-resolved copy with a <c>with</c> expression — mirrors
|
||
/// <c>OpcUaClientDriverOptions</c>. <see cref="Mode"/> selects the ingest shape;
|
||
/// <see cref="Sparkplug"/> and <see cref="Plain"/> are nullable sub-objects — only the one
|
||
/// matching <see cref="Mode"/> is populated.
|
||
/// <para>
|
||
/// ⚠️ <b>There are deliberately no <c>DataAnnotations</c> range attributes on this DTO, and adding
|
||
/// any would be documentation that reads like enforcement.</b> The options are bound by
|
||
/// <c>JsonSerializer.Deserialize</c> through <see cref="MqttJson.Options"/>, never by
|
||
/// <c>IOptions</c> + <c>ValidateDataAnnotations</c>, and nothing in the four MQTT projects calls
|
||
/// <c>Validator.TryValidateObject</c> — so the seven <c>[Range]</c>s this type used to carry never
|
||
/// ran once. Worse, two of them <i>contradicted</i> the real authority: <c>[Range(1, …)]</c> on
|
||
/// <see cref="KeepAliveSeconds"/> forbade the zero that <c>MqttDriver.Normalize</c> deliberately
|
||
/// admits as legal MQTT, and the same on <see cref="MaxPayloadBytes"/> forbade the non-positive
|
||
/// value this type's own remarks document as "falls back to the 1 MiB default". Wiring them up
|
||
/// would therefore have broken deliberate behaviour, so the bounds live where they are actually
|
||
/// applied — <c>MqttDriver.Normalize</c>, <c>MqttSubscriptionManager</c>'s constructor and
|
||
/// <c>MqttConnection.NextBackoff</c> — and each property below names its own.
|
||
/// </para>
|
||
/// </remarks>
|
||
public sealed record MqttDriverOptions
|
||
{
|
||
/// <summary>Broker hostname or IP address.</summary>
|
||
public string Host { get; init; } = "localhost";
|
||
|
||
/// <summary>
|
||
/// Broker TCP port. Range-checked by <c>MqttDriverProbe</c> and the AdminUI driver form; there is
|
||
/// no <c>[Range]</c> attribute here because nothing would ever run it — see the type remarks.
|
||
/// </summary>
|
||
public int Port { get; init; } = 8883;
|
||
|
||
/// <summary>
|
||
/// MQTT client identifier sent at CONNECT. Leave unset to let the driver generate one
|
||
/// (a stable per-instance id is recommended so broker-side ACLs / session state persist
|
||
/// across reconnects).
|
||
/// </summary>
|
||
public string? ClientId { get; init; }
|
||
|
||
/// <summary>
|
||
/// When <c>true</c>, connect over TLS. Default <c>true</c> — this driver never ships an
|
||
/// anonymous/plaintext-by-default posture; a deployment must opt into <c>false</c> for an
|
||
/// on-prem/dev broker with no TLS listener.
|
||
/// </summary>
|
||
public bool UseTls { get; init; } = true;
|
||
|
||
/// <summary>
|
||
/// When <c>true</c>, accept any self-signed / untrusted broker certificate. Dev/on-prem
|
||
/// escape hatch only — mirrors the <c>ServerHistorian</c> TLS knobs. Must stay
|
||
/// <c>false</c> in production so MITM attacks against the broker connection fail closed.
|
||
/// </summary>
|
||
public bool AllowUntrustedServerCertificate { get; init; } = false;
|
||
|
||
/// <summary>
|
||
/// PEM CA file pinning the broker's TLS chain. <c>null</c>/empty uses the OS trust
|
||
/// store.
|
||
/// </summary>
|
||
public string? CaCertificatePath { get; init; }
|
||
|
||
/// <summary>Username for broker authentication. <c>null</c> connects without a username.</summary>
|
||
public string? Username { get; init; }
|
||
|
||
/// <summary>
|
||
/// Password for broker authentication. Blank in committed JSON — supply via env, never
|
||
/// commit or log.
|
||
/// </summary>
|
||
public string? Password { get; init; } = "";
|
||
|
||
/// <summary>MQTT protocol version to negotiate at CONNECT.</summary>
|
||
public MqttProtocolVersion ProtocolVersion { get; init; } = MqttProtocolVersion.V500;
|
||
|
||
/// <summary>Whether to request a clean session (v3.1.1) / clean start (v5.0) at CONNECT.</summary>
|
||
public bool CleanSession { get; init; } = true;
|
||
|
||
/// <summary>
|
||
/// Keep-alive interval sent at CONNECT. Bounded by <c>MqttDriver.Normalize</c>, which admits
|
||
/// <b>zero</b> — legal MQTT for "no keep-alive" — and only replaces a negative value.
|
||
/// </summary>
|
||
public int KeepAliveSeconds { get; init; } = 30;
|
||
|
||
/// <summary>
|
||
/// Bounded connect deadline (see design §8) — the driver never hangs past this. A non-positive
|
||
/// value is replaced by <c>MqttDriver.Normalize</c>, which is the enforcement point.
|
||
/// </summary>
|
||
public int ConnectTimeoutSeconds { get; init; } = 15;
|
||
|
||
/// <summary>Initial reconnect backoff after a connection drop; clamped by <c>MqttConnection.NextBackoff</c>.</summary>
|
||
public int ReconnectMinBackoffSeconds { get; init; } = 1;
|
||
|
||
/// <summary>Cap on the exponential reconnect backoff; clamped by <c>MqttConnection.NextBackoff</c>.</summary>
|
||
public int ReconnectMaxBackoffSeconds { get; init; } = 30;
|
||
|
||
/// <summary>
|
||
/// Ceiling on an inbound message body, in bytes. A larger message is refused before any
|
||
/// decode or parse and degrades its own tags to <c>BadDecodingError</c>. Default 1 MiB.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// Decode and parse both run synchronously on MQTTnet's shared dispatcher thread, so their
|
||
/// cost is paid by <i>every</i> subscription, not just the offending topic — without a bound,
|
||
/// one publisher shipping a multi-megabyte body stalls the whole driver's delivery. "Unbounded"
|
||
/// is deliberately not offered; a non-positive value falls back to the driver's own 1 MiB
|
||
/// default. The literal is duplicated from <c>MqttSubscriptionManager.DefaultMaxPayloadBytes</c>
|
||
/// because this <c>.Contracts</c> assembly is <i>referenced by</i> the driver assembly and
|
||
/// cannot reference it back; the manager's constructor is the single enforcement point.
|
||
/// </remarks>
|
||
public int MaxPayloadBytes { get; init; } = 1024 * 1024;
|
||
|
||
/// <summary>Selects the ingest shape — Plain topics or Sparkplug B.</summary>
|
||
public MqttMode Mode { get; init; } = MqttMode.Plain;
|
||
|
||
/// <summary>
|
||
/// The cluster's authored raw MQTT tags, as delivered by the deploy artifact: each carries the
|
||
/// tag's <b>RawPath</b> (its v3 identity and driver wire reference) plus its <c>TagConfig</c>
|
||
/// blob. <see cref="MqttDriver"/> maps each through <see cref="MqttTagDefinitionFactory"/> at
|
||
/// initialize and re-registers the set <b>wholesale</b> on every reinitialize, so a redeploy
|
||
/// that drops a tag stops feeding it.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// This is also the <b>only</b> source of the driver's discoverable node set — plain MQTT has
|
||
/// no browsable address space, and a tag that is not authored here is never materialized no
|
||
/// matter how much traffic its topic carries. Mirrors <c>ModbusDriverOptions.RawTags</c> /
|
||
/// <c>FocasDriverOptions.RawTags</c>.
|
||
/// </remarks>
|
||
public IReadOnlyList<RawTagEntry> RawTags { get; init; } = [];
|
||
|
||
/// <summary>
|
||
/// Sparkplug-only settings. Populated when <see cref="Mode"/> is
|
||
/// <see cref="MqttMode.SparkplugB"/>; <c>null</c> in Plain mode.
|
||
/// </summary>
|
||
public MqttSparkplugOptions? Sparkplug { get; init; }
|
||
|
||
/// <summary>
|
||
/// Plain-mode-only settings. Populated when <see cref="Mode"/> is
|
||
/// <see cref="MqttMode.Plain"/>; <c>null</c> in Sparkplug B mode.
|
||
/// </summary>
|
||
public MqttPlainOptions? Plain { get; init; }
|
||
|
||
/// <summary>
|
||
/// Record-generated <c>ToString()</c> member printer, overridden so <see cref="Password"/>
|
||
/// never renders in plaintext — this DTO routinely lands in logs / exception messages /
|
||
/// debugger watches, and the plan's cross-cutting rule is explicit: never commit or log
|
||
/// creds. A set password prints as <c>***</c>; unset (<c>null</c>/empty) renders
|
||
/// distinguishably so the redaction can't be mistaken for a real secret.
|
||
/// </summary>
|
||
private bool PrintMembers(StringBuilder builder)
|
||
{
|
||
var passwordDisplay = Password switch
|
||
{
|
||
null => "<null>",
|
||
"" => "<empty>",
|
||
_ => "***",
|
||
};
|
||
|
||
builder.Append("Host = ").Append(Host);
|
||
builder.Append(", Port = ").Append(Port);
|
||
builder.Append(", ClientId = ").Append(ClientId);
|
||
builder.Append(", UseTls = ").Append(UseTls);
|
||
builder.Append(", AllowUntrustedServerCertificate = ").Append(AllowUntrustedServerCertificate);
|
||
builder.Append(", CaCertificatePath = ").Append(CaCertificatePath);
|
||
builder.Append(", Username = ").Append(Username);
|
||
builder.Append(", Password = ").Append(passwordDisplay);
|
||
builder.Append(", ProtocolVersion = ").Append(ProtocolVersion);
|
||
builder.Append(", CleanSession = ").Append(CleanSession);
|
||
builder.Append(", KeepAliveSeconds = ").Append(KeepAliveSeconds);
|
||
builder.Append(", ConnectTimeoutSeconds = ").Append(ConnectTimeoutSeconds);
|
||
builder.Append(", ReconnectMinBackoffSeconds = ").Append(ReconnectMinBackoffSeconds);
|
||
builder.Append(", ReconnectMaxBackoffSeconds = ").Append(ReconnectMaxBackoffSeconds);
|
||
builder.Append(", MaxPayloadBytes = ").Append(MaxPayloadBytes);
|
||
builder.Append(", Mode = ").Append(Mode);
|
||
builder.Append(", Sparkplug = ").Append(Sparkplug);
|
||
builder.Append(", Plain = ").Append(Plain);
|
||
// Count only: a deployment routinely authors thousands of raw tags and each carries a full
|
||
// TagConfig blob, so printing the list would turn any log of this DTO into a config dump.
|
||
builder.Append(", RawTags = ").Append(RawTags.Count).Append(" tag(s)");
|
||
return true;
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// Sparkplug B settings for an <see cref="MqttDriverOptions"/> instance in
|
||
/// <see cref="MqttMode.SparkplugB"/> mode. See
|
||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||
/// </summary>
|
||
public sealed record MqttSparkplugOptions
|
||
{
|
||
/// <summary>Sparkplug group id — the driver subscribes <c>spBv1.0/{GroupId}/#</c>.</summary>
|
||
public string GroupId { get; init; } = "";
|
||
|
||
/// <summary>
|
||
/// Sparkplug Host Application identity — published as <c>spBv1.0/STATE/{HostId}</c>
|
||
/// (Sparkplug v3.0).
|
||
/// </summary>
|
||
public string HostId { get; init; } = "";
|
||
|
||
/// <summary>
|
||
/// When <c>true</c>, this driver instance acts as the Sparkplug Primary Host
|
||
/// Application. At most one primary host may exist per host-id per broker.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// Implemented by <c>SparkplugPrimaryHost</c> on a dedicated broker connection
|
||
/// whose lifetime <i>is</i> the claim, and gated on the redundancy Primary role so the two nodes
|
||
/// of a pair never both claim. Requires <see cref="HostId"/>; set without one, the driver warns
|
||
/// and declines rather than publishing to a malformed topic.
|
||
/// </remarks>
|
||
public bool ActAsPrimaryHost { get; init; } = false;
|
||
|
||
/// <summary>
|
||
/// When <c>true</c>, a detected sequence-number gap triggers a Sparkplug rebirth
|
||
/// request (NCMD) rather than silently continuing with stale metric state.
|
||
/// </summary>
|
||
public bool RequestRebirthOnGap { get; init; } = true;
|
||
|
||
/// <summary>
|
||
/// How long, in seconds, browse/discovery collects NBIRTH/DBIRTH traffic before
|
||
/// considering the observed metric set stable.
|
||
/// </summary>
|
||
public int BirthObservationWindowSeconds { get; init; } = 15;
|
||
}
|
||
|
||
/// <summary>
|
||
/// Plain-MQTT-mode settings for an <see cref="MqttDriverOptions"/> instance in
|
||
/// <see cref="MqttMode.Plain"/> mode. See
|
||
/// <c>docs/plans/2026-07-15-mqtt-sparkplug-driver-design.md</c> §5.1.
|
||
/// </summary>
|
||
public sealed record MqttPlainOptions
|
||
{
|
||
/// <summary>
|
||
/// Optional prefix prepended when the driver needs to compose a topic (e.g. discovery
|
||
/// scoping); per-tag topics are authored explicitly and are unaffected.
|
||
/// </summary>
|
||
public string TopicPrefix { get; init; } = "";
|
||
|
||
/// <summary>
|
||
/// Default QoS used when a tag's own <c>qos</c> is unset. MQTT defines exactly three levels;
|
||
/// <c>MqttSubscriptionManager</c>'s constructor clamps this to 0–2 before it can reach a
|
||
/// SUBSCRIBE, matching what the AdminUI driver form persists.
|
||
/// </summary>
|
||
public int DefaultQos { get; init; } = 1;
|
||
}
|