using System.Collections.Immutable;
using Connected.Annotations;

namespace Connected.Collections.Queues;
/// <summary>
/// Represents a distributed service for processing queue messages.
/// </summary>
/// <remarks>
/// Queue mechanism is mostly used as an internal logic of processes
/// and resources to offload work from the main thread to achieve better
/// responsiveness of the system. Aggregations and calculations are good
/// examples of queue usage. You should use queue whenever you must
/// perform any kind of work that is not necessary to perform it in a single
/// transaction scope.
/// </remarks>
[Service]
[ServiceUrl(CollectionRoutes.Queue)]
public interface IQueueService
{
	/// <summary>
	/// Enqueues the queue message.
	/// </summary>
	/// <typeparam name="TArgs">The type of the arguments used in queue message</typeparam>
	/// <param name="args">The arguments containing information about a queue message.</param>
	Task Enqueue<TClient, TArgs>(TArgs args)
		where TClient : IQueueClient<TArgs>
		where TArgs : QueueArgs;
	/// <summary>
	/// Dequeues the queue messages based on the provided arguments.
	/// </summary>
	/// <param name="args">The arguments containing information about dequeue criteria.</param>
	/// <returns>A list of valid queue messages that can be immediatelly processed.S</returns>
	Task<ImmutableList<IQueueMessage>> Dequeue(DequeueArgs args);
}