using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Tango.Telemetry.Reporting;

namespace Tango.Telemetry
{
    /// <summary>
    /// Defines the interface for a telemetry publisher responsible for managing sources, destinations,
    /// storage, and the overall publishing lifecycle.
    /// </summary>
    public interface ITelemetryPublisher : IDisposable
    {
        /// <summary>
        /// Occurs before a telemetry package is published to a destination.
        /// </summary>
        event EventHandler<TelemetryPackagePublishingEventArgs> PublishingPackage;

        /// <summary>
        /// Occurs when a telemetry package has been successfully published to a destination.
        /// </summary>
        event EventHandler<TelemetryPackagePublishedEventArgs> PackagePublished;

        /// <summary>
        /// Occurs when a telemetry package fails to publish to a destination.
        /// </summary>
        event EventHandler<TelemetryPackagePublishFailedEventArgs> PublishPackageFailed;

        /// <summary>
        /// Occurs when a telemetry publish operation has completed and a publish result is available,
        /// indicating the success or failure status for each destination.
        /// </summary>
        event EventHandler<TelemetryPublishResultAvailableEventArgs> PublishResultAvailable;

        /// <summary>
        /// Gets the storage manager used for telemetry persistence and checkpoint handling.
        /// </summary>
        ITelemetryStorageManager StorageManager { get; }

        /// <summary>
        /// Gets the telemetry queue manager responsible for internal queuing and retry logic.
        /// </summary>
        ITelemetryQueueManager QueueManager { get; }

        /// <summary>
        /// Gets the client used for remote checkpoint recovery.
        /// </summary>
        ITelemetryCheckpointsRecoveryClient CheckpointsRecoveryClient { get; }

        /// <summary>
        /// Gets the registered telemetry sources.
        /// </summary>
        ReadOnlyCollection<ITelemetrySource> Sources { get; }

        /// <summary>
        /// Registers a telemetry source with the publisher.
        /// </summary>
        /// <param name="source">The telemetry source to register.</param>
        void RegisterSource(ITelemetrySource source);

        /// <summary>
        /// Gets the registered telemetry destinations.
        /// </summary>
        ReadOnlyCollection<ITelemetryDestination> Destinations { get; }

        /// <summary>
        /// Registers a telemetry destination with the publisher.
        /// </summary>
        /// <param name="destination">The telemetry destination to register.</param>
        void RegisterDestination(ITelemetryDestination destination);

        /// <summary>
        /// Gets a value indicating whether the publisher is currently running.
        /// </summary>
        bool IsStarted { get; }

        /// <summary>
        /// Starts the telemetry publishing pipeline, including sources and destinations.
        /// </summary>
        /// <returns>A task representing the asynchronous start operation.</returns>
        Task Start();

        /// <summary>
        /// Stops the telemetry publishing pipeline and releases all resources.
        /// </summary>
        /// <returns>A task representing the asynchronous stop operation.</returns>
        Task Stop();

        /// <summary>
        /// Flushes up to the specified number of pending telemetries from local storage,
        /// attempting to publish them immediately. This can be used to force a retry of previously failed or postponed telemetry packages.
        /// </summary>
        /// <param name="maxCount">The maximum number of pending telemetry packages to flush.</param>
        /// <returns>A task that represents the asynchronous flush operation, returning a list of publish results for the flushed packages.</returns>
        Task<List<TelemetryPublishResult>> FlushPendingTelemetries(int maxCount);

        /// <summary>
        /// Generates a detailed telemetry report summarizing the current state of the telemetry system.
        /// The report includes statistics on published and pending telemetry, as well as per-source and per-destination results.
        /// </summary>
        Task<TelemetryReport> GetTelemetryReport();
    }
}