CBDDC/src/ZB.MOM.WW.CBDDC.Core/Storage/IOplogStore.cs

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

namespace ZB.MOM.WW.CBDDC.Core.Storage;

/// <summary>
///     Handles operations related to the Operation Log (Oplog), synchronization, and logical clocks.
/// </summary>
public interface IOplogStore : ISnapshotable<OplogEntry>
{
    /// <summary>
    ///     Occurs when changes are applied to the store from external sources (sync).
    /// </summary>
    event EventHandler<ChangesAppliedEventArgs> ChangesApplied;

    /// <summary>
    ///     Appends a new entry to the operation log asynchronously.
    /// </summary>
    /// <param name="entry">The operation log entry to append. Cannot be null.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the append operation.</param>
    /// <returns>A task that represents the asynchronous append operation.</returns>
    Task AppendOplogEntryAsync(OplogEntry entry, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Appends a new entry to the operation log asynchronously for a specific dataset.
    /// </summary>
    /// <param name="entry">The operation log entry to append.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task that represents the asynchronous append operation.</returns>
    Task AppendOplogEntryAsync(
        OplogEntry entry,
        string datasetId,
        CancellationToken cancellationToken = default)
    {
        return AppendOplogEntryAsync(entry, cancellationToken);
    }

    /// <summary>
    ///     Asynchronously retrieves all oplog entries that occurred after the specified timestamp.
    /// </summary>
    /// <param name="timestamp">The timestamp after which oplog entries should be returned.</param>
    /// <param name="collections">An optional collection of collection names to filter the results.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
    /// <returns>A task that represents the asynchronous operation containing matching oplog entries.</returns>
    Task<IEnumerable<OplogEntry>> GetOplogAfterAsync(HlcTimestamp timestamp, IEnumerable<string>? collections = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    ///     Asynchronously retrieves oplog entries after the specified timestamp for a specific dataset.
    /// </summary>
    /// <param name="timestamp">The lower-bound timestamp.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="collections">Optional collection filter.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task containing matching oplog entries.</returns>
    Task<IEnumerable<OplogEntry>> GetOplogAfterAsync(
        HlcTimestamp timestamp,
        string datasetId,
        IEnumerable<string>? collections = null,
        CancellationToken cancellationToken = default)
    {
        return GetOplogAfterAsync(timestamp, collections, cancellationToken);
    }

    /// <summary>
    ///     Asynchronously retrieves the latest observed hybrid logical clock (HLC) timestamp.
    /// </summary>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
    /// <returns>A task that represents the asynchronous operation containing the latest HLC timestamp.</returns>
    Task<HlcTimestamp> GetLatestTimestampAsync(CancellationToken cancellationToken = default);

    /// <summary>
    ///     Asynchronously retrieves the latest observed timestamp for a specific dataset.
    /// </summary>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task containing the latest timestamp.</returns>
    Task<HlcTimestamp> GetLatestTimestampAsync(string datasetId, CancellationToken cancellationToken = default)
    {
        return GetLatestTimestampAsync(cancellationToken);
    }

    /// <summary>
    ///     Asynchronously retrieves the current vector clock representing the state of distributed events.
    /// </summary>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
    /// <returns>A task that represents the asynchronous operation containing the current vector clock.</returns>
    Task<VectorClock> GetVectorClockAsync(CancellationToken cancellationToken = default);

    /// <summary>
    ///     Asynchronously retrieves the vector clock for a specific dataset.
    /// </summary>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task containing the vector clock.</returns>
    Task<VectorClock> GetVectorClockAsync(string datasetId, CancellationToken cancellationToken = default)
    {
        return GetVectorClockAsync(cancellationToken);
    }

    /// <summary>
    ///     Retrieves a collection of oplog entries for the specified node that occurred after the given timestamp.
    /// </summary>
    /// <param name="nodeId">The unique identifier of the node for which to retrieve oplog entries. Cannot be null or empty.</param>
    /// <param name="since">The timestamp after which oplog entries should be returned.</param>
    /// <param name="collections">An optional collection of collection names to filter the oplog entries.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
    /// <returns>A task that represents the asynchronous operation containing oplog entries for the specified node.</returns>
    Task<IEnumerable<OplogEntry>> GetOplogForNodeAfterAsync(string nodeId, HlcTimestamp since,
        IEnumerable<string>? collections = null, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Retrieves oplog entries for the specified node and dataset after the provided timestamp.
    /// </summary>
    /// <param name="nodeId">The node identifier.</param>
    /// <param name="since">The lower-bound timestamp.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="collections">Optional collection filter.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task containing matching oplog entries.</returns>
    Task<IEnumerable<OplogEntry>> GetOplogForNodeAfterAsync(
        string nodeId,
        HlcTimestamp since,
        string datasetId,
        IEnumerable<string>? collections = null,
        CancellationToken cancellationToken = default)
    {
        return GetOplogForNodeAfterAsync(nodeId, since, collections, cancellationToken);
    }

    /// <summary>
    ///     Asynchronously retrieves the hash of the most recent entry for the specified node.
    /// </summary>
    /// <param name="nodeId">
    ///     The unique identifier of the node for which to retrieve the last entry hash. Cannot be null or
    ///     empty.
    /// </param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the operation.</param>
    /// <returns>A task that represents the asynchronous operation containing the hash string of the last entry or null.</returns>
    Task<string?> GetLastEntryHashAsync(string nodeId, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Asynchronously retrieves the last entry hash for a node within a specific dataset.
    /// </summary>
    /// <param name="nodeId">The node identifier.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task containing the last hash or null.</returns>
    Task<string?> GetLastEntryHashAsync(string nodeId, string datasetId, CancellationToken cancellationToken = default)
    {
        return GetLastEntryHashAsync(nodeId, cancellationToken);
    }

    /// <summary>
    ///     Asynchronously retrieves a sequence of oplog entries representing the chain between the specified start and end
    ///     hashes.
    /// </summary>
    /// <param name="startHash">The hash of the first entry in the chain range. Cannot be null or empty.</param>
    /// <param name="endHash">The hash of the last entry in the chain range. Cannot be null or empty.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
    /// <returns>A task that represents the asynchronous operation containing OplogEntry objects in chain order.</returns>
    Task<IEnumerable<OplogEntry>> GetChainRangeAsync(string startHash, string endHash,
        CancellationToken cancellationToken = default);

    /// <summary>
    ///     Asynchronously retrieves a chain range for a specific dataset.
    /// </summary>
    /// <param name="startHash">The start hash.</param>
    /// <param name="endHash">The end hash.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task containing chain entries.</returns>
    Task<IEnumerable<OplogEntry>> GetChainRangeAsync(
        string startHash,
        string endHash,
        string datasetId,
        CancellationToken cancellationToken = default)
    {
        return GetChainRangeAsync(startHash, endHash, cancellationToken);
    }

    /// <summary>
    ///     Asynchronously retrieves the oplog entry associated with the specified hash value.
    /// </summary>
    /// <param name="hash">The hash string identifying the oplog entry to retrieve. Cannot be null or empty.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the asynchronous operation.</param>
    /// <returns>A task representing the asynchronous operation containing the OplogEntry if found, otherwise null.</returns>
    Task<OplogEntry?> GetEntryByHashAsync(string hash, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Asynchronously retrieves an entry by hash for a specific dataset.
    /// </summary>
    /// <param name="hash">The entry hash.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task containing the entry when found.</returns>
    Task<OplogEntry?> GetEntryByHashAsync(string hash, string datasetId, CancellationToken cancellationToken = default)
    {
        return GetEntryByHashAsync(hash, cancellationToken);
    }

    /// <summary>
    ///     Applies a batch of oplog entries asynchronously to the target data store.
    /// </summary>
    /// <param name="oplogEntries">A collection of OplogEntry objects representing the operations to apply. Cannot be null.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the batch operation.</param>
    /// <returns>A task that represents the asynchronous batch apply operation.</returns>
    Task ApplyBatchAsync(IEnumerable<OplogEntry> oplogEntries, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Applies a batch of oplog entries asynchronously for a specific dataset.
    /// </summary>
    /// <param name="oplogEntries">The entries to apply.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task that represents the apply operation.</returns>
    Task ApplyBatchAsync(
        IEnumerable<OplogEntry> oplogEntries,
        string datasetId,
        CancellationToken cancellationToken = default)
    {
        return ApplyBatchAsync(oplogEntries, cancellationToken);
    }

    /// <summary>
    ///     Asynchronously removes entries from the oplog that are older than the specified cutoff timestamp.
    /// </summary>
    /// <param name="cutoff">The timestamp that defines the upper bound for entries to be pruned.</param>
    /// <param name="cancellationToken">A cancellation token that can be used to cancel the prune operation.</param>
    /// <returns>A task that represents the asynchronous prune operation.</returns>
    Task PruneOplogAsync(HlcTimestamp cutoff, CancellationToken cancellationToken = default);

    /// <summary>
    ///     Asynchronously removes entries from the specified dataset oplog that are older than the cutoff.
    /// </summary>
    /// <param name="cutoff">The prune cutoff timestamp.</param>
    /// <param name="datasetId">The dataset identifier.</param>
    /// <param name="cancellationToken">A cancellation token.</param>
    /// <returns>A task that represents the prune operation.</returns>
    Task PruneOplogAsync(HlcTimestamp cutoff, string datasetId, CancellationToken cancellationToken = default)
    {
        return PruneOplogAsync(cutoff, cancellationToken);
    }
}