Package com.tnsai.idempotency

Interface IdempotencyStore

All Known Implementing Classes:

InMemoryIdempotencyStore, PostgresIdempotencyStore, RedisIdempotencyStore

public interface IdempotencyStore

SPI for persisting IdempotencyEntrys keyed by their idempotency key (issue #91).

Implementations range from InMemoryIdempotencyStore (default, ephemeral, per-process) to future Redis / Postgres adapters (distributed, survives restarts). The contract is intentionally narrow — get / put / invalidate — so future adapters can use whatever storage primitive fits (Redis SETEX, Postgres row with expires_at column, etc.).

Thread safety

Implementations MUST be safe to call concurrently. A single chat turn may trigger parallel tool calls that each consult the store.

TTL semantics

put(java.lang.String, com.tnsai.idempotency.IdempotencyEntry, java.time.Duration) accepts a per-entry TTL. Implementations are responsible for returning Optional.empty() from get(java.lang.String) once the TTL has elapsed, even if the entry is still physically present.

Since:

0.5.0 (issue #91)

Method Summary

Modifier and Type	Method	Description
Optional<IdempotencyEntry>	get(String key)	Look up a cached entry.
void	invalidate(String key)	Remove the entry for key if any.
void	put(String key, IdempotencyEntry entry, Duration ttl)	Store an entry under key with the given TTL.
int	size()	Approximate entry count.

Method Details

get

Optional<IdempotencyEntry> get(String key)

Look up a cached entry. Returns empty when no entry exists OR when the entry's TTL has elapsed.

put

void put(String key,
 IdempotencyEntry entry,
 Duration ttl)

Store an entry under key with the given TTL. Subsequent get(java.lang.String) calls within the TTL window return this entry. Overwrites any prior entry for the same key.

Throws:

NullPointerException - if any arg is null

IllegalArgumentException - if ttl is zero or negative

invalidate

void invalidate(String key)

Remove the entry for key if any. No-op if the key is not present.

size

int size()

Approximate entry count. Intended for monitoring / smoke-testing ("cache has grown to 10M entries, check your TTL"). Implementations may return an eventually-consistent snapshot.