001/*
002 * Copyright © 2025 CUI-OpenSource-Software (info@cuioss.de)
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 */
016package de.cuioss.http.client;
017
018import de.cuioss.http.client.retry.RetryStrategy;
019import de.cuioss.tools.net.http.HttpHandler;
020import lombok.NonNull;
021
022/**
023 * Unified provider interface for HTTP operations requiring both HttpHandler and RetryStrategy.
024 * <p>
025 * This interface establishes a consistent pattern for configuring HTTP operations with retry
026 * capabilities. Rather than passing HttpHandler and RetryStrategy as separate parameters,
027 * implementations provide both dependencies through a single provider interface.
028 * <h2>Design Benefits</h2>
029 * <ul>
030 *   <li><strong>Unified Constructor</strong>: {@code new ResilientHttpHandler(provider)}
031 *       instead of {@code new ResilientHttpHandler(handler, strategy)}</li>
032 *   <li><strong>Consistent Pattern</strong>: All HTTP configuration classes follow the same pattern</li>
033 *   <li><strong>Reduced Breaking Changes</strong>: Internal provider evolution without API changes</li>
034 *   <li><strong>Better Testability</strong>: Single interface to mock</li>
035 *   <li><strong>Future-Proof</strong>: Interface can evolve for HTTP-specific configuration needs</li>
036 * </ul>
037 * <h2>Implementation Pattern</h2>
038 * Configuration classes implement this interface by providing their HttpHandler and RetryStrategy:
039 * <pre>
040 * public class HttpJwksLoaderConfig implements HttpHandlerProvider {
041 *     &#64;Override
042 *     public HttpHandler getHttpHandler() { return httpHandler; }
043 *
044 *     &#64;Override
045 *     public RetryStrategy getRetryStrategy() { return retryStrategy; }
046 * }
047 * </pre>
048 * <h2>Consumer Pattern</h2>
049 * HTTP handler implementations consume this interface for unified dependency injection:
050 * <pre>
051 * public class ResilientHttpHandler {
052 *     public ResilientHttpHandler(HttpHandlerProvider provider) {
053 *         this.httpHandler = provider.getHttpHandler();
054 *         this.retryStrategy = provider.getRetryStrategy();
055 *     }
056 * }
057 * </pre>
058 *
059 * @author Oliver Wolff
060 * @since 1.0
061 */
062public interface HttpHandlerProvider {
063
064    /**
065     * Provides the HttpHandler for HTTP operations.
066     * <p>
067     * This HttpHandler is used by HTTP clients for making actual HTTP requests.
068     * The implementation must ensure that the returned HttpHandler is properly
069     * configured with appropriate timeouts, SSL settings, and other HTTP-specific parameters.
070     *
071     * @return the HttpHandler instance, never null
072     */
073    @NonNull
074    HttpHandler getHttpHandler();
075
076    /**
077     * Provides the RetryStrategy for HTTP operations.
078     * <p>
079     * This RetryStrategy defines how failed HTTP operations should be retried,
080     * including exponential backoff parameters, maximum attempts, and retry conditions.
081     * The implementation must ensure that the RetryStrategy is configured appropriately
082     * for the specific HTTP operation context.
083     *
084     * @return the RetryStrategy instance, never null
085     */
086    @NonNull
087    RetryStrategy getRetryStrategy();
088}