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;
018
019import org.jspecify.annotations.NonNull;
020import javax.annotation.concurrent.Immutable;
021import static java.util.Objects.requireNonNull;
022
023/**
024 * The outcome of one token revocation request.
025 * Non-transient endpoint client errors return a fixed rejection; transport, metadata, malformed responses and
026 * transient endpoint failures remain exceptions. Applications receive outcomes from the operation and cannot
027 * construct them. A later release may add variants; consuming switches should include a rejecting default.
028 * @author <a href="https://www.revetkn.com">Mark Allen</a>
029 * @since 1.0.0
030 */
031@Immutable
032public abstract sealed class OAuthRevocationResult permits OAuthRevocationResult.Succeeded, OAuthRevocationResult.Rejected {
033        OAuthRevocationResult() { }
034        static @NonNull OAuthRevocationResult fromSuccess() {
035                return new Succeeded();
036        }
037        static @NonNull OAuthRevocationResult fromEndpoint(@NonNull OAuthErrorResponseException failure) {
038                return new Rejected(OAuthEndpointError.fromWireValue(failure.getErrorCode().orElse("")), failure.getStatus());
039        }
040        /**
041         * Returns the outcome kind with all values redacted.
042         * @return redacted description
043         * @since 1.0.0
044         */
045        @Override
046        public final @NonNull String toString() {
047                return "OAuthRevocationResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
048        }
049        /**
050         * The endpoint accepted the revocation request; RFC 7009 also accepts unknown tokens.
051         * @author <a href="https://www.revetkn.com">Mark Allen</a>
052         * @since 1.0.0
053         */
054        @Immutable
055        public static final class Succeeded extends OAuthRevocationResult {
056                private Succeeded() { }
057        }
058        /**
059         * The endpoint returned a non-transient client error. No response body or credential is retained.
060         * @author <a href="https://www.revetkn.com">Mark Allen</a>
061         * @since 1.0.0
062         */
063        @Immutable
064        public static final class Rejected extends OAuthRevocationResult {
065                private final @NonNull OAuthEndpointError error;
066                private final int status;
067                private Rejected(@NonNull OAuthEndpointError error, int status) {
068                        this.error = requireNonNull(error); this.status = status;
069                }
070                /**
071                 * Returns the fixed endpoint error; unrecognized or absent codes use the same fallback.
072                 * @return fixed endpoint error
073                 * @since 1.0.0
074                 */
075                public @NonNull OAuthEndpointError getError() { return this.error; }
076                /**
077                 * Returns the endpoint's HTTP status.
078                 * @return endpoint status
079                 * @since 1.0.0
080                 */
081                public @NonNull Integer getStatus() { return this.status; }
082        }
083}