using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
///
/// MTConnect Agent driver configuration. Bound from the driver's DriverConfig JSON at
/// DriverHost.RegisterAsync. The driver polls a remote MTConnect Agent's REST endpoints
/// (/probe, /current, /sample) rooted at and maps
/// each returned DataItem into an OPC UA variable per .
///
public sealed class MTConnectDriverOptions
{
///
/// Gets the MTConnect Agent's base URI (e.g. http://agent:5000). Required — the
/// driver appends the standard Agent request paths (/probe, /current,
/// /sample) to this base.
///
public required string AgentUri { get; init; }
///
/// Optional device-name scope. When set, requests are narrowed to
/// {AgentUri}/{DeviceName}/... so a multi-device Agent only serves one device's
/// DataItems through this driver instance. Default null = agent-wide (all devices).
///
public string? DeviceName { get; init; }
///
/// Per-call HTTP deadline, in milliseconds, applied to every Agent request
/// (/probe, /current, /sample). Default 5000 — long enough for
/// a large device probe response over a LAN, short enough that a hung Agent surfaces as a
/// failed poll rather than wedging the driver.
///
public int RequestTimeoutMs { get; init; } = 5000;
///
/// The interval query parameter (milliseconds) passed to the Agent's /sample
/// streaming request — the minimum time the Agent waits between successive chunks of the
/// response. Default 1000; must be non-zero so the sample pump cannot spin the
/// connection into a busy-loop.
///
public int SampleIntervalMs { get; init; } = 1000;
///
/// The count query parameter passed to the Agent's /sample request — the
/// maximum number of DataItem observations returned per chunk. Default 1000, the
/// MTConnect Agent's own conventional default.
///
/// It caps subscription throughput at SampleCount / SampleIntervalMs observations per
/// millisecond (default 1000 a second): a machine producing more falls behind the Agent's ring buffer. The
/// pump measures that lag and, when it is persistently behind, reopens the stream with the count doubled — up
/// to 16× this value, at most 65 536 — and reports the effective count and the lag on the /hosts
/// diagnostics (review 2026-10-21 T-5). Each new stream starts again from this value.
///
///
public int SampleCount { get; init; } = 1000;
///
/// The heartbeat query parameter (milliseconds) passed to the Agent's /sample
/// streaming request — the Agent sends an empty chunk after this much idle time so the
/// client can detect a silently-stalled connection. Default 10000, matching the
/// MTConnect Agent's own conventional default; must be non-zero or a quiet connection can
/// never be distinguished from a dead one.
///
public int HeartbeatMs { get; init; } = 10000;
///
/// Gets how long, in milliseconds, the Agent must keep REFUSING connections (a definite loss — nothing is
/// listening at ) before every subscribed value is marked BadNoCommunication
/// (lmxopcua#846). Default 2000; 0 marks on the first refusal; a negative value disables the fast
/// path, leaving the comms-loss watchdog (~90 s) as the only signal. Ambiguous failures (timeouts, a stalled or
/// reset stream, DNS) never use it — they keep the watchdog contract.
///
public int CommsLossConfirmMs { get; init; } = 2000;
///
/// The authored tags this driver instance serves — one
/// per tag, keyed by the DataItem id it binds
/// (). The factory config DTO carries these and
/// builds them into the options; the driver indexes them to know each tag's target
/// when coercing an Agent observation
/// (whose wire form is always text) into a published value.
///
/// Defaults to empty, never null: a driver instance may legitimately be
/// authored with no tags yet, and a null collection here would surface as a
/// NullReferenceException at deploy time from operator-authored config.
///
///
public IReadOnlyList Tags { get; init; } = [];
///
/// The v3 data-plane binding: the authored raw tags the deploy artifact delivers. Each
/// pairs the tag's RawPath — the driver's wire reference for
/// read / subscribe / publish, and the key DriverHostActor routes published values by —
/// with the driver-specific TagConfig blob naming the Agent DataItem id it binds.
/// Injected into every driver's merged config by DriverDeviceConfigMerger, so this is the
/// collection a deployed instance actually serves from.
///
/// Relationship to . The driver builds ONE observation index and
/// ONE RawPath → dataItemId table from both collections:
///
/// - A tag in RawTags is reachable by its RawPath (production). Its coercion
/// type comes from the blob's driverDataType; failing that, from a
/// entry naming the same DataItem id; failing that, from the Agent's
/// own /probe declaration (); failing
/// that, — the coercion that cannot fail.
/// The /probe step is not reached by a browse-committed tag — the AdminUI's
/// commit mapper writes a full typed blob, so the first step always answers — but
/// the type it writes IS the browsed leaf's inference, so the answer
/// is the same one. It previously wrote the model's String default and silently
/// mistyped every browsed tag (code-reviews/Driver.MTConnect/findings.md).
/// The step still serves a hand-authored / CSV / API blob that
/// states no type.
/// - A tag in only is reachable by its DataItem id
/// (the driver CLI's authoring surface, and every pre-v3 test) and still contributes
/// its coercion type to the index.
///
/// Both default to empty, so neither collection is required and a driver instance
/// authored with no tags yet starts cleanly.
///
///
public IReadOnlyList RawTags { get; init; } = [];
///
/// Background connectivity-probe settings. When
/// is true the driver periodically issues a cheap /probe request and raises
/// OnHostStatusChanged on Running ↔ Stopped transitions.
///
public MTConnectProbeOptions Probe { get; init; } = new();
///
/// Reconnect backoff settings used after a failed Agent request or a dropped
/// /sample streaming connection.
///
public MTConnectReconnectOptions Reconnect { get; init; } = new();
///
/// Write-back settings. Off by default — the driver shipped read-only, and enabling this is
/// only half the gate: the Agent's own AllowPut must be on too.
///
public MTConnectWriteOptions Write { get; init; } = new();
}
/// Background connectivity-probe knobs, mirroring ModbusProbeOptions.
public sealed class MTConnectProbeOptions
{
/// Gets a value indicating whether probing is enabled.
public bool Enabled { get; init; } = true;
/// Gets the interval between probe requests.
public TimeSpan Interval { get; init; } = TimeSpan.FromSeconds(5);
/// Gets the probe request timeout.
public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(2);
}
/// Geometric-backoff settings for the post-failure reconnect loop, mirroring ModbusReconnectOptions.
public sealed class MTConnectReconnectOptions
{
/// Delay before the first reconnect attempt, in milliseconds. Default 0 = immediate.
public int MinBackoffMs { get; init; } = 0;
/// Upper bound on the geometric backoff sequence, in milliseconds.
public int MaxBackoffMs { get; init; } = 30000;
/// Multiplier applied each retry. Default 2.0 doubles each step.
public double BackoffMultiplier { get; init; } = 2.0;
}
///
/// Write-back knobs. A write is observation injection via the Agent's AllowPut
/// surface — it sets what the Agent reports for a DataItem, not the machine itself (design §2.2).
///
public sealed class MTConnectWriteOptions
{
///
/// Gets a value indicating whether write-back is enabled. Default false — an existing
/// deployment that never authors this block keeps today's read-only behaviour exactly.
///
public bool Enabled { get; init; }
}