Refactor http, grpc senders and promote to public API

docs/apidiffs/current_vs_latest/opentelemetry-exporter-common.txt

@@ -1,2 +1,109 @@
 Comparing source compatibility of opentelemetry-exporter-common-1.59.0-SNAPSHOT.jar against opentelemetry-exporter-common-1.58.0.jar
-No changes.
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.Compressor  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.io.OutputStream compress(java.io.OutputStream)
+		+++  NEW EXCEPTION: java.io.IOException
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getEncoding()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcResponse  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) byte[] getResponseMessage()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcStatusCode getStatusCode()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getStatusDescription()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSender  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void send(io.opentelemetry.exporter.marshal.MessageWriter, java.util.function.Consumer<io.opentelemetry.exporter.grpc.GrpcResponse>, java.util.function.Consumer<java.lang.Throwable>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.CompletableResultCode shutdown()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSenderConfig  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.Compressor getCompressor()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.time.Duration getConnectTimeout()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.net.URI getEndpoint()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.concurrent.ExecutorService getExecutorService()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getFullMethodName()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.function.Supplier<java.util.Map<java.lang.String,java.util.List<java.lang.String>>> getHeadersSupplier()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.export.RetryPolicy getRetryPolicy()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.SSLContext getSslContext()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.time.Duration getTimeout()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.X509TrustManager getTrustManager()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSenderProvider  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.grpc.GrpcSender createSender(io.opentelemetry.exporter.grpc.GrpcSenderConfig)
++++  NEW ENUM: PUBLIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode  (compatible)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW INTERFACE: java.lang.constant.Constable
+	+++  NEW INTERFACE: java.lang.Comparable
+	+++  NEW INTERFACE: java.io.Serializable
+	+++  NEW SUPERCLASS: java.lang.Enum
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode RESOURCE_EXHAUSTED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode ALREADY_EXISTS
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNIMPLEMENTED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode FAILED_PRECONDITION
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode NOT_FOUND
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode DEADLINE_EXCEEDED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode OUT_OF_RANGE
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNAUTHENTICATED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode CANCELLED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode DATA_LOSS
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode INTERNAL
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNAVAILABLE
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode UNKNOWN
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode ABORTED
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode OK
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode INVALID_ARGUMENT
+	+++  NEW FIELD: PUBLIC(+) STATIC(+) FINAL(+) io.opentelemetry.exporter.grpc.GrpcStatusCode PERMISSION_DENIED
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.exporter.grpc.GrpcStatusCode fromValue(int)
+	+++  NEW METHOD: PUBLIC(+) int getValue()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.exporter.grpc.GrpcStatusCode valueOf(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.exporter.grpc.GrpcStatusCode[] values()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpResponse  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) byte[] getResponseBody()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) int getStatusCode()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getStatusMessage()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSender  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void send(io.opentelemetry.exporter.marshal.MessageWriter, java.util.function.Consumer<io.opentelemetry.exporter.http.HttpResponse>, java.util.function.Consumer<java.lang.Throwable>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.CompletableResultCode shutdown()
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSenderConfig  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.compressor.Compressor getCompressor()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.time.Duration getConnectTimeout()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String getContentType()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.net.URI getEndpoint()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.concurrent.ExecutorService getExecutorService()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.util.function.Supplier<java.util.Map<java.lang.String,java.util.List<java.lang.String>>> getHeadersSupplier()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.export.ProxyOptions getProxyOptions()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.common.export.RetryPolicy getRetryPolicy()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.SSLContext getSslContext()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.time.Duration getTimeout()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) javax.net.ssl.X509TrustManager getTrustManager()
+		+++  NEW ANNOTATION: javax.annotation.Nullable
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSenderProvider  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.http.HttpSender createSender(io.opentelemetry.exporter.http.HttpSenderConfig)
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.exporter.marshal.MessageWriter  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) int getContentLength()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) void writeMessage(java.io.OutputStream)
+		+++  NEW EXCEPTION: java.io.IOException

