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 com.revetsec.jose.JoseObserver;
020import org.jspecify.annotations.NonNull;
021
022import javax.annotation.concurrent.ThreadSafe;
023import java.net.URI;
024import java.time.Duration;
025
026/**
027 * Receives synchronous, caller-thread OAuth events. Endpoint URIs contain only scheme, host, port and path;
028 * callbacks and request bodies are never passed. Implementations must be thread-safe and fast. A hook failure is
029 * contained by the caller except for {@link VirtualMachineError}.
030 *
031 * @author <a href="https://www.revetkn.com">Mark Allen</a>
032 * @since 1.0.0
033 */
034@ThreadSafe
035public interface OAuthObserver extends JoseObserver {
036        /**
037         * Returns an observer whose hooks do nothing.
038         *
039         * @return the disabled observer
040         * @since 1.0.0
041         */
042        @NonNull
043        static OAuthObserver disabledInstance() { return DisabledOAuthObserver.INSTANCE; }
044
045        /**
046         * Called after a browser authorization URL is prepared.
047         *
048         * @param endpoint its reduced endpoint URI
049         * @since 1.0.0
050         */
051        default void didBeginAuthorization(@NonNull URI endpoint) { }
052
053        /**
054         * Called before an OAuth endpoint request.
055         *
056         * @param endpoint endpoint kind
057         * @param uri its reduced URI
058         * @since 1.0.0
059         */
060        default void willRequestEndpoint(@NonNull OAuthEndpoint endpoint, @NonNull URI uri) { }
061
062        /**
063         * Called after a completed endpoint request.
064         *
065         * @param endpoint endpoint kind
066         * @param uri its reduced URI
067         * @param status HTTP status
068         * @param elapsed elapsed duration
069         * @since 1.0.0
070         */
071        default void didRequestEndpoint(@NonNull OAuthEndpoint endpoint, @NonNull URI uri,
072                        @NonNull Integer status, @NonNull Duration elapsed) { }
073
074        /**
075         * Called when an endpoint request fails. The exception is the same instance the caller receives.
076         *
077         * @param endpoint endpoint kind
078         * @param uri its reduced URI
079         * @param exception fixed-message exception
080         * @param elapsed elapsed duration
081         * @since 1.0.0
082         */
083        default void didFailEndpoint(@NonNull OAuthEndpoint endpoint, @NonNull URI uri,
084                        @NonNull OAuthException exception, @NonNull Duration elapsed) { }
085
086        /**
087         * Called when a callback fails a local validation check.
088         *
089         * @param exception fixed-message exception
090         * @since 1.0.0
091         */
092        default void didRejectCallback(@NonNull OAuthValidationException exception) { }
093
094        /**
095         * Called when the explicit unencoded Basic interoperability mode is configured and on every request using it.
096         * No credential value is passed.
097         *
098         * @since 1.0.0
099         */
100        default void didUseUnencodedBasic() { }
101        /**
102         * Called once after a client successfully enables endpoint-audience assertion compatibility.
103         * @param audience TOKEN_ENDPOINT compatibility selection
104         * @since 1.0.0
105         */
106        default void didEnableClientAssertionAudience(@NonNull ClientAssertionAudience audience) { }
107        /**
108         * Called when endpoint-audience compatibility is selected for an actual assertion operation, including failure.
109         * @param audience TOKEN_ENDPOINT compatibility selection
110         * @since 1.0.0
111         */
112        default void didUseClientAssertionAudience(@NonNull ClientAssertionAudience audience) { }
113        /**
114         * Called once for assertion preparation failure before any endpoint will event. The same fixed-message
115         * exception is received by the caller; no assertion or key is passed.
116         * @param endpoint selected POST role
117         * @param exception preparation failure
118         * @since 1.0.0
119         */
120        default void didFailClientAssertionPreparation(@NonNull OAuthEndpoint endpoint, @NonNull OAuthException exception) { }
121
122}