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 a cached client-credentials token acquisition.
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 AccessTokenAcquisitionResult permits AccessTokenAcquisitionResult.Succeeded, AccessTokenAcquisitionResult.Rejected {
033        AccessTokenAcquisitionResult() { }
034        static @NonNull AccessTokenAcquisitionResult fromAccessToken(@NonNull AccessToken accessToken) {
035                return new Succeeded(requireNonNull(accessToken));
036        }
037        static AccessTokenAcquisitionResult.@NonNull Rejected fromRejection(OAuthTokenRequestResult.@NonNull Rejected rejection) {
038                return new Rejected(rejection.getError(), rejection.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 "AccessTokenAcquisitionResult{outcome=" + getClass().getSimpleName() + ", data=<redacted>}";
048        }
049        /**
050         * The source returned a currently valid access token, from its cache or a completed renewal.
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 AccessTokenAcquisitionResult {
056                private final @NonNull AccessToken value;
057                private Succeeded(@NonNull AccessToken value) { this.value = requireNonNull(value); }
058                /**
059                 * Returns the value released after all operation checks passed.
060                 * @return checked value
061                 * @since 1.0.0
062                 */
063                public @NonNull AccessToken getAccessToken() { return this.value; }
064        }
065        /**
066         * The endpoint returned a non-transient client error. No response body or credential is retained.
067         * @author <a href="https://www.revetkn.com">Mark Allen</a>
068         * @since 1.0.0
069         */
070        @Immutable
071        public static final class Rejected extends AccessTokenAcquisitionResult {
072                private final @NonNull OAuthEndpointError error;
073                private final int status;
074                private Rejected(@NonNull OAuthEndpointError error, int status) {
075                        this.error = requireNonNull(error); this.status = status;
076                }
077                /**
078                 * Returns the fixed endpoint error; unrecognized or absent codes use the same fallback.
079                 * @return fixed endpoint error
080                 * @since 1.0.0
081                 */
082                public @NonNull OAuthEndpointError getError() { return this.error; }
083                /**
084                 * Returns the endpoint's HTTP status.
085                 * @return endpoint status
086                 * @since 1.0.0
087                 */
088                public @NonNull Integer getStatus() { return this.status; }
089        }
090}