using ZB.MOM.WW.OtOpcUa.Commons.Types;

namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;

/// <summary>
/// Live view of the local node's identity and the cluster's role topology. Implemented by
/// <c>ClusterRoleInfo</c> in <c>OtOpcUa.Cluster</c>; consumed by everything that needs to
/// distinguish admin-role vs driver-role members or react to role-leader changes (e.g. OPC UA
/// ServiceLevel computation).
/// </summary>
public interface IClusterRoleInfo
{
    /// <summary>Gets the local cluster node identifier.</summary>
    NodeId LocalNode { get; }
    /// <summary>Gets the set of roles assigned to the local node.</summary>
    IReadOnlySet<string> LocalRoles { get; }

    /// <summary>
    /// Gets the local node's cluster-scoped role (e.g. <c>cluster-SITE-A</c>), or <c>null</c> when
    /// the node carries none. Derived from the node's OWN configured roles at construction time —
    /// NOT from live cluster membership — so it is available before the cluster forms (per-cluster
    /// mesh, Phase 6). When more than one cluster-scoped role is configured, the first one wins.
    /// </summary>
    string? ClusterRole { get; }

    /// <summary>
    /// Gets the ClusterId extracted from <see cref="ClusterRole"/> (e.g. <c>SITE-A</c>), or
    /// <c>null</c> when the node carries no cluster-scoped role.
    /// </summary>
    string? ClusterId { get; }

    /// <summary>Checks if the local node has the specified role.</summary>
    /// <param name="role">Role name to check.</param>
    /// <returns>True if the local node has the role; otherwise, false.</returns>
    bool HasRole(string role);
    /// <summary>Gets all nodes assigned to the specified role.</summary>
    /// <param name="role">Role name to query.</param>
    /// <returns>List of node identifiers with the role.</returns>
    IReadOnlyList<NodeId> MembersWithRole(string role);
    /// <summary>Gets the leader node for the specified role, or null if no leader is elected.</summary>
    /// <param name="role">Role name to query.</param>
    /// <returns>The leader node identifier, or null if no leader exists.</returns>
    NodeId? RoleLeader(string role);

    /// <summary>Occurs when the leader of a role changes.</summary>
    event EventHandler<RoleLeaderChangedEventArgs>? RoleLeaderChanged;
}