Package at.aimon.session.web.spi

Interface IdempotencyStore

All Known Implementing Classes:

InMemoryIdempotencyStore

public interface IdempotencyStore

Idempotency store SPI per design §9.2.

Tracks IdempotencyEntrys keyed by client-supplied idempotency key. Provides atomic putIfAbsent for first-arrival detection, markDone for caching the final result, and a small set of operations needed by the holder-loss sweeper (touch(java.lang.String, java.lang.String), compareAndReset(java.lang.String, java.lang.String), findStaleInFlight(java.time.Instant)).

Method Summary

Modifier and Type	Method	Description
boolean	compareAndReset(String key, String expectedHolderId)	Atomically reset (or transition to FAILED) a stale in-flight entry held by expectedHolderId.
Optional<IdempotencyEntry>	find(String key)	Look up an entry by key.
List<IdempotencyEntry>	findStaleInFlight(Instant cutoff)	Enumerate in-flight entries whose lastTouchedAt is older than cutoff.
void	markDone(String key, at.aimon.core.agent.AgentExecutionResult result)	Transition an in-flight entry to IdempotencyEntry.Status.DONE and cache its result.
PutResult	putIfAbsent(String key, IdempotencyEntry entry, Duration ttl)	Insert entry only if no entry exists for key.
boolean	touch(String key, String holderId)	Refresh the secondary TTL of an in-flight entry.

Method Details

putIfAbsent

PutResult putIfAbsent(String key,
 IdempotencyEntry entry,
 Duration ttl)

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 markDone(java.lang.String, at.aimon.core.agent.AgentExecutionResult), the implementation switches to the longer primary TTL (typically 24h).

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

void markDone(String key,
 at.aimon.core.agent.AgentExecutionResult result)

Transition an in-flight entry to IdempotencyEntry.Status.DONE and cache its result. Refreshes TTL to the primary value.

Parameters:

key - the idempotency key (must not be null)

result - the final agent execution result (must not be null)

find

Optional<IdempotencyEntry> find(String key)

Look up an entry by key.

Parameters:

key - the idempotency key (must not be null)

Returns:

the entry, or empty when none exists or it has expired

touch

boolean touch(String key,
 String holderId)

Refresh the secondary TTL of an in-flight entry. Called from the lease renewer.

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

boolean compareAndReset(String key,
 String expectedHolderId)

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.

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

List<IdempotencyEntry> findStaleInFlight(Instant cutoff)

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.

Parameters:

cutoff - entries with lastTouchedAt < cutoff are returned (must not be null)

Returns:

matching entries (never null; may be empty)