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         *
071         * @param serverType                the server type that received the request
072         * @param request                   the request that was received
073         * @param resourceMethod            the <em>Resource Method</em> that will handle the request
074         * @param responseGenerator         function that performs standard request handling and returns a response
075         * @param responseWriter            receives the response to send to the client
076         */
077        default void interceptRequest(@NonNull ServerType serverType,
078                                                                                                                                        @NonNull Request request,
079                                                                                                                                        @Nullable ResourceMethod resourceMethod,
080                                                                                                                                        @NonNull Function<Request, MarshaledResponse> responseGenerator,
081                                                                                                                                        @NonNull Consumer<MarshaledResponse> responseWriter) {
082                requireNonNull(serverType);
083                requireNonNull(request);
084                requireNonNull(responseGenerator);
085                requireNonNull(responseWriter);
086                responseWriter.accept(responseGenerator.apply(request));
087        }
088
089        /**
090         * Acquires a threadsafe {@link RequestInterceptor} instance with sensible defaults.
091         * <p>
092         * The returned instance is guaranteed to be a JVM-wide singleton.
093         *
094         * @return a {@code RequestInterceptor} with default settings
095         */
096        @NonNull
097        static RequestInterceptor defaultInstance() {
098                return DefaultRequestInterceptor.defaultInstance();
099        }
100}