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 org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021import com.google.errorprone.annotations.CheckReturnValue;
022import javax.annotation.concurrent.Immutable;
023import java.util.Optional;
024import static java.util.Objects.requireNonNull;
025import javax.annotation.concurrent.ThreadSafe;
026import java.time.Duration;
027
028/**
029 * Safe synchronous caller-thread issuer events. Hooks run outside held locks and transactions and must be fast
030 * and thread-safe. Failures are contained except VirtualMachineError; interruption is restored. No event includes
031 * a client, subject, grant, credential, key identifier, URL, request or claims. Exactly one terminal hook follows
032 * each will hook during ordinary completion; status is absent only for validation or trusted management work.
033 * Terminal events describe the processing checkpoint before that hook runs. A hook that delays return or
034 * changes admission/clock health can still cause a subsequent release check to withhold normal output;
035 * that withholding does not emit a second terminal event. A successful event is not a delivery receipt.
036 * @since 1.0.0
037 */
038@ThreadSafe
039public interface OAuthServerObserver {
040        /** Returns the shared observer whose hooks do nothing.
041         * @return disabled observer
042         * @since 1.0.0
043         */
044        @CheckReturnValue static @NonNull OAuthServerObserver disabledInstance() { return DisabledOAuthServerObserver.INSTANCE; }
045        /** Called once after successful construction when the port-less HTTP localhost any-port option is enabled.
046         * This event carries no configuration or request data.
047         * @since 1.0.0
048         */
049        default void didEnableLocalhostAnyPortRedirects() {}
050        /** Called once per authorization operation that relies on port-less HTTP localhost any-port matching.
051         * It runs before store work, even if a later admission check rejects the request. Exact matches allowed by
052         * the separate exact-localhost option do not use this relaxation. This event carries no request data.
053         * @since 1.0.0
054         */
055        default void didUseLocalhostAnyPortRedirects() {}
056        /** Called before handling an operation.
057         * @param endpoint fixed operation kind
058         * @since 1.0.0
059         */
060        default void willHandleEndpoint(@NonNull Endpoint endpoint) {}
061        /** Called after ordinary successful completion.
062         * @param endpoint fixed operation kind
063         * @param statusCode HTTP status or null for non-HTTP work
064         * @param elapsed monotonic elapsed duration
065         * @since 1.0.0
066         */
067        default void didHandleEndpoint(@NonNull Endpoint endpoint, @Nullable Integer statusCode, @NonNull Duration elapsed) {}
068        /** Called after an expected rejection, including explicit application denial.
069         * @param endpoint fixed operation kind
070         * @param reason fixed rejection reason
071         * @param statusCode HTTP status or null for non-HTTP work
072         * @param elapsed monotonic elapsed duration
073         * @since 1.0.0
074         */
075        default void didRejectEndpoint(@NonNull Endpoint endpoint, OAuthServerException.@NonNull Reason reason,
076                @Nullable Integer statusCode, @NonNull Duration elapsed) {}
077        /** Called after infrastructure failure; the same fixed exception reaches the caller.
078         * @param endpoint fixed operation kind
079         * @param failure fixed exception without external causes
080         * @param elapsed monotonic elapsed duration
081         * @since 1.0.0
082         */
083        default void didFailToHandleEndpoint(@NonNull Endpoint endpoint, @NonNull OAuthServerException failure, @NonNull Duration elapsed) {}
084        /** Fixed operation kinds, without request or application data.
085         * @since 1.0.0
086         */
087        @Immutable enum Endpoint {
088                /** Browser interaction work. */ AUTHORIZATION,
089                /** Code or refresh exchange. */ TOKEN,
090                /** Explicit fresh deployment initialization. */ ISSUER_INITIALIZATION,
091                /** Explicit first subject registration. */ SUBJECT_REGISTRATION,
092                /** Credential revocation. */ REVOCATION,
093                /** Registered-resource introspection. */ INTROSPECTION,
094                /** Public issuer metadata. */ METADATA,
095                /** Public verification keys. */ JWKS,
096                /** Online issuer access-token validation. */ ACCESS_TOKEN_VALIDATION,
097                /** Trusted grant invalidation. */ GRANT_REVOCATION,
098                /** Trusted subject invalidation. */ SUBJECT_REVOCATION,
099                /** Trusted issuer-wide invalidation. */ ISSUER_REVOCATION,
100                /** Trusted store maintenance. */ STORE_RESEAL
101        }
102}
103final class DisabledOAuthServerObserver implements OAuthServerObserver {
104        static final @NonNull OAuthServerObserver INSTANCE=new DisabledOAuthServerObserver();
105        private DisabledOAuthServerObserver() {}
106}