using System.Net.WebSockets;

namespace CoreAgent.WebSocketTransport.Interfaces;

/// <summary>
/// WebSocket 连接接口
/// 单一职责：负责网络连接管理
/// </summary>
public interface IWebSocketConnection : IDisposable
{
    /// <summary>
    /// 连接状态
    /// </summary>
    WebSocketState State { get; }
    
    /// <summary>
    /// 是否已连接
    /// </summary>
    bool IsConnected { get; }
    
    /// <summary>
    /// 连接 WebSocket 服务器
    /// </summary>
    /// <param name="uri">服务器地址</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task ConnectAsync(Uri uri, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// 发送消息
    /// </summary>
    /// <param name="buffer">消息缓冲区</param>
    /// <param name="messageType">消息类型</param>
    /// <param name="endOfMessage">是否为消息结束</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task SendAsync(ArraySegment<byte> buffer, WebSocketMessageType messageType, bool endOfMessage, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// 接收消息
    /// </summary>
    /// <param name="buffer">接收缓冲区</param>
    /// <param name="cancellationToken">取消令牌</param>
    /// <returns>接收结果</returns>
    Task<WebSocketReceiveResult> ReceiveAsync(ArraySegment<byte> buffer, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// 关闭连接
    /// </summary>
    /// <param name="closeStatus">关闭状态</param>
    /// <param name="statusDescription">状态描述</param>
    /// <param name="cancellationToken">取消令牌</param>
    Task CloseAsync(WebSocketCloseStatus closeStatus, string statusDescription, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// 强制关闭连接并重新创建WebSocket实例
    /// 用于处理CloseReceived状态后无法重连的问题
    /// </summary>
    void ForceClose();
}