001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.auth.oauth;
018
019import java.security.*;
020import java.time.*;
021import java.util.*;
022
023import org.apache.juneau.rest.auth.oauth.flow.*;
024
025/**
026 * SPI for caching the result of an OAuth introspection or token-acquisition call.
027 *
028 * <p>
029 * Two value shapes are supported via dedicated entry types: validator-side caches store
030 * {@link CachedPrincipal} (used by {@link OAuthIntrospectionValidator}); flow-side caches store
031 * {@link OAuthToken}.  Implementations are not required to support both surfaces &mdash; a Redis-backed
032 * impl can serialize either via JSON, an in-memory impl can hold both.  The default impl
033 * {@link BoundedLruTokenCache} supports both.
034 *
035 * <p>
036 * Implementations must be thread-safe.
037 *
038 * @since 10.0.0
039 */
040public interface TokenCache {
041
042   /**
043    * Stores or replaces a principal entry.
044    *
045    * @param key The cache key (typically the opaque token string).  Never {@code null}.
046    * @param principal The principal to cache.  Never {@code null}.
047    * @param ttl The maximum cache lifetime relative to "now".  Must be positive.
048    */
049   void putPrincipal(String key, Principal principal, Duration ttl);
050
051   /**
052    * Retrieves a non-expired principal entry.
053    *
054    * @param key The cache key.
055    * @return The cached principal, or {@link Optional#empty()} if absent or expired.
056    */
057   Optional<Principal> getPrincipal(String key);
058
059   /**
060    * Stores or replaces a token entry.
061    *
062    * @param key The cache key (typically a stable key derived from the flow parameters).
063    * @param token The token to cache.  Never {@code null}.
064    */
065   void putToken(String key, OAuthToken token);
066
067   /**
068    * Retrieves a non-expired token entry.
069    *
070    * @param key The cache key.
071    * @param now The reference instant for expiry comparison.
072    * @param skew Skew tolerance subtracted from the entry's expiry.  Must be non-negative.
073    * @return The cached token, or {@link Optional#empty()} if absent or expired.
074    */
075   Optional<OAuthToken> getToken(String key, Instant now, Duration skew);
076
077   /**
078    * Removes the entry under the supplied key.  No-op if absent.
079    *
080    * @param key The cache key.
081    */
082   void invalidate(String key);
083
084   /**
085    * Returns the current entry count.  Primarily for tests and metrics.
086    *
087    * @return The entry count.
088    */
089   int size();
090}