exporters/common/src/main/java/io/opentelemetry/exporter/internal/compression/Compressor.java → exporters/common/src/main/java/io/opentelemetry/exporter/compressor/Compressor.java

@@ -3,18 +3,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.exporter.internal.compression;
+package io.opentelemetry.exporter.compressor;
 
 import java.io.IOException;
 import java.io.OutputStream;
 import javax.annotation.concurrent.ThreadSafe;
 
 /**
- * An abstraction for compressing messages. Implementation MUST be thread safe as the same instance
- * is expected to be used many times and concurrently. Instances are usually singletons.
- *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
+ * A service provider interface (SPI) for compression. Implementation MUST be thread safe as the
+ * same instance is expected to be used many times and concurrently.
  */
 @ThreadSafe
 public interface Compressor {

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcResponse.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+import io.opentelemetry.exporter.marshal.MessageWriter;
+import java.util.function.Consumer;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * A gRPC response.
+ *
+ * @see GrpcSender#send(MessageWriter, Consumer, Consumer)
+ */
+@Immutable
+public interface GrpcResponse {
+
+  /** The response gRPC status code. */
+  GrpcStatusCode getStatusCode();
+
+  /** A string description of the status. */
+  @Nullable
+  String getStatusDescription();
+
+  /** The gRPC response message bytes. */
+  @SuppressWarnings("mutable")
+  byte[] getResponseMessage();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcSender.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+import io.opentelemetry.exporter.marshal.MessageWriter;
+import io.opentelemetry.sdk.common.CompletableResultCode;
+import java.util.function.Consumer;
+
+/**
+ * An abstraction for executing gRPC calls, allowing for implementations backed by different client
+ * libraries.
+ *
+ * <p>While this interface is public, implementing a custom sender is generally not recommended. The
+ * {@code opentelemetry-java} project provides built-in implementations that cover virtually all
+ * cases.
+ *
+ * @see GrpcSenderProvider
+ */
+public interface GrpcSender {
+
+  /**
+   * Execute a gRPC unary call, including any retry attempts. {@code onResponse} is called with the
+   * gRPC response, either a success response or an error response after retries. {@code onError} is
+   * called when the call could not be executed due to cancellation, connectivity problems, or
+   * timeout.
+   *
+   * @param messageWriter the message writer
+   * @param onResponse the callback to invoke with the gRPC response
+   * @param onError the callback to invoke when the gRPC call could not be executed
+   */
+  void send(
+      MessageWriter messageWriter, Consumer<GrpcResponse> onResponse, Consumer<Throwable> onError);
+
+  /** Shutdown the sender. */
+  CompletableResultCode shutdown();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcSenderConfig.java

@@ -0,0 +1,92 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+import io.opentelemetry.exporter.compressor.Compressor;
+import io.opentelemetry.exporter.marshal.MessageWriter;
+import io.opentelemetry.sdk.common.export.RetryPolicy;
+import java.io.OutputStream;
+import java.net.URI;
+import java.time.Duration;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ExecutorService;
+import java.util.function.Consumer;
+import java.util.function.Supplier;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.X509TrustManager;
+
+/**
+ * Configuration for {@link GrpcSender} implementations, provided via {@link
+ * GrpcSenderProvider#createSender(GrpcSenderConfig)}.
+ */
+@Immutable
+public interface GrpcSenderConfig {
+
+  /**
+   * The gRPC endpoint to send to, including scheme. Omits path, which must be obtained from {@link
+   * #getFullMethodName()}.
+   */
+  URI getEndpoint();
+
+  /**
+   * The fully qualified gRPC method name, e.g. {@code
+   * opentelemetry.proto.collector.trace.v1.TraceService/Export}.
+   */
+  String getFullMethodName();
+
+  /**
+   * The compressor, or {@code null} if no compression is used. If present, {@link
+   * Compressor#compress(OutputStream)} must be applied to {@link
+   * MessageWriter#writeMessage(OutputStream)} when {@link GrpcSender#send(MessageWriter, Consumer,
+   * Consumer)} is called and {@link Compressor#getEncoding()} must be set as the {@code
+   * grpc-encoding}.
+   */
+  @Nullable
+  Compressor getCompressor();
+
+  /**
+   * The max duration allowed to send a request, including resolving DNS, connecting, writing the
+   * request, reading the response, and any retries via {@link #getRetryPolicy()}.
+   */
+  Duration getTimeout();
+
+  /** The max duration allowed to connect to a target host. */
+  Duration getConnectTimeout();
+
+  /**
+   * Additional headers that must be appended to every request. The resulting {@link Supplier} must
+   * be invoked for each request.
+   */
+  Supplier<Map<String, List<String>>> getHeadersSupplier();
+
+  /** The retry policy, or {@code null} if retry is disabled. */
+  @Nullable
+  RetryPolicy getRetryPolicy();
+
+  /**
+   * The SSL context to use, or {@code null} if the system default is used. If non-null, {@link
+   * #getTrustManager()} will also be non-null.
+   */
+  @Nullable
+  SSLContext getSslContext();
+
+  /**
+   * The trust manager to use, or {@code null} if the system default is used. If non-null, {@link
+   * #getSslContext()} will also be non-null.
+   */
+  @Nullable
+  X509TrustManager getTrustManager();
+
+  /**
+   * The executor service used to execute any asynchronous processing, or {@code null} if the sender
+   * default executor service should be used.
+   */
+  @Nullable
+  ExecutorService getExecutorService();
+}

exporters/common/src/main/java/io/opentelemetry/exporter/internal/grpc/GrpcSenderProvider.java → exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcSenderProvider.java

@@ -3,19 +3,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-package io.opentelemetry.exporter.internal.grpc;
-
-import io.opentelemetry.exporter.internal.marshal.Marshaler;
+package io.opentelemetry.exporter.grpc;
 
 /**
  * A service provider interface (SPI) for providing {@link GrpcSender}s backed by different client
  * libraries.
- *
- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
  */
 public interface GrpcSenderProvider {
 
   /** Returns a {@link GrpcSender} configured with the provided config. */
-  <T extends Marshaler> GrpcSender<T> createSender(GrpcSenderConfig<T> grpcSenderConfig);
+  GrpcSender createSender(GrpcSenderConfig grpcSenderConfig);
 }

exporters/common/src/main/java/io/opentelemetry/exporter/grpc/GrpcStatusCode.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.exporter.grpc;
+
+/**
+ * gRPC status codes. See <a href="https://grpc.io/docs/guides/status-codes/">official grpc.io
+ * docs</a> for usage.
+ */
+public enum GrpcStatusCode {
+  OK(0),
+  CANCELLED(1),
+  UNKNOWN(2),
+  INVALID_ARGUMENT(3),
+  DEADLINE_EXCEEDED(4),
+  NOT_FOUND(5),
+  ALREADY_EXISTS(6),
+  PERMISSION_DENIED(7),
+  RESOURCE_EXHAUSTED(8),
+  FAILED_PRECONDITION(9),
+  ABORTED(10),
+  OUT_OF_RANGE(11),
+  UNIMPLEMENTED(12),
+  INTERNAL(13),
+  UNAVAILABLE(14),
+  DATA_LOSS(15),
+  UNAUTHENTICATED(16);
+
+  private final int value;
+
+  GrpcStatusCode(int value) {
+    this.value = value;
+  }
+
+  /** Returns the integer representation of the status code. */
+  public int getValue() {
+    return value;
+  }
+
+  /**
+   * Returns the {@link GrpcStatusCode} corresponding to the integer {@code value}, or {@link
+   * GrpcStatusCode#UNKNOWN} if the {@code value} is not recognized.
+   */
+  public static GrpcStatusCode fromValue(int value) {
+    GrpcStatusCode[] values = GrpcStatusCode.values();
+    if (value >= 0 && value < values.length) {
+      return values[value];
+    }
+    return UNKNOWN;
+  }
+}