001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.oauth.server; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020 021import org.jspecify.annotations.NonNull; 022import org.jspecify.annotations.Nullable; 023 024import java.time.Duration; 025import java.util.Optional; 026 027import javax.annotation.concurrent.ThreadSafe; 028 029/** 030 * Thread-safe storage for bounded encrypted client-metadata carriers. Applications may use shared 031 * infrastructure. Revetsec retains namespace/provenance, parsing, eligibility, HTTP freshness and 032 * operation-specific fresh-fetch checks. This interface provides no loader, parser, TTL override, 033 * client authority or authorization-store fallback. Calls honor the shrinking positive budget and 034 * interruption; providers run outside authoritative transactions. Revetsec cannot forcibly preempt 035 * application code. Failures throw rather than pretending to be misses/conflicts; an optional-cache 036 * failure permits only a bounded fresh retrieval within the original budget, never stale use. 037 * Providers bound capacity and storage work; eviction/expiry may create misses. The policy does 038 * not impose a cluster-wide capacity limit on a custom provider. Shared key namespaces must be stable across compatible engines and distinct 039 * across issuer/configuration identities. Persist fields exactly. 040 * 041 * @author <a href="https://www.revetkn.com">Mark Allen</a> 042 * @since 1.0.0 043 */ 044@ThreadSafe 045@CheckReturnValue 046public interface OAuthClientMetadataCache { 047 /** 048 * Reads storage data or a confirmed miss; a hit is not a validated document or fresh200 proof. 049 * 050 * @param key the exact bounded address 051 * @param remainingBudget the positive remaining budget 052 * @return the carrier or a confirmed miss 053 * @throws OAuthClientMetadataCacheException for provider failure, timeout or interruption 054 * @since 1.0.0 055 */ 056 @NonNull Optional<@NonNull OAuthClientMetadataCacheEntry> read( 057 @NonNull OAuthClientMetadataCacheKey key, @NonNull Duration remainingBudget); 058 059 /** 060 * Atomically compares the exact current version/absence and then replaces/removes the carrier 061 * at one key. Null expectedVersion requires absence; null replacement removes the matched 062 * entry. False changes nothing. Replacement keys must match and replacement versions must be 063 * fresh and differ from expectedVersion. A competing write cannot be overwritten using an 064 * obsolete version. After eviction/expiry, absence can permit a new insertion; this is not 065 * durable historical ordering. A failure may leave a mutation applied. This is optional 066 * storage, not credential consumption or a distributed lock; no outcome satisfies a fresh200 067 * requirement. 068 * 069 * @param key the exact address 070 * @param expectedVersion the canonical comparison version, or null for absence 071 * @param replacement the bounded replacement, or null to remove 072 * @param remainingBudget the positive remaining budget 073 * @return whether the atomic comparison matched and the operation completed 074 * @throws IllegalArgumentException for an invalid version, mismatched key or reused comparison 075 * version 076 * @throws OAuthClientMetadataCacheException for provider failure, timeout or interruption 077 * @since 1.0.0 078 */ 079 @NonNull Boolean compareAndSet( 080 @NonNull OAuthClientMetadataCacheKey key, 081 @Nullable String expectedVersion, 082 @Nullable OAuthClientMetadataCacheEntry replacement, 083 @NonNull Duration remainingBudget); 084}