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

/// <summary>
///     Optional driver capability for per-host connectivity reporting. Currently used by
///     the Galaxy driver (Platform / AppEngine ScanState) but generalized so future drivers
///     with multi-host topology (e.g. an OPC UA Client gateway proxying multiple upstream
///     servers) can opt in.
/// </summary>
/// <remarks>
///     Per <c>docs/v2/plan.md</c> §5a — the Galaxy driver's <c>GalaxyRuntimeProbeManager</c>
///     becomes <c>IHostConnectivityProbe</c> after the v2 refactor.
/// </remarks>
public interface IHostConnectivityProbe
{
    /// <summary>
    ///     Snapshot of host-level connectivity. The Core uses this to drive Bad-quality
    ///     fan-out scoped to the affected host's subtree (not the whole driver namespace).
    /// </summary>
    IReadOnlyList<HostConnectivityStatus> GetHostStatuses();

    /// <summary>Fired when a host transitions Running ↔ Stopped (or similar lifecycle change).</summary>
    event EventHandler<HostStatusChangedEventArgs>? OnHostStatusChanged;
}

/// <summary>Per-host connectivity snapshot.</summary>
/// <param name="HostName">Driver-side host identifier (e.g. for Galaxy: Platform or AppEngine name).</param>
/// <param name="State">Current state.</param>
/// <param name="LastChangedUtc">Timestamp of the last state transition.</param>
public sealed record HostConnectivityStatus(
    string HostName,
    HostState State,
    DateTime LastChangedUtc);

/// <summary>Event payload for <see cref="IHostConnectivityProbe.OnHostStatusChanged"/>.</summary>
public sealed record HostStatusChangedEventArgs(
    string HostName,
    HostState OldState,
    HostState NewState);

/// <summary>Host lifecycle state. Generalization of Galaxy's Platform/Engine ScanState.</summary>
public enum HostState { Unknown, Running, Stopped, Faulted }