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 static java.util.Objects.requireNonNull;
020
021import com.revetsec.ErrorCategory;
022import com.revetsec.RevetsecException;
023
024import org.jspecify.annotations.NonNull;
025
026import javax.annotation.concurrent.Immutable;
027import javax.annotation.concurrent.NotThreadSafe;
028
029/**
030 * Fixed-diagnostic optional-cache failure, distinct from a miss or comparison conflict. Providers
031 * may throw this type without retaining backend messages or causes. A failed write may already have
032 * happened; cached data still requires core validation. This type supplies no authoritative-store
033 * outcome.
034 *
035 * @author <a href="https://www.revetkn.com">Mark Allen</a>
036 * @since 1.0.0
037 */
038@NotThreadSafe
039public final class OAuthClientMetadataCacheException extends RevetsecException {
040    private static final long serialVersionUID = 1L;
041
042    /** Fixed reason retained by this exception. */
043    private final OAuthClientMetadataCacheException.@NonNull Reason reason;
044
045    private OAuthClientMetadataCacheException(
046            OAuthClientMetadataCacheException.@NonNull Reason reason) {
047        super(
048                ErrorCategory.TRANSPORT,
049                requireNonNull(reason) != Reason.INTERRUPTED,
050                "Client metadata cache operation failed.",
051                null);
052        this.reason = reason;
053    }
054
055    /**
056     * Creates a fixed failure for an application cache provider; raw diagnostics and causes are not
057     * accepted.
058     *
059     * @param reason the fixed reason
060     * @return the provider failure
061     * @throws NullPointerException if reason is null
062     * @since 1.0.0
063     */
064    public static @NonNull OAuthClientMetadataCacheException fromReason(
065            OAuthClientMetadataCacheException.@NonNull Reason reason) {
066        return new OAuthClientMetadataCacheException(reason);
067    }
068
069    /**
070     * Returns the fixed failure reason.
071     *
072     * @return the reason
073     * @since 1.0.0
074     */
075    public OAuthClientMetadataCacheException.@NonNull Reason getReason() {
076        return this.reason;
077    }
078
079    /**
080     * The optional-cache failure reasons. Interrupted calls preserve the thread flag and are never
081     * transient.
082     *
083     * @author <a href="https://www.revetkn.com">Mark Allen</a>
084     * @since 1.0.0
085     */
086    @Immutable
087    public enum Reason {
088        /** The provider could not complete the operation. */
089        UNAVAILABLE,
090        /** The remaining operation budget elapsed. */
091        TIMEOUT,
092        /** The calling thread was interrupted. */
093        INTERRUPTED
094    }
095}