001/*
002 * Copyright 2022-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.soklet;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import java.util.function.Consumer;
023import java.util.function.Function;
024
025import static java.util.Objects.requireNonNull;
026
027/**
028 * Hook methods that can adjust Soklet's request processing flow.
029 * <p>
030 * A standard threadsafe implementation can be acquired via {@link #defaultInstance()}.
031 *
032 * @author <a href="https://www.revetkn.com">Mark Allen</a>
033 */
034public interface RequestInterceptor {
035        /**
036         * Called before Soklet begins request processing, allowing the request to be wrapped or replaced.
037         * <p>
038         * Routing happens after this callback, so changes to the HTTP method or path affect which
039         * <em>Resource Method</em> is selected.
040         * <p>
041         * You must call {@code requestProcessor.accept(...)} exactly once before returning to advance processing.
042         * If you do not, Soklet logs the error and returns a 500 response.
043         * <p>
044         * This method <strong>is not</strong> fail-fast. If an exception occurs when Soklet invokes this method,
045         * Soklet will catch it and surface separately via {@link LifecycleObserver#didReceiveLogEvent(LogEvent)}
046         * with type {@link LogEventType#REQUEST_INTERCEPTOR_WRAP_REQUEST_FAILED}.
047         *
048         * @param serverType      the server type that received the request
049         * @param request         the request that was received
050         * @param requestProcessor receives the request to use for subsequent processing
051         */
052        default void wrapRequest(@NonNull ServerType serverType,
053                                                                                                         @NonNull Request request,
054                                                                                                         @NonNull Consumer<Request> requestProcessor) {
055                requireNonNull(serverType);
056                requireNonNull(request);
057                requireNonNull(requestProcessor);
058                requestProcessor.accept(request);
059        }
060
061        /**
062         * Intercepts request processing, allowing the request to be replaced and/or the response to be transformed.
063         * <p>
064         * This method <strong>is not</strong> fail-fast. If an exception occurs when Soklet invokes this method,
065         * Soklet will catch it and surface separately via {@link LifecycleObserver#didReceiveLogEvent(LogEvent)}
066         * with type {@link LogEventType#REQUEST_INTERCEPTOR_INTERCEPT_REQUEST_FAILED}.
067         * <p>
068         * You must call {@code responseWriter.accept(...)} exactly once before returning to send a response.
069         * If you do not, Soklet logs the error and returns a 500 response.
070         * <p>
071         * This contract is synchronous: perform all request processing — including the
072         * {@code responseWriter.accept(...)} call — on the thread that invoked this method, before returning.
073         * Do not offload the {@code responseGenerator} or {@code responseWriter} invocations to another thread:
074         * Soklet's request lifecycle bookkeeping (for example, metrics correlation and timeout handling)
075         * is thread-affine to the request-handler thread.
076         *
077         * @param serverType                the server type that received the request
078         * @param request                   the request that was received
079         * @param resourceMethod            the <em>Resource Method</em> that will handle the request
080         * @param responseGenerator         function that performs standard request handling and returns a response
081         * @param responseWriter            receives the response to send to the client
082         */
083        default void interceptRequest(@NonNull ServerType serverType,
084                                                                                                                                        @NonNull Request request,
085                                                                                                                                        @Nullable ResourceMethod resourceMethod,
086                                                                                                                                        @NonNull Function<Request, MarshaledResponse> responseGenerator,
087                                                                                                                                        @NonNull Consumer<MarshaledResponse> responseWriter) {
088                requireNonNull(serverType);
089                requireNonNull(request);
090                requireNonNull(responseGenerator);
091                requireNonNull(responseWriter);
092                responseWriter.accept(responseGenerator.apply(request));
093        }
094
095        /**
096         * Acquires a threadsafe {@link RequestInterceptor} instance with sensible defaults.
097         * <p>
098         * The returned instance is guaranteed to be a JVM-wide singleton.
099         *
100         * @return a {@code RequestInterceptor} with default settings
101         */
102        @NonNull
103        static RequestInterceptor defaultInstance() {
104                return DefaultRequestInterceptor.defaultInstance();
105        }
106}