Package at.aimon.session.web.spi.inmemory

Class InMemoryIdempotencyStore

java.lang.Object
at.aimon.session.web.spi.inmemory.InMemoryIdempotencyStore
All Implemented Interfaces:
IdempotencyStore
public final class InMemoryIdempotencyStore extends Object implements IdempotencyStore
Single-process IdempotencyStore backed by a ConcurrentMap.

Expiry is checked lazily at every find(java.lang.String) / putIfAbsent(java.lang.String, at.aimon.session.web.spi.IdempotencyEntry, java.time.Duration) call. Suitable for SINGLE_NODE deployments and unit tests; not optimized for high churn.

  • Constructor Details

    • InMemoryIdempotencyStore

      public InMemoryIdempotencyStore()

    • InMemoryIdempotencyStore

      public InMemoryIdempotencyStore(Clock clock)

  • Method Details

    • putIfAbsent

      public PutResult putIfAbsent(String key, IdempotencyEntry entry, Duration ttl)
      Description copied from interface: IdempotencyStore
      Insert entry only if no entry exists for key. Atomic.

      For IdempotencyEntry.Status.IN_FLIGHT entries, ttl is the secondary TTL (~lease length, ~30s); upon IdempotencyStore.markDone(java.lang.String, at.aimon.core.agent.AgentExecutionResult), the implementation switches to the longer primary TTL (typically 24h).

      Specified by:
      putIfAbsent in interface IdempotencyStore
      Parameters:
      key - the idempotency key (must not be null)
      entry - the candidate entry (must not be null)
      ttl - initial TTL (must not be null)
      Returns:
      PutResult.inserted() on success, or PutResult.existing(IdempotencyEntry) when an entry already exists

    • markDone

      public void markDone(String key, at.aimon.core.agent.AgentExecutionResult result)
      Description copied from interface: IdempotencyStore
      Transition an in-flight entry to IdempotencyEntry.Status.DONE and cache its result. Refreshes TTL to the primary value.
      Specified by:
      markDone in interface IdempotencyStore
      Parameters:
      key - the idempotency key (must not be null)
      result - the final agent execution result (must not be null)

    • find

      public Optional<IdempotencyEntry> find(String key)
      Description copied from interface: IdempotencyStore
      Look up an entry by key.
      Specified by:
      find in interface IdempotencyStore
      Parameters:
      key - the idempotency key (must not be null)
      Returns:
      the entry, or empty when none exists or it has expired

    • touch

      public boolean touch(String key, String holderId)
      Description copied from interface: IdempotencyStore
      Refresh the secondary TTL of an in-flight entry. Called from the lease renewer.
      Specified by:
      touch in interface IdempotencyStore
      Parameters:
      key - the idempotency key (must not be null)
      holderId - the calling holder; the touch is silently ignored when this does not match the entry's holder
      Returns:
      true when the touch was applied

    • compareAndReset

      public boolean compareAndReset(String key, String expectedHolderId)
      Description copied from interface: IdempotencyStore
      Atomically reset (or transition to FAILED) a stale in-flight entry held by expectedHolderId. Two sweepers racing on the same stale entry must produce exactly one winner.
      Specified by:
      compareAndReset in interface IdempotencyStore
      Parameters:
      key - the idempotency key (must not be null)
      expectedHolderId - the holder id observed by the calling sweeper (must not be null)
      Returns:
      true when this caller won the race and reset the entry

    • findStaleInFlight

      public List<IdempotencyEntry> findStaleInFlight(Instant cutoff)
      Description copied from interface: IdempotencyStore
      Enumerate in-flight entries whose lastTouchedAt is older than cutoff.

      Implementations may use SCAN + per-entry TTL inspection (Redis) or a simple map walk (in-memory). Used by the holder-loss sweeper.

      Specified by:
      findStaleInFlight in interface IdempotencyStore
      Parameters:
      cutoff - entries with lastTouchedAt < cutoff are returned (must not be null)
      Returns:
      matching entries (never null; may be empty)