namespace ScadaLink.ClusterInfrastructure;

/// <summary>
/// Cluster configuration model, bound from the <c>ScadaLink:Cluster</c> section
/// of <c>appsettings.json</c> via the Options pattern.
/// <para>
/// This project owns the cluster <em>configuration contract</em>. The actual
/// Akka.NET bootstrap — building the HOCON from these values, starting the
/// <c>ActorSystem</c>, configuring the split-brain resolver and wiring
/// <c>CoordinatedShutdown</c> — lives in <c>ScadaLink.Host</c>
/// (see <c>Component-ClusterInfrastructure.md</c> → "Implementation Note — Code Placement").
/// </para>
/// <para>
/// Node-identity settings (remoting hostname/port, cluster role, site identifier,
/// gRPC port) are deliberately <em>not</em> here — they are owned by
/// <c>ScadaLink.Host.NodeOptions</c> (<c>ScadaLink:Node</c> section). Local SQLite
/// storage paths are owned by the database / store-and-forward options. This class
/// holds only the cluster-formation and failure-detection settings shared by every node.
/// </para>
/// </summary>
public class ClusterOptions
{
    /// <summary>
    /// The <c>appsettings.json</c> section name this options class binds from.
    /// Single source of truth so binding sites do not hard-code the magic string.
    /// </summary>
    public const string SectionName = "ScadaLink:Cluster";

    /// <summary>
    /// Akka.NET cluster seed nodes. Both nodes are seed nodes — each node lists
    /// itself and its partner — so either can start first and form the cluster.
    /// Must contain at least one entry.
    /// </summary>
    public List<string> SeedNodes { get; set; } = new();

    /// <summary>
    /// Split-brain resolver strategy. Must be <c>keep-oldest</c> for the two-node
    /// clusters ScadaLink uses: quorum strategies (<c>keep-majority</c>,
    /// <c>static-quorum</c>) cannot distinguish a crash from a partition with only
    /// two nodes and would shut down the whole cluster.
    /// </summary>
    public string SplitBrainResolverStrategy { get; set; } = "keep-oldest";

    /// <summary>
    /// Time the cluster membership must remain stable before the split-brain
    /// resolver acts to down unreachable nodes. Must be positive. Default 15s.
    /// </summary>
    public TimeSpan StableAfter { get; set; } = TimeSpan.FromSeconds(15);

    /// <summary>
    /// Frequency of cluster failure-detector heartbeat messages between nodes.
    /// Must be well below <see cref="FailureDetectionThreshold"/>. Default 2s.
    /// </summary>
    public TimeSpan HeartbeatInterval { get; set; } = TimeSpan.FromSeconds(2);

    /// <summary>
    /// Time without a heartbeat before a node is considered unreachable
    /// (Akka's <c>acceptable-heartbeat-pause</c>). Default 10s.
    /// </summary>
    public TimeSpan FailureDetectionThreshold { get; set; } = TimeSpan.FromSeconds(10);

    /// <summary>
    /// Akka's <c>min-nr-of-members</c>. Must be <c>1</c>: after failover only one
    /// node runs, and a value of <c>2</c> blocks the cluster singleton (Site Runtime
    /// Deployment Manager) — and therefore all data collection — indefinitely.
    /// </summary>
    public int MinNrOfMembers { get; set; } = 1;

    /// <summary>
    /// The keep-oldest resolver's <c>down-if-alone</c> flag. When <c>true</c> (the
    /// design-doc requirement), the oldest node downs itself if it finds it has no
    /// other reachable members, rather than running as an isolated single-node cluster.
    /// </summary>
    public bool DownIfAlone { get; set; } = true;
}
