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 com.revetsec.StoreTimeObservation; 021import org.jspecify.annotations.NonNull; 022import org.jspecify.annotations.Nullable; 023import javax.annotation.concurrent.Immutable; 024import java.util.Optional; 025import static java.util.Objects.requireNonNull; 026 027/** 028 * Coherent linearizable issuer entry/absence and admitted time metadata. 029 * Unavailable or fenced observations never establish absence. 030 * @since 1.0.0 031 */ 032@Immutable 033@CheckReturnValue 034public sealed interface OAuthStoreReadResult permits OAuthStoreReadResult.Available, 035 OAuthStoreReadResult.Fenced, OAuthStoreReadResult.Unavailable { 036 /** The exact requested address, entry/absence and metadata from one atomic observation. 037 * @since 1.0.0 */ 038 @Immutable 039 @CheckReturnValue 040 final class Available implements OAuthStoreReadResult { 041 private final @NonNull OAuthStoreKey key; 042 private final @Nullable OAuthStoreEntry entry; 043 private final @NonNull StoreTimeObservation timeObservation; 044 private Available(@NonNull OAuthStoreKey key, @Nullable OAuthStoreEntry entry, 045 @NonNull StoreTimeObservation timeObservation) { 046 this.key=requireNonNull(key); this.timeObservation=requireNonNull(timeObservation); 047 if(entry!=null && !key.equals(entry.getKey())) throw OAuthStoreFormat.invalid(); 048 this.entry=entry; 049 } 050 /** Retains one exact coherent backend observation without authenticating its bytes. 051 * @param key the requested address 052 * @param entry the exact entry, or null for confirmed absence 053 * @param timeObservation coherent authority/admission metadata 054 * @return the available observation 055 * @throws NullPointerException if key or metadata is null 056 * @throws IllegalArgumentException if entry has another address 057 * @since 1.0.0 */ 058 public static OAuthStoreReadResult.@NonNull Available fromObservation(@NonNull OAuthStoreKey key, 059 @Nullable OAuthStoreEntry entry, @NonNull StoreTimeObservation timeObservation) { 060 return new Available(key,entry,timeObservation); 061 } 062 /** Returns the exact requested address. 063 * @return the address 064 * @since 1.0.0 */ 065 public @NonNull OAuthStoreKey getKey(){return this.key;} 066 /** Returns the entry or confirmed absence. 067 * @return the optional entry 068 * @since 1.0.0 */ 069 public @NonNull Optional<@NonNull OAuthStoreEntry> getEntry(){return Optional.ofNullable(this.entry);} 070 /** Returns coherent authority metadata, which need not include healthy time. 071 * @return the observation 072 * @since 1.0.0 */ 073 public @NonNull StoreTimeObservation getTimeObservation(){return this.timeObservation;} 074 /** Redacts every entry, identity and time. 075 * @return a fixed description 076 * @since 1.0.0 */ 077 @Override public @NonNull String toString(){return "Available{observation=<redacted>}";} 078 } 079 /** The requested recovery/data incarnation cannot be served. 080 * @since 1.0.0 */ 081 @Immutable 082 @CheckReturnValue 083 final class Fenced implements OAuthStoreReadResult { 084 private static final @NonNull Fenced INSTANCE=new Fenced(); 085 private Fenced(){} 086 /** Returns the fixed refusal. 087 * @return the fenced refusal 088 * @since 1.0.0 */ 089 public static OAuthStoreReadResult.@NonNull Fenced get(){return INSTANCE;} 090 /** Redacts state. 091 * @return a fixed description 092 * @since 1.0.0 */ 093 @Override public @NonNull String toString(){return "Fenced{}";} 094 } 095 /** No coherent authoritative observation could be established. 096 * @since 1.0.0 */ 097 @Immutable 098 @CheckReturnValue 099 final class Unavailable implements OAuthStoreReadResult { 100 private static final @NonNull Unavailable INSTANCE=new Unavailable(); 101 private Unavailable(){} 102 /** Returns the fixed refusal. 103 * @return the unavailable refusal 104 * @since 1.0.0 */ 105 public static OAuthStoreReadResult.@NonNull Unavailable get(){return INSTANCE;} 106 /** Redacts state. 107 * @return a fixed description 108 * @since 1.0.0 */ 109 @Override public @NonNull String toString(){return "Unavailable{}";} 110 } 111}