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}