using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
using ZB.MOM.WW.ScadaBridge.Commons.Types.DataConnections;

namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;

/// <summary>
/// CentralUI facade over the central-to-site verify-endpoint command. Backs the
/// "Verify endpoint" button on the OPC UA endpoint editor: it serializes the
/// in-progress endpoint config and forwards a <see cref="VerifyEndpointCommand"/>
/// to the owning site via
/// <see cref="ZB.MOM.WW.ScadaBridge.Communication.CommunicationService"/>, which
/// runs a read-only connect probe and reports back a typed
/// <see cref="VerifyEndpointResult"/>.
/// </summary>
/// <remarks>
/// The service is the trust boundary for the verify capability: it enforces the
/// <c>Design</c> role at central before any cross-cluster traffic is generated,
/// because site-side actors do not unwrap the central trust envelope (mirrors
/// <see cref="IBrowseService"/>). Transport failures (timeouts, unreachable sites)
/// are translated into a typed <see cref="VerifyEndpointResult"/> so the editor can
/// render an inline outcome rather than throwing.
/// </remarks>
public interface IEndpointVerificationService
{
    /// <summary>
    /// Runs a read-only verification probe of <paramref name="config"/> against the
    /// live server at <paramref name="siteIdentifier"/>. The probe connects, captures
    /// the server certificate if it is untrusted, then disconnects — it never persists
    /// the config and never trusts the certificate (cert trust is a later action).
    /// </summary>
    /// <param name="siteIdentifier">The target site identifier (the machine-readable <c>SiteIdentifier</c> used in Akka addresses, NOT the numeric primary key).</param>
    /// <param name="connectionName">Name of the data connection being verified (for logging/correlation).</param>
    /// <param name="protocol">Protocol type string (e.g. <c>"OpcUa"</c>); matched case-insensitively at the site.</param>
    /// <param name="config">The endpoint configuration to verify; serialized to JSON before being sent to the site.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A task that resolves to a <see cref="VerifyEndpointResult"/> — success, or a classified failure (with a captured certificate when the failure is <see cref="VerifyFailureKind.UntrustedCertificate"/>).</returns>
    Task<VerifyEndpointResult> VerifyAsync(
        string siteIdentifier,
        string connectionName,
        string protocol,
        OpcUaEndpointConfig config,
        CancellationToken cancellationToken = default);
}