namespace JdeScoping.ConfigManager.Core.Services;

/// <summary>
/// Service for managing configuration file backups.
/// </summary>
public interface IBackupService
{
    /// <summary>
    /// Creates a backup copy of the specified file with a timestamp suffix.
    /// </summary>
    /// <param name="filePath">The path of the file to backup.</param>
    /// <param name="ct">Cancellation token for the operation.</param>
    /// <returns>The path of the created backup file.</returns>
    Task<string> CreateBackupAsync(string filePath, CancellationToken ct = default);

    /// <summary>
    /// Retrieves a list of existing backups for the specified file, sorted by timestamp descending.
    /// </summary>
    /// <param name="filePath">The original file path to find backups for.</param>
    /// <param name="ct">Cancellation token for the operation.</param>
    /// <returns>A read-only list of backup information sorted by timestamp.</returns>
    Task<IReadOnlyList<BackupInfo>> GetBackupsAsync(string filePath, CancellationToken ct = default);

    /// <summary>
    /// Restores a backup file by copying it to the target location.
    /// </summary>
    /// <param name="backupPath">The path of the backup file to restore from.</param>
    /// <param name="targetPath">The target path where the backup should be restored.</param>
    /// <param name="ct">Cancellation token for the operation.</param>
    Task RestoreBackupAsync(string backupPath, string targetPath, CancellationToken ct = default);

    /// <summary>
    /// Removes old backup files, keeping only the most recent backups.
    /// </summary>
    /// <param name="filePath">The original file path to find backups for.</param>
    /// <param name="keepCount">The number of most recent backups to retain (default: 10).</param>
    /// <param name="ct">Cancellation token for the operation.</param>
    Task CleanupOldBackupsAsync(string filePath, int keepCount = 10, CancellationToken ct = default);
}