dotnet-cqrs/Svrnty.CQRS.Sagas.Abstractions/ISagaBuilder.cs

using System;
using System.Threading;
using System.Threading.Tasks;

namespace Svrnty.CQRS.Sagas.Abstractions;

/// <summary>
/// Fluent builder for defining saga steps.
/// </summary>
/// <typeparam name="TData">The saga data type.</typeparam>
public interface ISagaBuilder<TData> where TData : class, ISagaData
{
    /// <summary>
    /// Adds a local step that executes synchronously within the orchestrator process.
    /// </summary>
    /// <param name="name">Unique name for this step.</param>
    /// <returns>Builder for configuring the step.</returns>
    ISagaStepBuilder<TData> Step(string name);

    /// <summary>
    /// Adds a step that sends a command to a remote service via messaging.
    /// </summary>
    /// <typeparam name="TCommand">The command type to send.</typeparam>
    /// <param name="name">Unique name for this step.</param>
    /// <returns>Builder for configuring the remote step.</returns>
    ISagaRemoteStepBuilder<TData, TCommand> SendCommand<TCommand>(string name) where TCommand : class;

    /// <summary>
    /// Adds a step that sends a command and expects a specific result.
    /// </summary>
    /// <typeparam name="TCommand">The command type to send.</typeparam>
    /// <typeparam name="TResult">The expected result type.</typeparam>
    /// <param name="name">Unique name for this step.</param>
    /// <returns>Builder for configuring the remote step.</returns>
    ISagaRemoteStepBuilder<TData, TCommand, TResult> SendCommand<TCommand, TResult>(string name) where TCommand : class;
}

/// <summary>
/// Builder for configuring a local saga step.
/// </summary>
/// <typeparam name="TData">The saga data type.</typeparam>
public interface ISagaStepBuilder<TData> where TData : class, ISagaData
{
    /// <summary>
    /// Defines the execution action for this step.
    /// </summary>
    /// <param name="action">The action to execute.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaStepBuilder<TData> Execute(Func<TData, ISagaContext, CancellationToken, Task> action);

    /// <summary>
    /// Defines the compensation action for this step.
    /// </summary>
    /// <param name="action">The compensation action to execute on rollback.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaStepBuilder<TData> Compensate(Func<TData, ISagaContext, CancellationToken, Task> action);

    /// <summary>
    /// Completes this step definition and returns to the saga builder.
    /// </summary>
    /// <returns>The saga builder for adding more steps.</returns>
    ISagaBuilder<TData> Then();
}

/// <summary>
/// Builder for configuring a remote command saga step (no result).
/// </summary>
/// <typeparam name="TData">The saga data type.</typeparam>
/// <typeparam name="TCommand">The command type to send.</typeparam>
public interface ISagaRemoteStepBuilder<TData, TCommand>
    where TData : class, ISagaData
    where TCommand : class
{
    /// <summary>
    /// Defines how to build the command from saga data.
    /// </summary>
    /// <param name="commandBuilder">Function to create the command.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand> WithCommand(Func<TData, ISagaContext, TCommand> commandBuilder);

    /// <summary>
    /// Defines what to do when the command completes successfully.
    /// </summary>
    /// <param name="handler">Handler for the response.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand> OnResponse(Func<TData, ISagaContext, CancellationToken, Task> handler);

    /// <summary>
    /// Defines the compensation command to send on rollback.
    /// </summary>
    /// <typeparam name="TCompensationCommand">The compensation command type.</typeparam>
    /// <param name="compensationBuilder">Function to create the compensation command.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand> Compensate<TCompensationCommand>(
        Func<TData, ISagaContext, TCompensationCommand> compensationBuilder) where TCompensationCommand : class;

    /// <summary>
    /// Sets a timeout for this step.
    /// </summary>
    /// <param name="timeout">The timeout duration.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand> WithTimeout(TimeSpan timeout);

    /// <summary>
    /// Configures retry behavior for this step.
    /// </summary>
    /// <param name="maxRetries">Maximum number of retries.</param>
    /// <param name="delay">Delay between retries.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand> WithRetry(int maxRetries, TimeSpan delay);

    /// <summary>
    /// Completes this step definition and returns to the saga builder.
    /// </summary>
    /// <returns>The saga builder for adding more steps.</returns>
    ISagaBuilder<TData> Then();
}

/// <summary>
/// Builder for configuring a remote command saga step with result.
/// </summary>
/// <typeparam name="TData">The saga data type.</typeparam>
/// <typeparam name="TCommand">The command type to send.</typeparam>
/// <typeparam name="TResult">The expected result type.</typeparam>
public interface ISagaRemoteStepBuilder<TData, TCommand, TResult>
    where TData : class, ISagaData
    where TCommand : class
{
    /// <summary>
    /// Defines how to build the command from saga data.
    /// </summary>
    /// <param name="commandBuilder">Function to create the command.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand, TResult> WithCommand(Func<TData, ISagaContext, TCommand> commandBuilder);

    /// <summary>
    /// Defines what to do when the command completes successfully with a result.
    /// </summary>
    /// <param name="handler">Handler for the response with result.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand, TResult> OnResponse(
        Func<TData, ISagaContext, TResult, CancellationToken, Task> handler);

    /// <summary>
    /// Defines the compensation command to send on rollback.
    /// </summary>
    /// <typeparam name="TCompensationCommand">The compensation command type.</typeparam>
    /// <param name="compensationBuilder">Function to create the compensation command.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand, TResult> Compensate<TCompensationCommand>(
        Func<TData, ISagaContext, TCompensationCommand> compensationBuilder) where TCompensationCommand : class;

    /// <summary>
    /// Sets a timeout for this step.
    /// </summary>
    /// <param name="timeout">The timeout duration.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand, TResult> WithTimeout(TimeSpan timeout);

    /// <summary>
    /// Configures retry behavior for this step.
    /// </summary>
    /// <param name="maxRetries">Maximum number of retries.</param>
    /// <param name="delay">Delay between retries.</param>
    /// <returns>This builder for chaining.</returns>
    ISagaRemoteStepBuilder<TData, TCommand, TResult> WithRetry(int maxRetries, TimeSpan delay);

    /// <summary>
    /// Completes this step definition and returns to the saga builder.
    /// </summary>
    /// <returns>The saga builder for adding more steps.</returns>
    ISagaBuilder<TData> Then();
}