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;
020import org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022import javax.annotation.concurrent.Immutable;
023import java.time.Instant;
024import java.time.Duration;
025import java.util.List;
026import java.util.Optional;
027import static java.util.Objects.requireNonNull;
028
029/**
030 * Application-owned authoritative issuer persistence. Implementations must be safe across callers and nodes.
031 * Reads are linearizable; commits atomically check every condition before applying all mutations and return
032 * a contextual COMMITTED receipt only after durability under the application's deployment contract. CONFLICT has zero effects;
033 * a lost connection with uncertain outcome returns UNKNOWN, never a guessed conflict or success.
034 * Condition-only commits are required atomic read-set barriers. TIMED commits validate fresh authority time
035 * after all waits and exact predicates, lower/upper bounds before capacity or mutation. FENCE_ONLY is
036 * restricted to the transaction type's two existing permanent-fence epoch transitions. Reads and failed
037 * writes perform no cleanup. Missing established roots cannot be recreated as a fresh namespace.
038 * All time and admission facts are backend-owned; no worker clock fallback is permitted. No callback executes inside a transaction.
039 * Providers honor the remaining budget and preserve permanent fences and retained replay tombstones:
040 * capacity pressure rejects work rather than evicting active records. Revetsec cannot forcibly preempt
041 * blocked application code. This interface supplies no database, durability or rollback detection by itself.
042 * @author <a href="https://www.revetkn.com">Mark Allen</a>
043 *
044 * @since 1.0.0
045 */
046@javax.annotation.concurrent.ThreadSafe
047@CheckReturnValue
048public interface OAuthAuthorizationServerStore {
049 /**
050  * Reads an authoritative entry or confirmed absence with coherent admitted time, preserving every transport field exactly.
051  * Infrastructure failure is unavailable, never translated into absence. Do not include record data in diagnostics.
052  * @param key the exact address
053  * @param remainingBudget the remaining positive operation budget
054  * @return the coherent available, fenced or unavailable observation
055  * @since 1.0.0
056  */
057 @NonNull OAuthStoreReadResult read(@NonNull OAuthStoreKey key,
058   @NonNull Duration remainingBudget);
059 /**
060  * Atomically checks the complete predicate set and applies the complete mutation set.
061  * Zero mutations still checks all predicates at one linearization point. Never partially apply writes.
062  * @param transaction the immutable engine-created transaction
063  * @param remainingBudget the remaining positive operation budget
064  * @return the actual durable, conflict or uncertain outcome
065  * @since 1.0.0
066  */
067 @NonNull OAuthStoreCommitReceipt commit(@NonNull OAuthStoreTransaction transaction,
068   @NonNull Duration remainingBudget);
069}