using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace Tango.Telemetry
{
    /// <summary>
    /// Defines the contract for managing telemetry storage, including pending telemetries and history source checkpoints.
    /// </summary>
    public interface ITelemetryStorageManager : IDisposable
    {
        /// <summary>
        /// Initializes the storage manager with the specified checkpoints recovery client.
        /// Responsible for loading the database, restoring from backup if necessary, and recovering remote checkpoints.
        /// </summary>
        /// <param name="checkpointsRecoveryClient">An implementation of the checkpoint recovery client used for cloud fallback.</param>
        Task Init(ITelemetryCheckpointsRecoveryClient checkpointsRecoveryClient);

        /// <summary>
        /// Inserts or updates a pending telemetry record in the local storage.
        /// </summary>
        /// <param name="pendingTelemetry">The pending telemetry to be stored or updated.</param>
        void UpsertPendingTelemetry(PendingTelemetry pendingTelemetry);

        /// <summary>
        /// Deletes a pending telemetry record from the local storage.
        /// </summary>
        /// <param name="pendingTelemetry">The pending telemetry to be deleted.</param>
        void DeletePendingTelemetry(PendingTelemetry pendingTelemetry);

        /// <summary>
        /// Retrieves a list of pending telemetry records, ordered by time, up to the specified maximum count.
        /// </summary>
        /// <param name="maxCount">The maximum number of pending telemetries to retrieve.</param>
        /// <returns>A list of pending telemetry objects.</returns>
        List<PendingTelemetry> GetPendingTelemetries(int maxCount);

        /// <summary>
        /// Gets the total number of pending telemetry records currently stored.
        /// </summary>
        /// <returns>The count of pending telemetry records.</returns>
        int GetPendingTelemetriesCount();

        /// <summary>
        /// Retrieves the current checkpoint for the specified history source.
        /// </summary>
        /// <param name="source">The telemetry history source for which to retrieve the checkpoint.</param>
        /// <returns>The stored checkpoint information for the given source.</returns>
        TelemetryHistorySourceCheckPoint GetHistorySourceCheckPoint(ITelemetryHistorySource source);

        /// <summary>
        /// Retrieves all stored history source checkpoints currently tracked by the storage system.
        /// Each checkpoint represents the latest processed state of a specific telemetry history source.
        /// </summary>
        /// <returns>A list of <see cref="TelemetryHistorySourceCheckPoint"/> entries for all registered history sources.</returns>
        List<TelemetryHistorySourceCheckPoint> GetHistorySourcesCheckPoints();

        /// <summary>
        /// Sets or updates the checkpoint for the specified history source.
        /// </summary>
        /// <param name="source">The telemetry history source for which to update the checkpoint.</param>
        /// <param name="time">The latest timestamp of telemetry data processed for the source.</param>
        /// <param name="totalCount">The total number of telemetry records processed for the source.</param>
        void SetHistorySourceCheckPoint(ITelemetryHistorySource source, DateTime time, int totalCount);

        /// <summary>
        /// Adds the specified telemetry item to the published telemetry cache,
        /// ensuring it is tracked as already published by the system.
        /// </summary>
        /// <param name="telemetry">The telemetry instance to register as published.</param>
        void AddToPublishedTelemetryCache(ITelemetry telemetry);

        /// <summary>
        /// Checks whether the specified telemetry item is already present in the published telemetry cache.
        /// </summary>
        /// <param name="telemetry">The telemetry instance to verify.</param>
        /// <returns>True if the telemetry appears to have already been published; otherwise, false.</returns>
        bool IsTelemetryInPublishedCache(ITelemetry telementry);

        /// <summary>
        /// Removes entries from the published telemetry cache that were marked as published
        /// before the specified time. Intended to manage memory and storage growth over time,
        /// especially once historical sources have progressed beyond the given point.
        /// </summary>
        /// <param name="olderThan">The timestamp indicating the oldest publication time to retain. Entries older than this will be removed.</param>
        void PerformPublishedTelemetriesCleanUp(DateTime olderThan);
    }
}