Interface OAuthClientMetadataCache

All Known Implementing Classes:
InMemoryOAuthClientMetadataCache

@ThreadSafe @CheckReturnValue public interface OAuthClientMetadataCache
Thread-safe storage for bounded encrypted client-metadata carriers. Applications may use shared infrastructure. Revetsec retains namespace/provenance, parsing, eligibility, HTTP freshness and operation-specific fresh-fetch checks. This interface provides no loader, parser, TTL override, client authority or authorization-store fallback. Calls honor the shrinking positive budget and interruption; providers run outside authoritative transactions. Revetsec cannot forcibly preempt application code. Failures throw rather than pretending to be misses/conflicts; an optional-cache failure permits only a bounded fresh retrieval within the original budget, never stale use. Providers bound capacity and storage work; eviction/expiry may create misses. The policy does not impose a cluster-wide capacity limit on a custom provider. Shared key namespaces must be stable across compatible engines and distinct across issuer/configuration identities. Persist fields exactly.
Since:
1.0.0
Author:
Mark Allen
  • Method Details

    • read

      Reads storage data or a confirmed miss; a hit is not a validated document or fresh200 proof.
      Parameters:
      key - the exact bounded address
      remainingBudget - the positive remaining budget
      Returns:
      the carrier or a confirmed miss
      Throws:
      OAuthClientMetadataCacheException - for provider failure, timeout or interruption
      Since:
      1.0.0
    • compareAndSet

      Atomically compares the exact current version/absence and then replaces/removes the carrier at one key. Null expectedVersion requires absence; null replacement removes the matched entry. False changes nothing. Replacement keys must match and replacement versions must be fresh and differ from expectedVersion. A competing write cannot be overwritten using an obsolete version. After eviction/expiry, absence can permit a new insertion; this is not durable historical ordering. A failure may leave a mutation applied. This is optional storage, not credential consumption or a distributed lock; no outcome satisfies a fresh200 requirement.
      Parameters:
      key - the exact address
      expectedVersion - the canonical comparison version, or null for absence
      replacement - the bounded replacement, or null to remove
      remainingBudget - the positive remaining budget
      Returns:
      whether the atomic comparison matched and the operation completed
      Throws:
      IllegalArgumentException - for an invalid version, mismatched key or reused comparison version
      OAuthClientMetadataCacheException - for provider failure, timeout or interruption
      Since:
      1.0.0