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.oidc;
018
019import com.revetsec.ErrorCategory;
020import com.revetsec.RevetsecException;
021import org.jspecify.annotations.NonNull;
022import javax.annotation.concurrent.Immutable;
023import javax.annotation.concurrent.NotThreadSafe;
024import static java.util.Objects.requireNonNull;
025
026/**
027 * A fixed configuration, preparation, storage or runtime failure in RP-Initiated Logout.
028 * No token, input, provider exception, cause or suppressed value is retained. Local session termination remains
029 * the application's responsibility and is never undone by this failure. No automatic retry is performed.
030 * @author <a href="https://www.revetkn.com">Mark Allen</a>
031 * @since 1.0.0
032 */
033@NotThreadSafe
034public final class OidcLogoutException extends RevetsecException {
035        private static final long serialVersionUID = 1L;
036        /** The fixed reason retained when serialized. */
037        private final @NonNull Reason reason;
038        private OidcLogoutException(@NonNull Reason reason) {
039                super(requireNonNull(reason).category, reason == Reason.BUDGET_EXHAUSTED || reason == Reason.DISCOVERY_UNAVAILABLE, reason.message, null);
040                this.reason = reason;
041        }
042        static @NonNull OidcLogoutException fromReason(@NonNull Reason reason) { return new OidcLogoutException(reason); }
043        /** Returns the fixed failure reason.
044         * @return reason
045         * @since 1.0.0
046         */
047        public @NonNull Reason getReason() { return this.reason; }
048        /**
049         * Fixed reasons. Future releases may add reasons; switches should include a rejecting default branch.
050         * @author <a href="https://www.revetkn.com">Mark Allen</a>
051         * @since 1.0.0
052         */
053        @Immutable
054        public enum Reason {
055                /** No fixed post-logout callback was configured. */
056                LOGOUT_NOT_CONFIGURED(ErrorCategory.CONFIGURATION, "OIDC logout is not configured."),
057                /** The provider does not advertise the selected logout endpoint. */
058                END_SESSION_UNSUPPORTED(ErrorCategory.UNSUPPORTED, "The provider does not support the selected logout request."),
059                /** The endpoint failed URI or reserved-parameter policy. */
060                ENDPOINT_NOT_PERMITTED(ErrorCategory.CONFIGURATION, "The OIDC logout endpoint is not permitted."),
061                /** A hint or authenticated source belongs to a different client or original reference. */
062                HINT_MISMATCH(ErrorCategory.CONFIGURATION, "The OIDC logout hint does not match the client and original reference."),
063                /** A selected logout representation exceeded its fixed profile. */
064                INPUT_LIMIT(ErrorCategory.CONFIGURATION, "The OIDC logout value exceeds its selected profile."),
065                /** The configured sealer cannot represent this bounded hint or pending record. */
066                STORAGE_PROFILE_UNSUPPORTED(ErrorCategory.CONFIGURATION, "The configured storage profile cannot represent OIDC logout state."),
067                /** A trusted clock, entropy, policy or sealing provider could not complete the operation. */
068                PROVIDER_UNAVAILABLE(ErrorCategory.CONFIGURATION, "The OIDC logout operation is unavailable."),
069                /** A transport or held-back discovery attempt did not complete. */
070                DISCOVERY_UNAVAILABLE(ErrorCategory.TRANSPORT, "OIDC logout discovery is unavailable."),
071                /** A store call may have consumed the pending record; safe retry is not established. */
072                STORE_INDETERMINATE(ErrorCategory.CONFIGURATION, "The OIDC logout store outcome is indeterminate."),
073                /** The original operation budget is exhausted. */
074                BUDGET_EXHAUSTED(ErrorCategory.TRANSPORT, "The OIDC logout budget is exhausted."),
075                /** The calling thread remains interrupted. */
076                INTERRUPTED(ErrorCategory.TRANSPORT, "The OIDC logout operation was interrupted.");
077                private final @NonNull ErrorCategory category;
078                private final @NonNull String message;
079                Reason(@NonNull ErrorCategory category, @NonNull String message) { this.category = category; this.message = message; }
080        }
081}