// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
 
namespace Microsoft.Build.TaskHost.BackEnd;
 
/// <summary>
/// Used to receive link status updates from an endpoint.
/// </summary>
/// <param name="endpoint">The endpoint invoking the delegate.</param>
/// <param name="status">The current status of the link.</param>
internal delegate void LinkStatusChangedDelegate(INodeEndpoint endpoint, LinkStatus status);
 
/// <summary>
/// The connection status of a link between the NodeEndpoint on the host and the NodeEndpoint
/// on the peer.
/// </summary>
internal enum LinkStatus
{
    /// <summary>
    /// The connection has never been started.
    /// </summary>
    Inactive,
 
    /// <summary>
    /// The connection is active, the most recent data has been successfully sent, and the
    /// node is responding to pings.
    /// </summary>
    Active,
 
    /// <summary>
    /// The connection has failed and been terminated.
    /// </summary>
    Failed,
 
    /// <summary>
    /// The connection could not be made/timed out.
    /// </summary>
    ConnectionFailed,
}
 
/// <summary>
/// This interface represents one end of a connection between the INodeProvider and a Node.
/// Implementations of this interface define the actual mechanism by which data is communicated.
/// </summary>
internal interface INodeEndpoint
{
    /// <summary>
    /// Raised when the status of the node's link has changed.
    /// </summary>
    event LinkStatusChangedDelegate OnLinkStatusChanged;
 
    /// <summary>
    /// Gets the current link status for this endpoint.
    /// </summary>
    LinkStatus LinkStatus { get; }
 
    /// <summary>
    /// Waits for the remote node to establish a connection.
    /// </summary>
    /// <param name="factory">The factory used to deserialize packets.</param>
    /// <remarks>Only one of Listen() or Connect() may be called on an endpoint.</remarks>
    void Listen(INodePacketFactory factory);
 
    /// <summary>
    /// Instructs the node to connect to its peer endpoint.
    /// </summary>
    /// <param name="factory">The factory used to deserialize packets.</param>
    void Connect(INodePacketFactory factory);
 
    /// <summary>
    /// Instructs the node to disconnect from its peer endpoint.
    /// </summary>
    void Disconnect();
 
    /// <summary>
    /// Sends a data packet to the node.
    /// </summary>
    /// <param name="packet">The packet to be sent.</param>
    void SendData(INodePacket packet);
 
    /// <summary>
    /// Called when we are about to send last packet to finalize graceful disconnection with client.
    /// This is needed to handle race condition when both client and server is gracefully about to close connection.
    /// </summary>
    void ClientWillDisconnect();
}