using Dpz.Core.Web.Jobs.Models.FileTransfer;

namespace Dpz.Core.Web.Jobs.Services.FileTransfer;

/// <summary>
/// 文件传输房间的内存存储接口。只保存连接元数据，不保存文件内容。
/// </summary>
public interface IFileTransferRoomStore
{
    /// <summary>未配对房间的最大存活时间。</summary>
    TimeSpan PendingRoomLifetime { get; }

    /// <summary>创建房间并绑定发起方连接。</summary>
    /// <param name="connectionId">发起方的 SignalR 连接 ID。</param>
    /// <param name="joinUrl">接收方加入链接。</param>
    /// <returns>包含房间对象和快照的操作结果。</returns>
    FileTransferRoomResult CreateRoom(string connectionId, string joinUrl);

    /// <summary>尝试接收方加入已有房间。</summary>
    /// <param name="roomKey">房间 Key。</param>
    /// <param name="connectionId">接收方的 SignalR 连接 ID。</param>
    /// <param name="joinUrl">接收方加入链接。</param>
    /// <returns>包含房间对象和快照的操作结果。</returns>
    FileTransferOperationResult<FileTransferRoomResult> TryJoinRoom(
        string roomKey,
        string connectionId,
        string joinUrl
    );

    /// <summary>尝试获取房间。</summary>
    /// <param name="roomKey">房间 Key。</param>
    /// <returns>房间对象操作结果。</returns>
    FileTransferOperationResult<FileTransferRoom> TryGetRoom(string roomKey);

    /// <summary>根据连接 ID 查找房间。</summary>
    /// <param name="connectionId">SignalR 连接 ID。</param>
    /// <returns>房间对象，未找到时返回 null。</returns>
    FileTransferRoom? GetRoomByConnection(string connectionId);

    /// <summary>移除指定连接关联的房间。</summary>
    /// <param name="connectionId">SignalR 连接 ID。</param>
    /// <returns>被移除的房间对象，未找到时返回 null。</returns>
    FileTransferRoom? RemoveByConnection(string connectionId);

    /// <summary>直接移除指定房间。</summary>
    /// <param name="roomKey">房间 Key。</param>
    /// <returns>被移除的房间对象，未找到时返回 null。</returns>
    FileTransferRoom? RemoveRoom(string roomKey);

    /// <summary>移除所有已过期的未配对房间。</summary>
    /// <param name="now">当前时间。</param>
    /// <returns>被移除的房间列表。</returns>
    IReadOnlyList<FileTransferRoom> RemoveExpiredPendingRooms(DateTimeOffset now);
}