114 lines
4.8 KiB
C#
114 lines
4.8 KiB
C#
using System;
|
|
using System.Collections.Generic;
|
|
using System.Threading;
|
|
using System.Threading.Tasks;
|
|
|
|
namespace Svrnty.CQRS.Events.ConsumerGroups.Abstractions;
|
|
|
|
/// <summary>
|
|
/// Store for managing consumer group offsets and consumer registration.
|
|
/// Enables multiple consumers to coordinate processing of event streams.
|
|
/// </summary>
|
|
public interface IConsumerOffsetStore
|
|
{
|
|
/// <summary>
|
|
/// Commit an offset for a consumer in a group.
|
|
/// This records that the consumer has successfully processed all events up to this offset.
|
|
/// </summary>
|
|
/// <param name="groupId">The consumer group ID.</param>
|
|
/// <param name="consumerId">The consumer ID within the group.</param>
|
|
/// <param name="streamName">The stream name.</param>
|
|
/// <param name="offset">The offset to commit.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>A task representing the asynchronous operation.</returns>
|
|
Task CommitOffsetAsync(
|
|
string groupId,
|
|
string consumerId,
|
|
string streamName,
|
|
long offset,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Get the last committed offset for a consumer group.
|
|
/// Returns the minimum offset across all consumers in the group, representing
|
|
/// the safe point up to which all events have been processed.
|
|
/// </summary>
|
|
/// <param name="groupId">The consumer group ID.</param>
|
|
/// <param name="streamName">The stream name.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>The last committed offset, or null if no offset has been committed.</returns>
|
|
Task<long?> GetCommittedOffsetAsync(
|
|
string groupId,
|
|
string streamName,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Get offsets for all consumers in a group.
|
|
/// Useful for monitoring consumer lag and group status.
|
|
/// </summary>
|
|
/// <param name="groupId">The consumer group ID.</param>
|
|
/// <param name="streamName">The stream name.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>Dictionary mapping consumer IDs to their committed offsets.</returns>
|
|
Task<IReadOnlyDictionary<string, long>> GetGroupOffsetsAsync(
|
|
string groupId,
|
|
string streamName,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Register a consumer as active (heartbeat).
|
|
/// Consumers should call this periodically to signal they are alive.
|
|
/// </summary>
|
|
/// <param name="groupId">The consumer group ID.</param>
|
|
/// <param name="consumerId">The consumer ID.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>A task representing the asynchronous operation.</returns>
|
|
Task RegisterConsumerAsync(
|
|
string groupId,
|
|
string consumerId,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Unregister a consumer (graceful shutdown).
|
|
/// Should be called when a consumer is shutting down gracefully.
|
|
/// </summary>
|
|
/// <param name="groupId">The consumer group ID.</param>
|
|
/// <param name="consumerId">The consumer ID.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>A task representing the asynchronous operation.</returns>
|
|
Task UnregisterConsumerAsync(
|
|
string groupId,
|
|
string consumerId,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Get all active consumers in a group.
|
|
/// Returns consumers that have registered and are sending heartbeats.
|
|
/// </summary>
|
|
/// <param name="groupId">The consumer group ID.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>List of active consumer information.</returns>
|
|
Task<IReadOnlyList<ConsumerInfo>> GetActiveConsumersAsync(
|
|
string groupId,
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Get all registered consumer groups.
|
|
/// </summary>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>List of group IDs.</returns>
|
|
Task<IReadOnlyList<string>> GetAllGroupsAsync(
|
|
CancellationToken cancellationToken = default);
|
|
|
|
/// <summary>
|
|
/// Clean up stale consumers that haven't sent heartbeats within the timeout period.
|
|
/// Typically called by a background health monitor.
|
|
/// </summary>
|
|
/// <param name="sessionTimeout">Time after which a consumer is considered stale.</param>
|
|
/// <param name="cancellationToken">Cancellation token.</param>
|
|
/// <returns>List of removed consumer infos.</returns>
|
|
Task<IReadOnlyList<ConsumerInfo>> CleanupStaleConsumersAsync(
|
|
TimeSpan sessionTimeout,
|
|
CancellationToken cancellationToken = default);
|
|
}
|