lmxopcua/src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IDriverProbe.cs

namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;

/// <summary>
///     Test-connect probe for one driver type. Implementations deserialize a driver-config
///     JSON, attempt a cheap connection (TCP open, OPC UA session, gRPC ping — whatever the
///     driver's native protocol supports), and report success/failure with latency. Probes
///     MUST NOT mutate any persistent state; the AdminUI invokes them against transient
///     config from the typed form, NOT against the persisted DriverInstance row.
/// </summary>
public interface IDriverProbe
{
    /// <summary>DriverInstance.DriverType string this probe handles. Used for DI lookup.</summary>
    string DriverType { get; }

    /// <summary>
    ///     Run the probe with the supplied config + timeout. Honour <paramref name="ct"/> for
    ///     timeout cancellation. Never throw on connection failure; instead return a result
    ///     with <c>Ok = false</c> + a message.
    /// </summary>
    /// <param name="configJson">The driver-specific configuration JSON to probe with.</param>
    /// <param name="timeout">The maximum time to allow the probe to run.</param>
    /// <param name="ct">Cancellation token for the operation.</param>
    /// <returns>The probe outcome, including success/failure and latency.</returns>
    Task<DriverProbeResult> ProbeAsync(string configJson, TimeSpan timeout, CancellationToken ct);
}

/// <summary>Outcome of a single <see cref="IDriverProbe.ProbeAsync"/> call.</summary>
/// <param name="Ok">True iff the probe reached its target and the handshake succeeded.</param>
/// <param name="Message">Human-readable status; null on success.</param>
/// <param name="Latency">Wall-clock duration of the successful probe; null on failure.</param>
public sealed record DriverProbeResult(bool Ok, string? Message, TimeSpan? Latency);