Add HTTP component API module (#10770)

feat(http): Add HTTP platform component API module

This module contains the API definition and test fixture for implementation modules.

feat(http): Disable API tests until a library is available

Co-authored-by: bruce.bujon <bruce.bujon@datadoghq.com>

Author: PerfectSlayer

components/http/http-api/build.gradle.kts

@@ -0,0 +1,35 @@
+plugins {
+  `java-library`
+  `java-test-fixtures`
+}
+
+apply(from = "$rootDir/gradle/java.gradle")
+
+description = "HTTP Client API"
+
+val minimumBranchCoverage by extra(0) // extra(0.7) -- need a library implementation
+val minimumInstructionCoverage by extra(0) // extra(0.7) -- need a library implementation
+
+// Exclude interfaces for test coverage
+val excludedClassesCoverage by extra(
+  listOf(
+    "datadog.http.client.HttpClient",
+    "datadog.http.client.HttpClient.Builder",
+    "datadog.http.client.HttpRequest",
+    "datadog.http.client.HttpRequest.Builder",
+    "datadog.http.client.HttpRequestBody",
+    "datadog.http.client.HttpRequestBody.MultipartBuilder",
+    "datadog.http.client.HttpRequestListener",
+    "datadog.http.client.HttpResponse",
+    "datadog.http.client.HttpUrl",
+    "datadog.http.client.HttpUrl.Builder",
+  )
+)
+
+dependencies {
+  // Add API implementations to test providers
+  // testRuntimeOnly(project(":components:http:http-lib-jdk"))
+  // testRuntimeOnly(project(":components:http:http-lib-okhttp"))
+  // Add MockServer for test fixtures
+  testFixturesImplementation("org.mock-server:mockserver-junit-jupiter-no-dependencies:5.14.0")
+}

components/http/http-api/src/main/java/datadog/http/client/HttpClient.java

@@ -0,0 +1,113 @@
+package datadog.http.client;
+
+import java.io.File;
+import java.io.IOException;
+import java.net.Proxy;
+import java.time.Duration;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executor;
+import javax.annotation.Nullable;
+
+/**
+ * This interface is an abstraction for HTTP clients, providing request execution capabilities. This
+ * abstraction is implementation-agnostic and can be backed by third party libraries of the JDK
+ * itself.
+ *
+ * <p>HttpClient instances should be reused across requests for connection pooling.
+ */
+public interface HttpClient {
+  /**
+   * Executes an HTTP request synchronously and returns the response. The caller is responsible for
+   * closing the response.
+   *
+   * @param request the request to execute
+   * @return the HTTP response
+   * @throws IOException if an I/O error occurs
+   */
+  HttpResponse execute(HttpRequest request) throws IOException;
+
+  /**
+   * Executes an HTTP request asynchronously and returns a {@link CompletableFuture}. The caller is
+   * responsible for closing the response.
+   *
+   * @param request the request to execute
+   * @return a CompletableFuture that completes with the HTTP response
+   */
+  CompletableFuture<HttpResponse> executeAsync(HttpRequest request);
+
+  /**
+   * Creates a new {@link Builder} for constructing HTTP clients.
+   *
+   * @return a new http client builder
+   */
+  static Builder newBuilder() {
+    return HttpProviders.newClientBuilder();
+  }
+
+  /** Builder for constructing {@link HttpClient} instances. */
+  interface Builder {
+    /**
+     * Sets the client timeouts, including the connection.
+     *
+     * @param timeout the timeout duration
+     * @return this builder
+     */
+    Builder connectTimeout(Duration timeout);
+
+    /**
+     * Sets the proxy configuration.
+     *
+     * @param proxy the proxy to use
+     * @return this builder
+     */
+    Builder proxy(Proxy proxy);
+
+    /**
+     * Sets proxy authentication credentials.
+     *
+     * @param username the proxy username
+     * @param password the proxy password, or {@code null} to use an empty password
+     * @return this builder
+     */
+    Builder proxyAuthenticator(String username, @Nullable String password);
+
+    /**
+     * Configures the client to use a Unix domain socket.
+     *
+     * @param socketFile the Unix domain socket file
+     * @return this builder
+     */
+    Builder unixDomainSocket(File socketFile);
+
+    /**
+     * Configures the client to use a named pipe (Windows).
+     *
+     * @param pipeName the named pipe name
+     * @return this builder
+     */
+    Builder namedPipe(String pipeName);
+
+    /**
+     * Forces clear text (HTTP) connections, disabling TLS.
+     *
+     * @param clearText {@code true} to force HTTP, {@code false} to allow HTTPS
+     * @return this builder
+     */
+    Builder clearText(boolean clearText);
+
+    /**
+     * Sets a custom executor for executing async requests.
+     *
+     * @param executor the executor to use for async requests
+     * @return this builder
+     */
+    Builder executor(Executor executor);
+
+    /**
+     * Builds the {@link HttpClient} with the configured settings.
+     *
+     * @return the constructed HttpClient
+     */
+    HttpClient build();
+  }
+}