Class IdempotencyManager

java.lang.Object
io.github.ravocode.avoonce.core.IdempotencyManager
public class IdempotencyManager extends Object
Core state machine that enforces exactly-once processing rules.

Three execution modes are supported:

  1. No hash — execute(String, Callable): idempotency by key only.
  2. Auto hash — execute(String, byte[], Callable): the library hashes the raw request body using the configured RequestHasher (SHA-256 by default).
  3. Pre-computed hash — execute(String, String, Callable): the caller supplies an already-computed hash string (e.g. from a signed request header).

  • Constructor Details

    • IdempotencyManager

      public IdempotencyManager(IdempotencyRepository repository)
      Constructs an IdempotencyManager using the default Sha256RequestHasher.
      Parameters:
      repository - the backing store for idempotency records.

    • IdempotencyManager

      public IdempotencyManager(IdempotencyRepository repository, RequestHasher hasher)
      Constructs an IdempotencyManager with a custom RequestHasher.
      Parameters:
      repository - the backing store for idempotency records.
      hasher - the hashing strategy used when a raw request body is provided.

  • Method Details

    • execute

      public IdempotencyResponse execute(String idempotencyKey, Callable<IdempotencyResponse> action) throws Exception
      Executes the given action idempotently based on the provided key alone. No payload validation is performed — the same key always replays the cached response.
      Parameters:
      idempotencyKey - The unique key identifying the idempotent request.
      action - The business logic to execute if this is the first attempt.
      Returns:
      The cached response if previously completed, or the newly generated response.
      Throws:
      IdempotencyConflictException - If another request with the same key is currently processing.
      Exception - If the underlying action throws an exception.

    • execute

      public IdempotencyResponse execute(String idempotencyKey, byte[] requestBody, Callable<IdempotencyResponse> action) throws Exception
      Executes the given action idempotently, hashing the raw requestBody using the configured RequestHasher to detect key reuse with a different payload.

      This is the recommended overload for HTTP filters and interceptors that already buffer the request body for replay purposes.

      Parameters:
      idempotencyKey - The unique key identifying the idempotent request.
      requestBody - The raw bytes of the HTTP request body to hash and validate.
      action - The business logic to execute if this is the first attempt.
      Returns:
      The cached response if previously completed, or the newly generated response.
      Throws:
      IdempotencyConflictException - If another request with the same key is currently processing.
      IdempotencyMismatchException - If the request body hash doesn't match the stored hash.
      Exception - If the underlying action throws an exception.

    • execute

      public IdempotencyResponse execute(String idempotencyKey, String requestHash, Callable<IdempotencyResponse> action) throws Exception
      Executes the given action idempotently using a caller-supplied pre-computed hash string. Use this when the hash is already available (e.g. extracted from a signed request header).
      Parameters:
      idempotencyKey - The unique key identifying the idempotent request.
      requestHash - The pre-computed hash of the request payload; may be null to skip payload validation.
      action - The business logic to execute if this is the first attempt.
      Returns:
      The cached response if previously completed, or the newly generated response.
      Throws:
      IdempotencyConflictException - If another request with the same key is currently processing.
      IdempotencyMismatchException - If the request hash doesn't match the stored hash.
      Exception - If the underlying action throws an exception.