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>
/// <remarks>
///     <para>
///         <see cref="Demoted"/> (PR ablegacy-12 / #255) is a soft-stopped state used by drivers
///         that auto-throttle a host after N consecutive comm failures. Reads are short-circuited
///         with <c>BadCommunicationError</c> for a configurable cool-down window so one slow PLC
///         doesn't starve faster peers sharing the same driver. Demoted is *not* the same as
///         <see cref="Stopped"/> (which means "probe says it's down") nor <see cref="Faulted"/>
///         (which means "the driver itself is broken"); it's a deliberate driver-side back-off.
///         Consumers that don't recognize <c>Demoted</c> can safely treat it as <c>Stopped</c>
///         (see <c>HostStatusPublisher.MapState</c>).
///     </para>
/// </remarks>
public enum HostState { Unknown, Running, Stopped, Faulted, Demoted }